Skip to main content
Version: Next

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:
    [...]
    volumes:
      - woodpecker-agent-config:/etc/woodpecker
    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_WORKFLOWS 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_WORKFLOWS 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_WORKFLOWS=4

Agent registration on server​

When the agent starts, it connects to the server using token from WOODPECKER_AGENT_SECRET. The server identifies agent and, if such agent doesn't exist, register him. There are two types of token, so would be two ways of agent registration.

Using system token​

System token is a token that is used system-wide, e. g. when you set the same token in WOODPECKER_AGENT_SECRET on both the server and the agents.

In that case registration process would be as follows:

  1. First time Agent communicates with Server using system token;
  2. Server registers Agent in DB, generates ID and sends this ID back to Agent;
  3. Agent stores ID in a file configured by WOODPECKER_AGENT_CONFIG_FILE.

At the following startups Agent uses system token and ID.

Using agent token​

Agent token is a token that is used by only particular agent. This unique token also configured by WOODPECKER_AGENT_SECRET, but only on the agent side.

In that case you probably doesn't configure WOODPECKER_AGENT_SECRET on the server side. The registration process would be as follows:

  1. Administrator registers Agent manually in Server settings - Agents - Add agent; Agent creationAgent created
  2. The token generated in previous step have to be provided to Agent in WOODPECKER_AGENT_SECRET;
  3. First time Agent communicates with Server using agent token;
  4. Server identifies Agent by the token and fills additional information provided by Agent; Agent connected

At following startups Agent uses own token only.

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_AGENT_SECRET_FILE​

Default: empty

Read the value for WOODPECKER_AGENT_SECRET from the specified filepath, e.g. /etc/woodpecker/agent-secret.conf

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_AGENT_CONFIG_FILE​

Default: /etc/woodpecker/agent.conf

Configures the path of the agent config file.

WOODPECKER_MAX_WORKFLOWS​

Default: 1

Configures the number of parallel workflows.

WOODPECKER_FILTER_LABELS​

Default: empty

Configures labels to filter pipeline pick up. Use a list of key-value pairs like key=value,second-key=*. * can be used as a wildcard. By default agents provide three additional labels platform=os/arch, hostname=my-agent and repo=* which can be overwritten if needed. To learn how labels work check out the pipeline syntax page.

WOODPECKER_HEALTHCHECK​

Default: true

Enable healthcheck endpoint.

WOODPECKER_HEALTHCHECK_ADDR​

Default: :3000

Configures healthcheck endpoint address.

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, docker, local, ssh or kubernetes.

WOODPECKER_BACKEND_DOCKER_*​

See Docker backend configuration

WOODPECKER_BACKEND_SSH_*​

See SSH backend configuration

WOODPECKER_BACKEND_K8S_*​

See Kubernetes backend configuration

Advanced Settings​

danger

Only change these If you know what you do.

WOODPECKER_CONNECT_RETRY_COUNT​

Default: 5

Configures number of times agent retries to connect to the server.

WOODPECKER_CONNECT_RETRY_DELAY​

Default: 2s

Configures delay between agent connection retries to the server.