A Useful Debug Step For Azure Pipelines

Variables and Parameters in Azure Pipelines

When building a pipeline within Azure DevOps it can be frustrating trying to make use of variables or parameters that should be in scope for your step buy don’t seem to be. This frustration has led me to develop a quick and simple Bash step that will output all the variables and Parameters that are in use at the moment the step is being executed, which I have found extremely useful. The main use case for this is when trying to expose variables across jobs and steps and you want to make sure the variable is present, or perhaps you want to confirm that the expected parameters are coming through to your step correctly.

The image below shows the output of Variables and Parameters in the pipeline when it runs our debug-output task.

Debug output of variables and parameters

Code For the Debug Output Task

So, lets look at the code. here is the code for the Task itself. As we probably want to add this step into numerous parts of our pipeline it makes sense to define it as a template saved to its own yaml file and then we can then just reference it when we need to use it.

parameters:
- name: parametersToLogOut
  type: object
- name: variablesToLogOut
  type: object
- name: actionName
  type: string
  default: 'action'

steps:
  - task: Bash@3
    displayName: Log Debug Info for ${{ parameters['actionName'] }}
    condition: and(eq(variables['System.debug'], true), succeeded())
    inputs:
      targetType: "inline"
      script: |
        echo "Outputting debug info here for $actionName"
        echo "##[group]Currently available parameters ... "
        echo "Parameters are : $parameters"
        echo "##[endgroup]"
        echo "##[group]Currently available variables ... "
        echo "Variables are : $variables"
        echo "##[endgroup]"
    env:
      parameters: ${{ convertToJson(parameters['parametersToLogOut']) }}
      variables: ${{ convertToJson(parameters['variablesToLogOut']) }}
      actionName: ${{ parameters['actionName'] }}

Firstly we need to take the parameters and variables that we want to log out as parameters into this step. Why do we do this instead of just outputting directly using the Parameters/Variables collection that is always automatically available in all tasks? Well remember we want output the values that are available in the step from where we are calling tis debug output task, we don’t want to log out the Parameters/Variables that this task has as it will be different. So we take the parameters and variables collections from the caller. The third parameter is actionName which is just used for giving some context to the output in the logs.

The condition on the Bash task ensures that this step only runs if the system.debug variable is set. This is important as we usually don’t want to output this information all the time, but only when we are actively debugging the pipelines. when running a pipeline we enable system.debug by setting the “Enable system diagnostics” checkbox in the run pipeline UI.

Enable System Diagnostics to enable System.Debug

To make the Parameters/Variables collections readable and play nicely with the pipeline logs we can use the very useful convertToJSON function provided in Azure Pipelines. We then output the JSON wrapped in a collapsible ##[group] tag for readability.

Pipeline Code Using The Debug Output Task

All that we need to do now if make use of the template task in our pipeline, like in the example below. The output-debug-info task has been added to the bottom of the pipeline and it passes it the parameters and variables that we want to log out (i.e. those available to this pipeline).

pool:
  vmImage: ubuntu-latest
parameters:
- name: parameter1
  type: string
  default: 'this is param example 1'
- name: parameter2
  type: boolean
  default: false
- name: parameter3
  type: object
  default: 
    - "one"
    - "two"
steps:
- script: echo "Hello world!"
  displayName: 'Example task
- script: |
    echo "Hello world again"
    echo ""
  displayName: 'Run a task'

- template: ./output-debug-info.yaml
  parameters:
    parametersToLogOut: ${{ parameters }}
    variablesToLogOut: ${{ variables }}
    actionName: 'HelloWorldTest'

Again here is the output that is produced, the first image showing the the collapsed group and the second image showing the expanded group.

Debug output of variables and parameters

Debug output of variables and parameters