Pipeline as Code

Best Practice: Pipeline as Code

Pipeline as Code is the practice of defining your build, test, and deployment pipeline in version-controlled files that live with the application source, rather than configuring it by clicking through a CI server's UI. The pipeline definition is reviewed, versioned, and reproduced like any other code. Popularized by Jenkins' Jenkinsfile and now standard across GitHub Actions, GitLab CI, and others, the practice brings the delivery process under the same engineering discipline as the application itself. For leaders, it makes the release process transparent, auditable, and portable.

Step-by-Step Implementation Guidance

1. Store the pipeline definition in the repository so it versions with the code it builds.
2. Use the platform's declarative format, such as a Jenkinsfile or YAML workflow file.
3. Review pipeline changes through pull requests like any other code change.
4. Parameterize environments so the same definition deploys to dev, staging, and production.
5. Factor out shared logic into reusable templates, libraries, or composite actions.
6. Run the pipeline from the committed definition, not from manual server configuration.
7. Secure secrets using the platform's secret store, never hard-coded in the file.

Common Mistakes Teams Make When Ignoring This Practice

• Configuring pipelines through the UI, leaving the process undocumented and unreproducible.
• Hard-coding credentials or environment values directly in pipeline files.
• Duplicating pipeline logic across repos instead of sharing reusable templates.
• Letting the committed definition drift from what actually runs on the server.
• Skipping review on pipeline changes, allowing risky delivery edits to slip in.

Tools and Techniques That Support This Practice

• Declarative pipelines: Jenkins Jenkinsfile, GitHub Actions workflows, GitLab CI YAML, and Tekton.
• Reuse: shared libraries, reusable workflows, and composite actions.
• Secret management: Vault, GitHub/GitLab secrets, and cloud secret managers.
• Validation: linters such as actionlint and yamllint to check pipeline files.

How This Practice Applies to Different Migration Types

• Cloud Migration: Version pipeline definitions so cloud deployment steps are reviewable and reproducible across accounts.
• Database Migration: Encode migration and rollback steps in the pipeline file so database changes follow the same gated process.
• SaaS Migration: Define SaaS deployment and integration steps as code so configuration changes are tracked and audited.
• Codebase Migration: Keep the migrated codebase's pipeline in the repo so build and deploy logic evolves with the code.

Checklist

• The pipeline is defined in files in the repository.
• A declarative format describes the stages.
• Pipeline changes go through code review.
• Environments are parameterized, not duplicated.
• Shared logic is factored into reusable templates.
• Secrets come from a secret store, not the file.

During modernization and migration work, pipeline as code is most valuable when it is treated as a continuous discipline rather than a one-time setup. Teams that codify the practice, measure its outcomes, and review it regularly keep risk low and feedback fast as systems evolve. Start small with one team or service, prove the value with concrete metrics such as lead time and change failure rate, and then expand the practice across the portfolio. Pair it with the related practices in this library so that build, test, release, and operational concerns reinforce one another. Documenting decisions and automating enforcement makes the practice durable as people and priorities change, which is exactly what large, multi-team migrations demand to stay safe and predictable over time.