Document safe-outputs GitHub App permission narrowing

[Copilot]

Safe outputs with GitHub Apps automatically narrow permissions per-job and revoke tokens at job end, but this critical security behavior was undocumented. Additionally, implicit permission requirements (e.g., create-pull-request requiring issues: write for fallback) were not explained.

Changes

GitHub App token behavior — Documented per-job minting, automatic permission narrowing to match job's permissions: block, and auto-revocation via DELETE /installation/token. Explains why org-wide Apps with broad permissions are safe.

Fallback field documentation — Clarified that create-pull-request defaults to fallback-as-issue: true (requires issues: write), and setting it to false reduces permissions to contents: write + pull-requests: write.

Token documentation generalization — Updated tokens reference to explain that per-job permission narrowing applies to all GitHub App configurations, not just MCP server tokens.

Frontmatter reference — Added notes about automatic per-job narrowing and token auto-revocation in safe-outputs and app configuration sections.

Example

safe-outputs:
  app:
    app-id: ${{ vars.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}
  create-pull-request:
    fallback-as-issue: false  # Avoids issues: write requirement

Per-job token minted with only contents: write + pull-requests: write, even if App has broader permissions configured.

Screenshot

Documentation explains the GitHub App security model with per-job narrowing and auto-revocation.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Docs: safe-outputs.app: permission narrowing + (?) implicit permission inflation</issue_title>
<issue_description>Created w Copilot to poke around the codebase a bit to see how things worked under the hood for token minting. Less sure about the second point, might've missed something when looking around.

Two related but distinct issues with safe-outputs.app: token handling.

---

1. Undocumented permission narrowing

safe-outputs.app: automatically narrows minted GitHub App tokens per-job, but this is undocumented. The only mention of permission narrowing is under GH_AW_GITHUB_MCP_SERVER_TOKEN, which describes MCP server tokens — not safe-outputs tokens.

Users configuring app: for cross-repo operations have no way to know from the docs that:

1. Each job mints its own independently-scoped token via actions/create-github-app-token with explicit permission-* fields
2. Token permissions are narrowed to match the job's permissions: block
3. Tokens are explicitly revoked at job end via DELETE /installation/token
4. A shared org-wide GitHub App is safe to use because tokens are narrowed per-job

Relevant code

• buildGitHubAppTokenMintStep() — generates per-job actions/create-github-app-token step with permission-* fields
• convertPermissionsToAppTokenFields() — maps job permissions to action inputs
• buildGitHubAppTokenInvalidationStep() — revokes token at job end

Docs to update

• Safe Outputs — app: — Document the per-job narrowing, auto-revocation, and that a broadly-permissioned App is safe due to per-job scoping.
• Tokens — Generalize the "permissions matching" statement to cover all app: configs, not just MCP server tokens.
• Frontmatter Reference — Note that permissions are auto-narrowed per-job and tokens are auto-revoked.

---

2. create-pull-request hardcodes issues: write

For a workflow that only configures create-pull-request:, the compiled safe_outputs job mints a token with: permission-contents: write, permission-issues: write, permission-pull-requests: write.

The issues: write is hardcoded in the create-pull-request handler — see compiler_safe_outputs_job.go L201-202 (ContentsWriteIssuesWritePRWrite). This is because create-pull-request falls back to creating an issue if PR creation fails (e.g., org settings block it).

This is surprising when you expect only contents: write + pull-requests: write for a PR-only workflow — and there's no way to opt out.

Suggestions

• Document which permissions each safe output type implicitly adds (a table in the Safe Outputs docs would help)
• Consider making the fallback-to-issue opt-out-able, so users who don't need it can avoid issues: write

Relevant code

• Per-handler permission merging — each safe output type adds its required permissions
  </issue_description>

<agent_instructions>Review the description and comments and update documentation.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@pelikhan good one. @pelikhan Adding field: https://github.com//pull/15276 @pelikhan Note that because the safe_outputs run in the same job, they will have the union of require permissions.

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

• Fixes Docs: safe-outputs.app: permission narrowing + (?) implicit permission inflation #15274

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[pelikhan]

@copilot remove detailled table

[Copilot]

Done in commit e6d3075. Removed the detailed permissions table while keeping the GitHub App token documentation explaining per-job narrowing and auto-revocation.

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro preview (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

Pull request overview

This PR documents the previously undocumented security model for GitHub App tokens in safe outputs, specifically explaining per-job token narrowing and auto-revocation. It also clarifies the fallback-as-issue field's permission implications for create-pull-request.

Changes:

• Documented GitHub App per-job token minting, automatic permission narrowing, and auto-revocation behavior
• Explained fallback-as-issue field and its impact on permission requirements (defaulting to true requires issues: write, setting to false only requires contents: write + pull-requests: write)
• Generalized token documentation to cover all GitHub App configurations, not just MCP server tokens

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
docs/src/content/docs/reference/tokens.mdx	Added explanation of per-job permission narrowing for GitHub App tokens and cross-reference to safe-outputs documentation
docs/src/content/docs/reference/safe-outputs.md	Added comprehensive "How GitHub App Tokens Work" section explaining per-job minting, permission narrowing, auto-revocation, and safe shared configuration; updated create-pull-request documentation to explain fallback-as-issue field and permission implications
docs/src/content/docs/reference/frontmatter-full.md	Updated comments for safe-outputs and app configuration sections to document automatic per-job narrowing and token auto-revocation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.