跳到主要内容

服务器

代码托管平台和用户配置​

Woodpecker 没有自己的用户注册。用户由您的代码托管平台提供（使用 OAuth2）。默认情况下注册是关闭的 (WOODPECKER_OPEN=false)。如果注册是开放的，任何有账户的用户都可以使用配置的代码托管平台登录到 Woodpecker。

您也可以限制注册：

  • 关闭注册并使用 CLI woodpecker-cli user 手动管理用户

  • 开放注册并使用设置 WOODPECKER_ADMIN 允许某些管理员用户

    WOODPECKER_OPEN=false
    WOODPECKER_ADMIN=john.smith,jane_doe

  • 开放注册并使用设置 WOODPECKER_ORGS 按组织归属过滤

    WOODPECKER_OPEN=true
    WOODPECKER_ORGS=dolores,dog-patch

管理员也应该在您的配置中明确设置。

WOODPECKER_ADMIN=john.smith,jane_doe

仓库配置​

Woodpecker 与用户在代码托管平台上的 OAuth 权限一起工作。默认情况下 Woodpecker 将同步用户有权访问的所有仓库。使用变量 WOODPECKER_REPO_OWNERS 来过滤哪些仓库应该仅由 GitHub 用户同步。通常您应该在此处输入您公司的 GitHub 名称。

WOODPECKER_REPO_OWNERS=my_company,my_company_oss_github_user

数据库​

Woodpecker 的默认数据库引擎是嵌入式 SQLite 数据库，不需要安装或配置。但您可以用 MySQL/MariaDB 或 PostgreSQL 数据库替换它。还有一些基本原则需要记住：

  • Woodpecker 不会自动创建您的数据库。如果您使用 MySQL 或 Postgres 驱动程序，您需要使用 CREATE DATABASE 手动创建数据库。

  • Woodpecker 不执行数据归档；这被认为是超出项目范围的。Woodpecker 对存储的数据量相当保守，但是，您应该预期数据库日志会大大增加数据库的大小。

  • Woodpecker 自动处理数据库迁移，包括初始表和索引的创建。新版本的 Woodpecker 将自动升级数据库，除非发行说明中另有说明。

  • Woodpecker 不执行数据库备份。这应该由您选择的数据库供应商提供的单独第三方工具处理。

SQLite​

默认情况下，Woodpecker 使用存储在 /var/lib/woodpecker/ 下的 SQLite 数据库。如果使用容器，您可以挂载 数据卷 来持久化 SQLite 数据库。

docker-compose.yaml
 services:
   woodpecker-server:
     [...]
+    volumes:
+      - woodpecker-server-data:/var/lib/woodpecker/

MySQL/MariaDB​

以下示例演示了 MySQL 数据库配置。有关配置选项和示例，请参阅官方驱动程序 文档。 MySQL/MariaDB 所需的最低版本由 go-sql-driver/mysql 决定 - 有关更多信息，请参阅 其 README。

WOODPECKER_DATABASE_DRIVER=mysql
WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true

PostgreSQL​

以下示例演示了 Postgres 数据库配置。有关配置选项和示例，请参阅官方驱动程序 文档。 请使用 11 或更高版本的 Postgres。

WOODPECKER_DATABASE_DRIVER=postgres
WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/postgres?sslmode=disable

TLS​

Woodpecker supports SSL configuration by mounting certificates into your container.

WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key

TLS support is provided using the ListenAndServeTLS function from the Go standard library.

Container configuration​

In addition to the ports shown in the docker-compose installation, port 443 must be exposed:

docker-compose.yaml
 services:
   woodpecker-server:
     [...]
     ports:
+      - 80:80
+      - 443:443
       - 9000:9000

Additionally, the certificate and key must be mounted and referenced:

docker-compose.yaml
 services:
   woodpecker-server:
     [...]
     environment:
+      - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
+      - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key
     volumes:
+      - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt
+      - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key

Reverse Proxy​

Apache​

This guide provides a brief overview for installing Woodpecker server behind the Apache2 web-server. This is an example configuration:

ProxyPreserveHost On

RequestHeader set X-Forwarded-Proto "https"

ProxyPass / http://127.0.0.1:8000/
ProxyPassReverse / http://127.0.0.1:8000/

