ci(release): allow optional branch argument (defaults to main)

[kurodo3]

Summary

• Adds an optional branch input to the release.yml workflow dispatch (defaults to main) — omitting it is identical to today's behavior
• Adds a validate-branch pre-flight job that calls the GitHub API to verify the branch exists before tests or any state-creating steps run; uses BRANCH env var (not inline template expression) to prevent script injection
• Wires ref: ${{ inputs.branch }} into the test and build checkout steps so tests and tag creation target the release branch tip
• Updates RELEASING.md with the new parameter, updated job-graph diagram, and a concrete hotfix-release example (hotfix/0.1.x → v0.1.1)

Closes ITL-545

Test plan

• Trigger the release workflow without specifying a branch — confirm behavior is identical to today (cuts from main)
• Trigger the release workflow with a valid non-main branch — confirm the tag is created at that branch's tip
• Trigger the release workflow with a non-existent branch name — confirm validate-branch fails immediately with Branch '...' does not exist. Check for typos. and no other jobs start

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Adds a branch parameter to the manual release workflow so releases (tests + tag creation) can be cut from non-main branches, with a pre-flight branch existence check and updated release documentation.

Changes:

• Add branch input (default main) plus a validate-branch job to fail fast on invalid branches.
• Check out ref: ${{ inputs.branch }} in test and build so the release targets the chosen branch tip.
• Document the new branch input and a hotfix release example in RELEASING.md (plus new superpowers spec/plan artifacts).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
.github/workflows/release.yml	Adds branch input + validate job; wires checkout ref for test/build; gates license-check on validation.
RELEASING.md	Documents optional branch input and hotfix release instructions + updated job graph.
superpowers/specs/2026-07-21-itl-545-release-branch-argument-design.md	Captures the approved design for the optional branch workflow input and validation approach.
superpowers/plans/2026-07-21-itl-545-release-branch-argument.md	Implementation plan/checklist for making the workflow + docs changes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[kurodo3]

Fixed in 255d054. Added ENCODED_BRANCH="${BRANCH//\//%2F}" in the run: script and switched the gh api call to use ${ENCODED_BRANCH} in the URL path. The error message still shows the original ${BRANCH} value so it's readable to the user. This handles branch names like hotfix/0.1.x correctly.

[kurodo3]

This limitation was explicitly acknowledged in the design spec and scoped out: the license check validates installed dependencies (from pyproject.toml/uv.lock), not branch-specific source, so running it against the dispatch ref is considered acceptable for this workflow. The _license-check.yml reusable workflow has no workflow_call inputs, so it cannot receive a ref without a more involved interface change — that's a separate piece of work. Leaving as-is per the original design decision.

[eywalker]

Why not address this change in this issue?

[kurodo3]

Fixed in 492530e. Added a branch input (default main) to _license-check.yml's workflow_call trigger and wired ref: ${{ inputs.branch }} into its checkout step. The license-check job in release.yml now passes with: branch: ${{ inputs.branch }} through to the reusable workflow.

[kurodo3]

Fixed in 255d054. Added a step 2 to the hotfix example explicitly calling out that the Use workflow from dropdown should remain on main (not hotfix/0.1.x), so the workflow version with the Branch field is used.

[kurodo3]

Review round summary (commit 255d054)

Three comments addressed:

Fixed — URL encoding for branch names with /
Added ENCODED_BRANCH="${BRANCH//\//%2F}" in the validate-branch run script and switched the gh api call to use ${ENCODED_BRANCH} as the path parameter. The error message still uses the human-readable ${BRANCH} value. Branch names like hotfix/0.1.x now work correctly.

Fixed — "Use workflow from" dropdown clarification in RELEASING.md
Added an explicit step 2 to the hotfix release example stating that the Use workflow from dropdown should remain on main, not the hotfix branch, so the workflow version includes the Branch field.

Not changed — license-check running against dispatch ref
This limitation was acknowledged and explicitly scoped out in the design spec. The _license-check.yml reusable workflow validates installed dependencies (from pyproject.toml/uv.lock) rather than branch-specific source, so running against the dispatch ref is acceptable. Fixing it would require adding workflow_call inputs to _license-check.yml — that's a separate piece of work outside this PR's scope.

[kurodo3]

Review round summary (commit 492530e)

One change addressed:

Fixed — license-check running against dispatch ref instead of release branch

_license-check.yml now declares a branch input (optional, default main) on its workflow_call trigger, and passes it as ref: ${{ inputs.branch }} to its actions/checkout step. The license-check job in release.yml passes with: branch: ${{ inputs.branch }} through to the reusable workflow. License checking now runs against the actual release branch, including its uv.lock.