How to Create a Repo-scoped Github Access Token in an Organization Account

Evidently, the only way to trigger a Github Action from a third-party (e.g. headless CMS) is via a repository_dispatch event. The only tricky part is that the request must be authenticated by an Access Token.

curl \
-X POST \
-H "Authorization: token {ACCESS TOKEN}"
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/{org}/{repo}/dispatches \
-d '{"event_type":"rebuild_static_site","client_payload":{"post_id":54}}}'

The problem with personal Access Tokens is that, by default, they give access to every repo you have access to. When working on private repos in organizational accounts at work, this is a non-starter!

Unfortunately, the only way to generate an Access Token scoped to a repository (public or private) in your organization is via a Github App. Hopefully this won't always be the case, but for now you can follow these steps to set one up in a few minutes:

Step 1: Create a new Github App

github.com/settings/apps/new

Give it a short unique name (max length is 34 characters).

Uncheck "Expire user authorization tokens" and leave "Callback URL" blank

Screenshot of token expiration checkbox

Uncheck "Active" checkbox under "Webhook" and leave "Webhook URL" blank

Screenshot of active webhook checkbox

Under "Repository Permissions" find "Contents" and enable Read & Write access.

Screenshot of contents permissions toggle

Since this Github action is for an Organization Account, you'll need to allow it to be installed on "Any Account". That makes the app Public, but it will not compromise your Access Token, since that's generated when you install it.

Screenshot of any account radio button

Click "Create Github App".

Step 2: Jot down the App ID and download the Private Key file (PEM)

You'll need these for step #4.

The App ID should be near the top of the page.

Screenshot of app ID on page

Download the PEM (private key) file.

Screenshot of link to download PEM file

Step 3: Install the App on your Organization Account

The link to install it should show up in the left-hand menu

Screenshot of app installation

Screenshot of installation screen

Jot down the Installation ID from the App Installation page that shows up after installing. You'll need this in the next step.

Screenshot of post-installation page

Step 4: Extract Access Token using Node library

Install github-app-installation-token and use it to extract the repo-specific Access Token from your new Github App.

You'll need the following data:

  • App ID (from step #2)
  • Installation ID (from step #3)
  • Private Key (PEM file in step #2)

There are detailed instructions for using this library in the README.

After running the script it should give you an Access Token, e.g.

{ token: 'ghs_jksGSQQkmtXSthnGnCsb9AY9yTWU58jhytm6' }

Step 5: You're done!

You can now use this Access Token to trigger a repository_dispatch event and fire a Github Action in your organization's private repo.

curl \
-X POST \
-H "Authorization: token ghs_jksGSQQkmtXSthnGnCsb9AY9yTWU58jhytm6"
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/test-inc/test-repo/dispatches \
-d '{"event_type":"rebuild_static_site","client_payload":{"post_id":54}}'

Comments are welcome!