All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

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

The same job on other stacks

More jobs like this: Upgrade dependencies weekly

Keep reading