Docs: `safe-outputs.app:` permission narrowing + (?) implicit permission inflation

[Yoyokrazy]

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

[pelikhan]

good one.

[pelikhan]

Adding field: #15276

[pelikhan]

Note that because the safe_outputs run in the same job, they will have the union of require permissions.

[Yoyokrazy]

Thanks for the response. The tools and safe-outputs fields of our md file are as follows, does anything look glaringly wrong?

The goal was to give read access to a broader range of repos, to investigate all details of a closed feature request, without giving write access. so in that, we gave app permissions with read-only to those repos, and then only gave create pull request perms via safe outputs field.

permissions:
    contents: read
    issues: read
    pull-requests: read
    actions: read
timeout-minutes: 15
tools:
    github:
        toolsets: [repos, issues, pull_requests]
        read-only: true
        app:
            app-id: ${{ secrets.asdfasdf-id }}
            private-key: ${{ secrets.asdfasdf-pkey }}
            owner: 'microsoft'
            repositories: ['vscode', 'vscode-copilot-chat', 'vscode-docs']
    bash: ['gh repo clone:*']
    edit:
safe-outputs:
    app:
        app-id: ${{ secrets.asdfasdf-id }}
        private-key: ${{ secrets.asdfasdf-pkey }}
        owner: 'microsoft'
        repositories: ['vscode-docs']
    create-pull-request:
        draft: true
        base-branch: vnext
        target-repo: 'microsoft/vscode-docs'
        allowed-repos: ['microsoft/vscode-docs']
        reviewers: [ntrogh]

[pelikhan]

@Yoyokrazy looks about right. Added safe-outputs.create-pull-request.fallback-as-input: false in next release.

[pelikhan]

If you have dought, it's useful to go down to the compiled .lock.yml which contains the "truth".