Condiciones de canalización

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

En este artículo se describen las distintas condiciones que permiten que se ejecute una fase, un trabajo o un paso de Azure Pipelines y cómo establecer esas condiciones en una definición de canalización de YAML.

Condiciones en las que se ejecuta una fase, un trabajo o un paso

De forma predeterminada, se ejecuta un trabajo o una fase de canalización si no depende de ningún otro trabajo o fase, o si todas sus dependencias se completaron y se realizaron correctamente. El requisito de dependencia se aplica a las dependencias directas y a sus dependencias indirectas, calculadas de forma recursiva.

De manera predeterminada, se ejecuta un paso si aún no se ha producido ningún error en su trabajo y el paso inmediatamente anterior a él ha finalizado. Para obtener más contexto sobre las fases, los trabajos y los pasos, consulte Conceptos clave de Azure Pipelines.

Puede invalidar o personalizar estos comportamientos predeterminados estableciendo una fase, un trabajo o un paso para ejecutarse incluso si se produce un error en una dependencia anterior o si se produce otro resultado. También puede definir condiciones personalizadas. En una definición de canalización YAML, se usa la condition propiedad para especificar condiciones en las que se puede ejecutar una fase, un trabajo o un paso.

Entre las condiciones basadas en el estado de dependencia anterior se incluyen:

• Exitoso: Ejecutar solo si todas las dependencias anteriores tienen éxito. Este comportamiento es el valor predeterminado si no hay ninguna condición establecida en YAML. Para aplicar esta condición, especifique condition: succeeded().
• Exitoso o fallido: Ejecuta incluso si falla una dependencia anterior, a menos que se cancele la ejecución. Para aplicar esta condición, especifique condition: succeededOrFailed().
• Siempre: ejecute incluso si se produce un error en una dependencia anterior, incluso si se cancela la ejecución. Para aplicar esta condición, especifique condition: always().
• Error: solo se ejecuta cuando se produce un error en una dependencia anterior. Para aplicar esta condición, especifique condition: failed().

Ejemplo de condición

En el siguiente ejemplo de YAML se muestran las always() condiciones y failed() . La primera tarea de script del trabajo 1 tiene una always condición, por lo que se ejecuta aunque se produzca un error en las dependencias o se cancele la compilación. En la segunda tarea de script, exit job1 fuerza a que el trabajo job1 falle.

Las fases de canalización se ejecutan secuencialmente de forma predeterminada, pero los trabajos se pueden ejecutar en paralelo. Puede usar la dependsOn propiedad para definir explícitamente las dependencias entre fases o trabajos.

Para establecer las condiciones de un trabajo que depende del resultado de otro trabajo, use dependsOn para definir la dependencia. En el ejemplo siguiente, job2 depende job1 de y se ejecuta porque job1 se produce un error.

jobs:
- job: job1
  steps:
  - script: echo Hello!
    condition: always() # this step runs even if the build is canceled
  - script: |
      echo "This task will fail."
      exit job1 
- job: job2
  dependsOn: job1
  condition: failed() # this job runs only if job1 fails

Condiciones personalizadas

Si las condiciones integradas no satisfacen sus necesidades, puede especificar condiciones personalizadas como expresiones en las definiciones de canalización de YAML.

El agente evalúa la expresión comenzando con la función más interna y continuando hacia fuera. El resultado final es un valor booleano que determina si se va a ejecutar o no la fase, el trabajo o el paso. Para obtener una guía completa sobre la sintaxis, consulte Expresiones.

Variables en condiciones

Puede establecer variables de canalización y usarlas en condiciones. La canalización siguiente establece una isMain variable y la usa en una condición que ejecuta la fase B solo cuando la rama de origen de compilación es main.

variables:
  isMain: $[eq(variables['Build.SourceBranch'], 'refs/heads/main')]

stages:
- stage: A
  jobs:
  - job: A1
    steps:
      - script: echo Hello Stage A!
- stage: B
  condition: and(succeeded(), eq(variables.isMain, true))
  jobs:
  - job: B1
    steps:
      - script: echo Hello Stage B!
      - script: echo $(isMain)

Puede establecer una condición para que se ejecute si una variable es null o una cadena vacía. Todas las variables se tratan como cadenas en Azure Pipelines, por lo que una cadena vacía es equivalente a null en la canalización siguiente:

variables:
- name: testEmpty
  value: ''

jobs:
  - job: A
    steps:
    - script: echo testEmpty is blank
    condition: eq(variables.testEmpty, '')

Variables de salida de trabajo usadas en otras condiciones de trabajo

Puede crear una variable en un trabajo que otros trabajos de la misma fase puedan especificar en condiciones. Las variables disponibles para los trabajos dependientes deben marcarse como variables de salida de varios trabajos mediante isOutput=true, como en el código siguiente:

jobs:
- job: A
  steps:
  - bash: |
      echo "This is job A."
      echo "##vso[task.setvariable variable=doThing;isOutput=true]Yes" #set variable doThing to Yes
    name: DetermineResult
- job: B
  dependsOn: A
  condition: eq(dependencies.A.outputs['DetermineResult.doThing'], 'Yes') #map doThing and check the value
  steps:
  - script: echo "Job A ran and doThing is Yes."

