What the agent does
Coverage in Go is a flag on go test, so the work is in choosing which packages count and where the numbers go. In an API laid out like xesina/golang-echo-realworld-example-app, go.mod declares go 1.18 and depends on github.com/labstack/echo/v4 v4.1.16, github.com/jinzhu/gorm v1.9.8 with its SQLite dialect, github.com/dgrijalva/jwt-go, github.com/swaggo/echo-swagger and github.com/stretchr/testify v1.4.0. .github/workflows/go.yml is the one workflow: on every push and pull request it checks out with actions/checkout@v3, installs Go 1.18 with actions/setup-go@v3, runs go build -v ./... and go test -v ./..., and that is all. The Makefile has a test target that runs go test -v -race ./..., which CI does not use, and build runs go build -race.
The agent then reads where the tests are. Every _test.go file is in handler/: handler_test.go has a TestMain whose setup() opens the SQLite file ./../realworld_test.db through db.TestDB(), runs db.AutoMigrate, builds the stores, a Handler and a router.New() Echo instance, and loads two users, two articles and comments as fixtures; tearDown() closes the database and db.DropTestDB() removes the file. user_test.go covers sign-up, login, the current user, profile and follow cases, and article_test.go covers list, get, create, update, feed, delete, comments, favourites and tags, each built with httptest.NewRequest and e.NewContext. The packages store, router, utils, db, model and main have no tests of their own, so a plain go test -cover would report a number for handler and nothing for the rest, and the whole-project figure would be flattering. Because mattn/go-sqlite3 needs cgo, the tests only build where a C compiler is present, which the Ubuntu runner has.
The workflow change is one step and three additions. The test step becomes go test -v -race -covermode=atomic -coverpkg=./... -coverprofile=coverage.out ./...: -coverpkg=./... counts statements in every package, including the ones only reached through the handler tests, so store and utils show real numbers instead of being absent; atomic is the mode -race requires. A following step runs go tool cover -func=coverage.out so the per-function table and the total: line land in the job log and in the step summary through GITHUB_STEP_SUMMARY, a third runs go tool cover -html=coverage.out -o coverage.html and uploads it with actions/upload-artifact so a reviewer can open the coloured source, and a fourth uploads coverage.out with codecov/codecov-action pinned to its current major, with fail_ci_if_error left off so a Codecov outage does not fail the build. Which of the last two the team keeps is a review choice; the pull request explains both. The agent raises actions/checkout and actions/setup-go to their current majors in the same file, since the old ones warn on every run, and leaves the Go version alone.
To show what the first run will report, the agent installs Go in its sandbox, runs the exact test command from the new workflow, and runs go tool cover -func=coverage.out on the result. It pastes the table into the pull request grouped by package, so the reader sees that handler is well exercised, that store is reached only through those handlers, and that router/middleware/jwt.go has branches no test touches, such as the invalid-token and missing-header paths. It writes no new tests; the table is the map for where they belong, and the pull request lists the three functions with the lowest coverage as suggested next targets. coverage.out and coverage.html are added to .gitignore beside the *.db pattern already there.
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 CI for this Echo API. Read go.mod, Makefile, .github/workflows/go.yml, handler/handler_test.go, handler/user_test.go, handler/article_test.go, db/db.go and .gitignore first. Change the test step in go.yml to run go test -v -race -covermode=atomic -coverpkg=./... -coverprofile=coverage.out ./..., add a step that runs go tool cover -func=coverage.out and writes the table to the step summary, a step that renders coverage.html and uploads it as an artifact, and a step that uploads coverage.out with codecov/codecov-action pinned to its current major without failing the build on an upload error. Raise actions/checkout and actions/setup-go to their current majors and keep Go 1.18. Add coverage.out and coverage.html to .gitignore. Install Go in the sandbox, run the new test command and go tool cover -func, and open a pull request that pastes the per-package table, names the three least covered functions, and writes no new tests.",
"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
The pull request changes .github/workflows/go.yml and .gitignore and nothing else. Its description pastes the go tool cover -func table from the sandbox grouped by package with the total: line, lists the three functions with the lowest coverage and the file each is in, and says which upload step to keep if the team does not use Codecov.
The Go workflow runs on the pull request itself, so the first coverage table appears in that run's step summary and coverage.html is attached as an artifact; if the repository has a Codecov token or is public, the Codecov comment appears on the pull request too. The run's record on Rush keeps the sandbox test output, so a reviewer can check the table in the description against what the workflow produced.
Before merging, a reviewer decides whether -race belongs in CI given it doubles test time, whether to add a coverage threshold later, and whether the Codecov step should stay. The tests, the handlers and the SQLite fixture setup are untouched.
Run it on every Go repository whose CI runs tests without coverage
An organisation with many Go services starts one run per repository from its own server: one POST /o/{org}/sessions each, with 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 reads its own workflow, so a service that already writes a profile gets -coverpkg and the summary step added, and one with a build matrix gets the upload steps on one leg only.
A team that wants the table in front of every change runs the follow-up as an automation in the Project with a github trigger on pull_request.opened. The trigger adds the pull request after the prompt, and the run reads the workflow's coverage artifact for that branch and the one for the base branch, and comments with the functions whose coverage dropped, so the number in the summary becomes a sentence a reviewer reads.
The use case this job follows, with its automation and trigger: Write the missing tests.
Why run it on Rush?
The flags are easy to get subtly wrong: without -coverpkg=./... a package with no test file is simply absent from the total, -race without -covermode=atomic fails, and go tool cover -func on a profile from a different working directory prints paths that match nothing. The agent runs the exact command the workflow will run, in its own sandbox with Go installed and a C compiler for SQLite, and the pull request carries the table that command produced.
Every command stays with the run, from go test to the HTML render, so a reviewer sees the numbers before the first workflow run. The same prompt runs across a fleet of Go services at once, each in its own sandbox and with its own pull request, which is how a coverage baseline for twenty repositories gets written in an afternoon.
Frequently asked questions
Why -coverpkg=./... instead of plain -cover?
Plain -cover measures each package only by its own tests, and this repository's tests all live in handler/, so store, utils and router would report nothing. With -coverpkg=./... every package's statements are instrumented, so code reached through the handler tests counts and the total reflects the whole module.
Does the test database need any setup in CI?
No. db.TestDB() opens a SQLite file next to the repository root and TestMain removes it after the suite. The runner needs a C compiler for mattn/go-sqlite3, which ubuntu-latest has, and -race needs cgo as well, which is on by default there.
Will the pull request add tests for the uncovered functions?
Not this one. It adds the measurement and names the three least covered functions so the next pull request has a target. Keeping the workflow change separate from new tests makes each easy to review and to revert.
Do I need a Codecov account?
No. The go tool cover -func table in the step summary and the uploaded coverage.html work with GitHub alone. The Codecov step is there for a team that wants a trend and a pull request comment; a public repository uploads without a token, a private one needs CODECOV_TOKEN as a secret, and either way an upload error does not fail the build.