Referensi penggunaan templat

  • Artikel

Layanan Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019

Templat memungkinkan Anda menentukan konten, logika, dan parameter yang dapat digunakan kembali dalam alur YAML. Untuk bekerja dengan templat secara efektif, Anda harus memiliki pemahaman dasar tentang konsep kunci Azure Pipelines seperti tahapan, langkah, dan pekerjaan.

Templat dapat membantu Anda mempercepat pengembangan. Misalnya, Anda dapat memiliki serangkaian tugas yang sama dalam templat lalu menyertakan templat beberapa kali dalam tahap yang berbeda dari alur YAML Anda.

Templat juga dapat membantu Anda mengamankan alur Anda. Saat templat mengontrol apa yang diizinkan dalam alur, templat menentukan logika yang harus diikuti file lain. Misalnya, Anda mungkin ingin membatasi tugas apa yang diizinkan untuk dijalankan. Untuk skenario tersebut, Anda dapat menggunakan templat untuk mencegah seseorang berhasil menjalankan tugas yang melanggar kebijakan keamanan organisasi Anda.

Ada dua jenis templat: termasuk dan diperluas.

  • Menyertakan templat memungkinkan Anda menyisipkan konten yang dapat digunakan kembali dengan templat. Jika templat digunakan untuk menyertakan konten, templat berfungsi seperti direktif sertakan dalam banyak bahasa pemrograman. Isi dari satu file disisipkan ke file lain.
  • Memperluas kontrol templat apa yang diizinkan dalam alur. Saat templat memperluas kontrol apa yang diizinkan dalam alur, templat menentukan logika yang harus diikuti file lain.

Untuk memanfaatkan templat sepenuhnya, Anda juga harus menggunakan ekspresi templat dan parameter templat.

Batas yang diberlakukan

Templat dan ekspresi templat dapat menyebabkan pertumbuhan eksplosif pada ukuran dan kompleksitas alur. Untuk membantu mencegah pertumbuhan runaway, Azure Pipelines memberlakukan batas berikut:

  • Tidak lebih dari 100 file YAML terpisah dapat disertakan (langsung atau tidak langsung)
  • Tidak lebih dari 20 tingkat pelapisan templat (templat yang meliputi templat lain)
  • Tidak lebih dari 10 megabyte memori yang digunakan saat mengurai YAML (dalam praktiknya, ini biasanya antara 600 KB - 2 MB YAML pada disk, tergantung pada fitur spesifik yang digunakan)

Gunakan templat untuk menentukan logika Anda sekali lalu gunakan kembali beberapa kali. Template menggabungkan konten beberapa file YAML ke dalam satu alur. Anda dapat meneruskan parameter ke dalam templat dari alur induk Anda.

Memperluas dari templat

Untuk meningkatkan keamanan, Anda dapat memberlakukan bahwa alur meluas dari templat tertentu. File start.yml menentukan parameter buildSteps, yang kemudian digunakan dalam alur azure-pipelines.yml. Di start.yml, jika buildStep diteruskan dengan langkah skrip, maka ditolak dan build alur gagal. Saat memperluas dari templat, Anda dapat meningkatkan keamanan dengan menambahkan persetujuan templat yang diperlukan.

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

Perluas dari templat dengan sumber daya

Anda juga dapat menggunakan extends untuk memperluas dari templat di alur Azure Anda yang berisi sumber daya.

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

Menyisipkan templat

Anda dapat menyalin konten dari satu YAML dan menggunakannya kembali di YAML yang berbeda. Menyalin konten dari satu YAML ke YAML lainnya akan menghemat Anda agar tidak perlu menyertakan logika yang sama secara manual di beberapa tempat. include-npm-steps.yml Templat file berisi langkah-langkah yang digunakan kembali di azure-pipelines.yml.

Catatan

File templat harus ada di sistem file Anda di awal eksekusi alur. Anda tidak dapat mereferensikan templat dalam artefak.

# 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

Penggunaan kembali langkah

Anda dapat menyisipkan templat untuk menggunakan kembali satu atau beberapa langkah di beberapa pekerjaan. Selain langkah-langkah dari templat, setiap pekerjaan dapat menentukan lebih banyak langkah.

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

Penggunaan kembali pekerjaan

Sama seperti langkah-langkah, pekerjaan dapat digunakan kembali dengan templat.

# 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

Saat bekerja dengan beberapa pekerjaan, ingatlah untuk menghapus nama pekerjaan dalam file templat, sehingga menghindari konflik

# 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

Penggunaan kembali tahap

Tahapan juga dapat digunakan kembali dengan templat.

# 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

Templat pekerjaan, tahap, dan langkah dengan parameter

# 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

Saat Anda menggunakan templat di alur Anda, tentukan nilai untuk parameter templat.

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

Anda juga dapat menggunakan parameter dengan templat langkah atau tahap. Misalnya, langkah-langkah dengan parameter:

# 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

Saat Anda menggunakan templat di alur Anda, tentukan nilai untuk parameter templat.

# File: azure-pipelines.yml

steps:
- script: npm install

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

Catatan

