# Migrate From gopkg.in/yaml.v2 to yaml.v3 in a Go Project

Yes. An agent moves a Go project from yaml.v2 to yaml.v3, rewrites MapSlice code as nodes, and shows which config values parse differently.

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

## What the agent does

The agent first finds how much of yaml.v2 the code really uses, because a project that only calls `yaml.Unmarshal` into structs migrates by changing one import and a project with custom unmarshalers does not. In a tool like pressly/sup, only `supfile.go` imports `gopkg.in/yaml.v2` (pinned at v2.2.8 in a `go.mod` that says `go 1.13`). That file has one `yaml.Unmarshal` call and four `UnmarshalYAML` methods. Three of them, on `Networks`, `Commands` and `Targets`, decode the same mapping twice: once into a Go map and once into a `yaml.MapSlice`, only to remember the order the keys were written in. The fourth, on `EnvList`, decodes into `[]yaml.MapItem` and turns every value into a string with `fmt.Sprintf("%v", v.Value)`.

The repository has no test files, so `go test ./...` prints `[no test files]` for all three packages and proves nothing. The agent writes a small probe test before it changes the import. The test parses `example/Supfile` and a second document made of awkward values, and prints the names in order and every environment variable. On yaml.v2 the example gives five networks in file order (`local`, `dev`, `stg`, `prod`, `k8s`), nineteen commands, and six variables. The awkward document shows what `%v` has been doing: `DEBUG: yes` becomes `DEBUG=true`, `MODE: 0755` becomes `MODE=493`, `RATIO: 1e3` becomes `RATIO=1000`, an empty value becomes the text `<nil>`, and a key written `ON` becomes a variable named `true`.

Changing the import to `gopkg.in/yaml.v3` produces exactly four compiler errors, three `undefined: yaml.MapSlice` and one `undefined: yaml.MapItem`, since v3 removed both types. The old method signature, `UnmarshalYAML(unmarshal func(interface{}) error)`, still compiles. That invites the wrong fix: declare a `yaml.Node`, pass it to the old `unmarshal` function, and walk its `Content`. It builds, it returns no error, and the node comes back empty, so the example file parses to zero networks, zero commands and no variables. The probe test catches that at once. The working port changes each method to v3's own signature, `UnmarshalYAML(node *yaml.Node) error`, calls `node.Decode` for the map, and reads keys and values from `node.Content` in pairs.

With that port the example file parses to the same output as before, line for line. The awkward document does not, and the agent reports each difference instead of hiding it. A node carries the text as written, so `yes` stays `yes`, `0755` stays `0755`, `1e3` stays `1e3` and an empty value becomes an empty string. An alias such as `B: *v` needs care: the node's `Value` is the anchor name, not the text it points to, so the port follows `node.Alias` or decodes the value node into a string. v3 also refuses a mapping with the same key twice when it decodes into a map (`mapping key "a" already defined at line 3`), where v2 accepted it and listed the command twice.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Migrate this Go module from gopkg.in/yaml.v2 to gopkg.in/yaml.v3. Read go.mod and every file that imports the package. List each use: Unmarshal, Marshal, Decoder and Encoder options, custom UnmarshalYAML and MarshalYAML methods, yaml.MapSlice, yaml.MapItem, and decoding into interface{} or map[interface{}]interface{}. Before changing anything, write a probe test that parses every example config in the repository plus one document with these values: yes, no, on, off, 0755, 1e3, an empty value, a quoted string, a duplicate key, an anchor with an alias, and a badly indented line. Run it on v2 and save the output. Then port: use the v3 signature UnmarshalYAML(node *yaml.Node) error for every custom unmarshaler, never pass a yaml.Node to the old unmarshal callback, and resolve aliases. Run the probe again and report every line that differs, saying for each whether a user's existing config file would now behave differently. Keep the probe as a real test with the v3 output as its expectation. Run go build, go vet, go test and go mod tidy. Do not change the go directive unless the build needs it. Open a pull request with both probe outputs in the description.",
  "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 edits `supfile.go`, `go.mod` and `go.sum`, and adds one test file where there were none. The parser gets shorter, since each ordered type decodes its map once and reads the key order from the same node. `go mod tidy` leaves the `go 1.13` line alone and records `gopkg.in/yaml.v3 v3.0.1`. The description shows the probe output on both versions and a short table of the values that changed.

