Teams

All actions against teams require at a minimum an authenticated user who is a member of the Owners team in the :org being managed. Additionally, OAuth users require the “read:org” scope.

List teams

GET /orgs/:org/teams

Response

Status: 200 OK
[
  {
    "url": "https://api.centelar.com/teams/1",
    "name": "Owners",
    "id": 1
  }
]

Get team

GET /teams/:id

Response

Status: 200 OK
{
  "url": "https://api.centelar.com/teams/1",
  "name": "Owners",
  "id": 1,
  "permission": "admin",
  "members_count": 3,
  "repos_count": 10,
  "organization": {
    "login": "centelar",
    "id": 1,
    "url": "https://api.centelar.com/orgs/centelar",
    "avatar_url": "https://centelar.com/images/error/octocat_happy.gif"
  }
}

Create team

In order to create a team, the authenticated user must be an owner of :org.

POST /orgs/:org/teams

Parameters

Name Type Description
name string Required. The name of the team.
repo_names array of strings The repositories to add the team to.
permission string The permission to grant the team. Can be one of:
* pull - team members can pull, but not push to or administer these repositories.
* push - team members can pull and push, but not administer these repositories.
* admin - team members can pull, push and administer these repositories.
Default: pull

Example

{
  "name": "new team",
  "permission": "push",
  "repo_names": [
    "centelar/dotfiles"
  ]
}

Response

Status: 201 Created
{
  "url": "https://api.centelar.com/teams/1",
  "name": "Owners",
  "id": 1,
  "permission": "admin",
  "members_count": 3,
  "repos_count": 10,
  "organization": {
    "login": "centelar",
    "id": 1,
    "url": "https://api.centelar.com/orgs/centelar",
    "avatar_url": "https://centelar.com/images/error/octocat_happy.gif"
  }
}

Edit team

In order to edit a team, the authenticated user must be an owner of the org that the team is associated with.

PATCH /teams/:id

Parameters

Name Type Description
name string Required. The name of the team.
permission string The permission to grant the team. Can be one of:
* pull - team members can pull, but not push to or administer these repositories.
* push - team members can pull and push, but not administer these repositories.
* admin - team members can pull, push and administer these repositories. Default: pull

Example

{
  "name": "new team name",
  "permission": "push"
}

Response

Status: 200 OK
{
  "url": "https://api.centelar.com/teams/1",
  "name": "Owners",
  "id": 1,
  "permission": "admin",
  "members_count": 3,
  "repos_count": 10,
  "organization": {
    "login": "centelar",
    "id": 1,
    "url": "https://api.centelar.com/orgs/centelar",
    "avatar_url": "https://centelar.com/images/error/octocat_happy.gif"
  }
}

Delete team

In order to delete a team, the authenticated user must be an owner of the org that the team is associated with.

DELETE /teams/:id

Response

Status: 204 No Content

List team members

In order to list members in a team, the authenticated user must be a member of the team.

GET /teams/:id/members

Response

