Riferimento allo schema YAML

Azure Pipelines

Questo articolo è una guida di riferimento dettagliata per Azure Pipelines pipeline YAML. Include un catalogo di tutte le funzionalità YAML supportate e le opzioni disponibili.

Il modo migliore per iniziare a usare le pipeline YAML è leggere la guida introduttiva. Successivamente, per informazioni su come configurare la pipeline YAML in base alle proprie esigenze, vedere argomenti concettuali come Variabili di compilazione e Processi.

Per informazioni su come configurare la pipeline YAML in base alle proprie esigenze, vedere argomenti concettuali come Variabili di compilazione e Processi.

Struttura della pipeline

Una pipeline è costituita da una o più fasi che descrivono un processo CI/CD. Le fasi sono le divisioni principali in una pipeline. Le fasi "Build this app", "Run these tests" (Esegui questi test) e "Deploy to preproduction" (Distribuisci in pre-produzione) sono esempi di buon livello.

Una fase è uno o più processi, ovvero unità di lavoro assegnabili allo stesso computer. È possibile organizzare le fasi e i processi in grafici dipendenze. Ad esempio, "Esegui questa fase prima di quella" e "Questo processo dipende dall'output del processo".

Un processo è una serie lineare di passaggi. I passaggi possono essere attività, script o riferimenti a modelli esterni.

Questa gerarchia si riflette nella struttura di un file YAML, ad esempio:

  • Pipeline
    • Fase A
      • Processo 1
        • Passaggio 1.1
        • Passaggio 1.2
        • ...
      • Processo 2
        • Passaggio 2.1
        • Passaggio 2.2
        • ...
    • Fase B
      • ...

Le pipeline semplici non richiedono tutti questi livelli. Ad esempio, in una compilazione a processo singolo è possibile omettere i contenitori per le fasi e i processi perché sono presenti solo passaggi. Poiché molte opzioni illustrate in questo articolo non sono necessarie e hanno valori predefiniti, è improbabile che le definizioni YAML includano tutte.

Una pipeline è uno o più processi che descrivono un processo CI/CD. Un processo è un'unità di lavoro assegnabile allo stesso computer. È possibile disporre i processi in grafici delle dipendenze, ad esempio "Questo processo dipende dall'output del processo".

Un processo è una serie lineare di passaggi. I passaggi possono essere attività, script o riferimenti a modelli esterni.

Questa gerarchia si riflette nella struttura di un file YAML, ad esempio:

  • Pipeline
    • Processo 1
      • Passaggio 1.1
      • Passaggio 1.2
      • ...
    • Processo 2
      • Passaggio 2.1
      • Passaggio 2.2
      • ...

Per le pipeline a processo singolo, è possibile omettere il contenitore dei processi perché sono presenti solo passaggi. Poiché molte opzioni illustrate in questo articolo non sono necessarie e hanno valori predefiniti, è improbabile che le definizioni YAML includano tutte.

Convenzioni

Ecco le convenzioni della sintassi usate in questo articolo:

  • A sinistra di è presente : una parola chiave letterale usata nelle definizioni della pipeline.
  • A destra di : è presente un tipo di dati. Il tipo di dati può essere un tipo primitivo, ad esempio string, o un riferimento a una struttura avanzata definita altrove in questo articolo.
  • La notazione [ datatype ] indica una matrice del tipo di dati indicato. Ad esempio, [ string ] è una matrice di stringhe.
  • La notazione { datatype : datatype } indica un mapping di un tipo di dati a un altro. Ad esempio, { string: string } è un mapping di stringhe a stringhe.
  • Il simbolo | indica che sono disponibili più tipi di dati per la parola chiave . Ad esempio, job | templateReference indica che è consentita una definizione di processo o un riferimento a un modello.

Informazioni di base su YAML

Questo documento illustra lo schema di un Azure Pipelines file YAML. Per informazioni di base su YAML, vedere Learn YAML in Y Minutes (Apprendere YAML in minuti Y). Azure Pipelines non supporta tutte le funzionalità YAML. Le funzionalità non supportate includono ancoraggi, chiavi complesse e set. Inoltre, a differenza di YAML standard, Azure Pipelines dipende dalla visualizzazione di , , o di un collegamento di attività come la prima stage job chiave in un task script mapping.

Pipeline

name: string  # build numbering format
resources:
  pipelines: [ pipelineResource ]
  containers: [ containerResource ]
  repositories: [ repositoryResource ]
variables: # several syntaxes, see specific section
trigger: trigger
pr: pr
stages: [ stage | templateReference ]

Se si dispone di una singola fase,è possibile omettere la parola stages chiave e specificare direttamente la parola chiave jobs:

# ... other pipeline-level keywords
jobs: [ job | templateReference ]

Se si dispone di una singola fase e di un singolo processo, è possibile omettere le parole chiave e stages e specificare direttamente la parola chiave jobs steps:

# ... other pipeline-level keywords
steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]
name: string  # build numbering format
resources:
  containers: [ containerResource ]
  repositories: [ repositoryResource ]
variables: # several syntaxes, see specific section
trigger: trigger
pr: pr
jobs: [ job | templateReference ]

Se si ha un singolo processo, è possibile omettere la parola jobs chiave e specificare direttamente la parola chiave steps:

# ... other pipeline-level keywords
steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]

Sono disponibili altre informazioni su:

Fase

Una fase è una raccolta di processi correlati. Per impostazione predefinita, le fasi vengono eseguite in sequenza. Ogni fase inizia solo dopo il completamento della fase precedente, se non diversamente specificato tramite la dependsOn proprietà .

