CI skip command check template

This template provides a job which parses the commit message of the pull request, and if it contains a CI skip command such as [skip ci] it sets a variable in the Azure Pipelines run. This variable can be used as a condition on subsequent stages of the run, such that using a skip command reduces the amount of building and testing.

For a CI skip command to be recognised for a job, the latest commit to the pull request branch that triggered the Azure Pipelines run must have a commit message that contains a recognised CI skip command in its first line. Recognised commands include [skip ci] and [ci skip]. See Custom skip commands for more details.

Basic setup

Firstly, ensure you load the templates under the OpenAstronomy namespace as described in Loading the templates. The following code shows how to place the job within a stage.

stages:
- stage: StageOne
  jobs:
  - template: check-skip.yml@OpenAstronomy

The template must be called as a job within a stage prior to the stages you want to conditionally skip.

Applying conditions to pipeline stages

The job provided by this template creates a variable in the Azure Pipelines run. This variable is accessed at dependencies.STAGE_NAME.outputs['check_skip.search.found'] where STAGE_NAME should be replaced with the name of the stage the template was used within.

It will have a string value of either 'true' or 'false'. It will be 'true' if a skip command was found in the commit message and 'false' otherwise.

This variable can be used to apply a condition to subsequent stages of the run, for example, and(succeeded(), ne(dependencies.Setup.outputs['check_skip.search.found'], 'true')).

Example

The following code provides an example of how to configure the stages section of your azure-pipelines.yml file using this template. Note that you will also need to make sure you first load the templates as described in Loading the templates.

stages:
- stage: StageOneTests
  displayName: Basic Tests
  jobs:
  - template: check-skip.yml@OpenAstronomy
  - template: run-tox-env.yml@OpenAstronomy
    envs:
    - linux: py39

- stage: StageTwoTests
  displayName: Detailed Tests
  condition: and(succeeded(), ne(dependencies.StageOneTests.outputs['check_skip.search.found'], 'true'))
  jobs:
  - template: run-tox-env.yml@OpenAstronomy
    envs:
    - macos: py39
    - windows: py39

In this example, the Basic Tests stage will always run, however, if a skip command is in the commit message the Detailed Tests stage will not run. As this template is independent of the other OpenAstronomy templates, the stages conditions are applied to do not need to run jobs defined using run-tox-env.yml.

Custom skip commands

By default, the list of recognised skip commands are taken from the Azure Pipelines documentation. This list includes [skip ci] and [ci skip] among others.

This default list can be replaced as shown in the following code.

stages:
- stage: StageOne
  jobs:
  - template: check-skip.yml@OpenAstronomy
    parameters:
      commands: '"[skip ci]" "[ci skip]" noci'

This will configure the check to only recognise [skip ci], [ci skip] and noci as valid skip commands. The value of commands must be a string of space separated skip commands, with commands containing spaces inside double quotes. Bash version 4.2 or above is required if specifying custom skip commands.