[Product Update] Using GitHub App functionality in a GitHub OAuth App organization

Build Environment
1

CircleCI’s GitHub App integration offers users more control over which resources in your VCS CircleCI can access and lets CircleCI access those resources in a more secure manner. Specifically:

  1. Users can select which repositories within a GitHub organization the GitHub App can access
  2. The GitHub App only asks for fine-grained permissions to access those resources
  3. The GitHub App uses short-lived tokens when accessing your resources.

Some existing and future functionality on CircleCI, such as triggering a pipeline via a custom webhook, will only be available when using the more secure GitHub App integration. Despite only being available when using the GitHub App, this functionality is still usable by organizations that currently integrate with CircleCI’s GitHub OAuth App. The GitHub App & OAuth App can co-exist side-by-side in the same organization without needing to sacrifice any functionality that is not yet available to the GitHub App integration (such as scheduled pipelines) or needing to setup and migrate to a new organization.

As an example, to use GitHub App functionality such as custom webhooks in a GitHub OAuth App organization:

  1. In the CircleCI web app, select a project, navigate to Project Settings > Pipelines. Click “Connect”. Follow the instructions to install the GitHub App in the organization that already has the OAuth App installed.
  2. Fill out the form to create a GitHub App pipeline that will co-exist with your project’s existing OAuth App pipeline.
  3. Navigate to the Triggers tab and create a custom webhook trigger that will run the newly created GitHub App pipeline.

If you are running into issues using GitHub App-specific functionality in your organization that also uses the GitHub OAuth App, comment below or reach out to me at sebastian@circleci.com.

Known limitations:

  • You cannot yet schedule GitHub App pipelines. You can continue to schedule pipelines that use the OAuth App

  • The “Edit Config” button in the CircleCI web app will only show the .circleci/config.yml from the repository. It will not show any other YML files in the repository’s .circleci directory.

  • The CIRCLE_REPOSITORY_URL built-in environment variable will return the name of the CircleCI project for GitHub App pipelines

  • Contexts that are restricted to a GitHub security group will return an “Unauthorized” error when used with using custom webhooks

  • If you are performing an explicit git clone in your YML configuration file, add the following snippet to ensure it continues to work:

    mkdir ~/.ssh
    touch ~/.ssh/known_hosts
    ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts

2 Likes