What the agent does
The shortcut most guides describe no longer exists. Older Go releases copied requirements out of Gopkg.lock when you ran go mod init; since Go 1.22 the command does not read other tools' files. In a library like antchfx/antch, which has Gopkg.toml, Gopkg.lock and no go.mod, go mod init github.com/antchfx/antch on Go 1.25 writes a two-line file, the module path and the go directive, and prints a hint to run go mod tidy. So the agent does the conversion by hand, and starts by reading what dep recorded.
It compares three lists: the constraints in Gopkg.toml, the projects in Gopkg.lock, and the imports in the code. In antch they disagree. Gopkg.toml constrains github.com/sirupsen/logrus to 1.0.3, but no Go file imports it and the lock has no entry for it. json.go imports github.com/antchfx/jsonquery, which appears in neither dep file, so the lock was already stale. Seven of the eight constraints are branch = "master", which means the only record of what was tested is the revision in the lock, for example 496ad84c8a0c for htmlquery and 3673e40ba225 for golang.org/x/net.
A bare go mod tidy ignores those revisions and takes the newest release of everything. The agent tries it in a scratch copy to show the size of that jump: htmlquery v1.3.7, xmlquery v1.5.2, robotstxt v1.1.2, and golang.org/x/net and golang.org/x/text at releases whose own go.mod says go 1.26.0, which raises this module's go directive to 1.26.0 and makes an older toolchain download a newer one. That is an upgrade of every dependency hidden inside a tooling change. The agent instead runs go get <module>@<revision> for each lock entry, which writes pseudo-versions such as v0.0.0-20180726134113-496ad84c8a0c, and then go mod tidy to add what the lock lacked. It reports the one place the pin cannot hold: jsonquery has no locked revision, its current release requires a newer xpath, and Go's minimal version selection raises xpath above the revision in the lock.
Then it proves the result. go build ./..., go vet ./... and go test ./... run before the dep files are deleted. In antch one test fails, TestRobotstxtHandler, with invalid port in the message: the test joins the server address and the path account with no slash between them. It fails the same way with the pinned versions and with the newest ones, so the agent reports it as a defect in the test that predates the conversion and leaves the fix for a separate change. Last, it deletes Gopkg.toml and Gopkg.lock, and rewrites .travis.yml, which pins Go 1.8 and 1.9 and downloads dep v0.3.2 to run dep ensure. Neither of those Go releases understands modules.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Convert this Go project from dep to Go modules. Do not assume go mod init imports Gopkg.lock: check what the installed Go version does and say so. Read Gopkg.toml, Gopkg.lock and the imports in every Go file, and list where they disagree: constraints nothing imports, imports with no lock entry, and constraints that follow a branch. Use the import path the code and CI already use as the module path. Pin each project in Gopkg.lock to its locked revision with go get module@revision, then run go mod tidy, and show the resulting go.mod. For any module that ends up at a different version than the lock, explain which requirement raised it. Separately, in a scratch copy, run go mod tidy with no pins and report which versions and which go directive it would have chosen, so the reviewer can see the difference; do not commit that result. If a vendor directory is committed, say whether CI builds from it and either regenerate it with go mod vendor or remove it, matching what CI does. Run go build, go vet and go test on every package, and for each failure say whether it also fails with the unpinned versions. Do not fix failing tests in this change; report them. Delete Gopkg.toml and Gopkg.lock, replace dep commands in CI files, the Makefile and the README with their go equivalents, and raise any Go version in CI that predates modules. Open a pull request.",
"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
A pull request that adds go.mod and go.sum, removes Gopkg.toml and Gopkg.lock, and updates the CI file. Its description has a table with one row per dependency: the constraint dep had, the revision dep locked, the version now in go.mod, and a note where they differ. For antch that table has seven rows from the lock plus jsonquery, and a line saying the logrus constraint was dropped because nothing imports it. Below it sit the versions an unpinned go mod tidy would have picked, labelled as not applied.
The reviewer checks three things. First, the module path: it must be the path other code already imports, because a different one breaks every importer. Second, any row where the version moved, since that is a real dependency change riding along. Third, the test section, which separates failures caused by the conversion from failures that were there before. Upgrading the pinned 2018 revisions is a sensible next step, and it belongs in its own pull request where a failing test points at one cause.
Run it on every repository that still has a Gopkg.toml
Organisations that adopted dep usually adopted it everywhere, so the same conversion is waiting in many repositories. List them with a code search for the filename Gopkg.toml, then send this body once per repository with that repository as the resources URL. Add a request_id, a fresh UUID you store beside the repository name, so a script that is interrupted and started again returns the runs it already created instead of opening second pull requests.
A key runs at most max_concurrent runs at once, 4 unless you changed it, within the plan limit of the member who created it. Requests past that are still accepted: each answers 202 with status: "queued" and starts when a slot frees, oldest first, so the script needs no retry loop. Give the key a webhook_url and each finished run posts run.completed with its execution_id; read the session then for the pull request it opened.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
The risk in this job is a silent change of versions, and the only way to see it is to resolve the module graph for real. The run has its own sandbox with a Go toolchain and network access to the module proxy, so go get at seven old revisions, go mod tidy, and a second resolve with no pins all run, and their output is kept in the session transcript. A reviewer who doubts a row in the table can find the command that produced it.
It also keeps the conversion honest about what it did not do. A project that last built with Go 1.9 is being compiled by a toolchain many releases newer, and failures from that gap would otherwise be blamed on modules. Running the tests against both dependency sets separates the two, which is tedious to do by hand and is exactly the sort of comparison that gets skipped.
Frequently asked questions
Doesn't go mod init convert Gopkg.lock automatically?
It used to. Since Go 1.22, go mod init no longer imports requirements from other dependency tools' files, so on a current toolchain you get a go.mod with only the module path and the go line. The locked revisions have to be carried over explicitly with go get module@revision.
Why not just run go mod tidy and take the latest versions?
Because that upgrades every dependency at once, across however many years the project sat on dep. If a test then fails you cannot tell whether the conversion or one of the upgrades caused it. Pinning first gives you a build equal to the old one, and upgrades can follow one at a time.
What happens to the vendor directory?
The agent checks whether one is committed and whether CI builds from it. If so, it regenerates it with go mod vendor so it matches go.mod; if not, it removes it. A project like antch commits no vendor directory, so there is nothing to do there.
What do [[override]] and [prune] in Gopkg.toml become?
An [[override]] that forces a transitive version becomes a direct require at that version, or a replace directive when it pointed at a fork through source. [prune] has no equivalent and needs none: the module cache is shared and go mod vendor already copies only the packages the build uses.
Will the pseudo-versions in go.mod cause problems?
No. A pseudo-version such as v0.0.0-20180724234803-3673e40ba225 names one commit by its time and hash, and is how modules refer to a commit that has no tag. They are verified through go.sum like any release, and they disappear as each dependency is later upgraded to a tagged version.
More jobs like this: Upgrade dependencies weekly
- Migrate From drf-yasg to drf-spectacular in Django REST Framework (drf-yasg)
- Migrate From faker to @faker-js/faker in a Node.js Project (Faker)
- Migrate From Flask-Cache to Flask-Caching (Flask-Cache)
- Migrate From Flask-JWT to Flask-JWT-Extended (Flask-JWT)
- Migrate From Flask-RESTPlus to Flask-RESTX (Flask-RESTPlus)
- Migrate From Flask-Script to the Flask CLI (Flask-Script)