Skip to main content
Version: 0.15.x

Agent configuration

Agents are configured by the command line or environment variables. At the minimum you need the following information:

# docker-compose.yml
version: '3'

services:
woodpecker-agent:
[...]
environment:
+ - WOODPECKER_SERVER=localhost:9000
+ - WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"

The following are automatically set and can be overridden:

  • WOODPECKER_HOSTNAME if not set, becomes the OS' hostname
  • WOODPECKER_MAX_PROCS if not set, defaults to 1

Processes per agentโ€‹

By default the maximum processes that are run per agent is 1. If required you can add WOODPECKER_MAX_PROCS to increase your parallel processing on a per-agent basis.

# docker-compose.yml
version: '3'

services:
woodpecker-agent:
[...]
environment:
- WOODPECKER_SERVER=localhost:9000
- WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
+ - WOODPECKER_MAX_PROCS=4

Filtering agentsโ€‹

When building your pipelines as long as you have set the platform or filter, builds can be made to only run code on certain agents.

- WOODPECKER_HOSTNAME=mycompany-ci-01.example.com
- WOODPECKER_FILTER=

Filter on Platformโ€‹

Only want certain pipelines or steps to run on certain agents with specific platforms? Such as arm vs amd64?

# .woodpecker.yml
pipeline:
build:
image: golang
commands:
- go build
- go test
when:
platform: linux/amd64


testing:
image: golang
commands:
- go build
- go test
when:
platform: linux/arm*


See Conditionals Pipeline syntax for more

All agent configuration optionsโ€‹

Here is the full list of configuration options and their default variables.

WOODPECKER_SERVERโ€‹

Default: localhost:9000

Configures gRPC address of the server.

WOODPECKER_USERNAMEโ€‹

Default: x-oauth-basic

The gRPC username.

WOODPECKER_AGENT_SECRETโ€‹

Default: empty

A shared secret used by server and agents to authenticate communication. A secret can be generated by openssl rand -hex 32.

WOODPECKER_LOG_LEVELโ€‹

Default: empty

Configures the logging level. Possible values are trace, debug, info, warn, error, fatal, panic, disabled and empty.

WOODPECKER_DEBUG_PRETTYโ€‹

Default: false

Enable pretty-printed debug output.

WOODPECKER_DEBUG_NOCOLORโ€‹

Default: true

Disable colored debug output.

WOODPECKER_HOSTNAMEโ€‹

Default: empty

Configures the agent hostname.

WOODPECKER_MAX_PROCSโ€‹

Default: 1

Configures the number of parallel builds.

WOODPECKER_HEALTHCHECKโ€‹

Default: true

Enable healthcheck endpoint.

WOODPECKER_KEEPALIVE_TIMEโ€‹

Default: empty

After a duration of this time of no activity, the agent pings the server to check if the transport is still alive.

WOODPECKER_KEEPALIVE_TIMEOUTโ€‹

Default: 20s

After pinging for a keepalive check, the agent waits for a duration of this time before closing the connection if no activity.

WOODPECKER_GRPC_SECUREโ€‹

Default: false

Configures if the connection to WOODPECKER_SERVER should be made using a secure transport.

WOODPECKER_GRPC_VERIFYโ€‹

Default: true

Configures if the gRPC server certificate should be verified, only valid when WOODPECKER_GRPC_SECURE is true.

WOODPECKER_BACKENDโ€‹

Default: auto-detect

Configures the backend engine to run pipelines on. Possible values are auto-detect or docker.