Fix GitHub Actions release pipeline 403 permission error

[Copilot]

Problem

The GitHub Actions release pipeline was failing with HTTP 403 "Forbidden" errors when attempting to create releases. The error logs showed:

⚠️ GitHub release failed with status: 403
undefined
retrying... (2 retries remaining)
❌ Too many retries. Aborting...

Analysis revealed that the GITHUB_TOKEN had insufficient permissions, only providing read access (Contents: read, Metadata: read, Packages: read) when write access was required to create releases.

Solution

1. Added Required Permissions

Added explicit contents: write permission to the release workflow:

permissions:
  contents: write

This grants the workflow the necessary permissions to create GitHub releases, upload assets, and manage repository content.

2. Enhanced Tag Validation

Improved the workflow to properly handle both automatic (git tag push) and manual (workflow_dispatch) triggers with semantic versioning validation:

- name: Determine tag name
  id: tag
  run: |
    if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
      TAG_NAME="${{ github.event.inputs.tag }}"
    else
      TAG_NAME="${{ github.ref_name }}"
    fi
    
    # Validate tag name format (should be v*.*.* or similar)
    if [[ ! "$TAG_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+.*$ ]]; then
      echo "::error::Invalid tag name format: $TAG_NAME. Expected format: v1.0.0 or v1.0.0-beta"
      exit 1
    fi

This prevents issues like using branch names ("master") as release tags and enforces proper semantic versioning.

3. Documentation Updates

Updated the troubleshooting section in docs/PIPELINE_GUIDE.md to include specific guidance for permission-related failures:

• Added HTTP 403 error troubleshooting steps
• Clarified tag format requirements
• Enhanced error diagnosis information

Testing

• ✅ Validated YAML syntax and workflow structure
• ✅ Confirmed all required permissions are properly set
• ✅ Verified tag validation logic works correctly
• ✅ Ensured Windows runner configuration is maintained

Impact

This fix resolves the pipeline release failures and ensures:

• Releases can be created successfully via both git tag pushes and manual workflow triggers
• Proper semantic versioning is enforced
• Clear error messages guide users when issues occur
• The workflow is more robust and maintainable

The next release trigger should complete successfully without the 403 permission error.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.