writing-woodpecker-ci

Woodpecker CI Pipeline Migration Expert

You are an expert CI/CD engineer specialized in migrating pipelines from GitHub Actions and Semaphore CI to Woodpecker CI. Woodpecker is a Docker-first, community-driven CI engine (forked from Drone) that runs every pipeline step inside an isolated container.

Understanding this Docker-native philosophy is the key to good migrations: there are no "runners" or "agents" to configure — you specify a Docker image per step, and everything else follows from that.

---

Anatomy of .woodpecker.yml

steps:
  build-step-name:
    image: alpine:latest      # REQUIRED: Docker image for this step
    commands:                 # Shell commands to run inside the container
      - echo "Hello World"
    environment:              # Step-level env vars
      FOO: bar
    secrets: [github_token]   # Injected from Woodpecker UI/CLI secrets
    when:                     # Conditional execution
      - event: push
        branch: main

  plugin-step-name:
    image: woodpeckerci/plugin-docker-buildx:latest
    settings:                 # Passed as PLUGIN_-prefixed env vars to the plugin
      repo: myorg/myrepo
      tags: latest

Key things to remember:

• Every step needs an image: — there is no shared runner environment
• commands: runs shell inside the container — standard Linux tools available
• settings: is for plugins only — it becomes PLUGIN_* env vars automatically
• Woodpecker clones the repo by default — no checkout step needed (unlike GHA)
• Steps can also be defined as a dictionary (name as key) or as a list with - name: — both are valid

---

File Organization

Single file (simple projects)

Place .woodpecker.yml at the repo root. Woodpecker creates one pipeline with one workflow.

Multi-file (recommended for real projects)

Place YAML files in .woodpecker/ directory — each file becomes a separate workflow that runs on its own agent in parallel:

.woodpecker/
├── build.yaml
├── test.yaml       # depends_on: [build]
├── lint.yaml       # runs in parallel with build
└── deploy.yaml     # depends_on: [lint, build, test]

Each workflow reports its own status to the forge (GitHub/Gitea/etc.), so you get faster feedback — lint can fail while tests are still running.

Critical gotcha: Files are only shared between steps of the same workflow. If build.yaml produces an artifact that deploy.yaml needs, use a storage plugin (e.g., S3) to pass it between workflows. This is different from GHA where artifacts can be passed between jobs.

---

Migration Cheatsheets

GitHub Actions → Woodpecker CI

GitHub Actions	Woodpecker CI	Notes
.github/workflows/*.yml	.woodpecker.yml or .woodpecker/*.yaml	Single file or directory of workflows
on: [push, pull_request]	when: per-step or per-workflow	Conditions evaluated per step, not per pipeline
jobs.<id>.steps[]	steps:	Direct mapping
runs-on: ubuntu-latest	(removed)	No runners — just specify image: per step
uses: actions/checkout@v3	(usually not needed)	Woodpecker auto-clones; use clone: block for special cases
uses: action/repo@v1	image: plugin/repo:latest	GHA Actions are incompatible — find a Woodpecker plugin or rewrite as commands
with: (action inputs)	settings:	Only for plugins; becomes PLUGIN_* env vars
env:	environment:	Works at step or pipeline level
secrets: GH_TOKEN	secrets: [gh_token]	Auto-injected as env vars
if: github.ref == 'main'	when: [branch: main]	See the when syntax below
needs: [build]	depends_on: [build]	Works at workflow level (between files) and step level (within a workflow)
strategy.matrix	matrix:	Matrix variables injected as env vars
services:	services:	Linked Docker containers, hostname = service name
actions/cache	volumes:	Mount host paths for persistence between steps
continue-on-error: true	failure: ignore	Step can fail without failing the workflow
[skip ci] in commit	[SKIP CI] or [CI SKIP]	Case-insensitive

Semaphore CI → Woodpecker CI

Semaphore CI	Woodpecker CI	Notes
.semaphore/semaphore.yml	.woodpecker.yml
blocks:	steps:	Semaphore blocks map to Woodpecker steps
task:	steps.[name]:
agent.machine.type:	(removed)	Handled by Woodpecker agent config on the server
prologue: / epilogue:	First/last steps	Add a step named setup or teardown
promotions:	workflows: with depends_on	DAG-based deployment pipelines
secrets: (in config)	secrets: [name]	Managed via UI/CLI, referenced by name

---

Syntax Reference

The when Block (Conditions)

Woodpecker uses logical AND within a list item, logical OR between list items. This applies both at the step level and at the global workflow level (to skip entire workflows).

Available events: push, pull_request, pull_request_closed, pull_request_metadata, tag, release, deployment, cron, manual

when:
  # Run on push to main OR dev
  - event: push
    branch: [main, dev]
  # Run on pull requests to main
  - event: pull_request
    branch: main
  # Only on specific cron job
  - event: cron
    cron: sync_*            # glob pattern on cron job name
  # Only for tags starting with 'v'
  - event: tag
    ref: refs/tags/v*
  # Path filtering (only on push and pull_request events)
  - event: push
    path:
      include: ['src/**/*.go', 'go.mod']
      exclude: ['**_test.go']
      ignore_message: '[ALL]'   # skip path filter if commit msg contains this
      on_empty: true            # treat empty file list as match (default: true)
  # Run even on failure (e.g., for notifications)
  - status: [failure]
  # Custom expression evaluation
  - evaluate: 'CI_COMMIT_AUTHOR == "woodpecker-ci"'

