kandev/docs/plans/release-pr-queue-bypass/plan.md

spec, created, status

spec	created	status
docs/specs/release/requirements/release-pr-queue-bypass.md	2026-08-17	complete

Implementation Plan: Stable Release PR Queue Bypass

Overview

The release workflow still requests an immediate branch deletion during a queued merge. GitHub rejects that option before the generated release pull request can merge.

The repair uses an organization-administrator personal access token for one privileged pull-request merge. It then binds tag creation to the merge commit reported by GitHub.

Release workflow

Regression contract

• Update .github/scripts/release-workflow-contract_test.py before the workflow change.
• Require the protected RELEASE_PR_BYPASS_TOKEN secret only in the privileged merge step.
• Require an explicit missing-token failure before the merge command.
• Require GITHUB_TOKEN for branch push and pull-request creation.
• Require the administrator token for gh pr merge --admin only.
• Require GITHUB_TOKEN for merged-state inspection.
• Reject --delete-branch, queue enrollment, polling, and a merge without --match-head-commit.
• Require the reported merge commit to exist on origin/main before tag creation.
• Require a valid lowercase pull-request title subject.

Immediate privileged merge

• Update .github/workflows/release.yml.
• Read RELEASE_PR_BYPASS_TOKEN only in the normal-release merge step.
• Fail before the merge command when the secret is empty.
• Capture the release pull-request URL and head commit.
• Merge with --admin, --squash, and --match-head-commit.
• Remove --delete-branch and rely on repository branch cleanup.
• Read the merged state and merge commit through GITHUB_TOKEN.
• Fetch main, make sure that it contains the merge commit, and select that commit for signing.
• Keep the existing public-key revalidation after the merge.

Release contract records

• Update docs/public/release-process.md as a how-to guide.
• Update docs/ci-merge-queue.md with the administrator-token exception.
• Update .agents/skills/release/SKILL.md with the bypass and configuration contract.
• Update AGENTS.md because its release guidance must name the bypass requirement.
• Set the repair spec and its index entry to shipped after the implementation checks pass.
• Keep ADR 2026-08-17-release-pr-ruleset-bypass aligned with the final implementation.

Tests

• What: Normal Stable releases expose the administrator token only to the privileged merge step. File: .github/scripts/release-workflow-contract_test.py. How: Assert the secret name, normal-release condition, missing-secret guard, and token isolation.
• What: Release pull requests bypass CI and the merge queue for one exact head. File: .github/scripts/release-workflow-contract_test.py. How: Assert --admin, --squash, and --match-head-commit. Reject --delete-branch and --auto.
• What: Tag signing uses the merge commit that GitHub reports. File: .github/scripts/release-workflow-contract_test.py. How: Assert merged-state parsing, ancestry validation against origin/main, and local selection of the reported commit.
• What: Excluded release modes cannot request the bypass token. File: .github/scripts/release-workflow-contract_test.py. How: Assert the normal-release condition on token creation, identity validation, and privileged merge steps.
• What: Maintainer documentation names the token scope, owner, expiration, rotation, ruleset, and protected environment contract. Files: docs/public/release-process.md, .agents/skills/release/SKILL.md, AGENTS.md, and docs/ci-merge-queue.md. How: Use the public-doc and harness-file validators.

Verification results

• python3 .github/scripts/release-workflow-contract_test.py passed 31 tests.
• python3 .github/scripts/lint-action-pinning_test.py passed 9 tests.
• node --test scripts/validate-public-docs.test.mjs passed 61 tests.
• node scripts/validate-public-docs.mjs validated 41 pages.
• python3 scripts/lint-harness-files.test.py passed 19 tests.
• python3 .github/scripts/lint-harness-files.py --all passed 118 files.
• pre-commit run harness-lint --files AGENTS.md .agents/skills/release/SKILL.md passed.
• git diff --check passed.
• actionlint was not available in the local environment. The repository contract tests and commit hooks remain required.

Implementation waves and parallel candidates

Wave 1 (sequential):

• task-01-release-workflow

Wave 2 (sequential, depends on Wave 1):

• task-02-release-documentation

Parallel delegation is not authorized. The tasks share the release contract and run sequentially in the primary conversation.

Post-merge rollout

1. Create a fine-grained personal access token from an organization administrator account.
2. Select only kdlbs/kandev and grant contents: write permission.
3. Add the token as the RELEASE_PR_BYPASS_TOKEN secret in the release environment.
4. Record its owner and expiration date in the maintainers' credential inventory.
5. Dispatch a new normal Stable release for v0.89.0.
6. Make sure that the release PR merges immediately and the signed tag targets its merge commit.

The implementation delivery closes stale release PR #2751. The next release run removes and recreates its existing release branch.

Open questions

None.