Usare i controlli di approvazione per controllare manualmente quando deve essere eseguita una fase. Questi controlli vengono comunemente usati per controllare le distribuzioni negli ambienti di produzione.

I controlli sono un meccanismo disponibile per il proprietario della risorsa. Controllano quando una fase in una pipeline usa una risorsa. In qualità di proprietario di una risorsa come un ambiente, è possibile definire i controlli necessari prima dell'avvio di una fase che utilizza la risorsa.

Attualmente, i controlli di approvazione manuale sono supportati negli ambienti. Per altre informazioni, vedere Approvazioni.

stages:
- stage: string  # name of the stage (A-Z, a-z, 0-9, and underscore)
  displayName: string  # friendly name to display in the UI
  dependsOn: string | [ string ]
  condition: string
  variables: # several syntaxes, see specific section
  jobs: [ job | templateReference]

Altre informazioni sulle fasi, le condizionie le variabili.

Processo

Un processo è una raccolta di passaggi eseguiti da un agente o in un server. I processi possono essere eseguiti in modo condizionale e possono dipendere da processi precedenti.

jobs:
- job: string  # name of the job (A-Z, a-z, 0-9, and underscore)
  displayName: string  # friendly name to display in the UI
  dependsOn: string | [ string ]
  condition: string
  strategy:
    parallel: # parallel strategy; see the following "Parallel" topic
    matrix: # matrix strategy; see the following "Matrix" topic
    maxParallel: number # maximum number of matrix jobs to run simultaneously
  continueOnError: boolean  # 'true' if future jobs should run even if this job fails; defaults to 'false'
  pool: pool # see the following "Pool" schema
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs
  container: containerReference # container to run this job inside of
  timeoutInMinutes: number # how long to run the job before automatically cancelling
  cancelTimeoutInMinutes: number # how much time to give 'run always even if cancelled tasks' before killing them
  variables: # several syntaxes, see specific section
  steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]
  services: { string: string | container } # container resources to run as a service container
  uses: # Any resources (repos or pools) required by this job that are not already referenced
    repositories: [ string ] # Repository references to Azure Git repositories
    pools: [ string ] # Pool names, typically when using a matrix strategy for the job

Per altre informazioni su uses , vedere Limitare l'ambito di autorizzazionedel processo Azure DevOps repository a cui si fa riferimento. Per altre informazioni sulle aree di lavoro, incluse le opzioni di pulizia, vedere l'argomento relativo alle aree di lavoro in Processi.

jobs:
- job: string  # name of the job (A-Z, a-z, 0-9, and underscore)
  displayName: string  # friendly name to display in the UI
  dependsOn: string | [ string ]
  condition: string
  strategy:
    parallel: # parallel strategy; see the following "Parallel" topic
    matrix: # matrix strategy; see the following "Matrix" topic
    maxParallel: number # maximum number of matrix jobs to run simultaneously
  continueOnError: boolean  # 'true' if future jobs should run even if this job fails; defaults to 'false'
  pool: pool # see the following "Pool" schema
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs
  container: containerReference # container to run this job inside of
  timeoutInMinutes: number # how long to run the job before automatically cancelling
  cancelTimeoutInMinutes: number # how much time to give 'run always even if cancelled tasks' before killing them
  variables: # several syntaxes, see specific section
  steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]
  services: { string: string | container } # container resources to run as a service container

Per altre informazioni sulle aree di lavoro, incluse le opzioni di pulizia, vedere l'argomento relativo alle aree di lavoro in Processi.

Altre informazioni su variabili, passaggi, poole processi server.

Nota

Se si dispone di una sola fase e di un processo, è possibile usare la sintassi a processo singolo come modo più breve per descrivere i passaggi da eseguire.

Informazioni di riferimento sul contenitore

Un contenitore è supportato dai processi.

container: string # Docker Hub image reference or resource alias
container:
  image: string  # container image name
  options: string  # arguments to pass to container at startup
  endpoint: string  # endpoint for a private container registry
  env: { string: string }  # list of environment variables to add
  # you can also use any of the other supported container attributes

Strategie

Le matrix parole chiave e parallel specificano strategie che si escludono a vicenda per duplicare un processo.

Matrice

L'uso di una matrice genera copie di un processo, ognuna con input diverso. Queste copie sono utili per il test su configurazioni o versioni della piattaforma diverse.

strategy:
  matrix: { string1: { string2: string3 } }
  maxParallel: number

Per ogni occorrenza di string1 nella matrice, viene generata una copia del processo. Il nome string1 è il nome della copia e viene aggiunto al nome del processo. Per ogni occorrenza di string2, una variabile denominata string2 con il valore string3 è disponibile per il processo.

Nota

I nomi di configurazione della matrice devono contenere solo lettere alfabetiche latini di base (A-Z e a-z), cifre (0-9) e caratteri di sottolineatura ( _ ). Devono iniziare con una lettera. Inoltre, la lunghezza deve essere di 100 caratteri o meno.

La parola maxParallel chiave facoltativa specifica il numero massimo di matrici simultanee da eseguire contemporaneamente.

Se maxParallel non è specificato o è impostato su 0, non viene applicato alcun limite.

Se maxParallel non è specificato, non viene applicato alcun limite.

Nota

La matrix sintassi non supporta il ridimensionamento automatico dei processi, ma è possibile implementare funzionalità simili usando la parola each chiave . Per un esempio, vedere espressioni.

Parallelo

Questa strategia specifica il numero di duplicati di un processo da eseguire. È utile per il selicing di una matrice di test di grandi dimensioni. L Visual Studio test di carico è in grado di dividere il carico di test tra il numero di processi pianificati.

strategy:
  parallel: number

