buf "buf: command not found" in CI

By Kaveh Alemi·Latchkey

The shell could not find a buf executable. GitHub-hosted runners do not include the Buf CLI, so buf lint, buf build, and buf generate fail until an earlier step installs it.

What this error means

A step running buf lint or buf generate fails with "buf: command not found" and the job exits 127.

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

Common causes

The Buf CLI is not installed on the runner

Hosted images do not ship buf, so any buf command fails until a setup step installs it.

buf-setup-action was skipped or ran in another job

The setup action only affects the job it runs in; a buf command in a different job without its own setup finds nothing on PATH.

How to fix it

Install buf with the official setup action

1. Add bufbuild/buf-setup-action before any buf step.
2. Pin the buf version for reproducibility.
3. Confirm with buf --version.

- uses: bufbuild/buf-setup-action@v1
  with:
    version: '1.34.0'
- run: buf --version

Add setup to every job that uses buf

Because setup is per-job, repeat the setup step (or a composite action) in each job that calls buf.

How to prevent it

• Pin the buf version in buf-setup-action so behavior is reproducible.
• Add buf setup to each job that runs a buf command.
• Verify with buf --version early so a missing CLI fails fast.

Frequently asked questions

Related guides

References

• GitHub Actions documentation