You must have these Apache modules installed:

  • proxy
  • proxy_http

You must configure Apache to set X-Forwarded-Proto when using https.

 ProxyPreserveHost On

+RequestHeader set X-Forwarded-Proto "https"

 ProxyPass / http://127.0.0.1:8000/
 ProxyPassReverse / http://127.0.0.1:8000/

Nginx​

This guide provides a basic overview for installing Woodpecker server behind the Nginx web-server. For more advanced configuration options please consult the official Nginx documentation.

Example configuration:

server {
    listen 80;
    server_name woodpecker.example.com;

    location / {
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;

        proxy_pass http://127.0.0.1:8000;
        proxy_redirect off;
        proxy_http_version 1.1;
        proxy_buffering off;

        chunked_transfer_encoding off;
    }
}

You must configure the proxy to set X-Forwarded proxy headers:

 server {
     listen 80;
     server_name woodpecker.example.com;

     location / {
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;

         proxy_pass http://127.0.0.1:8000;
         proxy_redirect off;
         proxy_http_version 1.1;
         proxy_buffering off;

         chunked_transfer_encoding off;
     }
 }

Caddy​

This guide provides a brief overview for installing Woodpecker server behind the Caddy web-server. This is an example caddyfile proxy configuration:

# expose WebUI and API
woodpecker.example.com {
  reverse_proxy woodpecker-server:8000
}

# expose gRPC
woodpecker-agent.example.com {
  reverse_proxy h2c://woodpecker-server:9000
}

Tunnelmole​

Tunnelmole is an open source tunneling tool.

Start by installing tunnelmole.

After the installation, run the following command to start tunnelmole:

tmole 8000

It will start a tunnel and will give a response like this:

➜  ~ tmole 8000
http://bvdo5f-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:8000
https://bvdo5f-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:8000

Set WOODPECKER_HOST to the Tunnelmole URL (xxx.tunnelmole.net) and start the server.

Ngrok​

Ngrok is a popular closed source tunnelling tool. After installing ngrok, open a new console and run the following command:

ngrok http 8000

Set WOODPECKER_HOST to the ngrok URL (usually xxx.ngrok.io) and start the server.

Traefik​

To install the Woodpecker server behind a Traefik load balancer, you must expose both the http and the gRPC ports. Here is a comprehensive example, considering you are running Traefik with docker swarm and want to do TLS termination and automatic redirection from http to https.

services:
  server:
    image: woodpeckerci/woodpecker-server:latest
    environment:
      - WOODPECKER_OPEN=true
      - WOODPECKER_ADMIN=your_admin_user
      # other settings ...

    networks:
      - dmz # externally defined network, so that traefik can connect to the server
    volumes:
      - woodpecker-server-data:/var/lib/woodpecker/

    deploy:
      labels:
        - traefik.enable=true

        # web server
        - traefik.http.services.woodpecker-service.loadbalancer.server.port=8000

        - traefik.http.routers.woodpecker-secure.rule=Host(`ci.example.com`)
        - traefik.http.routers.woodpecker-secure.tls=true
        - traefik.http.routers.woodpecker-secure.tls.certresolver=letsencrypt
        - traefik.http.routers.woodpecker-secure.entrypoints=web-secure
        - traefik.http.routers.woodpecker-secure.service=woodpecker-service

        - traefik.http.routers.woodpecker.rule=Host(`ci.example.com`)
        - traefik.http.routers.woodpecker.entrypoints=web
        - traefik.http.routers.woodpecker.service=woodpecker-service

        - traefik.http.middlewares.woodpecker-redirect.redirectscheme.scheme=https
        - traefik.http.middlewares.woodpecker-redirect.redirectscheme.permanent=true
        - traefik.http.routers.woodpecker.middlewares=woodpecker-redirect@docker

        #  gRPC service
        - traefik.http.services.woodpecker-grpc.loadbalancer.server.port=9000
        - traefik.http.services.woodpecker-grpc.loadbalancer.server.scheme=h2c

        - traefik.http.routers.woodpecker-grpc-secure.rule=Host(`woodpecker-grpc.example.com`)
        - traefik.http.routers.woodpecker-grpc-secure.tls=true
        - traefik.http.routers.woodpecker-grpc-secure.tls.certresolver=letsencrypt
        - traefik.http.routers.woodpecker-grpc-secure.entrypoints=web-secure
        - traefik.http.routers.woodpecker-grpc-secure.service=woodpecker-grpc

        - traefik.http.routers.woodpecker-grpc.rule=Host(`woodpecker-grpc.example.com`)
        - traefik.http.routers.woodpecker-grpc.entrypoints=web
        - traefik.http.routers.woodpecker-grpc.service=woodpecker-grpc

        - traefik.http.middlewares.woodpecker-grpc-redirect.redirectscheme.scheme=https
        - traefik.http.middlewares.woodpecker-grpc-redirect.redirectscheme.permanent=true
        - traefik.http.routers.woodpecker-grpc.middlewares=woodpecker-grpc-redirect@docker

