Especificar trabajos en la canalización

En el caso más sencillo, una canalización tiene un único trabajo. En ese caso, no es necesario usar explícitamente la palabra clave job a menos que use una plantilla. Puede especificar directamente los pasos en el archivo YAML.

Este archivo YAML tiene un trabajo que se ejecuta en un agente hospedado por Microsoft y genera Hello world.

pool:
  vmImage: 'ubuntu-latest'
steps:
- bash: echo "Hello world"

Es posible que desee especificar más propiedades en ese trabajo. En ese caso, puede usar la palabra clave job.

jobs:
- job: myJob
  timeoutInMinutes: 10
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - bash: echo "Hello world"

La canalización puede tener varios trabajos. En ese caso, use la palabra clave jobs.

jobs:
- job: A
  steps:
  - bash: echo "A"

- job: B
  steps:
  - bash: echo "B"

La canalización puede tener varias fases, cada una con varios trabajos. En ese caso, use la palabra clave stages.

stages:
- stage: A
  jobs:
  - job: A1
  - job: A2

- stage: B
  jobs:
  - job: B1
  - job: B2

La sintaxis completa para especificar un trabajo es:

- 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
    matrix: # matrix strategy
    maxParallel: number # maximum number simultaneous matrix legs to run
    # note: `parallel` and `matrix` are mutually exclusive
    # you may specify one or the other; including both is an error
    # `maxParallel` is only valid with `matrix`
  continueOnError: boolean  # 'true' if future jobs should run even if this job fails; defaults to 'false'
  pool: pool # agent pool
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs
  container: containerReference # container to run this job inside
  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: { string: string } | [ variable | variableReference ] 
  steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]
  services: { string: string | container } # container resources to run as a service container

La sintaxis completa para especificar un trabajo es:

- 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
    matrix: # matrix strategy
    maxParallel: number # maximum number simultaneous matrix legs to run
    # note: `parallel` and `matrix` are mutually exclusive
    # you may specify one or the other; including both is an error
    # `maxParallel` is only valid with `matrix`
  continueOnError: boolean  # 'true' if future jobs should run even if this job fails; defaults to 'false'
  pool: pool # agent pool
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs
  container: containerReference # container to run this job inside
  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: { string: string } | [ variable | variableReference ] 
  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

Si la intención principal del trabajo es implementar la aplicación (en lugar de compilar o probar la aplicación), puede usar un tipo especial de trabajo denominado trabajo de implementación.

La sintaxis de un trabajo de implementación es:

- deployment: string        # instead of job keyword, use deployment keyword
  pool:
    name: string
    demands: string | [ string ]
  environment: string
  strategy:
    runOnce:
      deploy:
        steps:
        - script: echo Hi!

Aunque puede agregar pasos para las tareas de implementación en job, se recomienda usar en su lugar un trabajo de implementación. Un trabajo de implementación tiene algunas ventajas. Por ejemplo, puede implementar en un entorno, lo que incluye ventajas como poder ver el historial de lo que ha implementado.

pool:
  name: myPrivateAgents    # your job runs on an agent in this pool
  demands: agent.os -equals Windows_NT    # the agent must have this capability to run the job
steps:
- script: echo hello world

O varias demandas:

pool:
  name: myPrivateAgents
  demands:
  - agent.os -equals Darwin
  - anotherCapability -equals somethingElse
steps:
- script: echo hello world

La sintaxis completa para especificar un trabajo de servidor es:

jobs:
- job: string
  timeoutInMinutes: number
  cancelTimeoutInMinutes: number
  strategy:
    maxParallel: number
    matrix: { string: { string: string } }

  pool: server # note: the value 'server' is a reserved keyword which indicates this is an agentless job

También puede usar la sintaxis simplificada:

jobs:
- job: string
  pool: server # note: the value 'server' is a reserved keyword which indicates this is an agentless job

La sintaxis para definir varios trabajos y sus dependencias es:

jobs:
- job: string
  dependsOn: string
  condition: string

Trabajos de ejemplo que se compilan secuencialmente:

jobs:
- job: Debug
  steps:
  - script: echo hello from the Debug build
- job: Release
  dependsOn: Debug
  steps:
  - script: echo hello from the Release build

Trabajos de ejemplo que se compilan en paralelo (sin dependencias):

jobs:
- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: echo hello from Windows
- job: macOS
  pool:
    vmImage: 'macOS-latest'
  steps:
  - script: echo hello from macOS
- job: Linux
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - script: echo hello from Linux

Ejemplo de distribución ramificada:

jobs:
- job: InitialJob
  steps:
  - script: echo hello from initial job
- job: SubsequentA
  dependsOn: InitialJob
  steps:
  - script: echo hello from subsequent A
