> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade Forge and apply its migration playbooks

> Move a project's pinned Forge version forward: preview the change with --check, list the migration playbooks, run project upgrade, and review the diff.

You will move the `shop` project to a newer Forge release in one command and review the result. `forge project upgrade` does every mechanical step for the range: Go modules, the codemods and playbook steps of each release you cross, the scaffolded files you have not edited, then generate and lint. What it cannot decide, it lists.

A project pins one Forge in `forge.yaml` (`forge_version`), and `reliant forge` hands each command to that version, so the pin moves only when you move it ([Forge CLI](https://docs.reliantlabs.io/cli/forge.md)).

## Before you begin

* A Forge project in git with a clean working tree, such as `shop` from [Add a database table with a CRUD API and pages](https://docs.reliantlabs.io/guides/forge/add-table-crud-api-pages.md).
* Go on your `PATH`. No account.

**1. Pick the target**

Check the current pin:

```bash terminal theme={null}
grep forge_version forge.yaml
```

```text theme={null}
forge_version: v1.6.1-0.20261115024114-0ab7c562e817
```

To move to the Forge inside `reliant` (`reliant forge --version`), use `reliant forge` in the steps below. To go past it, install the target release once and use that binary, written `forge` below:

```bash terminal theme={null}
(cd "$(mktemp -d)" && GOBIN="$HOME/.local/forge-v1.8.0" go install github.com/reliant-labs/forge/cmd/forge@v1.8.0)
export PATH="$HOME/.local/forge-v1.8.0:$PATH"
forge --version
```

```text theme={null}
forge version v1.8.0
```

`project upgrade` runs as the binary you call, not the pinned one. One run jumps at most two minor releases; a larger jump is refused with the version to stage through.

**2. List the migration playbooks**

A release whose change a diff cannot explain ships a migration playbook: steps for you or an agent. List the ones that match this project:

```bash terminal theme={null}
forge project upgrade list
```

```text theme={null}
Project is up to date.
```

No playbook applies between this pin and v1.8.0. When one does, it is listed by release ID; read it with `forge agent skill load migrations/<id>`.

**3. Preview the upgrade**

`--check` writes nothing. It names each file that differs, grouped by what adopting it costs:

```bash terminal theme={null}
forge project upgrade --check --to v1.8.0
```

```text Output (trimmed) theme={null}
forge project upgrade --check (dry run): v1.6.1-0.20261115024114-0ab7c562e817 (dev build) → v1.8.0

  go.mod: v1.6.1-0.20261115024114-0ab7c562e817 → v1.8.0
  gen/go.mod: v1.6.1-0.20261115024114-0ab7c562e817 → v1.8.0
  forge.yaml: v1.6.1-0.20261115024114-0ab7c562e817 (dev build) → v1.8.0
  3 with local edits (skipped), 15 up to date

  Your lines and the template's (merge by hand):
    internal/metrics/metrics.go       4 behind, 37 yours
    pkg/middleware/middleware.go      5 behind, 38 yours
    cmd/shop/cmd/commands.go          4 behind, 59 yours

Files you own, whose forge templates have moved on:
  2 cheap adopt(s), 15 merge(s), 2 absent here
```

Files you have not edited update on their own; a file you edited is reported and kept. `--check <path>` prints one file's diff.

**4. Run the upgrade**

```bash terminal theme={null}
forge project upgrade --to v1.8.0
```

```text Output (trimmed) theme={null}
Forge module requirements synchronized to v1.8.0.
forge_version → v1.8.0 (forge.yaml updated)
🔁 regenerating
✅ Code generation complete — 64 file(s) written, 12 changed (1 new, 11 updated).
   1 of them changed outside forge's writers: frontends/web/pnpm-lock.yaml
Converged: every mechanical fix applied and nothing is left for a person.
```

With `--json` it prints one document a pin bot can branch on: exit `0` converged, `9` needs a person (`needs_human` names each item and its fix), `1` failed, `2` retryable.

**5. Review the diff**

```bash terminal theme={null}
git status --short
```

```text theme={null}
 M forge.yaml
 M go.mod
 M go.sum
 M gen/go.mod
 M gen/go.sum
 M frontends/web/package.json
 M frontends/web/pnpm-lock.yaml
 M frontends/web/src/components/nav.tsx
 M internal/handlers/catalog/helpers_gen_test.go
?? frontends/web/src/lib/auth/route-access_gen.ts
 ...
```

Merge the files `--check` listed as yours by hand, or adopt one wholesale with `forge project upgrade --force <path>`. `forge project disown <path> --reason "..."` claims a file for good, and upgrade never touches it again.

**6. Verify and record**

`reliant forge` now hands every command to v1.8.0, building it once:

```bash terminal theme={null}
go build ./... && reliant forge lint --quiet
```

```text theme={null}
forge: building forge v1.8.0 (one time; cached in ...)
✅ All 29 gating linters passed.
```

Run `task test`, then commit the upgrade as one change. If a playbook was listed, finish its steps and record it with `forge project upgrade apply <id>` so `upgrade list` stops showing it.

## What this does not do

* **No silent overwrites.** A file you edited is replaced only when you name it after `--force`.
* **No downgrade.** To return to the old Forge, revert the upgrade commit.

## Troubleshooting

> [accordion] this forge is v1.8.0, but forge.yaml pins forge\_version ... — a different forge than the project's
>
> Printed before the pin moves. Ignore its advice to run the pinned Forge: the upgrade must run as the newer binary.

> [accordion] Exit 9: Still needs a person
>
> Everything mechanical is applied. Fix each listed item, then run `forge project upgrade` again to confirm it converges.

## Next steps

> [card] [Gate pull requests on lint and tests](https://docs.reliantlabs.io/guides/forge/gate-prs-forge-lint-tests.md)
>
> Run the gate on every upgrade PR

> [card] [Lint rule rollout](https://docs.reliantlabs.io/forge/linting/rollout.md)
>
> How new lint rules warn before they gate after an upgrade

> [card] [Generated and yours](https://docs.reliantlabs.io/forge/concepts/generated-vs-yours.md)
>
> Which files upgrade refreshes and which it leaves to you

> [card] [How forge generate works](https://docs.reliantlabs.io/deep-dives/how-forge-generate-works.md)
>
> What the regenerate step at the end of an upgrade does


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.