# Add golangci-lint to an Echo API's CI

Yes. An agent adds a v2 golangci-lint config and a lint job to your Echo app's CI, runs the linter first and fixes or scopes what it reports, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-golangci-lint-to-ci/echo/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the module is built and tested before it adds a linter, because a lint job that disagrees with the build job about the Go version is the first thing that goes wrong. In an app laid out like xesina/golang-echo-realworld-example-app, `go.mod` declares module `github.com/xesina/golang-echo-realworld-example-app` with `go 1.18` and depends on `github.com/labstack/echo/v4` v4.1.16, `github.com/jinzhu/gorm` v1.9.8 with the SQLite dialect, `github.com/dgrijalva/jwt-go` v3.2.0, `github.com/stretchr/testify` v1.4.0, `github.com/swaggo/swag` v1.6.5 with `echo-swagger`, `gopkg.in/go-playground/validator.v9` and `github.com/gosimple/slug`. `.github/workflows/go.yml` is one `build` job on push and pull request: `actions/checkout@v3`, `actions/setup-go@v3` with `go-version: 1.18`, `go build -v ./...` and `go test -v ./...`. The `Makefile` builds and tests with `-race` and has `container` targets, the `Dockerfile` builds on `golang:1.12.1`, and `readme.md` still shows a Travis badge. There is no `.golangci.yml`, no `go vet` step and no formatter check.

Then it reads the code the linter will see. `router/router.go` creates the `echo.Echo` with `RemoveTrailingSlash`, `Logger` and a `CORS` config, and sets a `validator.v9` validator. `router/middleware/jwt.go` parses the `Token` scheme from the `Authorization` header with `jwt.Parse` and reads `claims["id"].(float64)` without checking the assertion. `handler/routes.go` registers the `users`, `user`, `profiles`, `articles` and `tags` groups with a `Skipper` that lets unauthenticated `GET`s through except on `/api/articles/feed`. `handler/request.go` binds and validates each request struct. `handler/handler_test.go` has a `TestMain` whose `setup()` calls `loadFixtures()` and drops the error it returns, and a `responseMap` helper that calls `json.Unmarshal` without reading its result, both of which `errcheck` reports; `utils/jwt.go` discards the `SignedString` error explicitly with `_`, which it does not. `docs/docs.go` is generated by `swag` with a `GENERATED BY THE COMMAND ABOVE; DO NOT EDIT` header that is not the standard `Code generated ... DO NOT EDIT.` line, so the linter would read it as hand-written unless it is excluded by path. `db/db.go` carries a `TODO: err check` on `AutoMigrate`, which returns a `*gorm.DB` rather than an error, so no linter flags it.

The agent writes `.golangci.yml` in the version 2 format: `version: "2"`, `linters.default: standard`, which is `errcheck`, `govet`, `ineffassign`, `staticcheck` and `unused`, `linters.exclusions.paths` with `docs/` so the generated Swagger package is skipped, and `formatters.enable` with `gofmt` and `goimports`, which in v2 are separate from linters. It installs golangci-lint 2.15.0, the current release, in its sandbox and runs `golangci-lint run ./...`. What it reports is handled one of three ways: a real defect is fixed, so `setup()` now fails the test binary with `log.Fatal` when `loadFixtures()` errors and `responseMap` returns the `Unmarshal` error to the caller; a finding the team should see but not now is listed in `linters.exclusions.rules` with a path and a comment; and a formatter diff is applied. The linter runs again until it reports nothing, then `go build ./...` and `go test ./...` confirm the fixes did not change behaviour. The SQLite driver needs a C compiler, which the sandbox has.

The workflow gets a second job, `lint`, beside `build` in `go.yml`: `actions/checkout`, `actions/setup-go` with `go-version: stable` and `cache: true`, and `golangci/golangci-lint-action` at its current `v9` with `version: v2.15`. The lint job installs a current Go rather than 1.18 because the golangci-lint binary is built with a recent toolchain and analyses a module whose `go` directive is 1.18 without complaint, while the `build` job keeps 1.18 until the maintainers raise it; the pull request says that the two jobs differ and why. The agent also runs `actionlint` over the edited workflow. It does not touch `go.mod`, the `Dockerfile` or the swag-generated package.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add golangci-lint to this Echo API's CI. Read go.mod, the Makefile, .github/workflows/go.yml, router/router.go, router/middleware/jwt.go, handler/routes.go, handler/handler_test.go, utils/jwt.go, db/db.go and the header of docs/docs.go first. Write .golangci.yml in the version 2 format with the standard linters, gofmt and goimports as formatters, and the swag-generated docs/ package excluded by path. Install golangci-lint v2.15 and run it over ./... here; fix every real defect it finds, such as unchecked errors in the test setup, and put any finding you leave for the maintainers in an exclusion rule with a comment saying why. Run it again until it is clean, then go build ./... and go test ./... to show nothing changed. Add a lint job to go.yml using actions/setup-go with a stable Go and golangci/golangci-lint-action v9 pinned to the same linter version, leave the build job on Go 1.18 and explain the difference in the pull request, and run actionlint on the workflow. Do not change go.mod, the Dockerfile or anything under docs/. Open a pull request with the first and last linter output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **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.
2. **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.
3. **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 adds `.golangci.yml`, changes `.github/workflows/go.yml` and the files the fixes touched, `handler/handler_test.go` among them. Its description shows the linter's first report and its clean final run, the `go test` output after the fixes, and a list of every exclusion rule with its reason.

