GitHub App Installation Token and Authenticating as a GitHub App

[loujr]

GitHub Apps are often refered to as the first class actors when interacting with the API. Unlike their token brethren, they don't require a user and can make requests on their own identity, no service account required. To authenticate against the GitHub API, you will need to generate a GitHub App Installation Token. The name installation token is somewhat misleading because the app is already installed, but it is the secret key used to unlock programatic access as a GitHub App. Generating a GitHub App Installation Token is an efficient way to unlock the maximum aloted API calls to avoid rate limiting and can be used by multiple members of your organization.

These are the necessary steps to create a basic GitHub App and generate a GitHub App Token:

1. Create and Install a GitHub App
2. Create a Json Web Token
3. Exchange the JWT for an Installation Token

Creating and Installing a GitHub App

To authenticate as a GitHub App, you must create and install a GitHub App. For detailed instructions on how to create a GitHub App, check out Creating a GitHub App.

To install a GitHub App, first go to the GitHub Apps settings page. Select your app from the apps listed on the page and then click Install App. For more detailed instructions on how to install a GitHub App, check out Installing GitHub Apps.

In this example, my-awesome-test-app was created for the test organization @the-evil-corporation: the home of the slightly evil test repositories and a nod to Mr. Robot. The following image shows the app settings page after installing my-awesome-test-app. This contains your App ID that goes into your Json Web Token payload.

You will also notice the App ID is also visible. This used to be the primary way for creating an installation token but has been changed to the Client Id.

Generate a Private Key

After you have created and installed your GitHub App, you will need to generate a private key. The private key is a file that allows you to sign json web token requests that are then exchanged for GitHub App Installation tokens. To generate a private key, press the green button labelled Generate a Private Key.

The following key will then appear in the Private Keys section of your GitHub App.

How to Create a Json Web Token

The following script comes from Authenticating with GitHub Apps Using Python. This script will prompt you for the location of your PEM file and your Client ID or you can add these as inline arguments.

Note
Your app_id is found in the app settings page of your GitHub App installation. You can also obtain the app_id from the initial webhook ping after creating you GitHub App.

#!/usr/bin/env python3
import jwt
import time 
import sys
# Get PEM file path
if len(sys.argv) > 1:
    pem = sys.argv[1]
else:
    pem = input("Enter path of private PEM file: ")    
# Get the Client ID
if len(sys.argv) > 2:
    client_id = sys.argv[2]
else:
    client_id = input("Enter your Client ID: ") 
# Open PEM
with open(pem, 'rb') as pem_file:
    signing_key = jwt.jwk_from_pem(pem_file.read())
    
payload = {
    # Issued at time
    'iat': int(time.time()),
    # JWT expiration time (10 minutes maximum)
    'exp': int(time.time()) + 600, 
    # GitHub App's identifier
    'iss': client_id 
}
    
# Create JWT
jwt_instance = jwt.JWT()
encoded_jwt = jwt_instance.encode(payload, signing_key, alg='RS256')
     
print(f"JWT:  ", encoded_jwt)

In this example, this script was saved to a file called jwt_script.py.

python3 jwt_script.py 
Enter path of private PEM file: ~/Downloads/my-awesome-test-app.2023-01-23.private-key.pem
Enter your Client ID: Iv1.06861a3449488b03

JWT:   eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOiAxNjc0NjczNDA3LCAiZXhwIjogMTY3NDY3NDAwNywgImlzcyI6ICIyODQ3NTgifQ.EXc8THvEqqYEmwK-BgY-JIn26ZK9IucWr2tP29fKHrb5H4nMCcKg9bnHxgJUmdbW1GTxWG2hiqMIrR5xzfFWon8zJhbEVx-0pZHlblUZxV2L1iMQDXxBs7kfjOEHvSwFO5-oQDbvCgoOitnfH80P3qTGXujK8SwiGemeUhVQNJl5ETTkt3u_0sxI8jkPWqI-vRZYp6VnPH6JGeN08JIN4spENAi7GLQyKa0yxUeRCliBbJTNSqjMzluhwIv6R9LtheoNmtn-kWoGDJb9VnXw_Fzpa-PSleDNqDCStlJZE3FWZ5RzPAzmc9_m8dpW1S-J_2-C14EQiDyw39nAvdBJ0A

