Woodpecker CI Documentation

Woodpecker allows you to replace internal logic with external extensions by using pre-defined HTTP endpoints. There are currently three types of extensions available:

• Configuration extension: Modifies or generates pipeline configurations on the fly.
• Registry extension: Retrieves registry credentials from an external service.
• Secret extension: Retrieves secrets from an external service.

Status Reporting

Each workflow reports its own status back to your Git forge.

Ordering

Queued workflows within the same group start in the order their pipelines were created. This ensures that even if a later pipeline's dependencies finish faster, it will not overtake an earlier pipeline, guaranteeing that workflows like deployments happen in the correct commit order.

Plugins operate with specific constraints to ensure they perform only their intended functions:

• Workspace Access: Plugins share the build workspace, which is mounted as a volume. The workspace base is always mounted at /woodpecker, though the working directory is dynamically adjusted for the plugin.
• Restrictions: You cannot use commands or entrypoint in a plugin step; doing so will cause the step to fail.
• Environment Variables: While you can use the environment key, doing so changes how the container is treated. The container will no longer be treated as a standard plugin, meaning it cannot access secrets via plugin filters and will not be privileged unless explicitly defined.

Woodpecker is composed of three main components:

• server: Provides the user interface, processes forge webhooks, serves the API, and analyzes pipeline YAML configurations.
• agent: Executes workflows using a specific backend (Docker, Kubernetes, or local) and connects to the server via GRPC. You can run multiple agents to fine-tune job limits and backends.
• autoscaler (optional): Automatically spins up and destroys VMs on cloud providers to process pending builds.

To increase parallel workflow capacity, you can either add more agents or set the WOODPECKER_MAX_WORKFLOWS environment variable on an existing agent.

Woodpecker consists of three primary components that interact to provide CI/CD capabilities:

1. Server: The central orchestrator. It handles REST API requests, manages the database (store), connects to forges (GitHub, GitLab, etc.), and maintains a queue of work. It provides a WebUI and communicates with agents via gRPC.
2. Agent: A remote worker that connects to the server via gRPC. It polls the server's queue for new work, executes pipeline steps using the engine, and streams logs and execution state back to the server.
3. CLI: A command-line tool used to interact with the server (managing users, secrets, repos, etc.) or to execute pipelines locally for testing.

The Engine (found in the pipeline package) acts as the shared kernel that parses configuration files, enriches them with forge metadata, and prepares them for execution.

The SSH backend has been removed in v2.0.0. To achieve similar functionality, you can:

1. Install an agent running the local backend directly on the remote machine.
2. Execute ssh commands within your pipeline to connect to the remote server.

When configuring Woodpecker or writing code/scripts, adhere to these preferred naming conventions:

• URLs vs Links: Environment variables ending in *_LINK should be referred to as *_URL. When writing code, use the URL() method instead of Link().
• Pipelines: Use the term pipelines (formerly referred to as builds).
• Steps: Use the term steps (formerly referred to as jobs).
• Advanced Variables: Use the prefix WOODPECKER_EXPERT_ for advanced environment variables that are typically not required for standard user configuration.

Service containers often require time to initialize before they can accept connections. To prevent connection errors, implement a wait mechanism (like sleep) or a retry/backoff logic in your pipeline steps that depend on the service.

steps:
  - name: test
    image: golang
    commands:
      - sleep 15
      - go get
      - go test

 services:
   - name: database
     image: mysql

To generate a production build of the documentation for deployment to static page hosting, use the pnpm build command within the docs/ directory after installing dependencies and building required plugins.

cd docs/
pnpm install
pnpm build:woodpecker-plugins
pnpm build

To manually build and push the website to the deployment target, use the pnpm deploy command with the required environment variables. Note that standard deployments are typically handled via CI to woodpecker-ci.org.

GIT_USER=woodpecker-bot USE_SSH=true DEPLOYMENT_BRANCH=main pnpm deploy