On the pull request, the `Go` workflow runs both jobs: `build` on 1.18 as before and the new `lint` job, which installs the pinned linter through the action and reads the same `.golangci.yml`, so a finding that slipped past the sandbox shows up as an annotation on the changed line.

Before merging, a reviewer reads each exclusion rule and decides whether it should stay, whether the linter should run with `only-new-issues` so old code is not blocked at once, and whether the `build` job should move to the same Go the lint job uses now that `go.mod`'s 1.18 is several releases behind.

## Run it on every Go service without a linter

A team with several Go services starts one run per repository from its own server: a `POST /o/{org}/sessions` each, with this prompt as `input`, that 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. `GET /o/{org}/github` lists every repository the Rush GitHub App installation reaches, so the script can pick the ones with a `go.mod` and no `.golangci.yml`. Each run reads its own workflow, so a service already on a current Go gets one job edited rather than two, and one with a `Makefile` `lint` target gets the same command wired into it.

A team that files platform work as Linear issues runs the same prompt from an automation in the Project with a `linear` trigger on issues labelled `lint`. The trigger adds the issue after the prompt, so an issue that asks for a particular linter such as `gosec` to be enabled, or for a path to be excluded, reaches the agent with that request, and the pull request links back to it.

## Why run it on Rush?

Adding a linter is only half the job; the other half is reading what it says about years of code and deciding, finding by finding, what to fix and what to exclude. The agent does that in its own sandbox, where the linter, the C compiler the SQLite driver needs and the test suite all run, and every report and every decision stay with the run, so the pull request opens green rather than with a wall of annotations.

The same prompt runs across every Go service at once, each in its own sandbox with its own pull request, and each reads its own workflow and `go.mod` rather than receiving one template.

## Frequently asked questions

### Why the version 2 configuration format?

golangci-lint 2 reads a `version: "2"` file with `linters`, `formatters` and `exclusions` sections and rejects the old keys, and the current release, 2.15.0, is what the action installs when it is pinned to v2.15. A version 1 file would stop the job before any code was read.

### Will the first CI run fail on old code?

No. The agent runs the linter in its sandbox until it reports nothing, fixing defects and writing exclusion rules for the rest, so the lint job's first run on the pull request has nothing to say. From then on only new findings fail it, and `only-new-issues` on the action is the switch if the team prefers to see old findings as annotations without blocking.

### Does it change the Go version the app builds with?

No. `go.mod` stays at 1.18 and the `build` job keeps `go-version: 1.18`. Only the `lint` job installs a current Go, because the linter binary expects one; a module with an older `go` directive is analysed as that version. The pull request points out the gap so the maintainers can close it in their own time.

### What about the swag-generated docs package?

`docs/docs.go` is written by `swag` and should not be edited, but its header does not match the comment Go tools use to mark generated files, so the linter would report it. The configuration excludes the `docs/` path instead, which also keeps the job fast when the Swagger spec grows.

### Which findings does it fix rather than exclude?

Ones that hide a failure: a test setup that ignores the error from loading fixtures runs every test against an empty database and reports confusing failures, and a helper that ignores `json.Unmarshal` turns a malformed response into a nil map and a panic. Those are fixed in place. A stylistic finding in code the task did not come to change is excluded with a reason.

## More Echo jobs

- [Add Graceful Shutdown to an Echo App](https://getrush.ai/run/add-graceful-shutdown/echo/)
- [Add Health Checks to an Echo API](https://getrush.ai/run/add-health-checks/echo/)
- [Run an Echo App as a Non-Root User in Docker](https://getrush.ai/run/add-non-root-user/echo/)

## The same job on other stacks

- [Add golangci-lint to a Go CLI's CI](https://getrush.ai/run/add-golangci-lint-to-ci/go-cli/)

## More jobs like this: Hand off a long task

- [Add Google Benchmark to a CMake Project](https://getrush.ai/run/add-google-benchmark/cmake/)
- [Add Google Login to an Express and Mongoose API](https://getrush.ai/run/add-google-login/mongoose/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
