Note: This is not currently supported for Github Enterprise Server connections.
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 AppsunderDeveloper settings.
Under
GitHub AppselectNew GitHub App.Enter the following:
GitHub App name->Gearset-YourCompanyNameHomepage URL->https://app.gearset.comAuthorization 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_uriis 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
Webhookuncheck theActivecheckbox.
Under
Permissionsselect the followingRepository permissions:Administration: Read-only
Checks: Read-only
Commit statuses: Read and write
Contents: Read and write
Metadata: Read-only
Pull requests: Read and write
Webhooks: Read and write
Select
Any accountunderWhere 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
Installyou'll be able to select which repositories will be available to the GitHub app. Once you've selected the repositories clickInstallto 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.
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 the Github App replace the need for Team shared connection (service user)?
No, Gearsets Github app works via the authenticating on behalf of user method. This means that we need to use a user's details to make changes in your repo.
This means that a Team Shared connection/ Service user is required in order to perform all the changes in a pipeline or CI jobs that can not be directly correlated to a individuals users change, for example a semantic merges.
We do not currently have plans to support Authentication as a GitHub App.
If you have any questions about Github App feel free to reach out via the In-app chat.