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.

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
  }
}