woodpecker/docs/docs/30-administration/15-agent-config.md
Lukas Bachschwell 09e6460f95
Allow loading sensitive flags from files (#815)
With systems like docker swarm or docker compose it is usually a little awkward to manage secrets. 
There is no way to directly inject them into the environment config. So you often have to write your secrets directly into the compose file

There are hacky workarounds such as overriding the entry-point of the container and loading a script which then fetches secrets from /run/secrets and replaces the environment variables, but this becomes very difficult once we are using docker images built from "scratch" (which is a really great practice otherwise) as there is no shell or standard tooling available

This adds a *_FILE variant of their Environment config values to work around this issue.

Signed-off-by: Lukas Bachschwell <lukas@lbsfilm.at>
2022-03-01 16:09:33 +01:00

3.6 KiB

Agent configuration

Agents are configured by the command line or environement variables. At the minimum you need the following information:

# 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
  • WOODPECKER_MAX_PROCS if not set, defaults to 1

Processes per agent

By default the maximum processes that are run per agent is 1. If required you can add WOODPECKER_MAX_PROCS to increase your parellel processing on a per-agent basis.

# docker-compose.yml
version: '3'

services:
  woodpecker-agent:
  [...]
  environment:
    - WOODPECKER_SERVER=localhost:9000
    - WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
+    - WOODPECKER_MAX_PROCS=4

Filtering agents

When building your pipelines as long as you have set the platform or filter, builds can be made to only run code on certain agents.

- WOODPECKER_HOSTNAME=mycompany-ci-01.example.com
- WOODPECKER_FILTER=

Filter on Platform

Only want certain pipelines or steps to run on certain agents with specific platforms? Such as arm vs amd64?

# .woodpecker.yml
pipeline:
  build:
   image: golang
   commands:
     - go build
     - go test
  when:
    platform: linux/amd64


  testing:
   image: golang
   commands:
     - go build
     - go test
  when:
    platform: linux/arm*


See Conditionals Pipeline syntax for more

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

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_MAX_PROCS

Default: 1

Configures the number of parallel builds.

WOODPECKER_HEALTHCHECK

Default: true

Enable healthcheck endpoint.

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

Configures the backend engine to run pipelines on. Possible values are auto-detect or docker.