# Migrate a Go Project From dep (Gopkg.toml) to Go Modules

Yes. An agent turns Gopkg.toml and Gopkg.lock into go.mod and go.sum, keeps the locked revisions, proves the build and opens a pull request.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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

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.

## 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](https://getrush.ai/run/migrate-drf-yasg-to-drf-spectacular/drf-yasg/)
- [Migrate From faker to @faker-js/faker in a Node.js Project](https://getrush.ai/run/migrate-faker-to-faker-js/faker/)
- [Migrate From Flask-Cache to Flask-Caching](https://getrush.ai/run/migrate-flask-cache-to-flask-caching/flask-cache/)
- [Migrate From Flask-JWT to Flask-JWT-Extended](https://getrush.ai/run/migrate-flask-jwt-to-flask-jwt-extended/flask-jwt/)
- [Migrate From Flask-RESTPlus to Flask-RESTX](https://getrush.ai/run/migrate-flask-restplus-to-flask-restx/flask-restplus/)
- [Migrate From Flask-Script to the Flask CLI](https://getrush.ai/run/migrate-flask-script-to-flask-cli/flask-script/)

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