ci: prepare PM-safe platformctl auto deploy #234

Merged

pdurlej merged 2 commits from codex/auto-deploy/deploy-runner-boundary into main

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

codex commented

2026-05-12 07:43:07 +02:00

Collaborator

Canary status: missing — fire canary 3+3 manually before merge

Canary Context Pack

Product story

Piotr should move toward “review PR → click Merge → trusted pipeline plans, applies, checks health, and leaves evidence”, while still being protected from accidental production deploys, repo-secret shortcuts, and PR-head execution.

What changed

This PR adds the deploy-runner boundary and a PM-safe platformctl auto-deploy skeleton:

records deploy-host as the dedicated trusted production runner lane;
forbids production deploy credentials from Forgejo repo secrets;
adds .forgejo/workflows/platformctl-plan.yml for secret-free PR scope evidence;
adds .forgejo/workflows/platformctl-auto-apply.yml for post-merge trusted-main plan → apply → health evidence;
adds auto_apply_scope.py to allow only narrow v1 modules: rs2000, docker-compose, relative compose file, and no secret/provider-like diff lines;
adds find_merged_pr.py so auto-apply binds trusted main SHA back to a merged PR;
adds platformctl apply --remote-root and PLATFORMCTL_REMOTE_ROOT support.

Why it changed

Manual SSH/apply is still too much burden for a non-technical PM. Before a real auto-deploy can be trusted, the repo needs a hard runner/secret boundary and a narrow active workflow that fails closed when the runner is not ready.

Files touched

.forgejo/ci-policy.yaml
.forgejo/workflows/merged-in-main-audit.yml
.forgejo/workflows/platformctl-plan.yml
.forgejo/workflows/platformctl-auto-apply.yml
control-plane/platformctl/apply.py
control-plane/platformctl/cli.py
control-plane/platformctl/ci/auto_apply_scope.py
control-plane/platformctl/ci/find_merged_pr.py
control-plane/platformctl/tests/test_apply_phase3.py
control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py
control-plane/pyproject.toml
docs/ci/README.md
docs/ci/runner-contract.md
runbooks/forgejo-actions-runner.md

Relevant context

ADR-0017 merged in #220: PM-safe merge flow and main-landing protection.
Existing Phase 3 platformctl plan/apply/health chain.
AGENTS.md security-sensitive class of service.

Runtime evidence

No RS2000 runtime mutation. Local checks passed:

PYTHONPATH=control-plane pytest \
  control-plane/platformctl/tests/test_plan_phase3.py \
  control-plane/platformctl/tests/test_apply_phase3.py \
  control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py \
  control-plane/platformctl/tests/test_health_phase3.py \
  control-plane/platformctl/tests/test_smoke.py \
  -q
# 97 passed

PYTHONPATH=control-plane python3 control-plane/platformctl/ci/lint_workflows.py \
  --policy .forgejo/ci-policy.yaml \
  --workflows .forgejo/workflows \
  --json /tmp/workflow-lint-auto.json \
  --markdown /tmp/workflow-lint-auto.md
# 0 findings

git diff --check

Known constraints

The deploy runner must be registered/configured separately before the post-merge workflow can perform real work. The auto-apply job fails closed unless runner-local PLATFORMCTL_DEPLOY_READY=1 and local deploy capability are present.

Explicit out-of-scope

No RS2000 production mutation in this PR.
No Forgejo repo secrets for deploy.
No vps1000 auto-apply.
No absolute Agaria compose paths.
No canonical compose import/migration yet.
No arbitrary “run command with secrets” workflow.

Requested decision

Approve the dedicated deploy-runner boundary and narrow active workflow skeleton, then perform the one-time deploy runner setup before relying on auto-apply as the normal RS2000 change path.

Merge blockers

Any production deploy secret routed through Forgejo repo secrets.
Any PR-head deploy execution path.
Any broad shared runner replacing the dedicated deploy-host tier.
Any reviewer finding that the workflow can mutate production from untrusted PR code.

Operator Merge Checklist

Merge #233 first, or confirm its branch-protection readiness checker is already on main.
Do not create Forgejo repo secrets for production deploy: no SSH key, no Tailscale client secret, no Forgejo PAT/provider key.
Register/configure dedicated runner rs2000-deploy-host with label deploy-host before expecting auto-apply to work.
Set runner-local deploy readiness only after checks pass: PLATFORMCTL_DEPLOY_READY=1, local Forgejo apply token bridge, SSH/Tailscale capability, and PLATFORMCTL_REMOTE_ROOT=/opt/pdurlej-platform/current.
If the PR is not mergeable or auto-apply reports not_configured, do not guess; ask Codex/Claude for the next exact command.

Spec sources read

AGENTS.md — identity, Forgejo API, security-sensitive review class.
docs/ci/README.md — CI trust-tier documentation target.
docs/ci/runner-contract.md — runner contract target.
runbooks/forgejo-actions-runner.md — runner setup documentation target.
.forgejo/ci-policy.yaml — workflow policy source.
control-plane/platformctl/apply.py — apply remote-root and approval behavior.
control-plane/platformctl/cli.py — CLI flag surface.
control-plane/platformctl/tests/test_apply_phase3.py — apply tests.
control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py — contract tests.

Refs #142
Refs #220

