Buildkite

buildkite-mcp-server

Servidor do Model Context Protocol (MCP) que expõe dados do Buildkite (pipelines, builds, jobs, testes) para ferramentas e editores de IA.

A documentação completa está disponível em buildkite.com/docs/apis/mcp-server.

---

Repetir builds com permissões limitadas

O conjunto de ferramentas retries permite investigar falhas e repetir jobs sem acesso mais amplo de gravação em builds. Ele inclui list_builds, get_build, wait_for_build, list_jobs, get_job, search_logs, tail_logs, read_logs, retry_job e retry_failed_jobs. Ele requer os escopos read_builds, read_build_logs e retry_builds, não write_builds.

buildkite-mcp-server stdio --enabled-toolsets retries

retry_failed_jobs repete apenas falhas de infraestrutura; use sua opção dry_run para inspecionar as repetições propostas sem executá-las. retry_job repete um job específico. Ambos são ferramentas que alteram dados e são excluídos por --read-only. O conjunto de ferramentas não expõe operações de criação, reconstrução, cancelamento ou desbloqueio. As ferramentas de repetição existentes continuam disponíveis em builds; selecionar builds ou all ainda requer write_builds para as outras alterações.

A API do Buildkite precisa ter o recurso RetryBuildsScope habilitado para que o proprietário do token aceite retry_builds; os tokens write_builds existentes continuam sendo aceitos. O OAuth do MCP hospedado pode selecionar esse conjunto de ferramentas usando /mcp/x/retries assim que o servidor hospedado adotar uma versão que o inclua. Selecionar conjuntos de ferramentas por meio de cabeçalhos de solicitação não altera os escopos OAuth de um token existente.

Para consumidores da biblioteca, WithDisabledToolsets e os conjuntos de ferramentas desabilitados pela fábrica HTTP excluem todos os membros desses conjuntos, mesmo por meio de grupos sobrepostos. Por exemplo, desabilitar logs também remove as ferramentas de log de retries; desabilitar retries remove suas ferramentas de inspeção e repetição de outros grupos.

---

Configurar pipelines do GitHub Actions

create_pipeline e update_pipeline aceitam provider_settings e branch_configuration do GitHub. Omita as chaves do provedor para usar os padrões da API na criação ou mantê-las inalteradas na atualização. Um false explícito é preservado. Defina filter_condition ou pull_request_branch_filter_configuration como null para limpá-los; uma string vazia é enviada como string vazia. Defina branch_configuration: null na atualização para limpar um filtro de branch existente. Na criação, um filtro de branch omitido, nulo ou vazio usa o padrão nulo da API. As respostas completas de get_pipeline e list_pipelines preservam as configurações do GitHub compatíveis. As strings de resposta do go-buildkite não distinguem nulo de vazio; portanto, não reconstrua atualizações parciais a partir dos dados retornados.

Siga a configuração manual do GitHub Actions. Mantenha skip_queued_branch_builds e cancel_running_branch_builds em todo o branch como false para evitar ignorar ou cancelar builds de workflows irmãos. Use create_webhook: false: as configurações do provedor não provisionam um gatilho dedicado do GitHub Actions nem seu webhook, e as ferramentas de webhook existentes criam webhooks tradicionais de repositório. A disponibilidade do recurso no servidor e as permissões do token continuam se aplicando; aceitar as configurações não comprova a execução do workflow.

Na criação, forneça um configuration não vazio ou um pipeline_template_uuid aprovado, mas não ambos. Na atualização, omita pipeline_template_uuid para manter a atribuição, forneça um UUID para atribuir um modelo sem configuration ou envie null para removê-lo. A remoção pode incluir um configuration substituto; a API aplica os requisitos de configuração e a política de modelos da organização. As respostas completas do pipeline mantêm os UUIDs atribuídos; o go-buildkite omite o campo quando a atribuição na resposta é nula ou está ausente.

Use get_pipeline_github_webhook_processing, enable_pipeline_github_webhook_processing e disable_pipeline_github_webhook_processing para inspecionar ou alterar o processamento de webhooks tradicionais do GitHub. Eles usam GET/PUT/DELETE github-webhooks, não o endpoint de criação POST webhook. Eles não excluem webhooks de repositório nem alteram gatilhos dedicados do GitHub Actions. As respostas preservam enabled e os metadados anuláveis disabled_at e disabled_by; disabled_by é um nome de usuário. Os três exigem Full Access, um pipeline do GitHub ou GitHub Enterprise e a inscrição da organização em gatilhos de webhook expandidos. GET exige read_pipelines; habilitar/desabilitar exige write_pipelines e essas operações são excluídas no modo somente leitura. Um 404 pode significar que os controles não estão disponíveis, não que o pipeline esteja ausente. Os erros da API são retornados sem tratar a falha como um estado desabilitado.

