团队同步

使用 REST API 管理 GitHub Enterprise Cloud 团队与外部标识提供者 (IdP) 组之间的连接。

关于团队同步

要使用这些终结点，经过身份验证的用户必须是团队维护员或与团队关联的组织所有者。用于身份验证的令牌还需要获得授权才能与 IdP (SSO) 提供程序一起使用。有关详细信息，请参阅“授权组织 personal access token 以用于 SAML 单一登录”。

可以通过 IdP 使用团队同步管理 GitHub Enterprise Cloud 团队成员。必须启用团队同步才能使用这些终结点。有关详细信息，请参阅管理组织的团队同步。

注意：这些终结点不能与 Enterprise Managed Users 一起使用。若要详细了解如何管理 organization with managed users，请参阅“外部组”。

List IdP groups for an organization

Works with GitHub Apps

Lists IdP groups available in an organization.

Parameters

Headers
名称, Type, 说明
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
名称, Type, 说明
`org`stringRequired The organization name. The name is not case sensitive.
Query parameters
名称, Type, 说明
`per_page`integer The number of results per page (max 100). Default: `30`
`page`string Page token
`q`string Filters the results to return only those that begin with the value specified by this parameter. For example, a value of `ab` will return results that begin with "ab".

HTTP response status codes

Status code	说明
`200`	OK

Code samples

get/orgs/{org}/team-sync/groups

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/team-sync/groups

Response

Status: 200

{
  "groups": [
    {
      "group_id": "123",
      "group_name": "Octocat admins",
      "group_description": "The people who configure your octoworld."
    },
    {
      "group_id": "456",
      "group_name": "Octocat docs members",
      "group_description": "The people who make your octoworld come to life."
    }
  ]
}

List IdP groups for a team

List IdP groups connected to a team on GitHub Enterprise Cloud.

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

Note: You can also specify a team by org_id and team_id using the route GET /organizations/{org_id}/team/{team_id}/team-sync/group-mappings.

Parameters

Headers
名称, Type, 说明
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
名称, Type, 说明
`org`stringRequired The organization name. The name is not case sensitive.
`team_slug`stringRequired The slug of the team name.

HTTP response status codes

Status code	说明
`200`	OK

Code samples

get/orgs/{org}/teams/{team_slug}/team-sync/group-mappings

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/teams/TEAM_SLUG/team-sync/group-mappings

Response

Status: 200

{
  "groups": [
    {
      "group_id": "123",
      "group_name": "Octocat admins",
      "group_description": "The people who configure your octoworld."
    },
    {
      "group_id": "456",
      "group_name": "Octocat docs members",
      "group_description": "The people who make your octoworld come to life."
    }
  ]
}

Create or update IdP group connections

Creates, updates, or removes a connection between a team and an IdP group. When adding groups to a team, you must include all new and existing groups to avoid replacing existing groups with the new ones. Specifying an empty groups array will remove all connections for a team.

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

Note: You can also specify a team by org_id and team_id using the route PATCH /organizations/{org_id}/team/{team_id}/team-sync/group-mappings.

Parameters

Headers

名称, Type, 说明

acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters

名称, Type, 说明

orgstringRequired

The organization name. The name is not case sensitive.

team_slugstringRequired

The slug of the team name.

Body parameters

名称, Type, 说明

groupsarray of objects

The IdP groups you want to connect to a GitHub team. When updating, the new groups object will replace the original one. You must include any existing groups that you don't want to remove.

Properties of groups

名称, Type, 说明
`group_id`stringRequired ID of the IdP group.
`group_name`stringRequired Name of the IdP group.
`group_description`stringRequired Description of the IdP group.

HTTP response status codes

Status code	说明
`200`	OK

Code samples

patch/orgs/{org}/teams/{team_slug}/team-sync/group-mappings

curl \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/teams/TEAM_SLUG/team-sync/group-mappings \
  -d '{"groups":[{"group_id":"123","group_name":"Octocat admins","group_description":"string"}]}'

Response

Status: 200

{
  "groups": [
    {
      "group_id": "123",
      "group_name": "Octocat admins",
      "group_description": "The people who configure your octoworld."
    },
    {
      "group_id": "456",
      "group_name": "Octocat docs members",
      "group_description": "The people who make your octoworld come to life."
    }
  ]
}

List IdP groups for a team (Legacy)

Deprecation Notice: This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new List IdP groups for a team endpoint.

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

List IdP groups connected to a team on GitHub Enterprise Cloud.

Parameters

Headers
名称, Type, 说明
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
名称, Type, 说明
`team_id`integerRequired The unique identifier of the team.

HTTP response status codes

Status code	说明
`200`	OK
`403`	Forbidden
`404`	Resource not found

Code samples

get/teams/{team_id}/team-sync/group-mappings

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/teams/TEAM_ID/team-sync/group-mappings

Response

Status: 200

{
  "groups": [
    {
      "group_id": "123",
      "group_name": "Octocat admins",
      "group_description": "The people who configure your octoworld."
    },
    {
      "group_id": "456",
      "group_name": "Octocat docs members",
      "group_description": "The people who make your octoworld come to life."
    }
  ]
}

Create or update IdP group connections (Legacy)

Deprecation Notice: This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new Create or update IdP group connections endpoint.

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

Creates, updates, or removes a connection between a team and an IdP group. When adding groups to a team, you must include all new and existing groups to avoid replacing existing groups with the new ones. Specifying an empty groups array will remove all connections for a team.

Parameters

Headers

名称, Type, 说明

acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters

名称, Type, 说明

team_idintegerRequired

The unique identifier of the team.

Body parameters

名称, Type, 说明

groupsarray of objectsRequired

The IdP groups you want to connect to a GitHub team. When updating, the new groups object will replace the original one. You must include any existing groups that you don't want to remove.

Properties of groups

名称, Type, 说明
`group_id`stringRequired ID of the IdP group.
`group_name`stringRequired Name of the IdP group.
`group_description`stringRequired Description of the IdP group.
`id`string
`name`string
`description`string

synced_atstring

HTTP response status codes

Status code	说明
`200`	OK
`403`	Forbidden
`422`	Validation failed, or the endpoint has been spammed.

Code samples

patch/teams/{team_id}/team-sync/group-mappings

curl \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/teams/TEAM_ID/team-sync/group-mappings \
  -d '{"groups":[{"group_id":"123","group_name":"Octocat admins","description":"The people who configure your octoworld.","group_description":"string"}]}'

Response

Status: 200

{
  "groups": [
    {
      "group_id": "123",
      "group_name": "Octocat admins",
      "group_description": "The people who configure your octoworld."
    }
  ]
}