[BUG] Draft release is invisible to read-only publication jobs

[Brad-Edwards]

Description

The hardened release workflow creates a draft GitHub Release successfully, then fails before verification because the jobs that inspect that draft have only contents: read permission.

Release Please created the v3.4.0 tag and draft Release, but resolve-release failed at gh release view v3.4.0 with release not found. GitHub documents that only identities with push access can receive draft releases. The job's read-only GITHUB_TOKEN therefore cannot resolve the draft it is required to validate.

This is a workflow-permission failure, not a package, test, or OS-identity implementation failure.

Failed run: https://github.com/OpenRAE/rae/actions/runs/33701243875

Relevant workflow:

rae/.github/workflows/release-please.yml

Lines 57 to 105 in e0f6325

	resolve-release:
	needs: release-please
	if: >-
	always()
	&& ((github.event_name == 'push'
	&& needs.release-please.result == 'success'
	&& needs.release-please.outputs.release_created == 'true')
	|| github.event_name == 'workflow_dispatch')
	runs-on: ubuntu-latest
	permissions:
	contents: read
	outputs:
	release_sha: ${{ steps.resolve.outputs.release_sha }}
	base_sha: ${{ steps.resolve.outputs.base_sha }}
	tag: ${{ steps.resolve.outputs.tag }}
	release_id: ${{ steps.resolve.outputs.release_id }}
	release_is_draft: ${{ steps.resolve.outputs.release_is_draft }}
	steps:
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
	with:
	fetch-depth: 0
	- name: Resolve and bind the immutable release commit
	id: resolve
	env:
	EVENT_NAME: ${{ github.event_name }}
	GH_TOKEN: ${{ github.token }}
	INPUT_TAG: ${{ inputs.tag }}
	RELEASE_PLEASE_TAG: ${{ needs.release-please.outputs.tag_name }}
	RELEASE_PLEASE_SHA: ${{ needs.release-please.outputs.sha }}
	run: |
	set -euo pipefail
	if [ "${EVENT_NAME}" = "workflow_dispatch" ]; then
	tag="${INPUT_TAG}"
	expected_sha=""
	else
	tag="${RELEASE_PLEASE_TAG}"
	expected_sha="${RELEASE_PLEASE_SHA}"
	fi
	if [[ ! "${tag}" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
	echo "Expected a stable SemVer release tag such as v1.0.0, got '${tag}'" >&2
	exit 1
	fi
	release_json="$(
	gh release view "${tag}" --repo "${GITHUB_REPOSITORY}" \
	--json databaseId,isDraft,tagName
	)"

Draft visibility rule: https://docs.github.com/en/rest/releases/releases#list-releases

Introduced by the exact-SHA release hardening in #1138.

Steps to reproduce

1. Configure Release Please with draft: true and merge a release PR into main.

2. Allow the release-please job, which has contents: write, to create the tag and draft Release.

3. In a subsequent job with contents: read, run:

   gh release view v3.4.0 --repo OpenRAE/rae --json databaseId,isDraft,tagName

4. Observe release not found even though the draft Release exists and is visible to a push-capable identity.

The current v3.4.0 run reproduces this at commit e0f6325428f26b20e971a7ccce6471e94d689435.

Expected behavior

The publication graph should be able to resolve and validate the exact draft Release created by Release Please, run the exact-SHA verification and required container gate, build and smoke-test the distributions, publish them to PyPI, attach the tested artifacts, and finalize that same numeric GitHub Release.

The fix must retain the anti-race, exact-SHA, numeric-release-ID, artifact-identity, and retry-safety guarantees introduced by #1138.

Actual behavior

resolve-release has contents: read. Its draft lookup returns release not found, so set -euo pipefail terminates the job. All downstream verification, build, PyPI, attachment, finalization, and dev-sync jobs are skipped.

There is a second instance of the same permission mismatch: publish-pypi also has contents: read and re-runs gh release view against the still-draft Release immediately before PyPI publication. Fixing only resolve-release is therefore expected to move the same failure downstream.

The draft Release remains unpublished and PyPI remains on 3.3.0.

Environment

• RAES SDL version: N/A — repository release workflow
• Commit: e0f6325428f26b20e971a7ccce6471e94d689435
• Python version: N/A at failure point
• OS: GitHub-hosted Ubuntu 24.04 runner

Minimal input

resolve-release:
  permissions:
    contents: read
  steps:
    - env:
        GH_TOKEN: ${{ github.token }}
      run: gh release view v3.4.0 --repo OpenRAE/rae --json databaseId,isDraft,tagName

Acceptance criteria

• resolve-release can inspect and bind the Release Please-created draft to its numeric Release ID, tag, and exact commit SHA.
• The pre-PyPI identity revalidation can inspect that same draft after any protected-environment wait.
• No job relying on read-only draft visibility remains in the publication path.
• Exact-SHA verification, required unskipped container tests, single-build artifact reuse, tag dereferencing, numeric-ID finalization, artifact byte matching, and retry safety remain enforced.
• Workflow tests cover the permission/visibility requirement for every draft lookup, not only the command structure.
• The existing v3.4.0 draft can be resumed or safely republished without changing its bound commit or publishing duplicate artifacts.
• A successful run publishes the 3.4.0 wheel and sdist to PyPI and makes the corresponding GitHub Release public.

Downstream impact

Brad-Edwards/aptl#918 is waiting for a published RAES release containing #1077. The required implementation is present in the v3.4.0 tag, but APTL cannot consume it through its published, hashed dependency path until this release completes.

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 1190-draft-release-permissions, 2026-09-03T02:50:55.509Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #1190). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #1190). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Implementation plan

1. Lock the draft-visibility invariant with a regression test (Path B). Extend implementations/python/tests/test_release_workflows.py with a parsed, job-discovering assertion: retain workflow-level contents: read; find every job whose shell requests or parses GitHub Release draft state; require each such job to declare job-scoped contents: write; and require every checkout in a write-scoped job to set persist-credentials: false. Update the existing focused permission assertions to match. Run the focused test before the workflow change and record the expected failures for resolve-release, publish-pypi, and elevated checkout credential persistence.

2. Apply the least-privilege workflow correction (Path B). In .github/workflows/release-please.yml, grant contents: write only to resolve-release and publish-pypi, preserve id-token: write exclusively on publish-pypi, and disable persisted checkout credentials in resolve-release and the already-write-scoped publish-github job. Keep publish-pypi checkout-free and keep GH_TOKEN step-local. Do not alter the dependency graph, exact-SHA/tag dereferencing, numeric Release ID, container gate, single-build artifact flow, artifact byte matching, or retry-safe finalization.

3. Keep operator and architecture guidance aligned (Path D riding with the executable fix). Retain the architecture-preflight updates to docs/decisions/issue-1125-gov-928-exact-sha-release-verification-preflight.md and docs/explain/releasing.md, including the job-scoped permission rationale, non-persisted credential boundary, and existing manual-tag recovery seam for the v3.4.0 draft. No new release input, PAT, early publication path, schema, package version, or changelog change is introduced.

4. Verify all acceptance criteria. Re-run the focused release workflow tests, then the required completion and policy gates. Map each issue criterion to workflow/test/doc lines. The structural tests will cover every current and future shell-based draft lookup rather than only the two known failures, while existing tests continue to enforce exact-SHA verification, required container testing, single-build reuse, numeric-ID finalization, byte identity, and retry safety.

Design checks

• Security: GitHub event authorization, job permission resolution, protected PyPI OIDC, step-local token binding, shell validation, and runner credential persistence remain fail-closed. The unavoidable contents: write + id-token: write aggregation is confined to the checkout-free PyPI job; no long-lived token is added.
• Maintainability: reuse the safe YAML loader and existing workflow-structure suite; make draft-inspection discovery data-driven instead of duplicating a job-name allowlist.
• Extensibility: the parsed assertion automatically covers another shell draft lookup; workflow_dispatch.inputs.tag remains the sole recovery seam.
• Whole repository: the canonical release workflow, release configuration, reusable verifier, Docker gate, action-pin policy, release tests, GOV-928 preflight, and release runbook are the relevant surfaces. Published schemas, application packages, version metadata, and CHANGELOG.md remain untouched.

This extends the incumbent release-workflow test suite; it does not add a new repository policy engine, MCP gate, or implementation-workflow station.

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #1190 (branch 1190-draft-release-permissions)
Diff mode: inline — the complete diff was supplied in one prompt

Core review

Verdict: ship

This is shaped correctly: it narrowly repairs the GitHub draft-Release permission boundary at the two jobs that inspect draft state, retains read-only defaults and verification jobs, prevents elevated checkout credentials from persisting, and explicitly documents the unavoidable permission aggregation in the PyPI job. The generalized workflow test protects the cross-cutting invariant without coupling it only to today’s job names, while the existing immutable-SHA and publication seams remain intact. It leaves room for additional draft-inspection jobs through the same job-scoped permission pattern and does not conflict with the amended release decision.

No blocking findings.

Security review

Verdict: ship

This is shaped correctly: the change narrowly grants job-scoped contents: write where GitHub’s authorization model requires push capability to inspect draft Releases, while retaining the workflow-wide read-only default and disabling credential persistence on elevated checkouts. The PyPI job necessarily combines release visibility with OIDC issuance, but remains checkout-free and preserves the existing identity revalidation seam. No concrete exploitable security regression is introduced by the diff.

No blocking findings.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #1190 on branch '1190-draft-release-permissions'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.

[Brad-Edwards]

Review decision record — codex cycle 1 (issue #1190)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: This is shaped correctly: it narrowly repairs the GitHub draft-Release permission boundary at the two jobs that inspect draft state, retains read-only defaults and verification jobs, prevents elevated checkout credentials from persisting, and explicitly documents the unavoidable permission aggregation in the PyPI job. The generalized workflow test protects the cross-cutting invariant without coupling it only to today’s job names, while the existing immutable-SHA and publication seams remain intact. It leaves room for additional draft-inspection jobs through the same job-scoped permission pattern and does not conflict with the amended release decision.

Security reviewer: This is shaped correctly: the change narrowly grants job-scoped contents: write where GitHub’s authorization model requires push capability to inspect draft Releases, while retaining the workflow-wide read-only default and disabling credential persistence on elevated checkouts. The PyPI job necessarily combines release visibility with OIDC issuance, but remains checkout-free and preserves the existing identity revalidation seam. No concrete exploitable security regression is introduced by the diff.

Blocking findings: 0 (clean run)

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 — issue #1190

Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch: 1190-draft-release-permissions
Cycle: 1 / 1
Findings: 1

Finding 1 — [critical] implementations/python/tests/test_release_workflows.py::_run_github_finalization

Problem: The git and gh api stubs used by _run_github_finalization are hardcoded to always return values matching EXPECTED_SHA / EXPECTED_RELEASE_ID / EXPECTED_TAG / draft=false, for every test that calls the helper. This means the shell script's own re-verification guards against a moved tag (release-please.yml lines 615-619, 653-656, 678-682) and against a tampered finalization response (lines 691-696) can never be driven to their failure branch by any test in this file. Only the static substring check in test_publication_is_split_retry_safe_and_finalizes_the_same_release confirms the comparison text exists in the script — it does not confirm the comparison actually rejects a mismatch at runtime.
Why it matters: If someone deleted or weakened any of these post-network-call re-verification checks (the exact TOCTOU defenses this PR/file is about — 'exact-SHA release verification'), every existing test would keep passing, because the stubs never present a moved tag or a tampered PATCH response to catch the regression.
Fix: Parameterize the git stub in _run_github_finalization (e.g. a moved_tag: bool argument) so rev-parse --verify can return a SHA different from EXPECTED_SHA, and add a test asserting the finalization step fails with 'Release tag moved...' when it does. Similarly parameterize the gh api PATCH response so it can return a mismatched id/tag/draft, and add a test asserting 'GitHub Release finalization response changed the verified identity' fires.

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 complete for issue #1190 on branch '1190-draft-release-permissions'. Posted by the MCP server to enforce the gc_test_quality_review hard-cap-1 contract (issue #884 follow-up, default lowered in #906). Do not edit or delete — used by the next gc_test_quality_review invocation to count cycles.

[Brad-Edwards]

Review decision record — test-quality cycle 1 (issue #1190)

Reviewer: test-quality
Cycle: 1

Architectural read:

This test file earns its keep in most respects: rather than only inspecting workflow YAML structure, it extracts the embedded shell scripts from release-please.yml with a yaml.safe_load + step lookup, executes them under real bash/jq against hand-written gh/git stubs, and asserts on process exit codes and stdout/stderr — this is the correct way to unit-test CI shell policy, and it correctly drives several negative paths (replaced release id, moved tag pre-PyPI, mismatched already-public assets) to their actual failure exit codes rather than just checking that a guard string exists in the script. The one structural gap is in _run_github_finalization: two of its stubbed responses (git rev-parse --verify and the gh api PATCH response) are hardcoded to always match the expected identity across every test that uses the helper, so several of the script's own tag-moved / finalization-response guards — which exist specifically to close TOCTOU windows in the exact-SHA release flow this file is about — are never driven to their failure branch. The remaining "moved" and "response changed" checks are covered today only by the static substring assertion in test_publication_is_split_retry_safe_and_finalizes_the_same_release, which is an existence check, not a live one. This is fixable within the existing helper without restructuring anything.

Blocking findings: 1

Finding 1 — class (2 instances)

• ID: F1
• Title: (no title)
• Decision: fix
• Rationale: Addressed by next cycle
• Instances:
  • implementations/python/tests/test_release_workflows.py:186-189 (git stub: rev-parse --verify always echoes $EXPECTED_SHA, defeating the moved-tag checks at release-please.yml:615-619, 653-656, 678-682)
  • implementations/python/tests/test_release_workflows.py:166-169 (gh stub: api:* PATCH response hardcoded to {"id":1234,"tag_name":"v3.4.5","draft":false}, defeating the finalization-response check at release-please.yml:691-696)

[Brad-Edwards]

Review decision record — test-quality cycle 1 (issue #1190)

Reviewer: test-quality
Cycle: 1
Verdict: ship-with-fixes

Architectural read:

The two unreachable identity-mismatch branches identified by the test-quality review were made executable through parameterized git and GitHub API stub responses. Regression tests now prove that a moved tag and a tampered finalization response both fail closed.

Blocking findings: 1

Finding 1 — class (2 instances)

• ID: F1
• Title: Finalization identity-mismatch guards lacked executable negative-path coverage
• Decision: fix
• Rationale: Parameterized both stubs and added negative-path tests for moved-tag and tampered-finalization-response failures.
• Instances:
  • implementations/python/tests/test_release_workflows.py::_run_github_finalization git rev-parse stub
  • implementations/python/tests/test_release_workflows.py::_run_github_finalization GitHub API PATCH stub

Notes (non-blocking, no decisions):

• Post-fix evidence: the focused release workflow suite passes 19 tests; Ruff formatting and lint pass; the full completion and repository-policy gates pass.
• User directed the workflow to proceed without an over-cap test-quality rerun on 2026-09-04.

[Brad-Edwards]

Pre-PR base synchronization

• Source: refs/remotes/origin/dev at 635825a15a4dfe78a6aac4596097f2e7adf44dde
• Outcome: merged_clean
• Published feature head: bd93b16efefdcd9752dd9e7476aa17c2c5b414ca
• Verified tree: e33e7a1b9d5a75d54012ba16026fb5c6fb4b8987

[Brad-Edwards]

Pre-PR base synchronization

• Source: refs/remotes/origin/dev at 635825a15a4dfe78a6aac4596097f2e7adf44dde
• Outcome: already_current
• Published feature head: bd93b16efefdcd9752dd9e7476aa17c2c5b414ca
• Verified tree: e33e7a1b9d5a75d54012ba16026fb5c6fb4b8987