Processo di distribuzione

Un processo di distribuzione è un tipo speciale di processo. Si tratta di una raccolta di passaggi da eseguire in sequenza nell'ambiente. Nelle pipeline YAML è consigliabile inserire i passaggi di distribuzione in un processo di distribuzione.

jobs:
- deployment: string   # name of the deployment job, A-Z, a-z, 0-9, and underscore. The word "deploy" is a keyword and is unsupported as the deployment name.
  displayName: string  # friendly name to display in the UI
  pool:                # see pool schema
    name: string       # Use only global level variables for defining a pool name. Stage/job level variables are not supported to define pool name.
    demands: string | [ string ]
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs
  dependsOn: string
  condition: string
  continueOnError: boolean                # 'true' if future jobs should run even if this job fails; defaults to 'false'
  container: containerReference # container to run this job inside
  services: { string: string | container } # container resources to run as a service container
  timeoutInMinutes: nonEmptyString        # how long to run the job before automatically cancelling
  cancelTimeoutInMinutes: nonEmptyString  # how much time to give 'run always even if cancelled tasks' before killing them
  variables: # several syntaxes, see specific section
  environment: string  # target environment name and optionally a resource name to record the deployment history; format: <environment-name>.<resource-name>
  strategy:
    runOnce:    #rolling, canary are the other strategies that are supported
      deploy:
        steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]

Passaggi

Un passaggio è una sequenza lineare di operazioni che costituiscono un processo. Ogni passaggio viene eseguito nel proprio processo in un agente e ha accesso all'area di lavoro della pipeline in un disco rigido locale. Questo comportamento significa che le variabili di ambiente non vengono mantenute tra i passaggi, ma file system modifiche.

steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]

Per altre informazioni sui passaggi, vedere i riferimenti allo schema per:

Tutti i passaggi, indipendentemente dal fatto che siano documentati in questo articolo, supportano le proprietà seguenti:

  • displayName
  • nome
  • Condizione
  • continueOnError
  • abilitata
  • Env
  • timeoutInMinutes

Variabili

È possibile aggiungere direttamente valori hard coded, fare riferimento a gruppi di variabilio inserire tramite modelli di variabili.

Specificare le variabili a livello di pipeline, fase o processo.

Per un semplice set di variabili hard coded, usare la sintassi di mapping seguente:

variables: { string: string }

Per includere gruppi di variabili, passare a questa sintassi di sequenza:

variables:
- name: string  # name of a variable
  value: string # value of the variable
- group: string # name of a variable group

È possibile ripetere name / value coppie e group .

Le variabili possono anche essere impostate come di sola lettura per migliorare la sicurezza.

variables:
- name: myReadOnlyVar
  value: myValue
  readonly: true

È anche possibile includere variabili dai modelli.

Informazioni di riferimento sui modelli

Nota

Assicurarsi di vedere la sintassi completa dell'espressione di modello, che è di tutte le forme di ${{ }} .

È possibile esportare sezioni riutilizzabili della pipeline in un file separato. Questi file separati sono noti come modelli.

Azure Pipelines supporta quattro tipi di modelli:

È anche possibile usare i modelli per controllare ciò che è consentito in una pipeline e per definire come è possibile usare i parametri.

È possibile esportare sezioni riutilizzabili della pipeline in file separati. Questi file separati sono noti come modelli. Azure DevOps Server 2019 supporta questi due tipi di modelli:

I modelli stessi possono includere altri modelli. Azure Pipelines supporta un massimo di 50 file modello univoci in una singola pipeline.

Modelli di fase

È possibile definire un set di fasi in un file e usarlo più volte in altri file.

Nella pipeline principale:

- template: string # name of template to include
  parameters: { string: any } # provided parameters

Nel modello incluso:

parameters: { string: any } # expected parameters
stages: [ stage ]

Modelli di processo

È possibile definire un set di processi in un file e usarlo più volte in altri file.

Nella pipeline principale:

- template: string # name of template to include
  parameters: { string: any } # provided parameters

Nel modello incluso:

parameters: { string: any } # expected parameters
jobs: [ job ]

Per altre informazioni sull'uso dei modelli di processo, vedere modelli.

Modelli di passaggio

È possibile definire un set di passaggi in un file e usarlo più volte in un altro file.

Nella pipeline principale:

steps:
- template: string  # reference to template
  parameters: { string: any } # provided parameters

Nel modello incluso:

parameters: { string: any } # expected parameters
steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]

Per altre informazioni sull'uso dei modelli, vedere modelli.

Modelli di variabile

È possibile definire un set di variabili in un file e usarlo più volte in altri file.

Nella pipeline principale:

- template: string            # name of template file to include
  parameters: { string: any } # provided parameters

Nel modello incluso:

parameters: { string: any }   # expected parameters
variables: [ variable ]

Nota

La variables parola chiave usa due forme di sintassi: sequenza e mapping. Nella sintassi di mapping tutte le chiavi sono nomi di variabili e i relativi valori sono valori variabili. Per usare i modelli di variabile, è necessario usare la sintassi di sequenza. La sintassi della sequenza richiede di specificare se si sta citando una variabile ( ), un gruppo di variabili name ( ) o un modello ( group template ). Per altre informazioni, vedere l'argomento relativo alle variabili.

Parametri

È possibile usare i parametri in modelli e pipeline.

I campi tipo e nome sono obbligatori per la definizione dei parametri. Vedere tutti i tipi di dati dei parametri.

parameters:
- name: string          # name of the parameter; required
  type: enum            # see the enum data types in the following section
  default: any          # default value; if no default, then the parameter MUST be given by the user at runtime
  values: [ string ]    # allowed list of values (for some data types)

