Go "coverage: X% of statements" below gate script in CI

Go has no built-in coverage gate, so teams parse "coverage: X% of statements" from go test -cover and fail the build in a script. When measured coverage is below the minimum, that script exits non-zero.

What this error means

The job prints "coverage: 68.4% of statements" and the gate step fails with a message like "coverage 68.4% below required 80%", exiting non-zero.

ok      example.com/app/pkg    0.012s  coverage: 68.4% of statements
coverage 68.4% is below required 80%

Common causes

Measured coverage is below the gate minimum

New or untested packages lowered the aggregate percentage under the threshold the script enforces.

Coverage was computed over a narrow package set

Running go test without ./... or -coverpkg measures only the package under test, so the gate may not reflect the whole module.

How to fix it

Add tests, or compute coverage across the module

1. Generate a coverage profile across all packages.
2. Use go tool cover -func to see per-function gaps and the total.
3. Add tests for the lowest-covered functions until the total clears the gate.

go test -coverpkg=./... -coverprofile=cover.out ./...
go tool cover -func=cover.out | tail -1

Make the gate read the real total

Parse the total: line from go tool cover -func and compare it numerically so the gate reflects the whole module.

pct=$(go tool cover -func=cover.out | awk '/^total:/{print substr($3,1,length($3)-1)}')
awk -v p="$pct" -v min=80 'BEGIN{exit (p+0 < min)}' || \
  { echo "coverage $pct% is below required 80%"; exit 1; }

How to prevent it

• Compute coverage with -coverpkg=./... so the gate reflects the module.
• Use go tool cover -func to find low-coverage functions early.
• Raise the gate minimum gradually as coverage grows.

Related guides