GitHub Integration

OpsLevel supports two methods to authenticate our GitHub integration:

• OpsLevel's GitHub App (recommended for SaaS GitHub)
• Personal Access Tokens (recommended when OpsLevel or GitHub is Self-Hosted)

Where possible, we recommend using our GitHub App integration for its simplicity and built-in rotation of secrets.

Note: We may occasionally request additional permissions to enable new features (i.e. service templates require permissions to create repositories and merge requests). With the GitHub App, you'll automatically be prompted to increase permissions; with Personal Access Tokens you must manually add new permissions. If you want the ability to freeze the permissions set or "opt in" to only certain permissions (i.e. no write access to create repositories) we recommend the Personal Access Token. Note that excluding permissions for a Personal Access Token may prevent certain OpsLevel features from working properly.

Authenticating with OpsLevel's GitHub App

Add a GitHub integration in OpsLevel

Integrating with OpsLevel's GitHub App does not require any direct setup within GitHub. To get started, follow these steps:

1. In the OpsLevel app, click Integrations in the left sidebar.
2. Click on the + New Integration button.
3. Click the GitHub integration card.
4. In the modal, choose the GitHub App option
5. Follow the instructions within GitHub to install the OpsLevel GitHub App.

Integrating Multiple Organizations: If you have already integrated an organization for your GitHub instance and want to integrate another one, follow the steps above to add the integration in OpsLevel. Each integration is associated with a separate organization and GitHub will track which organizations have already been connected.

Permissions

The OpsLevel GitHub App requires the following permissions:

Authenticating with a Personal Access Token

Set up a Personal Access Token in GitHub

In order to integrate GitHub with OpsLevel using a Personal Access Token, you'll need to configure a Personal Access Token within GitHub.

Note: OpsLevel expects classic GitHub Personal Access Tokens, rather than Fine-grained tokens.

1. Enter a Note for your Personal Access Token, such as "OpsLevel Integration"
2. Choose the Expiration period that is right for your use case.
   Note: OpsLevel will allow you to replace the token in the Integration configuration after the integration is created.
3. The integration requires several scopes (refer to the screenshots below for more details):
   - repo
   - read:user
   - admin:repo_hook
   - admin:org_hook
   - admin_org:read_org
4. Once the scopes and expiration are configured, save the configuration and copy the token for use later.
   Note: the token will not be recoverable, so ensure that you store it in a lasting, secure location.
5. Ensure that the user that owns the Personal Access Token has admin access for each repository that you want OpsLevel to work with. This is because OpsLevel maintains webhooks for each repository.

Using PATs with GitHub Organizations that require SAML Single Sign-On

To use a personal access token (classic) with an organization that uses SAML single sign-on (SSO), you must first authorize the token. For instructions, view GitHub's guide to Authorizing a personal access token for use with SAML single sign-on.

Add a GitHub integration in OpsLevel

Once you have the PAT from GitHub, you will be able to integrate your OpsLevel account with your GitHub instance by:

1. In the OpsLevel app, clicking Integrations in the left sidebar.
2. Clicking on the + New Integration button.
3. Clicking the GitHub integration card.
4. In the modal, choose the Personal Access Token option
5. When prompted, enter the Access Token from the PAT that was created in GitHub and the publicly routable URL to your GitHub instance for the Base URL.

1. Press the Next button.
2. You will then be prompted to choose a GitHub organization or group of personal repositories to integrate into OpsLevel.

3. Select one and press Submit

Integrating Multiple Organizations: If you have already integrated an organization for your GitHub instance and want to integrate another one, follow the steps above to add the integration in OpsLevel. Each integration is associated with a separate organization and OpsLevel will track which organizations have already been integrated.

If you have any questions or feedback, let us know at [email protected].