- job: SubsequentB
  dependsOn: InitialJob
  steps:
  - script: echo hello from subsequent B

Ejemplo de absorción:

jobs:
- job: InitialA
  steps:
  - script: echo hello from initial A
- job: InitialB
  steps:
  - script: echo hello from initial B
- job: Subsequent
  dependsOn:
  - InitialA
  - InitialB
  steps:
  - script: echo hello from subsequent

Cuando se especifican varios trabajos en una canalización de compilación, se ejecutan en paralelo de forma predeterminada. Puede especificar el orden en el que se deben ejecutar los trabajos mediante la configuración de dependencias entre trabajos. Las dependencias del trabajo no se admiten en canalizaciones de versión. Varios trabajos de una canalización de versión se ejecutan en secuencia.

Ejemplo para ejecutar un trabajo en función del estado de ejecución de un trabajo anterior:

jobs:
- job: A
  steps:
  - script: exit 1

- job: B
  dependsOn: A
  condition: failed()
  steps:
  - script: echo this will run when A fails

- job: C
  dependsOn:
  - A
  - B
  condition: succeeded('B')
  steps:
  - script: echo this will run when B runs and succeeds

Ejemplo de uso de una condición personalizada:

jobs:
- job: A
  steps:
  - script: echo hello

- job: B
  dependsOn: A
  condition: and(succeeded(), eq(variables['build.sourceBranch'], 'refs/heads/main'))
  steps:
  - script: echo this only runs for master

Puede especificar que un trabajo se ejecute en función del valor de una variable de salida establecida en un trabajo anterior. En este caso, solo puede usar variables establecidas en trabajos dependientes directamente:

jobs:
- job: A
  steps:
  - script: "echo '##vso[task.setvariable variable=skipsubsequent;isOutput=true]false'"
    name: printvar

- job: B
  condition: and(succeeded(), ne(dependencies.A.outputs['printvar.skipsubsequent'], 'true'))
  dependsOn: A
  steps:
  - script: echo hello from B

Use la opción Ejecutar este trabajo en un agente o trabajo de servidor para ejecutar las tareas solo cuando se cumplan condiciones específicas. Seleccione una condición predefinida o seleccione "personalizada" y escriba una expresión que se evalúe como true o false. Se pueden usar expresiones anidadas y las expresiones pueden tener acceso a variables disponibles en la canalización de versión.

timeoutInMinutes permite establecer un límite para el tiempo de ejecución del trabajo. Cuando no se especifica, el valor predeterminado es de 60 minutos. Cuando 0 se especifica, se usa el límite máximo (descrito anteriormente).

cancelTimeoutInMinutes permite establecer un límite para la hora de cancelación del trabajo cuando se establece la tarea de implementación para seguir ejecutándose si se ha producido un error en una tarea anterior. Cuando no se especifica, el valor predeterminado es de 5 minutos. El valor debe estar comprendido entre 1 y 35790 minutos.

jobs:
- job: Test
  timeoutInMinutes: 10 # how long to run the job before automatically cancelling
  cancelTimeoutInMinutes: 2 # how much time to give 'run always even if cancelled tasks' before stopping them

La estrategia matrix permite que un trabajo se envíe varias veces, con conjuntos de variables diferentes. La etiqueta maxParallel restringe la cantidad de paralelismo. El siguiente trabajo se enviará tres veces con los valores de Ubicación y Explorador establecidos como se especifica. Sin embargo, solo se ejecutarán dos trabajos al mismo tiempo.

jobs:
- job: Test
  strategy:
    maxParallel: 2
    matrix: 
      US_IE:
        Location: US
        Browser: IE
      US_Chrome:
        Location: US
        Browser: Chrome
      Europe_Chrome:
        Location: Europe
        Browser: Chrome

También es posible usar variables de salida para generar una matriz. Esto puede ser útil si debe generar la matriz mediante un script.

matrix aceptará una expresión en tiempo de ejecución que contiene un objeto JSON con cadena. Ese objeto JSON, cuando se expande, debe coincidir con la sintaxis de matriz. En el ejemplo siguiente, hemos codificado de forma rígida la cadena JSON, pero podría generarse mediante un lenguaje de scripting o un programa de línea de comandos.

jobs:
- job: generator
  steps:
  - bash: echo "##vso[task.setVariable variable=legs;isOutput=true]{'a':{'myvar':'A'}, 'b':{'myvar':'B'}}"
    name: mtrx
  # This expands to the matrix
  #   a:
  #     myvar: A
  #   b:
  #     myvar: B
- job: runner
  dependsOn: generator
  strategy:
    matrix: $[ dependencies.generator.outputs['mtrx.legs'] ]
  steps:
  - script: echo $(myvar) # echos A or B depending on which leg is running

