Cluster maintainers

Cluster maintainers permissions can be assigned to a list of Users or teams, or both. This grants assignees the ability to manage the Buildkite clusters they maintain.

Cluster maintainer data model

id The ID of the cluster maintainer assignment.
actor Metadata on the assigned User or Team

List cluster maintainers

Returns a list of maintainers on a cluster.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/maintainers"

[
    {
        "id": "f6cf1097-c9c5-4492-885f-a2d3281a07dd",
        "actor": {
            "id": "01973824-0c57-45ae-a440-638fceb3ec06",
            "graphql_id": "VXNlci0tLTAxOTczODI0LTBjNTctNDVhZS1hNDQwLTYzOGZjZWIzZWMwNg==",
            "name": "Staff",
            "email": "staff@example.com",
            "type": "user"
        }
    },
    {
        "id": "282a043f-4d4f-4db5-ac9a-58673ae02caf",
        "actor": {
            "id": "0da645b7-9840-428f-bd80-0b92ee274480",
            "graphql_id": "VGVhbS0tLTBkYTY0NWI3LTk4NDAtNDI4Zi1iZDgwLTBiOTJlZTI3NDQ4MA==",
            "slug": "Developers",
            "type": "team"
        }
    }
]

Required scope: read_clusters

Success response: 200 OK

Get a cluster maintainer

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/maintainers/{id}"

{
    "id": "282a043f-4d4f-4db5-ac9a-58673ae02caf",
    "actor": {
        "id": "0da645b7-9840-428f-bd80-0b92ee274480",
        "graphql_id": "VGVhbS0tLTBkYTY0NWI3LTk4NDAtNDI4Zi1iZDgwLTBiOTJlZTI3NDQ4MA==",
        "slug": "Developers",
        "type": "team"
    }
}

Required scope: read_clusters

Success response: 200 OK

Create a cluster maintainer

Assigns cluster maintainer permissions to a user or team.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/maintainers" \
  -H "Content-Type: application/json" \
  -d '{ "team": "0da645b7-9840-428f-bd80-0b92ee274480" }'

{
    "id": "282a043f-4d4f-4db5-ac9a-58673ae02caf",
    "actor": {
        "id": "0da645b7-9840-428f-bd80-0b92ee274480",
        "graphql_id": "VGVhbS0tLTBkYTY0NWI3LTk4NDAtNDI4Zi1iZDgwLTBiOTJlZTI3NDQ4MA==",
        "slug": "Developers",
        "type": "team"
    }
}

Cluster maintainer permission target

Cluster maintainer permissions can be targeted to either a user or team by specifying either a user or team field as the target in the request body, along with the target's UUID for its value.

Target Value Example request body
Target user Value UUID of the user Example request body { "user: "282a043f-4d4f-4db5-ac9a-58673ae02caf" }
Target team Value UUID of the team Example request body { "team: "0da645b7-9840-428f-bd80-0b92ee274480" }

Required scope: write_clusters

Success response: 201 Created

Error responses:

422 Unprocessable Entity { "message": "Validation failed: Reason for failure" }

Remove a cluster maintainer

Remove cluster maintainer permissions from a user or team.

curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{id}"

Required scope: write_clusters

Success response: 204 No Content

Error responses:

422 Unprocessable Entity { "message": "Validation failed: Reason cluster maintainer permission could not be deleted" }