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 map users from GitHub to users in OpsLevel, and then map them to teams. We map users via:
  • GitHub handle - match GitHub users to OpsLevel users if the GitHub handle has been added to users' Contacts method in OpsLevel.
  • Email - match on email if we have permission to read the email, and it's not obfuscated by the GitHub Organization.
  • Name - if the GitHub full name matches the OpsLevel full name (case insensitive).

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:

   

FAQs

If I delete a team from GitHub, does that happen automatically in OpsLevel or will I have to do that manually?

We do not sync deleted teams/users from GitHub. Removal of teams/users from OpsLevel is manual at this time.