Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



91 Commits

Repository files navigation

GH Token

* _____ _   *_   _______ *  _      *  *    **   *
 / ____| |* | | |__   __|  | |  *       *         🦄  *
| | *__| |_*| | ⭐️ | | ___ | | _____*_ __  *     *
| | |_ |* __ *|    |*|/ _ \| |/ / _ \ '_ \     *   *
| |__| | |  | | *  | | (_)*|   <  __/ | | |  *
 \_____|_|  |_|    |_|\___/|_|\_\___|_| |_|   *

Manage installation access tokens for GitHub apps from your terminal


Creates an installation access token to make authenticated API requests.

Installation tokens expire 1 hour from the time you create them. Using an expired token produces a status code of 401 - Unauthorized, and requires creating a new installation token.

You can use this access token to make pretty much any REST or GraphQL API call the app is authorized to make!

gh-token demo


In order to use GitHub's REST or GraphQL APIs you will need either a Personal Access Token (PAT) or a GitHub App.

PATs are dangerous, they:

  1. have a very wide scope that spans across multiple organizations
  2. never (automatically) expire. They have an indefinite lifetime (or at least until you regenerate them)
  3. cannot be revoked (they're only revoked when a new one is generated)

With an access token generated with a GitHub App you don't have to worry about the concerns above. These tokens have a limited scope and lifetime. Just make sure you handle the token safely (avoid leaking). In the worst case scenario, the token will expire in 1 hour from creation time.


Download as a standalone binary

Download gh-token from the latest release for your platform.

Install as a gh cli extension

You can install gh-token as a gh cli extension!

$ gh extension install Link-/gh-token

# Verify installation
$ gh token

All the commands and parameters remain the same, the only different is you now can use gh token instead of gh-token.

Creating a GitHub App

Follow these steps


Compatible with GitHub Enterprise Server.

   gh-token - Manage GitHub App installation tokens

   gh-token [global options] command [command options] [arguments...]


   generate       Generate a new GitHub App installation token
   revoke         Revoke a GitHub App installation token
   installations  List GitHub App installations
   help, h        Shows a list of commands or help for one command

   --help, -h     show help
   --version, -v  print the version

Examples in the Terminal

Run gh token as a gh CLI extension

$ gh token generate \
    --key ./.keys/private-key.pem \
    --app-id 1122334 \
    --installation-id 5566778

  "token": "ghs_8Joht_______________bLCMS___M0EPOhJ",
  "expires_at": "2023-09-08T18:11:34Z",
  "permissions": {
    "actions": "write",
    "administration": "write",
    "metadata": "read",
    "members": "read",
    "organization_administration": "read"

Run gh token and pass the key as a base64 encoded string

$ gh token generate \
    --base64-key $(printf "%s" $APP_KEY | base64) \
    --app-id 1122334 \
    --installation-id 5566778

  "token": "ghs_8Joht_______________bLCMS___M0EPOhJ",
  "expires_at": "2023-09-08T18:11:34Z",
  "permissions": {
    "actions": "write",
    "administration": "write",
    "metadata": "read",
    "members": "read",
    "organization_administration": "read"

Run gh token with GitHub Enterprise Server

$ gh token generate \
    --base64-key $(printf "%s" $APP_KEY | base64) \
    --app-id 1122334 \
    --installation-id 5566778 \
    --hostname ""

  "token": "ghs_8Joht_______________bLCMS___M0EPOhJ",
  "expires_at": "2023-09-08T18:11:34Z",
  "permissions": {
    "actions": "write",
    "administration": "write",
    "metadata": "read",
    "members": "read",
    "organization_administration": "read"

Fetch list of installations for an app

$ gh token installations \
    --key ./private-key.pem \
    --app-id 2233445
    "id": 1,
    "account": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "",
      "gravatar_id": "",
      "url": "",
      "html_url": "",
      "followers_url": "",
      "following_url": "{/other_user}",
      "gists_url": "{/gist_id}",
      "starred_url": "{/owner}{/repo}",
      "subscriptions_url": "",
      "organizations_url": "",
      "repos_url": "",
      "events_url": "{/privacy}",
      "received_events_url": "",
      "type": "User",
      "site_admin": false
    "access_tokens_url": "",
    "repositories_url": "",
    "html_url": "",
    "app_id": 1,
    "target_id": 1,
    "target_type": "Organization",
    "permissions": {
      "checks": "write",
      "metadata": "read",
      "contents": "read"
    "events": [
    "single_file_name": "config.yaml",
    "has_multiple_single_files": true,
    "single_file_paths": [
    "repository_selection": "selected",
    "created_at": "2017-07-08T16:18:44-04:00",
    "updated_at": "2017-07-08T16:18:44-04:00",
    "app_slug": "github-actions",
    "suspended_at": null,
    "suspended_by": null

Revoke an installation access token

$ gh token revoke \
    --token "v1.bb1___168d_____________1202bb8753b133919" \
    --hostname ""

Successfully revoked installation token

Example in a workflow

Expand to show instructions
  1. You need to create a secret to store the applications private key securely (this can be an organization or a repository secret): Create private key secret

  2. You need to create another secret to store the application id security (same as the step above).

  3. The secrets need to be provided as an environment variable then encoded into base64 as show in the workflow example:

This example is designed to run on GitHub Enterprise Server. To use the same workflow with update the hostname to and change the API URL in the testing step.

name: Create access token via GitHub Apps Workflow


    # The type of runner that the job will run on
    runs-on: [ self-hosted ]

    - name: "Install gh-token"
      run: gh extension install Link-/gh-token
    # Create access token with a GitHub App ID and Key
    # We use the private key stored as a secret and encode it into base64
    # before passing it to gh-token
    - name: "Create access token"
      run: |
        token=$(gh token generate \
          --base64-key $(printf "%s" "$APP_PRIVATE_KEY" | base64 -w 0) \
          --app-id $APP_ID \
          --hostname "" \
          | jq -r ".token")
        echo "token=$token" >> $GITHUB_OUTPUT
        APP_ID: ${{ secrets.APP_ID }}
        APP_PRIVATE_KEY: ${{ secrets.APP_KEY }}
    # To test the token we will use it to fetch the list of repositories
    # belonging to our organization
    - name: "Fetch organization repositories"
      run: |
        curl -X GET \
          -H "Authorization: token $token" \
          -H "Accept: application/vnd.github.v3+json" \

Similar projects

These are not endorsements, just a listing of similar art work