actions/create-github-app-token, from App setup to the errors

By Kaveh Alemi·Latchkey

actions/create-github-app-token exchanges a GitHub App's client ID and private key for an installation access token inside the job. Unlike GITHUB_TOKEN it can reach other repositories and its pushes start workflows; unlike a personal access token it belongs to no person, expires after one hour and is revoked when the job ends.

Three problems send people to actions/create-github-app-token. A workflow pushes a commit or opens a pull request and none of the checks run. A job needs to read or write a second repository and GITHUB_TOKEN cannot see it. Or a personal access token that belongs to someone who has left is holding a pipeline together.

An App installation token answers all three, at the cost of a one-time setup: register an App, install it, and store its client ID and private key. After that, the step's inputs decide which repositories the token reaches and which permissions it carries, and the token stops working an hour after it was minted.

GITHUB_TOKEN, a personal access token or an App token

GITHUB_TOKEN is the right default and should stay so for anything inside the workflow's own repository that does not need to start another workflow. The other two exist for the cases it refuses.

A personal access token covers both, but it acts as a person: every commit and pull request carries their name, it reaches what they can reach, and it stops working when they leave. An App token acts as <app-slug>[bot], reaches only the repositories the App is installed on, with only the permissions the installation was granted, and lives for an hour.

Set up the App once

GitHub's own guide has four steps. Do them in order; the last one is the easy one to miss. Register a GitHub App and give it only the repository permissions your workflows need, for example Contents and Pull requests at read and write. Store its client ID as an Actions variable; the client ID is a different value from the numeric App ID. Generate a private key and store the whole file as a secret, including the -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- lines. Then install the App on the account and select the repositories it may touch.

Registering an App does not install it, even an App private to your organization. Until it is installed, the installation lookup the action makes returns Not Found.

on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - id: app
        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
        with:
          client-id: ${{ vars.APP_CLIENT_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
      - run: gh api "repos/$GITHUB_REPOSITORY" --jq .full_name
        env:
          GH_TOKEN: ${{ steps.app.outputs.token }}

Inputs, and how they decide what the token reaches

private-key and one of client-id or app-id are the only values you must pass. The rest decide the token's reach. With neither owner nor repositories, the token covers the current repository. With owner alone, it covers every repository in that owner's installation. With repositories, it covers exactly those, and since v3.2.0 an entry may be written owner/repo as long as the owner matches. enterprise is separate: it targets an enterprise installation, can call enterprise APIs only, and cannot be combined with the other two.

By default the token inherits every permission the installation has. The permission-* inputs narrow it: prefix the permission name, so pull-requests becomes permission-pull-requests: write. Asking for a permission the installation was never granted fails the step instead of quietly giving you less.

A token for another repository, with two permissions

The common shape is a job in one repository that opens a pull request in another. Scope the token to the target repository, ask for the two permissions the job uses, check the target out with that token, and pass the same token to peter-evans/create-pull-request. Because the push and the pull request come from the App, the target repository's push and pull_request workflows run on them.

If the job commits with plain git instead, set the committer to the App's bot so the commit is attributed to it: the name is <app-slug>[bot] and the email is <user-id>+<app-slug>[bot]@users.noreply.github.com, where the user ID comes from gh api /users/<app-slug>[bot] --jq .id. The app-slug output gives you the first half.

jobs:
  bump:
    runs-on: ubuntu-latest
    steps:
      - id: app
        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
        with:
          client-id: ${{ vars.APP_CLIENT_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          repositories: deploy-config
          permission-contents: write
          permission-pull-requests: write
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          repository: ${{ github.repository_owner }}/deploy-config
          token: ${{ steps.app.outputs.token }}
          persist-credentials: false
      - run: ./scripts/bump-image-tag.sh "$GITHUB_SHA"
      - uses: peter-evans/create-pull-request@3ffccacd46053766916f087ce41d627c0b8cf2d1 # v8.1.3
        with:
          token: ${{ steps.app.outputs.token }}
          branch: bot/bump-image
          title: Bump the image tag
          sign-commits: true

One hour, then 401

Installation tokens expire one hour after they are created. GitHub's REST reference says a call with an expired token gets 401 Unauthorized and needs a new token; there is no way to extend one. A job that mints the token in its first step and pushes after a 70-minute build fails at the push. Mint the token immediately before the step that uses it, or mint a second one later in the job.

The action also revokes the token in its post step, so it cannot be handed to another job through outputs: each job mints its own. skip-token-revoke: true turns revocation off, and there is rarely a reason to. The token is masked in the log either way.

Empty keys, missing installs and expired tokens

The first, fifth and sixth messages are verbatim from the action's source at v3.3.0, the second to fourth from issues #76, #153 and #235 on its repository, and the 401 from GitHub's REST reference. When the token is minted but a later API call returns 403 or 404, the cause is the installation's permissions or repository list, and the diagnosis is the same as for GITHUB_TOKEN cannot access another repository.

Moving from v1 or v2 to v3

v3 still accepts app-id, with a deprecation warning, so moving from v1 or v2 is a version bump plus, on proxied self-hosted runners, one environment variable.

Key takeaways

• An App token reaches other repositories and its pushes and pull requests start workflows; GITHUB_TOKEN does neither.
• Register, store the client ID and the whole key, then install: a registered but uninstalled App returns Not Found.
• No target inputs means the current repository; owner alone means the whole installation; permission-* narrows it.
• The token expires after one hour and is revoked in the post step, so mint it per job, close to where it is used.

Frequently asked questions

Related guides

References

• actions/create-github-app-token README (read 2026-11-12)
• actions/create-github-app-token action.yml at v3.3.0
• Making authenticated API requests with a GitHub App in a GitHub Actions workflow
• REST API: create an installation access token for an app
• Triggering a workflow from a workflow, docs.github.com
• GitHub Actions documentation