buf breaking "--against .git#branch=main" fetch-depth error in CI

By Kaveh Alemi·Latchkey

buf breaking needs the baseline ref (for example main) present in the local git history. The default checkout is shallow (fetch-depth 1), so --against .git#branch=main cannot find main and buf errors before it can compare.

What this error means

buf breaking fails with an error resolving the git reference, such as "could not resolve ref" or "revision main not found", when using --against '.git#branch=main' on a shallow checkout.

Failure: could not resolve reference "refs/heads/main": reference not found
Error: Process completed with exit code 1.

Common causes

The checkout is shallow

actions/checkout defaults to fetch-depth 1, so the main branch history buf breaking needs is not present locally.

The baseline branch was never fetched

On a pull request the base branch ref may not exist locally unless you fetch it explicitly.

How to fix it

Fetch full history in checkout

1. Set fetch-depth: 0 on actions/checkout so all refs are available.
2. Run buf breaking --against '.git#branch=main'.
3. The baseline now resolves and the comparison runs.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- run: buf breaking --against '.git#branch=main'

Compare against the BSR baseline instead

If you publish to the Buf Schema Registry, compare against the pushed module so no git history is needed.

buf breaking --against 'buf.build/acme/petapis'

How to prevent it

• Use fetch-depth: 0 whenever a step needs branch history.
• Prefer a BSR baseline for breaking checks in ephemeral runners.
• Fetch the base ref explicitly for pull-request comparisons.

Frequently asked questions

Related guides

References

• GitHub Actions documentation