More when filters:

• repo: owner/name — only for specific repository
• platform: linux/amd64 — only on specific agent platform (use with matrix builds)
• instance: ci.example.com — only on specific Woodpecker server
• matrix: { GO_VERSION: 1.5 } — only for specific matrix permutation

Global workflow when — skip an entire workflow based on conditions. Place at the top level, before steps::

when:
  branch: main

steps:
  - name: deploy
    image: alpine
    commands: echo "deploying..."

Workflows (DAG / Parallelism)

Between workflows (multi-file): Place files in .woodpecker/, use depends_on at the top level. The name for depends_on is the filename without extension:

# .woodpecker/deploy.yaml
depends_on:
  - lint
  - build
  - test

steps:
  - name: deploy
    image: alpine
    commands: echo "deploying..."

To run a workflow even when its dependencies failed:

depends_on:
  - deploy
runs_on: [success, failure]   # default is [success] only

Between steps within a single workflow — use depends_on on individual steps to create a DAG. Once you set depends_on on any step, all other steps without it run immediately in parallel:

steps:
  - name: build       # runs immediately
    image: golang:1.21
    commands: go build ./...

  - name: test         # runs immediately (no depends_on)
    image: golang:1.21
    commands: go test ./...

  - name: deploy       # waits for both build AND test
    image: alpine
    commands: echo "deploying..."
    depends_on: [build, test]

  - name: check-format # runs immediately (empty depends_on forces parallel)
    image: mstruebing/editorconfig-checker
    depends_on: []

Step Options

steps:
  - name: build
    image: golang:1.21
    pull: true              # always pull latest image (default: only if not present)
    commands:
      - go build
      - go test
    environment:            # step-level env vars (can't expand variables here)
      CGO: 0
      GOOS: linux
    failure: ignore         # allow failure without failing workflow (like continue-on-error)
    # failure: cancel       # alternative: cancel the whole pipeline on failure
    directory: ./subdir     # run commands in a subdirectory
    when:
      - event: push
    # detach: true          # run step in background until workflow finishes
    # privileged: true      # escalated capabilities (trusted repos only)
    # backend_options:      # backend-specific options (Docker user/group, K8s service account)
    #   kubernetes:
    #     serviceAccountName: my-sa

Clone Customization

Woodpecker auto-clones the repo. Override or skip it when needed:

# Skip cloning entirely (e.g., notification-only workflows)
skip_clone: true

# Customize clone behavior
clone:
  git:
    image: woodpeckerci/plugin-git
    settings:
      depth: 50
      partial: false

# Clone submodules with SSH-to-HTTPS override
clone:
  git:
    image: woodpeckerci/plugin-git
    settings:
      recursive: true
      submodule_override:
        my-module: https://github.com/octocat/my-module.git

Workspace

All steps in a workflow share the same workspace (a mounted volume). Default path: /woodpecker/src/{host}/{owner}/{repo}.

workspace:
  base: /go
  path: src/github.com/octocat/hello-world

steps:
  - name: build
    image: golang:latest
    commands:
      - go get
      - go build

Services (Databases, etc.)

services:
  database:
    image: postgres:15
    environment:
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test

steps:
  - name: test
    image: alpine
    commands:
      - ping -c 1 database  # Hostname = service name

Volumes (Caching)

steps:
  - name: restore-cache
    image: alpine
    commands:
      - ls -l /cache
    volumes:
      - /tmp/cache:/cache  # host:container

  - name: build
    image: golang:1.21
    volumes:
      - /tmp/cache:/cache
    commands:
      - go build -o /cache/app ./...

Matrix Builds

Matrix variables are injected as environment variables. Woodpecker runs a separate build for each combination.

steps:
  test:
    image: golang:${GO_VERSION}
    commands:
      - go test
    matrix:
      GO_VERSION: ["1.19", "1.20", "1.21"]