Canary status: missing — fire canary 3+3 manually before merge ## Canary Context Pack ### Product story Piotr should move toward “review PR → click Merge → trusted pipeline plans, applies, checks health, and leaves evidence”, while still being protected from accidental production deploys, repo-secret shortcuts, and PR-head execution. ### What changed This PR adds the deploy-runner boundary and a PM-safe `platformctl` auto-deploy skeleton: - records `deploy-host` as the dedicated trusted production runner lane; - forbids production deploy credentials from Forgejo repo secrets; - adds `.forgejo/workflows/platformctl-plan.yml` for secret-free PR scope evidence; - adds `.forgejo/workflows/platformctl-auto-apply.yml` for post-merge trusted-main plan → apply → health evidence; - adds `auto_apply_scope.py` to allow only narrow v1 modules: `rs2000`, `docker-compose`, relative compose file, and no secret/provider-like diff lines; - adds `find_merged_pr.py` so auto-apply binds trusted main SHA back to a merged PR; - adds `platformctl apply --remote-root` and `PLATFORMCTL_REMOTE_ROOT` support. ### Why it changed Manual SSH/apply is still too much burden for a non-technical PM. Before a real auto-deploy can be trusted, the repo needs a hard runner/secret boundary and a narrow active workflow that fails closed when the runner is not ready. ### Files touched - `.forgejo/ci-policy.yaml` - `.forgejo/workflows/merged-in-main-audit.yml` - `.forgejo/workflows/platformctl-plan.yml` - `.forgejo/workflows/platformctl-auto-apply.yml` - `control-plane/platformctl/apply.py` - `control-plane/platformctl/cli.py` - `control-plane/platformctl/ci/auto_apply_scope.py` - `control-plane/platformctl/ci/find_merged_pr.py` - `control-plane/platformctl/tests/test_apply_phase3.py` - `control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py` - `control-plane/pyproject.toml` - `docs/ci/README.md` - `docs/ci/runner-contract.md` - `runbooks/forgejo-actions-runner.md` ### Relevant context - ADR-0017 merged in #220: PM-safe merge flow and main-landing protection. - Existing Phase 3 `platformctl plan/apply/health` chain. - AGENTS.md security-sensitive class of service. ### Runtime evidence No RS2000 runtime mutation. Local checks passed: ```bash PYTHONPATH=control-plane pytest \ control-plane/platformctl/tests/test_plan_phase3.py \ control-plane/platformctl/tests/test_apply_phase3.py \ control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py \ control-plane/platformctl/tests/test_health_phase3.py \ control-plane/platformctl/tests/test_smoke.py \ -q # 97 passed PYTHONPATH=control-plane python3 control-plane/platformctl/ci/lint_workflows.py \ --policy .forgejo/ci-policy.yaml \ --workflows .forgejo/workflows \ --json /tmp/workflow-lint-auto.json \ --markdown /tmp/workflow-lint-auto.md # 0 findings git diff --check ``` ### Known constraints The deploy runner must be registered/configured separately before the post-merge workflow can perform real work. The auto-apply job fails closed unless runner-local `PLATFORMCTL_DEPLOY_READY=1` and local deploy capability are present. ### Explicit out-of-scope - No RS2000 production mutation in this PR. - No Forgejo repo secrets for deploy. - No vps1000 auto-apply. - No absolute Agaria compose paths. - No canonical compose import/migration yet. - No arbitrary “run command with secrets” workflow. ### Requested decision Approve the dedicated deploy-runner boundary and narrow active workflow skeleton, then perform the one-time deploy runner setup before relying on auto-apply as the normal RS2000 change path. ### Merge blockers - Any production deploy secret routed through Forgejo repo secrets. - Any PR-head deploy execution path. - Any broad shared runner replacing the dedicated `deploy-host` tier. - Any reviewer finding that the workflow can mutate production from untrusted PR code. ## Operator Merge Checklist 1. Merge #233 first, or confirm its branch-protection readiness checker is already on `main`. 2. Do not create Forgejo repo secrets for production deploy: no SSH key, no Tailscale client secret, no Forgejo PAT/provider key. 3. Register/configure dedicated runner `rs2000-deploy-host` with label `deploy-host` before expecting auto-apply to work. 4. Set runner-local deploy readiness only after checks pass: `PLATFORMCTL_DEPLOY_READY=1`, local Forgejo apply token bridge, SSH/Tailscale capability, and `PLATFORMCTL_REMOTE_ROOT=/opt/pdurlej-platform/current`. 5. If the PR is not mergeable or auto-apply reports `not_configured`, do not guess; ask Codex/Claude for the next exact command. ## Spec sources read - `AGENTS.md` — identity, Forgejo API, security-sensitive review class. - `docs/ci/README.md` — CI trust-tier documentation target. - `docs/ci/runner-contract.md` — runner contract target. - `runbooks/forgejo-actions-runner.md` — runner setup documentation target. - `.forgejo/ci-policy.yaml` — workflow policy source. - `control-plane/platformctl/apply.py` — apply remote-root and approval behavior. - `control-plane/platformctl/cli.py` — CLI flag surface. - `control-plane/platformctl/tests/test_apply_phase3.py` — apply tests. - `control-plane/platformctl/tests/test_forgejo_ci_scripts_contract.py` — contract tests. Refs #142 Refs #220

codex added 1 commit

2026-05-12 07:43:07 +02:00

ci: document deploy runner secret boundary

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

Details

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

Details

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

Details

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

Details

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