Integrating with GitHub through a GitHub App

Connecting to your source control repository with Gearset allows you to deploy to and from your source of truth. This article shows you how simple it is to connect to your cloud-based repo on https://github.com/ through a GitHub App which allows you to specify more granular permissions for Gearset to have. For example, you can specify which repositories would be accessible to Gearset.

Initial application setup

If a member of your team has already set up a GitHub App, you can skip to the Gearset setup section of this article.

Application creation

You will need to create a new GitHub app for Gearset to be able to connect to GitHub, by following these steps:

Log in into GitHub.
Go to your organization’s settings and navigate to GitHub Apps under Developer settings.
Under GitHub App select New GitHub App.
Enter the following:
1. GitHub App name -> Gearset-YourCompanyName
2. Homepage URL -> https://app.gearset.com
3. Authorization callback URL -> https://app.gearset.com/authorization/github/callback/linked-service-connections
  
  Note: Make sure to enter the correct callback URL. If the callback URL is not correct, you might see this message:
  "Be careful! The redirect_uri is not associated with this application. The application might be misconfigured or could be trying to redirect you to a website you weren't expecting".
Under Webhook uncheck the Active checkbox.
Under Permissions select the following Repository permissions:
1. Administration: Read-only
2. Checks: Read-only
3. Commit statuses: Read and write
4. Contents: Read and write
5. Metadata: Read-only
6. Pull requests: Read and write
7. Webhooks: Read and write
Select Any account under Where can this GitHub App be installed? so that other members of your team can also use the same GitHub app.
Click Create GitHub App.

Application installation

Once you've created the GitHub app you will need to install it in your GitHub organization.

Choose the organization where you want to install your GitHub app and click Install.
Once you click Install you'll be able to select which repositories will be available to the GitHub app. Once you've selected the repositories click Install to finish the GitHub app installation in your GitHub organization.

Generate a client secret

Once the GitHub app is installed select App settings from the top of the page.

GitHub app header with link to app settings

Click Generate a new client secret to get the secret you'll need to connect Gearset to your GitHub app.

Take note of the client id and client secret to use next in the Gearset setup.

Gearset setup

Once you've got your GitHub app in place and your client id and client secret, log into Gearset, head to the Team Security page under My account. This needs to be performed by a team owner as these permissions are only available to them.

Click Configure GitHub app under the GitHub App settings section.

Enter you client id and client secret and hit Save to configure Gearset to use a GitHub app.

Once this is saved, all the GitHub connections for your team will be deleted and you and your team members will need to connect to GitHub again through the Source control and connection page. This guarantees that all GitHub connections are being made through a GitHub app.

Does your GitHub connection give the error "Gearset can't find any repositories"?

Integrating with self-managed GitLab

Integrating with GitHub Enterprise Server

Integrating with GitHub

Gearset integration with GitHub Actions