Using GitHub App Functionality in a GitHub OAuth App Organization

Overview

CircleCI's GitHub App integration offers enhanced security and control over repository access compared to the traditional OAuth App integration. This article explains how you can utilize GitHub App-specific features within organizations that still use the GitHub OAuth App integration.

Benefits of GitHub App Integration

• Selective repository access: Choose exactly which repositories CircleCI can access
• Fine-grained permissions: The GitHub App only requests the specific permissions it needs
• Enhanced security: Uses short-lived tokens for accessing your GitHub resources

Using GitHub App Features with OAuth App Organizations

You can use both integration types simultaneously in the same organization without migration. Here's how to enable GitHub App features (like custom webhooks) in an organization that uses OAuth:

1. In the CircleCI web app, select your project and navigate to Project Settings > Pipelines
2. Click "Connect" and follow the instructions to install the GitHub App in your organization
3. Complete the form to create a GitHub App pipeline (this will coexist with your existing OAuth App pipeline)
4. Navigate to the Triggers tab to configure GitHub App-specific features like custom webhooks

Known Limitations

• Config editing: The "Edit Config" button will only show .circleci/config.yml files, not other YML files in the .circleci directory
• You cannot view the config.ymlfile in the CircleCI UI:  You can however, leverage the CircleCI v2 API to retrieve your config by using the following API call:

curl -G https://circleci.com/api/v2/pipeline/<<pipeline-id>>/config -H "Circle-Token: $CIRCLE_TOKEN" |sed 's/\\n/\n/g'

• Repository URL: The CIRCLE_REPOSITORY_URL environment variable does not return a value unless the GH App trigger is on a GH OAuth connected project
• Context restrictions: Contexts restricted to GitHub security groups will return "Unauthorized" errors when used with custom webhooks
• Git cloning: If performing explicit git clone operations in your configuration, add this 
   

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

Support

If you encounter issues using GitHub App functionality alongside OAuth App integration, you may drop a comment in this thread on Discuss, our community forum. 

Additional resources

• Schedule triggers now available for GitHub App