Esses contratos são cobertos por fixtures HTTP sintéticas locais. Disponibilidade hospedada, permissões, persistência e execução de workflows exigem verificação separada; o sucesso local não comprova suporte no ambiente implantado. O gerenciamento de gatilhos dedicados do GitHub Actions não está incluído.

---

Comparar builds

A ferramenta somente leitura compare_builds do conjunto de ferramentas investigations responde a perguntas como “O que mudou desde a última vez que este build passou em main?”. Informe org_slug, pipeline_slug e o build_number de destino. Ela seleciona o build anterior criado mais recentemente que esteja atualmente aprovado no mesmo pipeline e no branch exato. Não é necessário que o baseline já tivesse sido aprovado quando o build de destino começou. Informe baseline_build_number para comparar com um build específico desse pipeline, inclusive um build com falha ou em outro branch.

A resposta identifica o baseline e a regra de seleção, contabiliza os resultados de todos os jobs e retorna até 100 comparações de jobs, priorizando etapas que começaram a falhar, se recuperaram ou continuam falhando. A correspondência usa chaves de etapa, tipo de job, valores de matriz e índice/total de execução paralela. Quando ambos os jobs não têm chaves, ela recorre ao nome exato não vazio, além do tipo, chave do grupo, valores de matriz e índice/total de execução paralela, somente quando essa combinação é única em cada build. Os pares correspondentes expõem match_method: "step_key" ou "name_fallback"; correspondências alternativas incluem um aviso de que são heurísticas. Jobs sem nome e sem chave, assim como identidades duplicadas, permanecem sem correspondência. Chaves explícitas nunca recorrem a nomes, mesmo quando uma chave foi adicionada, removida ou alterada entre builds. Adicionado/removido significa que uma identidade de job está presente em apenas um build; portanto, renomear jobs sem chave ou alterar valores de matriz ou paralelismo também pode gerar entradas adicionadas/removidas. Tentativas repetidas são excluídas; os estados da tentativa final e as contagens de repetição continuam visíveis.

Os tempos de execução e as diferenças abrangem apenas as tentativas finais. O tempo de agendamento vai de scheduled_at a started_at, não inclui espera por dependências ou intervenção manual. Essas métricas não comparam o tempo total de execução dos builds nem o custo total das repetições. Timestamps ausentes ou inconsistentes omitem a métrica de tempo correspondente. Builds não finalizados são identificados explicitamente como snapshots em mudança.

Qualquer alteração em soft_failed é informada como state_changed: transições entre falhas leves e graves, mesmo quando ambos os jobs têm o estado failed, e entre jobs aprovados e com falha leve, que nunca são informados como newly_failing ou recovered, pois uma falha leve não bloqueia o build. Um build de baseline aprovado pode conter jobs com falha leve.

Por padrão, até três falhas recém-bloqueantes incluem as últimas 20 entradas de log: primeiro os jobs newly_failing, depois os jobs state_changed que agora têm falhas graves, como um job que teve falha leve no baseline. Os logs são limitados a 8 KiB de conteúdo cada. Defina include_logs: false para omitir os logs. Erros de log não descartam a comparação, exceto erros de autenticação HTTP 401, que seguem o fluxo de reautenticação do servidor. A ferramenta exige os escopos read_builds e read_build_logs. Use get_build_failure_summary ou tail_logs para investigar mais; uma etapa com falha compartilhada não comprova uma causa raiz comum nem torna segura uma repetição.

A busca pelo baseline examina no máximo 500 candidatos. Se nenhum for encontrado, a resposta informa que nenhuma comparação foi realizada e solicita um baseline explícito. Os inventários de jobs são limitados a 1.000 jobs por build; inventários maiores retornam um erro em vez de resultados parciais enganosos de itens adicionados/removidos. As omissões na saída são informadas separadamente das contagens completas de resultados.

---

Inspecionar workflows do Test Engine

As ferramentas somente leitura list_test_workflows e get_test_workflow do conjunto de ferramentas tests expõem os monitores, filtros, ações de alarme/recuperação e links configurados de uma suíte. Ambas exigem read_suites e acesso à suíte. Informe org_slug e test_suite_slug (um slug ou UUID) para listar workflows:

