docs: Document GitHub App token implementation and clarify OIDC distinction

[Copilot]

Documentation lacked technical details on how GitHub App authentication works in generated lock files and conflated it with OpenID Connect authentication.

Changes

Added Technical Implementation Details (tokens.md)

• Documents 3-phase lifecycle: token minting via actions/create-github-app-token, usage in safe outputs, automatic invalidation via DELETE /installation/token
• Explains permission auto-computation from safe output types (e.g., permission-issues: write for create-issue)
• Documents step ID convention (steps.app-token.outputs.token)

Clarified OIDC vs GitHub App Tokens

• OIDC (id-token: write): External cloud provider authentication (AWS/GCP/Azure)
• GitHub App tokens: GitHub API operations via safe-outputs.app configuration
• Added cross-references between permissions.md and tokens.md

Enhanced Safe Outputs Reference (safe-outputs.md)

• Links GitHub App configuration to comprehensive token documentation
• Explains automatic token invalidation behavior

Example

safe-outputs:
  app:
    app-id: ${{ vars.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}
  create-issue:  # Token auto-scoped with permission-issues: write

Generated lock files mint tokens at job start, use them for GitHub API calls, and revoke them at job end (even on failure).

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 grep -l id-token: write k.yml /usr/local/.ghcup/bin/grep (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 build grep -l safe-outputs: ies.md ep ripts/generate-ash ocumentation wit-c k/node_modules/.node install.js grep -l safe-outputs: -analysis-strategies.md nfig/composer/vendor/bin/grep id-token: write s-report.md ndor/bin/grep grep (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)

Original prompt

Review the usage if the app authentication / openid / getToken usage in generated lock files, and ensure documentation on token is up to date

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

---

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