# Upgrade Go Modules in an Echo App

Yes. Each week an agent upgrades your Echo app's Go modules in groups, replaces the archived JWT library, race-tests, runs govulncheck and opens one PR.

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

## What the agent does

In a service like xesina/golang-echo-realworld-example-app, `go.mod` declares `go 1.18` and eleven direct requirements: `github.com/labstack/echo/v4` v4.1.16, `github.com/labstack/gommon` at a 2021 pseudo-version, `github.com/jinzhu/gorm` v1.9.8, `github.com/dgrijalva/jwt-go` v3.2.0+incompatible, `golang.org/x/crypto` at a pseudo-version from April 2020, `gopkg.in/go-playground/validator.v9` v9.28.0, `github.com/swaggo/swag` v1.6.5, `github.com/swaggo/echo-swagger` v1.0.0, `github.com/gosimple/slug` v1.5.0, `github.com/stretchr/testify` v1.4.0 and `github.com/alecthomas/template`. `github.com/mattn/go-sqlite3` v1.10.0 is pulled in indirectly by the GORM SQLite dialect and is what the tests run on: `handler/handler_test.go` opens `realworld_test.db` through `db.TestDB()`, runs `AutoMigrate` and loads fixtures in `TestMain`. `.github/workflows/go.yml` sets up Go 1.18 and runs `go build -v ./...` and `go test -v ./...`; the `Makefile` builds and tests with `-race`. The `Dockerfile` builds on `golang:1.12.1`.

Three of those cannot be moved by `go get -u` alone, and the agent handles each explicitly. `github.com/dgrijalva/jwt-go` is archived, so the agent changes the import in `utils/jwt.go` and `router/middleware/jwt.go` to `github.com/golang-jwt/jwt/v5`, the maintained successor: `jwt.New(jwt.SigningMethodHS256)`, `jwt.MapClaims`, `jwt.Parse` with a key function and the `*jwt.SigningMethodHMAC` check all keep their names, so the diff is the import path and the `go.mod` line. `github.com/jinzhu/gorm` and `gopkg.in/go-playground/validator.v9` both have successors on new module paths, `gorm.io/gorm` and `github.com/go-playground/validator/v10`, that change the API; the weekly job moves them to the last release on their current paths, v1.9.16 and v9.31.0, and names the two rewrites in the pull request as separate work. The agent also notes that `labstack/echo` has a v5 on its own module path, which `go get -u` never selects, and leaves it there.

The rest goes up in groups so a failure is attributable. The framework group is `echo/v4` to v4.16.2 and `gommon`; the data group is `jinzhu/gorm` and `mattn/go-sqlite3`; the docs group is `swag` to v1.16.6 and `echo-swagger` to v1.5.2; the auth group is `golang-jwt/jwt/v5` and `golang.org/x/crypto`; the test group is `testify`. After each group it runs `go build ./...`, `go vet ./...` and `go test -race ./...`, and a group that breaks the build or a test is reverted and reported rather than patched around. Two consequences are expected and shown: `echo/v4` v4.16.2 carries a `go 1.26.0` directive, so the module's own `go` line rises and the `go` command fetches that toolchain under its default `GOTOOLCHAIN=auto`, which means `go.yml` and the `Dockerfile` base have to follow; and the `swag` upgrade means `docs/docs.go` was generated by an older CLI, so the agent installs `swag` at the matching version and reruns `swag init` so the generated file and the library agree, then starts the server and fetches `/swagger/index.html`.

Finally it runs `govulncheck ./...` before and after and pastes both reports, because the 2020 `golang.org/x/crypto` pseudo-version and the old `jwt-go` are exactly the kind of modules the tool flags; it runs `go mod tidy` and `go mod verify`, and it reports whether `go.sum` shrank or grew. The pull request lists every module with its old and new version, the groups in the order they were applied, which group a dropped upgrade belonged to and the failing output, and the three follow-ups it did not do: GORM v2, validator v10 and Echo v5.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Upgrade the Go modules in this Echo app. Read go.mod, go.sum, .github/workflows/go.yml, the Makefile, the Dockerfile, utils/jwt.go, router/middleware/jwt.go, db/db.go and handler/handler_test.go first. Run govulncheck ./... and keep the report. Replace the archived dgrijalva/jwt-go import with github.com/golang-jwt/jwt/v5 where the API is unchanged. Upgrade the remaining modules in groups: the Echo framework modules, the GORM and SQLite modules, the swag and echo-swagger modules, the crypto module, then testify, running go build, go vet and go test -race after each group and reverting a group that fails with its output in the pull request. Stay on each module's current major path and list the successors on new paths as follow-ups. If the Go directive rises, update the CI Go version and the Dockerfile base to match. Regenerate the swag docs with the matching CLI and check /swagger/index.html serves. Run go mod tidy, go mod verify and govulncheck again, and open one pull request with every version change and both vulnerability reports.",
  "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 changes `go.mod`, `go.sum`, `utils/jwt.go`, `router/middleware/jwt.go`, `docs/docs.go`, `docs/swagger.json`, `docs/swagger.yaml`, `.github/workflows/go.yml` and the `Dockerfile`. Its description is a table of every module with the version before and after, the group it was upgraded in, and the build and test result after that group, followed by the two `govulncheck` reports and the `go test -race` output for the final tree.

