woodpecker/docs/docs/20-usage/22-conditional-execution.md

Conditional Step Execution

Woodpecker supports defining conditional pipeline steps in the when block. If all conditions in the when block evaluate to true the step is executed, otherwise it is skipped.

This can also be utilised on a playbook level if you have multi-arch agents and require specific pipelines to be run on specific architectures. See platform below.

repo

Example conditional execution by repository:

 pipeline:
   slack:
     image: plugins/slack
     settings:
       channel: dev
+    when:
+      repo: test/test

branch

Example conditional execution by branch:

pipeline:
  slack:
    image: plugins/slack
    settings:
      channel: dev
+   when:
+     branch: master

The step now triggers on master, but also if the target branch of a pull request is master. Add an event condition to limit it further to pushes on master only.

Execute a step if the branch is master or develop:

when:
  branch: [master, develop]

Execute a step if the branch starts with prefix/*:

when:
  branch: prefix/*

Execute a step using custom include and exclude logic:

when:
  branch:
    include: [ master, release/* ]
    exclude: [ release/1.0.0, release/1.1.* ]

event

Execute a step if the build event is a tag:

when:
  event: tag

Execute a step if the build event is a tag created from the specified branch:

when:
  event: tag
+ branch: master

Execute a step for all non-pull request events:

when:
  event: [push, tag, deployment]

Execute a step for all build events:

when:
  event: [push, pull_request, tag, deployment]

tag

Execute a step if the tag name starts with release:

when:
  tag: release*

status

There are use cases for executing pipeline steps on failure, such as sending notifications for failed pipelines. Use the status constraint to execute steps even when the pipeline fails:

pipeline:
  slack:
    image: plugins/slack
    settings:
      channel: dev
+   when:
+     status: [ success, failure ]

platform

Execute a step for a specific platform:

when:
  platform: linux/amd64

Execute a step for a specific platform using wildcards:

when:
  platform:  [ linux/*, windows/amd64 ]

environment

Execute a step for deployment events matching the target deployment environment:

when:
  environment: production
  event: deployment

matrix

Execute a step for a single matrix permutation:

when:
  matrix:
    GO_VERSION: 1.5
    REDIS_VERSION: 2.8

instance

Execute a step only on a certain Woodpecker instance matching the specified hostname:

when:
  instance: stage.woodpecker.company.com

path

:::info This feature is currently only available for GitHub, Gitlab and Gitea. Pull requests aren't supported at the moment (#697).
Path conditions are ignored for tag events. :::

Execute a step only on a pipeline with certain files being changed:

when:
  path: "src/*"

You can use glob patterns to match the changed files and specify if the step should run if a file matching that pattern has been changed include or if some files have not been changed exclude.

when:
  path:
    include: [ '.woodpecker/*.yml', '*.ini' ]
    exclude: [ '*.md', 'docs/**' ]
    ignore_message: "[ALL]"

** Hint: ** Passing a defined ignore-message like [ALL] inside the commit message will ignore all path conditions.