docs(git-integration): multi-environment pattern and promotion guide
Merged
LA
4mo ago+326+326+012345678901234567890123456789-0-0-0123456789
What
Adds two spokes under Branches & Change Control → Git Integration documenting how to run separate development / staging / production Infrahub instances from a single Git repository, and how to promote changes between them.
docs/docs/git-integration/multi-environment.mdx— concept: the all-read-only, branch-per-environment model; what moves through Git (.infrahub.ymlcontent); Git-vs-Infrahub terminology; the staged promotion model (import into an Infrahub branch, review via a proposed change); and reaching production safely.docs/docs/git-integration/promote-between-environments.mdx— how-to: register a read-only repository per instance, author a change, the staged promotion flow, and an optional/experimental CI automation note.docs/sidebars.ts— two entries under Git Integration.
Key points of the documented model
- Every environment is a read-only consumer pinned to one long-lived Git branch via
ref; no instance uses a read-writeRepository, and nothing is pushed back to Git. - Read-only repositories never auto-import — imports are always triggered manually (UI) or via API.
- Promotion is staged: import into an Infrahub branch and merge via a proposed change; importing straight to
mainis a caveated side-note, not recommended. - The environment count is an example (dev/staging/prod) — 2 or 5 work identically.
- No clean rollback is claimed; safety comes from rehearsing on a pre-production instance restored from a current production backup.
For reviewers
- Placement under Git Integration is provisional — flag if this should be a top-level section instead.
- The "Automate the promotion" section is intentionally marked optional/experimental. A fully automated PC-merge gate is blocked by open behavior: a proposed-change merge currently carries a read-only repository's branch-aware
ref/commitonto the destination branch, which would repoint an instance'smain. That behavior is under review (internal ticket; relates to IFC-1361) — the docs deliberately keep production promotion manual until it's resolved. - Product framing (positioning / "who this is for") is expected to be iterated post-merge by product.
<repository-id>and host placeholders are intentional; the reader substitutes their own.
Verification
- Facts verified against backend source (mutation/type names,
refvsdefault_branch,CoreValidatorstate/conclusion,CoreProposedChange.validations,.infrahub.ymlimportable content). npm run buildpasses; all cross-links and anchors resolve; Vale/banned-qualifier scan clean.
🤖 Generated with Claude Code
Summary by cubic
Adds docs for running multiple Infrahub environments from one Git repo using read‑only repos and staged, branch-based promotion. Includes a single‑instance develop workflow, a cross‑environment promotion guide, diagrams, and sidebar links.
- New Features
- Added
docs/docs/git-integration/multi-environment.mdx(concepts): branch‑per‑environment viaref, read‑only imports (no polling), staged promotion on Infrahub branches (don’t import tomain), explicit schema retire (state: absent), production rehearsal; topology diagram. - Added
docs/docs/git-integration/develop-changes.mdx(how‑to): feature branch → test by settingrefon an Infrahub branch (auto‑import) → land onmainvia a proposed change; BuiltinTagcolorexample; faster iteration withinfrahubctl schema load. - Added
docs/docs/git-integration/promote-between-environments.mdx(how‑to): promotedevelop→mainwith per‑instance read‑only repos; validate on a throwaway Infrahub branch; optional CI gate viaCoreProposedChange.validations; develop/promote flow diagram. - Added diagrams:
docs/docs/media/multi-environment-topology.excalidraw.svg,docs/docs/media/develop-promote-flow.excalidraw.svg. - Updated
docs/sidebars.tswith “Develop changes,” “Multiple environments,” and “Promote between environments.”
- Added