ci: add branch protection readiness check #233

Merged

pdurlej merged 1 commit from codex/auto-deploy/pm-safety-activation into main

2026-05-12 08:06:40 +02:00

codex commented

2026-05-12 07:39:13 +02:00

Collaborator

Canary status: missing — Full/security-sensitive CI guardrail review before merge

Canary Context Pack

Product story

Piotr is a non-technical PM/operator. A Forgejo Merge button must not silently merge into a stacked branch or require Piotr to inspect Git internals. ADR-0017 already added the policy; this PR makes the branch-protection state checkable and gives Piotr a short setup/runbook.

What changed

Added control-plane/platformctl/ci/check_branch_protection.py to report whether main requires base-is-main / guard.
Added runbooks/pm-safe-merge.md with the one-time Forgejo branch protection setup and PM merge rule.
Documented the readiness check in docs/ci/README.md.
Tightened .forgejo/workflows/merged-in-main-audit.yml by setting persist-credentials:false and fully qualifying Forgejo actions.
Added tests for ready/not-ready branch-protection states.

Why it changed

The current live Forgejo branch payload reports protected=true and required_approvals=1, but enable_status_check=false. That means ADR-0017 is merged but not yet mechanically enforced for Piotr.

Files touched

.forgejo/workflows/merged-in-main-audit.yml
control-plane/platformctl/ci/check_branch_protection.py
control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py
docs/ci/README.md
runbooks/pm-safe-merge.md

Relevant context

ADR-0017 no stacked PRs to main
ADR-0007 security-sensitive/full review discipline
Forgejo branch API live state for main

Runtime evidence

No production mutation. Live read-only check result:

Ready: false
Protected: true
Required status checks enabled: false
Required context present: false
Required action: enable required status checks for base-is-main / guard.

Known constraints

This PR cannot enable Forgejo branch protection itself with codex permissions. Operator/admin must do the one-time toggle after merge.

Explicit out-of-scope

Auto-deploy workflow activation
Deploy runner registration
Compose migration
Any SSH or RS2000 runtime mutation

Requested decision

Approve/merge if the checker and runbook are clear. Then operator enables the required status check in Forgejo settings.

Merge blockers

Checker prints or requires raw token values
Runbook asks Piotr to bypass failed checks
Workflow change weakens credential persistence or action pinning policy

Spec sources read

decisions/0017-no-stacked-prs-to-main.md — policy being activated
.forgejo/workflows/base-is-main.yml — required status context source
.forgejo/workflows/merged-in-main-audit.yml — fixed existing guardrail drift
.forgejo/ci-policy.yaml — workflow trust policy
docs/ci/README.md / docs/ci/runner-contract.md — CI/runbook conventions

Test plan

PYTHONPATH=control-plane pytest control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py -q → 15 passed
PYTHONPATH=control-plane python3 control-plane/platformctl/ci/lint_workflows.py --policy .forgejo/ci-policy.yaml --workflows .forgejo/workflows --json /tmp/workflow-lint.json --markdown /tmp/workflow-lint.md → 0 findings
Live read-only branch check with codex PAT in env, no token printed → Ready: false as expected until operator toggles branch protection

Refs #142

Canary status: missing — Full/security-sensitive CI guardrail review before merge ## Canary Context Pack ### Product story Piotr is a non-technical PM/operator. A Forgejo Merge button must not silently merge into a stacked branch or require Piotr to inspect Git internals. ADR-0017 already added the policy; this PR makes the branch-protection state checkable and gives Piotr a short setup/runbook. ### What changed - Added `control-plane/platformctl/ci/check_branch_protection.py` to report whether `main` requires `base-is-main / guard`. - Added `runbooks/pm-safe-merge.md` with the one-time Forgejo branch protection setup and PM merge rule. - Documented the readiness check in `docs/ci/README.md`. - Tightened `.forgejo/workflows/merged-in-main-audit.yml` by setting `persist-credentials:false` and fully qualifying Forgejo actions. - Added tests for ready/not-ready branch-protection states. ### Why it changed The current live Forgejo branch payload reports `protected=true` and `required_approvals=1`, but `enable_status_check=false`. That means ADR-0017 is merged but not yet mechanically enforced for Piotr. ### Files touched - `.forgejo/workflows/merged-in-main-audit.yml` - `control-plane/platformctl/ci/check_branch_protection.py` - `control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py` - `docs/ci/README.md` - `runbooks/pm-safe-merge.md` ### Relevant context - ADR-0017 no stacked PRs to main - ADR-0007 security-sensitive/full review discipline - Forgejo branch API live state for `main` ### Runtime evidence No production mutation. Live read-only check result: - `Ready: false` - `Protected: true` - `Required status checks enabled: false` - `Required context present: false` - Required action: enable required status checks for `base-is-main / guard`. ### Known constraints This PR cannot enable Forgejo branch protection itself with codex permissions. Operator/admin must do the one-time toggle after merge. ### Explicit out-of-scope - Auto-deploy workflow activation - Deploy runner registration - Compose migration - Any SSH or RS2000 runtime mutation ### Requested decision Approve/merge if the checker and runbook are clear. Then operator enables the required status check in Forgejo settings. ### Merge blockers - Checker prints or requires raw token values - Runbook asks Piotr to bypass failed checks - Workflow change weakens credential persistence or action pinning policy ## Spec sources read - `decisions/0017-no-stacked-prs-to-main.md` — policy being activated - `.forgejo/workflows/base-is-main.yml` — required status context source - `.forgejo/workflows/merged-in-main-audit.yml` — fixed existing guardrail drift - `.forgejo/ci-policy.yaml` — workflow trust policy - `docs/ci/README.md` / `docs/ci/runner-contract.md` — CI/runbook conventions ## Test plan - `PYTHONPATH=control-plane pytest control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py -q` → 15 passed - `PYTHONPATH=control-plane python3 control-plane/platformctl/ci/lint_workflows.py --policy .forgejo/ci-policy.yaml --workflows .forgejo/workflows --json /tmp/workflow-lint.json --markdown /tmp/workflow-lint.md` → 0 findings - Live read-only branch check with codex PAT in env, no token printed → `Ready: false` as expected until operator toggles branch protection Refs #142

codex added 1 commit

2026-05-12 07:39:13 +02:00

ci: add branch protection readiness check

canary-required / collect-diff (pull_request) Successful in 3s

Details

infra-docs-drift / docs-drift (pull_request) Successful in 3s

Details

pyfallow / Pyfallow gate (control-plane) (pull_request) Successful in 17s

Details

python-ci / Python 3.11 (pull_request) Successful in 45s

Details

python-ci / Python 3.12 (pull_request) Successful in 46s