Mirrors/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2026-03-15 17:13:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add 2.6 docs (#3786)

Browse Source
This commit is contained in:
qwerty287
2024-06-13 19:31:54 +02:00
committed by GitHub
parent 760a903a30
commit 4f7df39edd
94 changed files with 1571 additions and 2001 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
docs/versioned_docs/version-2.6/30-administration/00-deployment/00-overview.md Normal file
View File

@@ -0,0 +1,76 @@
# Deployment
A Woodpecker deployment consists of two parts:
- A server which is the heart of Woodpecker and ships the web interface.
- Next to one server, you can deploy any number of agents which will run the pipelines.
Each agent is able to process one pipeline step by default.
If you have four agents installed and connected to the Woodpecker server, your system will process four workflows in parallel.
:::tip
You can add more agents to increase the number of parallel workflows or set the agent's `WOODPECKER_MAX_WORKFLOWS=1` environment variable to increase the number of parallel workflows for that agent.
:::
## Which version of Woodpecker should I use?
Woodpecker is having two different kinds of releases: **stable** and **next**.
Find more information about the different versions [here](/versions).
## Hardware Requirements
Below are minimal resources requirements for Woodpecker components itself:
| Component | Memory | CPU |
| --------- | ------ | --- |
| Server | 200 MB | 1 |
| Agent | 32 MB | 1 |
Note, that those values do not include the operating system or workload (pipelines execution) resources consumption.
In addition you need at least some kind of database which requires additional resources depending on the selected database system.
## Installation
You can install Woodpecker on multiple ways:
- Using [docker-compose](./10-docker-compose.md) with the official [container images](./10-docker-compose.md#docker-images)
- Using [Kubernetes](./20-kubernetes.md) via the Woodpecker Helm chart
- Using binaries, DEBs or RPMs you can download from [latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest)
## Authentication
Authentication is done using OAuth and is delegated to your forge which is configured using environment variables.
See the complete reference for all supported forges [here](../11-forges/11-overview.md).
## Database
By default Woodpecker uses a SQLite database which requires zero installation or configuration. See the [database settings](../30-database.md) page to further configure it or use MySQL or Postgres.
## SSL
Woodpecker supports SSL configuration by using Let's encrypt or by using own certificates. See the [SSL guide](../60-ssl.md). You can also put it behind a [reverse proxy](#behind-a-proxy)
## Metrics
A [Prometheus endpoint](../90-prometheus.md) is exposed.
## Behind a proxy
See the [proxy guide](../70-proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok.
In the case you need to use Woodpecker with a URL path prefix (like: <https://example.org/woodpecker/>), add the root path to [`WOODPECKER_HOST`](../10-server-config.md#woodpecker_host).
## Third-party installation methods
:::info
These installation methods are not officially supported. If you experience issues with them, please open issues in the specific repositories.
:::
- [Using NixOS](./30-nixos.md) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker)
- [On Alpine Edge](https://pkgs.alpinelinux.org/packages?name=woodpecker&branch=edge&repo=&arch=&maintainer=)
- [On Arch Linux](https://archlinux.org/packages/?q=woodpecker)
- [Using YunoHost](https://apps.yunohost.org/app/woodpecker)
- [On Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html)

147
docs/versioned_docs/version-2.6/30-administration/00-deployment/10-docker-compose.md Normal file
View File

@@ -0,0 +1,147 @@
# docker-compose
The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start a Woodpecker server with a single agent.
It relies on a number of environment variables that you must set before running `docker-compose up`. The variables are described below.
```yaml title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
ports:
- 8000:8000
volumes:
- woodpecker-server-data:/var/lib/woodpecker/
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
command: agent
restart: always
depends_on:
- woodpecker-server
volumes:
- woodpecker-agent-config:/etc/woodpecker
- /var/run/docker.sock:/var/run/docker.sock
environment:
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
volumes:
woodpecker-server-data:
woodpecker-agent-config:
```
Woodpecker needs to know its own address. You must therefore provide the public address of it in `<scheme>://<hostname>` format. Please omit trailing slashes:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_HOST=${WOODPECKER_HOST}
```
Woodpecker can also have its port's configured. It uses a separate port for gRPC and for HTTP. The agent performs gRPC calls and connects to the gRPC port.
They can be configured with `*_ADDR` variables:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR}
+ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR}
```
Reverse proxying can also be [configured for gRPC](../70-proxy.md#caddy). If the agents are connecting over the internet, it should also be SSL encrypted. The agent then needs to be configured to be secure:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_GRPC_SECURE=true # defaults to false
+ - WOODPECKER_GRPC_VERIFY=true # default
```
As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon:
```diff title="docker-compose.yaml"
version: '3'
services:
[...]
woodpecker-agent:
[...]
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
```
Agents require the server address for agent-to-server communication. The agent connects to the server's gRPC port:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-agent:
[...]
environment:
+ - WOODPECKER_SERVER=woodpecker-server:9000
```
The server and agents use a shared secret to authenticate communication. This should be a random string of your choosing and should be kept private. You can generate such string with `openssl rand -hex 32`:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
woodpecker-agent:
[...]
environment:
- [...]
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
```
## Docker images
Image variants:
- The `latest` image is the latest stable release
- The `vX.X.X` images are stable releases
- The `vX.X` images are based on the current release branch (e.g. `release/v1.0`) and can be used to get bugfixes asap
- The `next` images are based on the current `main` branch
```bash
# server
docker pull woodpeckerci/woodpecker-server:latest
docker pull woodpeckerci/woodpecker-server:latest-alpine
# agent
docker pull woodpeckerci/woodpecker-agent:latest
docker pull woodpeckerci/woodpecker-agent:latest-alpine
# cli
docker pull woodpeckerci/woodpecker-cli:latest
docker pull woodpeckerci/woodpecker-cli:latest-alpine
```

9
docs/versioned_docs/version-2.6/30-administration/00-deployment/20-kubernetes.md Normal file
View File

@@ -0,0 +1,9 @@
# Kubernetes
We recommended to deploy Woodpecker using the [Woodpecker helm chart](https://github.com/woodpecker-ci/helm).
Have a look at the [`values.yaml`](https://github.com/woodpecker-ci/helm/blob/main/charts/woodpecker/values.yaml) config files for all available settings.
The chart contains two subcharts, `server` and `agent` which are automatically configured as needed.
The chart started off with two independent charts but was merged into one to simplify the deployment at start of 2023.
A couple of backend-specific config env vars exists which are described in the [kubernetes backend docs](../22-backends/40-kubernetes.md).

88
docs/versioned_docs/version-2.6/30-administration/00-deployment/30-nixos.md Normal file
View File

@@ -0,0 +1,88 @@
# NixOS
:::info
Note that this module is not maintained by the Woodpecker developers.
If you experience issues please open a bug report in the [nixpkgs repo](https://github.com/NixOS/nixpkgs/issues/new/choose) where the module is maintained.
:::
The NixOS install is in theory quite similar to the binary install and supports multiple backends.
In practice, the settings are specified declaratively in the NixOS configuration and no manual steps need to be taken.
## General Configuration
```nix
{ config
, ...
}:
let
domain = "woodpecker.example.org";
in
{
# This automatically sets up certificates via let's encrypt
security.acme.defaults.email = "acme@example.com";
security.acme.acceptTerms = true;
security.acme.certs."${domain}" = { };
# Setting up a nginx proxy that handles tls for us
networking.firewall.allowedTCPPorts = [ 80 443 ];
services.nginx = {
enable = true;
recommendedTlsSettings = true;
recommendedOptimisation = true;
recommendedProxySettings = true;
virtualHosts."${domain}" = {
enableACME = true;
forceSSL = true;
locations."/" = {
proxyPass = "http://localhost:3007";
};
};
};
services.woodpecker-server = {
enable = true;
environment = {
WOODPECKER_HOST = "https://${domain}";
WOODPECKER_SERVER_ADDR = ":3007";
WOODPECKER_OPEN = "true";
};
# You can pass a file with env vars to the system it could look like:
# WOODPECKER_AGENT_SECRET=XXXXXXXXXXXXXXXXXXXXXX
environmentFile = "/path/to/my/secrets/file";
};
# This sets up a woodpecker agent
services.woodpecker-agents.agents."docker" = {
enable = true;
# We need this to talk to the podman socket
extraGroups = [ "podman" ];
environment = {
WOODPECKER_SERVER = "localhost:9000";
WOODPECKER_MAX_WORKFLOWS = "4";
DOCKER_HOST = "unix:///run/podman/podman.sock";
WOODPECKER_BACKEND = "docker";
};
# Same as with woodpecker-server
environmentFile = [ "/var/lib/secrets/woodpecker.env" ];
};
# Here we setup podman and enable dns
virtualisation.podman = {
enable = true;
defaultNetwork.settings = {
dns_enabled = true;
};
};
# This is needed for podman to be able to talk over dns
networking.firewall.interfaces."podman0" = {
allowedUDPPorts = [ 53 ];
allowedTCPPorts = [ 53 ];
};
}
```
All configuration options can be found via [NixOS Search](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker)
## Tips and tricks
There are some resources on how to utilize Woodpecker more effectively with NixOS on the [Awesome Woodpecker](../../92-awesome.md) page, like using the runners nix-store in the pipeline.

6
docs/versioned_docs/version-2.6/30-administration/00-deployment/_category_.yaml Normal file
View File

@@ -0,0 +1,6 @@
label: 'Deployment'
collapsible: true
collapsed: true
link:
type: 'doc'
id: 'overview'

578
docs/versioned_docs/version-2.6/30-administration/10-server-config.md Normal file
View File

@@ -0,0 +1,578 @@
---
toc_max_heading_level: 2
---
# Server configuration
## User registration
Woodpecker does not have its own user registry; users are provided from your [forge](./11-forges/11-overview.md) (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:
```ini
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
```ini
WOODPECKER_OPEN=false
WOODPECKER_ADMIN=johnsmith,janedoe
```
### Only allow registration of users, who are members of approved organizations
```ini
WOODPECKER_OPEN=true
WOODPECKER_ORGS=dolores,dogpatch
```
## Administrators
Administrators should also be enumerated in your configuration.
```ini
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.
```ini
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.
```ini
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.
```diff title="docker-compose.yaml"
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:
```bash
echo "my_agent_secret_key" | docker secret create woodpecker-agent-secret -
```
or generate a random one like this:
```bash
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.
```ini
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`
```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`
```javascript
// place/copy a minified version of jQuery or ZeptoJS 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_LOG_XORM`
> Default: `false`
Enable XORM logs.
### `WOODPECKER_LOG_XORM_SQL`
> Default: `false`
Enable XORM SQL command logs.
### `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_WEBHOOK_HOST`
> Default: value from `WOODPECKER_HOST` config env
Server fully qualified URL of the Webhook-facing hostname and path prefix.
Example: `WOODPECKER_WEBHOOK_HOST=http://woodpecker-server.cicd.svc.cluster.local:8000`
### `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
Comma-separated list of syncable repo owners. ???
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_IMAGE`
> Default is defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/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.
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_ESCALATE`
> Defaults are defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go)
Docker images to run in privileged mode. Only change if you are sure what you do!
<!--
### `WOODPECKER_VOLUME`
> Default: empty
Comma-separated list of Docker volumes that are mounted into every pipeline step.
Example: `WOODPECKER_VOLUME=/path/on/host:/path/in/container:rw`|
-->
### `WOODPECKER_DOCKER_CONFIG`
> Default: empty
Configures a specific private registry config for all pipelines.
Example: `WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json`
<!--
### `WOODPECKER_ENVIRONMENT`
> Default: empty
TODO
### `WOODPECKER_NETWORK`
> Default: empty
Comma-separated list of Docker networks that are attached to every pipeline step.
Example: `WOODPECKER_NETWORK=network1,network2`
-->
### `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` 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:
```bash
# 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](https://pkg.go.dev/text/template) 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
---
### `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: empty
Specify a configuration service endpoint, see [Configuration Extension](./100-external-configuration-api.md)
### `WOODPECKER_FORGE_TIMEOUT`
> Default: 3s
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`](#woodpecker_log_store) is `file`.
---
### `WOODPECKER_GITHUB_...`
See [GitHub configuration](./11-forges/20-github.md#configuration)
### `WOODPECKER_GITEA_...`
See [Gitea configuration](./11-forges/30-gitea.md#configuration)
### `WOODPECKER_BITBUCKET_...`
See [Bitbucket configuration](./11-forges/50-bitbucket.md#configuration)
### `WOODPECKER_GITLAB_...`
See [GitLab configuration](./11-forges/40-gitlab.md#configuration)
### `WOODPECKER_ADDON_FORGE`
See [addon forges](./11-forges/100-addon.md).

104
docs/versioned_docs/version-2.6/30-administration/100-external-configuration-api.md Normal file
View File

@@ -0,0 +1,104 @@
# 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](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures) 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](https://github.com/woodpecker-ci/example-config-service)
:::warning
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.
:::
## Config
```ini title="Server"
WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig
```
### Example request made by Woodpecker
```json
{
"repo": {
"id": 100,
"uid": "",
"user_id": 0,
"namespace": "",
"name": "woodpecker-testpipe",
"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": ["somefilename.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
},
"configs": [
{
"name": ".woodpecker.yaml",
"data": "steps:\n - name: backend\n image: alpine\n commands:\n - echo \"Hello there from Repo (.woodpecker.yaml)\"\n"
}
]
}
```
### Example response structure
```json
{
"configs": [
{
"name": "central-override",
"data": "steps:\n - name: backend\n image: alpine\n commands:\n - echo \"Hello there from ConfigAPI\"\n"
}
]
}
```

68
docs/versioned_docs/version-2.6/30-administration/11-forges/100-addon.md Normal file
View File

@@ -0,0 +1,68 @@
# Addon forges
If the forge you're using does not comply with [Woodpecker's requirements](../../92-development/02-core-ideas.md#forges) or your setup is too specific to be added to Woodpecker's core, you can write your own forge using an addon forge.
:::warning
Addon forges are still experimental. Their implementation can change and break at any time.
:::
:::danger
You need to trust the author of the addon forge you use. It can access authentication codes and other possibly sensitive information.
:::
## Usage
To use an addon forge, download the correct addon version. Then, you can add the following to your configuration:
```ini
WOODPECKER_ADDON_FORGE=/path/to/your/addon/forge/file
```
In case you run Woodpecker as container, you probably want to mount the addon binary to `/opt/addons/`.
### Bug reports
If you experience bugs, please check which component has the issue. If it's the addon, **do not raise an issue in the main repository**, but rather use the separate addon repositories. To check which component is responsible for the bug, look at the logs. Logs from addons are marked with a special field `addon` containing their addon file name.
## List of addon forges
If you wrote or found an addon forge, please add it here so others can find it!
_Be the first one to add your addon forge!_
## Creating addon forges
Addons use RPC to communicate to the server and are implemented using the [`go-plugin` library](https://github.com/hashicorp/go-plugin).
### Writing your code
This example will use the Go language.
Directly import Woodpecker's Go packages (`go.woodpecker-ci.org/woodpecker/woodpecker/v2`) and use the interfaces and types defined there.
In the `main` function, just call `"go.woodpecker-ci.org/woodpecker/v2/server/forge/addon".Serve` with a `"go.woodpecker-ci.org/woodpecker/v2/server/forge".Forge` as argument.
This will take care of connecting the addon forge to the server.
### Example structure
```go
package main
import (
"context"
"net/http"
"go.woodpecker-ci.org/woodpecker/v2/server/forge/addon"
forgeTypes "go.woodpecker-ci.org/woodpecker/v2/server/forge/types"
"go.woodpecker-ci.org/woodpecker/v2/server/model"
)
func main() {
addon.Serve(config{})
}
type config struct {
}
// `config` must implement `"go.woodpecker-ci.org/woodpecker/v2/server/forge".Forge`. You must directly use Woodpecker's packages - see imports above.
```

13
docs/versioned_docs/version-2.6/30-administration/11-forges/11-overview.md Normal file
View File

@@ -0,0 +1,13 @@
# Forges
## Supported features
| Feature | [GitHub](20-github.md) | [Gitea](30-gitea.md) | [Forgejo](35-forgejo.md) | [Gitlab](40-gitlab.md) | [Bitbucket](50-bitbucket.md) | [Bitbucket Datacenter](60-bitbucket_datacenter.md) |
| ------------------------------------------------------------- | :--------------------: | :------------------: | :----------------------: | :--------------------: | :--------------------------: | :------------------------------------------------: |
| Event: Push | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Event: Tag | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Event: Pull-Request | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Event: Release | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: |
| Event: Deploy | :white_check_mark: | :x: | :x: | :x: | :x: | :x: |
| [Multiple workflows](../../20-usage/25-workflows.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [when.path filter](../../20-usage/20-workflow-syntax.md#path) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: |

89
docs/versioned_docs/version-2.6/30-administration/11-forges/20-github.md Normal file
View File

@@ -0,0 +1,89 @@
---
toc_max_heading_level: 2
---
# GitHub
Woodpecker comes with built-in support for GitHub and GitHub Enterprise.
To use Woodpecker with GitHub the following environment variables should be set for the server component:
```ini
WOODPECKER_GITHUB=true
WOODPECKER_GITHUB_CLIENT=YOUR_GITHUB_CLIENT_ID
WOODPECKER_GITHUB_SECRET=YOUR_GITHUB_CLIENT_SECRET
```
You will get these values from GitHub when you register your OAuth application.
To do so, go to Settings -> Developer Settings -> GitHub Apps -> New Oauth2 App.
:::warning
Do not use a "GitHub App" instead of an Oauth2 app as the former will not work correctly with Woodpecker right now (because user access tokens are not being refreshed automatically)
:::
## App Settings
- Name: An arbitrary name for your App
- Homepage URL: The URL of your Woodpecker instance
- Callback URL: `https://<your-woodpecker-instance>/authorize`
- (optional) Upload the Woodpecker Logo: <https://avatars.githubusercontent.com/u/84780935?s=200&v=4>
## Client Secret Creation
After your App has been created, you can generate a client secret.
Use this one for the `WOODPECKER_GITHUB_SECRET` environment variable.
## Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
### `WOODPECKER_GITHUB`
> Default: `false`
Enables the GitHub driver.
### `WOODPECKER_GITHUB_URL`
> Default: `https://github.com`
Configures the GitHub server address.
### `WOODPECKER_GITHUB_CLIENT`
> Default: empty
Configures the GitHub OAuth client id to authorize access.
### `WOODPECKER_GITHUB_CLIENT_FILE`
> Default: empty
Read the value for `WOODPECKER_GITHUB_CLIENT` from the specified filepath.
### `WOODPECKER_GITHUB_SECRET`
> Default: empty
Configures the GitHub OAuth client secret. This is used to authorize access.
### `WOODPECKER_GITHUB_SECRET_FILE`
> Default: empty
Read the value for `WOODPECKER_GITHUB_SECRET` from the specified filepath.
### `WOODPECKER_GITHUB_MERGE_REF`
> Default: `true`
### `WOODPECKER_GITHUB_SKIP_VERIFY`
> Default: `false`
Configure if SSL verification should be skipped.
### `WOODPECKER_GITHUB_PUBLIC_ONLY`
> Default: `false`
Configures the GitHub OAuth client to only obtain a token that can manage public repositories.

103
docs/versioned_docs/version-2.6/30-administration/11-forges/30-gitea.md Normal file
View File

@@ -0,0 +1,103 @@
---
toc_max_heading_level: 2
---
# Gitea
Woodpecker comes with built-in support for Gitea. To enable Gitea you should configure the Woodpecker container using the following environment variables:
```ini
WOODPECKER_GITEA=true
WOODPECKER_GITEA_URL=YOUR_GITEA_URL
WOODPECKER_GITEA_CLIENT=YOUR_GITEA_CLIENT
WOODPECKER_GITEA_SECRET=YOUR_GITEA_CLIENT_SECRET
```
## Gitea on the same host with containers
If you have Gitea also running on the same host within a container, make sure the agent does have access to it.
The agent tries to clone using the URL which Gitea reports through its API. For simplified connectivity, you should add the Woodpecker agent to the same docker network as Gitea is in.
Otherwise, the communication should go via the `docker0` gateway (usually 172.17.0.1).
To configure the Docker network if the network's name is `gitea`, configure it like this:
```diff title="docker-compose.yaml"
version: '3'
services:
[...]
woodpecker-agent:
[...]
environment:
- [...]
+ - WOODPECKER_BACKEND_DOCKER_NETWORK=gitea
```
## Registration
Register your application with Gitea to create your client id and secret. You can find the OAuth applications settings of Gitea at `https://gitea.<host>/user/settings/`. It is very import the authorization callback URL matches your http(s) scheme and hostname exactly with `https://<host>/authorize` as the path.
If you run the Woodpecker CI server on the same host as the Gitea instance, you might also need to allow local connections in Gitea, since version `v1.16`. Otherwise webhooks will fail. Add the following lines to your Gitea configuration (usually at `/etc/gitea/conf/app.ini`).
```ini
[webhook]
ALLOWED_HOST_LIST=external,loopback
```
For reference see [Configuration Cheat Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/#webhook-webhook).
![gitea oauth setup](gitea_oauth.gif)
## Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
### `WOODPECKER_GITEA`
> Default: `false`
Enables the Gitea driver.
### `WOODPECKER_GITEA_URL`
> Default: `https://try.gitea.io`
Configures the Gitea server address.
### `WOODPECKER_GITEA_CLIENT`
> Default: empty
Configures the Gitea OAuth client id. This is used to authorize access.
### `WOODPECKER_GITEA_CLIENT_FILE`
> Default: empty
Read the value for `WOODPECKER_GITEA_CLIENT` from the specified filepath
### `WOODPECKER_GITEA_SECRET`
> Default: empty
Configures the Gitea OAuth client secret. This is used to authorize access.
### `WOODPECKER_GITEA_SECRET_FILE`
> Default: empty
Read the value for `WOODPECKER_GITEA_SECRET` from the specified filepath
### `WOODPECKER_GITEA_SKIP_VERIFY`
> Default: `false`
Configure if SSL verification should be skipped.
## Advanced options
### `WOODPECKER_DEV_GITEA_OAUTH_URL`
> Default: value of `WOODPECKER_GITEA_URL`
Configures the user-facing Gitea server address. Should be used if `WOODPECKER_GITEA_URL` points to an internal URL used for API requests.

97
docs/versioned_docs/version-2.6/30-administration/11-forges/35-forgejo.md Normal file
View File

@@ -0,0 +1,97 @@
---
toc_max_heading_level: 2
---
# Forgejo
:::warning
Forgejo support is experimental.
:::
Woodpecker comes with built-in support for Forgejo. To enable Forgejo you should configure the Woodpecker container using the following environment variables:
```ini
WOODPECKER_FORGEJO=true
WOODPECKER_FORGEJO_URL=YOUR_FORGEJO_URL
WOODPECKER_FORGEJO_CLIENT=YOUR_FORGEJO_CLIENT
WOODPECKER_FORGEJO_SECRET=YOUR_FORGEJO_CLIENT_SECRET
```
## Forgejo on the same host with containers
If you have Forgejo also running on the same host within a container, make sure the agent does have access to it.
The agent tries to clone using the URL which Forgejo reports through its API. For simplified connectivity, you should add the Woodpecker agent to the same docker network as Forgejo is in.
Otherwise, the communication should go via the `docker0` gateway (usually 172.17.0.1).
To configure the Docker network if the network's name is `forgejo`, configure it like this:
```diff title="docker-compose.yaml"
services:
[...]
woodpecker-agent:
[...]
environment:
- [...]
+ - WOODPECKER_BACKEND_DOCKER_NETWORK=forgejo
```
## Registration
Register your application with Forgejo to create your client id and secret. You can find the OAuth applications settings of Forgejo at `https://forgejo.<host>/user/settings/`. It is very import the authorization callback URL matches your http(s) scheme and hostname exactly with `https://<host>/authorize` as the path.
If you run the Woodpecker CI server on the same host as the Forgejo instance, you might also need to allow local connections in Forgejo. Otherwise webhooks will fail. Add the following lines to your Forgejo configuration (usually at `/etc/forgejo/conf/app.ini`).
```ini
[webhook]
ALLOWED_HOST_LIST=external,loopback
```
For reference see [Configuration Cheat Sheet](https://forgejo.org/docs/latest/admin/config-cheat-sheet/#webhook-webhook).
![forgejo oauth setup](gitea_oauth.gif)
## Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
### `WOODPECKER_FORGEJO`
> Default: `false`
Enables the Forgejo driver.
### `WOODPECKER_FORGEJO_URL`
> Default: `https://next.forgejo.org`
Configures the Forgejo server address.
### `WOODPECKER_FORGEJO_CLIENT`
> Default: empty
Configures the Forgejo OAuth client id. This is used to authorize access.
### `WOODPECKER_FORGEJO_CLIENT_FILE`
> Default: empty
Read the value for `WOODPECKER_FORGEJO_CLIENT` from the specified filepath
### `WOODPECKER_FORGEJO_SECRET`
> Default: empty
Configures the Forgejo OAuth client secret. This is used to authorize access.
### `WOODPECKER_FORGEJO_SECRET_FILE`
> Default: empty
Read the value for `WOODPECKER_FORGEJO_SECRET` from the specified filepath
### `WOODPECKER_FORGEJO_SKIP_VERIFY`
> Default: `false`
Configure if SSL verification should be skipped.

68
docs/versioned_docs/version-2.6/30-administration/11-forges/40-gitlab.md Normal file
View File

@@ -0,0 +1,68 @@
---
toc_max_heading_level: 2
---
# GitLab
Woodpecker comes with built-in support for the GitLab version 8.2 and higher. To enable GitLab you should configure the Woodpecker container using the following environment variables:
```ini
WOODPECKER_GITLAB=true
WOODPECKER_GITLAB_URL=http://gitlab.mycompany.com
WOODPECKER_GITLAB_CLIENT=95c0282573633eb25e82
WOODPECKER_GITLAB_SECRET=30f5064039e6b359e075
```
## Registration
You must register your application with GitLab in order to generate a Client and Secret. Navigate to your account settings and choose Applications from the menu, and click New Application.
Please use `http://woodpecker.mycompany.com/authorize` as the Authorization callback URL. Grant `api` scope to the application.
If you run the Woodpecker CI server on a private IP (RFC1918) or use a non standard TLD (e.g. `.local`, `.intern`) with your GitLab instance, you might also need to allow local connections in GitLab, otherwise API requests will fail. In GitLab, navigate to the Admin dashboard, then go to `Settings > Network > Outbound requests` and enable `Allow requests to the local network from web hooks and services`.
## Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
### `WOODPECKER_GITLAB`
> Default: `false`
Enables the GitLab driver.
### `WOODPECKER_GITLAB_URL`
> Default: `https://gitlab.com`
Configures the GitLab server address.
### `WOODPECKER_GITLAB_CLIENT`
> Default: empty
Configures the GitLab OAuth client id. This is used to authorize access.
### `WOODPECKER_GITLAB_CLIENT_FILE`
> Default: empty
Read the value for `WOODPECKER_GITLAB_CLIENT` from the specified filepath
### `WOODPECKER_GITLAB_SECRET`
> Default: empty
Configures the GitLab OAuth client secret. This is used to authorize access.
### `WOODPECKER_GITLAB_SECRET_FILE`
> Default: empty
Read the value for `WOODPECKER_GITLAB_SECRET` from the specified filepath
### `WOODPECKER_GITLAB_SKIP_VERIFY`
> Default: `false`
Configure if SSL verification should be skipped.

75
docs/versioned_docs/version-2.6/30-administration/11-forges/50-bitbucket.md Normal file
View File

@@ -0,0 +1,75 @@
---
toc_max_heading_level: 2
---
# Bitbucket
Woodpecker comes with built-in support for Bitbucket Cloud. To enable Bitbucket Cloud you should configure the Woodpecker container using the following environment variables:
```ini
WOODPECKER_BITBUCKET=true
WOODPECKER_BITBUCKET_CLIENT=... # called "Key" in Bitbucket
WOODPECKER_BITBUCKET_SECRET=...
```
## Registration
You must register an OAuth application at Bitbucket in order to get a key and secret combination for Woodpecker. Navigate to your workspace settings and choose `OAuth consumers` from the menu, and finally click `Add Consumer` (the url should be like: `https://bitbucket.org/[your-project-name]/workspace/settings/api`).
Please set a name and set the `Callback URL` like this:
```uri
https://<your-woodpecker-address>/authorize
```
![bitbucket oauth setup](bitbucket_oauth.png)
Please also be sure to check the following permissions:
- Account: Email, Read
- Workspace membership: Read
- Projects: Read
- Repositories: Read
- Pull requests: Read
- Webhooks: Read and Write
![bitbucket permissions](bitbucket_permissions.png)
## Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
### `WOODPECKER_BITBUCKET`
> Default: `false`
Enables the Bitbucket driver.
### `WOODPECKER_BITBUCKET_CLIENT`
> Default: empty
Configures the Bitbucket OAuth client key. This is used to authorize access.
### `WOODPECKER_BITBUCKET_CLIENT_FILE`
> Default: empty
Read the value for `WOODPECKER_BITBUCKET_CLIENT` from the specified filepath
### `WOODPECKER_BITBUCKET_SECRET`
> Default: empty
Configures the Bitbucket OAuth client secret. This is used to authorize access.
### `WOODPECKER_BITBUCKET_SECRET_FILE`
> Default: empty
Read the value for `WOODPECKER_BITBUCKET_SECRET` from the specified filepath
## Missing Features
Path filters for pull requests are not supported. We are interested in patches to include this functionality.
If you are interested in contributing to Woodpecker and submitting a patch please **contact us** via [Discord](https://discord.gg/fcMQqSMXJy) or [Matrix](https://matrix.to/#/#WoodpeckerCI-Develop:obermui.de).

98
docs/versioned_docs/version-2.6/30-administration/11-forges/60-bitbucket_datacenter.md Normal file
View File

@@ -0,0 +1,98 @@
---
toc_max_heading_level: 2
---
# Bitbucket Datacenter / Server
:::warning
Woodpecker comes with experimental support for Bitbucket Datacenter / Server, formerly known as Atlassian Stash.
:::
To enable Bitbucket Server you should configure the Woodpecker container using the following environment variables:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_BITBUCKET_DC=true
+ - WOODPECKER_BITBUCKET_DC_GIT_USERNAME=foo
+ - WOODPECKER_BITBUCKET_DC_GIT_PASSWORD=bar
+ - WOODPECKER_BITBUCKET_DC_CLIENT_ID=xxx
+ - WOODPECKER_BITBUCKET_DC_CLIENT_SECRET=yyy
+ - WOODPECKER_BITBUCKET_DC_URL=http://stash.mycompany.com
woodpecker-agent:
[...]
```
## Service Account
Woodpecker uses `git+https` to clone repositories, however, Bitbucket Server does not currently support cloning repositories with an OAuth token. To work around this limitation, you must create a service account and provide the username and password to Woodpecker. This service account will be used to authenticate and clone private repositories.
## Registration
Woodpecker must be registered with Bitbucket Datacenter / Server. In the administration section of Bitbucket choose "Application Links" and then "Create link". Woodpecker should be listed as "External Application" and the direction should be set to "Incomming". Note the client id and client secret of the registration to be used in the configuration of Woodpecker.
See also [Configure an incoming link](https://confluence.atlassian.com/bitbucketserver/configure-an-incoming-link-1108483657.html).
## Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
### `WOODPECKER_BITBUCKET_DC`
> Default: `false`
Enables the Bitbucket Server driver.
### `WOODPECKER_BITBUCKET_DC_URL`
> Default: empty
Configures the Bitbucket Server address.
### `WOODPECKER_BITBUCKET_DC_CLIENT_ID`
> Default: empty
Configures your Bitbucket Server OAUth 2.0 client id.
### `WOODPECKER_BITBUCKET_DC_CLIENT_SECRET`
> Default: empty
Configures your Bitbucket Server OAUth 2.0 client secret.
### `WOODPECKER_BITBUCKET_DC_GIT_USERNAME`
> Default: empty
This username is used to authenticate and clone all private repositories.
### `WOODPECKER_BITBUCKET_DC_GIT_USERNAME_FILE`
> Default: empty
Read the value for `WOODPECKER_BITBUCKET_DC_GIT_USERNAME` from the specified filepath
### `WOODPECKER_BITBUCKET_DC_GIT_PASSWORD`
> Default: empty
The password is used to authenticate and clone all private repositories.
### `WOODPECKER_BITBUCKET_DC_GIT_PASSWORD_FILE`
> Default: empty
Read the value for `WOODPECKER_BITBUCKET_DC_GIT_PASSWORD` from the specified filepath
### `WOODPECKER_BITBUCKET_DC_SKIP_VERIFY`
> Default: `false`
Configure if SSL verification should be skipped.

6
docs/versioned_docs/version-2.6/30-administration/11-forges/_category_.yaml Normal file
View File

@@ -0,0 +1,6 @@
label: 'Forges'
collapsible: true
collapsed: true
link:
type: 'doc'
id: 'overview'

BIN
docs/versioned_docs/version-2.6/30-administration/11-forges/bitbucket_oauth.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
docs/versioned_docs/version-2.6/30-administration/11-forges/bitbucket_permissions.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
docs/versioned_docs/version-2.6/30-administration/11-forges/gitea_oauth.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 129 KiB

BIN
docs/versioned_docs/version-2.6/30-administration/11-forges/github_oauth.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

199
docs/versioned_docs/version-2.6/30-administration/15-agent-config.md Normal file
View File

@@ -0,0 +1,199 @@
---
toc_max_heading_level: 2
---
# Agent configuration
Agents are configured by the command line or environment variables. At the minimum you need the following information:
```ini
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_WORKFLOWS` if not set, defaults to 1
## Workflows per agent
By default, the maximum workflows that are executed in parallel on an agent is 1. If required, you can add `WOODPECKER_MAX_WORKFLOWS` to increase your parallel processing for an agent.
```ini
WOODPECKER_SERVER=localhost:9000
WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
WOODPECKER_MAX_WORKFLOWS=4
```
## Agent registration
When the agent starts it connects to the server using the token from `WOODPECKER_AGENT_SECRET`. The server identifies the agent and registers the agent in its database if it wasn't connected before.
There are two types of tokens to connect an agent to the server:
### Using system token
A _system token_ is a token that is used system-wide, e.g. when you set the same token in `WOODPECKER_AGENT_SECRET` on both the server and the agents.
In that case registration process would be as following:
1. The first time the agent communicates with the server, it is using the system token
1. The server registers the agent in its database if not done before and generates a unique ID which is then sent back to the agent
1. The agent stores the received ID in a file (configured by `WOODPECKER_AGENT_CONFIG_FILE`)
1. At the following startups, the agent uses the system token **and** its received ID to identify itself to the server
### Using agent token
An _agent token_ is a token that is used by only one particular agent. This unique token is applied to the agent by `WOODPECKER_AGENT_SECRET`.
To get an _agent token_ you have to register the agent manually in the server using the UI:
1. The administrator registers a new agent manually at `Settings -> Agents -> Add agent`
![Agent creation](./new-agent-registration.png)
![Agent created](./new-agent-created.png)
1. The generated token from the previous step has to be provided to the agent using `WOODPECKER_AGENT_SECRET`
1. The agent will connect to the server using the provided token and will update its status in the UI:
![Agent connected](./new-agent-connected.png)
## 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, e.g. `/etc/woodpecker/agent-secret.conf`
### `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_AGENT_CONFIG_FILE`
> Default: `/etc/woodpecker/agent.conf`
Configures the path of the agent config file.
### `WOODPECKER_MAX_WORKFLOWS`
> Default: `1`
Configures the number of parallel workflows.
### `WOODPECKER_FILTER_LABELS`
> Default: empty
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-workflow-syntax.md#labels).
### `WOODPECKER_HEALTHCHECK`
> Default: `true`
Enable healthcheck endpoint.
### `WOODPECKER_HEALTHCHECK_ADDR`
> Default: `:3000`
Configures healthcheck endpoint address.
### `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`, `docker`, `local` or `kubernetes`.
### `WOODPECKER_BACKEND_DOCKER_*`
See [Docker backend configuration](./22-backends/10-docker.md#configuration)
### `WOODPECKER_BACKEND_K8S_*`
See [Kubernetes backend configuration](./22-backends/40-kubernetes.md#configuration)
### `WOODPECKER_BACKEND_LOCAL_*`
See [Local backend configuration](./22-backends/20-local.md#options)
## Advanced Settings
:::warning
Only change these If you know what you do.
:::
### `WOODPECKER_CONNECT_RETRY_COUNT`
> Default: `5`
Configures number of times agent retries to connect to the server.
### `WOODPECKER_CONNECT_RETRY_DELAY`
> Default: `2s`
Configures delay between agent connection retries to the server.

64
docs/versioned_docs/version-2.6/30-administration/22-backends/10-docker.md Normal file
View File

@@ -0,0 +1,64 @@
---
toc_max_heading_level: 2
---
# Docker backend
This is the original backend used with Woodpecker. The docker backend executes each step inside a separate container started on the agent.
## Docker credentials
Woodpecker supports [Docker credentials](https://github.com/docker/docker-credential-helpers) to securely store registry credentials. Install your corresponding credential helper and configure it in your Docker config file passed via [`WOODPECKER_DOCKER_CONFIG`](../10-server-config.md#woodpecker_docker_config).
To add your credential helper to the Woodpecker server container you could use the following code to build a custom image:
```dockerfile
FROM woodpeckerci/woodpecker-server:latest-alpine
RUN apk add -U --no-cache docker-credential-ecr-login
```
## Podman support
While the agent was developed with Docker/Moby, Podman can also be used by setting the environment variable `DOCKER_HOST` to point to the Podman socket. In order to work without workarounds, Podman 4.0 (or above) is required.
## Image cleanup
The agent **will not** automatically remove images from the host. This task should be managed by the host system. For example, you can use a cron job to periodically do clean-up tasks for the CI runner.
:::danger
The following commands **are destructive** and **irreversible** it is highly recommended that you test these commands on your system before running them in production via a cron job or other automation.
:::
### Remove all unused images
```bash
docker image rm $(docker images --filter "dangling=true" -q --no-trunc)
```
### Remove Woodpecker volumes
```bash
docker volume rm $(docker volume ls --filter name=^wp_* --filter dangling=true -q)
```
## Configuration
### `WOODPECKER_BACKEND_DOCKER_NETWORK`
> Default: empty
Set to the name of an existing network which will be attached to all your pipeline containers (steps). Please be careful as this allows the containers of different pipelines to access each other!
### `WOODPECKER_BACKEND_DOCKER_ENABLE_IPV6`
> Default: `false`
Enable IPv6 for the networks used by pipeline containers (steps). Make sure you configured your docker daemon to support IPv6.
### `WOODPECKER_BACKEND_DOCKER_VOLUMES`
> Default: empty
List of default volumes separated by comma to be mounted to all pipeline containers (steps). For example to use custom CA
certificates installed on host and host timezone use `/etc/ssl/certs:/etc/ssl/certs:ro,/etc/timezone:/etc/timezone`.

67
docs/versioned_docs/version-2.6/30-administration/22-backends/20-local.md Normal file
View File

@@ -0,0 +1,67 @@
---
toc_max_heading_level: 3
---
# Local backend
:::danger
The local backend executes pipelines on the local system without any isolation.
:::
:::note
Currently we do not support [services](../../20-usage/60-services.md) for this backend.
[Read more here](https://github.com/woodpecker-ci/woodpecker/issues/3095).
:::
Since the commands run directly in the same context as the agent (same user, same
filesystem), a malicious pipeline could be used to access the agent
configuration especially the `WOODPECKER_AGENT_SECRET` variable.
It is recommended to use this backend only for private setup where the code and
pipeline can be trusted. It should not be used in a public instance where
anyone can submit code or add new repositories. The agent should not run as a privileged user (root).
The local backend will use a random directory in `$TMPDIR` to store the cloned
code and execute commands.
In order to use this backend, you need to download (or build) the
[agent](https://github.com/woodpecker-ci/woodpecker/releases/latest), configure it and run it on the host machine.
## Usage
To enable the local backend, set the following:
```ini
WOODPECKER_BACKEND=local
```
### Shell
The `image` entrypoint is used to specify the shell, such as `bash` or `fish`, that is
used to run the commands.
```yaml title=".woodpecker.yaml"
steps:
- name: build
image: bash
commands: [...]
```
### Plugins
```yaml
steps:
- name: build
image: /usr/bin/tree
```
If no commands are provided, plugins are treated in the usual manner.
In the context of the local backend, plugins are simply executable binaries, which can be located using their name if they are listed in `$PATH`, or through an absolute path.
### Options
#### `WOODPECKER_BACKEND_LOCAL_TEMP_DIR`
> Default: default temp directory
Directory to create folders for workflows.

305
docs/versioned_docs/version-2.6/30-administration/22-backends/40-kubernetes.md Normal file
View File

@@ -0,0 +1,305 @@
---
toc_max_heading_level: 2
---
# Kubernetes backend
The Kubernetes backend executes steps inside standalone Pods. A temporary PVC is created for the lifetime of the pipeline to transfer files between steps.
## Images from private registries
In order to pull private container images defined in your pipeline YAML you must provide [registry credentials in Kubernetes Secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).
As the Secret is Agent-wide, it has to be placed in namespace defined by `WOODPECKER_BACKEND_K8S_NAMESPACE`.
Besides, you need to provide the Secret name to Agent via `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES`.
## Job specific configuration
### Resources
The Kubernetes backend also allows for specifying requests and limits on a per-step basic, most commonly for CPU and memory.
We recommend to add a `resources` definition to all steps to ensure efficient scheduling.
Here is an example definition with an arbitrary `resources` definition below the `backend_options` section:
```yaml
steps:
- name: 'My kubernetes step'
image: alpine
commands:
- echo "Hello world"
backend_options:
kubernetes:
resources:
requests:
memory: 200Mi
cpu: 100m
limits:
memory: 400Mi
cpu: 1000m
```
You can use [Limit Ranges](https://kubernetes.io/docs/concepts/policy/limit-range/) if you want to set the limits by per-namespace basis.
### Runtime class
`runtimeClassName` specifies the name of the RuntimeClass which will be used to run this Pod. If no `runtimeClassName` is specified, the default RuntimeHandler will be used.
See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/containers/runtime-class/) for more information on specifying runtime classes.
### Service account
`serviceAccountName` specifies the name of the ServiceAccount which the Pod will mount. This service account must be created externally.
See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/security/service-accounts/) for more information on using service accounts.
### Node selector
`nodeSelector` specifies the labels which are used to select the node on which the job will be executed.
Labels defined here will be appended to a list which already contains `"kubernetes.io/arch"`.
By default `"kubernetes.io/arch"` is inferred from the agents' platform. One can override it by setting that label in the `nodeSelector` section of the `backend_options`.
Without a manual overwrite, builds will be randomly assigned to the runners and inherit their respective architectures.
To overwrite this, one needs to set the label in the `nodeSelector` section of the `backend_options`.
A practical example for this is when running a matrix-build and delegating specific elements of the matrix to run on a specific architecture.
In this case, one must define an arbitrary key in the matrix section of the respective matrix element:
```yaml
matrix:
include:
- NAME: runner1
ARCH: arm64
```
And then overwrite the `nodeSelector` in the `backend_options` section of the step(s) using the name of the respective env var:
```yaml
[...]
backend_options:
kubernetes:
nodeSelector:
kubernetes.io/arch: "${ARCH}"
```
You can use [WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR](#woodpecker_backend_k8s_pod_node_selector) if you want to set the node selector per Agent
or [PodNodeSelector](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#podnodeselector) admission controller if you want to set the node selector by per-namespace basis.
### Tolerations
When you use `nodeSelector` and the node pool is configured with Taints, you need to specify the Tolerations. Tolerations allow the scheduler to schedule Pods with matching taints.
See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for more information on using tolerations.
Example pipeline configuration:
```yaml
steps:
- name: build
image: golang
commands:
- go get
- go build
- go test
backend_options:
kubernetes:
serviceAccountName: 'my-service-account'
resources:
requests:
memory: 128Mi
cpu: 1000m
limits:
memory: 256Mi
nodeSelector:
beta.kubernetes.io/instance-type: p3.8xlarge
tolerations:
- key: 'key1'
operator: 'Equal'
value: 'value1'
effect: 'NoSchedule'
tolerationSeconds: 3600
```
### Volumes
To mount volumes a PersistentVolume (PV) and PersistentVolumeClaim (PVC) are needed on the cluster which can be referenced in steps via the `volumes` option.
Assuming a PVC named `woodpecker-cache` exists, it can be referenced as follows in a step:
```yaml
steps:
- name: "Restore Cache"
image: meltwater/drone-cache
volumes:
- woodpecker-cache:/woodpecker/src/cache
settings:
mount:
- "woodpecker-cache"
[...]
```
### Security context
Use the following configuration to set the [Security Context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for the Pod/container running a given pipeline step:
```yaml
steps:
- name: test
image: alpine
commands:
- echo Hello world
backend_options:
kubernetes:
securityContext:
runAsUser: 999
runAsGroup: 999
privileged: true
[...]
```
Note that the `backend_options.kubernetes.securityContext` object allows you to set both Pod and container level security context options in one object.
By default, the properties will be set at the Pod level. Properties that are only supported on the container level will be set there instead. So, the
configuration shown above will result in something like the following Pod spec:
```yaml
kind: Pod
spec:
securityContext:
runAsUser: 999
runAsGroup: 999
containers:
- name: wp-01hcd83q7be5ymh89k5accn3k6-0-step-0
image: alpine
securityContext:
privileged: true
[...]
```
You can also restrict a container's syscalls with [seccomp](https://kubernetes.io/docs/tutorials/security/seccomp/) profile
```yaml
backend_options:
kubernetes:
securityContext:
seccompProfile:
type: Localhost
localhostProfile: profiles/audit.json
```
or restrict a container's access to resources by specifying [AppArmor](https://kubernetes.io/docs/tutorials/security/apparmor/) profile
```yaml
backend_options:
kubernetes:
securityContext:
apparmorProfile:
type: Localhost
localhostProfile: k8s-apparmor-example-deny-write
```
:::note
AppArmor syntax follows [KEP-24](https://github.com/kubernetes/enhancements/blob/fddcbb9cbf3df39ded03bad71228265ac6e5215f/keps/sig-node/24-apparmor/README.md).
:::
### Annotations and labels
You can specify arbitrary [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) and [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to be set on the Pod definition for a given workflow step using the following configuration:
```yaml
backend_options:
kubernetes:
annotations:
workflow-group: alpha
io.kubernetes.cri-o.Devices: /dev/fuse
labels:
environment: ci
app.kubernetes.io/name: builder
```
In order to enable this configuration you need to set the appropriate environment variables to `true` on the woodpecker agent:
[WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS_ALLOW_FROM_STEP](#woodpecker_backend_k8s_pod_annotations_allow_from_step) and/or [WOODPECKER_BACKEND_K8S_POD_LABELS_ALLOW_FROM_STEP](#woodpecker_backend_k8s_pod_labels_allow_from_step).
## Tips and tricks
### CRI-O
CRI-O users currently need to configure the workspace for all workflows in order for them to run correctly. Add the following at the beginning of your configuration:
```yaml
workspace:
base: '/woodpecker'
path: '/'
```
See [this issue](https://github.com/woodpecker-ci/woodpecker/issues/2510) for more details.
### `KUBERNETES_SERVICE_HOST` environment variable
Like the below env vars used for configuration, this can be set in the environment fonfiguration of the agent. It configures the address of the Kubernetes API server to connect to.
If running the agent within Kubernetes, this will already be set and you don't have to add it manually.
## Configuration
These env vars can be set in the `env:` sections of the agent.
### `WOODPECKER_BACKEND_K8S_NAMESPACE`
> Default: `woodpecker`
The namespace to create worker Pods in.
### `WOODPECKER_BACKEND_K8S_VOLUME_SIZE`
> Default: `10G`
The volume size of the pipeline volume.
### `WOODPECKER_BACKEND_K8S_STORAGE_CLASS`
> Default: empty
The storage class to use for the pipeline volume.
### `WOODPECKER_BACKEND_K8S_STORAGE_RWX`
> Default: `true`
Determines if `RWX` should be used for the pipeline volume's [access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes). If false, `RWO` is used instead.
### `WOODPECKER_BACKEND_K8S_POD_LABELS`
> Default: empty
Additional labels to apply to worker Pods. Must be a YAML object, e.g. `{"example.com/test-label":"test-value"}`.
### `WOODPECKER_BACKEND_K8S_POD_LABELS_ALLOW_FROM_STEP`
> Default: `false`
Determines if additional Pod labels can be defined from a step's backend options.
### `WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS`
> Default: empty
Additional annotations to apply to worker Pods. Must be a YAML object, e.g. `{"example.com/test-annotation":"test-value"}`.
### `WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS_ALLOW_FROM_STEP`
> Default: `false`
Determines if Pod annotations can be defined from a step's backend options.
### `WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR`
> Default: empty
Additional node selector to apply to worker pods. Must be a YAML object, e.g. `{"topology.kubernetes.io/region":"eu-central-1"}`.
### `WOODPECKER_BACKEND_K8S_SECCTX_NONROOT`
> Default: `false`
Determines if containers must be required to run as non-root users.
### `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES`
> Default: empty
Secret names to pull images from private repositories. See, how to [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).

23
docs/versioned_docs/version-2.6/30-administration/22-backends/50-custom-backends.md Normal file
View File

@@ -0,0 +1,23 @@
# Custom backends
If none of our backends fits your usecases, you can write your own.
Therefore, implement the interface `"go.woodpecker-ci.org/woodpecker/woodpecker/v2/pipeline/backend/types".Backend` and
build a custom agent using your backend with this `main.go`:
```go
package main
import (
"go.woodpecker-ci.org/woodpecker/v2/cmd/agent/core"
backendTypes "go.woodpecker-ci.org/woodpecker/v2/pipeline/backend/types"
)
func main() {
core.RunAgent([]backendTypes.Backend{
yourBackend,
})
}
```
It is also possible to use multiple backends, you can select with [`WOODPECKER_BACKEND`](../15-agent-config.md#woodpecker_backend) between them.

4
docs/versioned_docs/version-2.6/30-administration/22-backends/_category_.yaml Normal file
View File

@@ -0,0 +1,4 @@
label: 'Backends'
# position: 3
collapsible: true
collapsed: true

53
docs/versioned_docs/version-2.6/30-administration/30-database.md Normal file
View File

@@ -0,0 +1,53 @@
# Databases
The default database engine of Woodpecker is an embedded SQLite database which requires zero installation or configuration. But you can replace it with a MySQL/MariaDB or Postgres database.
## Configure SQLite
By default Woodpecker uses a SQLite database stored under `/var/lib/woodpecker/`. If using containers, you can mount a [data volume](https://docs.docker.com/storage/volumes/#create-and-manage-volumes) to persist the SQLite database.
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
+ volumes:
+ - woodpecker-server-data:/var/lib/woodpecker/
```
## Configure MySQL/MariaDB
The below example demonstrates MySQL database configuration. See the official driver [documentation](https://github.com/go-sql-driver/mysql#dsn-data-source-name) for configuration options and examples.
The minimum version of MySQL/MariaDB required is determined by the `go-sql-driver/mysql` - see [it's README](https://github.com/go-sql-driver/mysql#requirements) for more information.
```ini
WOODPECKER_DATABASE_DRIVER=mysql
WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true
```
## Configure Postgres
The below example demonstrates Postgres database configuration. See the official driver [documentation](https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING) for configuration options and examples.
Please use Postgres versions equal or higher than **11**.
```ini
WOODPECKER_DATABASE_DRIVER=postgres
WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/postgres?sslmode=disable
```
## Database Creation
Woodpecker does not create your database automatically. If you are using the MySQL or Postgres driver you will need to manually create your database using `CREATE DATABASE`.
## Database Migration
Woodpecker automatically handles database migration, including the initial creation of tables and indexes. New versions of Woodpecker will automatically upgrade the database unless otherwise specified in the release notes.
## Database Backups
Woodpecker does not perform database backups. This should be handled by separate third party tools provided by your database vendor of choice.
## Database Archiving
Woodpecker does not perform data archival; it considered out-of-scope for the project. Woodpecker is rather conservative with the amount of data it stores, however, you should expect the database logs to grow the size of your database considerably.

90
docs/versioned_docs/version-2.6/30-administration/60-ssl.md Normal file
View File

@@ -0,0 +1,90 @@
# SSL
Woodpecker supports two ways of enabling SSL communication. You can either use Let's Encrypt to get automated SSL support with
renewal or provide your own SSL certificates.
## Let's Encrypt
Woodpecker supports automated SSL configuration and updates using Let's Encrypt.
You can enable Let's Encrypt by making the following modifications to your server configuration:
```ini
WOODPECKER_LETS_ENCRYPT=true
WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld
```
Note that Woodpecker uses the hostname from the `WOODPECKER_HOST` environment variable when requesting certificates. For example, if `WOODPECKER_HOST=https://example.com` is set the certificate is requested for `example.com`. To receive emails before certificates expire Let's Encrypt requires an email address. You can set it with `WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld`.
The SSL certificates are stored in `$HOME/.local/share/certmagic` for binary versions of Woodpecker and in `/var/lib/woodpecker` for the Container versions of it. You can set a custom path by setting `XDG_DATA_HOME` if required.
> Once enabled you can visit the Woodpecker UI with http and the HTTPS address. HTTP will be redirected to HTTPS.
### Certificate Cache
Woodpecker writes the certificates to `/var/lib/woodpecker/certmagic/`.
### Certificate Updates
Woodpecker uses the official Go acme library which will handle certificate upgrades. There should be no addition configuration or management required.
## SSL with own certificates
Woodpecker supports SSL configuration by mounting certificates into your container.
```ini
WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key
```
### Certificate Chain
The most common problem encountered is providing a certificate file without the intermediate chain.
> LoadX509KeyPair reads and parses a public/private key pair from a pair of files. The files must contain PEM encoded data. The certificate file may contain intermediate certificates following the leaf certificate to form a certificate chain.
### Certificate Errors
SSL support is provided using the [ListenAndServeTLS](https://golang.org/pkg/net/http/#ListenAndServeTLS) function from the Go standard library. If you receive certificate errors or warnings please examine your configuration more closely.
### Running in containers
Update your configuration to expose the following ports:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
ports:
+ - 80:80
+ - 443:443
- 9000:9000
```
Update your configuration to mount your certificate and key:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
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
```
Update your configuration to provide the paths of your certificate and key:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
environment:
+ - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
+ - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key
```

199
docs/versioned_docs/version-2.6/30-administration/70-proxy.md Normal file
View File

@@ -0,0 +1,199 @@
# Proxy
## Apache
This guide provides a brief overview for installing Woodpecker server behind the Apache2 web-server. This is an example configuration:
```apacheconf
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.
```diff
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](https://docs.nginx.com/nginx/admin-guide).
Example configuration:
```nginx
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:
```diff
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](https://caddyserver.com/). This is an example caddyfile proxy configuration:
```caddy
# expose WebUI and API
woodpecker.example.com {
reverse_proxy woodpecker-server:8000
}
# expose gRPC
woodpeckeragent.example.com {
reverse_proxy h2c://woodpecker-server:9000
}
```
:::note
Above configuration shows how to create reverse-proxies for web and agent communication. If your agent uses SSL do not forget to enable [`WOODPECKER_GRPC_SECURE`](./15-agent-config.md#woodpecker_grpc_secure).
:::
## Tunnelmole
[Tunnelmole](https://github.com/robbie-cahill/tunnelmole-client) is an open source tunneling tool.
Start by [installing tunnelmole](https://github.com/robbie-cahill/tunnelmole-client#installation).
After the installation, run the following command to start tunnelmole:
```bash
tmole 8000
```
It will start a tunnel and will give a response like this:
```bash
➜ ~ 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](https://ngrok.com/) is a popular closed source tunnelling tool. After installing ngrok, open a new console and run the following command:
```bash
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](https://traefik.io/) 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.
```yaml
version: '3.8'
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(`cd.yourdomain.com`)
- traefik.http.routers.woodpecker-secure.tls=true
- traefik.http.routers.woodpecker-secure.tls.certresolver=letsencrypt
- traefik.http.routers.woodpecker-secure.entrypoints=websecure
- traefik.http.routers.woodpecker-secure.service=woodpecker-service
- traefik.http.routers.woodpecker.rule=Host(`cd.yourdomain.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.yourdomain.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=websecure
- traefik.http.routers.woodpecker-grpc-secure.service=woodpecker-grpc
- traefik.http.routers.woodpecker-grpc.rule=Host(`woodpecker-grpc.yourdomain.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
```
You should pass `WOODPECKER_GRPC_SECURE=true` and `WOODPECKER_GRPC_VERIFY=true` to your agent when using this configuration.

37
docs/versioned_docs/version-2.6/30-administration/80-autoscaler.md Normal file
View File

@@ -0,0 +1,37 @@
# Autoscaler
If your would like dynamically scale your agents with the load, you can use [our autoscaler](https://github.com/woodpecker-ci/autoscaler).
Please note that the autoscaler is not feature-complete yet. You can follow the progress [here](https://github.com/woodpecker-ci/autoscaler#roadmap).
## Setup
### docker-compose
If you are using docker-compose you can add the following to your `docker-compose.yaml` file:
```yaml
version: '3'
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:next
[...]
woodpecker-autoscaler:
image: woodpeckerci/autoscaler:next
restart: always
depends_on:
- woodpecker-server
environment:
- WOODPECKER_SERVER=https://your-woodpecker-server.tld # the url of your woodpecker server / could also be a public url
- WOODPECKER_TOKEN=${WOODPECKER_TOKEN} # the api token you can get from the UI https://your-woodpecker-server.tld/user
- WOODPECKER_MIN_AGENTS=0
- WOODPECKER_MAX_AGENTS=3
- WOODPECKER_WORKFLOWS_PER_AGENT=2 # the number of workflows each agent can run at the same time
- WOODEPCKER_GRPC_ADDR=https://grpc.your-woodpecker-server.tld # the grpc address of your woodpecker server, publicly accessible from the agents
- WOODEPCKER_GRPC_SECURE=true
- WOODPECKER_AGENT_ENV= # optional environment variables to pass to the agents
- WOODPECKER_PROVIDER=hetznercloud # set the provider, you can find all the available ones down below
- WOODPECKER_HETZNERCLOUD_API_TOKEN=${WOODPECKER_HETZNERCLOUD_API_TOKEN} # your api token for the Hetzner cloud
```

81
docs/versioned_docs/version-2.6/30-administration/90-prometheus.md Normal file
View File

@@ -0,0 +1,81 @@
# Prometheus
Woodpecker is compatible with Prometheus and exposes a `/metrics` endpoint if the environment variable `WOODPECKER_PROMETHEUS_AUTH_TOKEN` is set. Please note that access to the metrics endpoint is restricted and requires the authorization token from the environment variable mentioned above.
```yaml
global:
scrape_interval: 60s
scrape_configs:
- job_name: 'woodpecker'
bearer_token: dummyToken...
static_configs:
- targets: ['woodpecker.domain.com']
```
## Authorization
An administrator will need to generate a user API token and configure in the Prometheus configuration file as a bearer token. Please see the following example:
```diff
global:
scrape_interval: 60s
scrape_configs:
- job_name: 'woodpecker'
+ bearer_token: dummyToken...
static_configs:
- targets: ['woodpecker.domain.com']
```
As an alternative, the token can also be read from a file:
```diff
global:
scrape_interval: 60s
scrape_configs:
- job_name: 'woodpecker'
+ bearer_token_file: /etc/secrets/woodpecker-monitoring-token
static_configs:
- targets: ['woodpecker.domain.com']
```
## Metric Reference
List of Prometheus metrics specific to Woodpecker:
```yaml
# HELP woodpecker_pipeline_count 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="mkdocs",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3
# HELP woodpecker_pipeline_time Build time.
# TYPE woodpecker_pipeline_time gauge
woodpecker_pipeline_time{branch="main",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 116
woodpecker_pipeline_time{branch="mkdocs",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 155
# HELP woodpecker_pipeline_total_count Total number of builds.
# TYPE woodpecker_pipeline_total_count gauge
woodpecker_pipeline_total_count 1025
# HELP woodpecker_pending_steps Total number of pending pipeline steps.
# TYPE woodpecker_pending_steps gauge
woodpecker_pending_steps 0
# HELP woodpecker_repo_count Total number of repos.
# TYPE woodpecker_repo_count gauge
woodpecker_repo_count 9
# HELP woodpecker_running_steps Total number of running pipeline steps.
# TYPE woodpecker_running_steps gauge
woodpecker_running_steps 0
# HELP woodpecker_user_count Total number of users.
# TYPE woodpecker_user_count gauge
woodpecker_user_count 1
# HELP woodpecker_waiting_steps Total number of pipeline waiting on deps.
# 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
```

4
docs/versioned_docs/version-2.6/30-administration/_category_.yaml Normal file
View File

@@ -0,0 +1,4 @@
label: 'Administration'
# position: 3
collapsible: true
collapsed: true

BIN
docs/versioned_docs/version-2.6/30-administration/new-agent-connected.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.3 KiB

BIN
docs/versioned_docs/version-2.6/30-administration/new-agent-created.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.4 KiB

BIN
docs/versioned_docs/version-2.6/30-administration/new-agent-registration.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB