Skip to content
Back to Deployment

Deploying with Buildkite

Hybrid CI/CD platform with self-hosted agents and cloud-based orchestration.

CI/CDIntermediate

Why

Buildkite combines cloud control with your own compute — fast, secure, and cost-effective for large builds. DORA's 2024 State of DevOps report shows elite teams deploy 973x more frequently than low performers.

CI/CD pipelines with automated testing reduce change failure rate to 5-15% versus 40-60% for manual deployments.

When

Teams needing fast builds on their own hardware while keeping pipeline management in the cloud. Avoid complex pipeline orchestration for repos with fewer than 5 contributors — a pre-commit hook + GitHub Actions suffices.

Skip self-hosted runners unless you need GPU or VPN access.

How

# .buildkite/pipeline.yml steps: - label: ":hammer: Build" command: "npm ci && npm run build" artifact_paths: "dist/**" - wait - label: ":test_tube: Test" command: "npm test" depends_on: "build" - wait - block: "Deploy to production?" key: "approve" - label: ":rocket: Deploy" command: "kubectl rollout restart deployment/app" depends_on: "approve" branches: "main" 4. Verify deployment — curl -I https://your-app.example.com 5. Monitor logs — check for errors in first 5 minutes 6. Rollback if needed — revert to previous version

Example

# Start a Buildkite agent docker run -d --name buildkite-agent \ -e BUILDKITE_AGENT_TOKEN=$TOKEN \ -v /var/run/docker.sock:/var/run/docker.sock \ buildkite/agent:latest

Common Problems

  • ⚠Agent not picking up jobs — check token and tags
  • ⚠Artifacts not uploading — verify artifact upload bucket
  • ⚠Configuration drift between environments — use infrastructure-as-code (Terraform/Pulumi) to keep dev/staging/prod identical

Best Practices

  • ✓Use agent tags for routing — match jobs to capable agents
  • ✓Use monorepo diff-based pipeline generation — skip unchanged work
  • ✓Set up health checks and graceful shutdown — handle SIGTERM to drain in-flight requests before exit

FAQ