Fix release workflow to verify tag is on main branch before publishing

[Copilot]

Problem

The release.yml workflow currently triggers on any push of a version tag (v*), regardless of which branch the tag is on. With the main branch now protected and requiring pull requests for all changes, this creates a potential issue:

• If a tag is pushed on a feature/release branch during PR creation, the workflow would trigger immediately
• The release would attempt to publish from the feature branch instead of from main
• There was no verification ensuring releases only originate from reviewed and merged code on main

Solution

This PR adds a verification step to the release workflow that checks if the tag's commit exists on the main branch before proceeding with PyPI publishing.

Workflow Changes

The release.yml workflow now:

1. Checks out the repository with full git history (fetch-depth: 0)
2. Verifies the tag's commit is on origin/main using git branch -r --contains
3. Fails gracefully with a clear error message if the tag is not on main
4. Only proceeds with PyPI publishing if the verification passes

- name: Verify tag is on main branch
  run: |
    TAG_COMMIT=$(git rev-list -n 1 ${{ github.ref }})
    if ! git branch -r --contains $TAG_COMMIT | grep -q 'origin/main'; then
      echo "Error: Tag ${{ github.ref_name }} is not on the main branch"
      exit 1
    fi

Updated Release Process

The documentation and tooling have been updated to reflect a PR-based release workflow:

1. Create a release branch: git checkout -b release-x.y.z
2. Run the release task: invoke release [patch|minor|major]
3. Push the branch and tags: git push origin release-x.y.z && git push origin --tags
4. Create a Pull Request to main
5. After PR review and merge, the workflow automatically publishes to PyPI

The invoke release task no longer prompts for direct pushing, instead providing clear guidance on the next steps.

Benefits

• Prevents accidental releases: Tags on feature branches will trigger the workflow but fail verification safely
• Works with protected branches: Compatible with branch protection rules requiring PRs
• Maintains security: Ensures releases only come from reviewed and merged code
• Clear error messages: Failed verifications provide actionable guidance
• Minimal changes: Only 3 files modified with 36 insertions and 7 deletions

Testing

The verification logic was tested locally to confirm:

• Commits on PR branches are correctly identified as NOT on main
• After merge, commits are correctly identified as on main
• YAML, Python, and RST syntax all validated successfully

Fixes #[issue_number]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Verify release workflow</issue_title>
<issue_description>Check the release.yml github actions workflow. It's currently triggered on push of a version tag, but now main is protected and cannot be pushed to directly. In the past, it was possible for admins to force push tags there and that would trigger the process, however, if I push a tag on a branch now in a Pull Request, this will maybe try to release from a branch? It's not clear to me. What would be the approach to get this workflow to trigger at the right time, only when the PR containing the proposal for release gets merged into main containing the tag as well?</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #144

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[gonzalocasas]

@sea-bass @EzraBrooks what do you think about this to fix the release workflow to work correctly with the new permissions/branch protection rules?

[sea-bass]

I trust that in your approval you've verified the Copilot generated code and are happy with the results? If so, go ahead!

[gonzalocasas]

I trust that in your approval you've verified the Copilot generated code and are happy with the results? If so, go ahead!

Indeed, I tested the generated code locally as close as possible, I'll merge and create a release PR for 2.0.0!
Thank you!