Guia Completo de Buildkite — Integration Pipelines

🚦Visão Geral

Buildkite é uma plataforma de CI/CD híbrida: o control plane é SaaS, mas os agents rodam na sua infraestrutura (on-prem, AWS, GCP, Azure, K8s). É usado em escala por Uber, DoorDash, Pinterest e Shopify.

Integration Pipelines são pipelines dedicados a rodar testes de integração — onde múltiplos serviços/módulos sobem juntos (DB real, Redis, mocks contratados) para validar contratos. Diferem de unit pipelines por tempo de execução, requisitos de infraestrutura e isolamento.

Anatomia de um pipeline.yml com etapa de integração

# .buildkite/pipeline.yml
steps:
  - label: ":docker: Build"
    key: "build"
    command: "docker compose build app"
    agents:
      queue: "default"
    plugins:
      - docker-compose#v5.5.0:
          build: app

  - wait

  - label: ":test_tube: Unit tests"
    key: "unit"
    command: "pnpm vitest run"
    parallelism: 4
    depends_on: "build"
    agents:
      queue: "default"

  - label: ":mag: Integration tests"
    key: "integration"
    command: "pnpm test:integration"
    depends_on: "build"
    agents:
      queue: "integration"   # queue dedicada com mais recursos
    timeout_in_minutes: 30
    retry:
      automatic:
        - exit_status: -1
          limit: 2

  - wait

  - block: "Deploy to prod?"
    branches: "main"

  - label: ":rocket: Deploy"
    command: ".buildkite/deploy.sh"
    branches: "main"
    agents:
      queue: "deploy"

Dynamic pipelines (bootstrap → generate)

#!/usr/bin/env bash
# .buildkite/generate-pipeline.sh
# Bootstrap → generate pattern: 1 step inicial monta o resto do pipeline.

set -euo pipefail

# Detecta serviços alterados no diff
CHANGED=$(git diff --name-only origin/main...HEAD | cut -d/ -f1 | sort -u)

cat <<'YAML'
steps:
YAML

for svc in $CHANGED; do
  if [[ -d "services/$svc" ]]; then
    cat <<YAML
  - label: ":hammer: Test $svc"
    command: "cd services/$svc && make ci"
    agents:
      queue: "integration"
    key: "test-$svc"
YAML
  fi
done

cat <<'YAML'
  - wait

  - label: ":ship: Deploy changed services"
    command: ".buildkite/deploy-changed.sh"
    branches: "main"
YAML

# Pipeline A dispara Pipeline B com env e meta-data
steps:
  - label: ":package: Build artifact"
    command: ./build.sh
    key: "build"

  - trigger: "integration-tests"   # slug do pipeline B
    label: ":arrow_right: Run integration suite"
    depends_on: "build"
    build:
      message: "Triggered from ${BUILDKITE_PIPELINE_SLUG} #${BUILDKITE_BUILD_NUMBER}"
      commit: "${BUILDKITE_COMMIT}"
      branch: "${BUILDKITE_BRANCH}"
      env:
        ARTIFACT_URL: "s3://artifacts/${BUILDKITE_BUILD_NUMBER}.tar"
      meta_data:
        source_build: "${BUILDKITE_BUILD_ID}"
    async: false                   # bloqueia até B terminar

Agent stack no Kubernetes

# Instalar agent-stack-k8s via Helm
helm upgrade --install agent-stack-k8s \
  oci://ghcr.io/buildkite/helm/agent-stack-k8s \
  --namespace buildkite \
  --create-namespace \
  --values values.yml

# values.yml minimo
config:
  org: minha-org
  cluster-uuid: <cluster-uuid>
agentToken: bkua_xxx           # ou agentTokenSecretName apontando para um Secret
agentStackSecret: bkagent_xxx
podSpec:
  serviceAccountName: buildkite-agent
  containers:
    - name: agent
      resources:
        requests: { cpu: "500m", memory: "1Gi" }
        limits:   { cpu: "2",    memory: "4Gi" }

📺Vídeos · Fundamentos & Onboarding

Material oficial e introdutório. Comece por aqui se nunca usou Buildkite. Todos os vídeos são em inglês (EN) — não há material em português significativo (gap real do nicho).

🤖Vídeos · Agents, Infra & Integrações

Como rodar agents em escala — Kubernetes, AWS, parallelismo, manutenção e infraestrutura como código com Terraform.

📈Vídeos · Casos de Escala (Uber, Twilio, Aviator)

Como empresas grandes usam Buildkite em monorepos, monorepos com 10k builds/dia e merge queues. Boa leitura pra justificar adoção em time/empresa.

🧪Vídeos · Test Analytics & Flaky Tests

Buildkite Test Analytics é o produto irmão dos pipelines — ingesta resultados de teste, rastreia flakies e mede saúde da suite ao longo do tempo. Crucial para integration pipelines, onde flakes são endêmicos.

🔌Vídeos · Integrações Pontuais

Plugins, registries e conteúdo não-inglês (o único material próximo de PT que encontrei foi em espanhol).

📚Documentação Oficial

Fontes canônicas — preferir sempre estas ao invés de blogs antigos.

• Pipelines — docs principal — referência completa de steps, env, plugins, retries.
• Getting Started — tutorial mão-na-massa do primeiro pipeline.
• Create Your Own Pipeline — escrever o pipeline.yml para o seu repo.
• Dynamic Pipelines — gerar steps em runtime (bootstrap → generate).
• Example Pipelines — catálogo de pipelines prontos por stack (Ruby, Node, Go, mobile, ML).
• Agent overview — o que é o agent e o ciclo de vida.
• Self-hosted agents — rodar agents na sua infra (recomendado em produção).
• agent-stack-k8s — instalação — Helm chart para rodar agents no Kubernetes.
• Agents em AWS — Elastic CI Stack autoscaling com CloudFormation.
• Elastic CI Stack — GCP via Terraform
• Agents em Microsoft Azure
• Deploying to Kubernetes — padrões de deploy a partir do pipeline.

📦Repositórios GitHub

• buildkite/agent — o agent oficial, escrito em Go. Open-source.
• buildkite/agent-stack-k8s — controller K8s + Helm chart para autoscaling.
• buildkite/elastic-ci-stack-for-aws — CloudFormation autoscaling em AWS.
• buildkite/terraform-buildkite-elastic-ci-stack-for-gcp — Terraform module para GCP.

📰Blog Posts & Artigos

• The power of Dynamic Pipelines: creating CI/CD pipelines in code, at runtime — blog oficial.
• What are CI/CD Pipelines? — fundamentos conceituais.
• Self-hosted Bazel remote cache em AWS com Terraform — caso real de cache de build em monorepo grande.
• Getting started with iOS CI and fastlane
• Setting up Buildkite and your first CI pipeline in 2 hours — Harvey Delaney, guia prático passo-a-passo.
• Streamlining CI/CD with Buildkite — Installation and Setup — Medium, install detalhado.
• Know How to Get Started with Buildkite — Opstree
• AWS CodeBuild como runner Buildkite (tutorial AWS)
• Using Buildkite + Pulumi (CI/CD para IaC)

⚖️Comparações & Decisão

Antes de adotar, vale comparar com alternativas. Estas leituras ajudam a justificar (ou refutar) a escolha do Buildkite.

• Buildkite vs todas (página oficial de comparação)
• GitHub Actions vs CircleCI
• Alternatives to Jenkins (2025)
• GitHub Actions vs Jenkins
• Shipyard — Comparing CI/CD Tools
• StackShare — Buildkite vs CircleCI vs Jenkins
• Top 9 Buildkite Alternatives (2026)