refactor: migrate to machine user PAT auth (closes #27)

.github/workflows/backfill-approvals.yml

@@ -20,15 +20,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Generate GitHub App token
-        uses: actions/create-github-app-token@v1
-        id: app-token
-        with:
-          app-id: ${{ secrets.APP_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-          owner: petry-projects
-
       - name: Backfill approvals
         env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GH_TOKEN: ${{ secrets.DON_PETRY_BOT_PETRY_PROJECT_PAT }}
         run: bash scripts/backfill-approvals.sh "${{ inputs.dry_run }}"

.github/workflows/daily-pr-review-health.yml

@@ -35,14 +35,6 @@ jobs:
       RUN_LIMIT: ${{ inputs.run_limit || '10' }}
 
     steps:
-      - name: Generate GitHub App token
-        uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547  # v1
-        id: app-token
-        with:
-          app-id: ${{ secrets.APP_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-          owner: petry-projects
-
       - name: Checkout agent repo
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
 
@@ -56,9 +48,9 @@ jobs:
 
       - name: Run health check
         env:
-          # App token covers petry-projects scope. If it lacks access to
+          # DON_PETRY_BOT_PETRY_PROJECT_PAT covers petry-projects scope. If it lacks access to
           # don-petry/pr-review-agent, set GH_PAT_WORKFLOWS as fallback.
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GH_TOKEN: ${{ secrets.DON_PETRY_BOT_PETRY_PROJECT_PAT }}
           GH_PAT_FALLBACK: ${{ secrets.GH_PAT_WORKFLOWS }}
         run: bash scripts/pr_review_health.sh
 
@@ -76,7 +68,7 @@ jobs:
         if: env.HAS_FAILURES == 'true' && hashFiles('pr_review_health_report.md') != ''
         uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b  # v7
         with:
-          github-token: ${{ steps.app-token.outputs.token }}
+          github-token: ${{ secrets.DON_PETRY_BOT_PETRY_PROJECT_PAT }}
           script: |
             const fs = require('fs');
             const report = fs.readFileSync('pr_review_health_report.md', 'utf8');

.github/workflows/fix-stuck-prs.yml

@@ -19,16 +19,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Generate GitHub App token
-        uses: actions/create-github-app-token@v1
-        id: app-token
-        with:
-          app-id: ${{ secrets.APP_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-          owner: petry-projects
-
       - name: Fix stuck PRs
         env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GH_TOKEN: ${{ secrets.DON_PETRY_BOT_PETRY_PROJECT_PAT }}
         run: |
           bash scripts/fix-stuck-prs.sh "${{ inputs.dry_run }}"

.github/workflows/pr-review.yml

@@ -52,19 +52,12 @@ jobs:
       MAX_REVIEW_CYCLES: ${{ vars.MAX_REVIEW_CYCLES || '3' }}
 
     steps:
-      - name: Generate GitHub App token
-        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
-        id: app-token
-        with:
-          client-id: ${{ secrets.APP_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-          owner: petry-projects
       - name: Checkout agent repo
         uses: actions/checkout@v5
 
       - name: Install review engine CLIs
         env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GH_TOKEN: ${{ secrets.DON_PETRY_BOT_PETRY_PROJECT_PAT }}
         run: |
           # Primary engine must install successfully; duck engine is best-effort.
           case "$REVIEW_ENGINE" in
@@ -88,14 +81,14 @@ jobs:
 
       - name: Verify auth
         env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GH_TOKEN: ${{ secrets.DON_PETRY_BOT_PETRY_PROJECT_PAT }}
         run: |
           gh auth status
 
       - name: Enumerate candidate PRs
         id: list
         env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GH_TOKEN: ${{ secrets.DON_PETRY_BOT_PETRY_PROJECT_PAT }}
         run: |
           set -euo pipefail
           if [ -n "${PR_URL_OVERRIDE}" ]; then
@@ -114,7 +107,7 @@ jobs:
       - name: Review each PR (cascade)
         if: steps.list.outputs.count != '0'
         env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GH_TOKEN: ${{ secrets.DON_PETRY_BOT_PETRY_PROJECT_PAT }}
           MAX_PRS: ${{ vars.MAX_PRS || '10' }}
           CANDIDATE_LIMIT: ${{ vars.CANDIDATE_LIMIT || '100' }}
         run: |

.gitignore

@@ -3,3 +3,4 @@
 # The actions/checkout post-job sweep trips on unregistered git directories
 # here and emits exit-128 warnings on every run.
 .claude/worktrees/
+.claude/scheduled_tasks.lock

DOCUMENTATION.md

@@ -17,25 +17,19 @@ This repository contains several documentation files describing the PR Review Ag
   - Configuration options
 
 - **[IMPLEMENTATION.md](IMPLEMENTATION.md)** — Technical deep dive
-  - Why GitHub Apps over bot accounts
+  - Authentication: machine user with PAT
   - How PR enumeration works
   - Review pipeline architecture
   - Separation of agent vs infrastructure concerns
   - Rate limiting and fallback logic
   - Stuck PR cleanup explained
 
-## Setting Up GitHub App (If Rebuilding)
-- **[GITHUB_APP_SETUP.md](GITHUB_APP_SETUP.md)** — Step-by-step app creation
-  - Create the GitHub App in your organization
-  - Configure permissions
-  - Install to organization and repos
-  - Generate and store secrets
-  - Test authentication
-
-## Current Implementation Details
-- **App Name:** `petry-projects-pr-review-agent`
-- **App ID:** `3505640`
-- **Installation:** https://github.com/organizations/petry-projects/settings/installations/127129996
+## Setting Up Authentication
+- **[MACHINE_USER_SETUP.md](MACHINE_USER_SETUP.md)** — Machine user and PAT setup
+  - Create machine user account and org team
+  - Configure CODEOWNERS for code owner approvals
+  - Generate fine-grained PAT
+  - Store secrets and rotate tokens
 
 ## File Organization
 
@@ -61,7 +55,7 @@ docs/
 ├── SETUP.md                # Quick start (read first)
 ├── AGENT.md                # Full documentation
 ├── IMPLEMENTATION.md       # Technical details
-├── GITHUB_APP_SETUP.md     # App creation guide
+├── MACHINE_USER_SETUP.md   # Machine user and PAT setup
 └── DOCUMENTATION.md        # This file
 ```
 
@@ -71,7 +65,7 @@ docs/
 → Read [AGENT.md](AGENT.md)
 
 ### I need to set up the agent in a new organization
-→ Follow [GITHUB_APP_SETUP.md](GITHUB_APP_SETUP.md)
+→ Follow [MACHINE_USER_SETUP.md](MACHINE_USER_SETUP.md)
 
 ### The agent isn't working, help!
 → Check [SETUP.md#troubleshooting](SETUP.md#troubleshooting)
@@ -87,20 +81,15 @@ docs/
 
 ## Authentication Method
 
-The agent uses **GitHub Apps** for authentication:
+The agent uses a **machine user account** with a fine-grained PAT:
 
-**Why GitHub Apps?**
-- ✅ No human account required
-- ✅ Auto-expiring tokens (1 hour) — more secure
-- ✅ Fine-grained permissions
-- ✅ Better audit trail
-- ✅ GitHub's recommended approach
+**Why Machine User?**
+- ✅ Can be listed in CODEOWNERS via org team membership
+- ✅ Approvals satisfy `require_code_owner_review` branch protection
+- ✅ Simple PAT-based auth — no JWT generation step needed
+- ✅ Works identically to a human reviewer
 
-**Why not a bot user account?**
-- Would require creating and maintaining a separate GitHub user
-- Long-lived PATs (1 year) with higher security risk
-- Less audit visibility
-- More complex permissions management
+Previously used GitHub Apps, but they cannot be listed in CODEOWNERS (GitHub platform limitation). See [issue #27](https://github.com/don-petry/pr-review-agent/issues/27).
 
 ## Required Secrets
 
@@ -109,9 +98,7 @@ All secrets must be set in the repository (`Settings → Secrets and variables 
 | Secret | Purpose |
 |--------|---------|
 | `CLAUDE_CODE_OAUTH_TOKEN` | Claude Code API access |
-| `APP_ID` | GitHub App ID (3505640) |
-| `APP_INSTALLATION_ID` | App installation in org (127129996) |
-| `APP_PRIVATE_KEY` | GitHub App private key (.pem) |
+| `DON_PETRY_BOT_PETRY_PROJECT_PAT` | Machine user fine-grained PAT |
 | `COPILOT_GITHUB_TOKEN` | Optional fallback engine |
 
 ## Review Workflow
@@ -136,7 +123,7 @@ All secrets must be set in the repository (`Settings → Secrets and variables 
 
 - **Workflow failing to authenticate**: Check [SETUP.md#troubleshooting](SETUP.md#troubleshooting)
 - **Questions about design**: See [IMPLEMENTATION.md](IMPLEMENTATION.md)
-- **Setup instructions**: Follow [GITHUB_APP_SETUP.md](GITHUB_APP_SETUP.md)
+- **Setup instructions**: Follow [MACHINE_USER_SETUP.md](MACHINE_USER_SETUP.md)
 - **Agent capabilities**: Read [AGENT.md](AGENT.md)
 
 ## Document Maintenance