Server configuration
User registrationโ
Registration is closed by default. While disabled an administrator needs to add new users manually (exp. woodpecker-cli user add
).
If registration is open every user with an account at the configured forges can login to Woodpecker. This example enables open registration for users that are members of approved organizations:
# docker-compose.yml
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_OPEN=true
+ - WOODPECKER_ORGS=dolores,dogpatch
Administratorsโ
Administrators should also be enumerated in your configuration.
# docker-compose.yml
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_ADMIN=johnsmith,janedoe
Filtering repositoriesโ
Woodpecker operates with the user's OAuth permission. Due to the coarse permission handling of GitHub, you may end up syncing more repos into Woodpecker than preferred.
Use the WOODPECKER_REPO_OWNERS
variable to filter which GitHub user's repos should be synced only. You typically want to put here your company's GitHub name.
# docker-compose.yml
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_REPO_OWNERS=mycompany,mycompanyossgithubuser
Global registry settingโ
If you want to make available a specific private registry to all pipelines, use the WOODPECKER_DOCKER_CONFIG
server configuration.
Point it to your server's docker config.
# docker-compose.yml
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json
Handling sensitive data in docker-compose and docker-swarmโ
To handle sensitive data in docker-compose or docker-swarm configurations there are several options:
For docker-compose you can use a .env file next to your compose configuration to store the secrets outside of the compose file. While this separates configuration from secrets it is still not very secure.
Alternatively use docker-secrets. As it may be difficult to use docker secrets for environment variables woodpecker allows to read sensible data from files by providing a *_FILE
option of all sensible configuration variables. Woodpecker will try to read the value directly from this file. Keep in mind that when the original environment variable gets specified at the same time it will override the value read from the file.
# docker-compose.yml
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_AGENT_SECRET_FILE=/run/secrets/woodpecker-agent-secret
+ secrets:
+ - woodpecker-agent-secret
+
+secrets:
+ woodpecker-agent-secret:
+ external: true
Store a value to a docker secret like this:
echo "my_agent_secret_key" | docker secret create woodpecker-agent-secret -
or generate a random one like this:
openssl rand -hex 32 | docker secret create woodpecker-agent-secret -
All server configuration optionsโ
The following list describes all available server configuration options.
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_HOST
โ
Default: empty
Server fully qualified URL of the user-facing hostname.
Example: WOODPECKER_HOST=http://woodpecker.example.org
WOODPECKER_SERVER_ADDR
โ
Default:
:8000
Configures the HTTP listener port.
WOODPECKER_SERVER_CERT
โ
Default: empty
Path to an SSL certificate used by the server to accept HTTPS requests.
Example: WOODPECKER_SERVER_CERT=/path/to/cert.pem
WOODPECKER_SERVER_KEY
โ
Default: empty
Path to an SSL certificate key used by the server to accept HTTPS requests.
Example: WOODPECKER_SERVER_KEY=/path/to/key.pem
WOODPECKER_LETS_ENCRYPT
โ
Default:
false
Automatically generates an SSL certificate using Let's Encrypt, and configures the server to accept HTTPS requests.
WOODPECKER_GRPC_ADDR
โ
Default:
:9000
Configures the gRPC listener port.
WOODPECKER_GRPC_SECRET
โ
Default:
secret
Configures the gRPC JWT secret.
WOODPECKER_METRICS_SERVER_ADDR
โ
Default: empty
Configures an unprotected metrics endpoint. An empty value disables the metrics endpoint completely.
Example: :9001
WOODPECKER_ADMIN
โ
Default: empty
Comma-separated list of admin accounts.
Example: WOODPECKER_ADMIN=user1,user2
WOODPECKER_ORGS
โ
Default: empty
Comma-separated list of approved organizations.
Example: org1,org2
WOODPECKER_REPO_OWNERS
โ
Default: empty
Comma-separated list of syncable repo owners. ???
Example: user1,user2
WOODPECKER_OPEN
โ
Default:
false
Enable to allow user registration.
WOODPECKER_DOCS
โ
Default:
https://woodpecker-ci.org/
Link to documentation in the UI.
WOODPECKER_AUTHENTICATE_PUBLIC_REPOS
โ
Default:
false
Always use authentication to clone repositories even if they are public. Needed if the forge requires to always authenticate as used by many companies.
WOODPECKER_DEFAULT_CANCEL_PREVIOUS_PIPELINE_EVENTS
โ
Default:
pull_request, push
List of event names that will be canceled when a new pipeline for the same context (tag, branch) is created.
WOODPECKER_DEFAULT_CLONE_IMAGE
โ
Default is defined in shared/constant/constant.go
The default docker image to be used when cloning the repo
WOODPECKER_DEFAULT_PIPELINE_TIMEOUT
โ
60 (minutes)
The default time for a repo in minutes before a pipeline gets killed
WOODPECKER_MAX_PIPELINE_TIMEOUT
โ
120 (minutes)
The maximum time in minutes you can set in the repo settings before a pipeline gets killed
WOODPECKER_SESSION_EXPIRES
โ
Default:
72h
Configures the session expiration time.
WOODPECKER_ESCALATE
โ
Defaults are defined in shared/constant/constant.go
Docker images to run in privileged mode. Only change if you are sure what you do!
WOODPECKER_DOCKER_CONFIG
โ
Default: empty
Configures a specific private registry config for all pipelines.
Example: WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json
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_KEEPALIVE_MIN_TIME
โ
Default: empty
Server-side enforcement policy on the minimum amount of time a client should wait before sending a keepalive ping.
Example: WOODPECKER_KEEPALIVE_MIN_TIME=10s
WOODPECKER_DATABASE_DRIVER
โ
Default:
sqlite3
The database driver name. Possible values are sqlite3
, mysql
or postgres
.
WOODPECKER_DATABASE_DATASOURCE
โ
Default:
woodpecker.sqlite
The database connection string. The default value is the path of the embedded SQLite database file.
Example:
# MySQL
# https://github.com/go-sql-driver/mysql#dsn-data-source-name
WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true
# PostgreSQL
# https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING
WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker?sslmode=disable
WOODPECKER_DATABASE_DATASOURCE_FILE
โ
Default: empty
Read the value for WOODPECKER_DATABASE_DATASOURCE
from the specified filepath
WOODPECKER_ENCRYPTION_KEY
โ
Default: empty
Encryption key used to encrypt secrets in DB. See secrets encryption
WOODPECKER_ENCRYPTION_KEY_FILE
โ
Default: empty
Read the value for WOODPECKER_ENCRYPTION_KEY
from the specified filepath
WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE
โ
Default: empty
Filepath to encryption keyset used to encrypt secrets in DB. See secrets encryption
WOODPECKER_ENCRYPTION_DISABLE
โ
Default: empty
Boolean flag to decrypt secrets in DB and disable server encryption. See secrets encryption
WOODPECKER_PROMETHEUS_AUTH_TOKEN
โ
Default: empty
Token to secure the Prometheus metrics endpoint. Must be set to enable the endpoint.
WOODPECKER_PROMETHEUS_AUTH_TOKEN_FILE
โ
Default: empty
Read the value for WOODPECKER_PROMETHEUS_AUTH_TOKEN
from the specified filepath
WOODPECKER_STATUS_CONTEXT
โ
Default:
ci/woodpecker
Context prefix Woodpecker will use to publish status messages to SCM. You probably will only need to change it if you run multiple Woodpecker instances for a single repository.
WOODPECKER_STATUS_CONTEXT_FORMAT
โ
Default:
{{ .context }}/{{ .event }}/{{ .pipeline }}
Template for the status messages published to forges, uses Go templates as template language. Supported variables:
context
: Woodpecker's context (seeWOODPECKER_STATUS_CONTEXT
)event
: the event which started the pipelinepipeline
: the pipeline's nameowner
: the repo's ownerrepo
: the repo's name
WOODPECKER_LIMIT_MEM_SWAP
โ
Default:
0
The maximum amount of memory a single pipeline container is allowed to swap to disk, configured in bytes. There is no limit if 0
.
WOODPECKER_LIMIT_MEM
โ
Default:
0
The maximum amount of memory a single pipeline container can use, configured in bytes. There is no limit if 0
.
WOODPECKER_LIMIT_SHM_SIZE
โ
Default:
0
The maximum amount of memory of /dev/shm
allowed in bytes. There is no limit if 0
.
WOODPECKER_LIMIT_CPU_QUOTA
โ
Default:
0
The number of microseconds per CPU period that the container is limited to before throttled. There is no limit if 0
.
WOODPECKER_LIMIT_CPU_SHARES
โ
Default:
0
The relative weight vs. other containers.
WOODPECKER_LIMIT_CPU_SET
โ
Default: empty
Comma-separated list to limit the specific CPUs or cores a pipeline container can use.
Example: WOODPECKER_LIMIT_CPU_SET=1,2
WOODPECKER_CONFIG_SERVICE_ENDPOINT
โ
Default: ``
Specify a configuration service endpoint, see Configuration Extension
WOODPECKER_FORGE_TIMEOUT
โ
Default: 3sec
Specify how many seconds before timeout when fetching the Woodpecker configuration from a Forge
WOODPECKER_GITHUB_...
โ
WOODPECKER_GOGS_...
โ
WOODPECKER_GITEA_...
โ
WOODPECKER_BITBUCKET_...
โ
WOODPECKER_STASH_...
โ
See Bitbucket server configuration