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:
In the CircleCI web app, select your project and navigate to Project Settings > Pipelines
Click "Connect" and follow the instructions to install the GitHub App in your organization
Complete the form to create a GitHub App pipeline (this will coexist with your existing OAuth App pipeline)
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.ymlfiles, not other YML files in the.circlecidirectoryYou 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_URLenvironment variable does not return a value unless the GH App trigger is on a GH OAuth connected projectContext restrictions: Contexts restricted to GitHub security groups will return "Unauthorized" errors when used with custom webhooks
Git cloning: If performing explicit
git cloneoperations in your configuration, add thismkdir ~/.sshtouch ~/.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.