Skip to main content
Version: 3.4.x

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

Environment variables​

SERVER​

  • Name: WOODPECKER_SERVER
  • Default: localhost:9000

Configures gRPC address of the server.

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_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. 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.

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.

GRPC_VERIFY​

  • Name: WOODPECKER_GRPC_VERIFY
  • Default: true

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

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.