volumes:
  woodpecker-server-data:
    driver: local

networks:
  dmz:
    external: true

指标​

端点​

Woodpecker 与 Prometheus 兼容，如果设置了环境变量 WOODPECKER_PROMETHEUS_AUTH_TOKEN，则会暴露 /metrics 端点。请注意，对指标端点的访问是受限制的，需要上述环境变量中的授权令牌。

global:
  scrape_interval: 60s

scrape_configs:
  - job_name: 'woodpecker'
    bearer_token: dummyToken...

    static_configs:
      - targets: ['woodpecker.domain.com']

授权​

管理员需要生成用户 API 令牌并在 Prometheus 配置文件中配置为 bearer 令牌。请参阅以下示例：

 global:
   scrape_interval: 60s

 scrape_configs:
   - job_name: 'woodpecker'
+    bearer_token: dummyToken...

     static_configs:
        - targets: ['woodpecker.domain.com']

或者，令牌也可以从文件中读取：

 global:
   scrape_interval: 60s

 scrape_configs:
   - job_name: 'woodpecker'
+    bearer_token_file: /etc/secrets/woodpecker-monitoring-token

     static_configs:
        - targets: ['woodpecker.domain.com']

参考​

Woodpecker 特定的 Prometheus 指标列表：

# HELP woodpecker_pipeline_count 管道计数。
# TYPE woodpecker_pipeline_count counter
woodpecker_pipeline_count{branch="main",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3
woodpecker_pipeline_count{branch="dev",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3
# HELP woodpecker_pipeline_time 构建时间。
# TYPE woodpecker_pipeline_time gauge
woodpecker_pipeline_time{branch="main",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 116
woodpecker_pipeline_time{branch="dev",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 155
# HELP woodpecker_pipeline_total_count 构建总数。
# TYPE woodpecker_pipeline_total_count gauge
woodpecker_pipeline_total_count 1025
# HELP woodpecker_pending_steps 待处理管道步骤总数。
# TYPE woodpecker_pending_steps gauge
woodpecker_pending_steps 0
# HELP woodpecker_repo_count 仓库总数。
# TYPE woodpecker_repo_count gauge
woodpecker_repo_count 9
# HELP woodpecker_running_steps 运行中的管道步骤总数。
# TYPE woodpecker_running_steps gauge
woodpecker_running_steps 0
# HELP woodpecker_user_count 用户总数。
# TYPE woodpecker_user_count gauge
woodpecker_user_count 1
# HELP woodpecker_waiting_steps 等待依赖的管道总数。
# TYPE woodpecker_waiting_steps gauge
woodpecker_waiting_steps 0
# HELP woodpecker_worker_count Total number of workers.
# TYPE woodpecker_worker_count gauge
woodpecker_worker_count 4

External Configuration API​

To provide additional management and preprocessing capabilities for pipeline configurations Woodpecker supports an HTTP API which can be enabled to call an external config service. Before the run or restart of any pipeline Woodpecker will make a POST request to an external HTTP API sending the current repository, build information and all current config files retrieved from the repository. The external API can then send back new pipeline configurations that will be used immediately or respond with HTTP 204 to tell the system to use the existing configuration.

Every request sent by Woodpecker is signed using a http-signature by a private key (ed25519) generated on the first start of the Woodpecker server. You can get the public key for the verification of the http-signature from http(s)://your-woodpecker-server/api/signature/public-key.

A simplistic example configuration service can be found here: https://github.com/woodpecker-ci/example-config-service

注意

You need to trust the external config service as it is getting secret information about the repository and pipeline and has the ability to change pipeline configs that could run malicious tasks.

Configuration​

Server
WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig

Example request made by Woodpecker​

{
  "repo": {
    "id": 100,
    "uid": "",
    "user_id": 0,
    "namespace": "",
    "name": "woodpecker-test-pipe",
    "slug": "",
    "scm": "git",
    "git_http_url": "",
    "git_ssh_url": "",
    "link": "",
    "default_branch": "",
    "private": true,
    "visibility": "private",
    "active": true,
    "config": "",
    "trusted": false,
    "protected": false,
    "ignore_forks": false,
    "ignore_pulls": false,
    "cancel_pulls": false,
    "timeout": 60,
    "counter": 0,
    "synced": 0,
    "created": 0,
    "updated": 0,
    "version": 0
  },
  "pipeline": {
    "author": "myUser",
    "author_avatar": "https://myforge.com/avatars/d6b3f7787a685fcdf2a44e2c685c7e03",
    "author_email": "my@email.com",
    "branch": "main",
    "changed_files": ["some-file-name.txt"],
    "commit": "2fff90f8d288a4640e90f05049fe30e61a14fd50",
    "created_at": 0,
    "deploy_to": "",
    "enqueued_at": 0,
    "error": "",
    "event": "push",
    "finished_at": 0,
    "id": 0,
    "link_url": "https://myforge.com/myUser/woodpecker-testpipe/commit/2fff90f8d288a4640e90f05049fe30e61a14fd50",
    "message": "test old config\n",
    "number": 0,
    "parent": 0,
    "ref": "refs/heads/main",
    "refspec": "",
    "clone_url": "",
    "reviewed_at": 0,
    "reviewed_by": "",
    "sender": "myUser",
    "signed": false,
    "started_at": 0,
    "status": "",
    "timestamp": 1645962783,
    "title": "",
    "updated_at": 0,
    "verified": false
  },
  "netrc": {
    "machine": "https://example.com",
    "login": "user",
    "password": "password"
  }
}

Example response structure​

{
  "configs": [
    {
      "name": "central-override",
      "data": "steps:\n  - name: backend\n    image: alpine\n    commands:\n      - echo \"Hello there from ConfigAPI\"\n"
    }
  ]
}

UI customization​

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>");
});

Environment variables​

LOG_LEVEL​

  • Name: WOODPECKER_LOG_LEVEL
  • Default: info

Configures the logging level. Possible values are trace, debug, info, warn, error, fatal, panic, disabled and empty.

LOG_FILE​

  • Name: WOODPECKER_LOG_FILE
  • Default: stderr

Output destination for logs. 'stdout' and 'stderr' can be used as special keywords.

DATABASE_LOG​

  • Name: WOODPECKER_DATABASE_LOG
  • Default: false

Enable logging in database engine (currently xorm).

DATABASE_LOG_SQL​

  • Name: WOODPECKER_DATABASE_LOG_SQL
  • Default: false

Enable logging of sql commands.

DATABASE_MAX_CONNECTIONS​

  • Name: WOODPECKER_DATABASE_MAX_CONNECTIONS
  • Default: 100

Max database connections xorm is allowed create.

DATABASE_IDLE_CONNECTIONS​

  • Name: WOODPECKER_DATABASE_IDLE_CONNECTIONS
  • Default: 2

Amount of database connections xorm will hold open.

DATABASE_CONNECTION_TIMEOUT​

  • Name: WOODPECKER_DATABASE_CONNECTION_TIMEOUT
  • Default: 3 Seconds

Time an active database connection is allowed to stay open.

DEBUG_PRETTY​

  • Name: WOODPECKER_DEBUG_PRETTY
  • Default: false

Enable pretty-printed debug output.

DEBUG_NOCOLOR​

  • Name: WOODPECKER_DEBUG_NOCOLOR
  • Default: true

Disable colored debug output.

HOST​

  • Name: WOODPECKER_HOST
  • Default: none

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

SERVER_ADDR​

  • Name: WOODPECKER_SERVER_ADDR
  • Default: :8000

Configures the HTTP listener port.

SERVER_ADDR_TLS​

  • Name: WOODPECKER_SERVER_ADDR_TLS
  • Default: :443

Configures the HTTPS listener port when SSL is enabled.

SERVER_CERT​

  • Name: WOODPECKER_SERVER_CERT
  • Default: none

Path to an SSL certificate used by the server to accept HTTPS requests.

Example: WOODPECKER_SERVER_CERT=/path/to/cert.pem

SERVER_KEY​

  • Name: WOODPECKER_SERVER_KEY
  • Default: none

Path to an SSL certificate key used by the server to accept HTTPS requests.

Example: WOODPECKER_SERVER_KEY=/path/to/key.pem

CUSTOM_CSS_FILE​

  • Name: WOODPECKER_CUSTOM_CSS_FILE
  • Default: none

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

CUSTOM_JS_FILE​

  • Name: WOODPECKER_CUSTOM_JS_FILE
  • Default: none

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

GRPC_ADDR​

  • Name: WOODPECKER_GRPC_ADDR
  • Default: :9000

Configures the gRPC listener port.

GRPC_SECRET​

  • Name: WOODPECKER_GRPC_SECRET
  • Default: secret

Configures the gRPC JWT secret.

GRPC_SECRET_FILE​

  • Name: WOODPECKER_GRPC_SECRET_FILE
  • Default: none

Read the value for WOODPECKER_GRPC_SECRET from the specified filepath.

METRICS_SERVER_ADDR​

  • Name: WOODPECKER_METRICS_SERVER_ADDR
  • Default: none

Configures an unprotected metrics endpoint. An empty value disables the metrics endpoint completely.

Example: :9001

ADMIN​

  • Name: WOODPECKER_ADMIN
  • Default: none

Comma-separated list of admin accounts.

Example: WOODPECKER_ADMIN=user1,user2

ORGS​

  • Name: WOODPECKER_ORGS
  • Default: none

Comma-separated list of approved organizations.

Example: org1,org2

REPO_OWNERS​

  • Name: WOODPECKER_REPO_OWNERS
  • Default: none

Repositories by those owners will be allowed to be used in woodpecker.

Example: user1,user2

OPEN​

  • Name: WOODPECKER_OPEN
  • Default: false

Enable to allow user registration.

AUTHENTICATE_PUBLIC_REPOS​

  • Name: 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.

DEFAULT_ALLOW_PULL_REQUESTS​

  • Name: WOODPECKER_DEFAULT_ALLOW_PULL_REQUESTS
  • Default: true

The default setting for allowing pull requests on a repo.

DEFAULT_CANCEL_PREVIOUS_PIPELINE_EVENTS​

  • Name: 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.

DEFAULT_CLONE_PLUGIN​

  • Name: WOODPECKER_DEFAULT_CLONE_PLUGIN
  • Default: docker.io/woodpeckerci/plugin-git

The default docker image to be used when cloning the repo.

It is also added to the trusted clone plugin list.

DEFAULT_WORKFLOW_LABELS​

  • Name: WOODPECKER_DEFAULT_WORKFLOW_LABELS
  • Default: none

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

DEFAULT_PIPELINE_TIMEOUT​

  • Name: WOODPECKER_DEFAULT_PIPELINE_TIMEOUT
  • Default: 60

The default time for a repo in minutes before a pipeline gets killed

MAX_PIPELINE_TIMEOUT​

  • Name: WOODPECKER_MAX_PIPELINE_TIMEOUT
  • Default: 120

The maximum time in minutes you can set in the repo settings before a pipeline gets killed

SESSION_EXPIRES​

  • Name: 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.

PLUGINS_PRIVILEGED​

  • Name: WOODPECKER_PLUGINS_PRIVILEGED
  • Default: none

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.

PLUGINS_TRUSTED_CLONE​

  • Name: WOODPECKER_PLUGINS_TRUSTED_CLONE
  • Default: docker.io/woodpeckerci/plugin-git,docker.io/woodpeckerci/plugin-git,quay.io/woodpeckerci/plugin-git

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.

DOCKER_CONFIG​

  • Name: WOODPECKER_DOCKER_CONFIG
  • Default: none

Configures a specific private registry config for all pipelines.

Example: WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json

ENVIRONMENT​

  • Name: WOODPECKER_ENVIRONMENT
  • Default: none

If you want specific environment variables to be available in all of your pipelines use the WOODPECKER_ENVIRONMENT setting on the Woodpecker server. Note that these can't overwrite any existing, built-in variables.

Example: WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2

AGENT_SECRET​

  • Name: WOODPECKER_AGENT_SECRET
  • Default: none

A shared secret used by server and agents to authenticate communication. A secret can be generated by openssl rand -hex 32.

AGENT_SECRET_FILE​

  • Name: WOODPECKER_AGENT_SECRET_FILE
  • Default: none

Read the value for WOODPECKER_AGENT_SECRET from the specified filepath

DISABLE_USER_AGENT_REGISTRATION​

  • Name: WOODPECKER_DISABLE_USER_AGENT_REGISTRATION
  • Default: false

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.

KEEPALIVE_MIN_TIME​

  • Name: WOODPECKER_KEEPALIVE_MIN_TIME
  • Default: none

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

DATABASE_DRIVER​

  • Name: WOODPECKER_DATABASE_DRIVER
  • Default: sqlite3

The database driver name. Possible values are sqlite3, mysql or postgres.

DATABASE_DATASOURCE​

  • Name: 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

DATABASE_DATASOURCE_FILE​

  • Name: WOODPECKER_DATABASE_DATASOURCE_FILE
  • Default: none

Read the value for WOODPECKER_DATABASE_DATASOURCE from the specified filepath

PROMETHEUS_AUTH_TOKEN​

  • Name: WOODPECKER_PROMETHEUS_AUTH_TOKEN
  • Default: none

Token to secure the Prometheus metrics endpoint. Must be set to enable the endpoint.

PROMETHEUS_AUTH_TOKEN_FILE​

  • Name: WOODPECKER_PROMETHEUS_AUTH_TOKEN_FILE
  • Default: none

Read the value for WOODPECKER_PROMETHEUS_AUTH_TOKEN from the specified filepath

STATUS_CONTEXT​

  • Name: 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.

STATUS_CONTEXT_FORMAT​

  • Name: 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 (see WOODPECKER_STATUS_CONTEXT)
  • event: the event which started the pipeline
  • workflow: the workflow's name
  • owner: the repo's owner
  • repo: the repo's name

CONFIG_SERVICE_ENDPOINT​

  • Name: WOODPECKER_CONFIG_SERVICE_ENDPOINT
  • Default: none

Specify a configuration service endpoint, see Configuration Extension

FORGE_TIMEOUT​

  • Name: WOODPECKER_FORGE_TIMEOUT
  • Default: 5s

Specify timeout when fetching the Woodpecker configuration from forge. See https://pkg.go.dev/time#ParseDuration for syntax reference.

FORGE_RETRY​

  • Name: WOODPECKER_FORGE_RETRY
  • Default: 3

Specify how many retries of fetching the Woodpecker configuration from a forge are done before we fail.

ENABLE_SWAGGER​

  • Name: WOODPECKER_ENABLE_SWAGGER
  • Default: true

Enable the Swagger UI for API documentation.

DISABLE_VERSION_CHECK​

  • Name: WOODPECKER_DISABLE_VERSION_CHECK
  • Default: false

Disable version check in admin web UI.

LOG_STORE​

  • Name: WOODPECKER_LOG_STORE
  • Default: database

Where to store logs. Possible values: database or file.

LOG_STORE_FILE_PATH​

  • Name: WOODPECKER_LOG_STORE_FILE_PATH
  • Default: none

Directory to store logs in if WOODPECKER_LOG_STORE is file.

EXPERT_WEBHOOK_HOST​

  • Name: WOODPECKER_EXPERT_WEBHOOK_HOST
  • Default: none
注意

This option is not required in most cases and should only be used if you know what you're doing.

Fully qualified Woodpecker server URL, called by the webhooks of the forge. Format: <scheme>://<host>[/<prefix path>].

EXPERT_FORGE_OAUTH_HOST​

  • Name: WOODPECKER_EXPERT_FORGE_OAUTH_HOST
  • Default: none
注意

This option is not required in most cases and should only be used if you know what you're doing.

Fully qualified public forge URL, used if forge url is not a public URL. Format: <scheme>://<host>[/<prefix path>].

GITHUB_*​

See GitHub configuration

GITEA_*​

See Gitea configuration

BITBUCKET_*​

See Bitbucket configuration

GITLAB_*​

See GitLab configuration