Variables de paso usadas en condiciones de paso posteriores

Puede crear una variable en un paso que los pasos futuros del mismo trabajo pueden especificar en condiciones. Las variables creadas a partir de los pasos están disponibles para los pasos futuros del trabajo de forma predeterminada y no es necesario marcarlas como variables de salida de varios trabajos.

Las variables creadas en un paso de un trabajo tienen las siguientes limitaciones:

• Se limitan a los pasos del mismo trabajo.
• Están disponibles en pasos posteriores solo como variables de entorno.
• No se puede usar en el mismo paso que los define.

En el ejemplo siguiente se crea una variable de canalización en un paso y se usa la variable en la condición de script de un paso posterior.

steps:

# This step creates a new pipeline variable: doThing. This variable is available to subsequent steps.
- bash: |
    echo "##vso[task.setvariable variable=doThing]Yes"
  displayName: Step 1

# This step uses doThing in its condition
- script: |
    # Access the variable from Step 1 as an environment variable.
    echo "Value of doThing (as DOTHING env var): $DOTHING."
  displayName: Step 2
  condition: and(succeeded(), eq(variables['doThing'], 'Yes')) # or and(succeeded(), eq(variables.doThing, 'Yes'))

Configuración de condiciones para varios resultados

En la tabla siguiente se muestra condition la configuración para generar varios resultados deseados.

Resultados de condición cuando se cancela una compilación

Cancelar una compilación no significa que todas sus fases, trabajos y pasos dejen de ejecutarse. Los trabajos, fases o pasos que dejan de ejecutarse dependen de las condiciones especificadas y en qué punto de ejecución de la canalización canceló la compilación. Si se omite una fase, un trabajo o un elemento primario del paso, la fase, el trabajo o el paso no se ejecutan, independientemente de sus condiciones.

Una fase, trabajo o paso se ejecuta cada vez que sus condiciones se evalúan como true. Si una condición no tiene en cuenta el estado del elemento primario de la tarea, la tarea podría ejecutarse incluso si se cancela su elemento primario. Para controlar si se ejecutan trabajos, fases o pasos cuando se cancela una compilación, incluya una función de comprobación de estado del trabajo en las condiciones.

Si cancela una compilación mientras se encuentra en la fase de cola, pero aún no se está ejecutando, se cancela toda la ejecución, incluidas todas las demás fases.

Resultados de condición de fase de ejemplo

En los ejemplos siguientes se muestran los resultados de varias condiciones establecidas en fases cuando se cancela la compilación.

Ejemplo de fase 1

En la siguiente canalización, de forma predeterminada stage2 dependerá stage1 de completarse correctamente. Sin embargo, stage2 tiene un condition conjunto que se ejecutará siempre que la rama de origen sea main, independientemente del stage1 estado.

Si pone en cola una compilación en la rama main y la cancela mientras se ejecuta stage1, stage2 seguirá ejecutándose, ya que eq(variables['Build.SourceBranch'], 'refs/heads/main') se evalúa como true.

stages:
- stage: stage1
  jobs:
  - job: A
    steps:
      - script: echo 1; sleep 30
- stage: stage2
  condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')
  jobs:
  - job: B
    steps:
      - script: echo 2

Ejemplo de fase 2

En la siguiente canalización, de forma predeterminada stage2 depende stage1 de completarse correctamente. El trabajo B de tiene establecido stage2 que se ejecutará cada vez que la rama de origen sea conditionmain .

Si pone en cola una compilación en la main rama y la cancela mientras stage1 se está ejecutando, stage2 y sus trabajos no se ejecutan en absoluto, aunque la fase contenga un trabajo cuya condición se evalúa como true.

stages:
- stage: stage1
  jobs:
  - job: A
    steps:
      - script: echo 1; sleep 30
- stage: stage2
  jobs:
  - job: B
    condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')
    steps:
      - script: echo 2

Ejemplo de fase 3

En la siguiente canalización, de forma predeterminada stage2 depende stage1 de completarse correctamente. El paso dentro del trabajo B dentro de stage2 tiene un condition conjunto que se va a ejecutar siempre que la rama de origen sea main.

Si pone en cola una compilación en la main rama y la cancela mientras stage1 se está ejecutando y stage2 el trabajo B no se ejecuta en absoluto, aunque el trabajo B contenga un paso cuya condición se evalúa como true. Stage2 se omite por completo porque stage1 se canceló.

stages:
- stage: stage1
  jobs:
  - job: A
    steps:
      - script: echo 1; sleep 30
- stage: stage2
  jobs:
  - job: B
    steps:
      - script: echo 2
        condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')

Resultados de condición de trabajo de ejemplo

En los ejemplos siguientes se muestran los resultados de varias condiciones establecidas en los trabajos cuando se cancela la compilación.

Ejemplo de trabajo 1

En la siguiente canalización YAML, el trabajo B que se ejecuta depende de la ejecución del trabajo A . El trabajo B también tiene un condition conjunto para ejecutarse siempre que la rama de origen sea main.

