Server configuration
User registrationโ
Woodpecker does not have its own user registry; users are provided from your forge (using OAuth2).
Registration is closed by default (WOODPECKER_OPEN=false
). If registration is open (WOODPECKER_OPEN=true
) then every user with an account at the configured forge can login to Woodpecker.
To open registration:
WOODPECKER_OPEN=true
You can also restrict registration, by keep registration closed and:
- adding new users manually via the CLI:
woodpecker-cli user add
- allowing specific admin users via the
WOODPECKER_ADMIN
setting - by open registration and filter by organization membership through the
WOODPECKER_ORGS
setting
Close registration, but allow specific admin usersโ
WOODPECKER_OPEN=false
WOODPECKER_ADMIN=john.smith,jane_doe
Only allow registration of users, who are members of approved organizationsโ
WOODPECKER_OPEN=true
WOODPECKER_ORGS=dolores,dog-patch
Administratorsโ
Administrators should also be enumerated in your configuration.
WOODPECKER_ADMIN=john.smith,jane_doe
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.
WOODPECKER_REPO_OWNERS=my_company,my_company_oss_github_user
Disallow normal users to create agentsโ
By default, users can create new agents for their repos they have admin access to. If an instance admin doesn't want this feature enabled, they can disable the API and hide the Web UI elements.
You should set this option if you have, for example, global secrets and don't trust your users to create a rogue agent and pipeline for secret extraction.
WOODPECKER_DISABLE_USER_AGENT_REGISTRATION=true
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.
WOODPECKER_DOCKER_CONFIG=/root/.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.
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 -
Custom JavaScript and CSSโ
Woodpecker supports custom JS and CSS files. These files must be present in the server's filesystem. They can be backed in a Docker image or mounted from a ConfigMap inside a Kubernetes environment. The configuration variables are independent of each other, which means it can be just one file present, or both.
WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.css
WOODPECKER_CUSTOM_JS_FILE=/usr/local/www/woodpecker.js
The examples below show how to place a banner message in the top navigation bar of Woodpecker.
woodpecker.css
โ
.banner-message {
position: absolute;
width: 280px;
height: 40px;
margin-left: 240px;
margin-top: 5px;
padding-top: 5px;
font-weight: bold;
background: red no-repeat;
text-align: center;
}
woodpecker.js
โ
// place/copy a minified version of your preferred lightweight JavaScript library here ...
!(function () {
'use strict';
function e() {} /*...*/
})();
$().ready(function () {
$('.app nav img').first().htmlAfter("<div class='banner-message'>This is a demo banner message :)</div>");
});
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_LOG_FILE
โ
Default:
stderr
Output destination for logs. 'stdout' and 'stderr' can be used as special keywords.
WOODPECKER_DATABASE_LOG
โ
Default:
false
Enable logging in database engine (currently xorm).
WOODPECKER_DATABASE_LOG_SQL
โ
Default:
false
Enable logging of sql commands.
WOODPECKER_DATABASE_MAX_CONNECTIONS
โ
Default:
100
Max database connections xorm is allowed create.
WOODPECKER_DATABASE_IDLE_CONNECTIONS
โ
Default:
2
Amount of database connections xorm will hold open.
WOODPECKER_DATABASE_CONNECTION_TIMEOUT
โ
Default:
3 Seconds
Time an active database connection is allowed to stay open.
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, port (if not default for HTTP/HTTPS) and path prefix.
Examples:
WOODPECKER_HOST=http://woodpecker.example.org
WOODPECKER_HOST=http://example.org/woodpecker
WOODPECKER_HOST=http://example.org:1234/woodpecker
WOODPECKER_SERVER_ADDR
โ
Default:
:8000
Configures the HTTP listener port.
WOODPECKER_SERVER_ADDR_TLS
โ
Default:
:443
Configures the HTTPS listener port when SSL is enabled.
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_CUSTOM_CSS_FILE
โ
Default: empty
File path for the server to serve a custom .CSS file, used for customizing the UI. Can be used for showing banner messages, logos, or environment-specific hints (a.k.a. white-labeling). The file must be UTF-8 encoded, to ensure all special characters are preserved.
Example: WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.css
WOODPECKER_CUSTOM_JS_FILE
โ
Default: empty
File path for the server to serve a custom .JS file, used for customizing the UI. Can be used for showing banner messages, logos, or environment-specific hints (a.k.a. white-labeling). The file must be UTF-8 encoded, to ensure all special characters are preserved.
Example: WOODPECKER_CUSTOM_JS_FILE=/usr/local/www/woodpecker.js
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_GRPC_SECRET_FILE
โ
Default: empty
Read the value for WOODPECKER_GRPC_SECRET
from the specified filepath.
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
Repositories by those owners will be allowed to be used in woodpecker.
Example: user1,user2
WOODPECKER_OPEN
โ
Default:
false
Enable to allow user registration.
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_PLUGIN
โ
Default is defined in shared/constant/constant.go
The default docker image to be used when cloning the repo.
It is also added to the trusted clone plugin list.
WOODPECKER_DEFAULT_WORKFLOW_LABELS
โ
By default run workflows on any agent if no label conditions are set in workflow definition.
You can specify default label/platform conditions that will be used for agent selection for workflows that does not have labels conditions set.
Example: platform=linux/amd64,backend=docker
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. Context: when someone does log into Woodpecker, a temporary session token is created. As long as the session is valid (until it expires or log-out), a user can log into Woodpecker, without re-authentication.
WOODPECKER_PLUGINS_PRIVILEGED
โ
Docker images to run in privileged mode. Only change if you are sure what you do!
You should specify the tag of your images too, as this enforces exact matches.
WOODPECKER_PLUGINS_TRUSTED_CLONEโ
Defaults are defined in shared/constant/constant.go
Plugins which are trusted to handle the Git credential info in clone steps. If a clone step use an image not in this list, Git credentials will not be injected and users have to use other methods (e.g. secrets) to clone non-public repos.
You should specify the tag of your images too, as this enforces exact matches.
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_DISABLE_USER_AGENT_REGISTRATION
โ
Default: false
Read about "Disallow normal users to create agents"
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
if not running inside a container,/var/lib/woodpecker/woodpecker.sqlite
if running inside a container
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_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 }}/{{ .workflow }}{{if not (eq .axis_id 0)}}/{{.axis_id}}{{end}}
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 pipelineworkflow
: the workflow's nameowner
: the repo's ownerrepo
: the repo's name
WOODPECKER_CONFIG_SERVICE_ENDPOINT
โ
Default: empty
Specify a configuration service endpoint, see Configuration Extension
WOODPECKER_FORGE_TIMEOUT
โ
Default: 5s
Specify timeout when fetching the Woodpecker configuration from forge. See https://pkg.go.dev/time#ParseDuration for syntax reference.
WOODPECKER_FORGE_RETRY
โ
Default: 3
Specify how many retries of fetching the Woodpecker configuration from a forge are done before we fail.
WOODPECKER_ENABLE_SWAGGER
โ
Default: true
Enable the Swagger UI for API documentation.
WOODPECKER_DISABLE_VERSION_CHECK
โ
Default: false
Disable version check in admin web UI.
WOODPECKER_LOG_STORE
โ
Default:
database
Where to store logs. Possible values: database
or file
.
WOODPECKER_LOG_STORE_FILE_PATH
โ
Default empty
Directory to store logs in if WOODPECKER_LOG_STORE
is file
.
WOODPECKER_GITHUB_...
โ
WOODPECKER_GITEA_...
โ
WOODPECKER_BITBUCKET_...
โ
WOODPECKER_GITLAB_...
โ
WOODPECKER_ADDON_FORGE
โ
See addon forges.