Referência de uso do modelo
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Os modelos permitem definir conteúdo, lógica e parâmetros reutilizáveis em pipelines YAML. Para trabalhar com modelos de forma eficaz, você precisará ter uma compreensão básica dos principais conceitos do Azure Pipelines, como estágios, etapas e trabalhos.
Os modelos podem ajudá-lo a acelerar o desenvolvimento. Por exemplo, você pode ter uma série das mesmas tarefas em um modelo e, em seguida, incluir o modelo várias vezes em diferentes estágios do seu pipeline YAML.
Os modelos também podem ajudá-lo a proteger seu pipeline. Quando um modelo controla o que é permitido em um pipeline, o modelo define a lógica que outro arquivo deve seguir. Por exemplo, talvez você queira restringir quais tarefas podem ser executadas. Para esse cenário, você pode usar o modelo para impedir que alguém execute com êxito uma tarefa que viole as políticas de segurança da sua organização.
Existem dois tipos de modelos: inclui e estende.
- Inclui modelos que permitem inserir conteúdo reutilizável com um modelo. Se um modelo é usado para incluir conteúdo, ele funciona como uma diretiva include em muitas linguagens de programação. O conteúdo de um arquivo é inserido em outro arquivo.
- Estende o controle de modelo o que é permitido em um pipeline. Quando um modelo estendido controla o que é permitido em um pipeline, o modelo define a lógica que outro arquivo deve seguir.
Para tirar o máximo proveito dos modelos, você também deve usar expressões de modelo e parâmetros de modelo.
Limites impostos
Os modelos e as expressões de modelos podem causar um crescimento explosivo do tamanho e complexidade de um pipeline. Para ajudar a evitar o crescimento descontrolado, o Azure Pipelines impõe os seguintes limites:
- Não podem ser incluídos mais de 100 ficheiros YAML separados (direta ou indiretamente)
- Não podem existir mais de 20 níveis de aninhamento de modelos (modelos, incluindo outros modelos)
- Não mais do que 10 megabytes de memória consumida durante a análise do YAML (na prática, isso normalmente é entre 600 KB - 2 MB de YAML no disco, dependendo dos recursos específicos usados)
Use modelos para definir sua lógica uma vez e, em seguida, reutilize-a várias vezes. Os modelos combinam o conteúdo de vários arquivos YAML em um único pipeline. Você pode passar parâmetros para um modelo a partir do pipeline pai.
Estender a partir de um modelo
Para aumentar a segurança, você pode impor que um pipeline se estenda a partir de um modelo específico. O arquivo start.yml
define o parâmetro buildSteps
, que é usado no pipeline azure-pipelines.yml
.
No start.yml
, se um buildStep
for passado com uma etapa de script, ele será rejeitado e a compilação do pipeline falhará.
Ao estender a partir de um modelo, você pode aumentar a segurança adicionando uma aprovação de modelo necessária.
# File: start.yml
parameters:
- name: buildSteps # the name of the parameter is buildSteps
type: stepList # data type is StepList
default: [] # default value of buildSteps
stages:
- stage: secure_buildstage
pool:
vmImage: windows-latest
jobs:
- job: secure_buildjob
steps:
- script: echo This happens before code
displayName: 'Base: Pre-build'
- script: echo Building
displayName: 'Base: Build'
- ${{ each step in parameters.buildSteps }}:
- ${{ each pair in step }}:
${{ if ne(pair.value, 'CmdLine@2') }}:
${{ pair.key }}: ${{ pair.value }}
${{ if eq(pair.value, 'CmdLine@2') }}:
# Step is rejected by raising a YAML syntax error: Unexpected value 'CmdLine@2'
'${{ pair.value }}': error
- script: echo This happens after code
displayName: 'Base: Signing'
# File: azure-pipelines.yml
trigger:
- main
extends:
template: start.yml
parameters:
buildSteps:
- bash: echo Test #Passes
displayName: succeed
- bash: echo "Test"
displayName: succeed
# Step is rejected by raising a YAML syntax error: Unexpected value 'CmdLine@2'
- task: CmdLine@2
inputs:
script: echo "Script Test"
# Step is rejected by raising a YAML syntax error: Unexpected value 'CmdLine@2'
- script: echo "Script Test"
Estender a partir de um modelo com recursos
Você também pode usar extends
para estender a partir de um modelo em seu pipeline do Azure que contém recursos.
# File: azure-pipelines.yml
trigger:
- none
extends:
template: resource-template.yml
# File: resource-template.yml
resources:
pipelines:
- pipeline: my-pipeline
source: sourcePipeline
steps:
- script: echo "Testing resource template"
Inserir um modelo
Você pode copiar o conteúdo de um YAML e reutilizá-lo em um YAML diferente. Copiar conteúdo de um YAML para outro evita que você tenha que incluir manualmente a mesma lógica em vários lugares. O include-npm-steps.yml
modelo de arquivo contém etapas que são reutilizadas no azure-pipelines.yml
.
Nota
Os arquivos de modelo precisam existir em seu sistema de arquivos no início de uma execução de pipeline. Não é possível fazer referência a modelos em um artefato.
# File: templates/include-npm-steps.yml
steps:
- script: npm install
- script: yarn install
- script: npm run compile
# File: azure-pipelines.yml
jobs:
- job: Linux
pool:
vmImage: 'ubuntu-latest'
steps:
- template: templates/include-npm-steps.yml # Template reference
- job: Windows
pool:
vmImage: 'windows-latest'
steps:
- template: templates/include-npm-steps.yml # Template reference
Reutilização gradual
Você pode inserir um modelo para reutilizar uma ou mais etapas em vários trabalhos. Além das etapas do modelo, cada trabalho pode definir mais etapas.
# File: templates/npm-steps.yml
steps:
- script: npm install
- script: npm test
# File: azure-pipelines.yml
jobs:
- job: Linux
pool:
vmImage: 'ubuntu-latest'
steps:
- template: templates/npm-steps.yml # Template reference
- job: macOS
pool:
vmImage: 'macOS-latest'
steps:
- template: templates/npm-steps.yml # Template reference
- job: Windows
pool:
vmImage: 'windows-latest'
steps:
- script: echo This script runs before the template's steps, only on Windows.
- template: templates/npm-steps.yml # Template reference
- script: echo This step runs after the template's steps.
Reutilização de trabalhos
Assim como as etapas, os trabalhos podem ser reutilizados com modelos.
# File: templates/jobs.yml
jobs:
- job: Ubuntu
pool:
vmImage: 'ubuntu-latest'
steps:
- bash: echo "Hello Ubuntu"
- job: Windows
pool:
vmImage: 'windows-latest'
steps:
- bash: echo "Hello Windows"
# File: azure-pipelines.yml
jobs:
- template: templates/jobs.yml # Template reference
Ao trabalhar com vários trabalhos, lembre-se de remover o nome do trabalho no arquivo de modelo, para evitar conflitos
# File: templates/jobs.yml
jobs:
- job:
pool:
vmImage: 'ubuntu-latest'
steps:
- bash: echo "Hello Ubuntu"
- job:
pool:
vmImage: 'windows-latest'
steps:
- bash: echo "Hello Windows"
# File: azure-pipelines.yml
jobs:
- template: templates/jobs.yml # Template reference
- template: templates/jobs.yml # Template reference
- template: templates/jobs.yml # Template reference
Reutilização de palco
Os estágios também podem ser reutilizados com modelos.
# File: templates/stages1.yml
stages:
- stage: Angular
jobs:
- job: angularinstall
steps:
- script: npm install angular
# File: templates/stages2.yml
stages:
- stage: Build
jobs:
- job: build
steps:
- script: npm run build
# File: azure-pipelines.yml
trigger:
- main
pool:
vmImage: 'ubuntu-latest'
stages:
- stage: Install
jobs:
- job: npminstall
steps:
- task: Npm@1
inputs:
command: 'install'
- template: templates/stages1.yml # Template reference
- template: templates/stages2.yml # Template reference
Modelos de trabalho, estágio e etapa com parâmetros
Nos seguintes modelos:
templates/npm-with-params.yml
define dois parâmetros:name
evmImage
cria um trabalho com o parâmetro name para o nome do trabalho e o parâmetro vmImage para a imagem VM.- O pipeline (
azure-pipelines.yml
) faz referência ao modelo três vezes, cada uma com valores de parâmetros diferentes referentes ao sistema operacional e aos nomes de imagem da VM. - O pipeline construído é executado em uma imagem de VM diferente e nomeado de acordo com o sistema operacional especificado. Cada trabalho executa as etapas de instalação e teste do npm.
# File: templates/npm-with-params.yml
parameters:
- name: name # defaults for any parameters that aren't specified
default: ''
- name: vmImage
default: ''
jobs:
- job: ${{ parameters.name }}
pool:
vmImage: ${{ parameters.vmImage }}
steps:
- script: npm install
- script: npm test
Ao consumir o modelo em seu pipeline, especifique valores para os parâmetros do modelo.
# File: azure-pipelines.yml
jobs:
- template: templates/npm-with-params.yml # Template reference
parameters:
name: Linux
vmImage: 'ubuntu-latest'
- template: templates/npm-with-params.yml # Template reference
parameters:
name: macOS
vmImage: 'macOS-latest'
- template: templates/npm-with-params.yml # Template reference
parameters:
name: Windows
vmImage: 'windows-latest'
Modelos de palco com vários parâmetros
Nos seguintes modelos:
- O
stage-template.yml
modelo define quatro parâmetros:stageName
,jobName
,vmImage
, escriptPath
, todos do tipo string. O modelo cria um estágio usando ostageName
parâmetro para definir o nome do palco, define um trabalho comjobName
o , e inclui uma etapa para executar um script. - O pipeline, , em seguida,
azure-pipeline.yml
definir dinamicamente estágios e trabalhos usando parâmetros e executa um trabalho que executa um script,build-script.sh
.
# stage-template.yml
parameters:
- name: stageName
type: string
- name: jobName
type: string
- name: vmImage
type: string
- name: scriptPath
type: string
stages:
- stage: ${{ parameters.stageName }}
jobs:
- job: ${{ parameters.jobName }}
pool:
vmImage: ${{ parameters.vmImage }}
steps:
- script: ./${{ parameters.scriptPath }}
# azure-pipelines.yml
trigger:
- main
stages:
- template: stage-template.yml
parameters:
stageName: 'BuildStage'
jobName: 'BuildJob'
scriptPath: 'build-script.sh' # replace with script in your repository
vmImage: 'ubuntu-latest'
Modelos com etapas e parâmetros
Você também pode usar parâmetros com modelos de etapa ou estágio.
Nos seguintes modelos:
- O modelo (
templates/steps-with-params.yml
) define um parâmetro nomeadorunExtendedTests
com um valor padrão de false. - O pipeline (
azure-pipelines.yml
) é executadonpm test
enpm test --extended
porque orunExtendedTests
parâmetro é true.
# File: templates/steps-with-params.yml
parameters:
- name: 'runExtendedTests' # defaults for any parameters that aren't specified
type: boolean
default: false
steps:
- script: npm test
- ${{ if eq(parameters.runExtendedTests, true) }}:
- script: npm test --extended
Ao consumir o modelo em seu pipeline, especifique valores para os parâmetros do modelo.
# File: azure-pipelines.yml
steps:
- script: npm install
- template: templates/steps-with-params.yml # Template reference
parameters:
runExtendedTests: 'true'
Nota
Parâmetros escalares sem um tipo especificado são tratados como strings.
Por exemplo, eq(true, parameters['myparam'])
retornará true
, mesmo que o myparam
parâmetro seja a palavra false
, se myparam
não for explicitamente feito boolean
.
Strings não vazias são convertidas em true
um contexto booleano.
Essa expressão poderia ser reescrita para comparar explicitamente cadeias de caracteres: eq(parameters['myparam'], 'true')
.
Os parâmetros não estão limitados a cadeias escalares.
Consulte a lista de tipos de dados.
Por exemplo, usando o object
tipo:
# azure-pipelines.yml
jobs:
- template: process.yml
parameters:
pool: # this parameter is called `pool`
vmImage: ubuntu-latest # and it's a mapping rather than a string
# process.yml
parameters:
- name: 'pool'
type: object
default: {}
jobs:
- job: build
pool: ${{ parameters.pool }}
Reutilização variável
As variáveis podem ser definidas em um YAML e incluídas em outro modelo. Isso pode ser útil se você quiser armazenar todas as suas variáveis em um arquivo. Se você estiver usando um modelo para incluir variáveis em um pipeline, o modelo incluído só poderá ser usado para definir variáveis. Você pode usar etapas e lógica mais complexa quando estiver estendendo a partir de um modelo. Use parâmetros em vez de variáveis quando quiser restringir o tipo.
Neste exemplo, a variável favoriteVeggie
está incluída em azure-pipelines.yml
.
# File: vars.yml
variables:
favoriteVeggie: 'brussels sprouts'
# File: azure-pipelines.yml
variables:
- template: vars.yml # Template reference
steps:
- script: echo My favorite vegetable is ${{ variables.favoriteVeggie }}.
Modelos variáveis com parâmetro
Você pode passar parâmetros para variáveis com modelos. Neste exemplo, você está passando o DIRECTORY
parâmetro para uma RELEASE_COMMAND
variável.
# File: templates/package-release-with-params.yml
parameters:
- name: DIRECTORY
type: string
default: "." # defaults for any parameters that specified with "." (current directory)
variables:
- name: RELEASE_COMMAND
value: grep version ${{ parameters.DIRECTORY }}/package.json | awk -F \" '{print $4}'
Ao consumir o modelo em seu pipeline, especifique valores para os parâmetros do modelo.
# File: azure-pipelines.yml
variables: # Global variables
- template: package-release-with-params.yml # Template reference
parameters:
DIRECTORY: "azure/checker"
pool:
vmImage: 'ubuntu-latest'
stages:
- stage: Release_Stage
displayName: Release Version
variables: # Stage variables
- template: package-release-with-params.yml # Template reference
parameters:
DIRECTORY: "azure/todo-list"
jobs:
- job: A
steps:
- bash: $(RELEASE_COMMAND) #output release command
Estender a partir de um modelo e usar um modelo de inclusão com variáveis
Um cenário comum é ter um pipeline com estágios para desenvolvimento, teste e produção que use um modelo para variáveis e um modelo estendido para estágios ou trabalhos.
No exemplo a seguir, variables-template.yml
define um conjunto de variáveis de máquina virtual que são usadas no azure-pipeline.yml
.
# variables-template.yml
variables:
- name: devVmImage
value: 'ubuntu-latest'
- name: testVmImage
value: 'ubuntu-latest'
- name: prodVmImage
value: 'ubuntu-latest'
O arquivo stage-template.yml
a seguir define uma configuração de estágio reutilizável com três parâmetros (name
, vmImage
, steps
) e um trabalho chamado Build
.
# stage-template.yml
parameters:
- name: name
type: string
default: ''
- name: vmImage
type: string
default: ''
- name: steps
type: stepList
default: []
stages:
- stage: ${{ parameters.name }}
jobs:
- job: Build
pool:
vmImage: ${{ parameters.vmImage }}
steps: ${{ parameters.steps }}
O pipeline a seguir, , importa variáveis de variables-template.yml
e, em seguida, azure-pipelines.yml
usa o stage-template.yml
modelo para cada estágio. Cada estágio (Dev, Test, Prod) é definido com o mesmo modelo, mas com parâmetros diferentes, levando à consistência entre os estágios, permitindo a personalização. O estágio Prod inclui uma variável de ambiente como um exemplo de algo que você pode usar para autenticação. Para saber mais sobre como definir parâmetros, consulte Parâmetros de modelo.
# azure-pipelines.yml
trigger:
- main
variables:
- template: variables-template.yml
stages:
- template: stage-template.yml
parameters:
name: Dev
vmImage: ${{ variables.devVmImage }}
steps:
- script: echo "Building in Dev"
- template: stage-template.yml
parameters:
name: Test
vmImage: ${{ variables.testVmImage }}
steps:
- script: echo "Testing in Test"
- template: stage-template.yml
parameters:
name: Prod
vmImage: ${{ variables.prodVmImage }}
steps:
- script: echo "Deploying to Prod"
env:
SYSTEM_ACCESSTOKEN: $(System.AccessToken)
Caminhos de modelo de referência
Os caminhos de modelo podem ser um caminho absoluto dentro do repositório ou relativo ao arquivo que faz a inclusão.
Para usar um caminho absoluto, o caminho do modelo deve começar com um /
arquivo . Todos os outros caminhos são considerados relativos.
Aqui está um exemplo de hierarquia aninhada.
|
+-- fileA.yml
|
+-- dir1/
|
+-- fileB.yml
|
+-- dir2/
|
+-- fileC.yml
Então, em fileA.yml
você pode referenciar fileB.yml
e fileC.yml
gostar disso.
steps:
- template: dir1/fileB.yml
- template: dir1/dir2/fileC.yml
Se fileC.yml
é o seu ponto de partida, você pode incluir fileA.yml
e fileB.yml
gostar disso.
steps:
- template: ../../fileA.yml
- template: ../fileB.yml
Quando fileB.yml
é o seu ponto de partida, você pode incluir fileA.yml
e fileC.yml
assim.
steps:
- template: ../fileA.yml
- template: dir2/fileC.yml
Alternativamente, fileB.yml
poderia referir-se e fileA.yml
fileC.yml
usar caminhos absolutos como este.
steps:
- template: /fileA.yml
- template: /dir1/dir2/fileC.yml
Usar outros repositórios
Você pode manter seus modelos em outros repositórios. Por exemplo, suponha que você tenha um pipeline principal que deseja que todos os pipelines de aplicativos usem. Você pode colocar o modelo em um repositório principal e, em seguida, consultá-lo a partir de cada um dos repositórios do aplicativo:
# Repo: Contoso/BuildTemplates
# File: common.yml
parameters:
- name: 'vmImage'
default: 'ubuntu-22.04'
type: string
jobs:
- job: Build
pool:
vmImage: ${{ parameters.vmImage }}
steps:
- script: npm install
- script: npm test
Agora você pode reutilizar esse modelo em vários pipelines.
Use a resources
especificação para fornecer a localização do repositório principal.
Quando você se refere ao repositório principal, use @
e o nome que você deu a resources
ele.
# Repo: Contoso/LinuxProduct
# File: azure-pipelines.yml
resources:
repositories:
- repository: templates
type: github
name: Contoso/BuildTemplates
jobs:
- template: common.yml@templates # Template reference
# Repo: Contoso/WindowsProduct
# File: azure-pipelines.yml
resources:
repositories:
- repository: templates
type: github
name: Contoso/BuildTemplates
ref: refs/tags/v1.0 # optional ref to pin to
jobs:
- template: common.yml@templates # Template reference
parameters:
vmImage: 'windows-latest'
Pois type: github
, name
é <identity>/<repo>
como nos exemplos acima.
Para type: git
(Azure Repos), name
é <project>/<repo>
.
Se esse projeto estiver em uma organização separada do Azure DevOps, você precisará configurar uma conexão de serviço do tipo Azure Repos/Team Foundation Server
com acesso ao projeto e incluí-la no YAML:
resources:
repositories:
- repository: templates
name: Contoso/BuildTemplates
endpoint: myServiceConnection # Azure DevOps service connection
jobs:
- template: common.yml@templates
Os repositórios são resolvidos apenas uma vez, quando o pipeline é iniciado. Depois disso, o mesmo recurso é usado durante a duração do pipeline. Somente os arquivos de modelo são usados. Quando os modelos são totalmente expandidos, o pipeline final é executado como se estivesse definido inteiramente no repositório de origem. Isso significa que você não pode usar scripts do repositório de modelos em seu pipeline.
Se você quiser usar uma versão específica e fixa do modelo, certifique-se de fixar em um ref
arquivo .
As refs
são ramificações (refs/heads/<name>
) ou tags (refs/tags/<name>
).
Se você quiser fixar uma confirmação específica, primeiro crie uma tag apontando para essa confirmação e, em seguida, fixe nessa tag.
Nota
Se não ref
for especificado, o pipeline assumirá como padrão o uso refs/heads/main
do .
Você também pode fixar em uma confirmação específica no Git com o valor SHA para um recurso de repositório. O valor SHA é um hash de soma de verificação de 40 caracteres que identifica exclusivamente a confirmação.
resources:
repositories:
- repository: templates
type: git
name: Contoso/BuildTemplates
ref: 1234567890abcdef1234567890abcdef12345678
Você também pode usar @self
para fazer referência ao repositório onde o pipeline original foi encontrado.
Isso é conveniente para uso em extends
modelos se você quiser consultar o conteúdo no repositório do pipeline de extensão.
Por exemplo:
# Repo: Contoso/Central
# File: template.yml
jobs:
- job: PreBuild
steps: []
# Template reference to the repo where this template was
# included from - consumers of the template are expected
# to provide a "BuildJobs.yml"
- template: BuildJobs.yml@self
- job: PostBuild
steps: []
# Repo: Contoso/MyProduct
# File: azure-pipelines.yml
resources:
repositories:
- repository: templates
type: git
name: Contoso/Central
extends:
template: template.yml@templates
# Repo: Contoso/MyProduct
# File: BuildJobs.yml
jobs:
- job: Build
steps: []
FAQ
Como posso utilizar variáveis em modelos?
Por vezes, pode ser útil definir parâmetros como valores baseados em variáveis. Os parâmetros são expandidos no início do processamento de uma execução de pipeline, portanto, nem todas as variáveis estão disponíveis. Para ver que variáveis predefinidas estão disponíveis nos modelos, veja Utilizar variáveis predefinidas.
Neste exemplo, as variáveis Build.SourceBranch
predefinidas e Build.Reason
são usadas em condições em template.yml.
# File: azure-pipelines.yml
trigger:
- main
extends:
template: template.yml
# File: template.yml
steps:
- script: echo Build.SourceBranch = $(Build.SourceBranch) # outputs refs/heads/main
- script: echo Build.Reason = $(Build.Reason) # outputs IndividualCI
- ${{ if eq(variables['Build.SourceBranch'], 'refs/heads/main') }}:
- script: echo I run only if Build.SourceBranch = refs/heads/main
- ${{ if eq(variables['Build.Reason'], 'IndividualCI') }}:
- script: echo I run only if Build.Reason = IndividualCI
- script: echo I run after the conditions