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
```yaml
# docker-compose.yml
version: '3'
services:
woodpecker-agent:
[...]
environment:
+ - 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
2022-10-28 15:38:53 +00:00
- WOODPECKER_MAX_WORKFLOWS if not set, defaults to 1
2021-11-20 19:45:59 +00:00
## Processes per agent
2022-10-28 15:38:53 +00:00
By default the maximum processes that are run per agent is 1. If required you can add `WOODPECKER_MAX_WORKFLOWS` to increase your parallel processing on a per-agent basis.
2021-11-20 19:45:59 +00:00
```yaml
# docker-compose.yml
version: '3'
services:
woodpecker-agent:
[...]
environment:
- WOODPECKER_SERVER=localhost:9000
- WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
2022-10-28 15:38:53 +00:00
+ - WOODPECKER_MAX_WORKFLOWS=4
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`
> 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` .
2022-03-01 15:09:33 +00:00
### `WOODPECKER_AGENT_SECRET_FILE`
> Default: empty
Read the value for `WOODPECKER_AGENT_SECRET` from the specified filepath
2022-01-08 22:22:06 +00:00
### `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.
2022-10-28 15:38:53 +00:00
### `WOODPECKER_MAX_WORKFLOWS`
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`
> Default: empty
2022-08-31 23:52:52 +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-pipeline-syntax.md#labels ).
2022-05-30 23:12:18 +00:00
2022-01-08 22:22:06 +00:00
### `WOODPECKER_HEALTHCHECK`
> 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`
> Default: `:3000`
Configures healthcheck endpoint address.
2022-01-08 22:22:06 +00:00
### `WOODPECKER_KEEPALIVE_TIME`
> 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`
> 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`
> Default: `false`
Configures if the connection to `WOODPECKER_SERVER` should be made using a secure transport.
### `WOODPECKER_GRPC_VERIFY`
> Default: `true`
Configures if the gRPC server certificate should be verified, only valid when `WOODPECKER_GRPC_SECURE` is `true` .
### `WOODPECKER_BACKEND`
> Default: `auto-detect`
2022-04-29 10:30:50 +00:00
Configures the backend engine to run pipelines on. Possible values are `auto-detect` , `docker` , `local` or `ssh` .
2022-04-29 13:15:32 +00:00
### `WOODPECKER_BACKEND_DOCKER_*`
See [Docker backend configuration ](backends/docker/#configuration )
2022-04-29 10:30:50 +00:00
### `WOODPECKER_BACKEND_SSH_*`
See [SSH backend configuration ](backends/ssh/#configuration )