Skip to main content
Version: 2.5.x ๐Ÿ’€


Woodpecker architectureโ€‹

Woodpecker architecture

Pipeline, workflow & stepโ€‹

Relation between pipelines, workflows and steps


  • Woodpecker CI: The project name around Woodpecker.
  • Woodpecker: An open-source tool that executes pipelines on your code.
  • Server: The component of Woodpecker that handles webhooks from forges, orchestrates agents, and sends status back. It also serves the API and web UI for administration and configuration.
  • Agent: A component of Woodpecker that executes pipelines (specifically one or more workflows) with a specific backend (e.g. Docker, Kubernetes, local). It connects to the server via GRPC.
  • CLI: The Woodpecker command-line interface (CLI) is a terminal tool used to administer the server, to execute pipelines locally for debugging / testing purposes, and to perform tasks like linting pipelines.
  • Pipeline: A sequence of workflows that are executed on the code. Pipelines are triggered by events.
  • Workflow: A sequence of steps and services that are executed as part of a pipeline. Workflows are represented by YAML files. Each workflow has its own isolated workspace, and often additional resources like a shared network (docker).
  • Steps: Individual commands, actions or tasks within a workflow.
  • Code: Refers to the files tracked by the version control system used by the forge.
  • Repos: Short for repositories, these are storage locations where code is stored.
  • Forge: The hosting platform or service where the repositories are hosted.
  • Workspace: A folder shared between all steps of a workflow containing the repository and all the generated data from previous steps.
  • Event: Triggers the execution of a pipeline, such as a forge event like push, or manual triggered manually from the UI.
  • Commit: A defined state of the code, usually associated with a version control system like Git.
  • Matrix: A configuration option that allows the execution of workflows for each value in the matrix.
  • Service: A service is a step that is executed from the start of a workflow until its end. It can be accessed by name via the network from other steps within the same workflow.
  • Plugins: Plugins are extensions that provide pre-defined actions or commands for a step in a workflow. They can be configured via settings.
  • Container: A lightweight and isolated environment where commands are executed.
  • YAML File: A file format used to define and configure workflows.
  • Dependency: Workflows can depend on each other, and if possible, they are executed in parallel.
  • Status: Status refers to the outcome of a step or workflow after it has been executed, determined by the internal command exit code. At the end of a workflow, its status is sent to the forge.
  • Service extension: Some parts of Woodpecker internal services like secrets storage or config fetcher can be replaced through service extensions.

Pipeline eventsโ€‹

  • push: A push event is triggered when a commit is pushed to a branch.
  • pull_request: A pull request event is triggered when a pull request is opened or a new commit is pushed to it.
  • pull_request_closed: A pull request closed event is triggered when a pull request is closed or merged.
  • tag: A tag event is triggered when a tag is pushed.
  • release: A release event is triggered when a release, pre-release or draft is created. (You can apply further filters using evaluate with environment variables.)
  • manual: A manual event is triggered when a user manually triggers a pipeline.
  • cron: A cron event is triggered when a cron job is executed.


Sometimes there are multiple terms that can be used to describe something. This section lists the preferred terms to use in Woodpecker:

  • Environment variables *_LINK should be called *_URL. In the code use URL() instead of Link()
  • Use the term pipelines instead of the previous builds
  • Use the term steps instead of the previous jobs
  • Use the prefix WOODPECKER_EXPERT_ for advanced environment variables that are normally not required to be set by users