Use PAT in auto-tag-release to enable Release workflow triggering (#355)

* Initial plan

* Update auto-tag-release job to use PAT for triggering release workflow

- Remove unused actions:write permission
- Add RELEASE_TOKEN to checkout step to enable workflow triggering
- Add explanatory comments about PAT requirement

Co-authored-by: devakesu <61821107+devakesu@users.noreply.github.com>

* Add detailed documentation for RELEASE_TOKEN requirements

- Document required PAT permissions (Contents: Read and write)
- Add setup instructions directly in workflow file
- Reference official GitHub PAT creation URL

Co-authored-by: devakesu <61821107+devakesu@users.noreply.github.com>

* docs: Add RELEASE_TOKEN documentation to all relevant files

- Update .example.env with RELEASE_TOKEN setup instructions
- Add Prerequisites section in RELEASING.md for PAT configuration
- Add troubleshooting section for release workflow issues
- Update README.md production checklist
- Include setup steps, required permissions, and security checklist

Co-authored-by: devakesu <61821107+devakesu@users.noreply.github.com>

* docs: Improve security guidance and clarify placeholders

- Reduce recommended PAT expiration from 1 year to 90 days-6 months
- Add token rotation guidance for better security practices
- Clarify OWNER/REPO placeholder in .example.env

Co-authored-by: devakesu <61821107+devakesu@users.noreply.github.com>

* docs: Refine guidance for clarity and decision-making

- Clarify OWNER/REPO placeholder replacement with example
- Provide specific expiration guidance (90 days vs 6 months trade-off)

Co-authored-by: devakesu <61821107+devakesu@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: devakesu <61821107+devakesu@users.noreply.github.com>

Author: Copilot

.example.env

@@ -327,6 +327,16 @@ IMAGE_NAME=ghostclass
 SOURCE_DATE_EPOCH=1767225600
 APP_COMMIT_SHA=<auto-generated-by-github-actions>
 #
+# Release Automation:
+#   RELEASE_TOKEN=<personal-access-token>
+#   - Fine-Grained Personal Access Token for auto-tag-release workflow
+#   - Required to trigger the Release workflow when version tags are pushed
+#   - Create at: https://github.com/settings/tokens?type=beta
+#   - Required permissions: Contents - Read and write
+#   - Repository access: Only select repositories (select this repo)
+#   - Add as repository secret at: https://github.com/OWNER/REPO/settings/secrets/actions
+#     (Replace entire 'OWNER/REPO' with your values, e.g., 'yourname/ghostclass')
+#
 # Sentry (same as above):
 #   SENTRY_ORG=devakesu
 #   SENTRY_PROJECT=ghostclass
@@ -396,6 +406,10 @@ COOLIFY_API_TOKEN=<your-api-token>
 # 8. Set up GitHub Secrets (for CI/CD):
 #    - Go to your repository > Settings > Secrets and variables > Actions
 #    - Add all the secrets listed in the "GITHUB SECRETS CONFIGURATION" section
+#    - IMPORTANT: Add RELEASE_TOKEN (Personal Access Token) for auto-tag-release:
+#      * Create at: https://github.com/settings/tokens?type=beta
+#      * Required permissions: Contents - Read and write
+#      * Add as repository secret named: RELEASE_TOKEN
 #
 # ============================================================================
 # SECURITY CHECKLIST
@@ -407,5 +421,6 @@ COOLIFY_API_TOKEN=<your-api-token>
 # ✅ All secrets are stored in environment variables (not hardcoded)
 # ✅ Production secrets are different from development secrets
 # ✅ GitHub Secrets are configured for CI/CD pipeline
+# ✅ RELEASE_TOKEN (PAT) is configured for auto-tag-release workflow
 # ✅ Derived variables (URLs, emails) are constructed automatically
 # ============================================================================

.github/workflows/pipeline.yml

@@ -231,12 +231,16 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
-      actions: write
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
+          # Use PAT instead of GITHUB_TOKEN to allow triggering the Release workflow
+          # Required permissions: Contents - Read and write
+          # Setup: Create Fine-Grained PAT at https://github.com/settings/tokens?type=beta
+          # and add as repository secret named RELEASE_TOKEN
+          token: ${{ secrets.RELEASE_TOKEN }}
 
       - name: Setup Node.js
         uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
@@ -316,7 +320,8 @@ jobs:
             exit 1
           fi
           
-          # Push tag with error handling
+          # Push tag with PAT (this will trigger the release workflow)
+          # Note: Using GITHUB_TOKEN would NOT trigger the release workflow
           if ! git push origin "${VERSION_TAG}"; then
             echo "ERROR: Failed to push tag ${VERSION_TAG}"
             echo "The tag was created locally but not pushed to remote"

README.md

@@ -573,6 +573,7 @@ docker run -p 3000:3000 --env-file .env ghostclass
 7. ✅ Enable HTTPS with valid SSL certificate
 8. ✅ Set up cron jobs for attendance sync
 9. ✅ Configure legal terms version and effective date
+10. ✅ Set up `RELEASE_TOKEN` secret for auto-release workflow (see [RELEASING.md](RELEASING.md))
 
 <br />
 

RELEASING.md

@@ -50,6 +50,29 @@ We follow [Semantic Versioning 2.0.0](https://semver.org/):
 
 There are three ways to create a release:
 
+### Prerequisites
+
+Before using the auto-tag-release feature, ensure the `RELEASE_TOKEN` secret is configured:
+
+1. **Create a Fine-Grained Personal Access Token**:
+   - Go to https://github.com/settings/tokens?type=beta
+   - Click "Generate new token"
+   - Token name: `GhostClass Release Automation` (or similar)
+   - Expiration: Choose appropriate expiration (recommend 90 days for higher security, up to 6 months for convenience; set rotation reminders)
+   - Repository access: "Only select repositories" → Select your repository
+   - Permissions:
+     - Repository permissions → **Contents: Read and write**
+   - Click "Generate token" and copy the token value
+
+2. **Add the token as a repository secret**:
+   - Go to your repository's Settings > Secrets and variables > Actions
+   - Click "New repository secret"
+   - Name: `RELEASE_TOKEN`
+   - Secret: Paste the PAT value
+   - Click "Add secret"
+
+**Note**: The `RELEASE_TOKEN` is required for the auto-tag-release workflow to trigger the Release workflow. Without it, version tags will be created but releases won't be automatically published.
+
 ### Automatic Release (On Version Bump)
 
 **NEW**: When you update the version in `package.json` and push to the main branch, the CI/CD pipeline will automatically:
@@ -284,6 +307,19 @@ After creating a release:
 
 ## Troubleshooting
 
+### Release workflow not triggered after tag push
+
+**Check:**
+- Verify `RELEASE_TOKEN` secret is configured in repository settings
+- Ensure the token has `Contents: Read and write` permissions
+- Check that the token hasn't expired
+- Verify the token is added to the correct repository
+
+If the tag was created but release workflow didn't trigger:
+1. The tag was likely pushed using `GITHUB_TOKEN` instead of `RELEASE_TOKEN`
+2. GitHub Actions workflows cannot trigger other workflows when using `GITHUB_TOKEN`
+3. Solution: Reconfigure `RELEASE_TOKEN` and re-push the tag (see Prerequisites section)
+
 ### Release workflow fails during build
 
 **Check:**