Compartilhar via

Referências de uso de modelo

  • Artigo

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Os modelos permitem definir o conteúdo, a logica e os 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 ajudar você 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 pipeline YAML.

Os modelos também podem ajudar você 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: de inclusão e de extensão.

  • Modelos de inclusão permitem inserir conteúdo reutilizável com um modelo. Se um modelo for usado para incluir conteúdo, ele funcionará como uma diretiva include em muitas linguagens de programação. O conteúdo de um arquivo é inserido em outro arquivo.
  • Modelo de extensão controla o que é permitido em um pipeline. Quando um modelo de extensão controla o que é permitido em um pipeline, o modelo define a lógica que outro arquivo deve seguir.

Para aproveitar ao máximo os modelos, você também deve usar expressões de modelo e parâmetros de modelo.

Limites impostos

Modelos e expressões de modelo podem causar um crescimento explosivo do tamanho e da complexidade de um pipeline. Para ajudar a evitar o crescimento descontrolado, o Azure Pipelines impõe os seguintes limites:

  • Não mais de 100 arquivos YAML separados podem ser incluídos (direta ou indiretamente)
  • Não mais do que 20 níveis de aninhamento de modelos (modelos incluindo outros modelos)
  • Não mais do que 10 megabytes de memória consumidos durante a análise do YAML (na prática, isso costuma estar entre 600 KB e 2 MB de YAML no disco, dependendo dos recursos específicos utilizados)

Use modelos para definir sua lógica uma vez e reutilizá-la várias vezes. Os modelos combinam o conteúdo de vários arquivos YAML em um único pipeline. Passe parâmetros para um modelo por meio do pipeline pai.

Estender de um modelo

Para aumentar a segurança, você pode impor que um pipeline se estenda de um modelo específico. O arquivo start.yml define o parâmetro buildSteps, que é usado no pipeline azure-pipelines.yml. Em start.yml, se um buildStep for passado com uma etapa de script, ele será rejeitado e o build do pipeline falhará. Ao estender 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 de um modelo com recursos

Você também pode usar extends para estender 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ê precise incluir manualmente a mesma lógica em vários lugares. O modelo de arquivo include-npm-steps.yml contém etapas reutilizados no azure-pipelines.yml.

Observação

Os arquivos de modelo precisam existir em seu sistema de arquivos no início de uma execução de pipeline. Não é possível referenciar 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 da etapa

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 trabalho

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 fase

Fases também podem ser reutilizadas 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 modelos a seguir:

  • templates/npm-with-params.yml define dois parâmetros: name e vmImage e cria um trabalho com o parâmetro name para o nome do trabalho e o parâmetro vmImage para a imagem da VM.
  • O pipeline (azure-pipelines.yml) faz referência ao modelo três vezes, cada uma com valores de parâmetro diferentes referentes ao sistema operacional e aos nomes de imagem da VM.
  • O pipeline criado é executado em uma imagem de VM diferente e nomeado de acordo com o sistema operacional especificado. Cada trabalho executa as etapas npm install e npm test.
# 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 de 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 estágio com vários parâmetros

Nos modelos a seguir:

  • O stage-template.yml modelo define quatro parâmetros do tipo string: stageName, jobName, vmImage e scriptPath. O modelo cria um estágio usando o parâmetro stageName para definir o nome do estágio, define um trabalho com jobName e inclui uma etapa para executar um script.
  • O pipeline azure-pipeline.yml define 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 de estágio.

Nos modelos a seguir:

  • O modelo (templates/steps-with-params.yml) define um parâmetro nomeado runExtendedTests com um valor padrão de false.
  • O pipeline (azure-pipelines.yml) executa npm test e npm test --extended porque o parâmetro runExtendedTests é 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 de modelo.

# File: azure-pipelines.yml

steps:
- script: npm install

- template: templates/steps-with-params.yml  # Template reference
  parameters:
    runExtendedTests: 'true'

Observação

