From d5fdd11044c3799c4d7c519955edb53ab550a4b2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 24 Jan 2026 16:52:56 +0000 Subject: [PATCH 1/3] Initial plan From 005b8515e2916ebaaa1380f4ab5e728ff5bee039 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 24 Jan 2026 17:01:44 +0000 Subject: [PATCH 2/3] Document GitHub App authentication for GitHub MCP server Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/reference/tokens.md | 124 +++++++++++++++++++++- docs/src/content/docs/reference/tools.md | 42 ++++++++ 2 files changed, 162 insertions(+), 4 deletions(-) diff --git a/docs/src/content/docs/reference/tokens.md b/docs/src/content/docs/reference/tokens.md index 24710e43ed..b4b0a5d2d0 100644 --- a/docs/src/content/docs/reference/tokens.md +++ b/docs/src/content/docs/reference/tokens.md @@ -20,6 +20,13 @@ For GitHub Agentic Workflows, you only need to create a few **optional** secrets | Any GitHub Projects v2 operations | `GH_AW_PROJECT_GITHUB_TOKEN` | **Required** for `update-project`. Default `GITHUB_TOKEN` cannot access Projects v2 API. | | Isolating Model Context Protocol (MCP) server permissions (advanced optional) | `GH_AW_GITHUB_MCP_SERVER_TOKEN` | Only if you want MCP to use a different token than other jobs. | +> [!TIP] +> GitHub App Authentication (Recommended for Production) +> Instead of PATs, you can use GitHub Apps for enhanced security with short-lived tokens: +> - **Safe outputs**: Configure `app-id` and `private-key` in `safe-outputs.app` +> - **GitHub MCP server**: Configure `app-id` and `private-key` in `tools.github.app`, or import `shared/github-mcp-app.md` +> - See [GitHub App Tokens](#github-app-tokens) and [GitHub App Tokens for GitHub MCP Server](#github-app-tokens-for-github-mcp-server) for details + Create these as **repository secrets in *your* repo**. The easiest way is to use the GitHub Agentic Workflows CLI: ```bash @@ -517,6 +524,113 @@ safe-outputs: create-issue: ``` +### GitHub App Tokens for GitHub MCP Server + +GitHub App tokens can also be used to authenticate the GitHub MCP server, providing the same security benefits as safe-outputs while isolating MCP server permissions. + +**Benefits**: + +- **Isolated permissions**: GitHub MCP server uses separate token from safe-outputs +- **On-demand minting**: Token created at workflow start, minimized exposure +- **Automatic revocation**: Token invalidated at workflow end (even on failure) +- **Permission mapping**: Automatically computed from agent job `permissions` field +- **Dual mode support**: Works with both local (Docker) and remote (hosted) modes + +**Setup**: + +Configure the GitHub App directly in the tools configuration: + +```yaml wrap +permissions: + contents: read + issues: write + pull-requests: read + +tools: + github: + mode: remote # or "local" for Docker-based + toolsets: [repos, issues, pull_requests] + app: + app-id: ${{ vars.APP_ID }} + private-key: ${{ secrets.APP_PRIVATE_KEY }} + owner: "my-org" # Optional: defaults to current repo owner + repositories: ["repo1", "repo2"] # Optional: defaults to current repo only +``` + +**Shared workflow pattern** (recommended): + +Use the provided shared workflow for centralized configuration: + +```yaml wrap +imports: + - shared/github-mcp-app.md # Provides APP_ID and APP_PRIVATE_KEY configuration + +permissions: + contents: read + issues: write + +tools: + github: + toolsets: [repos, issues, pull_requests] +``` + +The shared workflow (`shared/github-mcp-app.md`) expects: +- **Repository Variable**: `APP_ID` - Your GitHub App ID +- **Repository Secret**: `APP_PRIVATE_KEY` - Your GitHub App private key + +**How it works**: + +1. At workflow start, a token minting step (`github-mcp-app-token`) is automatically inserted before MCP server setup +2. The token is minted with permissions matching the agent job's `permissions` field +3. Token is passed to the GitHub MCP server as `GITHUB_MCP_SERVER_TOKEN` +4. At workflow end, the token is automatically invalidated (even on failure) + +**Token precedence**: + +When a GitHub App is configured for the GitHub MCP server: + +1. GitHub App token (highest priority) +2. `tools.github.github-token` (custom token) +3. `GH_AW_GITHUB_MCP_SERVER_TOKEN` (dedicated MCP token) +4. `GH_AW_GITHUB_TOKEN` (general enhanced token) +5. `GITHUB_TOKEN` (default Actions token - not supported in remote mode) + +**Setup repository variables**: + +```bash wrap +# Set GitHub App ID as repository variable +gh variable set APP_ID --body "123456" + +# Set GitHub App private key as repository secret +gh aw secrets set APP_PRIVATE_KEY --value "$(cat path/to/private-key.pem)" +``` + +> [!TIP] +> Dual App Configuration +> You can configure GitHub Apps for both safe-outputs and GitHub MCP server independently: +> +> ```yaml +> tools: +> github: +> app: +> app-id: ${{ vars.MCP_APP_ID }} +> private-key: ${{ secrets.MCP_APP_PRIVATE_KEY }} +> +> safe-outputs: +> app: +> app-id: ${{ vars.SAFE_OUTPUTS_APP_ID }} +> private-key: ${{ secrets.SAFE_OUTPUTS_APP_PRIVATE_KEY }} +> ``` +> +> This allows different permission levels for MCP server operations versus safe output operations. + +> [!NOTE] +> Permission Requirements +> The GitHub App must have sufficient permissions for the operations you need: +> - **Read operations**: Contents: Read, Issues: Read, Pull requests: Read +> - **Write operations**: Match the permissions in your workflow's `permissions` field +> - **Organization access**: If accessing org-owned repositories, the app must be installed at the organization level + ## Token Selection Guide Use this guide to choose the right token for your workflow: @@ -526,11 +640,11 @@ Use this guide to choose the right token for your workflow: | Single repository, basic operations | `GITHUB_TOKEN` (default) | None needed | | Cross-repository operations | `GH_AW_GITHUB_TOKEN` | GitHub App | | Copilot engine workflows | `COPILOT_GITHUB_TOKEN` | None | -| Remote GitHub MCP mode | `GH_AW_GITHUB_TOKEN` | GitHub App | +| Remote GitHub MCP mode | `GH_AW_GITHUB_TOKEN` | GitHub App via `tools.github.app` | +| GitHub MCP server (isolated permissions) | GitHub App via `tools.github.app` | `GH_AW_GITHUB_MCP_SERVER_TOKEN` | | Agent assignments | `GH_AW_AGENT_TOKEN` | `GH_AW_GITHUB_TOKEN` with elevated permissions | | GitHub Projects v2 operations | `GH_AW_PROJECT_GITHUB_TOKEN` | `GH_AW_GITHUB_TOKEN` with Projects permissions | -| Production workflows | GitHub App | `GH_AW_GITHUB_TOKEN` with fine-grained PAT | -| Custom MCP server permissions | `GH_AW_GITHUB_MCP_SERVER_TOKEN` | Use `GH_AW_GITHUB_TOKEN` | +| Production workflows | GitHub App (safe-outputs and MCP) | `GH_AW_GITHUB_TOKEN` with fine-grained PAT | ## Security Best Practices @@ -620,7 +734,9 @@ github-token: ${{ secrets.ISSUE_TOKEN }} **Different permissions per output**: Override at per-output level with different PATs -**Production (most secure)**: Configure GitHub App with `app-id` and `private-key` in safe-outputs +**Production (most secure)**: Configure GitHub App with `app-id` and `private-key` in safe-outputs and/or tools.github + +**GitHub MCP with App**: Import `shared/github-mcp-app.md` and configure `APP_ID` + `APP_PRIVATE_KEY` repository variables ## Troubleshooting diff --git a/docs/src/content/docs/reference/tools.md b/docs/src/content/docs/reference/tools.md index 6fe49fc82f..df0458221d 100644 --- a/docs/src/content/docs/reference/tools.md +++ b/docs/src/content/docs/reference/tools.md @@ -128,6 +128,48 @@ tools: See [Automatic GitHub Lockdown](/gh-aw/guides/security/#automatic-github-lockdown-on-public-repositories) for security implications. +### GitHub App Authentication + +Use GitHub App tokens for enhanced security with short-lived, automatically-revoked credentials: + +```yaml wrap +tools: + github: + mode: remote + toolsets: [repos, issues, pull_requests] + app: + app-id: ${{ vars.APP_ID }} + private-key: ${{ secrets.APP_PRIVATE_KEY }} + owner: "my-org" # Optional: defaults to current repo owner + repositories: ["repo1", "repo2"] # Optional: defaults to current repo only +``` + +**Shared workflow pattern** (recommended): + +```yaml wrap +imports: + - shared/github-mcp-app.md # Centralized GitHub App configuration + +permissions: + contents: read + issues: write + +tools: + github: + toolsets: [repos, issues] +``` + +**Benefits**: +- On-demand token minting at workflow start +- Automatic token revocation at workflow end (even on failure) +- Permissions automatically mapped from agent job `permissions` field +- Works with both local (Docker) and remote (hosted) modes +- Isolated from safe-outputs token configuration + +See [GitHub App Tokens for GitHub MCP Server](/gh-aw/reference/tokens/#github-app-tokens-for-github-mcp-server) for complete setup and configuration details. + +**Token precedence**: GitHub App → `github-token` → `GH_AW_GITHUB_MCP_SERVER_TOKEN` → `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN` + ## Playwright Tool (`playwright:`) Enables containerized browser automation with domain-based access control: From 506b0d90fb70cf984c3e44d3e86aefee1797efb3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 24 Jan 2026 17:03:12 +0000 Subject: [PATCH 3/3] Add GitHub App authentication recommendation to security guide Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/guides/security.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/src/content/docs/guides/security.md b/docs/src/content/docs/guides/security.md index 30583866f0..1c7d1a2af9 100644 --- a/docs/src/content/docs/guides/security.md +++ b/docs/src/content/docs/guides/security.md @@ -347,6 +347,16 @@ tools: - **Automatic and transparent**: Works automatically when `GH_AW_GITHUB_MCP_SERVER_TOKEN` is defined - **Safe by default**: Detection failures default to the most secure setting +> [!TIP] +> GitHub App Authentication (More Secure) +> For enhanced security, consider using GitHub App tokens instead of long-lived PATs: +> - **Short-lived tokens**: Automatically minted at workflow start and revoked at workflow end +> - **Scoped permissions**: Token permissions automatically match your workflow's `permissions` field +> - **No manual rotation**: Eliminates need for PAT expiration management +> - **Better audit trail**: All actions logged under GitHub App identity +> +> Configure via `tools.github.app` or import `shared/github-mcp-app.md`. See [GitHub App Tokens for GitHub MCP Server](/gh-aw/reference/tokens/#github-app-tokens-for-github-mcp-server) for setup details. + See also: [GitHub MCP Tool Configuration](/gh-aw/reference/tools/#github-tools-github) for complete tool configuration options. ### Agent Security and Prompt Injection Defense