Skip to main content

Conditional Step Execution

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

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 by gitea at the moment (go-gitea/gitea#18228).
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.