# Buildkite Best Practices Documentation

> Buildkite documentation for CI/CD best practices, covering pipeline design and structure, agent management, Docker-based builds, parallelization, monorepos, dependency management, secrets, infrastructure as code, caching, monitoring, and security controls.

## Pipelines

### Best practices

- [Overview](https://buildkite.com/docs/pipelines/best-practices.md)
- [Pipeline design and structure](https://buildkite.com/docs/pipelines/best-practices/pipeline-design-and-structure.md): Patterns for maintainable pipelines: modularity, monorepo builds, fast feedback loops, YAML structure, and versioning.
- [Agent management](https://buildkite.com/docs/pipelines/best-practices/agent-management.md): Best practices for agent infrastructure: cloud compute, Kubernetes, hosted agents, queue design, lifecycle, and autoscaling.
- [Docker-based builds](https://buildkite.com/docs/pipelines/best-practices/docker-containerized-builds.md): Running builds in Docker containers using the Docker and Docker Compose plugins, with configuration examples.
- [Parallelizing builds](https://buildkite.com/docs/pipelines/best-practices/parallel-builds.md): Running steps in parallel across multiple agents and using job parallelism to split test suites for faster builds.
- [Working with monorepos](https://buildkite.com/docs/pipelines/best-practices/working-with-monorepos.md): Static and dynamic approaches for running monorepo pipelines with change detection using if_changed and diff plugins.
- [Environment and dependency management](https://buildkite.com/docs/pipelines/best-practices/environment-and-dependency.md): Best practices for containerized builds, dependency locking, caching, environment variable management, and tool versioning.
- [Secrets management](https://buildkite.com/docs/pipelines/best-practices/secrets-management.md): Recommendations for secrets management: native tools, rotation, scoping, and audit logging.
- [Infrastructure as code recommendations](https://buildkite.com/docs/pipelines/best-practices/iac.md): Managing Buildkite organizations, pipelines, and agents as code using Terraform, GitOps workflows, and OIDC.
- [Git checkout optimization](https://buildkite.com/docs/pipelines/best-practices/git-checkout-optimization.md): Optimizing Git checkout performance with sparse checkout and Git mirrors for large repositories.
- [Plugin management](https://buildkite.com/docs/pipelines/best-practices/plugin-management.md): Best practices for plugin standardization: common use cases, plugin sources, versioning, and security vetting.
- [Caching](https://buildkite.com/docs/pipelines/best-practices/caching.md): Caching strategies for dependencies, Docker layers, and Git mirrors using hosted cache volumes and cache plugins.
- [Monitoring and observability](https://buildkite.com/docs/pipelines/best-practices/monitoring-and-observability.md): Best practices for telemetry, metrics collection, alerting, log management, and integrating with observability tools.
- [Platform controls](https://buildkite.com/docs/pipelines/best-practices/platform-controls.md): How platform teams maintain centralized control over agent infrastructure, pipeline templates, and developer autonomy.
- [Enforcing security controls](https://buildkite.com/docs/pipelines/best-practices/security-controls.md): Security engineering guide covering authentication, source code integrity, supply chain, artifact, and pipeline hardening.

### Agent

- [Overview](https://buildkite.com/docs/agent.md): Overview of the Buildkite agent, comparing self-hosted and Buildkite hosted agents, architecture, lifecycle, and CLI usage.

#### Queues

- [Overview](https://buildkite.com/docs/agent/queues.md): How queues route jobs to specific agents, targeting queues from pipeline YAML, and self-hosted vs hosted queue types.
- [Managing](https://buildkite.com/docs/agent/queues/managing.md): Creating, configuring, pausing, and deleting self-hosted and Buildkite hosted queues within clusters.
- [Agent lifecycle](https://buildkite.com/docs/agent/lifecycle.md): Agent lifecycle stages, signal handling (SIGTERM/SIGQUIT), exit codes, and troubleshooting common issues.
- [Hooks](https://buildkite.com/docs/agent/hooks.md): Agent hook types, scopes (agent, repository, plugin), lifecycle events, and polyglot hook support.

## See also

- [Buildkite Pipeline Configuration Documentation](https://buildkite.com/docs/llms-pipeline-configurations.txt): Buildkite documentation for configuring pipelines, including step types, dynamic pipelines, environment variables, workflows, artifacts, and build settings.
- [Buildkite Security Documentation](https://buildkite.com/docs/llms-security.txt): Buildkite documentation for security, including secrets management, OIDC, clusters, permissions, SSO, agent security, signed pipelines, and security best practices.
- [Buildkite Troubleshooting and Debugging Documentation](https://buildkite.com/docs/llms-debugging.txt): Buildkite documentation for debugging and troubleshooting builds, agents, and infrastructure, covering log output management, build annotations, terminal access, agent lifecycle, and platform-specific troubleshooting guides.