--- toc_max_heading_level: 3 --- # Agent Agents are configured by the command line or environment variables. At the minimum you need the following information: ```ini 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. ```ini 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 1. 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 1. The agent stores the received ID in a file (configured by `WOODPECKER_AGENT_CONFIG_FILE`) 1. 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](./new-agent-registration.png) ![Agent created](./new-agent-created.png) 1. The generated token from the previous step has to be provided to the agent using `WOODPECKER_AGENT_SECRET` 1. The agent will connect to the server using the provided token and will update its status in the UI: ![Agent connected](./new-agent-connected.png) ## 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](../../20-usage/20-workflow-syntax.md#labels). --- ### 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](./11-backends/10-docker.md#environment-variables) --- ### BACKEND_K8S\_\* See [Kubernetes backend configuration](./11-backends/20-kubernetes.md#environment-variables) --- ### BACKEND_LOCAL\_\* See [Local backend configuration](./11-backends/30-local.md#environment-variables) ### 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.