Files
kandev/docs/plans/persistent-fork-approval-labels/plan.md
T
2026-08-24 11:09:03 +00:00

123 lines
5.3 KiB
Markdown

---
spec: docs/specs/integrations/requirements/claude-fork-review-allowlist.md
created: 2026-08-22
status: implemented
---
# Implementation Plan: Persist Fork Approval Labels
## Overview
Change the fork approval workflows so `safe-to-test` and `safe-to-review` are
durable maintainer approvals. Remove the synchronize-time cleanup jobs, allow
the existing label paths on follow-up pushes, and add contract coverage that
prevents either workflow from silently returning to per-commit re-approval.
Update the related security decision and allowlist spec in the same change.
## Confirmed root cause
PR #2815 is a fork pull request. The GitHub audit trail shows both labels added
by a maintainer and later removed by `github-actions[bot]` after contributor
pushes. The corresponding successful workflow runs executed
`strip-safe-to-test` and `strip-safe-to-review`. The jobs and the
`event.action != 'synchronize'` guards are explicit in the current workflow
files.
## Workflow changes
- `.github/workflows/preview-env.yml`
- Keep `safe-to-test` in the `deploy-fork` authorization expression.
- Remove the `github.event.action != 'synchronize'` exclusion from that label
path so an existing approval authorizes the current fork head after pushes.
- Remove the `strip-safe-to-test` job and stale per-commit comments.
- `.github/workflows/opencode-code-review.yml`
- Keep `safe-to-review` in the fork review authorization expression.
- Remove the synchronize exclusion from that label path.
- Remove the `strip-safe-to-review` job and stale per-commit comments.
- `.github/workflows/lint-action-pinning.yml`
- Run the OpenCode workflow contract test in the existing always-on workflow
contract suite.
## Contract tests
- `.github/scripts/preview-env-workflow-contract_test.py`
- Assert the preview workflow keeps the label authorization path.
- Assert the synchronize exclusion and `strip-safe-to-test` job are absent.
- `.github/scripts/opencode-code-review-workflow-contract_test.py`
- Add focused coverage for the fork label gate, synchronize eligibility, and
absence of `strip-safe-to-review`/`removeLabel` cleanup.
- Keep the Claude workflow contract test passing to prove the separate
open/labeled-only Claude review policy remains unchanged.
## Documentation and decision records
- Amend `docs/specs/integrations/requirements/claude-fork-review-allowlist.md` with durable-label
scenarios and the changed OpenCode/preview behavior.
- Amend `docs/decisions/2026-08-07-claude-allowlist-label-bridge.md` to point
the superseded per-commit clause at the new decision.
- Add `docs/decisions/2026-08-22-persistent-fork-approval-labels.md` and index
it in `docs/decisions/INDEX.md`.
## Tests
- **What:** The preview label path authorizes a fork `synchronize` event and no
cleanup job removes `safe-to-test`.
**File:** `.github/scripts/preview-env-workflow-contract_test.py`.
**How:** Read the workflow text and assert the label expression remains, the
synchronize exclusion is absent, and the cleanup job is absent.
- **What:** The OpenCode label path authorizes a fork `synchronize` event and
no cleanup job removes `safe-to-review`.
**File:** `.github/scripts/opencode-code-review-workflow-contract_test.py`.
**How:** Read the workflow text and assert the trigger, label gate, and
absence of cleanup and synchronize exclusion.
- **What:** Existing fork allowlist labeling and Claude review behavior remain
intact.
**File:** `.github/scripts/claude-code-review-workflow-contract_test.py`.
**How:** Run the existing contract suite without changing its open/labeled
assertions.
## Verification commands
Run from the repository root:
```bash
python3 .github/scripts/preview-env-workflow-contract_test.py
python3 .github/scripts/opencode-code-review-workflow-contract_test.py
python3 .github/scripts/claude-code-review-workflow-contract_test.py
python3 .github/scripts/lint-action-pinning_test.py
python3 .github/scripts/lint-action-pinning.py
zizmor .github/workflows
git diff --check
```
## Implementation Waves
Wave 1 (sequential; one coupled security-boundary change):
- [x] [Task 01: Persist fork approval labels](task-01-persist-fork-approval-labels.md)
## Risks and out of scope
- This intentionally makes a maintainer label approval apply to future fork
heads. Maintainers must remove labels when trust should be revoked.
- `CLAUDE_REVIEW_ALLOWLIST` and the other direct allowlist paths remain
independent and fail-closed.
- The Claude review workflow does not gain a `synchronize` trigger in this
change. This task does not alter same-repository review behavior or add a new
token/App-based label event bridge.
## Verification Results
- RED: The new preview and OpenCode contract assertions failed against the
pre-change workflows because the synchronize exclusions and cleanup jobs
were still present.
- GREEN: `preview-env-workflow-contract_test.py` (2 tests),
`opencode-code-review-workflow-contract_test.py` (3 tests), and the existing
`claude-code-review-workflow-contract_test.py` (9 tests) pass.
- Security checks: `lint-action-pinning_test.py` (9 tests) and
`lint-action-pinning.py` pass; `git diff --check` passes.
- `zizmor .github/workflows` ran but exits non-zero on existing repository-wide
findings, including pre-existing dangerous-trigger, permissions, artifact,
cache, and template-injection findings. This change did not expand that
audit scope.