ci: auto-merge compatibility matrix PRs once CI is green

[petercrocker]

Why

The Infrahub release pipeline opens a docs: update compatibility matrix PR into stable on every release (most recently #1216). It contains nothing but a regenerated compatibility table, yet it sits waiting for someone to click merge.

Goal: those PRs merge themselves once CI is green.

Non-goals: this does not change how the PR is created — that workflow lives in opsmill/infrahub (.github/workflows/update-sdk-compatibility-docs.yml) and is untouched. No other PR is auto-merged.

What changed

• The compatibility matrix PR enables auto-merge (squash) on itself as soon as it opens, so it lands unattended once checks pass.
• CI now reports a single rollup result, ci-gate, alongside the existing per-job checks.

Implementation notes:

• ci-gate (.github/workflows/ci.yml) needs: every CI job, runs with if: always(), and fails only when a dependency reported failure or cancelled. Skipped jobs pass. This exists so branch protection can require CI with one context name: several jobs are conditional on files-changed (yaml-lint, action-lint and uv-lock-check were all skipped on docs: update compatibility matrix #1216), and unit-tests fans out over a Python matrix whose check names change whenever we add or drop a version.
• auto-merge-compatibility-docs.yml guards on all of: same-repo head, head ref automated/update-compatibility-docs, base stable, author opsmill-bot, and not a draft. It authenticates with GH_UPDATE_PACKAGE_OTTO rather than GITHUB_TOKEN because auto-merge merges as whoever enabled it, and opsmill-bot is the identity on stable's review-bypass list.

What stayed the same: no existing CI job was modified, and no other PR's merge behaviour changes until the branch-protection step below is applied.

Required follow-up — this PR does nothing on its own

stable currently has no required status checks. Without one, gh pr merge --auto finds no unmet requirement and merges immediately, ignoring CI. Making auto-merge actually wait requires registering ci-gate as a required check:

gh api -X PUT repos/opsmill/infrahub-sdk-python/branches/stable/protection \
  --input - <<'JSON'
{
  "required_status_checks": { "strict": false, "contexts": ["ci-gate"] },
  "enforce_admins": false,
  "required_pull_request_reviews": {
    "dismiss_stale_reviews": false,
    "require_code_owner_reviews": false,
    "require_last_push_approval": false,
    "required_approving_review_count": 1,
    "bypass_pull_request_allowances": { "users": ["opsmill-bot"], "teams": [], "apps": [] }
  },
  "restrictions": null,
  "required_linear_history": false,
  "allow_force_pushes": false,
  "allow_deletions": false,
  "block_creations": false,
  "required_conversation_resolution": false,
  "lock_branch": false,
  "allow_fork_syncing": false
}
JSON

That payload reproduces every current setting verbatim and adds only required_status_checks. Three things to get right:

1. Order. Merge this PR first. Applying the required check while PRs are open blocks each of them as "expected — waiting for status" until its head SHA produces a ci-gate result, which only happens once the job exists on the base branch.
2. develop needs ci-gate too. A PR's checks come from the head branch's workflow files, so a develop → stable release PR would run develop's ci.yml. If that lacks ci-gate, the release PR blocks forever. Port this change to develop (or merge stable into it) before enabling the required check.
3. strict: false is deliberate. With strict: true the bot PR stalls whenever stable moves ahead, because auto-merge does not update the branch for you.

How to review

Focus on the ci-gate needs: list — it must name every job in ci.yml, or a failure in an omitted job would not block the gate. Current list: prepare-environment, files-changed, yaml-lint, python-lint, markdown-lint, action-lint, uv-lock-check, documentation, validate-generated-documentation, validate-documentation-style, unit-tests, integration-tests-latest-infrahub.

Worth extra scrutiny: these PRs will merge without the sa team review the creating workflow requests. opsmill-bot bypasses the approval requirement on stable, so green CI is the only gate. That was a deliberate call for a docs-only change; say so if you'd rather keep a human in the loop, in which case the fix is to drop opsmill-bot from the bypass list.

How to test

uvx yamllint -s .github/workflows/ci.yml .github/workflows/auto-merge-compatibility-docs.yml
actionlint .github/workflows/ci.yml .github/workflows/auto-merge-compatibility-docs.yml

Both pass locally. End to end, the next release-triggered compatibility PR should show an enable-auto-merge run and an "auto-merge enabled" banner, then merge on its own when ci-gate goes green.

Impact & rollout

• Backward compatibility: no behaviour change until ci-gate is made a required check. The auto-merge workflow is inert for every PR that does not match all five guards.
• Config/env changes: consumes the existing GH_UPDATE_PACKAGE_OTTO secret; adds no new secret. Adds one short-lived runner job per CI run.
• Deployment notes: safe to merge. The branch-protection step is the coordinated part, and it makes CI mandatory for every PR into stable — nothing enforces that today.

---

Summary by cubic

Auto-merges the generated compatibility matrix PRs once CI is green by adding a ci-gate rollup check and a targeted auto-merge workflow. Other PRs are unchanged.

• New Features

  • Added ci-gate job that depends on all CI jobs and fails only on failure/cancelled (skips pass), giving one stable check for branch protection.
  • Added .github/workflows/auto-merge-compatibility-docs.yml to enable squash auto-merge for the docs PR only (same-repo, head automated/update-compatibility-docs, base stable, author opsmill-bot, not draft) using GH_UPDATE_PACKAGE_OTTO; re-evaluates on ready_for_review to handle draft-to-ready transitions.

• Migration

  • After this PR merges, set ci-gate as a required status check on stable (and ensure develop also includes ci-gate before release PRs); keep strict=false.
  • Update branch protection after this lands to avoid blocking existing PRs.

^{Written for commit 69c8a31. Summary will update on new commits.}

[cloudflare-workers-and-pages]

Deploying infrahub-sdk-python with    Cloudflare Pages

Latest commit:	69c8a31
Status:	✅  Deploy successful!
Preview URL:	https://dbeec316.infrahub-sdk-python.pages.dev
Branch Preview URL:	https://auto-merge-compat-matrix.infrahub-sdk-python.pages.dev

View logs

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@           Coverage Diff           @@
##           stable    #1217   +/-   ##
=======================================
  Coverage   82.47%   82.47%           
=======================================
  Files         138      138           
  Lines       12186    12186           
  Branches     1833     1833           
=======================================
  Hits        10051    10051           
  Misses       1572     1572           
  Partials      563      563           

Flag	Coverage Δ
integration-tests	40.56% <ø> (-0.01%)	⬇️
python-3.10	56.26% <ø> (ø)
python-3.11	56.27% <ø> (ø)
python-3.12	56.27% <ø> (ø)
python-3.13	56.26% <ø> (-0.02%)	⬇️
python-3.14	56.27% <ø> (ø)
python-filler-3.12	22.21% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cubic-dev-ai]

All reported issues were addressed across 2 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>