From cb9c14344f8b83e8a9b9ee073ca87094c5e18a60 Mon Sep 17 00:00:00 2001
From: GitHub Actions <noreply@github.com>
Date: Sat, 24 Jan 2026 17:58:56 +0000
Subject: [PATCH] docs: add GitHub App token minting for GitHub MCP server

Document the new GitHub App authentication feature for GitHub MCP server
added in PR #11660. This feature enables short-lived, automatically-revoked
tokens with automatic permission mapping from job permissions.

Key additions to tools reference:
- New "GitHub App Authentication" section
- Configuration with app-id and private-key
- Benefits: short-lived tokens, auto-revocation, no PAT rotation
- Setup instructions and shared workflow pattern
- Token precedence and permission mapping documentation

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 docs/src/content/docs/reference/tools.md | 82 ++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/docs/src/content/docs/reference/tools.md b/docs/src/content/docs/reference/tools.md
index 6fe49fc82f..3d42afadd6 100644
--- a/docs/src/content/docs/reference/tools.md
+++ b/docs/src/content/docs/reference/tools.md
@@ -128,6 +128,88 @@ tools:
 
 See [Automatic GitHub Lockdown](/gh-aw/guides/security/#automatic-github-lockdown-on-public-repositories) for security implications.
 
+### GitHub App Authentication
+
+Configure GitHub App token minting for enhanced security with short-lived, automatically-revoked credentials:
+
+```yaml wrap
+tools:
+  github:
+    toolsets: [repos, issues, pull_requests]
+    app:
+      app-id: ${{ vars.APP_ID }}
+      private-key: ${{ secrets.APP_PRIVATE_KEY }}
+      repositories:  # Optional: defaults to current repo only
+        - "repo1"
+        - "repo2"
+```
+
+**Benefits**:
+
+- **Short-lived tokens**: Created at job start, automatically revoked at job end (even on failure)
+- **Automatic permissions**: Compiler calculates required permissions from job `permissions` field
+- **No PAT rotation**: Eliminates manual token management
+- **Audit trail**: Actions logged under GitHub App identity
+
+**How it works**:
+
+1. Token minted at workflow start with permissions matching the job's `permissions` field
+2. Token overrides `github-token` and default token fallback
+3. Token automatically invalidated at workflow end using `if: always()` condition
+4. Works with both local (Docker) and remote (hosted) GitHub MCP modes
+
+**Setup**:
+
+Repository variables and secrets needed:
+- `APP_ID` - GitHub App ID (repository variable)
+- `APP_PRIVATE_KEY` - GitHub App private key (repository secret)
+
+```bash wrap
+gh variable set APP_ID --body "YOUR_APP_ID"
+gh secret set APP_PRIVATE_KEY < app-private-key.pem
+```
+
+**Shared workflow pattern** (recommended):
+
+Create a shared workflow for reusable GitHub App configuration:
+
+```yaml wrap
+# .github/aw/shared/github-mcp-app.md
+---
+tools:
+  github:
+    app:
+      app-id: ${{ vars.APP_ID }}
+      private-key: ${{ secrets.APP_PRIVATE_KEY }}
+---
+```
+
+Import in workflows:
+
+```yaml wrap
+# .github/aw/my-workflow.md
+---
+imports:
+  - shared/github-mcp-app.md
+permissions:
+  contents: read
+  issues: write
+tools:
+  github:
+    toolsets: [repos, issues]
+---
+
+# Workflow uses app token automatically
+```
+
+**Permissions**: The minted token receives permissions matching your job's `permissions` configuration. For example, `contents: read, issues: write` grants the token read access to repository contents and write access to issues.
+
+> [!NOTE]
+> Token precedence
+> When GitHub App is configured, the app token takes precedence over all other tokens: app token → `github-token` → `GH_AW_GITHUB_MCP_SERVER_TOKEN` → `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN`
+
+See [GitHub Tokens](/gh-aw/reference/tokens/#github-app-tokens) for complete authentication options and [Safe Outputs](/gh-aw/reference/safe-outputs/) for safe-outputs-specific app configuration.
+
 ## Playwright Tool (`playwright:`)
 
 Enables containerized browser automation with domain-based access control: