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:
Users can select which repositories within a GitHub organization the GitHub App can access
The GitHub App only asks for fine-grained permissions to access those resources
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 usableby 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.
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.
Fill out the form to create a GitHub App pipeline that will co-exist with your project’s existing OAuth App pipeline.
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_URLbuilt-in environment variable will return the name of the CircleCI project for GitHub App pipelines
Hi! I am from Hugging Face, and we want to use features like trigger by PR ready for review. I asked our CircleCI org admin to do install the GitHub App in the organization, they ask me why CircleCI GitHub App asks for write permission:
Read and write access to code, commit statuses, and pull requests
Is any documentation explaining this? Thank you in advance.
Hey, the write permission is needed send statuses back to your repository. It’s also used to power features like the YML config editor in the CircleCI web app so that you can make changes and push them to your repo from the web app.
This isn’t new, the CircleCI OAuth App that you already have installed in your organization has write permissions. If they have more questions, feel free to reach out at sebastian@circleci.com.
I have a similar question to @ydshieh . We are happy continuing to use our GitHub OAuth App organization but want to use features like triggering on PR open, so we’d like to transition some of our repos from GH OAuth pipelines to GH App pipelines. When we add a new pipeline in our repo, there is a big blue “Authorize” button under “Connection”.
What’s unclear is — does it matter who clicks that “Authorize” button? Is this just a temporary authorization that is used one time for the process of installing the app in GitHub? Or does the identity of the person who clicks the button continue to be used in an ongoing basis by the integration? Is it the sort of thing where if the GitHub user ends up leaving the organization or has their permission level reduced, the integration will break? Or is it the sort of thing where, as long as it works once during setup, it will continue working even if the user’s relationship with the organization changes?
Hi @glasser.
“Authorization” in GitHub is not an org-level action but a user-level action, so it’s not the case that once you have authorized you have permanently linked an identity to your org.
Even after your org is connected to CircleCI, each individual user still needs to “Authorize” so the GitHub App knows their specific GitHub identity. You can still use CircleCI without authorizing, but you’ll run into some limitations
if you are using the “prevent unregistered user spend” flag, then pipelines by unauthorized users won’t run
the pipelines run by users who are not authorized will not have access to contexts
non-authorized users won’t be able to run pipelines directly from the CircleCI web app
In GitHub, you can see authorized apps in your personal account (not on the organization’s account), by going to Settings > Applications > Authorized GitHub App tab.
We know the current setup isn’t very user-friendly, as that authorization button is buried inside the “Add pipeline” form when it really should be accessible to everyone. Good news though - we’re rolling out an update (likely later today) that will place this button prominently at the top of the page whenever the GitHub App is installed. This should make it much easier for unauthorized users to spot and click it. If you have any thoughts or suggestions about this change, we’d really appreciate your feedback.
Sorry, are you saying that if we switch our pipeline to a GitHub App pipeline, branches/PRs pushed to GitHub by people in our org won’t successfully run builds (we certainly depend on contexts) until they go and click some buttons in CircleCI? Or does “the pipelines run by users” mean something different from “pipelines triggered by pushes from users”? ie, with this auth setup, there’s no way to say “anyone at our company pushing to our private repo should have their CI work properly without clicking more buttons”?
And they’ll need to click these buttons for every individual repository in our org that has a GHA-based pipeline if they want their PRs to work?
That’s correct - users need to authorize the GitHub App, but they only need to do this once for their GitHub account, not per repository.
This stems from the fact that the GitHub App model provides more fine-grained permissions than the previous OAuth approach - something many customers specifically requested. Rather than using broad-scoped tokens, it requires explicit authorization from each user, creating a more secure permission model with less aggressive token scopes.
Happy to talk more in person if it’s easier, feel free to email me (benedetta@circleci.com) to schedule a quick call.