This long string of output is the Json Web Token also called a JWT. Json Web Tokens are exchanged for a GitHub App Installation Token to authenticated against GitHub's API and has a maximum expiration time of ten minutes.

Making the Exchange

To exchange a Json Web Token for a GitHub App Installation token, you need to query the following endpoint:

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/app/installations/:installation_id/access_tokens

In the field YOUR_JWT, put the string you generated from your python script. Your installation_id is found in your organization developer settings under third-party access.

Click the configure button for your app in the app settings page.

On the app settings page your installation id is located in the top URL. In this example URL, the installation id is 33507770:

https://github.com/organizations/the-evil-corporation/settings/installations/33507770

Once you have both the installation_id and your JWT, query the endpoint for the GitHub App Installation Token.

$ curl -i -X POST -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOiAxNjc0NjczNDA3LCAiZXhwIjogMTY3NDY3NDAwNywgImlzcyI6ICIyODQ3NTgifQ.EXc8THvEqqYEmwK-BgY-JIn26ZK9IucWr2tP29fKHrb5H4nMCcKg9bnHxgJUmdbW1GTxWG2hiqMIrR5xzfFWon8zJhbEVx-0pZHlblUZxV2L1iMQDXxBs7kfjOEHvSwFO5-oQDbvCgoOitnfH80P3qTGXujK8SwiGemeUhVQNJl5ETTkt3u_0sxI8jkPWqI-vRZYp6VnPH6JGeN08JIN4spENAi7GLQyKa0yxUeRCliBbJTNSqjMzluhwIv6R9LtheoNmtn-kWoGDJb9VnXw_Fzpa-PSleDNqDCStlJZE3FWZ5RzPAzmc9_m8dpW1S-J_2-C14EQiDyw39nAvdBJ0A" -H "Accept: application/vnd.github+json" https://api.github.com/app/installations/33507770/access_tokens

The installation token appears in the response under token:. GitHub App installation tokens have a one hour expiration time afterwards they must be regenerated. Also notice the prefix for a GitHub App Installation token always begins with ghs_.

{
  "token": "ghs_owui5O5JCSUWHvEQhxTC8kb6kqHH5J3tQiEZ",
  "expires_at": "2023-01-25T20:04:26Z",
  "permissions": {
    "actions": "write",
    "actions_variables": "write",
    "administration": "write",
    "checks": "write",
    "codespaces": "write",
    "codespaces_lifecycle_admin": "write",
    "codespaces_metadata": "read",
    "codespaces_secrets": "write",
    "deployments": "write",
    "discussions": "write",
    "environments": "write",
    "issues": "write",
    "merge_queues": "write",
    "metadata": "read",
    "packages": "write",
    "pages": "write",
    "pull_requests": "write",
    "repository_announcement_banners": "write",
    "repository_hooks": "write",
    "repository_projects": "admin",
    "secrets": "write",
    "secret_scanning_alerts": "write",
    "security_events": "write",
    "statuses": "write",
    "vulnerability_alerts": "write",
    "workflows": "write"
  },
  "repository_selection": "all"
}

Now that you have your GitHub App Installation Token, you can plug it directly into the GitHub API and authenticate as a GitHub App. For this example, the GitHub App Installation Token was used to list commits in Repo-Test555. You can find out more about this endpoint in List Commit Comments for a Repository. The added -i flag in the request shows additional information regarding the request that was made.

curl -i -H "Accept: application/vnd.github+json" -H "Authorization: Bearer ghs_owui5O5JCSUWHvEQhxTC8kb6kqHH5J3tQiEZ" -H "X-GitHub-Api-Version: 2022-11-28"   https://api.github.com/repos/the-evil-corporation/repo-test555/comments 

The following request was successful. If you look at the x-github-ratelimit-limit header in the response body, the API rate limit is 15000 calls per hour. This shows that this was a successful authenticated request against GitHub's API as a GitHub App.