Parameter skalar tanpa jenis tertentu diperlakukan sebagai string. Misalnya, eq(true, parameters['myparam']) akan mengembalikan true, bahkan jika myparam parameternya adalah kata false, jika myparam tidak dibuat booleansecara eksplisit . String yang tidak kosong dilemparkan ke true dalam konteks Boolean. Ekspresi tersebut dapat ditulis ulang untuk membandingkan string secara eksplisit: eq(parameters['myparam'], 'true').

Parameter tidak terbatas pada string skalar. Lihat daftar jenis data. Misalnya, menggunakan object jenis :

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

Penggunaan kembali variabel

Variabel dapat didefinisikan dalam satu YAML dan disertakan dalam templat lain. Ini bisa berguna jika Anda ingin menyimpan semua variabel Anda dalam satu file. Jika Anda menggunakan templat untuk menyertakan variabel dalam alur, templat yang disertakan hanya dapat digunakan untuk menentukan variabel. Anda dapat menggunakan langkah-langkah dan logika yang lebih kompleks saat memperluas dari templat. Gunakan parameter alih-alih variabel saat Anda ingin membatasi jenis.

Dalam contoh ini, variabel favoriteVeggie disertakan dalam 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 }}.

Templat variabel dengan parameter

Anda dapat meneruskan parameter ke variabel dengan templat. Dalam contoh ini, Anda meneruskan parameter ke DIRECTORYRELEASE_COMMAND variabel.

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

Saat Anda menggunakan templat di alur Anda, tentukan nilai untuk parameter templat.

# 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

Jalur templat referensi

Jalur templat dapat menjadi jalur absolut dalam repositori atau relatif terhadap file yang menyertakan.

Untuk menggunakan jalur absolut, jalur templat harus dimulai dengan /. Semua jalur lain dianggap relatif.

Berikut adalah contoh hierarki berlapis.

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

Kemudian, dalam fileA.yml Anda dapat mereferensikan fileB.yml dan fileC.yml seperti ini.

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

Jika fileC.yml adalah titik awal Anda, Anda dapat menyertakan fileA.yml dan fileB.yml menyukai ini.

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

Kapan fileB.yml titik awal Anda, Anda dapat menyertakan fileA.yml dan fileC.yml menyukai ini.

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

Atau, fileB.yml dapat merujuk ke fileA.yml dan fileC.yml menggunakan jalur absolut seperti ini.

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

Gunakan repositori lain

Anda dapat menyimpan templat Anda di repositori lain. Misalnya, Anda memiliki alur inti yang Anda inginkan untuk digunakan oleh semua alur aplikasi Anda. Anda dapat menempatkan templat dalam repositori inti lalu merujuknya dari setiap repositori aplikasi Anda:

# 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

Sekarang Anda dapat menggunakan kembali templat ini di beberapa alur. resources Gunakan spesifikasi untuk menyediakan lokasi repositori inti. Ketika Anda merujuk ke repositori inti, gunakan @ dan nama yang Anda berikan di 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'

Untuk type: github, name adalah <identity>/<repo> seperti dalam contoh di atas. Untuk type: git (Azure Repos), name adalah <project>/<repo>. Jika proyek tersebut berada dalam organisasi Azure DevOps terpisah, Anda harus mengonfigurasi koneksi layanan jenis Azure Repos/Team Foundation Server dengan akses ke proyek dan menyertakannya dalam YAML:

resources:
  repositories:
  - repository: templates
    name: Contoso/BuildTemplates
    endpoint: myServiceConnection # Azure DevOps service connection
jobs:
- template: common.yml@templates

Repositori diselesaikan hanya sekali, ketika alur dimulai. Setelah itu, sumber daya yang sama digunakan untuk durasi alur. Hanya file templat yang digunakan. Setelah templat diperluas sepenuhnya, alur akhir berjalan seolah-olah didefinisikan sepenuhnya dalam repositori sumber. Ini berarti Anda tidak dapat menggunakan skrip dari repositori templat di alur Anda.

Jika Anda ingin menggunakan versi templat tertentu yang tetap, pastikan untuk menyematkan ke ref. refs adalah cabang (refs/heads/<name>) atau tag (refs/tags/<name>). Jika Anda ingin menyematkan penerapan tertentu, pertama-tama buat tag yang menunjuk ke penerapan tersebut, lalu sematkan ke tag tersebut.

Catatan

Jika tidak ref ada yang ditentukan, alur akan default menggunakan refs/heads/main.

Anda juga dapat menyematkan ke penerapan tertentu di Git dengan nilai SHA untuk sumber daya repositori. Nilai SHA adalah hash checksum 40 karakter yang secara unik mengidentifikasi penerapan.

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

Anda juga dapat menggunakan @self untuk merujuk ke repositori tempat alur asli ditemukan. Ini nyaman digunakan dalam extends templat jika Anda ingin merujuk kembali ke konten di repositori alur yang diperluas. Misalnya:

# 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

Bagaimana cara menggunakan variabel di dalam template?

Ada kalanya mengatur parameter ke nilai berdasarkan variabel mungkin berguna. Parameter diperluas lebih awal dalam memproses eksekusi alur sehingga tidak semua variabel tersedia. Untuk melihat variabel yang telah ditentukan sebelumnya yang tersedia dalam template, lihat Menggunakan variabel yang telah ditentukan sebelumnya.

Dalam contoh ini, variabel Build.SourceBranch yang telah ditentukan sebelumnya dan Build.Reason digunakan dalam kondisi dalam 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