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?

GitHub Apps are tools that extend the functionality of GitHub. They can perform actions on GitHub, such as opening issues, commenting on pull requests, and managing projects, or even interact with external services based on events that happen on GitHub. For example, a GitHub App could post a message in Slack when an issue is opened in a repository.

GitHub Apps primarily provide the ability to receive webhook events and acquire narrowly scoped, short lived authentication tokens.

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 1 hour. 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. Configure it with the necessary permissions. Note that you will need to add private keys to an App in order to generate installation authentication tokens.
  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.
  2. Repository admins must create a support issue to request transfer of the new app to the VA organization and installation into 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/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.

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.