docs(git-integration): multi-environment pattern and promotion guide

Merged
LA
4mo ago
+326-0

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.yml content); 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-write Repository, 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 main is 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/commit onto the destination branch, which would repoint an instance's main. 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, ref vs default_branch, CoreValidator state/conclusion, CoreProposedChange.validations, .infrahub.yml importable content).
  • npm run build passes; 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 via ref, read‑only imports (no polling), staged promotion on Infrahub branches (don’t import to main), explicit schema retire (state: absent), production rehearsal; topology diagram.
    • Added docs/docs/git-integration/develop-changes.mdx (how‑to): feature branch → test by setting ref on an Infrahub branch (auto‑import) → land on main via a proposed change; BuiltinTag color example; faster iteration with infrahubctl schema load.
    • Added docs/docs/git-integration/promote-between-environments.mdx (how‑to): promote develop → main with per‑instance read‑only repos; validate on a throwaway Infrahub branch; optional CI gate via CoreProposedChange.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.ts with “Develop changes,” “Multiple environments,” and “Promote between environments.”