La estrategia parallel permite que un trabajo se duplique muchas veces. Las variables System.JobPositionInPhase y System.TotalJobsInPhase se agregan a cada trabajo. A continuación, las variables se pueden usar dentro de los scripts para dividir el trabajo entre los trabajos. Consulte Ejecución en paralelo y varias ejecuciones mediante trabajos de agente.

El siguiente trabajo se enviará cinco veces con el correcto establecimiento de los valores de System.JobPositionInPhase y System.TotalJobsInPhase.

jobs:
- job: Test
  strategy:
    parallel: 5

Este es un ejemplo de definición de variables en un trabajo y su uso en tareas.

variables:
  mySimpleVar: simple var value
  "my.dotted.var": dotted var value
  "my var with spaces": var with spaces value

steps:
- script: echo Input macro = $(mySimpleVar). Env var = %MYSIMPLEVAR%
  condition: eq(variables['agent.os'], 'Windows_NT')
- script: echo Input macro = $(mySimpleVar). Env var = $MYSIMPLEVAR
  condition: in(variables['agent.os'], 'Darwin', 'Linux')
- bash: echo Input macro = $(my.dotted.var). Env var = $MY_DOTTED_VAR
- powershell: Write-Host "Input macro = $(my var with spaces). Env var = $env:MY_VAR_WITH_SPACES"

$(Build.ArtifactStagingDirectory) y $(Common.TestResultsDirectory) siempre se eliminan y se vuelven a crear antes de cada compilación.

Al ejecutar una canalización en un agente autohospedado, de forma predeterminada, ninguno de los subdirectorios distintos de $(Build.ArtifactStagingDirectory) y $(Common.TestResultsDirectory) se limpia entre dos ejecuciones consecutivas. Como resultado, puede realizar compilaciones e implementaciones incrementales, siempre que las tareas se implementen para usarlas. Puede invalidar este comportamiento mediante la configuración workspace del trabajo.

- job: myJob
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs

Al especificar una de las opciones clean, se interpretan de la siguiente manera:

• outputs: elimine Build.BinariesDirectory antes de ejecutar un nuevo trabajo.
• resources: elimine Build.SourcesDirectory antes de ejecutar un nuevo trabajo.
• all: elimine todo el directorio Pipeline.Workspace antes de ejecutar un nuevo trabajo.

  jobs:
  - deployment: MyDeploy
    pool:
      vmImage: 'ubuntu-latest'
    workspace:
      clean: all
    environment: staging

Además de limpiar el área de trabajo, también puede configurar la limpieza mediante la configuración Limpiar en la interfaz de usuario de configuración de la canalización. Cuando la opción Limpiar es true, que también es su valor predeterminado, equivale a especificar clean: true para cada paso de restauración de la canalización. Al especificar clean: true, se ejecutará git clean -ffdx seguido de git reset --hard HEAD antes de la captura de Git. Para configurar la opción Limpiar:

1. Edite la canalización, elija ... y seleccione Desencadenadores.

   

2. Seleccione YAML, Obtener orígenes y configure la opción de Limpiar deseada. El valor predeterminado es true.

   

# test and upload my code as an artifact named WebSite
jobs:
- job: Build
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - script: npm test
  - task: PublishBuildArtifacts@1
    inputs:
      pathtoPublish: '$(System.DefaultWorkingDirectory)'
      artifactName: WebSite

# download the artifact and deploy it only if the build job succeeded
- job: Deploy
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - checkout: none #skip checking out the default repository resource
  - task: DownloadBuildArtifacts@0
    displayName: 'Download Build Artifacts'
    inputs:
      artifactName: WebSite
      downloadPath: $(Pipeline.Workspace)

  dependsOn: Build
  condition: succeeded()

Como alternativa, puede optar por descargar artefactos específicos durante la ejecución del trabajo en una versión. Use esta opción si las tareas de un trabajo determinado solo dependen de artefactos específicos.

El token de OAuth siempre está disponible para las canalizaciones de YAML. Debe asignarse explícitamente a la tarea o paso mediante env. Este es un ejemplo:

steps:
- powershell: |
    $url = "$($env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)$env:SYSTEM_TEAMPROJECTID/_apis/build/definitions/$($env:SYSTEM_DEFINITIONID)?api-version=4.1-preview"
    Write-Host "URL: $url"
    $pipeline = Invoke-RestMethod -Uri $url -Headers @{
      Authorization = "Bearer $env:SYSTEM_ACCESSTOKEN"
    }
    Write-Host "Pipeline = $($pipeline | ConvertTo-Json -Depth 100)"
  env:
    SYSTEM_ACCESSTOKEN: $(system.accesstoken)