Skip to main content
Version: Next 🚧

Agent

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

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

Workflows per agent​

By default, the maximum workflows that are executed in parallel on an agent is 1. If required, you can add WOODPECKER_MAX_WORKFLOWS to increase your parallel processing for an agent.

WOODPECKER_SERVER=localhost:9000
WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
WOODPECKER_MAX_WORKFLOWS=4

Agent registration​

When the agent starts it connects to the server using the token from WOODPECKER_AGENT_SECRET. The server identifies the agent and registers the agent in its database if it wasn't connected before.

There are two types of tokens to connect an agent to the server:

Using system token​

A 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 following:

  1. The first time the agent communicates with the server, it is using the system token
  2. The server registers the agent in its database if not done before and generates a unique ID which is then sent back to the agent
  3. The agent stores the received ID in a file (configured by WOODPECKER_AGENT_CONFIG_FILE)
  4. At the following startups, the agent uses the system token and its received ID to identify itself to the server

Using agent token​

An agent token is a token that is used by only one particular agent. This unique token is applied to the agent by WOODPECKER_AGENT_SECRET.

To get an agent token you have to register the agent manually in the server using the UI:

  1. The administrator registers a new agent manually at Settings -> Agents -> Add agent Agent creation Agent created
  2. The generated token from the previous step has to be provided to the agent using WOODPECKER_AGENT_SECRET
  3. The agent will connect to the server using the provided token and will update its status in the UI: Agent connected

Agent filters​

Labels set with WOODPECKER_AGENT_LABELS are reported by the agent itself. An agent can therefore claim any label it likes, which makes them unsuitable to restrict what an agent is allowed to pick up.

Agent filters are the server-side counterpart: they are stored in the server database and are applied by the server every time the agent asks for work. An agent cannot see, change or drop them.

Filters use the same syntax as agent labels:

  • key=value matches workflows whose label key is value
  • key=* matches workflows with any value for key
  • !key=value additionally requires the workflow to have that label set and matched

Filters are managed as a key-value list in the UI when creating or editing an agent:

  • instance-wide agents at Settings -> Agents
  • organization agents at Organization settings -> Agents
  • personal agents at User settings -> Agents

If a filter uses the same key as a label reported by the agent, the filter wins.

info

Changes to the filters of an agent apply the next time that agent requests a workflow.

Organization and personal agents always get the org-id filter enforced on top of the configured filters, so they can never pick up workflows of another organization.

Environment variables​

SERVER​

  • Name: WOODPECKER_SERVER
  • Default: localhost:9000

Configures gRPC address to the server. If you want to use an unix socket add unix:// prefix and the path.

USERNAME​

  • Name: WOODPECKER_USERNAME
  • Default: x-oauth-basic

The gRPC username.

AGENT_SECRET​

  • Name: WOODPECKER_AGENT_SECRET
  • Default: none

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

AGENT_SECRET_FILE​

  • Name: WOODPECKER_AGENT_SECRET_FILE
  • Default: none

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

LOG_LEVEL​

  • Name: WOODPECKER_LOG_LEVEL
  • Default: info

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

DEBUG_PRETTY​

  • Name: WOODPECKER_DEBUG_PRETTY
  • Default: false

Enable pretty-printed debug output.

DEBUG_NOCOLOR​

  • Name: WOODPECKER_DEBUG_NOCOLOR
  • Default: true

Disable colored debug output.

HOSTNAME​

  • Name: WOODPECKER_HOSTNAME
  • Default: none

Configures the agent hostname.

AGENT_CONFIG_FILE​

  • Name: WOODPECKER_AGENT_CONFIG_FILE
  • Default: /etc/woodpecker/agent.conf

Configures the path of the agent config file.

MAX_WORKFLOWS​

  • Name: WOODPECKER_MAX_WORKFLOWS
  • Default: 1

Configures the number of parallel workflows.

AGENT_SINGLE_WORKFLOW​

  • Name: WOODPECKER_AGENT_SINGLE_WORKFLOW
  • Default: false

Configures the agent to exit (shutdown) after executing one workflow. When configured, WOODPECKER_MAX_WORKFLOWS is forced to 1.

This one-shot mode is useful in ephemeral environments that are provisioned on demand by external automation — for example, when an autoscaler spins up a dedicated machine. In these setups, the agent starts, executes exactly one workflow, and exits, allowing the environment to be cleanly torn down afterward.

AGENT_LABELS​

  • Name: WOODPECKER_AGENT_LABELS
  • Default: none

Configures custom labels for the agent, to let workflows filter by it. Use a list of key-value pairs like key=value,second-key=*. * can be used as a wildcard. If you use ! as key prefix it is mandatory for the workflow to have that label set (without !) set and matched. By default, agents provide four additional labels platform=os/arch, hostname=my-agent, backend=my-backend and repo=* which can be overwritten if needed. To learn how labels work, check out the pipeline syntax page.

Labels set here are reported by the agent and can be overruled by the server-side agent filters.

HEALTHCHECK​

  • Name: WOODPECKER_HEALTHCHECK
  • Default: true

Enable healthcheck endpoint.

HEALTHCHECK_ADDR​

  • Name: WOODPECKER_HEALTHCHECK_ADDR
  • Default: :3000

Configures healthcheck endpoint address.

KEEPALIVE_TIME​

  • Name: WOODPECKER_KEEPALIVE_TIME
  • Default: none

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

KEEPALIVE_TIMEOUT​

  • Name: 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.

GRPC_SECURE​

  • Name: WOODPECKER_GRPC_SECURE
  • Default: false

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

GRPC_SKIP_VERIFY​

  • Name: WOODPECKER_GRPC_SKIP_VERIFY
  • Default: true

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

RETRY_TIMEOUT​

  • Name: WOODPECKER_RETRY_TIMEOUT
  • Default: 2m

Set how long the agent keeps retrying to reconnect to the server after the gRPC connection is lost before giving up.

warning

If set to 0 we retry forever.

LOG_ENTRY_STREAM_BUFFER_SIZE​

  • Name: WOODPECKER_LOG_ENTRY_STREAM_BUFFER_SIZE
  • Default: 100

Set how many log lines an agent can buffer before it blocks io.Pipe, expect logentries to reach 1 MB in worst case. If used with local backend, tis can increase your performance in special cases significantly.

warning

If set to 0 we are always blocking.

BACKEND​

  • Name: WOODPECKER_BACKEND
  • Default: auto-detect

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

BACKEND_DOCKER_*​

See Docker backend configuration

BACKEND_K8S_*​

See Kubernetes backend configuration

BACKEND_LOCAL_*​

See Local backend configuration

Advanced Settings​

warning

Only change these If you know what you do.

CONNECT_RETRY_COUNT​

  • Name: WOODPECKER_CONNECT_RETRY_COUNT
  • Default: 5

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

CONNECT_RETRY_DELAY​

  • Name: WOODPECKER_CONNECT_RETRY_DELAY
  • Default: 2s

Configures delay between agent connection retries to the server.