Skip to main content
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).

Before you begin

1

Pick the target

Check the current pin:
terminal
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:
terminal
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:
terminal
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:
terminal
Output (trimmed)
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

terminal
Output (trimmed)
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

terminal
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:
terminal
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

Printed before the pin moves. Ignore its advice to run the pinned Forge: the upgrade must run as the newer binary.
Everything mechanical is applied. Fix each listed item, then run forge project upgrade again to confirm it converges.

Next steps

Gate pull requests on lint and tests

Run the gate on every upgrade PR

Lint rule rollout

How new lint rules warn before they gate after an upgrade

Generated and yours

Which files upgrade refreshes and which it leaves to you

How forge generate works

What the regenerate step at the end of an upgrade does