CircleCI Logo
Navigation Menu Icon

Using the CircleCI GitHub App in an OAuth organization

Language Icon 1 day ago · 11 min read
Cloud
Contribute Go to Code

This page is relevant if your CircleCI organization has /github/ or /gh/ in the URL. Throughout this guide we will refer to org types by the appearance of /github/ or other strings in the URL.

This guide explains the two different ways your CircleCI organization can integrate with GitHub and how they affect the following:

  • The type of pipeline you can set up .

  • The triggers you can use.

Through reading this guide you will better understand your integration options, and how to leverage both for maximum functionality.

Two types of GitHub integration

CircleCI offers two methods for integrating with GitHub:

GitHub OAuth app integration

This integration is built-in for organizations with /github/ in their URL. The GitHub OAuth app integration cannot be uninstalled from these organizations, nor installed on any other org type.

GitHub App integration (recommended)

The CircleCI GitHub App is an add-on integration. The GitHub App can be installed or uninstalled on organizations with /github/ or /circleci/ in their URL, including organizations that are already integrated with GitHub through the OAuth integration. Compared to the GitHub OAuth app, the GitHub App offers increased control over the resources that CircleCI can access. The GitHub App only asks for fine-grained permissions, and uses short-lived tokens when accessing resources.

The majority of new CircleCI work triggering functionality will be made available through the GitHub App integration. We recommend installing the CircleCI GitHub App to ensure access to all new features.
Organization type identified by URL GitHub OAuth integration GitHub App integration Notes

/github/ or /gh/

built-in

add-on

Organization name, roles, permissions, and projects inherited from GitHub

/circleci/

Not available

add-on

Independent user, permissions and project management

/bitbucket/ or /bb/

Not available

Not available

-

Project types

Projects are the same for all integration types.

Pipeline types

When both GitHub integrations are installed in the same organization, different pipeline types can coexist within the same project. Each pipeline type has distinct characteristics and capabilities.

All GitHub pipeline types can be managed through Project settings  Project setup.
OAuth pipeline GitHub App pipeline

If you are a long time CircleCI user, this is the classic pipeline you will be familiar with. Identified by a gray badge: OAuth pipeline badge

Only available once the CircleCI GitHub App has been installed. Identified by a purple badge: GitHub App pipeline badge

Pipeline characteristics

  • One (and only one) per project, created automatically for OAuth organizations.

  • Cannot be deleted.

  • Cannot be renamed (always matches the project name).

  • Configuration file must be named .circleci/config.yml and stored in the repository that gives the project its name.

  • Checkout source is always the repository that gives the project its name.

  • Zero, one or many per project.

  • Can be created and deleted freely.

  • Can be renamed.

  • Configuration files can be stored in any repository the CircleCI GitHub App has access to, at any file path.

  • Checkout source can be configured independently from the project name and configuration source.

Available triggers

GitHub OAuth triggers
Used to trigger pipelines on push events from GitHub

  • Zero or one can exist per pipeline.

  • Automatically created for all OAuth pipelines.

  • The event source repository is always the same repository that gives the project its name.

  • The event name field only has two options:

    • “All pushes to the repository”.

    • “Pushes to open pull requests, default branch, and tags” (equivalent to turning the project level flag “only build pull request” on).

Schedules
Used to trigger pipelines on a schedule (nightly builds for example)

  • Zero, one or many can be created per pipeline.

API / Manual
OAuth pipelines can be triggered via API and manually through the CircleCI web app.

GitHub App triggers
Used to trigger pipelines on a wide range of events from GitHub

  • Zero, one or many per pipeline.

  • The event source repository can be any repository the CircleCI GitHub App has access to. This enable cross-repository pipeline triggering.

  • Extensive event name options available, including all pushes, pull request opened, pull request merged, pull request marked ready for review, tag pushes, and many more (see full list).

Custom Webhook triggers
Used to trigger pipelines from any external system that can send HTTP requests

  • Zero, one or many per pipeline.

  • Event name and event source are user-defined.

Schedules
Not supported yet, but coming soon. As an alternative, use custom webhooks with third-party scheduling tools.

API / Manual
GitHub App pipelines can be triggered via API and manually through the CircleCI web app.

Summary of trigger availability by pipeline type

The following table summarizes the trigger availability by pipeline type.

Pipeline type OAuth trigger Schedule trigger GitHub App trigger Custom Webhook API / Manual triggering

GitHub OAuth OAuth pipeline badge

Zero or one

Zero, one, many

No

No

Yes

GitHub App GitHub App pipeline badge

No

No

Zero, one, many

Zero, one, many

Yes

Installing the CircleCI GitHub App alongside the GitHub OAuth app

Organizations with /github/ in their URL can leverage both GitHub integration types simultaneously to access new functionality.

Installation steps

Installing the CircleCI GitHub App is a one-time action that enables all new features across the entire organization. Only organization admins can take this action.

  1. Navigate to Organization Settings  VCS Connections.

  2. Select Install GitHub App.

  3. Select repositories to grant access.

  4. Create new GitHub App pipelines alongside existing OAuth pipelines. This can be achieved in the following ways:

    • Navigate to Project Settings  Project setup

    • Via API

    • Via CLI

If you run into issues while installing the CircleCI GitHub App, submit a request through this form. A member of our team will be in touch promptly.

Having both a GitHub App trigger and a GitHub OAuth trigger configured in the same project could result in duplicate builds. You can prevent this behavior by deleting the GitHub trigger associate with the GitHub OAuth pipeline, in Project settings  Project setup. This trigger can be re-created by selecting click here at the bottom of the GitHub OAuth pipeline card.

Authorization steps

Once the GitHub App is installed, each user must authorize the CircleCI App by clicking on the Authorize button displayed on the web app top bar for unauthorized users.

Authorizing the GitHub App ensures that users can:

If you run into an issue while attempting to authorize, submit a request through this form. A member of our team will be in touch promptly.

Benefits of dual integration

Dual integration provides the following benefits:

  • Access to new GitHub App features while maintaining existing OAuth pipelines. Key functionality enabled through the GitHub App integration includes the following:

    • The option to have multiple pipelines in the same project, each defined in its own YAML file.

    • The possibility to set up your pipelines so that the config file and the application code are stored in different repositories. Refer to the changelog entry for more information.

    • A more flexible trigger system, with each pipeline having any number of VCS or non-VCS triggers. This includes:

      • Non-repo based triggers: Custom webhooks enable triggering builds from any system that can emit webhook events. Refer to our community forum for an example and known limitations.

      • Cross-repo triggers: Events in one repository can trigger builds on one or many other repositories.

      • More GitHub events as triggers: Pipelines can be set up to run on events other than push, including pull request events, with more powerful customization of trigger conditions. For full details, see the GitHub trigger event options page.

  • Gradual migration path for complex projects

  • New trigger options without disrupting current pipelines

Troubleshooting

Can I convert an OAuth pipeline to a GitHub App pipeline?

Pipelines cannot be directly converted.

Instead, if you want to stop building through the OAuth integration, duplicate the OAuth pipeline as a GitHub App pipeline, then remove the OAuth GitHub trigger.

Why can’t I see GitHub App options?

Ensure the GitHub App is installed via Organization Settings  VCS Connections. Then select Add pipeline on the Project Settings  Project setup page to create a new GitHub App pipeline.

How do I prevent duplicate builds?

Configure trigger events carefully or delete OAuth triggers when using GitHub App pipelines for the same repository.