GitHub App integration overview

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:

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.

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.

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.

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.

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.

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:

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.