Using GitHub App Credentials with the Terraform Provider for GitHub

Why would I do this?

Accessing GitHub's API via a personal access token owned by a user is subject to a rate limit of 5000 requests per hour. The Terraform Provider can often run up against this rate limit when used for repository creation and management. That rate limit increases to 15,000 requests per hour when the request to the GitHub API is made using credentials from a GitHub App that is owned by a GitHub Enterprise Cloud organization.

Am I installing an app?

No. GitHub Apps behave like service accounts. They have the option to receive webhooks from your GitHub Organization, but that is not a requirement. You can create a new Application that is owned by your Organization and use the credentials issued to that application for the GitHub Terraform Provider.

Can the app be used by more than one Organization?

Yes, but you must both make the app available to other users and organizations when you create it and install the app in each organization.

Can the credentials be used by more than one Organization?

No. The credentials require a separate identifier for each organization called installation ID.

Why can't I name my app [insert name here]?

GitHub App names must be unique, and they occupy the same namespace as users or organizations. So you can't have an app that shares the same name as your organization or another user.

Can more than one person manage the app?

Yes. GitHub Apps owned by organizations can be managed by owners of that organization and users that have been given explicit permission to manage apps for the organization.

Set up the GitHub App

Note: You must be an owner of or have been granted GitHub App manager permissions in the organization or organizations to create or install an app in that organization.

1. Go to your organization's Settings tab, and select Developer Settings->GitHub Apps from the very bottom of the left hand navigation.

2. Select the New GitHub App button at the top right of the page.

3. Provide an Application name and homepage URL for your app. The application homepage can be any valid URL.

4. The parameters for Identifying and authorizing users and for Post installation can remain as their defaults (or you may choose to define these if you are familiar with their use). The Web hook "Active" checkbox should be un-checked.

5. The permissions defined in the permission section will depend on what type of access you'd like the Terraform Provider to have. The application will request these permissions during the installation process. You should define these permissions based on the scope of access you'd like the Terraform Provider to have within your organization.

6. Choosing where the app can be installed determines whether you can use this one app in multiple organization or will limit the installation to this organization. Choose to limit the app if you plan to use a separate app for each organization or share the app if you plan to use the same app for multiple organizations.

7. After you have filled out the form, click the "Create GitHub app" button to create the app.

8. Now we will generate the remaining credentials needed for the Terraform Provider. To use application credentials the Terraform Provider requires an application ID, a key in the form of a PEM file, and an installation ID. Creating the application will have generated an application ID and will likely have prompted you with a message to create a private key.

9. Follow that link or scroll to the bottom of the page to the section on Private keys and generate a private key. That will cause the your browser to be prompted to download the PEM file we need.

10. The last piece we need is the installation ID. In the left navigation of the app settings page, choose the Install App option. This will display a list of organizations where you are authorized to install the application.

11. Click the button to install the app in the organization where you'd like it installed. This will prompt you to authorize the app to have access to your organization using the permissions you specified for the app. Click the Install button here to install the app.

12. Once the app is installed you can get its installation ID from the URL in your browser window. The ID is the numbers at the end of the URL.

13. Once you have this information you can set the appropriate credentials in your Terraform Provider, and the provider will access the GitHub API under the much higher rate limit. Note that you will need at least a separate installation ID for each organization, so the specific credentials for your Terraform Provider will always vary between organizations.