Skip to main content
Warning

Migrations are coming to VA GitHub. See the Migrations section for more information.

Using GitHub Apps

Learn how to create GitHub Apps and transition service accounts to apps.

What is a GitHub App?

The name GitHub App can be confusing, so it is most important to first define what a GitHub App is not: A GitHub App is not an actual software application that users need to build and host.

For most VA users, a GitHub App is just a mechanism that you can use to generate an authentication token to make GitHub API requests, that will replace the use of a PAT from a service account. Users register GitHub Apps by entering some information in the GitHub UI, then you can use the App’s information to generate an authentication token for making API requests.

A GitHub App can include webhook configuration that will enable delivery of webhook events to an HTTP service that you define. If you want to receive webhook events for your GitHub App then you would need some HTTP service or endpoint to receive the webhook events. However most VA use of GitHub Apps is only to get an authentication token to make API requests, so the webhook configuration and corresponding HTTP service is not necessary.

See these resources for more information on GitHub Apps:

GitHub Apps vs. Service Accounts

While service accounts are supported we strongly encourage teams to use GitHub Apps where possible.

There are numerous benefits to using GitHub App tokens instead of service account or user PATs:

  1. GitHub Apps only have access to specific repositories, in contrast to a service account which (typically) needs to be an organization member, granted the service account access to all internal repositories.
  2. They provide enhanced security because the tokens only last 8 hours. GitHub App tokens are acquired on the fly so they never need rotating.
  3. GitHub Apps also use fine-grained permissions which allow you to scope an App’s permissions to the bare minimum that is necessary, further enhancing security.
  4. They provide more scalability because each GitHub App has its own rate limits, compared to shared rate limits for user PATs since all PATs from a single user share the rate limit. The rate limits for a user and a GitHub App are generally similar, however it’s easier to scale out by creating multiple GitHub Apps which would each receive their own rate limits. Workflows that need extremely high rate limits can also achieve greater scalability by using different GitHub Apps (with more limited permission sets) for various parts of the workflow, or even cycling through multiple instances of a similar GitHub App in a round robin fashion to spread the rate limit load among multiple GitHub Apps.
  5. GitHub Apps are not tied to a user, so they remain functional even if users leave the organization or if problems were to arise with the va.gov service account configuration.
  6. GitHub Apps may be easier for users to create since you don’t have to create a GitHub user to keep track of.
  7. GitHub Apps can define a webhook HTTP endpoint and can subscribe to webhook events.

Switching from service accounts to GitHub Apps

The basic steps to switch from using PATs to GitHub App Tokens are as follows:

  1. Analyse your current usage: Identify the API calls and permissions your PATs are using, and document the repositories and resources accessed by the PATs.
  2. Register a GitHub App: Create the app in your user namespace following our guidance.
  3. Follow the instructions below for requesting GitHub App installation into the VA department-of-veterans-affairs organization.
  4. Update your workflows to authenticate as the App installation instead of using PATs. That documentation provides instructions on using the GitHub APIs to generate App installation tokens, however there are also several publicly available utilities that you can use to simplify this process. If you are using tokens in an Actions workflow you can use the create-github-app-token custom action to generate a token. There is also the gh-token CLI extension that can be used to easily create an installation token.

Be aware that there may still be some scenarios and GitHub APIs that will require the use of a user PAT instead of an App token, for example APIs that require full user-level access rather than fine-grained permissions. It is beyond the scope of this documentation to outline every scenario for which GitHub Apps may not work, however we believe that GitHub Apps can replace the vast majority of service account use in VA GitHub workflows. Create a support request if you would like consultation on your specific scenarios.

GitHub App Installation Instructions

Installing new GitHub Apps

Follow these instructions to request the installation of new GitHub apps in VA GHEC.

  1. Create the new GitHub App in your personal namespace. See our guidance below for instructions on filling out the new GitHub App form for typical VA use.
  2. Repository admins must create a support issue to request transfer of the new app to the VA organization and installation into their VA repositories. We ignore all app transfer or installation requests that do not have a corresponding support issue from a repository admin. The support issue should mention the app name and the repositories that you want it installed into. Depending on the app configuration, repository admins may be able to install the app into their repositories on their own (see below for details).
  3. Transfer app ownership from the user to the department-of-veterans-affairs organization. We cannot inspect and manage apps owned by users. Note that you must ensure that you are transferring the app to the department-of-veterans-affairs GitHub organization, not the similarly named GitHub enterprise. The GitHub UI will indicate whether you are choosing an enterprise or an organization.
  4. We will approve the app transfer request if it meets the following criteria:
    1. It is only requesting repository or user permissions and does not request the repository Administration permission. For some scenarios we will approve apps with limited organization permissions, but there must be justification for those permissions.
    2. It is not requesting permissions to any secrets or keys: Codespaces user secrets, GPG keys, Git SSH keys, SSH signing keys.
    3. It is not sending webhooks to an external service.
    4. It is not a third-party app.
    5. The Expire user authorization tokens option is enabled, so that user auth tokens expire automatically.

