From e62fba9cc1aae289d31c18750a588316f6ab1111 Mon Sep 17 00:00:00 2001
From: Chris Farhood <chris@farhood.org>
Date: Thu, 12 Feb 2026 15:08:53 -0500
Subject: [PATCH] ci: use GitHub App token to enable automatic workflow
 triggering

The prepare-release workflow now uses GH_APP_TOKEN instead of
GITHUB_TOKEN to push commits and tags. This allows the tag push
to automatically trigger the release workflow without manual
intervention.

GITHUB_TOKEN cannot trigger other workflows due to GitHub's
security policy to prevent infinite workflow loops.

Added documentation in .github/GH_APP_TOKEN.md explaining the
token setup and requirements.

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
---
 .github/GH_APP_TOKEN.md                | 36 ++++++++++++++++++++++++++
 .github/workflows/prepare-release.yaml |  5 +++-
 2 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 .github/GH_APP_TOKEN.md

diff --git a/.github/GH_APP_TOKEN.md b/.github/GH_APP_TOKEN.md
new file mode 100644
index 0000000..7caac43
--- /dev/null
+++ b/.github/GH_APP_TOKEN.md
@@ -0,0 +1,36 @@
+# GitHub App Token Setup
+
+The `prepare-release.yaml` workflow requires a GitHub App token stored as a repository secret named `GH_APP_TOKEN`.
+
+## Why GitHub App Token?
+
+GitHub's default `GITHUB_TOKEN` has a security limitation: actions performed with it (like pushing commits or tags) **do not trigger other workflows**. This prevents infinite workflow loops but also means our `prepare-release` workflow cannot automatically trigger the `release` workflow when it pushes a tag.
+
+Using a GitHub App token bypasses this limitation because the app is a separate identity from GitHub Actions.
+
+## Setup
+
+1. **GitHub App**: Ensure your GitHub App is installed on this repository with the following permissions:
+   - Repository permissions:
+     - Contents: Read and write
+     - Metadata: Read-only
+
+2. **Generate Token**: Your GitHub App should generate installation access tokens
+
+3. **Add Secret**: Store the token as a repository secret:
+   - Go to: Settings → Secrets and variables → Actions
+   - Name: `GH_APP_TOKEN`
+   - Value: Your GitHub App installation token
+
+## Alternative: Personal Access Token (PAT)
+
+If you don't have a GitHub App, you can use a classic PAT with `repo` scope:
+- Create PAT at: Settings → Developer settings → Personal access tokens → Tokens (classic)
+- Scope required: `repo`
+- Store as `GH_APP_TOKEN` secret
+
+**Note**: PATs are tied to your user account; GitHub Apps are preferred for organizational use.
+
+## Validation
+
+After setup, the `prepare-release` workflow will automatically trigger the `release` workflow when it pushes a tag. You should see both workflows run in sequence without manual intervention.
diff --git a/.github/workflows/prepare-release.yaml b/.github/workflows/prepare-release.yaml
index 41ddc72..91dbe78 100644
--- a/.github/workflows/prepare-release.yaml
+++ b/.github/workflows/prepare-release.yaml
@@ -1,5 +1,8 @@
 name: Prepare Release
 
+# Uses GitHub App token (GH_APP_TOKEN) to trigger the release workflow
+# GITHUB_TOKEN cannot trigger other workflows due to GitHub security policy
+
 on:
   workflow_dispatch:
     inputs:
@@ -24,7 +27,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ secrets.GH_APP_TOKEN }}
 
       - name: Configure git
         run: |