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. If your sync is running but users are missing from teams, see Troubleshooting: Users Not Appearing After Sync below.

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. Note: If a user has marked their email as private in their GitHub profile settings, the GitHub API will not return it - even if the email appears visible when viewing their profile in a browser. Email matching will not work for these users.
  • 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

GitHubs Team Sync Schedule

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.

Ensure User contact details are updated

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:

Users Not Appearing After Sync

If specific users are missing from OpsLevel teams, the most likely cause is that OpsLevel couldn't match the GitHub user to an OpsLevel user. OpsLevel tries three matching methods in order. Work through the table below to identify which applies to your situation:

Recommended resolution priority:

1. Add the GitHub handle to the user's OpsLevel contact methods — this is the most reliable matching method and doesn't depend on GitHub privacy settings.
2. Have the user set their work email as their public email in GitHub profile settings.
3. Ensure the GitHub display name matches the OpsLevel full name exactly.

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.