You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/pipelines/process/templates.md
+44-35Lines changed: 44 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,8 +2,8 @@
2
2
title: How to use YAML templates for reusable and secure pipelines
3
3
description: Learn how to create reusable YAML pipeline templates to streamline and secure your CI/CD processes.
4
4
ms.assetid: 6f26464b-1ab8-4e5b-aad8-3f593da556cf
5
-
ms.topic: conceptual
6
-
ms.date: 02/26/2025
5
+
ms.topic: how-to
6
+
ms.date: 08/21/2025
7
7
monikerRange: "<=azure-devops"
8
8
zone_pivot_groups: template-type
9
9
ai-usage: ai-assisted
@@ -17,18 +17,27 @@ ai-usage: ai-assisted
17
17
18
18
Templates let you define reusable content, logic, and parameters in YAML pipelines. To work with templates effectively, you need to have a basic understanding of [Azure Pipelines key concepts](../get-started/key-pipelines-concepts.md) such as stages, steps, and jobs.
19
19
20
-
Templates can help you speed up development. For example, you can have a series of the same tasks in a template and then include the template multiple times in different stages of your YAML pipeline.
20
+
There are two main types of templates:
21
+
22
+
-**Includes templates:** Insert reusable content into a pipeline. If a template is used to include content, it functions like an include directive in many programming languages. Content from a template is inserted into the pipeline or template that includes it.
23
+
-**Extends templates:** Control and define a schema for what is allowed in a pipeline. When an extends template is used, it defines logic and structure that a pipeline must follow. This is useful for enforcing security, compliance, or organizational standards.
24
+
25
+
Templates can help you speed up development. For example, you can have a series of the same tasks in a template and then include the template multiple times in different stages of your YAML pipeline.
21
26
22
27
Templates can also help you secure your pipeline. When a template controls what is allowed in a pipeline, the template defines logic that another file must follow. For example, you might want to restrict what tasks are allowed to run. For that scenario, you can use template to prevent someone from successfully running a task that violates your organization's security policies.
23
-
24
-
There are two types of templates: includes and extends.
25
28
26
-
-**Includes templates** let you insert reusable content with a template. If a template is used to include content, it functions like an include directive in many programming languages. Content from template is inserted into the pipeline or template that includes it.
27
-
-**Extends templates** let you control what is allowed in a pipeline. When an extends template controls what is allowed in a pipeline, the template defines logic that a pipeline must follow. For example, an extends template can be used in the context of extending a pipeline to perform stages or jobs.
29
+
To take full advantage of templates, you should also use [template expressions](template-expressions.md) and [template parameters](template-parameters.md).
30
+
31
+
## Prerequisites
32
+
33
+
|**Product**|**Requirements**|
34
+
|---|---|
35
+
| **Azure DevOps** | - An [Azure DevOps project](../../organizations/projects/create-project.md).<br> - An ability to run pipelines on Microsoft-hosted agents. You can either purchase a [parallel job](../licensing/concurrent-jobs.md) or you can request a free tier. <br> - Basic knowledge of YAML and Azure Pipelines. For more information, see [Create your first pipeline](../create-first-pipeline.md). <br> - **Permissions:**<br> - To create a pipeline: you must be in the **Contributors** group and the group needs to have *Create build pipeline* permission set to Allow. Members of the [Project Administrators group](../../organizations/security/permissions.md) can manage pipelines. <br> - To create service connections: You must have the *Administrator* or *Creator* role for [service connections](../library/add-resource-protection.md).
36
+
|**GitHub**| - A [GitHub](https://github.com) account. <br> - A [GitHub service connection](../library/service-endpoints.md) to authorize Azure Pipelines.|
37
+
|**Azure**| An [Azure subscription](https://azure.microsoft.com/free/). |
28
38
29
-
To take full advantage of templates, you should also use [template expressions](template-expressions.md) and [template parameters](template-parameters.md).
30
39
31
-
###Imposed limits on template updates
40
+
## Imposed limits on template updates
32
41
33
42
Templates and template expressions can cause explosive growth to the size and complexity of a pipeline.
34
43
To help prevent runaway growth, Azure Pipelines imposes the following limits:
@@ -45,12 +54,12 @@ To help prevent runaway growth, Azure Pipelines imposes the following limits:
45
54
46
55
::: moniker range=">=azure-devops-2020"
47
56
48
-
To increase security, you can enforce that a pipeline extends from a particular template. The file `start.yml` defines the parameter `buildSteps`, which is then used in the pipeline `azure-pipelines.yml`.
49
-
In `start.yml`, if a `buildStep` gets passed with a script step, then it's rejected and the pipeline build fails.
57
+
To increase security, you can enforce that a pipeline extends from a particular template. The file `start-extends-template.yml` defines the parameter `buildSteps`, which is then used in the pipeline `azure-pipelines.yml`.
58
+
In `start-extends-template.yml`, if a `buildStep` gets passed with a script step, then it's rejected and the pipeline build fails.
50
59
When extending from a template, you can increase security by adding a [required template approval](../security/templates.md#set-required-templates).
51
60
52
61
```yaml
53
-
# File: start.yml
62
+
# File: start-extends-template.yml
54
63
parameters:
55
64
- name: buildSteps # the name of the parameter is buildSteps
56
65
type: stepList # data type is StepList
@@ -85,7 +94,7 @@ trigger:
85
94
- main
86
95
87
96
extends:
88
-
template: start.yml
97
+
template: start-extends-template.yml
89
98
parameters:
90
99
buildSteps:
91
100
- bash: echo Test #Passes
@@ -110,11 +119,11 @@ trigger:
110
119
- none
111
120
112
121
extends:
113
-
template: resource-template.yml
122
+
template: resource-extends-template.yml
114
123
```
115
124
116
125
```yaml
117
-
# File: resource-template.yml
126
+
# File: resource-extends-template.yml
118
127
resources:
119
128
pipelines:
120
129
- pipeline: my-pipeline
@@ -134,13 +143,13 @@ steps:
134
143
135
144
::: moniker range=">=azure-devops-2020"
136
145
137
-
You can copy content from one YAML and reuse it in a different YAML. Copying content from one YAML to another saves you from having to manually include the same logic in multiple places. The `include-npm-steps.yml` file template contains steps that are reused in `azure-pipelines.yml`.
146
+
You can insert content from one YAML and reuse it in a different YAML. Inserting content from one YAML to another saves you from having to manually include the same logic in multiple places. The `insert-npm-steps.yml` file template contains steps that are reused in `azure-pipelines.yml`.
138
147
139
148
> [!NOTE]
140
149
> Template files need to exist on your filesystem at the start of a pipeline run. You can't reference templates in an artifact.
![prmerger-automator[bot]](https://avatars.githubusercontent.com/u/22479449?v=4&size=40){kind=avatar}
0 commit comments