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

[lancamat1]

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 repositories and a staged promotion workflow. Includes a concepts page and a step-by-step guide that adds a Tag color attribute and promotes it from dev to prod.

• New Features
  • Added docs/docs/git-integration/multi-environment.mdx (concepts): branch-per-environment via ref; what moves via .infrahub.yml; read-only repos import only on action (no polling); staged promotion via Infrahub branches and proposed changes; explicit schema retirement with state: absent; rehearse production on a pre-prod from backup; avoid importing directly on main.
  • Added docs/docs/git-integration/promote-between-environments.mdx (how-to): register per-instance read-only repos (CoreReadOnlyRepositoryCreate); develop on an Infrahub branch by pointing ref to a Git feature branch (CoreReadOnlyRepositoryUpdate auto-imports); merge to develop, then bring the merged result onto main via a proposed change; mirror flow to promote develop → main on production; includes a production verify step; optional CI that polls CoreProposedChange.validations using X-INFRAHUB-KEY.
  • Updated docs/sidebars.ts with “Multiple environments” and “Promote between environments” under Git Integration.

^{Written for commit 2bdff2e. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed

Confidence score: 5/5

• Safe to merge after the addressed issues were fixed.

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic</sub>