GitHub App integration overview
1 day ago
If your CircleCI organization is integrated with GitHub through the CircleCI GitHub App, the content on this page is for you.
This page walks you through integrating a GitHub project with CircleCI through the CircleCI GitHub App integration. The sections below introduce you to concepts and ways to manage CI/CD (continuous integration and continuous delivery) pipelines for your GitHub project. CircleCI features that are in development for GitHub App projects are detailed in the Currently not supported section.
Steps to integrate GitHub projects with CircleCI
Follow the steps on the Sign up and try CircleCI page to connect your GitHub account, which creates your CircleCI organization.
When you create a new organization, you will be guided to start creating projects, as follows:
-
The first project you create will prompt you to install the CircleCI GitHub App in a GitHub organization.
-
After installing the GitHub App, you will select a repository to use for your project’s first pipeline.
-
CircleCI will automatically generate a custom configuration file based on the programming languages and frameworks detected in your repository for this pipeline. If you already have a YAML configuration file on the default branch of the repository that you selected, CircleCI will use the configuration file that exists in the repository instead of generating a new one for your project’s first pipeline.
-
You can then choose a trigger event option out of the dropdown list.
-
Finally, you can review your setup.
-
If CircleCI generated a custom configuration file for you, CircleCI will commit the generated configuration to a new branch (
circleci-project-setup) when you click the Commit config and run button.
If you are new to CircleCI, you may wish to get started with our Quickstart guide, our Hello world examples, or take a look at some of our sample configurations that demonstrate different types of workflows. The Configuration reference is a full reference to the keys used in a .circleci/config.yml file.
|
Can I integrate a GitHub org with multiple CircleCI orgs?
A GitHub org with the CircleCI GitHub App installed can only be integrated with one CircleCI organization.
In this scenario, attempting to integrate with a second CircleCI organization will redirect you to a GitHub App integration settings page when creating a project. If you are not sure what other CircleCI organization may be connected to your GitHub organization, you can submit a request here.
Trigger a pipeline in CircleCI
When you click Commit config and run, as described above, a pipeline is triggered. You will see the pipeline running when you are taken to the CircleCI dashboard.
When the event you selected under the "Run on" menu occurs (see the GitHub event trigger options page, for a full list of options), a new pipeline is triggered. You will see the pipeline running in the CircleCI web app.
Project settings
Within CircleCI, a project can have one or more Pipelines. Each pipeline is defined by two key characteristics:
-
A configuration file, which is stored in a repository referred to as config source, at a path of your choosing. The default config source location is
.circleci/config.yml, but any file path with extension*.ymlcan be used. -
A checkout source, which determines which repository will be checked out when running a checkout step. This model allows your CircleCI config to be stored in a different repository from your code.
Each pipeline can have zero or many triggers, which are events that cause a pipeline to run.
The following settings are found by clicking the Project Settings button within your project.
People
Project roles give control over which users have access to which projects within an organization. This enables teams to have limited access to only their projects, while managers and others can have broader organizational access. The access options are:
-
Admin: Read and write access to the project and all settings and ability to manage other users' access.
-
Contributor: Read and write access to the project and some settings.
-
Viewer: Read only access to the project and some settings.
For a complete list of permissions, see the Roles and permissions overview page.
Pipelines and triggers
You can add or delete pipelines for your project. For details see the pipelines overview.
Advanced
-
You can enable dynamic configuration using setup workflows in CircleCI. To learn about dynamic configuration, read the Dynamic configuration guide.
Only build pull requests
In your trigger settings, select the "PR opened or pushed to, default branch and tag pushes" option under the "Run on" menu. For a full list of GitHub event trigger options, see the GitHub trigger event options page.
Organization settings
For GitHub App integrations, organizations and users are managed independently from your VCS. Organizations and users are considered CircleCI organizations and users, with their own roles and permissions that do not rely on those defined in your VCS.
To manage settings at the organization level, select Organization Settings in the CircleCI web app sidebar.
People
Add or remove users, and manage user roles for the organization as well as user invites. See the Roles and permissions overview page for full details.
Roles and permissions
CircleCI users have different abilities depending on assigned roles in a particular organization. For a detailed list of CircleCI org and project roles and associated permissions, see the Roles and permissions page.
Deprecated system environment variables
A subset of built-in environment variables are not available in GitHub-based projects authorized through the GitHub App. VCS support for each environment variable is indicated in the Built-in environment variables table on the Project values and variables page. If your pipelines need these environment variables, we recommend you use suitable replacements from the available pipeline values.
Moving from the GitHub OAuth app integration to the GitHub App integration
Before attempting to move your information from an org integrated with the GitHub OAuth app to an org integrated with CircleCI’s GitHub App, consider the following:
-
If the motivation for moving is to leverage new functionality that is only available to the GitHub App integration, consider using your existing organization and installing the GitHub App alongside your OAuth app integration, as described in this guide.
-
If the motivation is to completely remove the OAuth app integration for security, compliance, or other reasons, follow the steps below.
Steps to migrate to an organization without default GitHub OAuth integration
The following steps guide you through migrating you organization as follows:
-
From an organization integrated with GitHub through the OAuth integration by default (identifiable by
/github/or/gh/in the URL). -
To an organization that does not have a default OAuth integration with GitHub (identifiable by
/circleci/in the URL).
|
-
From your existing CircleCI organization in the CircleCI web app, select the organization dropdown in the top-left corner.
-
At the bottom of the drop-down, select Create New Organization.
-
On the "Connect your code" page, select Connect next to "GitHub".
-
You will be redirected to GitHub to install the CircleCI GitHub App into your GitHub organization.
You can install the CircleCI GitHub App into the same GitHub organization that already uses the GitHub OAuth App integration, as long as your original CirlceCI organization is not already connected to it. -
Follow the instructions to create a project that is connected to one of your GitHub repositories.
-
If you are on a paid pricing plan:
-
Navigate back to the organization that is connected to the GitHub OAuth app
-
Select Plan in the CircleCI web app
-
Select the "Share and Transfer" tab
-
Select Add shared organization and choose the new organization that you just created that integrates with CircleCI’s GitHub App.
-
-
Navigate to the project that was created in step 4 in the "new" organization that is integrated with the GitHub App. Match any custom project settings that you had from your previous project to this new project on the Project Settings page. This includes things like environment variables and outbound webhooks.
-
Perform a test push of code to your repository to ensure that a pipeline is triggered and is working as expected in your new CircleCI organization.
-
Assuming the repository you connected is also connected to your previous CircleCI organization, CircleCI will start pipelines when a push event happens to the repository in both the old and new organizations. If your test from step 8 above was successful, go to Project Settings in your organization connected to the GitHub OAuth App (your "old" org), scroll down and select Stop Building. This will ensure that push events to your repository only trigger pipelines in the project connected to your GitHub App organization.
-
Repeat steps 6-9 by selecting for each project that you had set up in your previous organization.
-
If you are using contexts, you will need to recreate the contexts in your new organization.
-
Invite your teammates to the new organization (the one that is integrated with the CircleCI GitHub App) using the instructions on this page.
-
If you are on a paid pricing plan and followed step 6:
-
Navigate back to the "old" organization and select .
-
Select the
next to the "new" organization to remove the shared relationship between the "new" and "old" organizations. -
Select Transfer Plan and follow the instructions to transfer the plan from the "old" organization to the "new" organization.
-
-
At this point, you will be left with a GitHub App-integrated organization that has the same payment plan and projects as your previous organization. If you get logged out, you can continue to use the "Login with GitHub" button on the CircleCI login page as long as the old organization is not deleted.
| Data from Insights and historical pipeline runs will not be present in your new organization. Contexts will not be present until you recreate them for your new org. |
Currently not supported
If one of these pieces of functionality is especially critical to you, tell us why.
The following sections are features of CircleCI which are not yet supported when using the GitHub App integration. These features are planned for future releases.
Restrict a context to a security group
The ability to restrict a context to a security group is not yet supported for GitHub App projects.
In-app config editor
The in-app config editor is currently only available for GitHub App accounts during project creation.
Account integrations
Viewing does not currently show a GitHub App integration. This page only shows GitHub OAuth app integrations.
Scheduled pipelines
The ability to schedule pipelines is not yet supported for pipelines that use the GitHub App integration. This feature is planned for release by September 2025. As an alternative, use a custom webhook or the V2 API to trigger a pipeline, which you can curl with a 3rd party scheduling tool.
Build forked pull requests
The Build forked pull requests feature is not currently supported for GitHub App pipelines.
Passing secrets to forked pull requests
Passing secrets to forked pull requests is not currently supported for GitHub App pipelines.
Stop building
GitHub App integrations do not currently support the Stop Building option that can normally be found in Project settings. However, the same functionality can be achieved by deleting (or disabling) all triggers associated with existing pipelines, from .
Additional SSH keys only
Deploy keys and user keys are not used by GitHub App integrations. All keys are stored in . If you are looking to set up an SSH key to check out code from additional repositories in GitHub, see Add additional SSH keys.
Outbound webhooks
While outbound webhooks are available for GitHub App pipelines, their payload differs from that of GitHub OAuth pipelines. See the outbound webhook reference page for more details.
Test Insights
Test Insights is currently not supported for orgs authenticated with the CircleCI GitHub App. Test Insights is available for GitHub OAuth authenticated orgs that have GitHub App pipelines set up.