Start Building for Free

GitHub App integration overview

4 days ago8 min read
On This Page

If your CircleCI account is authenticated through the GitHub App, the content on this page is for you.

This page walks you through integrating a GitHub project with CircleCI. 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.

The following limits are currently in place for GitHub App integrations:

  • Each user can create up to three organizations.

  • Each organization under a Free Plan can have up to 10 projects.

If you need more organizations or projects, consider upgrading to a Paid plan, or contact our Support team. If you need to delete an organization, contact our Support team.

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 and connect your GitHub account, you will be guided to start creating projects, as follows:

  1. You will be prompted to create a new project from a repository

  2. After creating a new project, CircleCI will automatically generate a custom configuration file based on the programming languages and frameworks detected in your repository

  3. You will be presented with options to either

    1. Commit and Run the generated CircleCI configuration in a new branch

    2. Review the configuration file in the configuration editor in the CircleCI web app

Trigger a pipeline in CircleCI

When you choose the Commit and Run option described in the section above, a pipeline is automatically triggered. You should see the pipeline running shortly after you are taken to the CircleCI dashboard.

If you choose to review the configuration file in the config editor first, the pipeline is triggered after you save the .circleci/config.yml by clicking the Commit and Run button.

Each time you push changes to your GitHub repository, a new pipeline is triggered and you should see it running for the project within the CircleCI web app.

Successful pipeline run

Project settings

Within CircleCI, a project can have one or more configurations, which are pipeline definitions. Configurations include, but are not limited to, a .circleci/config.yml file in your repository.

A project can have one or more triggers, which are events from a source of change. Triggers include, but are not limited to, a Version Control System (VCS). A trigger determines which configuration should be used to start a pipeline.

The following settings are found by clicking the Project Settings button within your project. At this time, both configurations and triggers are limited to GitLab and GitHub App integrations.


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.


You can add or delete a configuration source for your project. If you followed the steps above to connect GitHub, a GitHub configuration source has been automatically added for you.

Once you define a configuration source, you can set up a trigger that points to that configuration.

Trigger setup page


The scheduled pipelines feature is not currently available for use with GitHub App integrations.

If you followed the steps above to connect GitHub, a trigger set with GitHub as the configuration source has been automatically added for you.

Trigger setup page

When the CircleCI GitHub App is installed for your organization, GitHub starts to send events for the repositories you have granted access to. When a trigger is created CircleCI has enough information to use the event data to determine if a pipeline should be triggered.


  • You can enable dynamic configuration using setup workflows in CircleCI. To learn about dynamic configuration, read the Dynamic configuration guide.

  • At this time, auto-cancel redundant workflows is not supported. Refer to the Auto cancelling section of the skip or cancel jobs and workflows page for more details.

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, click Organization Settings in the CircleCI web app sidebar.


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

There are a number of built-in environment variables that are not available in GitHub-based projects for accounts authenticated 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

CircleCI’s GitHub App integration provides fine-grained permissions, uses short-lived tokens, and gives you more control over which repositories CircleCI has access to. The CircleCI GitHub App also enables functionality like inbound webhooks, CircleCI’s config suggestions bot, and the ability to use multiple configuration files within one project.

There is no automated way to migrate your organization from the GitHub OAuth app to CircleCI’s 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, confirm that you do not immediately need any of the functionality listed in the Currently not supported section below. If you cannot move your organization because of missing functionality, tell us why. If you would like to switch from the OAuth app integration to the GitHub App integration, follow these steps:

  1. From your existing CircleCI organization in the CircleCI web app, click the organization dropdown in the top-left corner.

  2. At the bottom of the drop-down, click Create New Organization.

  3. On the "Connect your code" page, click Connect next to "GitHub".

  4. You will be redirected to GitHub to install the CircleCI GitHub App into your GitHub organization.

  5. Follow the instructions to create a project that is connected to one of your GitHub repositories.

  6. 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.

  7. 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.

  8. 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 7 above was successful, go to Project Settings in your organization connected to the GitHub OAuth App (your "old" org), scroll down and click Stop Building. This will ensure that push events to your repository only trigger pipelines in the project connected to your GitHub App organization.

  9. Repeat steps 5-8 by selecting Projects  Create a Project for each project that you had set up in your previous organization.

  10. If you are using contexts, you will need to recreate the contexts in your new organization.

  11. Invite your teammates to the new organization (the one that is integrated with the CircleCI GitHub App) using the instructions on this page.

  12. If you are on a paid pricing plan, go to "Plan" in the CircleCI web app and click on the "Share and Transfer" tab. Click "Transfer plan" and follow the instructions to transfer your pricing plan to your new organization by clicking on the new organization in the "transfer" UI.

  13. If you followed step 12, your pricing plan will now be transferred to your new organization (the one that is integrated through the CircleCI GitHub App integration).

  14. 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.

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 currently supported. These features are planned for future releases.

Manual trigger pipeline option

The ability to manually trigger a pipeline from the web app is not currently 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

There is currently no method to manage the connection with GitHub outside of the project setup, trigger, and configuration settings. CircleCI is working on enabling users to manage their users’ GitHub identity as part of their user profile’s account integration settings.

Scheduled pipelines

The ability to schedule pipelines is not currently supported for GitHub App projects. This feature is planned for a future release.

Auto-cancel redundant workflows

Auto-cancel redundant workflows is not currently supported. It is often used to remove noise from the pipeline page and lower the time to feedback for a commit. Refer to the Skip or cancel jobs and workflows page for more details.

Passing secrets to forked pull requests

Passing secrets to forked pull requests is not currently supported.

Stop building

GitHub App integrations do not currently support the Stop Building option that can normally be found in Project settings.

The recommendation is to either:

  • Suspend your installation. This would stop sending all events to CircleCI, so all builds will stop. This option is available in GitHub Organization settings under the GitHub Apps menu option.

  • Stop a single project from sending events to CircleCI. This option is available in GitHub Organization settings under the GitHub Apps menu option. Under Repository access, select Only select repositories and deselect the repository you want to stop building.

Additional SSH keys only

Deploy keys and user keys are not used by GitHub App integrations. All keys are stored in Project Settings  Additional SSH Keys. If you are looking to set up an SSH key in order to check out code from additional repositories in GitHub, see Add additional SSH keys.

Test Insights

Test Insights is currently not supported.

Insights snapshot badge

The Insights snapshot badge feature is not currently supported.

Only build pull requests

The Only Build Pull Requests option (usually available in Project Settings  Advanced or within trigger setup options) is not currently supported for GitHub App integrations

Suggest an edit to this page

Make a contribution
Learn how to contribute