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

Create an installation access token for a GitHub app from your terminal

Creates an installation access token that enables a GitHub App to make authenticated API requests for the app's installation on an organization or individual account. 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!

Why?

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.

Installation

Download ghtoken from the main branch

wget

# Download a file, name it ghtoken then do a checksum
wget -O ghtoken \
    https://raw.githubusercontent.com/Link-/github-app-bash/main/ghtoken && \
    echo "5ee00974ae8d97ec5cfbcd7cb58777787b0107e2e8b84d46fe30a86160d93a2a  ghtoken" | \
    shasum -c - && \
    chmod u+x ./ghtoken

curl

# Download a file, name it ghtoken following [L]ocation redirects, and 
# automatically [C]ontinuing (resuming) a previous file transfer then 
# do a checksum
curl -o ghtoken \
     -O -L -C  - \
     https://raw.githubusercontent.com/Link-/github-app-bash/main/ghtoken && \
     echo "5ee00974ae8d97ec5cfbcd7cb58777787b0107e2e8b84d46fe30a86160d93a2a  ghtoken" | \
     shasum -c - && \
     chmod u+x ./ghtoken

Creating a GitHub App

Follow these steps

Usage

Compatible with GitHub Enterprise Server.

Usage:
  ghtoken generate --key /tmp/private-key.pem --app_id 112233

Options:
  -k | --key <key>  Path to a PEM-encoded certificate and key. (Required)
  -b | --base64_key <key> Base64 encoded PEM certificate and key. (Optional)
  -i | --app_id <id>  GitHub App Id. (Required)
  -d | --duration <duration>  The duration of the token in minutes. (Default = 10)
  -h | --hostname <hostname>  The API URL of GitHub. (Default = api.github.com)
  -j | --install_jwt_cli  Install jwt-cli (dependency) on the current system. (Optional)
  -l | --installation_id <id> GitHub App installation id. (Default = latest id)

Description:
  Generates a JWT signed with the supplied key and fetches an 
  installation token

Examples in the Terminal

Run ghtoken assuming jwt-cli is already installed

# Assumed starting point
.
├── .keys
│   └── private-key.pem
├── README.md
└── ghtoken

1 directory, 3 files

# Run ghtoken
$ ghtoken generate \
    --key ./.keys/private-key.pem \
    --app_id 1122334 \
    | jq

{
  "token": "ghs_g7___MlQiHCYI__________7j1IY2thKXF",
  "expires_at": "2021-04-28T15:53:44Z"
}

Run ghtoken and install jwt-cli

# Assumed starting point
.
├── .keys
│   └── private-key.pem
├── README.md
└── ghtoken

1 directory, 3 files

# Run ghtoken and add --install_jwt_cli
$ ghtoken generate \
    --key ./.keys/private-key.pem \
    --app_id 1122334 \
    --install_jwt_cli \
    | jq

{
  "token": "ghs_8Joht_______________bLCMS___M0EPOhJ",
  "expires_at": "2021-04-28T15:55:32Z"
}

# jwt-cli will be downloaded in the same directory
.
├── .keys
│   └── private-repo-checkout.2021-04-22.private-key.pem
├── README.md
├── ghtoken
└── jwt

Run ghtoken and pass the key as a base64 encoded variable

# Assumed starting point
.
├── README.md
└── ghtoken

1 directory, 2 files

# Run ghtoken and add --install_jwt_cli
$ ghtoken generate \
    --base64_key $(printf "%s" $APP_KEY | base64) \
    --app_id 1122334 \
    --install_jwt_cli \
    | jq

{
  "token": "ghs_GxVel5cp__________DOaCv8eDs___2l94Ta",
  "expires_at": "2021-04-28T16:30:59Z"
}

Run ghtoken with GitHub Enterprise Server

# Assumed starting point
.
├── .keys
│   └── private-key.pem
├── README.md
└── ghtoken

1 directory, 3 files

# Run ghtoken and specify the --hostname
$ ghtoken generate \
    --key ./.keys/private-key.pem \
    --app_id 2233445 \
    --installation_id 5 \
    --install_jwt_cli \
    --hostname "github.example.com" \
    | jq

{
  "token": "v1.bb1___168d_____________1202bb8753b133919",
  "expires_at": "2021-04-28T16:01:05Z"
}

Example in a workflow

1. You need to create a secret to store the applications private key securely (this can be an organization or a repository 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 GitHub.com update the hostname to api.github.com and change the API URL in the testing step.

name: Create access token via GitHub Apps Workflow

on:
  workflow_dispatch:

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

    steps:
    - name: "Download ghtoken"
      run: |
        curl -o ghtoken \
             -O -L -C  - \
             https://raw.githubusercontent.com/Link-/github-app-bash/main/ghtoken && \
             echo "5ee00974ae8d97ec5cfbcd7cb58777787b0107e2e8b84d46fe30a86160d93a2a  ghtoken" | \
             shasum -c - && \
             chmod u+x ./ghtoken
    # 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 ghtoken
    - name: "Create access token"
      id: "create_token"
      run: |
        token=$(./ghtoken generate \
          --base64_key $(printf "%s" "$APP_PRIVATE_KEY" | base64 -w 0) \
          --app_id $APP_ID \
          --install_jwt_cli \
          --hostname "github.example.com" \
          | jq -r ".token")
        echo "::set-output name=token::$token"
      env:
        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 ${{ steps.create_token.outputs.token }}" \
          -H "Accept: application/vnd.github.v3+json" \
          https://github.example.com/api/v3/orgs/<ORGNAME>/repos

Similar projects

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

CLI

• gha-token in Go

Actions

• workflow-application-token-action
• action-github-app-token
• github-app-token-generator