What the agent does
The agent reads how the tests run before it measures them, because in a Go CLI the Makefile and the workflow often disagree. In a project like spf13/cobra-cli, go.mod declares module github.com/spf13/cobra-cli with go 1.15, cobra v1.6.1 and viper v1.12.0. The code is main.go, the cmd package with root.go, init.go, add.go, project.go, helpers.go and eight licence files, and the tpl package holding the templates the generator writes. The tests are all in cmd: add_test.go, init_test.go, project_test.go, helpers_test.go and golden_test.go, which compares generated files against cmd/testdata/*.golden. Makefile runs richgo test -v ./... under test after go get -v ./..., and build cross-compiles with gox. .github/workflows/test.yml has three jobs: golangci-lint, test-unix across ubuntu and macOS on Go 1.14 to 1.17 running make test build, and test-win under MSYS2. No job passes -cover, nothing writes a profile, and no coverage service or artifact exists. .github/dependabot.yml already watches gomod and github-actions weekly.
Measuring comes first, in the sandbox, so the floor in the workflow is a number the agent read rather than guessed. It runs go test -race -covermode=atomic -coverprofile=coverage.out ./..., with atomic because -race requires it, then go tool cover -func=coverage.out, which prints one line per function with its percentage and a final total: line, and go tool cover -html=coverage.out -o coverage.html for the browsable report. The main package has only main.go and no test, so it shows as uncovered in the per-package list; the agent notes in the pull request which packages and functions cover -func reports at 0.0%, since that list is the to-do list a coverage floor implies. The floor goes a few points under the total it measured, so the job fails on a real drop and not on noise.
The workflow change is one new job, coverage, added to test.yml beside the existing three so nothing about the matrix, the lint job or the Windows job changes. It runs on ubuntu-latest with actions/checkout and actions/setup-go at their current major releases, v7 for both as of the day the agent checks, and go-version: stable, because a coverage number only needs one toolchain. The steps are the same go test command, go tool cover -func written to the job summary through $GITHUB_STEP_SUMMARY so the total appears on the run page, a shell step that reads the total: line and exits non-zero below COVERAGE_MIN, an env variable at the top of the job where it is easy to raise, and actions/upload-artifact, v7 as of that day, with coverage.out and coverage.html and a short retention. The agent pins each action by its release commit SHA with the version in a comment, as the repository's Dependabot config can keep updated.
Two small changes outside the workflow make the number reproducible locally: a cover target in Makefile that runs the same two commands without richgo, and coverage.out and coverage.html in .gitignore. The agent does not add Codecov or another upload service, because that needs a token in the repository's secrets and a person's account; the pull request names codecov/codecov-action and the CODECOV_TOKEN secret as the step to add if the team wants history and pull request comments. Before opening the pull request it runs actionlint on test.yml, runs the new make cover target, and runs make test once more to show the existing target still passes.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add test coverage reporting to this Go CLI's CI. Read go.mod, Makefile, .github/workflows/test.yml, .github/dependabot.yml, .gitignore and every *_test.go file first. In the sandbox run go test -race -covermode=atomic -coverprofile=coverage.out ./... and go tool cover -func=coverage.out, and record the total and the functions at 0.0%. Add a coverage job to the existing workflow, without changing the other jobs, that checks out the code with the current major of actions/checkout and actions/setup-go pinned by commit SHA with the version in a comment, runs the same go test command, writes the go tool cover -func output to the job summary, fails when the total is below a COVERAGE_MIN env variable set a few points under the measured total, and uploads coverage.out and an HTML report with the current major of actions/upload-artifact. Add a cover target to the Makefile and ignore the coverage files in .gitignore. Do not add a coverage service that needs a token; name it as an option in the pull request. Run actionlint, make cover and make test, and open a pull request that pastes the per-function summary.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that changes .github/workflows/test.yml, Makefile and .gitignore. The description pastes the go tool cover -func output from the sandbox with its total: line, states the COVERAGE_MIN it chose and why, lists the functions reported at 0.0% by package, and shows the actionlint result.
The run's record holds the coverage run with -race, the HTML report generation and the make test run, so a reviewer can see the exact total the floor was derived from and that the existing target is untouched.
Before merging, a reviewer decides whether the floor should be lower during a period of new work, whether the job should also run on the Windows path where the golden tests touch line endings, and whether to add Codecov for trend lines. Once merged, the coverage job's summary on each pull request shows the total, and the artifact holds the report for anyone who wants the per-line view.
Run it on every Go module without a coverage number
A team with several Go CLIs or services starts one run per repository with POST /o/{org}/sessions, this prompt and the repository in resources, and a request_id that is a UUID v5 of the repository's full name so a retried call returns the run already started. Each run measures that repository's own total and sets its own floor, so a module with thin tests gets a low floor and a to-do list rather than a red check on day one, and each run opens its own pull request.
The key's webhook_url receives run.completed for each run with a session_url, so a script can collect the pull request links and the measured totals across the repositories as the runs finish.
The use case this job follows, with its automation and trigger: Write the missing tests.
Why run it on Rush?
A coverage floor that nobody measured first is either useless or a blocker: set too low it never fires, set too high it fails the first pull request and gets deleted. The agent runs the profile in its own sandbox, reads the total and the uncovered functions, and derives the floor from them, so the number in the workflow has a provenance a reviewer can check in the run's record.
Running it on Rush also keeps the change honest about scope. The existing jobs, matrix and Makefile targets stay as they are, the new job is additive, and the pull request names the upload service as an option rather than wiring a secret the team has not agreed to. Several repositories can get the same treatment at once, one run and one pull request each.
Frequently asked questions
Why a floor in the workflow instead of Codecov?
A floor needs nothing but go tool cover and a shell step, so it works on the first pull request with no token, no account and no third party reading the repository. Codecov and similar services add history, per-file deltas and pull request comments, but need a CODECOV_TOKEN secret and someone to own the account. The pull request adds the floor now and names the service as the next step.
Why -covermode=atomic?
Because the existing Makefile runs the tests with -race, and Go's race detector requires the atomic coverage mode; the default set mode fails with it. Keeping -race in the coverage job means the coverage run is also a race run, so the job does double duty.
Do the golden-file tests count toward coverage?
Yes. go test -coverprofile records every statement executed in the packages under test, however the test drives them, so the generator code exercised by golden_test.go through its testdata comparisons is covered like code reached by a direct unit test. Code that only runs in main.go is not, because main has no test, and the summary says so.
Why not fail on any decrease instead of a fixed floor?
Comparing against the previous run needs somewhere to store the previous total, which is what a coverage service or a cache step provides. A fixed COVERAGE_MIN is a single number in the workflow that anyone can raise in the same pull request that adds tests, and it needs no state. The pull request notes how to move to a delta check later.
More Cobra jobs
The same job on other stacks
- Add Test Coverage to CI for a Django REST Framework API (Django REST Framework)
- Add Code Coverage to CI for a .NET Solution (.NET)
- Add Test Coverage to CI for an Echo API (Echo)