GitHub Teams Integration

If your organization uses GitHub to manage teams and hierarchy, you can take advantage of our GitHub Teams Sync to manage your teams and users in OpsLevel.

We use the GitHub REST API to periodically sync teams and their members every 12 hours. We also subscribe to team membership webhooks to keep them up to date in real time. To enable this feature either use the GitHub App, or use a Personal Access Token with the required permissions (see our installation docs for details).

The remainder of this guide is focused on enabling you to configure the integration.

Features

The following provisioning features are supported by OpsLevel today:

• Teams - We will create new teams when we sync teams every 12h from GitHub.
• Team Hierarchy - We will maintain the Team hierarchy from GitHub
• Team memberships - We will pull in the team memberships, and if we find matching users in OpsLevel we will assign them to the Teams we create in OpsLevel. This can be done through GitHub handle or GitHub email if present.

Requirements

Authorize (or reauthorize) the GitHub App, or create a token with the require permissions. The option to Sync Teams will be available if we detect the necessary permissions. As mentioned in our installation docs, the permissions are

• admin:org - read:org (to read the teams + memberships)
• admin:org_hook (to create a webhook that will alert us when memberships change)
• user:
  • read:user (user, to read user profile data)
  • user:email (optional - we attempt with just the GitHub handle, but this is nice to have)

Step-by-step configuration instructions

1. Install the GitHub Integration. See our detailed install instructions for more info.

2. On the integration page, if you have the correct permissions, we will show the option to Sync GitHub Teams to OpsLevel Teams. Click Enabled, and we will begin syncing teams from GitHub.

   

3. After allowing some time for the initial sync, head to the Teams page to see you organization in OpsLevel.

Troubleshooting

1. Teams are synced every 12 hours. If you don't see a team that was created or updated recently, you can hit the manual Update Teams button once an hour.

2. If you don't see all of the members on a team, it means we weren't able to map them by the GitHub Handle, or by their GitHub email if provided. You can add contact information to existing users to help us map them: