Troubleshooting adding GitHub App to an organization with GitHub OAuth

Overview

There are two types of apps available for GitHub:

• OAuth App - This is the original app for integrating GitHub with CircleCI, providing CircleCI with access to all repositories in your GitHub account or organization. This is the one that you will use when you initially connect your GitHub account to CircleCI. If you go into the settings of a project and view either the "Pipelines" or "Triggers" option, you will see the "OAuth" badge beside it.
• GitHub App - This is the newer GitHub integration. The difference between this app and the OAuth app is that the GitHub App provides a more granular approach to which repos CircleCI can access. This means you do not need to give CircleCI access to all of your repositories, and you can fine-tune it as needed.

You can add the GitHub App to an existing organization that uses the GitHub OAuth app. This article describes how to troubleshoot the issue you may encounter when adding it.

Solution

This issue can be resolved by going into GitHub and removing the GitHub App.

Removing the GitHub app can be done via the following steps:

1. Go to your "Settings" in GitHub and then select "Applications" from the left-hand sidebar.
2. In the 'Installed GitHub Apps' tab, there should be a CircleCI App. Click on the grey "Configure" button.
3. To make sure that this is the right app, there should be an area titled "Repository access" with two options: "All Repositories" and "Only select repositories". 
4. At the bottom of the page, there should be a red "Danger zone" area. Click on the grey "Uninstall" button.

With the app removed, you should be able to go back into CircleCI and do the following:

1. Head into a project, go to the "Project Settings" area, and click on "Pipelines".
2. Within the "Pipelines" area, click on the blue "Add Pipeline" button.
3. On the "Add Pipeline" setup page, select "GitHub App" if it is not already selected in the dropdown, and then click the blue "Connect" button.
4. This will prompt you to reinstall the GitHub App. Select your account or organization from the list.
   NOTE: If you see a "Configure" button beside the account or organization you want to use, it means the app was not appropriately uninstalled in the previous steps.
5. Select whether you want CircleCI to have access to "All Repositories" or "Only select repositories" and then click on the green "Install & Authorize" button.
   NOTE: If you use the "Only select repositories" option, you will need to select which repositories you want CircleCI to have access to via a dropdown that appears.
6. This should then redirect you back to CircleCI to continue the setup. Continue setting up and then click the blue "Save" button at the top of the page.