Tipi

Il type valore deve essere uno dei membri della tabella enum seguente.

Tipo di dati Note
string string
number può essere limitato a values: . In caso contrario, viene accettata qualsiasi stringa simile a un numero
boolean true o false
object qualsiasi struttura YAML
step un singolo passaggio
stepList sequenza di passaggi
job un singolo processo
jobList sequenza di processi
deployment un singolo processo di distribuzione
deploymentList sequenza di processi di distribuzione
stage una singola fase
stageList sequenza di fasi

I tipi di dati stepList, job, jobList, deployment, deploymentList, stage e stageList usano tutti il formato di schema YAML standard. Questo esempio include string, number, boolean, object, step e stepList.

parameters:
- name: myString
  type: string
  default: a string
- name: myMultiString
  type: string
  default: default
  values:
  - default
  - ubuntu
- name: myNumber
  type: number
  default: 2
  values:
  - 1
  - 2
  - 4
  - 8
  - 16
- name: myBoolean
  type: boolean
  default: true
- name: myObject
  type: object
  default:
    foo: FOO
    bar: BAR
    things:
    - one
    - two
    - three
    nested:
      one: apple
      two: pear
      count: 3
- name: myStep
  type: step
  default:
    script: echo my step
- name: mySteplist
  type: stepList
  default:
    - script: echo step one
    - script: echo step two

trigger: none

jobs: 
- job: stepList
  steps: ${{ parameters.mySteplist }}
- job: myStep
  steps:
    - ${{ parameters.myStep }}

Risorse

Una risorsa è qualsiasi servizio esterno che viene utilizzato come parte della pipeline. Un esempio di risorsa è un'altra pipeline CI/CD che produce:

  • Artifacts come Azure Pipelines o Jenkins.
  • Repository di codice come GitHub, Azure Repos o Git.
  • Registri di immagini del contenitore come Registro Azure Container o l'hub Docker.

Le risorse in YAML rappresentano origini di pipeline, contenitori, repository e tipi. Per altre informazioni sulle risorse, vedere qui.

Schema generale

resources:
  pipelines: [ pipeline ]  
  builds: [ build ]
  repositories: [ repository ]
  containers: [ container ]
  packages: [ package ]

Risorsa pipeline

Se si dispone di una pipeline di Azure che produce artefatti, la pipeline può utilizzare gli artefatti usando la parola chiave pipeline per definire una risorsa della pipeline. È anche possibile abilitare i trigger di completamento della pipeline.

resources:
  pipelines:
  - pipeline: string  # identifier for the resource used in pipeline resource variables
    project: string # project for the source; optional for current project
    source: string  # name of the pipeline that produces an artifact
    version: string  # the pipeline run number to pick the artifact, defaults to latest pipeline successful across all stages; Used only for manual or scheduled triggers
    branch: string  # branch to pick the artifact, optional; defaults to all branches; Used only for manual or scheduled triggers
    tags: [ string ] # list of tags required on the pipeline to pickup default artifacts, optional; Used only for manual or scheduled triggers
    trigger:     # triggers are not enabled by default unless you add trigger section to the resource
      branches:  # branch conditions to filter the events, optional; Defaults to all branches.
        include: [ string ]  # branches to consider the trigger events, optional; Defaults to all branches.
        exclude: [ string ]  # branches to discard the trigger events, optional; Defaults to none.
      tags: [ string ]  # list of tags to evaluate for trigger event, optional; 2020.1 and greater
      stages: [ string ] # list of stages to evaluate for trigger event, optional; 2020.1 and greater

Importante

Quando si definisce un trigger di risorsa, se la relativa risorsa della pipeline deriva dallo stesso repo della pipeline corrente, l'attivazione segue lo stesso ramo e il commit in cui viene generato l'evento. Tuttavia, se la risorsa della pipeline deriva da un altro repo, la pipeline corrente viene attivata nel ramo specificato dall'impostazione Ramo predefinito per compilazioni manuali e pianificate. Per altre informazioni, vedere Considerazioni sui rami per i trigger di completamento della pipeline.

Metadati delle risorse della pipeline come variabili predefinite

In ogni esecuzione, i metadati per una risorsa della pipeline sono disponibili per tutti i processi come variabili predefinite:

resources.pipeline.<Alias>.projectName
resources.pipeline.<Alias>.projectID
resources.pipeline.<Alias>.pipelineName
resources.pipeline.<Alias>.pipelineID
resources.pipeline.<Alias>.runName
resources.pipeline.<Alias>.runID
resources.pipeline.<Alias>.runURI
resources.pipeline.<Alias>.sourceBranch
resources.pipeline.<Alias>.sourceCommit
resources.pipeline.<Alias>.sourceProvider
resources.pipeline.<Alias>.requestedFor
resources.pipeline.<Alias>.requestedForID

È possibile utilizzare gli artefatti da una risorsa della pipeline usando download un'attività. Vedere la parola chiave download.

Risorsa contenitore

I processi contenitore consentono di isolare gli strumenti e le dipendenze all'interno di un contenitore. L'agente avvia un'istanza del contenitore specificato e quindi esegue i passaggi al suo interno. La container parola chiave consente di specificare le immagini del contenitore.

I contenitori di servizi vengono eseguiti insieme a un processo per fornire varie dipendenze, ad esempio i database.