That table is what the reviewer decides on. Passing `0755` through as text instead of the decimal 493 is almost certainly what the author of a deploy file meant. An empty variable no longer exporting the string `<nil>` reads as a bug fix. But they are changes to what reaches a remote shell, and a team with existing files should hear about them in the release notes. The duplicate key error is the other one: a file that used to load with a silently repeated command now stops with a line number.

The reviewer also sees one thing the port did not touch. A YAML syntax error is reported at a different line by the two parsers for the same broken file (line 4 on v2, line 2 on v3 for the probe's bad indent), so any documentation that quotes an error message needs the same update.

## Run it on every GitHub issue labelled yaml-v3

In an org with many Go services, open one tracking issue per repository and let the label start the work. Add an automation to each repository's Project with a `github` trigger on `issues.labeled`, set its `labels` filter to `yaml-v3`, and save the prompt above. Only a label added by an owner, member or collaborator of the repository fires it. The issue is placed after the prompt as event text, so the saved prompt remains the instruction and the issue can carry local notes, such as which example files matter most.

An automation has a cap of 1 to 30 runs per hour that you set. An event past the cap creates a `queued` run that starts when the hour has room, up to one more hour's worth of waiting runs; an event beyond that is refused. Label a large batch in groups no bigger than twice the cap.

## Why run it on Rush?

The risk in this migration is in data, not in code. Both versions compile, both parse the example file, and the difference appears only for a value like `0755` in somebody's real config. Finding that takes running the same documents through both parsers and reading two outputs side by side. The agent does that in its own sandbox with the commands recorded, so the claim "the example parses identically" in the pull request is backed by output a reviewer can open.

It also guards against the port that looks finished. The empty-node version of this change compiles cleanly, passes `go vet` and would pass review by diff alone in a repository with no tests. A run that is told to write the probe first cannot produce that pull request, because its own check fails on the first try.

## Frequently asked questions

### What replaces yaml.MapSlice in yaml.v3?

Nothing with the same name. v3 exposes the parsed document as `yaml.Node`, and a mapping node's `Content` holds its keys and values alternately, in file order. Code that used `MapSlice` to keep order reads the pairs from there.

### Why does my custom UnmarshalYAML return empty data after the upgrade?

Most likely it kept the v2 signature and decodes into a `yaml.Node` through the old `unmarshal` callback. That compiles in v3 and yields a node with no content, without an error. Switch the method to `UnmarshalYAML(node *yaml.Node) error` and use the node it is given.

### Is gopkg.in/yaml.v3 still maintained?

The go-yaml/yaml repository on GitHub is archived, and v3.0.1 is the last tag published at that import path. The YAML organization maintains a fork that publishes the same API as `go.yaml.in/yaml/v3`. Moving from v2 to v3 first is still the larger step, since the fork keeps v3's types; changing the import path afterwards is a search and replace the agent can do in the same run if you ask.

### Do yes and no still parse as booleans?

When the target is a Go `bool` field, yes. When the target is `interface{}` or a node, v3 keeps them as the strings that were written, where v2 produced `true` and `false`.

## More jobs like this: Upgrade dependencies weekly

- [Migrate From github.com/golang/protobuf to google.golang.org/protobuf](https://getrush.ai/run/migrate-golang-protobuf-to-google-protobuf/golang-protobuf/)
- [Replace Deprecated golint With revive, go vet and staticcheck in a Go Project](https://getrush.ai/run/migrate-golint-to-revive/golint/)
- [Migrate a Custom Environment From OpenAI Gym to Gymnasium](https://getrush.ai/run/migrate-gym-to-gymnasium/gym/)
- [Migrate From the Deprecated @hapi/joi Package to joi](https://getrush.ai/run/migrate-hapi-joi-to-joi/hapi-joi/)
- [Migrate an Express App From Jade to Pug](https://getrush.ai/run/migrate-jade-to-pug/jade/)
- [Migrate a Java Project From Joda-Time to java.time](https://getrush.ai/run/migrate-joda-time-to-java-time/joda-time/)

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