About infrahub-planning-upgrades
Infrahub Upgrade Path Planner is an agent skill that creates `UPGRADE_PLAN.md` for moving an Infrahub deployment between versions within the same edition. It maps each minor-version hop, checks release changes against the repository and, when available, the live instance, and describes a plan without performing the upgrade.
Key features
- 01Plan sequential minor-version upgrade hops
- 02Review release notes including patch releases
- 03Inspect schemas, configuration and code
- 04Compare changes with a reachable instance
- 05Record findings and evidence in `UPGRADE_PLAN.md`
- 06Keep probes read-only; do not perform upgrades
Use cases
- 01Plan an Infrahub upgrade across several minor versions
- 02Check repository schemas and code for release impacts
- 03Assess upgrade changes against a reachable Infrahub instance
MCP support
When an Infrahub instance is reachable, the skill uses MCP read tools to inspect live data. It does not perform upgrades or write branches.
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/infrahub-planning-upgradesin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
reference.mdrules/_sections.mdimpact-verdict-needs-evidence.mdsafety-read-only-probes.mdsources-enumerate-every-hop.mdDetails
From the project READMEInfrahub Upgrade Path Planner
Overview
Produces UPGRADE_PLAN.md: the route from the running
Infrahub version to the target, one hop per minor
version, with every breaking change in that range
checked against this repository and, when reachable,
this instance.
The plan describes how to upgrade; it does not upgrade. It never runs the upgrade, a schema load, or a branch write, and it never hands the user the upgrade command. It may run and show read-only probes. The user's deployment method (Docker Compose, Helm, Enterprise, Community) decides the exact commands, and the upgrade guide for that deployment owns them.
Versions, not editions. The plan covers a move to a later version within one edition. Switching between Community and Enterprise, in either direction, is not a version upgrade and the release notes do not cover it. Say so and point at https://docs.infrahub.app/overview/community-vs-enterprise#migration-path instead of planning it. A request that does both plans the version upgrade only and names the edition change as out of scope.
Write is granted for UPGRADE_PLAN.md only. Bash is
granted for reading release notes with gh and for the
read-only probes.
Project Context
This skill runs in a forked context and has no view of
the parent conversation, so the user's request arrives
verbatim as the arguments: the versions, and everything
else the plan depends on, such as a pasted schema, the
deployment method (step 6 picks the upgrade guide from
it), the edition, and any pressure to "just run it".
For example:
/infrahub:planning-upgrades We run 1.9.2 on Docker Compose, Community, and want 1.10.0. Here is our schema: ...
With no target, ask for one. With no current version,
read it from infrahubctl info (Infrahub Version:),
and ask if the server is unreachable.
Workflow
- Fix the endpoints and the hops. Infrahub supports upgrades only from the previous minor version (N-1), so 1.6.3 to 1.9.0 is three hops: 1.6 to 1.7, 1.7 to 1.8, 1.8 to 1.9. Never plan a jump across minors, even when the user asks for "one go". Patches are different: one upgrade applies every pending migration in order, so 1.9.1 to 1.9.6 is a single hop, and a minor hop can start from any patch of the previous minor (1.9.1 to 1.10.0). Rolling up patches within the current minor first (1.10.8 to 1.10.10) is fine as its own section, not a requirement.
- Enumerate every release in the range, patches included, and read each one's notes. Read rules/sources-enumerate-every-hop.md before fetching anything: breaking changes ship in patch releases, and no machine-readable flag marks them.
- Inventory the repository. Schema YAML,
.infrahub.yml, GraphQL queries, and the Python checks, generators, and transforms. If an instance is reachable, confirm it withinfrahubctl info(connectivity-server-check) and read live data through the MCP read tools (mcp-tools). The instance is optional; the repository is not. - Give every finding a verdict and back it. Read
rules/impact-verdict-needs-evidence.md
before filling the
AffectedandEvidencecolumns. - Probe, read-only. Read rules/safety-read-only-probes.md before running or showing any command, and again if the user asks you to run the upgrade.
- Write
UPGRADE_PLAN.mdin the shape below. Each hop's steps are prose: take a backup, clear thebeforefindings, upgrade to the hop's target following the upgrade guide, clear theduringandafterfindings. Link the guide rather than transcribing it, picking the edition page when you know the edition:
Plan Format
One ## section per hop, in ascending order, with the
hop's two versions in the heading (## 1.9 -> 1.10).
Each hop carries one findings table with these nine
columns, in this order:
| Change | Release | Kind | Severity | When | Affected | Evidence | Action | Source |
|---|
| Column | Values |
|---|---|
Release | one version, X.Y.Z, never a range |
Kind | breaking or preparation |
Severity | critical, warning, or info |
When | before, during, or after the hop |
Affected | yes, no, or unknown |
What each value means, and a worked example, are in reference.md. Read it before writing the first row.
Rule Categories
| Category | Prefix | Rules |
|---|---|---|
| Sources | sources- | sources-enumerate-every-hop |
| Impact | impact- | impact-verdict-needs-evidence |
| Safety | safety- | safety-read-only-probes |
Supporting References
- reference.md: column semantics and an example plan. Read at step 6.
- rules/_sections.md: the rule index.