resources:
  containers:
  - container: string  # identifier (A-Z, a-z, 0-9, and underscore)
    image: string  # container image name
    options: string  # arguments to pass to container at startup
    endpoint: string  # reference to a service connection for the private registry
    env: { string: string }  # list of environment variables to add
    ports: [ string ] # ports to expose on the container
    volumes: [ string ] # volumes to mount on the container
    mapDockerSocket: bool # whether to map in the Docker daemon socket; defaults to true
    mountReadOnly:  # volumes to mount read-only - all default to false
      externals: boolean  # components required to talk to the agent
      tasks: boolean  # tasks required by the job
      tools: boolean  # installable tools like Python and Ruby
      work: boolean # the work directory
resources:
  containers:
  - container: string  # identifier (A-Z, a-z, 0-9, and underscore)
    image: string  # container image name
    options: string  # arguments to pass to container at startup
    endpoint: string  # reference to a service connection for the private registry
    env: { string: string }  # list of environment variables to add
    ports: [ string ] # ports to expose on the container
    volumes: [ string ] # volumes to mount on the container
    mapDockerSocket: bool # whether to map in the Docker daemon socket; defaults to true
resources:
  containers:
  - container: string  # identifier (A-Z, a-z, 0-9, and underscore)
    image: string  # container image name
    options: string  # arguments to pass to container at startup
    endpoint: string  # reference to a service connection for the private registry
    env: { string: string }  # list of environment variables to add
    ports: [ string ] # ports to expose on the container
    volumes: [ string ] # volumes to mount on the container

Risorsa repository

Se la pipeline contiene modelli in un altro repository,è necessario inserirne le informazioni sul sistema. La repository parola chiave consente di specificare un repository esterno.

Se la pipeline contiene modelli in un altro repositoryo se si vuole usare la transazione con più repository con un repository che richiede una connessione al servizio, è necessario instradare il sistema a tale repository. La repository parola chiave consente di specificare un repository esterno.

resources:
  repositories:
  - repository: string  # identifier (A-Z, a-z, 0-9, and underscore)
    type: enum  # see the following "Type" topic
    name: string  # repository name (format depends on `type`)
    ref: string  # ref name to use; defaults to 'refs/heads/main'
    endpoint: string  # name of the service connection to use (for types that aren't Azure Repos)
    trigger:  # CI trigger for this repository, no CI trigger if skipped (only works for Azure Repos)
      branches:
        include: [ string ] # branch names which will trigger a build
        exclude: [ string ] # branch names which will not
      tags:
        include: [ string ] # tag names which will trigger a build
        exclude: [ string ] # tag names which will not
      paths:
        include: [ string ] # file paths which must match to trigger a build
        exclude: [ string ] # file paths which will not trigger a build

Tipo

Pipelines supportano i valori seguenti per il tipo di repository: git github , e bitbucket . Il git tipo fa riferimento Azure Repos repository Git.

  • Se si specifica type: git , il valore fa riferimento a un altro repository nello stesso name progetto. Un esempio è name: otherRepo. Per fare riferimento a un repo in un altro progetto all'interno della stessa organizzazione, aggiungere al nome il nome del progetto. Un esempio è name: OtherProject/otherRepo.

  • Se si specifica , il valore è il nome completo del type: github name GitHub e include l'utente o l'organizzazione. Un esempio è name: Microsoft/vscode. GitHub repository richiedono una connessione GitHub servizio per l'autorizzazione.

  • Se si specifica , il valore è il nome completo del type: bitbucket name repo di Bitbucket Cloud e include l'utente o l'organizzazione. Un esempio è name: MyBitbucket/vscode. I repository cloud Bitbucket richiedono una connessione al servizio cloud Bitbucket per l'autorizzazione.

Risorsa Packages

È possibile usare NuGet e npm GitHub come risorsa nelle pipeline YAML. Quando si specificano le risorse del pacchetto, impostare il pacchetto NuGet su o npm .

resources:
  packages:
    - package: myPackageAlias # alias for the package resource
      type: Npm # type of the package NuGet/npm
      connection: GitHubConnectionName # Github service connection with the PAT type
      name: nugetTest/nodeapp # <Repository>/<Name of the package>
      version: 1.0.1 # Version of the packge to consume; Optional; Defaults to latest
      trigger: true # To enable automated triggers (true/false); Optional; Defaults to no triggers

Trigger

Nota

I blocchi di trigger non possono contenere variabili o espressioni di modello.

Trigger di push

Un trigger di push specifica quali rami causano l'esecuzione di una compilazione di integrazione continua. Se non si specifica alcun trigger di push, i push in qualsiasi ramo attivano una compilazione. Altre informazioni sui trigger e su come specificarli.

Per la parola chiave sono disponibili tre opzioni di sintassi distinte: un elenco di rami da includere, un modo per disabilitare i trigger CI e la sintassi completa per trigger il controllo completo.

Sintassi dell'elenco:

trigger: [ string ] # list of branch names

Sintassi di disabilitazione:

trigger: none # will disable CI builds entirely

Sintassi completa:

trigger:
  batch: boolean # batch changes if true; start a new build for every push if false (default)
  branches:
    include: [ string ] # branch names which will trigger a build
    exclude: [ string ] # branch names which will not
  tags:
    include: [ string ] # tag names which will trigger a build
    exclude: [ string ] # tag names which will not
  paths:
    include: [ string ] # file paths which must match to trigger a build
    exclude: [ string ] # file paths which will not trigger a build

Se si specifica una clausola senza una clausola per , o , equivale exclude include a specificare nella branches tags paths * include clausola .

trigger:
  batch: boolean # batch changes if true; start a new build for every push if false (default)
  branches:
    include: [ string ] # branch names which will trigger a build
    exclude: [ string ] # branch names which will not
  paths:
    include: [ string ] # file paths which must match to trigger a build
    exclude: [ string ] # file paths which will not trigger a build

Importante