Status: 200 OK
[
  {
    "login": "octocat",
    "id": 1,
    "avatar_url": "https://centelar.com/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "url": "https://api.centelar.com/users/octocat",
    "html_url": "https://centelar.com/octocat",
    "followers_url": "https://api.centelar.com/users/octocat/followers",
    "following_url": "https://api.centelar.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.centelar.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.centelar.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.centelar.com/users/octocat/subscriptions",
    "organizations_url": "https://api.centelar.com/users/octocat/orgs",
    "repos_url": "https://api.centelar.com/users/octocat/repos",
    "events_url": "https://api.centelar.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.centelar.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
]

Get team member

In order to get if a user is a member of a team, the authenticated user must be a member of the team.

GET /teams/:id/members/:username

Response if user is a member

Status: 204 No Content

Response if user is not a member

Status: 404 Not Found

Add team member

In order to add a user to a team, the authenticated user must have ‘admin’ permissions to the team or be an owner of the org that the team is associated with.

PUT /teams/:id/members/:username

Response

Status: 204 No Content

If you attempt to add an organization to a team, you will get this:

Status: 422 Unprocessable Entity
{
  "message": "Validation Failed",
  "errors": [
    {
      "code": "org",
      "field": "user",
      "resource": "TeamMember"
    }
  ]
}

Remove team member

In order to remove a user from a team, the authenticated user must have ‘admin’ permissions to the team or be an owner of the org that the team is associated with. NOTE: This does not delete the user, it just remove them from the team.

DELETE /teams/:id/members/:username

Response

Status: 204 No Content

List team repos

GET /teams/:id/repos

Response

Status: 200 OK
[
  {
    "id": 1296269,
    "owner": {
      "login": "octocat",
      "id": 1,
      "avatar_url": "https://centelar.com/images/error/octocat_happy.gif",
      "gravatar_id": "somehexcode",
      "url": "https://api.centelar.com/users/octocat",
      "html_url": "https://centelar.com/octocat",
      "followers_url": "https://api.centelar.com/users/octocat/followers",
      "following_url": "https://api.centelar.com/users/octocat/following{/other_user}",
      "gists_url": "https://api.centelar.com/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.centelar.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.centelar.com/users/octocat/subscriptions",
      "organizations_url": "https://api.centelar.com/users/octocat/orgs",
      "repos_url": "https://api.centelar.com/users/octocat/repos",
      "events_url": "https://api.centelar.com/users/octocat/events{/privacy}",
      "received_events_url": "https://api.centelar.com/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "description": "This your first repo!",
    "private": false,
    "fork": false,
    "url": "https://api.centelar.com/repos/octocat/Hello-World",
    "html_url": "https://centelar.com/octocat/Hello-World",
    "clone_url": "https://centelar.com/octocat/Hello-World.git",
    "git_url": "git://centelar.com/octocat/Hello-World.git",
    "ssh_url": "git@centelar.com:octocat/Hello-World.git",
    "svn_url": "https://svn.centelar.com/octocat/Hello-World",
    "mirror_url": "git://git.example.com/octocat/Hello-World",
    "homepage": "https://centelar.com",
    "language": null,
    "forks_count": 9,
    "stargazers_count": 80,
    "watchers_count": 80,
    "size": 108,
    "default_branch": "master",
    "open_issues_count": 0,
    "has_issues": true,
    "has_wiki": true,
    "has_downloads": true,
    "pushed_at": "2011-01-26T19:06:43Z",
    "created_at": "2011-01-26T19:01:12Z",
    "updated_at": "2011-01-26T19:14:43Z",
    "permissions": {
      "admin": false,
      "push": false,
      "pull": true
    }
  }
]

Check if a team manages a repository

GET /teams/:id/repos/:owner/:repo

Response if repository is managed by this team

Status: 204 No Content

Response if repository is not managed by this team

Status: 404 Not Found

Add team repository

In order to add a repository to a team, the authenticated user must be an owner of the org that the team is associated with. Also, the repository must be owned by the organization, or a direct fork of a repository owned by the organization.

PUT /teams/:id/repos/:org/:repo

Response

Status: 204 No Content

If you attempt to add a repository to a team that is not owned by the organization, you get:

Status: 422 Unprocessable Entity
{
  "message": "Validation Failed",
  "errors": [
    {
      "code": "not_owned",
      "field": "repository",
      "resource": "TeamMember"
    }
  ]
}

Remove team repository

In order to remove a repository from a team, the authenticated user must be an owner of the org that the team is associated with. Also, since the Owners team always has access to all repositories in the organization, repositories cannot be removed from the Owners team. NOTE: This does not delete the repository, it just removes it from the team.

DELETE /teams/:id/repos/:owner/:repo

Response

Status: 204 No Content

List user teams

List all of the teams across all of the organizations to which the authenticated user belongs. This method requires user or repo scope when authenticating via OAuth.

GET /user/teams

Response

Status: 200 OK
[
  {
    "url": "https://api.centelar.com/teams/1",
    "name": "Owners",
    "id": 1,
    "permission": "admin",
    "members_count": 3,
    "repos_count": 10,
    "organization": {
      "login": "centelar",
      "id": 1,
      "url": "https://api.centelar.com/orgs/centelar",
      "avatar_url": "https://centelar.com/images/error/octocat_happy.gif"
    }
  }
]