teams

Create a team

Changed on

To create a team, the authenticated user must be a member or owner of {org}. By default, organization members can create teams. Organization owners can limit team creation to organization owners. For more information, see "Setting team creation permissions."

When you create a new team, you automatically become a team maintainer without explicitly adding yourself to the optional array of maintainers. For more information, see "About teams".

post/orgs/{org}/teams

Request

  • Base URL: https://api.github.com
  • URL: https://api.github.com/orgs/{org}/teams
  • Auth: none declared

Path parameters

orgstring required

The organization name. The name is not case sensitive.

Request body

namestring required

The name of the team.

descriptionstring

The description of the team.

maintainersstring[]

List GitHub usernames for organization members who will become team maintainers.

repo_namesstring[]

The full name (e.g., "organization-name/repository-name") of repositories to add the team to.

privacy'secret' | 'closed'

The level of privacy this team should have. The options are:
For a non-nested team:

  • secret - only visible to organization owners and members of this team.
  • closed - visible to all members of this organization.
    Default: secret
    For a parent or child team:
  • closed - visible to all members of this organization.
    Default for child team: closed
notification_setting'notifications_enabled' | 'notifications_disabled'

The notification setting the team has chosen. The options are:

  • notifications_enabled - team members receive notifications when the team is @mentioned.
  • notifications_disabled - no one receives notifications.
    Default: notifications_enabled
permission'pull' | 'push'

Closing down notice. The permission that new repositories will be added to the team with when none is specified.

parent_team_idinteger

The ID of a team to set as the parent team.

parent_team_slugstring

The slug of a team to set as the parent team. Ignored when parent_team_id is also provided.

Response

Response

idinteger required

Unique identifier of the team

node_idstring required
urlstring uri required

URL for the team

html_urlstring uri required
namestring required

Name of the team

slugstring required
descriptionstring nullable required
privacy'closed' | 'secret'

The level of privacy this team should have

notification_setting'notifications_enabled' | 'notifications_disabled'

The notification setting the team has set

permissionstring required

Permission that the team will have for its repositories

members_urlstring required
repositories_urlstring uri required
members_countinteger required
repos_countinteger required
created_atstring date-time required
updated_atstring date-time required
ldap_dnstring

The distinguished name (DN) of the LDAP entry to map to a team.

type'enterprise' | 'organization' required

The ownership type of the team

organization_idinteger

Unique identifier of the organization to which this team belongs

enterprise_idinteger

Unique identifier of the enterprise to which this team belongs

Example response

{
  "id": 42,
  "node_id": "MDQ6VGVhbTE=",
  "url": "https://api.github.com/organizations/1/team/1",
  "html_url": "https://github.com/orgs/rails/teams/core",
  "name": "Developers",
  "slug": "justice-league",
  "description": "A great team.",
  "privacy": "closed",
  "notification_setting": "notifications_enabled",
  "permission": "push",
  "members_url": "https://api.github.com/organizations/1/team/1/members{/member}",
  "repositories_url": "https://api.github.com/organizations/1/team/1/repos",
  "parent": {
    "id": 1,
    "node_id": "MDQ6VGVhbTE=",
    "url": "https://api.github.com/organizations/1/team/1",
    "members_url": "https://api.github.com/organizations/1/team/1/members{/member}",
    "name": "Justice League",
    "description": "A great team.",
    "permission": "admin",
    "privacy": "closed",
    "notification_setting": "notifications_enabled",
    "html_url": "https://github.com/orgs/rails/teams/core",
    "repositories_url": "https://api.github.com/organizations/1/team/1/repos",
    "slug": "justice-league",
    "ldap_dn": "uid=example,ou=users,dc=github,dc=com",
    "organization_id": 37,
    "enterprise_id": 42
  },
  "members_count": 3,
  "repos_count": 10,
  "created_at": "2017-07-14T16:53:42Z",
  "updated_at": "2017-08-17T12:37:15Z",
  "organization": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization",
    "name": "github",
    "company": "GitHub",
    "blog": "https://github.com/blog",
    "location": "San Francisco",
    "email": "octocat@github.com",
    "twitter_username": "github",
    "is_verified": true,
    "has_organization_projects": true,
    "has_repository_projects": true,
    "public_repos": 2,
    "public_gists": 1,
    "followers": 20,
    "html_url": "https://github.com/octocat",
    "created_at": "2008-01-14T04:33:35Z",
    "type": "Organization",
    "total_private_repos": 100,
    "owned_private_repos": 100,
    "private_gists": 81,
    "disk_usage": 10000,
    "collaborators": 8,
    "billing_email": "org@example.com",
    "members_can_create_repositories": true,
    "two_factor_requirement_enabled": true,
    "members_allowed_repository_creation_type": "all",
    "members_can_create_public_repositories": true,
    "members_can_create_private_repositories": true,
    "members_can_create_internal_repositories": true,
    "members_can_create_pages": true,
    "members_can_create_public_pages": true,
    "members_can_create_private_pages": true
  },
  "ldap_dn": "cn=Enterprise Ops,ou=teams,dc=github,dc=com",
  "organization_id": 37,
  "enterprise_id": 42
}

Changes

  • 2022-11-28cb7b1b79509eRevision changes
    • breaking

      the response property / became nullable for the status

    • breaking

      the response property / became nullable for the status

    • breaking

      the response property / became nullable for the status

    • breaking

      the response property / became nullable for the status

  • 2022-11-2825796179fcb2Revision changes
    • info

      added the new optional request property