Quando si specifica un trigger, solo i rami che si configurano in modo esplicito per l'inclusione attivano una pipeline. Le inclusioni vengono elaborate per prime e quindi le esclusioni vengono rimosse dall'elenco. Se si specifica un'esclusione ma nessuna inclusione, non viene attivato alcun trigger.

Trigger di richiesta pull

Un trigger di richiesta pull specifica quali rami causano l'esecuzione di una compilazione di richiesta pull. Se non si specifica alcun trigger di richiesta pull, le richieste pull a qualsiasi ramo attivano una compilazione. Altre informazioni sui trigger di richiesta pull e su come specificarli.

Importante

I trigger di richiesta pull YAML sono supportati solo in GitHub e Bitbucket Cloud. Se si usa git Azure Repos, è possibile configurare criteri di ramo per la convalida della compilazione per attivare la pipeline di compilazione per la convalida.

Importante

I trigger di richiesta pull YAML sono supportati solo in GitHub. Se si usa git Azure Repos, è possibile configurare criteri di ramo per la convalida della compilazione per attivare la pipeline di compilazione per la convalida.

Esistono tre opzioni di sintassi distinte per la parola chiave : un elenco di rami da includere, un modo per disabilitare i trigger di richiesta pull e la sintassi completa per pr il controllo completo.

Sintassi dell'elenco:

pr: [ string ] # list of branch names

Sintassi di disabilitazione:

pr: none # will disable PR builds entirely; will not disable CI triggers

Sintassi completa:

pr:
  autoCancel: boolean # indicates whether additional pushes to a PR should cancel in-progress runs for the same PR. Defaults to true
  branches:
    include: [ string ] # branch names which will trigger a build
    exclude: [ string ] # branch names which will not
  paths:
    include: [ string ] # file paths which must match to trigger a build
    exclude: [ string ] # file paths which will not trigger a build
pr:
  autoCancel: boolean # indicates whether additional pushes to a PR should cancel in-progress runs for the same PR. Defaults to true
  branches:
    include: [ string ] # branch names which will trigger a build
    exclude: [ string ] # branch names which will not
  paths:
    include: [ string ] # file paths which must match to trigger a build
    exclude: [ string ] # file paths which will not trigger a build
  drafts: boolean # For GitHub only, whether to build draft PRs, defaults to true

Se si specifica una exclude clausola senza una clausola per o , equivale include a specificare nella branches paths * include clausola .

Importante

Quando si specifica un trigger di richiesta pull, solo i rami che si configurano in modo esplicito per l'inclusione attivano una pipeline. Le inclusioni vengono elaborate per prime e quindi le esclusioni vengono rimosse dall'elenco. Se si specifica un'esclusione ma nessuna inclusione, non viene attivato alcun trigger.

Trigger pianificato

I trigger pianificati YAML non sono disponibili in questa versione di Azure DevOps Server o Visual Studio Team Foundation Server . È possibile usare i trigger pianificati nell'editor classico.

Un trigger pianificato specifica una pianificazione in base alla quale vengono compilati i rami. Se non si specifica alcun trigger pianificato, non vengono eseguite compilazioni pianificate. Altre informazioni sui trigger pianificati e su come specificarli.

schedules:
- cron: string # cron syntax defining a schedule in UTC time
  displayName: string # friendly name given to a specific schedule
  branches:
    include: [ string ] # which branches the schedule applies to
    exclude: [ string ] # which branches to exclude from the schedule
  always: boolean # whether to always run the pipeline or only if there have been source code changes since the last successful scheduled run. The default is false.

Nota

Se si specifica una exclude clausola senza una clausola per , equivale include a specificare nella branches * include clausola .

Trigger della pipeline

I trigger di completamento della pipeline vengono configurati usando una risorsa pipeline. Per altre informazioni, vedere Trigger di completamento della pipeline.

Pool

La pool parola chiave specifica il pool da usare per un processo della pipeline. Una pool specifica contiene anche informazioni sulla strategia del processo per l'esecuzione.

In Azure DevOps Server 2019 è possibile specificare un pool a livello di processo in YAML e a livello di pipeline nell'interfaccia utente delle impostazioni della pipeline. In Azure DevOps Server 2019.1 è anche possibile specificare un pool a livello di pipeline in YAML se si dispone di un singolo processo implicito.

È possibile specificare un pool a livello di pipeline, fase o processo.

Il pool specificato al livello più basso della gerarchia viene usato per eseguire il processo.

La sintassi completa è:

pool:
  name: string  # name of the pool to run this job in
  demands: string | [ string ]  # see the following "Demands" topic
  vmImage: string # name of the VM image you want to use; valid only in the Microsoft-hosted pool

Se si usa un pool ospitato da Microsoft, scegliere un'immagine di macchina virtuale disponibile.

Se si usa un pool privato e non è necessario specificare le richieste, è possibile abbreviare la sintassi per:

pool: string # name of the private pool to run this job in

Altre informazioni su condizioni e timeout.

Richieste

La demands parola chiave è supportata dai pool privati. È possibile verificare l'esistenza di una funzionalità o di una stringa specifica.

pool:
  demands: [ string ]

Altre informazioni sulle richieste.

Ambiente

La environment parola chiave specifica l'ambiente o la relativa risorsa di destinazione di un processo di distribuzione della pipeline. Un ambiente contiene anche informazioni sulla strategia di distribuzione per l'esecuzione dei passaggi definiti all'interno del processo.

La sintassi completa è:

environment:                # create environment and/or record deployments
  name: string              # name of the environment to run this job on.
  resourceName: string      # name of the resource in the environment to record the deployments against
  resourceId: number        # resource identifier
  resourceType: string      # type of the resource you want to target. Supported types - virtualMachine, Kubernetes
  tags: string | [ string ] # tag names to filter the resources in the environment
