helmfile "command not found" on the runner in CI

By Kaveh Alemi·Latchkey

The shell could not find a helmfile executable on PATH. GitHub-hosted runners do not ship helmfile, so a helmfile apply step fails with exit code 127 until you install the binary in an earlier step.

What this error means

A step running helmfile apply or helmfile sync fails with "helmfile: command not found" and "Process completed with exit code 127", even though helm may already be present.

/home/runner/work/_temp/script.sh: line 1: helmfile: command not found
Error: Process completed with exit code 127.

Common causes

helmfile is not preinstalled on hosted runners

GitHub-hosted images bundle kubectl and sometimes helm, but not helmfile. Without an install step the binary is absent.

The binary was installed to a directory not on PATH

A manual download extracted helmfile somewhere like the workspace root without adding it to PATH, so the shell cannot resolve it.

How to fix it

Install helmfile with a setup action

Use a dedicated action that also wires up helm and the helm-diff plugin that helmfile needs.

- uses: helmfile/helmfile-action@v2
  with:
    helmfile-args: apply

Download the release binary onto PATH

1. Fetch the helmfile release archive for linux-amd64.
2. Move the extracted binary into a directory already on PATH such as /usr/local/bin.
3. Run helmfile version to confirm it resolves before apply.

curl -fsSL -o helmfile.tgz \
  https://github.com/helmfile/helmfile/releases/download/v0.169.0/helmfile_0.169.0_linux_amd64.tar.gz
tar -xzf helmfile.tgz helmfile
sudo mv helmfile /usr/local/bin/
helmfile version

How to prevent it

• Install helmfile explicitly in CI; do not assume the runner has it.
• Install helm, kubectl, and the helm-diff plugin in the same setup step.
• Pin the helmfile version so the toolchain is reproducible across runs.

Frequently asked questions

Related guides

References

• Kubernetes documentation
• GitHub Actions documentation