Agent configuration
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' hostnameWOODPECKER_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:
- The first time the agent communicates with the server, it is using the system token
- 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
- The agent stores the received ID in a file (configured by
WOODPECKER_AGENT_CONFIG_FILE
) - 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:
- The administrator registers a new agent manually at
Settings -> Agents -> Add agent
- The generated token from the previous step has to be provided to the agent using
WOODPECKER_AGENT_SECRET
- The agent will connect to the server using the provided token and will update its status in the UI:
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.