update-router-version

name	update-router-version
description	Update this flake to a new Apollo Router release. Bumps the `router-src` flake input, pins the matching upstream Rust version from `rust-toolchain.toml`, refreshes `cargoHash`, runs `nix flake update`, verifies the build, then commits and tags. Takes one argument: the target router version (with or without leading `v`).
allowed-tools	Bash, Read, Edit, WebFetch

Update Apollo Router Version

A one-shot upgrade procedure for flake.nix. Run it when the user says something like "update to v2.13.0" or invokes /update-router-version 2.13.0.

Inputs

• $ARG — the target version, e.g. 2.13.0 or v2.13.0. Normalize to two forms and use them throughout:
  • VERSION — without leading v (used in commit/tag messages and logs)
  • TAG — with leading v (used for the upstream tag, the router-src URL, and the git tag created here)

If no argument was given, stop and ask the user which version to upgrade to.

Preflight

1. Confirm the working tree is clean: git status --porcelain. If dirty, stop and ask the user how to proceed — do not stash or discard.
2. Read the current inputs.router-src.url from flake.nix. If the tag in the URL already matches TAG, stop and tell the user.
3. Confirm the upstream tag exists by fetching rust-toolchain.toml (next step). A 404 means the tag is wrong.

Step 1 — Determine the upstream Rust version

Fetch https://raw.githubusercontent.com/apollographql/router/${TAG}/rust-toolchain.toml and read the channel field under [toolchain]. That value is RUST_VERSION (e.g. 1.91.1).

If the file is missing or the channel field can't be parsed, stop — the upstream tag is invalid or the toolchain layout has changed.

Step 2 — Edit flake.nix

Make these exact replacements with the Edit tool:

1. url = "github:apollographql/router/v<old>"; → url = "github:apollographql/router/${TAG}";
2. rustVersion = "<old>"; → rustVersion = "${RUST_VERSION}"; (skip if unchanged)
3. cargoHash = "sha256-..."; → cargoHash = lib.fakeHash;

lib is already in scope inside the with pkgs; block — no extra import needed. The source narHash is not edited here; it lives in flake.lock and is managed by the next step.

Step 3 — Refresh flake inputs

nix flake update

This re-resolves router-src against the new tag (writing the correct narHash into flake.lock) and bumps nixpkgs and rust-overlay so the new RUST_VERSION is available in the overlay. If the overlay doesn't yet have the requested Rust version (rare, only on same-day Rust releases), report and stop.

Step 4 — Resolve cargoHash

nix build 2>&1 | tee /tmp/router-flake-build.log

Expect failure with a hash mismatch on the vendored Cargo deps. Extract the new hash from the log:

awk '/got:/ {print $2; exit}' /tmp/router-flake-build.log

Edit flake.nix: replace cargoHash = lib.fakeHash; with cargoHash = "<got-hash>";.

If the failure is not a hash mismatch (e.g. compilation error, missing buildInput on a new platform), stop and surface the error to the user — do not paper over it.

Step 5 — Verify

nix build
nix flake check

Both must succeed before committing. The CI workflow runs nix flake check on tag push, so this is the same gate.

Step 6 — Commit and tag

Match the existing repo convention (see commit 87facf3 "Update to v2.12.1"):

git add flake.nix flake.lock
git commit -m "Update to ${TAG}"
git tag ${TAG}

Use dangerouslyDisableSandbox: true for the commit (GPG signing). Do not push — confirm with the user first; the CD workflow triggers on tag push and will publish to Cachix.

Reporting back

After tagging, summarize in one or two lines:

• old version → new version
• Rust version (note if it changed)
• the tag created locally
• a reminder that git push --follow-tags will trigger the release build

Failure modes worth handling explicitly

Symptom	Cause	Action
404 on rust-toolchain.toml	Tag doesn't exist upstream	Stop; ask user to verify the version
nix flake update fails on router-src	Tag doesn't exist, or input URL is malformed	Stop; re-check the URL
nix build fails with compiler error	Upstream raised MSRV without updating toolchain file, or new dep needs a system lib	Stop; report; do not commit
Same cargoHash error twice in a row	Edit didn't land — re-read flake.nix to confirm before re-running
nix flake check fails after nix build succeeds	Often a formatting/eval issue introduced by edits	Run nix fmt and re-check