Azure-devops-docs: stageDependencies

[tehho]

Release notes from 4 May said that there is a new support for variables between stages called stageDependencies.
https://docs.microsoft.com/en-us/azure/devops/release-notes/2020/sprint-168-update

Tried it in a pipeline and got
"An error occurred while loading the YAML build pipeline. Unrecognized value: 'stageDependencies'. Located at position 5 within expression: eq( stageDependencies.Build.Plan.outputs['plan.output'], '2' )"

How are you suppose to use this feature?

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 3f151218-9a11-0078-e038-f96198a76143
• Version Independent ID: 09c4d032-62f3-d97c-79d7-6fbfd89910e9
• Content: Conditions - Azure Pipelines
• Content Source: docs/pipelines/process/conditions.md
• Product: devops
• Technology: devops-cicd-process
• GitHub Login: @juliakm
• Microsoft Alias: jukullam

[msebolt]

@tehho Thank you for the feedback, assigning this to the author for review.

In the meantime, please refer to this post for syntax.

[kmadof]

@tehho The issue is that you probably used stageDependencies in condition at stage level. But this is not supported. What you can do is to use it in job level of subsequent stages, assuming that stage you are reference to is a dependency. Please check this link and at the bottom, you have an example how to use it.

@msebolt can I take care of this issue and propose a change for documentation to make this clear for the future?

[juliakm]

@kmadof @tehho We are working on getting documentation for this up right now. The schema for stageDependencies is a little different than for dependencies.

The context is called dependencies for jobs and stages. Inside a job, if you refer to an output variable from a job in another stage, the context is called stageDependencies.

Example 1

In this example, Stage A will always be skipped and Stage B will run.

stages:
- stage: A
  condition: false
  jobs:
  - job: A1
    steps:
    - script: echo Job A1
- stage: B
  condition: in(dependencies.A.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
  jobs:
  - job: B1
    steps:
    - script: echo Job B1

Example 2

Stages can also use output variables from the prior stage. Here Stage B depends on a variable in Stage A.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - script: echo "##vso[task.setvariable variable=skipsubsequent;isOutput=true]false"
       name: printvar
- stage: B
  condition: and(succeeded(), ne(stageDependencies.A.A1.outputs['printvar.skipsubsequent'], 'true'))
  dependsOn: A
  jobs:
  - job: B1
    steps:
    - script: echo hello from Stage B

[kmadof]

@juliakm Thanks for reply. I tried your second example and I got an error:

An error occurred while loading the YAML build pipeline. Unrecognized value: 'stageDependencies'. Located at position 21 within expression: and(succeeded(), ne(stageDependencies.A.A1.outputs['printvar.skipsubsequent'], 'true')). For more help, refer to https://go.microsoft.com/fwlink/?linkid=842996

But when I changed condition to:

condition: and(succeeded(), ne(dependencies.A.A1.outputs['printvar.skipsubsequent'], 'true'))

All went fine, but just because dependencies.A.A1.outputs['printvar.skipsubsequent'] was not true, but it is also not false. For this condition condition: and(succeeded(), eq(dependencies.A.A1.outputs['printvar.skipsubsequent'], 'false')) stage is skipped.

[tehho]

I assumed that it would be something like it's not implemented yet since the above stackoverflow only mentions jobs can access other stages.

stageDependencies would be a fix to a problem we are facing, update but no change.
We run a terraform plan on every pr push but only want to trigger a apply if there are changes in the plan. But we don't want to trigger an apply without a human gate so we have added a gate in the environment so the stage does not trigger without our knowledge.
This causes a lot of our pipelines to be "Pending, waiting approval" when they are "Done, no change needed".

My hope is that the condition is run before gates so you can trigger the stage and environment gates only if the condition applies.

Another nice thing would be human gates as a condition instead of an environment gate so you could define the gate in the yaml, would up the visibility of who is the target reviewer.

[wolesolana]

Hi @juliakm,

I tried Example 2 and it doesn't seem to work. I also tried @kmadof's suggestion but that doesn't work either. I am running the pipeline using these settings:

Agent name: 'Azure Pipelines 8'
Agent machine name: 'fv-az716'
Current agent version: '2.171.1'
Operating System
Ubuntu
18.04.4
LTS
Virtual Environment
Environment: ubuntu-18.04
Version: 20200709.0

[wolesolana]

Hi @juliakm,

I tried Example 2 and it doesn't seem to work. I also tried @kmadof's suggestion but that doesn't work either. I am running the pipeline using these settings:

Agent name: 'Azure Pipelines 8'
Agent machine name: 'fv-az716'
Current agent version: '2.171.1'
Operating System
Ubuntu
18.04.4
LTS
Virtual Environment
Environment: ubuntu-18.04
Version: 20200709.0

@msebolt, can you help with this issue?

[Nojinverse]

Hi @juliakm, @kmadof
I would like to point out that it's a coincidence that example 2 works since the correct syntax is not used unfortunately. This also explains why @kmadof is saying that it's also not false. from https://github.com/microsoft/azure-pipelines-tasks/issues/4743 we get that the syntax for conditions on job level and stage level is different:

stage condition use: [stageDependencies|dependencies].<stage>.outputs['<job>.<step>.<var>']
job condition use: stageDependencies.<stage>.<job>.outputs['<step>.<var>']

where stageDependencies and dependencies is interchangeable.

the correct code for example 2 is therefore

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - script: echo "##vso[task.setvariable variable=skipsubsequent;isOutput=true]false"
       name: printvar
- stage: B
  condition: and(succeeded(), ne(stageDependencies.A.outputs[A1.printvar.skipsubsequent'], 'true'))
  dependsOn: A
  jobs:
  - job: B1
    steps:
    - script: echo hello from Stage B

[wolesolana]

Thanks @Nojinverse! I also stumbled across your solution while poring through the documentation yesterday. For reference, the correct syntax is documented here.

[juliakm]

@Nojinverse Thanks for your contribution. Updating the example now.

[danquirk]

I got tripped up trying to do this because my stage A was defining the output var in a deployment job which appears to not support this feature (passing variables across stages). Once I defined my output var in a regular job I was able to follow @Nojinverse's example successfully.

It's shockingly difficult to do this seemingly simple thing (declare and use a var) correctly with the lack of Intellisense/debuggability =\