Parâmetros escalares sem um tipo especificado são tratados como cadeias de caracteres. Por exemplo, eq(true, parameters['myparam']) retornará true, mesmo que o parâmetro myparam seja a palavra false, se myparam não for explicitamente feito boolean. Cadeias de caracteres não vazias são convertidas em true em um contexto booliano. Essa expressão pode ser reescrita para comparar explicitamente cadeias de caracteres: eq(parameters['myparam'], 'true').

Os parâmetros não estão limitados a cadeias de caracteres escalares. Confira a lista de tipos de dados. Por exemplo, usando o tipo object:

# 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 de variável

As variáveis podem ser definidas em um YAML e incluídas em outro modelo. Isso poderá 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 ao estender 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 de variável com parâmetro

Você pode passar parâmetros para variáveis com modelos. Neste exemplo, você está passando o parâmetro DIRECTORY para uma variável RELEASE_COMMAND.

# 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 de 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 usa 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 em azure-pipeline.yml.

# variables-template.yml

variables:
- name: devVmImage
  value: 'ubuntu-latest'
- name: testVmImage
  value: 'ubuntu-latest'
- name: prodVmImage
  value: 'ubuntu-latest'

O arquivo a seguir stage-template.yml 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 azure-pipelines.yml, importa variáveis de variables-template.yml, e usa o modelo stage-template.yml para cada estágio. Cada estágio (Desenvolvimento, Teste, Produção) é definido com o mesmo modelo, mas com parâmetros diferentes, o que leva à consistência entre os estágios e, ao mesmo tempo, permite 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.

# 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 /. Todos os outros caminhos são considerados relativos.

Aqui está um exemplo de hierarquia aninhada.

|
+-- fileA.yml
|
+-- dir1/
     |
     +-- fileB.yml
     |
     +-- dir2/
          |
          +-- fileC.yml

Em seguida, em fileA.yml, você pode referenciar fileB.yml e fileC.yml deste modo.

steps:
- template: dir1/fileB.yml
- template: dir1/dir2/fileC.yml

Se fileC.yml for seu ponto de partida, você poderá incluir fileA.yml e fileB.yml deste modo.

steps:
- template: ../../fileA.yml
- template: ../fileB.yml

Quando fileB.yml é o ponto de partida, você pode incluir fileA.yml e fileC.yml deste modo.

steps:
- template: ../fileA.yml
- template: dir2/fileC.yml

Alternativamente, fileB.yml poderia se referir a fileA.yml e fileC.yml usando 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 aplicativo usem. Você pode colocar o modelo em um repositório principal e fazer referência a ele de cada um dos seus repositórios de aplicativos:

# 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 especificação resources para fornecer o local do repositório principal. Quando você se referir ao repositório principal, use @ e o nome que você deu a ele em resources.

# 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'

Para 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 o pipeline. Somente os arquivos de modelo são usados. Depois que os modelos forem totalmente expandidos, o pipeline final será executado como se tivesse sido 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 fixa específica do modelo, fixe em um ref. Os refs são branches (refs/heads/<name>) ou marcas (refs/tags/<name>). Se você quiser fixar uma confirmação específica, primeiro crie uma marca apontando para essa confirmação e então fixe nessa marca.

Observação

Se nenhum ref for especificado, o pipeline usará por padrão refs/heads/main.

Você também pode fixar um commit específico no Git com o valor SHA para um recurso de repositório. O valor de SHA é im hash de soma de verificação de 40 caracteres que identifica exclusivamente o commit.

resources:
  repositories:
    - repository: templates
      type: git
      name: Contoso/BuildTemplates
      ref: 1234567890abcdef1234567890abcdef12345678

Você também pode usar @self para se referir ao repositório em que o pipeline original foi encontrado. Isso é conveniente para uso em modelos extends se você quiser fazer referência ao 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: []

Perguntas frequentes

Como posso usar variáveis dentro de modelos?

Há momentos em que pode ser útil definir parâmetros para valores com base em variáveis. Os parâmetros são expandidos no início do processamento de uma execução de pipeline para que nem todas as variáveis estejam disponíveis. Para ver quais variáveis predefinidas estão disponíveis em modelos, confira Usar variáveis predefinidas.

Neste exemplo, as variáveis predefinidas Build.SourceBranch 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