Si pone en cola una compilación en la rama main y la cancela mientras se ejecuta el trabajo A, el trabajo B seguirá ejecutándose, ya que condition: eq(variables['Build.SourceBranch'], 'refs/heads/main') se evalúa como true.

jobs:
- job: A
  steps:
  - script: sleep 30
- job: B
  dependsOn: A 
  condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')
  steps:
    - script: echo step 2.1

Si desea que el trabajo se ejecute solo cuando el trabajo BA se realiza correctamente y el origen de compilación es main, debe establecer en conditionand(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main')).

Ejemplo de trabajo 2

En la siguiente canalización de YAML, el trabajo B depende del trabajo A correcto. El trabajo B tiene un condition conjunto para ejecutarse siempre que el trabajo A se realiza correctamente y la rama de origen de compilación es main.

Si pone en cola una compilación en la main rama y la cancela mientras se ejecuta el trabajo A , el trabajo B no se ejecuta, aunque tenga uno condition que se evalúe como true. La condición en el trabajo B se false evalúa como porque el trabajo A no se realizó correctamente. Por lo tanto, se omiten el trabajo B y sus pasos.

jobs:
- job: A
  steps:
  - script: sleep 30
- job: B
  dependsOn: A 
  steps:
    - script: echo step 2.1
  condition: and(eq(variables['Build.SourceBranch'], 'refs/heads/main'), succeeded())

Resultado de condición de paso de ejemplo

También puede establecer condiciones en los pasos. En la canalización siguiente, el paso 2.3 tiene establecida una condition para ejecutarse cada vez que la rama de origen sea main.

Si pone en cola una compilación en la rama main y la cancela mientras se ejecutan los pasos 2.1 o 2.2, el paso 2.3 se sigue ejecutando, ya que eq(variables['Build.SourceBranch'], 'refs/heads/main') se evalúa como true.

steps:
  - script: echo step 2.1
  - script: echo step 2.2; sleep 30
  - script: echo step 2.3
    condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')

Parámetros en condiciones

Puede usar parámetros en condiciones. La expansión de parámetros se produce antes de que la canalización se ejecute y reemplace los valores rodeados por ${{ }} los valores de parámetro literal. Dado que la expansión de parámetros se produce antes de la evaluación de la condición, puede declarar un parámetro en una canalización e insertar el parámetro dentro de cualquier condición de esa canalización.

En condition el ejemplo siguiente se combinan dos funciones: succeeded() y ${{ eq(parameters.doThing, true) }}. La función succeeded() comprueba si el paso anterior se realizó correctamente. Esta función también devuelve true si no hay ningún paso anterior.

La función ${{ eq(parameters.doThing, true) }} comprueba si el parámetro doThing es igual a true. El paso de script del ejemplo siguiente se ejecuta porque no había ningún paso anterior y parameters.doThing es true de forma predeterminada.

parameters:
- name: doThing
  default: true
  type: boolean

steps:
- script: echo I did a thing
  condition: and(succeeded(), ${{ eq(parameters.doThing, true) }})

Parámetros de plantilla bajo condiciones

Al pasar un parámetro a una plantilla de canalización, puede establecer el valor del parámetro en el archivo de plantilla o usar templateContext para pasar el parámetro a la plantilla.

El siguiente archivo de plantilla parameters.yml declara el doThing parámetro con un valor predeterminado de true y usa el parámetro en una condición de trabajo.

# parameters.yml
parameters:
- name: doThing
  default: true
  type: boolean

jobs:
  - job: B
    steps:
    - script: echo I did a thing
    condition: ${{ eq(parameters.doThing, true) }}

La siguiente definición de canalización azure-pipelines.yml hace referencia al trabajo en el archivo de plantilla parameters.yml . La salida de la canalización se debe I did a thing a que el parámetro doThing es true de forma predeterminada.

# azure-pipelines.yml

extends:
  template: parameters.yml

Para obtener más ejemplos de parámetros de plantilla, consulte Referencia de uso de plantillas.

Preguntas más frecuentes

¿Cómo puedo desencadenar un trabajo si un trabajo anterior se realizó correctamente con incidencias?

Puede usar el resultado del trabajo anterior en una condición. En el siguiente CÓDIGO YAML, la condición eq(dependencies.A.result,'SucceededWithIssues') establece el trabajo B que se ejecutará después de que el trabajo A se haya realizado correctamente con problemas.

jobs:
- job: A
  steps:
  - script: echo Job A ran
- job: B
  dependsOn: A
  condition: eq(dependencies.A.result,'SucceededWithIssues') # targets the result of the previous job 
  steps:
  - script: echo Job A had issues

¿Por qué mi compilación sigue ejecutándose después de cancelarla?

Puede experimentar este problema si una condición configurada en una fase no incluye ninguna función de comprobación de estado del trabajo. Para resolver el problema, agregue una función de comprobación de estado del trabajo a la condición. Para obtener más información, consulte Resultados de condición cuando se cancela una compilación.

Contenido relacionado

• Especifica los trabajos en tu canalización
• Adición de fases, dependencias y condiciones
• Uso de parámetros de plantilla