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
- A Forge project in git with a clean working tree, such as
shopfrom Add a database table with a CRUD API and pages. - Go on your
PATH. No account.
1
Pick the target
Check the current pin:To move to the Forge inside
terminal
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:No playbook applies between this pin and v1.8.0. When one does, it is listed by release ID; read it with
terminal
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)
--check <path> prints one file’s diff.4
Run the upgrade
terminal
Output (trimmed)
--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
--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
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
this forge is v1.8.0, but forge.yaml pins forge_version ... — a different forge than the project's
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.
Exit 9: Still needs a person
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
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