Installation Token Generation

When to Use This Skill

Installation tokens authenticate your GitHub App for specific repository operations. They enable:

• Cross-repository automation - Operate across multiple repositories
• Organization-wide workflows - Access all repositories in your organization
• Automated processes - No user interaction required
• Scoped permissions - Limit access to specific repositories
• Short-lived credentials - 1-hour expiration for security

Token Limitations

• 1-hour expiration (automatic refresh available)
• Requires GitHub App installation on target repositories
• Permissions limited to app's configured scope
• Cannot perform user-attributed actions

Implementation

Installation tokens provide automated, secure access to repositories where your GitHub App is installed. Use installation tokens for GitHub Actions workflows, CI/CD automation, and cross-repository operations.

When to Use Installation Tokens

Installation tokens are for automated repository operations. Use JWT for app-level operations and OAuth for user-attributed actions.

Overview

Installation tokens authenticate your GitHub App for specific repository operations. They enable:

• Cross-repository automation - Operate across multiple repositories
• Organization-wide workflows - Access all repositories in your organization
• Automated processes - No user interaction required
• Scoped permissions - Limit access to specific repositories
• Short-lived credentials - 1-hour expiration for security

Token Limitations

• 1-hour expiration (automatic refresh available)
• Requires GitHub App installation on target repositories
• Permissions limited to app's configured scope
• Cannot perform user-attributed actions

Token Scoping Decision

See examples.md for detailed code examples.

Basic Usage

Single Repository Token

Generate a token scoped to the current repository.

See examples.md for detailed code examples.

Output: Token accessible via ${{ steps.app_token.outputs.token }}

Scope: Current repository only (where workflow runs)

Organization-Scoped Tokens

Generate tokens with access to all repositories where the app is installed.

See examples.md for detailed code examples.

Owner Parameter is Critical

• With owner: Access all repositories in the organization
• Without owner: Access only the current repository
• Must match your GitHub organization name exactly

Use cases:

• Discovery workflows (list all repositories)
• Cross-repository automation
• Organization-wide policy enforcement
• Dynamic repository targeting

Repository-Scoped Tokens

Limit token access to specific repositories for enhanced security.

See examples.md for detailed code examples.

Security Best Practice

Use repository-scoped tokens when you know exactly which repositories need access. This follows the principle of least privilege.

Benefits:

• Explicit allow list of repositories
• Reduces blast radius if token is compromised
• Clear audit trail of intended access
• Enforces access boundaries

When NOT to Use Installation Tokens

Don't Use Installation Tokens For

• User-attributed actions - Use OAuth instead
• App-level operations - Use JWT (list installations, get app manifest)
• Public repository read-only access - Use GITHUB_TOKEN if simpler
• Personal repository access - Use OAuth for user's private repos
• Operations requiring user identity - Actions appear as "bot" with installation tokens

Next Steps

• Workflow Patterns - Cross-repository automation patterns
• Use Cases - Real-world implementation examples
• Lifecycle and Security - Token management and security best practices

Overview

Installation tokens authenticate your GitHub App for specific repository operations. They enable:

• Cross-repository automation - Operate across multiple repositories
• Organization-wide workflows - Access all repositories in your organization
• Automated processes - No user interaction required
• Scoped permissions - Limit access to specific repositories
• Short-lived credentials - 1-hour expiration for security

Token Limitations

• 1-hour expiration (automatic refresh available)
• Requires GitHub App installation on target repositories
• Permissions limited to app's configured scope
• Cannot perform user-attributed actions

Token Scoping Decision

See examples.md for detailed code examples.

Basic Usage

Single Repository Token

Generate a token scoped to the current repository.

See examples.md for detailed code examples.

Output: Token accessible via ${{ steps.app_token.outputs.token }}

Scope: Current repository only (where workflow runs)

Organization-Scoped Tokens

Generate tokens with access to all repositories where the app is installed.

See examples.md for detailed code examples.

Owner Parameter is Critical

• With owner: Access all repositories in the organization
• Without owner: Access only the current repository
• Must match your GitHub organization name exactly

Use cases:

• Discovery workflows (list all repositories)
• Cross-repository automation
• Organization-wide policy enforcement
• Dynamic repository targeting

Repository-Scoped Tokens

Limit token access to specific repositories for enhanced security.

See examples.md for detailed code examples.

Security Best Practice

Use repository-scoped tokens when you know exactly which repositories need access. This follows the principle of least privilege.

Benefits:

• Explicit allow list of repositories
• Reduces blast radius if token is compromised
• Clear audit trail of intended access
• Enforces access boundaries

When NOT to Use Installation Tokens

Don't Use Installation Tokens For

• User-attributed actions - Use OAuth instead
• App-level operations - Use JWT (list installations, get app manifest)
• Public repository read-only access - Use GITHUB_TOKEN if simpler
• Personal repository access - Use OAuth for user's private repos
• Operations requiring user identity - Actions appear as "bot" with installation tokens

Next Steps

• Workflow Patterns - Cross-repository automation patterns
• Use Cases - Real-world implementation examples
• Lifecycle and Security - Token management and security best practices

Examples

See examples.md for code examples.

Full Reference

See reference.md for complete documentation.

References

• Source Documentation
• AEL Patterns