Teams

A collection of common tasks with teams using the GraphQL API.

You can test out the Buildkite GraphQL API using the Buildkite explorer. This includes built-in documentation under the Docs panel.

Create a team

Create a new team.

First, get the organization ID:

query getOrganizationId {
  organization(slug: "organization-slug") {
    id
  }
}

Then use the ID to create a new team within the organization:

mutation CreateTeam {
  teamCreate(input: {
    organizationID: "organization-id",
    name: "team-name",
    privacy: SECRET,
    isDefaultTeam: false,
    defaultMemberRole: MEMBER
  }) {
    organization {
      uuid
      teams(first: 1, order: RECENTLY_CREATED) {
        count
        edges {
          node {
            name
          }
        }
      }
    }
  }
}

Add an existing organization user to a team

Add an organization member to a team. This does not create a new user.

First, get a list of teams in the organization, to get the team ID:

query getOrgTeams {
  organization(slug: "organization-slug") {
    teams(first: 500) {
      edges {
        node {
          name
          id
        }
      }
    }
  }
}

Then, add a team member. You can get the user-id using the example in Search for organization members.

clientMutationId is null when the mutation is successful.

mutation addTeamMember {
  teamMemberCreate(input: {teamID: "team-id", userID: "user-id"}) {
    clientMutationId
  }
}

Remove a team member

This deletes a user from a team, but not from the organization.

First, get a list of teams and members, to get the team IDs and current memberships:

query TeamMembersQuery {
  organization(slug: "organization-slug") {
    teams(first: 500) {
      edges {
        node {
          name
          id
          members(first: 100) {
            edges {
              node {
                role
                id
                user {
                  name
                  email
                  id
                }
              }
            }
          }
        }
      }
    }
  }
}

Then delete a team member. Check that you have the team member ID and not the user ID:

clientMutationId is null when the mutation is successful.

mutation deleteTeamMember {
  teamMemberDelete(input: {id: "team-member-id"}) {
    clientMutationId
  }
}

Get pipelines by team

To get the first 100 pipelines managed by the first 100 teams, use the following query.

query getPipelinesByTeam {
  organization(slug: "organization-slug") {
    id
    name
    teams(first: 100) {
      pageInfo {
        hasNextPage
        endCursor
      }
      edges {
        node {
          name
          pipelines(first: 100) {
            pageInfo {
              hasNextPage
              endCursor
            }
            edges {
              node {
                pipeline {
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}

If you have more than 100 teams or more than 100 pipelines per team, use the pagination information in pageInfo to get the next results page.

Search for team names and retrieve the teams' members

The following query retrieves members of one or more teams within a Buildkite organization, along with each team member's role, based on a partial match to the teams' name specified in the query. This query finds the first 200 members of the first team containing the letters "My te" (for example, "My team"), noting that any letters specified are case insensitive.

query GetTeamsAndTheirMembers {
  organization(slug:"organization-slug") {
    teams(first:1, search:"My te") {
      edges {
        node {
          name
          members(first:200) {
            edges {
              node {
                role
                user {
                  name
                  email
                }
              }
            }
          }
        }
      }
    }
  }
}

Get members from a specific team

The following query retrieves members of a team, along with each team member's roles, which requires both the Buildkite organization and team slugs, separated by a /. This query finds the first 10 members of the team with slug my-team within the Buildkite organization with slug organization-slug.

query GetTeamMember {
  team(slug: "organization-slug/my-team") {
    id
    members(first:10) {
      edges {
        node {
          role
          user {
            name
            email
          }
        }
      }
    }
  }
}

Set teams' pipeline edit access to READ_ONLY or BUILD_AND_READ

Remove edit access from existing teams. This is helpful when you want to centralize pipeline edit permissions to a single system user, controlled by an organization admin.

First, walk through all teams:

query Teams {
  organization(slug: "organization-slug") {
    teams(first: 500) {
      edges {
        node {
          slug
        }
      }
    }
  }
}

Then, get the team pipeline IDs from the team slugs. Use the id returned here as the team-pipeline-id in the next step.

query TeamPipelineIDs {
  team(slug: "organization-slug/team-slug") {
    pipelines(first: 500) {
      edges {
        node {
          id
        }
      }
    }
  }
}

Finally, update all pipelines in a team to have either READ_ONLY or BUILD_AND_READ access:

mutation UpdateTeamPipelineReadonly {
  teamPipelineUpdate(input: {
    id: "team-pipeline-id",
    accessLevel: BUILD_AND_READ
  }) {
    teamPipeline {
      permissions {
        teamPipelineDelete {
          allowed
          code
          message
        }
        teamPipelineUpdate {
          allowed
          code
          message
        }
      }
    }
    clientMutationId
  }
}