strategy:                 # deployment strategy
  runOnce:                # default strategy
    deploy:
      steps:
      - script: echo Hello world

Se si specifica un ambiente o una delle relative risorse ma non è necessario specificare altre proprietà, è possibile abbreviare la sintassi per:

environment: environmentName.resourceName
strategy:                 # deployment strategy
  runOnce:              # default strategy
    deploy:
      steps:
      - script: echo Hello world

Server

Il server valore specifica un processo server. Solo le attività server come la chiamata di un'app per le funzioni di Azure possono essere eseguite in un processo server.

Quando si usa server , un processo viene eseguito come processo server anziché come processo agente.

pool: server

Script

La script parola chiave è un collegamento per l'attività della riga di comando. L'attività esegue uno script usando cmd.exe in Windows e Bash in altre piattaforme.

steps:
- script: string  # contents of the script to run
  displayName: string  # friendly name displayed in the UI
  name: string  # identifier for this step (A-Z, a-z, 0-9, and underscore)
  workingDirectory: string  # initial working directory for the step
  failOnStderr: boolean  # if the script writes to stderr, should that be treated as the step failing?
  condition: string
  continueOnError: boolean  # 'true' if future steps should run even if this step fails; defaults to 'false'
  enabled: boolean  # whether to run this step; defaults to 'true'
  target:
    container: string # where this step will run; values are the container name or the word 'host'
    commands: enum  # whether to process all logging commands from this step; values are `any` (default) or `restricted`
  timeoutInMinutes: number
  env: { string: string }  # list of environment variables to add

Se non si specifica una modalità di comando, è possibile abbreviare target la struttura per:

- script:
  target: string  # container name or the word 'host'

Altre informazioni su condizioni, timeout edestinazioni dei passaggi.

Bash

La bash parola chiave è un collegamento per l'attività script della shell. L'attività esegue uno script in Bash Windows, macOS e Linux.

steps:
- bash: string  # contents of the script to run
  displayName: string  # friendly name displayed in the UI
  name: string  # identifier for this step (A-Z, a-z, 0-9, and underscore)
  workingDirectory: string  # initial working directory for the step
  failOnStderr: boolean  # if the script writes to stderr, should that be treated as the step failing?
  condition: string
  continueOnError: boolean  # 'true' if future steps should run even if this step fails; defaults to 'false'
  enabled: boolean  # whether to run this step; defaults to 'true'
  target:
    container: string # where this step will run; values are the container name or the word 'host'
    commands: enum  # whether to process all logging commands from this step; values are `any` (default) or `restricted`
  timeoutInMinutes: number
  env: { string: string }  # list of environment variables to add

Se non si specifica una modalità di comando, è possibile abbreviare target la struttura per:

- bash:
  target: string  # container name or the word 'host'

Altre informazioni su condizioni, timeout edestinazioni dei passaggi.

pwsh

La pwsh parola chiave è un collegamento per l'attività di PowerShell quando il valore pwsh di tale attività è impostato su true. L'attività esegue uno script in PowerShell Core in Windows, macOS e Linux.

steps:
- pwsh: string  # contents of the script to run
  displayName: string  # friendly name displayed in the UI
  name: string  # identifier for this step (A-Z, a-z, 0-9, and underscore)
  errorActionPreference: enum  # see the following "Error action preference" topic
  ignoreLASTEXITCODE: boolean  # see the following "Ignore last exit code" topic
  failOnStderr: boolean  # if the script writes to stderr, should that be treated as the step failing?
  workingDirectory: string  # initial working directory for the step
  condition: string
  continueOnError: boolean  # 'true' if future steps should run even if this step fails; defaults to 'false'
  enabled: boolean  # whether to run this step; defaults to 'true'
  timeoutInMinutes: number
  env: { string: string }  # list of environment variables to add

Nota

Ogni sessione di PowerShell dura solo per la durata del processo in cui viene eseguita. Le attività che dipendono da ciò che è stato avviato devono essere nello stesso processo del bootstrap.

Altre informazioni su condizioni e timeout.

PowerShell

La powershell parola chiave è un collegamento per l'attività di PowerShell. L'attività esegue uno script in Windows PowerShell.

steps:
- powershell: string  # contents of the script to run
  displayName: string  # friendly name displayed in the UI
  name: string  # identifier for this step (A-Z, a-z, 0-9, and underscore)
  errorActionPreference: enum  # see the following "Error action preference" topic
  ignoreLASTEXITCODE: boolean  # see the following "Ignore last exit code" topic
  failOnStderr: boolean  # if the script writes to stderr, should that be treated as the step failing?
  workingDirectory: string  # initial working directory for the step
  condition: string
  continueOnError: boolean  # 'true' if future steps should run even if this step fails; defaults to 'false'
  enabled: boolean  # whether to run this step; defaults to 'true'
  timeoutInMinutes: number
  env: { string: string }  # list of environment variables to add

Nota

Ogni sessione di PowerShell dura solo per la durata del processo in cui viene eseguita. Le attività che dipendono da ciò che è stato avviato devono essere nello stesso processo del bootstrap.

Altre informazioni su condizioni e timeout.

Preferenza azione di errore

Se non diversamente specificato, la preferenza per l'azione di errore viene impostata sul valore predefinito e la riga viene anteposta stop $ErrorActionPreference = 'stop' all'inizio dello script.

Quando la preferenza per l'azione di errore è impostata su Stop, gli errori causano l'interruzione dell'attività da parte di PowerShell e la restituzione di un codice di uscita diverso da zero. Anche l'attività è contrassegnata come Non riuscita.

