Skip to main content
Buildkite 조직을 연결하면 CloudThinker 에이전트가 파이프라인 상태를 추적하고, 로그와 어노테이션으로 실패한 빌드를 분류하고, 에이전트와 클러스터 용량을 확인하고, 잡 재시도나 배포 게이트 해제 같은 승인 게이트 작업을 실행할 수 있습니다. Buildkite는 Buildkite가 호스팅하는 MCP 서버를 통해 API 액세스 토큰으로 인증합니다. 토큰의 스코프가 성공하는 작업을 결정하므로, 부여한 스코프가 곧 에이전트가 접근할 수 있는 범위의 상한입니다.

​
사전 요구 사항

  • 모니터링하려는 조직에 접근할 수 있는 Buildkite 계정.
  • 아래 “필수 권한”에 나열된 읽기 스코프를 가진 API 액세스 토큰.
  • 승인 게이트 작업에는 동일한 토큰에 write_builds 스코프가 필요합니다.
모니터링과 분류는 읽기 스코프만으로 동작합니다. retry, unblock, rebuild, cancel에는 토큰에 write_builds가 추가로 필요합니다.

​
설정

1

API 액세스 토큰 생성

Buildkite에서 Personal Settings → API Access Tokens → New API Access Token(buildkite.com/user/api-access-tokens/new)으로 이동합니다:
  • Description: cloudthinker
  • Organization access: CloudThinker가 접근할 조직 선택
  • REST API scopes: read_organizations, read_pipelines, read_builds, read_build_logs, read_artifacts, read_agents, read_clusters, read_user — 빌드 제어를 사용할 경우에만 write_builds 추가
  • Expiry: 유효 기간을 선택하고 교체 계획 수립
토큰은 즉시 복사하세요 — Buildkite는 한 번만 표시합니다.
2

CloudThinker에서 연결 추가

Connections → Buildkite로 이동하여 입력합니다:
  • Token: 방금 생성한 API 액세스 토큰
Connect를 클릭합니다. CloudThinker가 자격 증명을 확인하고 Connected 상태를 표시합니다.
API 액세스 토큰은 생성 직후 복사하세요. 분실하면 새 토큰을 만들어야 합니다.

​
연결 세부 정보

CloudThinker는 토큰에서 조직을 자동으로 확인하므로 org slug를 설정할 필요가 없습니다. 연결은 Buildkite가 호스팅하는 MCP 서버 https://mcp.buildkite.com/direct를 사용하며, 토큰을 Buildkite REST API로 그대로 전달합니다.

​
필수 권한

에이전트에게 맡기려는 작업에 해당하는 스코프만 부여하세요.
최소 권한을 따르세요: 모니터링 전용 연결에서는 write_builds를 제외합니다. 에이전트는 모든 읽기 기능을 그대로 사용하고, 네 가지 제어 작업은 승인 게이트에 의존하기 전에 Buildkite에서 먼저 실패합니다.

​
에이전트 기능

연결하면 에이전트는 Buildkite 파이프라인, 빌드, 로그, 아티팩트, 에이전트에 대한 읽기 권한을 갖습니다. 수동 게이트에서 대기 중인 빌드는 Buildkite API에서 passed로 보고됩니다. CloudThinker는 해당 빌드를 게이트 대기로 표시하고 블록 단계의 이름을 알려주며 성공률 계산에서 제외합니다. 따라서 보류된 배포가 정상 파이프라인으로 보고되는 일은 없습니다.

​
연결 확인

​
예시 프롬프트

파이프라인이 많은 조직에서는 단일 파이프라인으로 범위를 좁혀 요청하면 집중된 결과를 얻을 수 있습니다.

​
문제 해결

토큰이 유효하지 않거나 만료 또는 취소되었습니다. MCP 핸드셰이크는 잘못된 토큰으로도 성공하고 도구를 실행할 때 비로소 실패하므로, 연결 상태가 정상이라고 해서 토큰이 동작한다는 증거는 아닙니다. 새 API 액세스 토큰을 만들고 다시 연결하세요.
토큰에 스코프가 부족합니다. 읽기에는 read_organizations, read_pipelines, read_builds, read_build_logs, read_artifacts, read_agents, read_clusters가 필요합니다. Buildkite에서 토큰의 스코프를 수정하세요 — 새 토큰을 만들 필요는 없습니다.
토큰에 write_builds가 없습니다. Buildkite에서 해당 스코프를 추가하거나, 연결을 읽기 전용으로 두고 Buildkite에서 직접 작업하세요.
수동 게이트이며 이미 처리되어 있습니다. 최신 빌드는 게이트에 걸려 있는 동안 성공률에서 제외됩니다. 에이전트가 게이트 상태를 unknown으로 보고하면 게이트 확인 자체가 실패한 것으로, 대개 레이트 리밋 때문이며 이 경우에도 빌드는 제외됩니다. unknown은 게이트가 없다는 뜻이 아닙니다.
Buildkite가 slug를 요구하는 자리에 파이프라인 이름을 사용했습니다. 에이전트에게 파이프라인 목록을 요청하고 그 출력의 slug를 사용하세요.
한 요청에 파이프라인이나 빌드가 너무 많습니다. 단일 파이프라인으로 범위를 좁히거나 최근 빌드 수를 줄여 요청하세요.

​
보안

  • 최소 권한 — 에이전트가 사용 사례에 필요한 권한만 부여하세요. 읽기 전용으로 시작한 후 필요에 따라 확장하세요.
  • 기본 읽기 전용 — 에이전트가 이 연결을 통해 변경 작업을 수행하게 할 것이 아니라면 읽기 전용 자격증명을 사용하세요.
  • 자격증명 교체 — 정기 일정에 따라 키와 토큰을 교체하세요. 연결을 업데이트하면 CloudThinker가 새 값을 자동으로 반영합니다.
  • 오프보딩 시 취소 — 연결을 삭제하거나 팀원이 퇴사할 때 프로바이더에서 자격증명을 제거하세요.
  • 빌드 제어에는 승인 유지 — retry, unblock, rebuild, cancel은 승인 게이트를 유지하세요. 언블록은 누군가 의도적으로 둔 게이트, 보통 배포 게이트를 해제합니다.
  • 승인뿐 아니라 토큰 스코프로 제한 — 토큰 스코프는 Buildkite가 강제합니다. write_builds가 없는 토큰은 CI 상태를 전혀 변경할 수 없습니다.

​
관련 항목

CircleCI 연결

파이프라인 상태, 빌드 로그 분류, 승인 게이트 제어

승인

승인 게이트 작업의 동작 방식