HTTP/2 200 
server: GitHub.com
date: Mon, 06 Feb 2023 21:07:52 GMT
content-type: application/json; charset=utf-8
content-length: 7026
cache-control: private, max-age=60, s-maxage=60
vary: Accept, Authorization, Cookie, X-GitHub-OTP
etag: "3f26077d6345f8c7531d51f086132a14a15c5d4e4725d22d83ad843619c87562"
x-github-media-type: github.v3; format=json
x-github-api-version-selected: 2022-11-28
x-ratelimit-limit: 15000
x-ratelimit-remaining: 14998
x-ratelimit-reset: 1675720841
x-ratelimit-used: 2
x-ratelimit-resource: core
access-control-expose-headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
access-control-allow-origin: *
strict-transport-security: max-age=31536000; includeSubdomains; preload
x-frame-options: deny
x-content-type-options: nosniff
x-xss-protection: 0
referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
content-security-policy: default-src 'none'
vary: Accept-Encoding, Accept, X-Requested-With
x-github-request-id: F423:0566:F421F0:1F247FD:63E16C27

Finally, listed is the comments on the test repository's commits.

    },
    "position": null,
    "line": null,
    "path": null,
    "commit_id": "c9bc90a4568c2430a7dd868d657eb7ea31115162",
    "created_at": "2022-08-22T20:43:10Z",
    "updated_at": "2022-08-22T20:43:10Z",
    "author_association": "COLLABORATOR",
    "body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
    "reactions": {
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/comments/81875426/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    }

If you have made it this far, congratulations on creating your first GitHub App token 🎉

For a collection of available endpoints for connecting with GitHub's API, please check out Endpoints Available for GitHub Apps.

[SiyaaJhawar]

Hi i am getting error while reading pem file pls help

[bobrossthepainter]

Hi @loujr,
thank you for the great write-up!
I made the discovery, that even though my GitHub-App has the "write" permission for packages, I'm not able to pull any OCI (container / docker) images from GitHub Packages with a valid installation token. I tried this with a GitHub Enterprise Installation (v3.6.7).
Are installation tokens not supported for the authentication with the GitHub packages container registry?
Regards
Robert

[loujr]

Hello Robert!

Installation tokens are not supported with the GitHub packages container registry. Packages don’t support fine grained permissions which is what Apps and their installations use.

Regards,

Lou

[bobrossthepainter]

Thank you for the info! :)
Do you know about another possibility to authenticate against GitHub packages besides a PAT?

[loujr]

Currently the only way is to Authenticate using a PAT. If you are using GitHub Actions you can use github_token. We currently have a feature request to expand these options. However, I do not have a timeline as to if or when this will be pushed into production.

[alex-linx]

@loujr Hi, is this still the case for pulling images from containers registry? We wanted to use a github app token for use with kubernetes imagePullSecret

[Jegan307]

I can able to retrieve response as below

{
"token": "ghs_CBhTdfUl6Egw0bNMaHsa7vH0Df0dz3QV4Ez",
"expires_at": "2023-03-17T13:13:11Z",
"permissions": {
"administration": "write",
"checks": "write",
"contents": "write",
"metadata": "read",
"pull_requests": "write",
"statuses": "write"
},
"repository_selection": "selected"
}

but expires_at time in different time zone. because based on the time zone I need to generate new Token.

Thanks in Advance !

[cheng-hsin]

❤️

[wutania]

Hello! I am having issues with accessing images with URLs like https://github.com/`RepoOwner`/`RepoName`/assets/xxxx/yyyyyy type files with the Github App Installation Token, even though the GitHub App is installed on the repository where the we uploaded an image to the issue (where the App has read/write access to issues).

We can however access the image URL by passing a personal access token of a person that has read access to this issue.

Is this an intended behavior? Or is this a bug? Thanks!

[Mgmdrzx]

Espero que alguien te haya ayudado a recuperarlo yo porque tampoco tengo ni idea que estoy de novato por aquí....