errorActionPreference: stop | continue | silentlyContinue

Ignora ultimo codice di uscita

L'ultimo codice di uscita restituito dallo script viene controllato per impostazione predefinita. Un codice diverso da zero indica un errore del passaggio, nel qual caso il sistema aggiunge lo script con:

if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }

Se non si vuole questo comportamento, specificare ignoreLASTEXITCODE: true .

ignoreLASTEXITCODE: boolean

Altre informazioni su condizioni e timeout.

Pubblica

La publish parola chiave è un collegamento per l'attività Pubblica elemento pipeline. L'attività pubblica (carica) un file o una cartella come artefatto della pipeline che può essere utilizzato da altri processi e pipeline.

steps:
- publish: string # path to a file or folder
  artifact: string # artifact name
  displayName: string  # friendly name to display in the UI

Altre informazioni sulla pubblicazione di elementi.

Scarica

La download parola chiave è un collegamento per l'attività Scarica artefatto pipeline. L'attività scarica gli artefatti associati all'esecuzione corrente o da un'altra pipeline di Azure associata come risorsa della pipeline.

steps:
- download: [ current | pipeline resource identifier | none ] # disable automatic download if "none"
  artifact: string ## artifact name, optional; downloads all the available artifacts if not specified
  patterns: string # patterns representing files to include; optional
  displayName: string  # friendly name to display in the UI

Percorso di download dell'artefatto

Artifacts dalla pipeline corrente vengono scaricati in $(**Pipeline.Workspace**)/<artifact name> .

Artifacts dalla risorsa pipeline associata vengono scaricati in $(**Pipeline.Workspace**)/\<pipeline resource identifier\>/<artifact name> .

Download automatico nei processi di distribuzione

Tutti gli artefatti disponibili dalla pipeline corrente e dalle risorse della pipeline associate vengono scaricati automaticamente nei processi di distribuzione e resi disponibili per la distribuzione. Per impedire i download, specificare download: none .

Altre informazioni sul download degli artefatti.

Checkout

I processi non di distribuzione estraeno automaticamente il codice sorgente. Usare la checkout parola chiave per configurare o eliminare questo comportamento.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # if true, execute `execute git clean -ffdx && git reset --hard HEAD` before fetching
  fetchDepth: number  # the depth of commits to ask Git to fetch (applies to submodules too if they're enabled); defaults to no limit
  lfs: boolean  # whether to download Git-LFS files; defaults to false
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules; defaults to not checking out submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1); defaults to a directory called `s`
  persistCredentials: boolean  # if 'true', leave the OAuth token in the Git config after the initial fetch; defaults to false
steps:
- checkout: self | none | repository name # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # if true, run `execute git clean -ffdx && git reset --hard HEAD` before fetching
  fetchDepth: number  # the depth of commits to ask Git to fetch; defaults to no limit
  lfs: boolean  # whether to download Git-LFS files; defaults to false
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules; defaults to not checking out submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1); defaults to a directory called `s`
  persistCredentials: boolean  # if 'true', leave the OAuth token in the Git config after the initial fetch; defaults to false

Nota

Oltre all'opzione di pulizia disponibile tramite , è anche possibile configurare la checkout pulizia in un'area di lavoro. Per altre informazioni sulle aree di lavoro, incluse le opzioni di pulizia, vedere l'argomento relativo alle aree di lavoro in Processi.

Per evitare la sincronizzazione delle origini:

steps:
- checkout: none

Nota

Se si esegue l'agente nell'account del servizio locale e si vuole modificare il repository corrente usando operazioni Git o caricando moduli secondari Git, assegnare le autorizzazioni appropriate all'utente account del servizio di compilazione di Project Collection.

- checkout: self
  submodules: true
  persistCredentials: true

Per estrarre più repository nella pipeline, usare più checkout passaggi:

- checkout: self
- checkout: git://MyProject/MyRepo
- checkout: MyGitHubRepo # Repo declared in a repository resource

Per altre informazioni, vedere Estrarre più repository nella pipeline.

Attività

Le attività sono i blocchi predefiniti di una pipeline. È disponibile un catalogo di attività tra cui scegliere.

steps:
- task: string  # reference to a task and version, e.g. "VSBuild@1"
  displayName: string  # friendly name displayed in the UI
  name: string  # identifier for this step (A-Z, a-z, 0-9, and underscore)
  condition: string
  continueOnError: boolean  # 'true' if future steps should run even if this step fails; defaults to 'false'
  enabled: boolean  # whether to run this step; defaults to 'true'
  target:
    container: string # where this step will run; values are the container name or the word 'host'
    commands: enum  # whether to process all logging commands from this step; values are `any` (default) or `restricted`
    settableVariables: string # what variables are allowed; defaults to all; can be `none` or a list of allowed vars
  timeoutInMinutes: number
  inputs: { string: string }  # task-specific inputs
  env: { string: string }  # list of environment variables to add

Se non si specifica una modalità di comando, è possibile abbreviare target la struttura per:

- task:
  target: string  # container name or the word 'host'

Altre informazioni su condizioni, timeout edestinazioni dei passaggi.

Evidenziazione della sintassi

L'evidenziazione della sintassi è disponibile per lo schema della pipeline tramite un'Visual Studio Code predefinita. È possibile scaricare Visual Studio Code, installare l'estensioneed estrarre il progetto in GitHub. L'estensione include uno schema JSON per la convalida.

È anche possibile ottenere uno schema specifico dell'organizzazione(ovvero contiene attività personalizzate installate) dall'endpoint yamlschema dell'API REST Azure DevOps.