create-github-app-token

The scope of the generated token is determined by the combination of inputs provided. The action uses the POST /app/installations/{installation_id}/access_tokens endpoint to create the token.

Important Lifecycle Note: Unless skip-token-revoke is set to true, the token is revoked at the end of the job. This means you cannot pass the token to a different job via outputs unless you disable revocation.

You can scope the generated token to specific owners, specific repositories within an owner, or an entire enterprise installation using the following inputs:

• owner: The account (user or organization) that owns the installation.
• repositories: A multi-line string or comma-separated list of repository names to scope the token to.
• enterprise: The slug of the GitHub Enterprise.
• github-api-url: The API URL for GitHub Enterprise Server (GHES).

To use this action, you must first register a GitHub App and configure your repository with the necessary credentials:

1. Register a new GitHub App via GitHub's documentation.
2. Store the App's Client ID in your repository variables (e.g., APP_CLIENT_ID).
3. Store the App's private key in your repository secrets (e.g., APP_PRIVATE_KEY).

IMPORTANT

Installation access tokens expire after 1 hour. For long-running processes, consider alternative approaches.

When using the generated token with actions/checkout, you should set persist-credentials: false to ensure the GITHUB_TOKEN is not persisted in the repository's local git configuration, which helps maintain security.

- uses: actions/create-github-app-token@v3
  id: app-token
  with:
    client-id: ${{ vars.APP_CLIENT_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}
- uses: actions/checkout@v6
  with:
    token: ${{ steps.app-token.outputs.token }}
    ref: ${{ github.head_ref }}
    persist-credentials: false

This action uses Node.js native proxy support. To ensure HTTP_PROXY or HTTPS_PROXY environment variables are honored, you must set NODE_USE_ENV_PROXY: "1" on the action step. You can also use NO_PROXY for bypass rules.

- uses: actions/create-github-app-token@v3
  id: app-token
  env:
    HTTPS_PROXY: http://proxy.example.com:8080
    NO_PROXY: github.example.com
    NODE_USE_ENV_PROXY: "1"
  with:
    client-id: ${{ vars.APP_CLIENT_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}

If your GitHub App private key is stored as a Base64 encoded secret, you must decode it before passing it to the private-key input. Use the following pattern to decode the key, mask it to prevent accidental logging, and pass it to the action via $GITHUB_OUTPUT.

steps:
  - name: Decode the GitHub App Private Key
    id: decode
    run: |
      private_key=$(echo "${{ secrets.APP_PRIVATE_KEY }}" | base64 -d | awk 'BEGIN {ORS="\\n"} {print}' | head -c -2) &> /dev/null
      echo "::add-mask::$private_key"
      echo "private-key=$private_key" >> "$GITHUB_OUTPUT"
  - name: Generate GitHub App Token
    id: app-token
    uses: actions/create-github-app-token@v3
    with:
      client-id: ${{ vars.APP_CLIENT_ID }}
      private-key: ${{ steps.decode.outputs.private-key }}

Use this configuration to generate a token scoped to the repository where the workflow is running. The token is available via the app-token step output.

- uses: actions/create-github-app-token@v3
  id: app-token
  with:
    client-id: ${{ vars.APP_CLIENT_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}

name: Run tests on staging
on:
  push:
    branches:
      - main

jobs:
  hello-world:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/create-github-app-token@v3
        id: app-token
        with:
          client-id: ${{ vars.APP_CLIENT_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
      - uses: ./actions/staging-tests
        with:
          token: ${{ steps.app-token.outputs.token }}

You can request specific permissions for the generated token by using the permission-<scope> input (e.g., permission-issues: write).

NOTE

The selected permissions must already be granted to the GitHub App installation. If you request a permission that the installation does not have, the action will return an error.

- uses: actions/create-github-app-token@v3
  id: app-token
  with:
    client-id: ${{ vars.APP_CLIENT_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}
    owner: ${{ github.repository_owner }}
    permission-issues: write

The action provides the following outputs which can be used in subsequent steps of your workflow:

• token: The generated GitHub App installation access token.
• installation-id: The GitHub App installation ID.
• app-slug: The slug of the GitHub App.