{"org_slug": "acme", "test_suite_slug": "backend"}

Para inspecionar um workflow, chame get_test_workflow com a mesma organização e suíte e informe o id de um item como workflow_id.

Use os rótulos configurados com list_tests para encontrar testes marcados; os rótulos, por si só, não classificam a instabilidade. Os workflows descrevem a configuração, não comprovam que uma ação foi executada nem fornecem o histórico de eventos. Ambas as ferramentas sempre substituem os endpoints de webhook por [REDACTED], independentemente das permissões de API do chamador.

---

Inspecionar agregados de spans do Test Engine

O conjunto de ferramentas somente leitura tests inclui quatro ferramentas de agregação de spans que exigem read_suites:

• list_span_aggregate_scopes: informe org_slug, test_suite_slug e um period opcional para listar escopos de instrumentação por duração total. A ingestão de traces OTel precisa estar habilitada. Os agregados têm precisão horária e retenção de um mês; o período solicitado precisa estar dentro do limite de histórico da API da organização.
• list_span_aggregate_scopes_for_build: informe org_slug e build_uuid para listar escopos de instrumentação nas suítes visíveis do build. Exige ingestão de traces OTel e acesso ao pipeline do build.
• list_span_aggregate_names: informe org_slug, test_suite_slug e scope_name para obter estatísticas de nomes de spans de uma suíte. Aceita os mesmos valores de period e a mesma retenção de list_span_aggregate_scopes, além das opções sort e limit descritas abaixo. Exige ingestão de traces OTel.
• list_span_aggregate_names_for_build: informe org_slug, build_uuid (não o número do build do pipeline) e scope_name para obter estatísticas de nomes de spans nas suítes visíveis do build. Use uma string vazia para o escopo sem nome. Exige acesso ao pipeline do build. sort é opcional e, por padrão, usa -total; limit usa 20 por padrão (máximo de 100). Verifique span_names_truncated antes de considerar o resultado completo.

As durações são expressas em nanossegundos. Os totais somam as durações dos spans, em vez de medir o tempo de relógio; os valores p50 e p95 são aproximados. Nenhuma ferramenta de agregação de spans é paginada. Ambas as ferramentas de nomes de spans aceitam um scope_name vazio para o escopo sem nome e retornam span_names_truncated quando há mais nomes.

---

Uso da biblioteca

A API Go exportada deste módulo deve ser considerada instável e sujeita a alterações incompatíveis à medida que evoluímos este projeto.

---

Segurança

Para garantir que o servidor MCP seja executado em um ambiente seguro, recomendamos executá-lo em um contêiner.

Esta imagem é criada a partir de cgr.dev/chainguard/static e é executada como um usuário sem privilégios.

Encaminhar cabeçalhos de identidade no modo HTTP

Implantações HTTP auto-hospedadas podem encaminhar cabeçalhos selecionados de cada solicitação MCP recebida para a API do Buildkite:

BUILDKITE_API_TOKEN=bkua_xxx \
  buildkite-mcp-server http \
  --passthrough-http-header X-User-Identity

Repita --passthrough-http-header para permitir mais de um cabeçalho ou defina um valor BUILDKITE_PASSTHROUGH_HTTP_HEADERS separado por vírgulas. Somente os cabeçalhos explicitamente permitidos são encaminhados, e apenas para a origem configurada por BUILDKITE_BASE_URL. Eles são removidos de solicitações redirecionadas para outros destinos.

Para autenticar cada solicitação MCP com seu próprio token da API do Buildkite, permita Authorization e omita o token de todo o processo:

BUILDKITE_PASSTHROUGH_HTTP_HEADERS=Authorization \
  buildkite-mcp-server http

Nesse modo, cada solicitação /mcp precisa conter exatamente um cabeçalho Authorization não vazio. A ausência de credenciais retorna HTTP 401; o servidor nunca recorre a um token de API compartilhado. O proxy reverso diante do servidor MCP é responsável por autenticar os chamadores e definir ou validar quaisquer cabeçalhos de identidade encaminhados. O encaminhamento de cabeçalhos não está disponível no modo stdio. Antes de disponibilizar os logs do job, o servidor verifica se o chamador atual pode acessar o log do job. Essa verificação é realizada em cada solicitação da ferramenta de logs, inclusive quando os dados do log já estão em cache.

---

Contribuição

As diretrizes de desenvolvimento estão em DEVELOPMENT.md.

---

Licença

MIT © Buildkite

SPDX-License-Identifier: MIT