A reviewer sees the JWT import change as the only source edit, the regenerated Swagger files as a separate commit, and the Go version bump in CI and the image base in one more, so each can be judged on its own. The `Go` workflow runs on the pull request with the new Go version and shows the suite passing against the fresh `realworld_test.db` the tests create.

Before merging, a reviewer decides whether to take the three follow-ups the pull request names, and whether the next weekly run should be allowed to move the `go` directive on its own or hold it. The handlers, stores and models are unchanged.

## Run it on every Monday morning

Echo, GORM and the `swaggo` tools each release on their own schedule, and `golang.org/x/crypto` moves often. A weekly job that sends this request from any scheduler you already run picks each change up while it is one line. Point it at the repository in `resources` and send a `request_id` that is a UUID v5 of the repository's full name and the ISO week, so a scheduler that fires twice returns the run it already started instead of opening a second pull request. The key's `webhook_url` reports each run the key starts with the pull request in `result`, and a `run.failed` names a week where nothing could be upgraded cleanly.

Between runs, an automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request adds a requirement to go.mod, run govulncheck and say whether the new module or its version has a known advisory" keeps new dependencies to the same standard. The trigger adds the pull request after the prompt, and only work by an owner, member or collaborator fires it.

## Why run it on Rush?

Upgrading a Go module tree that has sat for years is not one command: an archived library needs an import rewrite, a framework upgrade drags the toolchain with it, a generated file stops matching its library, and a vulnerability scanner is the only honest measure of whether anything improved. The agent does each of those in its own sandbox with the race detector on, and the pull request carries the output of every step rather than a summary.

The group-by-group build and test results, the two `govulncheck` reports and the toolchain download all stay with the run. A team with several Go services on Echo gets one pull request per repository every week, each produced in its own sandbox, each with its own evidence.

## Frequently asked questions

### Why not move to Echo v5, GORM v2 or validator v10?

Because each lives on a new module path with API changes, and `go get -u` never crosses a major version. The weekly job upgrades within the paths the code imports, which keeps the diff reviewable, and lists the three rewrites as follow-ups with the files each one touches. Ask for one of them by name and the agent does that migration as its own pull request.

### What changes in the JWT code?

Only the import path. `github.com/golang-jwt/jwt/v5` is the maintained continuation of `dgrijalva/jwt-go`, and the calls this app makes, `jwt.New`, `jwt.MapClaims`, `jwt.Parse` with a key function and the `SigningMethodHMAC` type check, exist under the same names. The handler tests sign and verify tokens through `utils.GenerateJWT`, so they cover the change.

### Why does the pull request change the Go version?

Because the current `echo/v4` release declares a `go 1.26.0` directive, so `go get` raises the module's own `go` line to match and the `go` command downloads that toolchain under `GOTOOLCHAIN=auto`. CI pinned to 1.18 and a `golang:1.12.1` image base would then fail to build, so both move with it, and the pull request shows the line in `go.yml` and the `FROM` in the `Dockerfile`.

### What if a group breaks the tests?

The agent reverts that group, keeps the others, and pastes the failing build or test output under that group's heading in the pull request, so the next run or a person can pick it up with the error in front of them. A group is small enough that the cause is in one or two modules.

### Does the swag upgrade change the API docs?

The spec content comes from the same annotations in `main.go` and the handlers, so `swagger.json` describes the same routes; what changes is the generated `docs/docs.go`, which newer `swag` versions emit in a different shape, and some formatting in the YAML. The agent regenerates with the CLI version that matches the library and checks `/swagger/index.html` still loads.

## More Echo jobs

- [Write Unit Tests for an Echo API](https://getrush.ai/run/write-unit-tests/echo/)
- [Add Response Compression to an Echo App](https://getrush.ai/run/add-compression/echo/)
- [Add Test Coverage to CI for an Echo API](https://getrush.ai/run/add-coverage-to-ci/echo/)

## The same job on other stacks

- [Upgrade Go Modules in a Go CLI](https://getrush.ai/run/upgrade-go-modules/go-cli/)
- [Upgrade Go Modules Weekly for a Cobra CLI](https://getrush.ai/run/upgrade-go-modules/cobra/)

## More jobs like this: Upgrade dependencies weekly

- [Upgrade Gradle Dependencies Weekly for a Spring Boot App](https://getrush.ai/run/upgrade-gradle-dependencies/gradle/)

## 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/)
