Matrix workflows

Woodpecker has integrated support for matrix workflows. Woodpecker executes a separate workflow for each combination in the matrix, allowing you to build and test against multiple configurations.

warning

Woodpecker generates at most 64 workflows per matrix. The variables are also limited to 10 per axis. A matrix with more combinations is rejected with an error.

Example matrix definition:

matrix:
  GO_VERSION:
    - 1.4
    - 1.3
  REDIS_VERSION:
    - 2.6
    - 2.8
    - 3.0

Example matrix definition containing only specific combinations:

matrix:
  include:
    - GO_VERSION: 1.4
      REDIS_VERSION: 2.8
    - GO_VERSION: 1.5
      REDIS_VERSION: 2.8
    - GO_VERSION: 1.6
      REDIS_VERSION: 3.0

Interpolation

Matrix variables are interpolated in the YAML using the ${VARIABLE} syntax, before the YAML is parsed. This is an example YAML file before interpolating matrix parameters:

matrix:
  GO_VERSION:
    - 1.4
    - 1.3
  DATABASE:
    - mysql:8
    - mysql:5
    - mariadb:10.1

steps:
  - name: build
    image: golang:${GO_VERSION}
    commands:
      - go get
      - go build
      - go test

services:
  - name: database
    image: ${DATABASE}

Example YAML file after injecting the matrix parameters:

 steps:
   - name: build
-    image: golang:${GO_VERSION}
+    image: golang:1.4
     commands:
       - go get
       - go build
       - go test
+    environment:
+      - GO_VERSION=1.4
+      - DATABASE=mysql:8

 services:
   - name: database
-    image: ${DATABASE}
+    image: mysql:8

Examples

Example matrix pipeline based on Docker image tag

matrix:
  TAG:
    - 1.7
    - 1.8
    - latest

steps:
  - name: build
    image: golang:${TAG}
    commands:
      - go build
      - go test

Example matrix pipeline based on container image

matrix:
  IMAGE:
    - golang:1.7
    - golang:1.8
    - golang:latest

steps:
  - name: build
    image: ${IMAGE}
    commands:
      - go build
      - go test

Example matrix pipeline using multiple platforms

matrix:
  platform:
    - linux/amd64
    - linux/arm64

labels:
  platform: ${platform}

steps:
  - name: test
    image: alpine
    commands:
      - echo "I am running on ${platform}"

  - name: test-arm-only
    image: alpine
    commands:
      - echo "I am running on ${platform}"
      - echo "Arm is cool!"
    when:
      platform: linux/arm*

note

If you want to control the architecture of a pipeline on a Kubernetes runner, see the nodeSelector documentation of the Kubernetes backend.