Synchronizing teams between your identity provider and GitHub

You can manage GitHub team membership through an identity provider (IdP) to automatically add and remove team members in an organization.

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see "GitHub's products."

In this article:

About team synchronization

When you sync a GitHub team with an IdP group, changes to the IdP group are reflected on GitHub automatically, reducing the need for manual updates and custom scripts.

You can configure team synchronization with Azure AD.

Once GitHub teams are connected to an IdP group, your IdP administrator must make team membership changes through the identity provider. For teams connected to an IdP group, the GitHub UI and API to manage team membership are disabled.

To manage repository access for a GitHub team, including teams connected to an IdP group, you must make changes on GitHub through the team's repositories tab. For more information, see "About teams" and "Managing team access to an organization repository." You can also make changes through the API. For more information, see "Team synchronization" on the GitHub Developer documentation.

All team membership changes made through the IdP will appear in the audit log on GitHub as changes made by the team synchronization bot. Team membership data is sent from the identity provider to GitHub once every hour.

Team synchronization is not supported in organizations owned by an enterprise account with SAML enabled.

Requirements for members of synchronized teams

As long as team synchronization is enabled, membership data for a user will synchronize if the individual continues to authenticate using SAML SSO and remains a member of both the connected team and IdP group with the same SSO identity.

Once you connect a team to an IdP group, an existing team or group member can be automatically removed from the team on GitHub and potentially lose access to repositories, if they are not authenticating to the organization using SSO or if they are not also in the connected IdP group.

A removed team member can be added back to a team automatically once they have authenticated to the organization using SSO and are moved to the connected IdP group.

To avoid unintentionally removing team members, we recommend enforcing SAML SSO in your organization, creating new teams to synchronize membership data, and checking IdP group membership before synchronizing existing teams. For more information, see “Enforcing SAML single sign-on for your organization."

Enabling team synchronization

To enable team synchronization for a GitHub Enterprise Cloud organization, you must:

Your Azure AD installation needs the following permissions:

  • Read all users’ full profiles
  • Sign in and read user profile
  • Read directory data
  1. In the top right corner of GitHub, click your profile photo, then click Your profile.

    Profile photo

  2. On the left side of your profile page, under "Organizations", click the icon for your organization.

    organization icons

  3. Under your organization name, click Settings.

    Organization settings button

  4. In the organization settings sidebar, click Security.

    Security settings

  5. Confirm that SAML SSO is enabled. For more information, see "Managing SAML single sign-on for your organization."

  6. Under "Team synchronization", click Enable for your identity provider.

    Enable team synchronization button on security settings page

  7. To confirm team synchronization:

    • If you have IdP access, click Enable team synchronization. You'll be redirected to your identity provider's SAML SSO page and asked to select your account and review the requested permissions.
    • If you don't have IdP access, copy the IdP redirect link and share it with your IdP administrator to continue enabling team synchronization.
      Enable team synchronization redirect button
  8. Review the identity provider tenant information you want to connect to your organization, then click Approve.

    Pending request to enable team synchronization to a specific IdP tenant with option to approve or cancel request

Team maintainers and organization owners can connect a team to an IdP group through team settings on GitHub or through the API. For more information, see "Creating a team and connecting it to an IdP group," "Changing a team’s connected IdP groups," or "Team synchronization" on the GitHub Developer documentation.

Creating a team and connecting it to an IdP group

After team synchronization is enabled, you can create a team and connect it to an IdP group if you:

You can connect up to five IdP groups to a GitHub team, and an IdP group can be assigned to multiple GitHub teams without restriction.

Parent teams cannot synchronize with IdP groups, so your new team can be a child team but not a parent team. For more information, see "About teams."

  1. In the top right corner of GitHub, click your profile photo, then click Your profile.

    Profile photo

  2. On the left side of your profile page, under "Organizations", click the icon for your organization.

    organization icons

  3. Under your organization name, click Settings.

    Organization settings button

  4. Under your organization name, click Teams.

    Teams tab

  5. On the right side of the Teams tab, click New team.

    New team button

  6. Under "Create new team", type the name for your new team.

    Team name field

  7. Optionally, in the "Description" field, type a description of the team.

    Team description field

  8. Under the identity provider name, choose an IdP group using the drop-down menu or prefix search, which uses the first three letters of the group name.

    Connecting a team to an IdP group may remove some team members. For more information, see "Requirements for members of synchronized teams."

    Drop-down menu showing IdP group search results

  9. Decide whether the team will be visible or secret.

    Options for visibility including visible and secret

  10. Click Create team.

To select the organization repositories that you want team members to have access to by default, see "Managing team access to an organization repository." Connected IdP groups will automatically have access to these repositories.

The GitHub team synchronization bot will automatically add members to the GitHub team from the connected IdP groups.

Changing a team's connected IdP groups

After team synchronization is enabled, you can create a team and connect it to an IdP group if you:

Once GitHub teams are connected to an IdP group, your IdP administrator must make team membership changes through the IdP.

You cannot connect an IdP group to a parent GitHub team, but you can connect to a child team. For more information, see "About teams." We recommend creating a new team or removing the nested relationships that make your team a parent team. For more information, see "Moving a team in your organization’s hierarchy" or "Creating a team and connecting it to an IdP group."

You can connect up to five IdP groups to a GitHub team, and an IdP group can be assigned to multiple GitHub teams without restriction.

  1. In the top right corner of GitHub, click your profile photo, then click Your profile.

    Profile photo

  2. On the left side of your profile page, under "Organizations", click the icon for your organization.

    organization icons

  3. Under your organization name, click Settings.

    Organization settings button

  4. Under your organization name, click Teams.

    Teams tab on the organization page

  5. Select the team that you'd like to change the connected IdP groups for.

    List of teams with two teams selected

  6. Optionally, to avoid unintentionally removing team members, visit your identity provider admin portal and confirm that each current team member is also in the identity groups that you want to connect to this team. If you don't have this access to your identity provider, you can reach out to your IdP administrator.

  7. Under the identity provider name, choose an IdP group using the drop-down menu or prefix search, which uses the first three letters of the group name.

    Connecting a team to an IdP group may remove some team members. For more information, see "Requirements for members of synchronized teams."

    Drop-down menu showing IdP group search results

  8. Optionally, to disconnect a connected IdP group, to the right of the connected IdP group name, click the . Any team members that were assigned to the GitHub team through the IdP group will be removed from the team.

    Unselect a connected IdP group from the GitHub team

  9. To confirm, click Save changes.

To modify the organization repositories that you want team members to have access to by default, see "Managing team access to an organization repository." Connected IdP groups will automatically have access to these repositories.

Disabling team synchronization

When you disable team synchronization, any team members that were assigned to a GitHub team through the IdP group are removed from the team and may lose access to repositories.

  1. In the top right corner of GitHub, click your profile photo, then click Your profile.

    Profile photo

  2. On the left side of your profile page, under "Organizations", click the icon for your organization.

    organization icons

  3. Under your organization name, click Settings.

    Organization settings button

  4. In the organization settings sidebar, click Security.

    Security settings

  5. Under "Team synchronization", click Disable team synchronization.

    Disable team synchronization

Ask a human

Can't find what you're looking for?

Contact us