Pipeline Template
A pipeline template is a delivery definition maintained in one place and used by many repositories, so that a build and deployment process is written once rather than fifty times. Every major delivery platform has a mechanism for it under its own name; this entry is about the design problem, which is the same regardless of product. The term itself is industry usage rather than a standardized one.
The decision that matters is not how to write one. It is what you intend it to be, because three different intentions are usually described with the same word and they require different designs.
Convenience, standard, or control
| Intent | How teams use it | What it requires | What it gets you |
|---|---|---|---|
| Convenience | Copied into each repository as a starting point, then edited freely | Almost nothing — a file to copy | A faster start. A fix must be applied in every copy, so improvements do not propagate |
| Standard | Referenced rather than copied, with parameters for the parts that differ | A version, an owner, tests, and a deprecation path | An improvement is made in one place; how quickly it reaches consumers depends on whether they pin. This is the version that pays back |
| Control | The only sanctioned route to something — a production credential, a protected environment | All of the above, plus enforcement so bypassing is prevented rather than discouraged | A place policy is actually applied, and a new class of responsibility |
The common failure is building the first and describing it as the third. A team copies a template into every repository, drift accumulates, and someone reports that all our pipelines run the security scan — which was true on the day of copying. The question that settles which one you have is blunt: if a team removes the step, does anything stop them or notice? If the answer is no, it is a convenience, whatever the documentation says.
None of the three is wrong. A convenience is appropriate where teams genuinely need to diverge and the platform team has no mandate. A control is appropriate for the small number of things that must not vary — how production credentials are obtained, what gates a deployment. Most estates need a standard for the bulk of the work and a control for a short list, and the mistake is not choosing.
A referenced template is a dependency
The moment repositories reference a template rather than copying it, you have published an interface with consumers, and everything that follows from that applies. Four requirements are not optional.
- Versioning. Consumers should be able to pin a version and upgrade deliberately. A template referenced by a moving pointer means every consumer’s pipeline can change without their involvement — convenient for urgent fixes, and the reason a Tuesday morning can break fifty builds at once.
- An owner. Someone answers questions and fixes breakage. A shared template with no owner degrades into a thing everyone works around.
- Tests. The template is executable code that runs in everyone’s delivery path. It deserves at least a repository that exercises it before a change is published.
- A deprecation path. Changing a template’s interface is a breaking change for its consumers, and the way to make one safely is the ordinary one: add the new form, migrate, then remove — see expand and contract.
The upgrade question deserves a deliberate answer rather than a default. Pinned versions give consumers control and let old versions linger, which means a security fix reaches only teams that act. Floating references propagate fixes instantly and make the template a shared production dependency that can break everyone simultaneously. A common middle position is to pin a major version and float within it, which only works if the template’s authors treat that boundary as a promise.
Parameterization fails in both directions
Too few parameters and teams cannot express what they need, so they abandon the template and copy it — at which point you have a convenience with extra steps. Too many and the template becomes a language of its own: a hundred inputs, conditional branches nobody can follow, and behaviour that differs per consumer in ways the owner cannot predict or test.
The useful heuristic is to parameterize values and resist parameterizing structure. Which image to build, which environment to target, which tests to run — values. Whether there is an approval step at all, or whether the deployment happens in a different order — structure, and a request for that is usually a signal that this consumer needs a different template rather than another flag in this one.
Two or three templates that are each comprehensible beat one that covers every case, and the cost of the extra template is smaller than the cost of a definition nobody can reason about.
Where it fits
A well-maintained template is one of the most concrete forms a golden path takes: the supported way to build and ship, available by reference, kept current by someone whose job it is. That framing also sets the standard to hold it to — a path is only golden if using it is easier than not using it, so a template that is harder to adopt than to copy has failed regardless of its content.
It is also where a platform team’s leverage is highest and its blast radius largest, which are the same property. One improvement to a widely referenced template improves every team’s delivery; one mistake stops every team’s delivery. Both of those describe the floating-reference case — with pinned consumers the improvement and the mistake travel at the speed teams bump their pins, which is the trade the previous section describes. Either way, treating the template with the care given to a shared library is the reasonable response, not a sign of excessive process: staged rollout, a tested change, and a rehearsed way to revert. What reverting means depends on how consumers reference you, and it is worth working out before you need it: with a floating reference you fix the reference and the next run is clean, whereas consumers pinned to an exact version have to move their pins, so your revert is an announcement plus a change in each of their repositories. Fast unilateral rollback and pinned stability are the same trade seen from the other side; you do not get both.
The practice of keeping definitions in the repository is pipeline as code; how the common delivery platforms differ in their reuse mechanisms, and in the more consequential matters of isolation and job identity, is worked through in Who Runs Your Build, and What Can It Reach.
Discover more from Insightful Data Lab
Subscribe to get the latest posts sent to your email.