Skip to content

Index

Definition of an organization Team, the following properties are supported:

Key Value Description Note
name string The name of the team
description string The description of the team
privacy string The level of privacy this team should have visible or secret
notifications boolean Whether the team members receive notifications when the team is @mentioned
members list[string] List of users that should be a member of the team
skip_members boolean If true, team members will be ignored
skip_non_organization_members boolean If true, users which are not yet organization members can not be added to the team
team_sync list[TeamSync] List of identity provider groups connected to the team via team synchronization GitHub Enterprise Cloud only
external_group_id integer or null The id of the external group connected to the team Enterprise Managed Users (EMU) only

Identity provider integration

The membership of a team can be managed by an identity provider (IdP), with one of these mechanisms:

  • team synchronization (team_sync): up to five IdP groups are connected to the team, available for organizations on GitHub Enterprise Cloud with team synchronization enabled
  • external groups (external_group_id): a single external group is connected to the team, available for organizations that are part of an enterprise using Enterprise Managed Users

Both mechanisms are mutually exclusive. The members of a team connected to an IdP are provisioned by the IdP, so members must not be set for such a team, and the current members of the team are ignored. When an existing team is connected to an external group for the first time, its current members are removed beforehand, as required by GitHub, once the external group has been found. They are restored with their role if the team can not be connected.

The connections to IdP groups are only retrieved from GitHub if the default configuration supports them, i.e. defines the newTeamSync function for team synchronization, or the external_group_id property in newTeam for external groups. If a mechanism is not available for an organization, it is skipped, while missing permissions of the credentials to retrieve them are reported as an error.

Jsonnet Function

orgs.newTeam('<name>') {
  <key>: <value>
}

Validation rules

  • setting privacy must be one of visible or secret, any other value triggers an error
  • specifying a non-empty list of members while skip_members is enabled, triggers an error
  • specifying a user in members that is not yet an organization member while skip_non_organization_members is enabled, triggers an error
  • specifying both team_sync and external_group_id, triggers an error
  • specifying a non-empty list of members for a team connected to an identity provider group, triggers an error
  • specifying the same group id more than once in team_sync, triggers an error
  • specifying more than five groups in team_sync, triggers an error

Example usage

orgs.newOrg('my-project', 'my-org') {
  teams+: [
    orgs.newTeam('committers') {
      description: "The project committers",
      privacy: "visible",
      members+: [
        "alice",
        "bob",
      ],
    },
    orgs.newTeam('admins') {
      description: "The project admins, managed by the identity provider",
      privacy: "secret",
      external_group_id: 1234,
    },
  ],
}

Open in the Playground