2024-01-08 17:40:43 +00:00
---
toc_max_heading_level: 2
---
2021-09-16 16:50:53 +00:00
# Agent configuration
2022-03-09 00:44:08 +00:00
Agents are configured by the command line or environment variables. At the minimum you need the following information:
2021-11-20 19:45:59 +00:00
2024-01-11 17:43:54 +00:00
```ini
WOODPECKER_SERVER=localhost:9000
WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
2021-11-20 19:45:59 +00:00
```
The following are automatically set and can be overridden:
2024-01-11 17:43:54 +00:00
- `WOODPECKER_HOSTNAME` if not set, becomes the OS' hostname
- `WOODPECKER_MAX_WORKFLOWS` if not set, defaults to 1
2021-11-20 19:45:59 +00:00
2023-10-17 08:31:08 +00:00
## Workflows per agent
2021-11-20 19:45:59 +00:00
2023-10-17 08:31:08 +00:00
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.
2021-11-20 19:45:59 +00:00
2024-01-11 17:43:54 +00:00
```ini
WOODPECKER_SERVER=localhost:9000
WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
WOODPECKER_MAX_WORKFLOWS=4
2021-11-20 19:45:59 +00:00
```
2023-10-17 08:31:08 +00:00
## Agent registration
2023-07-03 13:44:16 +00:00
2023-10-17 08:31:08 +00:00
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.
2023-07-03 13:44:16 +00:00
2023-10-17 08:31:08 +00:00
There are two types of tokens to connect an agent to the server:
2023-07-03 13:44:16 +00:00
2023-10-17 08:31:08 +00:00
### Using system token
2023-07-03 13:44:16 +00:00
2023-10-17 08:31:08 +00:00
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.
2023-07-03 13:44:16 +00:00
2023-10-17 08:31:08 +00:00
In that case registration process would be as following:
2023-07-03 13:44:16 +00:00
2023-10-17 08:31:08 +00:00
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
2023-07-03 13:44:16 +00:00
### Using agent token
2023-10-17 08:31:08 +00:00
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` .
2023-07-03 13:44:16 +00:00
2023-10-17 08:31:08 +00:00
To get an _agent token_ you have to register the agent manually in the server using the UI:
2023-07-03 13:44:16 +00:00
2023-10-17 08:31:08 +00:00
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 )
2023-07-03 13:44:16 +00:00
2021-11-20 19:45:59 +00:00
## All agent configuration options
2022-01-17 14:19:30 +00:00
Here is the full list of configuration options and their default variables.
2021-11-20 19:45:59 +00:00
2022-01-08 22:22:06 +00:00
### `WOODPECKER_SERVER`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> Default: `localhost:9000`
Configures gRPC address of the server.
### `WOODPECKER_USERNAME`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> Default: `x-oauth-basic`
The gRPC username.
### `WOODPECKER_AGENT_SECRET`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> Default: empty
A shared secret used by server and agents to authenticate communication. A secret can be generated by `openssl rand -hex 32` .
2022-03-01 15:09:33 +00:00
### `WOODPECKER_AGENT_SECRET_FILE`
2023-10-24 12:42:05 +00:00
2022-03-01 15:09:33 +00:00
> Default: empty
2023-07-02 15:22:05 +00:00
Read the value for `WOODPECKER_AGENT_SECRET` from the specified filepath, e.g. `/etc/woodpecker/agent-secret.conf`
2022-03-01 15:09:33 +00:00
2022-01-08 22:22:06 +00:00
### `WOODPECKER_LOG_LEVEL`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> Default: empty
Configures the logging level. Possible values are `trace` , `debug` , `info` , `warn` , `error` , `fatal` , `panic` , `disabled` and empty.
### `WOODPECKER_DEBUG_PRETTY`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> Default: `false`
Enable pretty-printed debug output.
### `WOODPECKER_DEBUG_NOCOLOR`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> Default: `true`
Disable colored debug output.
### `WOODPECKER_HOSTNAME`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> Default: empty
Configures the agent hostname.
2023-07-12 16:51:40 +00:00
### `WOODPECKER_AGENT_CONFIG_FILE`
2023-10-24 12:42:05 +00:00
2023-07-12 16:51:40 +00:00
> Default: `/etc/woodpecker/agent.conf`
2023-07-02 15:22:05 +00:00
2023-07-12 16:51:40 +00:00
Configures the path of the agent config file.
2023-07-02 15:22:05 +00:00
2022-10-28 15:38:53 +00:00
### `WOODPECKER_MAX_WORKFLOWS`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> Default: `1`
2022-10-28 15:38:53 +00:00
Configures the number of parallel workflows.
2022-01-08 22:22:06 +00:00
2022-05-30 23:12:18 +00:00
### `WOODPECKER_FILTER_LABELS`
2023-10-24 12:42:05 +00:00
2022-05-30 23:12:18 +00:00
> Default: empty
2023-10-17 08:31:08 +00:00
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 ](../20-usage/20-workflow-syntax.md#labels ).
2022-05-30 23:12:18 +00:00
2022-01-08 22:22:06 +00:00
### `WOODPECKER_HEALTHCHECK`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> Default: `true`
Enable healthcheck endpoint.
Change healtcheck port into address format, redo #1197 (#1423)
As discussed in the comments in PR #1197. Also add documenation
accordingly.
One thing I'm not sure about is the simple check in health.go if the
address is usable in the GET request or not. From reading
https://pkg.go.dev/net#Dial it seems that the only non-standard address
format that would work in the `net` package but not in a GET url would
likely only be `:port`, as the others listed here are actually also
valid urls:
`For TCP, UDP and IP networks, if the host is empty or a literal
unspecified IP address, as in ":80", "0.0.0.0:80" or "[::]:80" for TCP
and UDP, "", "0.0.0.0" or "::" for IP, the local system is assumed.`
One additional thing I noticed is that while `WOODPECKER_SERVER_ADDR`
and `WOODPECKER_SERVER_ADDR` use the default value format of `:PORT`,
`WOODPECKER_SERVER` actually uses `localhost:9000`. I guess it makes a
bit of sense, considering the server might not be local to the agent,
but it looks a bit inconsistent this way. I don't think it would hurt to
make the `WOODPECKER_HEALTHCHECK_ADDR` in this format too, but then it's
different from the server flags again... :-)
2022-11-19 11:06:51 +00:00
### `WOODPECKER_HEALTHCHECK_ADDR`
2023-10-24 12:42:05 +00:00
Change healtcheck port into address format, redo #1197 (#1423)
As discussed in the comments in PR #1197. Also add documenation
accordingly.
One thing I'm not sure about is the simple check in health.go if the
address is usable in the GET request or not. From reading
https://pkg.go.dev/net#Dial it seems that the only non-standard address
format that would work in the `net` package but not in a GET url would
likely only be `:port`, as the others listed here are actually also
valid urls:
`For TCP, UDP and IP networks, if the host is empty or a literal
unspecified IP address, as in ":80", "0.0.0.0:80" or "[::]:80" for TCP
and UDP, "", "0.0.0.0" or "::" for IP, the local system is assumed.`
One additional thing I noticed is that while `WOODPECKER_SERVER_ADDR`
and `WOODPECKER_SERVER_ADDR` use the default value format of `:PORT`,
`WOODPECKER_SERVER` actually uses `localhost:9000`. I guess it makes a
bit of sense, considering the server might not be local to the agent,
but it looks a bit inconsistent this way. I don't think it would hurt to
make the `WOODPECKER_HEALTHCHECK_ADDR` in this format too, but then it's
different from the server flags again... :-)
2022-11-19 11:06:51 +00:00
> Default: `:3000`
Configures healthcheck endpoint address.
2022-01-08 22:22:06 +00:00
### `WOODPECKER_KEEPALIVE_TIME`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> 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`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> 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`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> Default: `false`
Configures if the connection to `WOODPECKER_SERVER` should be made using a secure transport.
### `WOODPECKER_GRPC_VERIFY`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> Default: `true`
Configures if the gRPC server certificate should be verified, only valid when `WOODPECKER_GRPC_SECURE` is `true` .
### `WOODPECKER_BACKEND`
2023-10-24 12:42:05 +00:00
2022-01-08 22:22:06 +00:00
> Default: `auto-detect`
2023-10-23 23:55:30 +00:00
Configures the backend engine to run pipelines on. Possible values are `auto-detect` , `docker` , `local` or `kubernetes` .
2022-04-29 10:30:50 +00:00
2024-01-11 17:43:54 +00:00
### `WOODPECKER_ADDONS`
2023-12-20 13:26:57 +00:00
> Default: empty
List of addon files. See [addons ](./75-addons/00-overview.md ).
2022-04-29 13:15:32 +00:00
### `WOODPECKER_BACKEND_DOCKER_*`
2023-06-03 22:50:08 +00:00
See [Docker backend configuration ](./22-backends/10-docker.md#configuration )
2022-04-29 13:15:32 +00:00
2023-06-03 22:50:08 +00:00
### `WOODPECKER_BACKEND_K8S_*`
See [Kubernetes backend configuration ](./22-backends/40-kubernetes.md#configuration )
2023-05-03 11:31:29 +00:00
2023-11-02 14:45:18 +00:00
### `WOODPECKER_BACKEND_LOCAL_*`
See [Local backend configuration ](./22-backends/20-local.md#further-configuration )
2023-05-03 11:31:29 +00:00
## Advanced Settings
:::warning
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.