Note on third-party apps and custom apps with webhooks to external services: There are many such apps currently installed but in order to align with VA/FedRAMP Moderate requirements in GHEC-US we are no longer approving GitHub Apps that communicate with external services without approval from VA compliance and security. As we transition to GHEC-US we will provide more instructions on how VA engineering teams should request approval for these apps.

Installing existing GitHub Apps into new repositories

Once an app has been installed into the department-of-veterans-affairs organization with access to one or more repositories, repository admins can install the app into their repositories without approval or assistance from our team if the app does not request any organization permissions or the repository Administration permission. Otherwise, repository admins can create support requests to install existing apps into new repositories. The support request should include the name of the app and the list of repositories to install it into.

GitHub App Registration Guidance

Many of the available options when registering a new GitHub App are not necessary for most VA use cases. If you are registering a GitHub App to replace a service account or if you are only using the app to get authentication tokens for making GitHub API requests in automated workflows, then you can follow this guidance when filling out the new GitHub App form.

To create a new GitHub App for use in the VA department-of-veterans-affairs organization, you must first register the GitHub App in your personal namespace and then request to transfer ownership of the app to the department-of-veterans-affairs organization. To register a new GitHub App in your personal namespace, go to your profile Settings > Developer Settings > GitHub Apps and click the green New GitHub App button (or open this link in a new tab).

  • GitHub App name: Required. The name of your new app, this can be whatever you wish but it’s best to give a descriptive name that indicates the scope (such as team or organization name) and purpose of your app.
  • Description: Optional. This field is not labeled, it’s the text area beneath GitHub App name. This is descriptive text that is shown on your App’s page in GitHub. This can also be whatever you wish though good practice would be to provide some descriptive information on how this app will be used.
  • Homepage URL: Required. This is just informational and is not used by GitHub, it’s mostly intended to convey the home page for third-party apps. If the team that owns the app has an intranet site or some other home page or repository, you can use that.

Identifying and authorizing users

  • Callback URL: Optional. This is only used for web application flows which you most likely are not using, so leave it blank.
  • Expire user authorization tokens: Leave checked. User authorization (OAuth) tokens issued by the app will automatically expire after 8 hours. Note that this does not affect app installation tokens which always expire after 1 hour. We expect most VA usage to be through app installation tokens.- Request user authorization (OAuth) during installation: Optional. This enables the App to make API requests on behalf of a GitHub user, but the user must authorize the app first. You most likely don’t need this, so leave it unchecked.
  • Enable Device Flow: Optional. Device flow allows your app to authorize users for a headless application like the GitHub CLI. You most likely don’t need this, so leave it unchecked.

Post installation

  • Setup URL (optional): Optional. Not necessary for typical VA workflows.
  • Redirect on update: Optional, not necessary.

Webhook

  • Active: Optional. Uncheck this unless you are standing up an HTTP service to receive webhooks.
  • Webhook URL: Optional, but required for webhooks. Leave this blank unless you are standing up an HTTP service to receive webhooks. In that case, provide the URL to your HTTP service.
  • Secret: Optional. If provided this secret value will be included in the webhook HTTP requests so that your HTTP service can verify the authenticity of the HTTP requests that it receives.

Permissions

Select your desired permissions. Note that specific justification must be provided if your app requests any of these permissions:

  • Repository: Administration
  • Any Organization or Enterprise permissions
  • Any User permissions related to secrets or keys: GPG keys, Git SSH keys, SSH signing keys, etc.

Subscribe to events

This section is related to webhook configuration and will be hidden if you have deselected the Webhook Active checkbox.

These options are for subscribing to the various webhook events that are available for your chosen permissions. These are only used if your app is configured to receive webhook events. If your app is configured for webhook events, one or more of these options should be selected.

Where can this GitHub App be installed?

Select Only on this account just to ensure that no one tries to install your app into their repositories before you have transferred it to the VA organization. When the app is transferred to the VA organization this property will be updated so that the app is only installable into the VA org.

Creating App private keys

After you have registered the new app, you will need to add private keys to your App in order to generate installation authentication tokens. Save the private key files in a secure fashion for later use.