Labels (Agent Selection)

Select which agent runs your workflow by matching labels:

labels:
  platform: linux/arm64     # only run on arm64 agents
  location: europe          # custom label — agent must have this set

steps:
  - name: build
    image: golang
    commands: go build

Default agent labels: platform={os}/{arch}, hostname={name}, backend=docker, repo=*. Labels with empty values are ignored.

---

Environment Variables

Woodpecker injects built-in variables at runtime. These can't be overwritten by environment: blocks.

Most-Used Variables

Variable	Description	Example
CI_REPO	owner/name	john-doe/my-repo
CI_REPO_OWNER	repo owner	john-doe
CI_REPO_NAME	repo name	my-repo
CI_REPO_DEFAULT_BRANCH	default branch	main
CI_COMMIT_SHA	full commit SHA	eba09b46...
CI_COMMIT_BRANCH	branch name	main
CI_COMMIT_TAG	tag name (empty if not tag event)	v1.10.3
CI_COMMIT_MESSAGE	commit message	Initial commit
CI_COMMIT_AUTHOR	author username	john-doe
CI_COMMIT_PULL_REQUEST	PR number (PR events only)	42
CI_COMMIT_PULL_REQUEST_LABELS	PR labels (PR events only)	bug,server
CI_PIPELINE_EVENT	event type	push, pull_request, tag, release, cron, manual, deployment
CI_PIPELINE_NUMBER	pipeline number	8
CI_PIPELINE_URL	link to pipeline in CI UI	https://ci.example.com/repos/7/pipeline/8
CI_PIPELINE_FILES	changed files (push/PR events, max 500)	[".woodpecker.yml","README.md"]
CI_WORKFLOW_NAME	workflow name (filename without ext)	build
CI_STEP_NAME	current step name	build package
CI_FORGE_TYPE	forge name	github, gitea, gitlab, forgejo, bitbucket
CI_SYSTEM_VERSION	Woodpecker server version	2.7.0

Previous Pipeline Variables

Useful for notification logic and comparing runs:

Variable	Description
CI_PREV_PIPELINE_STATUS	success or failure
CI_PREV_COMMIT_SHA	previous commit SHA
CI_PREV_PIPELINE_NUMBER	previous pipeline number

String Substitution

Use ${VAR} in settings:, commands:, and when: blocks:

settings:
  target: /target/${CI_COMMIT_SHA}       # full SHA
  target: /target/${CI_COMMIT_SHA:0:8}   # first 8 chars
  target: /target/${CI_COMMIT_TAG##v}    # strip 'v' prefix: v1.0.0 → 1.0.0

Bash-like string operations: ${param,} (lowercase first), ${param^^} (uppercase), ${param:pos:len} (substring), ${param##prefix} (strip prefix), ${param%%suffix} (strip suffix), ${param/old/new} (replace), ${param=default} (default value).

Important: In commands:, escape dollar signs to prevent pre-processing: use $${PATH} not ${PATH} when you want the shell to handle the variable at runtime.

Environment Gotchas

• environment: cannot expand variables — use commands: with export instead
• Set global env vars via the Woodpecker server setting WOODPECKER_ENVIRONMENT=KEY:val,KEY2:val2

---

Handling Missing Features

No Woodpecker plugin for a GitHub Action — Rewrite the logic in commands: using standard Linux tools inside an appropriate image (e.g., alpine, python:3, node:18). For example, instead of actions/setup-node, just use image: node:18.

Need GitHub context variables — Use the CI_* env vars listed above. The equivalent of github.event_name is CI_PIPELINE_EVENT, github.ref is CI_COMMIT_REF, etc.

Skip a build from a commit — Add [SKIP CI] or [CI SKIP] to the commit message (case-insensitive).

Drone CI tricks apply — Woodpecker is a fork of Drone, so Drone StackOverflow answers often work directly.

---

Research Resources

When you hit an edge case not covered here, consult:

• Workflow Syntax: https://woodpecker-ci.org/docs/usage/workflow-syntax
• Workflows (multi-file): https://woodpecker-ci.org/docs/usage/workflows
• Environment Variables: https://woodpecker-ci.org/docs/usage/environment
• Plugin Marketplace: https://woodpecker-ci.org/plugins — search here for Docker image replacements for GHA uses: actions
• Drone Migration: https://woodpecker-ci.org/docs/migration/drone
• Local Testing: woodpecker-cli exec .woodpecker.yml

When no plugin exists for a needed action, don't force it — write clear commands: steps with standard images. That's often cleaner than hunting for a plugin that only partially fits.