projectbluefin/common/release-promotion

Release and promotion — common

Load this when cutting a release, evaluating whether a monthly tag is safe to create, doing a hotfix, or verifying signed artifacts.

When to Use

• Cutting or evaluating a monthly release tag
• Doing a hotfix outside the monthly window
• Verifying cosign signatures, SBOM, or SLSA attestations on a published image
• Understanding how common changes propagate to downstream :testing builds
• Debugging the testing→main squash promotion pipeline

When NOT to Use

• CI workflow editing (SHA pinning, pre-commit, Renovate) → `ci-tooling.md`
• Debugging silent CI failures or startup_failure → `ci-pitfalls.md`
• PR review or issue triage workflows

Promotion criteria

A common release is safe when all of the following are true:

If any criterion fails, do not tag a release. File or escalate the blocker issue and wait.

Planned gate (common#513): The monthly release.yml will be updated to run the promotion-candidate E2E as a required prerequisite job before creating the GitHub Release. Until that ships, the check above is manual.

Monthly release cadence

• Schedule: 1st of every month at 00:00 UTC (release.yml cron)
• Tag format: v<YEAR>.<MONTH> — e.g., v2026.06
• What it creates: A GitHub Release with a changelog since the previous tag, pointing at the current main HEAD
• What it does NOT do: Promote or retag the OCI image — :latest is always the most recent merge to main

Emergency hotfix release

When a critical fix needs a versioned tag outside the monthly window:

1. Merge the fix to main via normal PR process
2. Verify all promotion criteria above are met
3. Run release.yml manually via workflow_dispatch — it will tag the current main with the current month's tag (or create a patch tag manually with gh release create)
4. Notify downstream image repos if the fix affects their builds

Common Rationalizations

Red Flags

• Promotion PR has release/blocked with no E2E evidence → check post-testing-e2e.yml branches: filter
• promote-testing-to-main.yml fails with UD conflicts → file deletions on testing haven't reached main
• Publish workflow stuck in_progress > 30 min → zombie run holding concurrency queue
• execute-release.yml not triggering after promotion PR merges → check commit subject match

Verification

• [ ] Confirm all four promotion criteria are met before tagging
• [ ] For artifact verification: run gh attestation verify (keyless, post-2026-06-11), not just cosign verify
• [ ] After a hotfix: notify downstream repos if the fix affects their builds
• [ ] After a squash branch rebuild: wait for PR Validation — testsuite to complete before enqueuing

References