In my current role, I configured Terraform to manage our GitHub organisation. As with all providers, we need need to provide credentials for authentication. I didn’t want to use an access token, as they are tied to an individual user and will cause breakage should the user depart the organisation. Thankfully, GitHub supports using an application for authentication.

Create the GitHub Application

The first step in the process is to create a new GitHub application. While this can be done either in a personal account or within an organisation, I recommend doing this within the organisation. That way, if someone leaves the organisation the application doesn’t go with.

To create the application, browse to the Settings page of your organisation (https://github.org/<yourorg>/settings/apps) then expand Developer settings at the bottom of the navigation panel and select GitHub Apps. Then click the New GitHub App button at the top of the page.

On the Register new GitHub App page, enter a name for your GitHub app. Provide a description and a Homepage URL. Uncheck Active under Webhook. Under permissions, configure the permissions that you will require for management of your GitHub environment. Ensure that Only on this account is selected for where the app can be installed (unless you intend to use the same application across multiple orgs in the enterprise), then click Create GitHub App.

Once the application is created, you will see a confirmation banner at the top of the page. Under the About section, you will see the App ID which will be a number. Make a note of this, as we will need it for authentication.

Click the generate a private key link in the banner, then click the Generate a private key button to create a new private key for authentication. This will trigger the download of a PEM file which you will need for authentication.

Finally, we need to install the application into our organisation so we can use it. In the navigation sidebar, click Install App, then click the Install button next to your organisation name, and then click again on Install on the confirmation page. Once the application is installed, we need to get the Installaton ID. Sadly this does not show anywhere on the installed app page, so we need to get the ID from the page URL. In your browser’s address bar, copy the number from the end of the URL, after the text installations. This is your installation ID.

Configure the Terraform provider to use the GitHub app

Now that we have an app installed, and all the configuration details, we can configure the GitHub provider.

provider "github" {
  app_auth {
    id              = "<App ID>"
    installation_id = "<Installation ID>"
    pem_file        = file("<Path to PEM file>")
  }
  owner = "<Your Org>"
}

This configuration works for initial testing - but we don’t want to commit our secret key into our code repository. To solve this problem, we can create GitHub variables for the App ID (TERRAFORM_APP_ID) and Installation ID (TERRAFORM_INSTALLATION_ID) and a secret containing the PEM file (TERRAFORM_APP_PEM_FILE). If we leave the app_auth block empty, the values will be automatically populated with these values.