mirror of
https://github.com/woodpecker-ci/woodpecker.git
synced 2025-05-09 08:46:36 +00:00
Add docs for v3.5 release (#5049)
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
This commit is contained in:
Robert Kaussow
GitHub
parent
90e6efe162
commit
1c3c3f52ee
docs
versioned_docs
version-3.2
20-usage
30-administration
00-getting-started.md04-image-variants.md
05-deployment-methods
10-database.md10-server-config.md11-forges
22-backends
40-advanced
version-3.5
10-intro
20-usage
10-intro.md100-troubleshooting.md
15-terminology
architecture.excalidrawarchitecture.svgindex.mdpipeline-workflow-step.excalidrawpipeline-workflow-step.svg
20-workflow-syntax.md25-workflows.md30-matrix-workflows.md40-secrets.md41-registries.md45-cron.md50-environment.md51-plugins
60-services.md70-volumes.md72-linter.md75-project-settings.md80-badges.md90-advanced-usage.md_category_.yamlcron-settings.pnglinter-warnings-errors.pngpipeline.pngproject-settings.pngrepo-new.pngsecrets-plugins-filter.png30-administration
00-general.md
40-cli.md05-installation
10-configuration
10-server.md
_category_.yaml11-backends
12-forges
100-addon.md11-overview.md20-github.md30-gitea.md35-forgejo.md40-gitlab.md50-bitbucket.md60-bitbucket_datacenter.md_category_.yamlbitbucket_oauth.pngbitbucket_permissions.pnggitea_oauth.gifgithub_oauth.png
30-agent.md40-autoscaler.md_category_.yamlnew-agent-connected.pngnew-agent-created.pngnew-agent-registration.png92-development
versioned_sidebars
versions.json@ -1,156 +0,0 @@
|
||||
# Secrets
|
||||
|
||||
Woodpecker provides the ability to store named variables in a central secret store.
|
||||
These secrets can be passed securely to individual pipeline steps using the `from_secret` keyword.
|
||||
|
||||
Three different levels of secrets are available.
|
||||
The following list shows the priority of these.
|
||||
If a secret is defined in multiple levels, the following precedence applies: Repository secrets > Organization secrets > Global secrets.
|
||||
|
||||
1. **Repository secrets**: Available to all pipelines of a repository.
|
||||
1. **Organization secrets**: Available to all pipelines of an organization.
|
||||
1. **Global secrets**: Can only be set by instance admins.
|
||||
Global secret are available to all pipelines of the **entire** Woodpecker instance and should therefore be used with caution.
|
||||
|
||||
:::tip
|
||||
In addition to the native secret integration, external secret providers can be utilized by interacting with them directly within pipeline steps.
|
||||
Access to these providers can be configured using Woodpecker secrets, enabling the retrieval of secrets from the respective external sources.
|
||||
:::
|
||||
|
||||
:::warning
|
||||
Woodpecker can mask secrets from its native secret store, but it cannot apply the same protection to external secrets. As a result, these external secrets may be exposed in the pipeline logs.
|
||||
:::
|
||||
|
||||
## Usage
|
||||
|
||||
You can set a setting or environment value from Woodpecker secrets using the `from_secret` syntax.
|
||||
|
||||
The example below passes a secret called `secret_token` which will be stored in an environment variable named `TOKEN_ENV`:
|
||||
|
||||
```diff
|
||||
steps:
|
||||
- name: 'step name'
|
||||
image: registry/repo/image:tag
|
||||
commands:
|
||||
+ - echo "The secret is $TOKEN_ENV"
|
||||
+ environment:
|
||||
+ TOKEN_ENV:
|
||||
+ from_secret: secret_token
|
||||
```
|
||||
|
||||
The same syntax can be used to pass secrets to (plugin) settings.
|
||||
A secret named `secret_token` is assigned to the setting `TOKEN`, which will then be available in the plugin as environment variable `PLUGIN_TOKEN` (see [plugins](./51-plugins/20-creating-plugins.md#settings) for details).
|
||||
`PLUGIN_TOKEN` is then internally consumed by the plugin itself and will be honored during execution.
|
||||
|
||||
```diff
|
||||
steps:
|
||||
- name: 'step name'
|
||||
image: registry/repo/image:tag
|
||||
+ settings:
|
||||
+ TOKEN:
|
||||
+ from_secret: secret_token
|
||||
```
|
||||
|
||||
### Note about parameter pre-processing
|
||||
|
||||
Please note that parameter expressions undergo pre-processing, meaning they are evaluated before the pipeline starts.
|
||||
If secrets are to be used in expressions, they must be properly escaped (using `$$`) to ensure correct handling.
|
||||
|
||||
```diff
|
||||
steps:
|
||||
- name: docker
|
||||
image: docker
|
||||
commands:
|
||||
- - echo ${TOKEN_ENV}
|
||||
+ - echo $${TOKEN_ENV}
|
||||
environment:
|
||||
TOKEN_ENV:
|
||||
from_secret: secret_token
|
||||
```
|
||||
|
||||
### Use in Pull Requests events
|
||||
|
||||
By default, secrets are not exposed to pull requests.
|
||||
However, you can change this behavior by creating the secret and enabling the `pull_request` event type.
|
||||
This can be configured either through the UI or via the CLI, as demonstrated below.
|
||||
|
||||
:::warning
|
||||
Be cautious when exposing secrets to pull requests.
|
||||
If your repository is public and initiates pull request runs without requiring approval, your secrets may be at risk.
|
||||
Malicious actors could potentially exploit this to expose or transmit your secrets to an external location.
|
||||
:::
|
||||
|
||||
## Plugins filter
|
||||
|
||||
To prevent abusing your secrets from malicious usage, you can limit a secret to a list of plugins.
|
||||
If enabled they are not available to any other plugin (steps without user-defined commands).
|
||||
Plugins have the advantage that they cannot run arbitrary commands, hence they cannot be used to expose secrets (in contrast to arbitrary steps).
|
||||
|
||||
:::note
|
||||
If you specify a tag, the filter will honor it.
|
||||
However, if the same image appears multiple times in the list, the least privileged entry takes precedence.
|
||||
For example, an image without a tag will permit all tags, even if another entry with a pinned tag is included.
|
||||
:::
|
||||
|
||||
|
||||
|
||||
## Adding Secrets
|
||||
|
||||
Secrets can be added through the UI or via the CLI.
|
||||
|
||||
### CLI Examples
|
||||
|
||||
Create the secret using default settings.
|
||||
The secret will be available to all images in your pipeline, and will be available to all `push`, `tag`, and `deployment` events (not `pull_request` events).
|
||||
|
||||
```bash
|
||||
woodpecker-cli repo secret add \
|
||||
--repository octocat/hello-world \
|
||||
--name aws_access_key_id \
|
||||
--value <value>
|
||||
```
|
||||
|
||||
Create the secret and limit it to a single image:
|
||||
|
||||
```diff
|
||||
woodpecker-cli secret add \
|
||||
--repository octocat/hello-world \
|
||||
+ --image woodpeckerci/plugin-s3 \
|
||||
--name aws_access_key_id \
|
||||
--value <value>
|
||||
```
|
||||
|
||||
Create the secrets and limit it to a set of images:
|
||||
|
||||
```diff
|
||||
woodpecker-cli repo secret add \
|
||||
--repository octocat/hello-world \
|
||||
+ --image woodpeckerci/plugin-s3 \
|
||||
+ --image woodpeckerci/plugin-docker-buildx \
|
||||
--name aws_access_key_id \
|
||||
--value <value>
|
||||
```
|
||||
|
||||
Create the secret and enable it for multiple hook events:
|
||||
|
||||
```diff
|
||||
woodpecker-cli repo secret add \
|
||||
--repository octocat/hello-world \
|
||||
--image woodpeckerci/plugin-s3 \
|
||||
+ --event pull_request \
|
||||
+ --event push \
|
||||
+ --event tag \
|
||||
--name aws_access_key_id \
|
||||
--value <value>
|
||||
```
|
||||
|
||||
Secrets can be loaded from a file using the `@` syntax.
|
||||
This method is recommended for loading secrets from a file, as it ensures that newlines are preserved (this is for example important for SSH keys).
|
||||
Here’s an example:
|
||||
|
||||
```diff
|
||||
woodpecker-cli repo secret add \
|
||||
-repository octocat/hello-world \
|
||||
-name ssh_key \
|
||||
+ -value @/root/ssh/id_rsa
|
||||
```
|
||||
@ -1,59 +0,0 @@
|
||||
# Getting started
|
||||
|
||||
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 [workflow](../20-usage/15-terminology/index.md) by default. If you have 4 agents installed and connected to the Woodpecker server, your system will process four workflows (not pipelines) 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 per 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) resource 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. If you are not sure which one to choose, we recommend using the [docker compose](./05-deployment-methods/10-docker-compose.md) method for the beginning:
|
||||
|
||||
- Using [docker compose](./05-deployment-methods/10-docker-compose.md) with the official [container images](./05-deployment-methods/10-docker-compose.md#docker-images)
|
||||
- Using [Kubernetes](./05-deployment-methods/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)
|
||||
- Or using a [third-party installation method](./05-deployment-methods/30-third-party.md)
|
||||
|
||||
## Database
|
||||
|
||||
By default Woodpecker uses a SQLite database which requires zero installation or configuration. See the [database settings](./10-database.md) page if you want to use a different database system like MySQL or PostgreSQL.
|
||||
|
||||
## Forge
|
||||
|
||||
What would be a CI/CD system without any code? By connecting Woodpecker to your [forge](../20-usage/15-terminology/index.md) like GitHub or Gitea you can start running pipelines on events like pushes or pull requests. Woodpecker will also use your forge for authentication and to report back the status of your pipelines. See the [forge settings](./11-forges/11-overview.md) to connect it to Woodpecker.
|
||||
|
||||
## Configuration
|
||||
|
||||
Check the [server configuration](./10-server-config.md) and [agent configuration](./15-agent-config.md) pages to see if you need to adjust any additional parts and after that you should be ready to start with [your first pipeline](../20-usage/10-intro.md).
|
||||
|
||||
## Agent
|
||||
|
||||
The agent is the worker which executes the [workflows](../20-usage/15-terminology/index.md).
|
||||
Woodpecker agents can execute work using a [backend](../20-usage/15-terminology/index.md) like [docker](./22-backends/10-docker.md) or [kubernetes](./22-backends/40-kubernetes.md).
|
||||
By default if you choose to deploy an agent using [docker compose](./05-deployment-methods/10-docker-compose.md) the agent simply use docker for the backend as well.
|
||||
So nothing to worry about here. If you still prefer to adjust the agent to your needs, check the [agent configuration](./15-agent-config.md) page.
|
||||
@ -1,30 +0,0 @@
|
||||
# Image variants
|
||||
|
||||
:::info
|
||||
The `latest` tag has been deprecated as of v3.0 and will be completely removed in the future.
|
||||
This was done to prevent accidental major version upgrades.
|
||||
:::
|
||||
|
||||
- `vX.Y.Z`: SemVer tags for specific releases, no entrypoint shell (scratch image)
|
||||
- `vX.Y`
|
||||
- `vX`
|
||||
- `vX.Y.Z-alpine`: SemVer tags for specific releases, based on Alpine, rootless for Server and CLI (as of v3.0).
|
||||
- `vX.Y-alpine`
|
||||
- `vX-alpine`
|
||||
- `next`: Built from the `main` branch
|
||||
- `pull_<PR_ID>`: Images built from Pull Request branches.
|
||||
|
||||
## Image registries
|
||||
|
||||
Images are pushed to DockerHub and Quay.
|
||||
|
||||
[woodpecker-server (DockerHub)](https://hub.docker.com/r/docker/woodpeckerci/woodpecker-server)
|
||||
[woodpecker-server (Quay)](https://quay.io/repository/woodpeckerci/woodpecker-server)
|
||||
|
||||
[woodpecker-agent (DockerHub)](https://hub.docker.com/r/docker/woodpeckerci/woodpecker-agent)
|
||||
[woodpecker-agent (Quay)](https://quay.io/repository/woodpeckerci/woodpecker-agent)
|
||||
|
||||
[woodpecker-cli (DockerHub)](https://hub.docker.com/r/docker/woodpeckerci/woodpecker-cli)
|
||||
[woodpecker-cli (Quay)](https://quay.io/repository/woodpeckerci/woodpecker-cli)
|
||||
|
||||
[woodpecker-autoscaler (DockerHub)](https://hub.docker.com/r/docker/woodpeckerci/autoscaler)
|
||||
@ -1,140 +0,0 @@
|
||||
# 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"
|
||||
services:
|
||||
woodpecker-server:
|
||||
image: woodpeckerci/woodpecker-server:v3
|
||||
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:v3
|
||||
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"
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_HOST=${WOODPECKER_HOST}
|
||||
```
|
||||
|
||||
Woodpecker can also have its ports 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"
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR}
|
||||
+ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR}
|
||||
```
|
||||
|
||||
Reverse proxying can also be [configured for gRPC](../40-advanced/10-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"
|
||||
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"
|
||||
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"
|
||||
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"
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
|
||||
```
|
||||
|
||||
## Docker images
|
||||
|
||||
Image variants:
|
||||
|
||||
- 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 bug fixes asap
|
||||
- The `vX` same as `vX.X` variant but also includes feature releases
|
||||
- The `next` images are based on the current `main` branch
|
||||
|
||||
:::note
|
||||
The `latest` tag is not available on purpose (and has been dropped with the 3.x release) to prevent accidental major version upgrades.
|
||||
Hence, users are forced to specify a fixed or rolling tag, omitting the tag identifier (which equals to pulling `latest` implicitly) won't work.
|
||||
:::
|
||||
|
||||
```bash
|
||||
# server
|
||||
docker pull woodpeckerci/woodpecker-server:v3
|
||||
docker pull woodpeckerci/woodpecker-server:v3-alpine
|
||||
|
||||
# agent
|
||||
docker pull woodpeckerci/woodpecker-agent:v3
|
||||
docker pull woodpeckerci/woodpecker-agent:v3-alpine
|
||||
|
||||
# cli
|
||||
docker pull woodpeckerci/woodpecker-cli:v3
|
||||
docker pull woodpeckerci/woodpecker-cli:v3-alpine
|
||||
```
|
||||
@ -1,50 +0,0 @@
|
||||
# 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 sub-charts, `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).
|
||||
|
||||
## Metrics
|
||||
|
||||
Please see [Prometheus](../40-advanced/90-prometheus.md) for general information on configuration and usage.
|
||||
|
||||
For Kubernetes, you must set the following values when deploying via Helm chart to enable in-cluster metrics gathering:
|
||||
|
||||
```yaml
|
||||
metrics:
|
||||
enabled: true
|
||||
port: 9001
|
||||
```
|
||||
|
||||
This activates the `/metrics` endpoint on port `9001` without authentication. This port is not exposed externally by default. Use the instructions at [Prometheus](../40-advanced/90-prometheus.md) if you want to enable authenticated external access to metrics.
|
||||
|
||||
To enable Prometheus pod monitoring discovery, you must also make the following settings:
|
||||
|
||||
<!-- cspell:disable -->
|
||||
|
||||
```yaml
|
||||
prometheus:
|
||||
podmonitor:
|
||||
enabled: true
|
||||
interval: 60s
|
||||
labels: {}
|
||||
```
|
||||
|
||||
<!-- cspell:enable -->
|
||||
|
||||
### Troubleshooting Metrics
|
||||
|
||||
If you are not receiving metrics despite the steps above, ensure that in your Prometheus configuration either your namespace is explicitly configured in `podMonitorNamespaceSelector` or the selectors are disabled.
|
||||
|
||||
```yaml
|
||||
# Search all available namespaces
|
||||
podMonitorNamespaceSelector:
|
||||
matchLabels: {}
|
||||
# Enable all available pod monitors
|
||||
podMonitorSelector:
|
||||
matchLabels: {}
|
||||
```
|
||||
@ -1,12 +0,0 @@
|
||||
# Distribution packages
|
||||
|
||||
:::info
|
||||
Woodpecker itself is not responsible for creating these packages. Please reach out to the people responsible for packaging Woodpecker for the individual distributions.
|
||||
:::
|
||||
|
||||
- [NixOS](./40-nixos.md) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker)
|
||||
- [Alpine (Edge)](https://pkgs.alpinelinux.org/packages?name=woodpecker&branch=edge&repo=&arch=&maintainer=)
|
||||
- [Arch Linux](https://archlinux.org/packages/?q=woodpecker)
|
||||
- [openSUSE](https://software.opensuse.org/package/woodpecker)
|
||||
- [YunoHost](https://apps.yunohost.org/app/woodpecker)
|
||||
- [Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html)
|
||||
@ -1,90 +0,0 @@
|
||||
# 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
|
||||
|
||||
<!-- cspell:words Optimisation -->
|
||||
|
||||
```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](/awesome) page, like using the runners nix-store in the pipeline.
|
||||
@ -1,51 +0,0 @@
|
||||
# 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"
|
||||
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.
|
||||
@ -1,587 +0,0 @@
|
||||
---
|
||||
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=john.smith,jane_doe
|
||||
```
|
||||
|
||||
### Only allow registration of users, who are members of approved organizations
|
||||
|
||||
```ini
|
||||
WOODPECKER_OPEN=true
|
||||
WOODPECKER_ORGS=dolores,dog-patch
|
||||
```
|
||||
|
||||
## Administrators
|
||||
|
||||
Administrators should also be enumerated in your configuration.
|
||||
|
||||
```ini
|
||||
WOODPECKER_ADMIN=john.smith,jane_doe
|
||||
```
|
||||
|
||||
## Filtering repositories
|
||||
|
||||
Woodpecker operates with the user's OAuth permission. Due to the coarse permission handling of GitHub, you may end up syncing more repos into Woodpecker than preferred.
|
||||
|
||||
Use the `WOODPECKER_REPO_OWNERS` variable to filter which GitHub user's repos should be synced only. You typically want to put here your company's GitHub name.
|
||||
|
||||
```ini
|
||||
WOODPECKER_REPO_OWNERS=my_company,my_company_oss_github_user
|
||||
```
|
||||
|
||||
## Disallow normal users to create agents
|
||||
|
||||
By default, users can create new agents for their repos they have admin access to.
|
||||
If an instance admin doesn't want this feature enabled, they can disable the API and hide the Web UI elements.
|
||||
|
||||
:::note
|
||||
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.
|
||||
:::
|
||||
|
||||
```ini
|
||||
WOODPECKER_DISABLE_USER_AGENT_REGISTRATION=true
|
||||
```
|
||||
|
||||
## Global registry setting
|
||||
|
||||
If you want to make available a specific private registry to all pipelines, use the `WOODPECKER_DOCKER_CONFIG` server configuration.
|
||||
Point it to your server's docker config.
|
||||
|
||||
```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"
|
||||
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 your preferred lightweight JavaScript library here ...
|
||||
!(function () {
|
||||
'use strict';
|
||||
function e() {} /*...*/
|
||||
})();
|
||||
|
||||
$().ready(function () {
|
||||
$('.app nav img').first().htmlAfter("<div class='banner-message'>This is a demo banner message :)</div>");
|
||||
});
|
||||
```
|
||||
|
||||
## All server configuration options
|
||||
|
||||
The following list describes all available server configuration options.
|
||||
|
||||
### `WOODPECKER_LOG_LEVEL`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty.
|
||||
|
||||
### `WOODPECKER_LOG_FILE`
|
||||
|
||||
> Default: `stderr`
|
||||
|
||||
Output destination for logs.
|
||||
'stdout' and 'stderr' can be used as special keywords.
|
||||
|
||||
### `WOODPECKER_DATABASE_LOG`
|
||||
|
||||
> Default: `false`
|
||||
|
||||
Enable logging in database engine (currently xorm).
|
||||
|
||||
### `WOODPECKER_DATABASE_LOG_SQL`
|
||||
|
||||
> Default: `false`
|
||||
|
||||
Enable logging of sql commands.
|
||||
|
||||
### `WOODPECKER_DATABASE_MAX_CONNECTIONS`
|
||||
|
||||
> Default: `100`
|
||||
|
||||
Max database connections xorm is allowed create.
|
||||
|
||||
### `WOODPECKER_DATABASE_IDLE_CONNECTIONS`
|
||||
|
||||
> Default: `2`
|
||||
|
||||
Amount of database connections xorm will hold open.
|
||||
|
||||
### `WOODPECKER_DATABASE_CONNECTION_TIMEOUT`
|
||||
|
||||
> Default: `3 Seconds`
|
||||
|
||||
Time an active database connection is allowed to stay open.
|
||||
|
||||
### `WOODPECKER_DEBUG_PRETTY`
|
||||
|
||||
> Default: `false`
|
||||
|
||||
Enable pretty-printed debug output.
|
||||
|
||||
### `WOODPECKER_DEBUG_NOCOLOR`
|
||||
|
||||
> Default: `true`
|
||||
|
||||
Disable colored debug output.
|
||||
|
||||
### `WOODPECKER_HOST`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Server fully qualified URL of the user-facing hostname, port (if not default for HTTP/HTTPS) and path prefix.
|
||||
|
||||
Examples:
|
||||
|
||||
- `WOODPECKER_HOST=http://woodpecker.example.org`
|
||||
- `WOODPECKER_HOST=http://example.org/woodpecker`
|
||||
- `WOODPECKER_HOST=http://example.org:1234/woodpecker`
|
||||
|
||||
### `WOODPECKER_SERVER_ADDR`
|
||||
|
||||
> Default: `:8000`
|
||||
|
||||
Configures the HTTP listener port.
|
||||
|
||||
### `WOODPECKER_SERVER_ADDR_TLS`
|
||||
|
||||
> Default: `:443`
|
||||
|
||||
Configures the HTTPS listener port when SSL is enabled.
|
||||
|
||||
### `WOODPECKER_SERVER_CERT`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Path to an SSL certificate used by the server to accept HTTPS requests.
|
||||
|
||||
Example: `WOODPECKER_SERVER_CERT=/path/to/cert.pem`
|
||||
|
||||
### `WOODPECKER_SERVER_KEY`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Path to an SSL certificate key used by the server to accept HTTPS requests.
|
||||
|
||||
Example: `WOODPECKER_SERVER_KEY=/path/to/key.pem`
|
||||
|
||||
### `WOODPECKER_CUSTOM_CSS_FILE`
|
||||
|
||||
> Default: empty
|
||||
|
||||
File path for the server to serve a custom .CSS file, used for customizing the UI.
|
||||
Can be used for showing banner messages, logos, or environment-specific hints (a.k.a. white-labeling).
|
||||
The file must be UTF-8 encoded, to ensure all special characters are preserved.
|
||||
|
||||
Example: `WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.css`
|
||||
|
||||
### `WOODPECKER_CUSTOM_JS_FILE`
|
||||
|
||||
> Default: empty
|
||||
|
||||
File path for the server to serve a custom .JS file, used for customizing the UI.
|
||||
Can be used for showing banner messages, logos, or environment-specific hints (a.k.a. white-labeling).
|
||||
The file must be UTF-8 encoded, to ensure all special characters are preserved.
|
||||
|
||||
Example: `WOODPECKER_CUSTOM_JS_FILE=/usr/local/www/woodpecker.js`
|
||||
|
||||
### `WOODPECKER_GRPC_ADDR`
|
||||
|
||||
> Default: `:9000`
|
||||
|
||||
Configures the gRPC listener port.
|
||||
|
||||
### `WOODPECKER_GRPC_SECRET`
|
||||
|
||||
> Default: `secret`
|
||||
|
||||
Configures the gRPC JWT secret.
|
||||
|
||||
### `WOODPECKER_GRPC_SECRET_FILE`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Read the value for `WOODPECKER_GRPC_SECRET` from the specified filepath.
|
||||
|
||||
### `WOODPECKER_METRICS_SERVER_ADDR`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Configures an unprotected metrics endpoint. An empty value disables the metrics endpoint completely.
|
||||
|
||||
Example: `:9001`
|
||||
|
||||
### `WOODPECKER_ADMIN`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Comma-separated list of admin accounts.
|
||||
|
||||
Example: `WOODPECKER_ADMIN=user1,user2`
|
||||
|
||||
### `WOODPECKER_ORGS`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Comma-separated list of approved organizations.
|
||||
|
||||
Example: `org1,org2`
|
||||
|
||||
### `WOODPECKER_REPO_OWNERS`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Repositories by those owners will be allowed to be used in woodpecker.
|
||||
|
||||
Example: `user1,user2`
|
||||
|
||||
### `WOODPECKER_OPEN`
|
||||
|
||||
> Default: `false`
|
||||
|
||||
Enable to allow user registration.
|
||||
|
||||
### `WOODPECKER_AUTHENTICATE_PUBLIC_REPOS`
|
||||
|
||||
> Default: `false`
|
||||
|
||||
Always use authentication to clone repositories even if they are public. Needed if the forge requires to always authenticate as used by many companies.
|
||||
|
||||
### `WOODPECKER_DEFAULT_ALLOW_PULL_REQUESTS`
|
||||
|
||||
> Default: `true`
|
||||
|
||||
The default setting for allowing pull requests on a repo.
|
||||
|
||||
### `WOODPECKER_DEFAULT_CANCEL_PREVIOUS_PIPELINE_EVENTS`
|
||||
|
||||
> Default: `pull_request, push`
|
||||
|
||||
List of event names that will be canceled when a new pipeline for the same context (tag, branch) is created.
|
||||
|
||||
### `WOODPECKER_DEFAULT_CLONE_PLUGIN`
|
||||
|
||||
> Default is defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go)
|
||||
|
||||
The default docker image to be used when cloning the repo.
|
||||
|
||||
It is also added to the trusted clone plugin list.
|
||||
|
||||
### `WOODPECKER_DEFAULT_WORKFLOW_LABELS`
|
||||
|
||||
> By default run workflows on any agent if no label conditions are set in workflow definition.
|
||||
|
||||
You can specify default label/platform conditions that will be used for agent selection for workflows that does not have labels conditions set.
|
||||
|
||||
Example: `platform=linux/amd64,backend=docker`
|
||||
|
||||
### `WOODPECKER_DEFAULT_PIPELINE_TIMEOUT`
|
||||
|
||||
> 60 (minutes)
|
||||
|
||||
The default time for a repo in minutes before a pipeline gets killed
|
||||
|
||||
### `WOODPECKER_MAX_PIPELINE_TIMEOUT`
|
||||
|
||||
> 120 (minutes)
|
||||
|
||||
The maximum time in minutes you can set in the repo settings before a pipeline gets killed
|
||||
|
||||
### `WOODPECKER_SESSION_EXPIRES`
|
||||
|
||||
> Default: `72h`
|
||||
|
||||
Configures the session expiration time.
|
||||
Context: when someone does log into Woodpecker, a temporary session token is created.
|
||||
As long as the session is valid (until it expires or log-out),
|
||||
a user can log into Woodpecker, without re-authentication.
|
||||
|
||||
### `WOODPECKER_PLUGINS_PRIVILEGED`
|
||||
|
||||
Docker images to run in privileged mode. Only change if you are sure what you do!
|
||||
|
||||
You should specify the tag of your images too, as this enforces exact matches.
|
||||
|
||||
### WOODPECKER_PLUGINS_TRUSTED_CLONE
|
||||
|
||||
> Defaults are defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go)
|
||||
|
||||
Plugins which are trusted to handle the Git credential info in clone steps.
|
||||
If a clone step use an image not in this list, Git credentials will not be injected and users have to use other methods (e.g. secrets) to clone non-public repos.
|
||||
|
||||
You should specify the tag of your images too, as this enforces exact matches.
|
||||
|
||||
<!--
|
||||
### `WOODPECKER_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_DISABLE_USER_AGENT_REGISTRATION`
|
||||
|
||||
> Default: false
|
||||
|
||||
[Read about "Disallow normal users to create agents"](./10-server-config.md#disallow-normal-users-to-create-agents)
|
||||
|
||||
### `WOODPECKER_KEEPALIVE_MIN_TIME`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Server-side enforcement policy on the minimum amount of time a client should wait before sending a keepalive ping.
|
||||
|
||||
Example: `WOODPECKER_KEEPALIVE_MIN_TIME=10s`
|
||||
|
||||
### `WOODPECKER_DATABASE_DRIVER`
|
||||
|
||||
> Default: `sqlite3`
|
||||
|
||||
The database driver name. Possible values are `sqlite3`, `mysql` or `postgres`.
|
||||
|
||||
### `WOODPECKER_DATABASE_DATASOURCE`
|
||||
|
||||
> Default: `woodpecker.sqlite` if not running inside a container, `/var/lib/woodpecker/woodpecker.sqlite` if running inside a container
|
||||
|
||||
The database connection string. The default value is the path of the embedded SQLite database file.
|
||||
|
||||
Example:
|
||||
|
||||
```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_CONFIG_SERVICE_ENDPOINT`
|
||||
|
||||
> Default: empty
|
||||
|
||||
Specify a configuration service endpoint, see [Configuration Extension](./40-advanced/100-external-configuration-api.md)
|
||||
|
||||
### `WOODPECKER_FORGE_TIMEOUT`
|
||||
|
||||
> Default: 5s
|
||||
|
||||
Specify timeout when fetching the Woodpecker configuration from forge. See <https://pkg.go.dev/time#ParseDuration> for syntax reference.
|
||||
|
||||
### `WOODPECKER_FORGE_RETRY`
|
||||
|
||||
> Default: 3
|
||||
|
||||
Specify how many retries of fetching the Woodpecker configuration from a forge are done before we fail.
|
||||
|
||||
### `WOODPECKER_ENABLE_SWAGGER`
|
||||
|
||||
> Default: true
|
||||
|
||||
Enable the Swagger UI for API documentation.
|
||||
|
||||
### `WOODPECKER_DISABLE_VERSION_CHECK`
|
||||
|
||||
> Default: false
|
||||
|
||||
Disable version check in admin web UI.
|
||||
|
||||
### `WOODPECKER_LOG_STORE`
|
||||
|
||||
> Default: `database`
|
||||
|
||||
Where to store logs. Possible values: `database` or `file`.
|
||||
|
||||
### `WOODPECKER_LOG_STORE_FILE_PATH`
|
||||
|
||||
> Default empty
|
||||
|
||||
Directory to store logs in if [`WOODPECKER_LOG_STORE`](#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).
|
||||
@ -1,15 +0,0 @@
|
||||
# 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: |
|
||||
|
||||
¹ The deployment event can be triggered for all forges from Woodpecker directly. However, only GitHub can trigger them using webhooks.
|
||||
@ -1,23 +0,0 @@
|
||||
# Custom backends
|
||||
|
||||
If none of our backends fits your usecase, you can write your own.
|
||||
|
||||
Therefore, implement the interface `"go.woodpecker-ci.org/woodpecker/woodpecker/v3/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/v3/cmd/agent/core"
|
||||
backendTypes "go.woodpecker-ci.org/woodpecker/v3/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.
|
||||
@ -1,201 +0,0 @@
|
||||
# Proxy
|
||||
|
||||
## Apache
|
||||
|
||||
This guide provides a brief overview for installing Woodpecker server behind the Apache2 web-server. This is an example configuration:
|
||||
|
||||
<!-- cspell:ignore apacheconf -->
|
||||
|
||||
```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
|
||||
woodpecker-agent.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.
|
||||
|
||||
<!-- cspell:words redirectscheme certresolver -->
|
||||
|
||||
```yaml
|
||||
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.your-domain.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(`cd.your-domain.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.your-domain.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.your-domain.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.
|
||||
@ -1,103 +0,0 @@
|
||||
# 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/rfc9421) 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-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
|
||||
|
||||
```json
|
||||
{
|
||||
"configs": [
|
||||
{
|
||||
"name": "central-override",
|
||||
"data": "steps:\n - name: backend\n image: alpine\n commands:\n - echo \"Hello there from ConfigAPI\"\n"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
@ -1,54 +0,0 @@
|
||||
# SSL
|
||||
|
||||
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"
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
ports:
|
||||
+ - 80:80
|
||||
+ - 443:443
|
||||
- 9000:9000
|
||||
```
|
||||
|
||||
Update your configuration to mount your certificate and key:
|
||||
|
||||
```diff title="docker-compose.yaml"
|
||||
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"
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
+ - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
|
||||
+ - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key
|
||||
```
|
||||
@ -1,25 +0,0 @@
|
||||
# Advanced options
|
||||
|
||||
Why should we be happy with a default setup? We should not! Woodpecker offers a lot of advanced options to configure it to your needs.
|
||||
|
||||
## Behind a proxy
|
||||
|
||||
See the [proxy guide](./10-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).
|
||||
|
||||
## SSL
|
||||
|
||||
Woodpecker supports SSL configuration by using Let's encrypt or by using own certificates. See the [SSL guide](./20-ssl.md).
|
||||
|
||||
## Metrics
|
||||
|
||||
A [Prometheus endpoint](./90-prometheus.md) is exposed by Woodpecker to collect metrics.
|
||||
|
||||
## Autoscaling
|
||||
|
||||
The [autoscaler](./30-autoscaler.md) can be used to deploy new agents to a cloud provider based on the current workload your server is experiencing.
|
||||
|
||||
## Configuration service
|
||||
|
||||
Sometime the normal yaml configuration compiler isn't enough. You can use the [configuration service](./100-external-configuration-api.md) to process your configuration files by your own.
|
||||
@ -1,81 +0,0 @@
|
||||
# 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="dev",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="dev",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
|
||||
```
|
||||
@ -1,6 +0,0 @@
|
||||
label: 'Advanced'
|
||||
collapsible: true
|
||||
collapsed: true
|
||||
link:
|
||||
type: 'doc'
|
||||
id: 'advanced'
|
||||
@ -23,4 +23,4 @@ Then you might want to jump directly into it and [start creating your first pipe
|
||||
|
||||
## Want to start from scratch and deploy your own Woodpecker instance?
|
||||
|
||||
Woodpecker is [pretty lightweight](../30-administration/00-getting-started.md#hardware-requirements) and will even run on your Raspberry Pi. You can follow the [deployment guide](../30-administration/00-getting-started.md) to set up your own Woodpecker instance.
|
||||
Woodpecker is lightweight and even runs on a Raspberry Pi. You can follow the [deployment guide](../30-administration/00-general.md) to set up your own Woodpecker instance.
|
||||
@ -83,20 +83,20 @@ the same workspace it can use the previously built binary and test it.
|
||||
|
||||
Sometimes you have some tasks that you need to do in every project. For example, deploying to Kubernetes or sending a Slack message. Therefore you can use one of the [official and community plugins](/plugins) or simply [create your own](./51-plugins/20-creating-plugins.md).
|
||||
|
||||
If you want to get a Slack notification after your pipeline has finished, you can add a Slack plugin to your pipeline:
|
||||
If you want to publish a file to an S3 bucket, you can add an S3 plugin to your pipeline:
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
# ...
|
||||
- name: notify me on Slack
|
||||
image: plugins/slack
|
||||
- name: upload
|
||||
image: woodpeckerci/plugin-s3
|
||||
settings:
|
||||
channel: developers
|
||||
username: woodpecker
|
||||
password:
|
||||
from_secret: slack_token
|
||||
when:
|
||||
status: [success, failure] # This will execute the step on success and failure
|
||||
bucket: my-bucket-name
|
||||
access_key: a50d28f4dd477bc184fbd10b376de753
|
||||
secret_key:
|
||||
from_secret: aws_secret_key
|
||||
source: public/**/*
|
||||
target: /target/location
|
||||
```
|
||||
|
||||
To configure a plugin you can use the `settings` section.
|
||||
|
Before 
(image error) Size: 31 KiB After 
(image error) Size: 31 KiB
|
@ -47,9 +47,9 @@ Sometimes there are multiple terms that can be used to describe something. This
|
||||
[Event]: ../20-workflow-syntax.md#event
|
||||
[Pipeline]: ../20-workflow-syntax.md
|
||||
[Workflow]: ../25-workflows.md
|
||||
[Forge]: ../../30-administration/11-forges/11-overview.md
|
||||
[Forge]: ../../30-administration/10-configuration/12-forges/11-overview.md
|
||||
[Plugin]: ../51-plugins/51-overview.md
|
||||
[Workspace]: ../20-workflow-syntax.md#workspace
|
||||
[Matrix]: ../30-matrix-workflows.md
|
||||
[Docker]: ../../30-administration/22-backends/10-docker.md
|
||||
[Local]: ../../30-administration/22-backends/20-local.md
|
||||
[Docker]: ../../30-administration/10-configuration/11-backends/10-docker.md
|
||||
[Local]: ../../30-administration/10-configuration/11-backends/30-local.md
|
||||
|
Before 
(image error) Size: 21 KiB After 
(image error) Size: 21 KiB
|
@ -200,10 +200,8 @@ A condition can be a check like:
|
||||
|
||||
```diff
|
||||
steps:
|
||||
- name: slack
|
||||
image: plugins/slack
|
||||
settings:
|
||||
channel: dev
|
||||
- name: prettier
|
||||
image: woodpeckerci/plugin-prettier
|
||||
+ when:
|
||||
+ - event: pull_request
|
||||
+ repo: test/test
|
||||
@ -211,7 +209,7 @@ A condition can be a check like:
|
||||
+ branch: main
|
||||
```
|
||||
|
||||
The `slack` step is executed if one of these conditions is met:
|
||||
The `prettier` step is executed if one of these conditions is met:
|
||||
|
||||
1. The pipeline is executed from a pull request in the repo `test/test`
|
||||
2. The pipeline is executed from a push to `main`
|
||||
@ -222,10 +220,8 @@ Example conditional execution by repository:
|
||||
|
||||
```diff
|
||||
steps:
|
||||
- name: slack
|
||||
image: plugins/slack
|
||||
settings:
|
||||
channel: dev
|
||||
- name: prettier
|
||||
image: woodpeckerci/plugin-prettier
|
||||
+ when:
|
||||
+ - repo: test/test
|
||||
```
|
||||
@ -240,10 +236,8 @@ Example conditional execution by branch:
|
||||
|
||||
```diff
|
||||
steps:
|
||||
- name: slack
|
||||
image: plugins/slack
|
||||
settings:
|
||||
channel: dev
|
||||
- name: prettier
|
||||
image: woodpeckerci/plugin-prettier
|
||||
+ when:
|
||||
+ - branch: main
|
||||
```
|
||||
@ -342,14 +336,12 @@ when:
|
||||
|
||||
#### `status`
|
||||
|
||||
There are use cases for executing steps on failure, such as sending notifications for failed workflow / pipeline. Use the status constraint to execute steps even when the workflow fails:
|
||||
There are use cases for executing steps on failure, such as sending notifications for failed workflow/pipeline. Use the status constraint to execute steps even when the workflow fails:
|
||||
|
||||
```diff
|
||||
steps:
|
||||
- name: slack
|
||||
image: plugins/slack
|
||||
settings:
|
||||
channel: dev
|
||||
- name: notify
|
||||
image: alpine
|
||||
+ when:
|
||||
+ - status: [ success, failure ]
|
||||
```
|
||||
@ -602,12 +594,16 @@ For more details check the [matrix build docs](./30-matrix-workflows.md).
|
||||
|
||||
## `labels`
|
||||
|
||||
You can set labels for your workflow to select an agent to execute the workflow on. An agent will pick up and run a workflow when **every** label assigned to it matches the agents labels.
|
||||
You can define labels for your workflow in order to select an agent to execute the workflow. An agent takes up a workflow and executes it if **every** label assigned to it matches the label of the agent.
|
||||
|
||||
To set additional agent labels, check the [agent configuration options](../30-administration/15-agent-config.md#woodpecker_agent_labels). Agents will have at least four default labels: `platform=agent-os/agent-arch`, `hostname=my-agent`, `backend=docker` (type of the agent backend) and `repo=*`. Agents can use a `*` as a wildcard for a label. For example `repo=*` will match every repo.
|
||||
To specify additional agent labels, check the [Agent configuration options] (../30-administration/10-configuration/30-agent.md#agent_labels). The agents have at least four default labels: `platform=agent-os/agent-arch`, `hostname=my-agent`, `backend=docker` (type of agent backend) and `repo=*`. Agents can use an `*` as a placeholder for a label. For example, `repo=*` matches any repo.
|
||||
|
||||
Workflow labels with an empty value will be ignored.
|
||||
By default, each workflow has at least the `repo=your-user/your-repo-name` label. If you have set the [platform attribute](#platform) for your workflow it will have a label like `platform=your-os/your-arch` as well.
|
||||
Workflow labels with an empty value are ignored.
|
||||
By default, each workflow has at least the label `repo=your-user/your-repo-name`. If you have set the [platform attribute](#platform) for your workflow, it will also have a label such as `platform=your-os/your-arch`.
|
||||
|
||||
:::warning
|
||||
Labels with the `woodpecker-ci.org` prefix are managed by Woodpecker and can not be set as part of the pipeline definition.
|
||||
:::
|
||||
|
||||
You can add additional labels as a key value map:
|
||||
|
||||
@ -733,10 +729,8 @@ Example conditional execution by branch:
|
||||
+ branch: main
|
||||
+
|
||||
steps:
|
||||
- name: slack
|
||||
image: plugins/slack
|
||||
settings:
|
||||
channel: dev
|
||||
- name: prettier
|
||||
image: woodpeckerci/plugin-prettier
|
||||
```
|
||||
|
||||
The workflow now triggers on `main`, but also if the target branch of a pull request is `main`.
|
||||
@ -139,5 +139,5 @@ steps:
|
||||
```
|
||||
|
||||
:::note
|
||||
If you want to control the architecture of a pipeline on a Kubernetes runner, see [the nodeSelector documentation of the Kubernetes backend](../30-administration/22-backends/40-kubernetes.md#node-selector).
|
||||
If you want to control the architecture of a pipeline on a Kubernetes runner, see [the nodeSelector documentation of the Kubernetes backend](../30-administration/10-configuration/11-backends/20-kubernetes.md#node-selector).
|
||||
:::
|
||||
148
docs/versioned_docs/version-3.5/20-usage/40-secrets.md
Normal file
148
docs/versioned_docs/version-3.5/20-usage/40-secrets.md
Normal file
@ -0,0 +1,148 @@
|
||||
# Secrets
|
||||
|
||||
Woodpecker provides the ability to store named variables in a central secret store.
|
||||
These secrets can be securely passed on to individual pipeline steps using the keyword `from_secret`.
|
||||
|
||||
There are three different levels of secrets available. If a secret is defined in multiple levels, the following order of priority applies (last wins):
|
||||
|
||||
1. **Repository secrets**: Available for all pipelines of a repository.
|
||||
1. **Organization secrets**: Available for all pipelines of an organization.
|
||||
1. **Global secrets**: Can only be set by instance administrators.
|
||||
Global secrets are available for all pipelines of the **entire** Woodpecker instance and should therefore be used with caution.
|
||||
|
||||
In addition to the native integration of secrets, external providers of secrets can also be used by interacting with them directly within pipeline steps. Access to these providers can be configured with Woodpecker secrets, which enables the retrieval of secrets from the respective external sources.
|
||||
|
||||
:::warning
|
||||
Woodpecker can mask secrets from its own secrets store, but it cannot apply the same protection to external secrets. As a result, these external secrets can be exposed in the pipeline logs.
|
||||
:::
|
||||
|
||||
## Usage
|
||||
|
||||
You can set a setting or environment value from Woodpecker secrets by using the `from_secret` syntax.
|
||||
|
||||
The following example passes a secret called `secret_token` which is stored in an environment variable called `TOKEN_ENV`:
|
||||
|
||||
```diff
|
||||
steps:
|
||||
- name: 'step name'
|
||||
image: registry/repo/image:tag
|
||||
commands:
|
||||
+ - echo "The secret is $TOKEN_ENV"
|
||||
+ environment:
|
||||
+ TOKEN_ENV:
|
||||
+ from_secret: secret_token
|
||||
```
|
||||
|
||||
The same syntax can be used to pass secrets to (plugin) settings.
|
||||
A secret called `secret_token` is assigned to the setting `TOKEN`, which is then available in the plugin as the environment variable `PLUGIN_TOKEN` (see [plugins](./51-plugins/20-creating-plugins.md#settings) for details).
|
||||
`PLUGIN_TOKEN` is then used internally by the plugin itself and taken into account during execution.
|
||||
|
||||
```diff
|
||||
steps:
|
||||
- name: 'step name'
|
||||
image: registry/repo/image:tag
|
||||
+ settings:
|
||||
+ TOKEN:
|
||||
+ from_secret: secret_token
|
||||
```
|
||||
|
||||
### Escape secrets
|
||||
|
||||
Please note that parameter expressions are preprocessed, i.e. they are evaluated before the pipeline starts.
|
||||
If secrets are to be used in expressions, they must be properly escaped (with `$$`) to ensure correct processing.
|
||||
|
||||
```diff
|
||||
steps:
|
||||
- name: docker
|
||||
image: docker
|
||||
commands:
|
||||
- - echo ${TOKEN_ENV}
|
||||
+ - echo $${TOKEN_ENV}
|
||||
environment:
|
||||
TOKEN_ENV:
|
||||
from_secret: secret_token
|
||||
```
|
||||
|
||||
### Events filter
|
||||
|
||||
By default, secrets are not exposed to pull requests.
|
||||
However, you can change this behavior by creating the secret and enabling the `pull_request` event type.
|
||||
This can be configured either via the UI or via the CLI.
|
||||
|
||||
:::warning
|
||||
Be careful when exposing secrets for pull requests.
|
||||
If your repository is public and accepts pull requests from everyone, your secrets may be at risk.
|
||||
Malicious actors could take advantage of this to expose your secrets or transfer them to an external location.
|
||||
:::
|
||||
|
||||
### Plugins filter
|
||||
|
||||
To prevent your secrets from being misused by malicious users, you can restrict a secret to a list of plugins.
|
||||
If enabled, they are not available to any other plugins.
|
||||
Plugins have the advantage that they cannot execute arbitrary commands and therefore cannot reveal secrets.
|
||||
|
||||
:::tip
|
||||
If you specify a tag, the filter will take it into account.
|
||||
However, if the same image appears several times in the list, the least privileged entry will take precedence.
|
||||
For example, an image without a tag will allow all tags, even if it contains another entry with a tag attached.
|
||||
:::
|
||||
|
||||
|
||||
|
||||
## CLI
|
||||
|
||||
In addition to the UI, secrets can also be managed using the CLI.
|
||||
|
||||
Create the secret with the default settings.
|
||||
The secret is available for all images in your pipeline and for all `push`, `tag` and `deployment` events (not for `pull_request` events).
|
||||
|
||||
```bash
|
||||
woodpecker-cli repo secret add \
|
||||
--repository octocat/hello-world \
|
||||
--name aws_access_key_id \
|
||||
--value <value>
|
||||
```
|
||||
|
||||
Create the secret and limit it to a single image:
|
||||
|
||||
```diff
|
||||
woodpecker-cli secret add \
|
||||
--repository octocat/hello-world \
|
||||
+ --image woodpeckerci/plugin-s3 \
|
||||
--name aws_access_key_id \
|
||||
--value <value>
|
||||
```
|
||||
|
||||
Create the secrets and limit it to a set of images:
|
||||
|
||||
```diff
|
||||
woodpecker-cli repo secret add \
|
||||
--repository octocat/hello-world \
|
||||
+ --image woodpeckerci/plugin-s3 \
|
||||
+ --image woodpeckerci/plugin-docker-buildx \
|
||||
--name aws_access_key_id \
|
||||
--value <value>
|
||||
```
|
||||
|
||||
Create the secret and enable it for multiple hook events:
|
||||
|
||||
```diff
|
||||
woodpecker-cli repo secret add \
|
||||
--repository octocat/hello-world \
|
||||
--image woodpeckerci/plugin-s3 \
|
||||
+ --event pull_request \
|
||||
+ --event push \
|
||||
+ --event tag \
|
||||
--name aws_access_key_id \
|
||||
--value <value>
|
||||
```
|
||||
|
||||
Secrets can be loaded from a file using the syntax `@`.
|
||||
This method is recommended for loading secrets from a file, as it ensures that line breaks are preserved (this is important for SSH keys, for example):
|
||||
|
||||
```diff
|
||||
woodpecker-cli repo secret add \
|
||||
-repository octocat/hello-world \
|
||||
-name ssh_key \
|
||||
+ -value @/root/ssh/id_rsa
|
||||
```
|
||||
@ -37,7 +37,7 @@ Example registry hostname matching logic:
|
||||
|
||||
## Global registry support
|
||||
|
||||
To make a private registry globally available, check the [server configuration docs](../30-administration/10-server-config.md#global-registry-setting).
|
||||
To make a private registry globally available, check the [server configuration docs](../30-administration/10-configuration/10-server.md#docker_config).
|
||||
|
||||
## GCR registry support
|
||||
|
||||
@ -23,7 +23,7 @@ steps:
|
||||
template: config/k8s/service.yaml
|
||||
```
|
||||
|
||||
Example pipeline using the Docker and Slack plugins:
|
||||
Example pipeline using the Docker and Prettier plugins:
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
@ -33,16 +33,14 @@ steps:
|
||||
- go build
|
||||
- go test
|
||||
|
||||
- name: prettier
|
||||
image: woodpeckerci/plugin-prettier
|
||||
|
||||
- name: publish
|
||||
image: woodpeckerci/plugin-kaniko
|
||||
settings:
|
||||
repo: foo/bar
|
||||
tags: latest
|
||||
|
||||
- name: notify
|
||||
image: plugins/slack
|
||||
settings:
|
||||
channel: dev
|
||||
```
|
||||
|
||||
## Plugin Isolation
|
||||
|
Before 
(image error) Size: 40 KiB After 
(image error) Size: 40 KiB
|
|
Before 
(image error) Size: 113 KiB After 
(image error) Size: 113 KiB
|
|
Before 
(image error) Size: 430 KiB After 
(image error) Size: 430 KiB
|
|
Before 
(image error) Size: 353 KiB After 
(image error) Size: 353 KiB
|
|
Before 
(image error) Size: 351 KiB After 
(image error) Size: 351 KiB
|
|
Before 
(image error) Size: 29 KiB After 
(image error) Size: 29 KiB
|
@ -0,0 +1,43 @@
|
||||
# General
|
||||
|
||||
Woodpecker consists of essential components (`server` and `agent`) and an optional component (`autoscaler`).
|
||||
|
||||
The **server** provides the user interface, processes webhook requests to the underlying forge, serves the API and analyzes the pipeline configurations from the YAML files.
|
||||
|
||||
The **agent** executes the [workflows](../20-usage/15-terminology/index.md) via a specific [backend](../20-usage/15-terminology/index.md) (Docker, Kubernetes, local) and connects to the server via GRPC. Multiple agents can coexist so that the job limits, choice of backend and other agent-related settings can be fine-tuned for a single instance.
|
||||
|
||||
The **autoscaler** allows spinning up new VMs on a cloud provider of choice to process pending builds. After the builds finished, the VMs are destroyed again (after a short transition time).
|
||||
|
||||
:::tip
|
||||
You can add more agents to increase the number of parallel workflows or set the agent's [`WOODPECKER_MAX_WORKFLOWS=1`](./10-configuration/30-agent.md#max_workflows) environment variable to increase the number of parallel workflows per agent.
|
||||
:::
|
||||
|
||||
## Database
|
||||
|
||||
Woodpecker uses a SQLite database by default, which requires no installation or configuration. For larger instances it is recommended to use it with a Postgres or MariaDB instance. For more details take a look at the [database settings](./10-configuration/10-server.md#databases) page.
|
||||
|
||||
## Forge
|
||||
|
||||
What would a CI/CD system be without any code. By connecting Woodpecker to your [forge](../20-usage/15-terminology/index.md), you can start pipelines on events like pushes or pull requests. Woodpecker will also use your forge to authenticate and report back the status of your pipelines. For more details take a look at the [forge settings](./10-configuration/12-forges/11-overview.md) page.
|
||||
|
||||
## Container images
|
||||
|
||||
:::info
|
||||
No `latest` tag exists to prevent accidental major version upgrades. Either use a SemVer tag or one of the rolling major/minor version tags. Alternatively, the `next` tag can be used for rolling builds from the `main` branch.
|
||||
:::
|
||||
|
||||
- `vX.Y.Z`: SemVer tags for specific releases, no entrypoint shell (scratch image)
|
||||
- `vX.Y`
|
||||
- `vX`
|
||||
- `vX.Y.Z-alpine`: SemVer tags for specific releases, rootless for Server and CLI (as of v3.0).
|
||||
- `vX.Y-alpine`
|
||||
- `vX-alpine`
|
||||
- `next`: Built from the `main` branch
|
||||
- `pull_<PR_ID>`: Images built from Pull Request branches.
|
||||
|
||||
Images are pushed to DockerHub and Quay.
|
||||
|
||||
- woodpecker-server ([DockerHub](https://hub.docker.com/r/woodpeckerci/woodpecker-server) or [Quay](https://quay.io/repository/woodpeckerci/woodpecker-server))
|
||||
- woodpecker-agent ([DockerHub](https://hub.docker.com/r/woodpeckerci/woodpecker-agent) or [Quay](https://quay.io/repository/woodpeckerci/woodpecker-agent))
|
||||
- woodpecker-cli ([DockerHub](https://hub.docker.com/r/woodpeckerci/woodpecker-cli) or [Quay](https://quay.io/repository/woodpeckerci/woodpecker-cli))
|
||||
- woodpecker-autoscaler ([DockerHub](https://hub.docker.com/r/woodpeckerci/autoscaler))
|
||||
@ -0,0 +1,142 @@
|
||||
# Docker Compose
|
||||
|
||||
This example [docker-compose](https://docs.docker.com/compose/) setup shows the deployment of a Woodpecker instance connected to GitHub (`WOODPECKER_GITHUB=true`). If you are using another forge, please change this including the respective secret settings.
|
||||
|
||||
It creates persistent volumes for the server and agent config directories. The bundled SQLite DB is stored in `/var/lib/woodpecker` and is the most important part to be persisted as it holds all users and repository information.
|
||||
|
||||
The server uses the default port `8000` and gets exposed to the host here, so WoodpeckerWO can be accessed through this port on the host or by a reverse proxy sitting in front of it.
|
||||
|
||||
```yaml title="docker-compose.yaml"
|
||||
services:
|
||||
woodpecker-server:
|
||||
image: woodpeckerci/woodpecker-server:v3
|
||||
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:v3
|
||||
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 must know its own address. You must therefore specify the public address in the format `<scheme>://<hostname>`. Please omit any trailing slashes:
|
||||
|
||||
```diff title="docker-compose.yaml"
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_HOST=${WOODPECKER_HOST}
|
||||
```
|
||||
|
||||
It is also possible to customize the ports used. Woodpecker uses a separate port for gRPC and for HTTP. The agent makes gRPC calls and connects to the gRPC port. They can be configured with `*_ADDR` variables:
|
||||
|
||||
```diff title="docker-compose.yaml"
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR}
|
||||
+ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR}
|
||||
```
|
||||
|
||||
If the agents establish a connection via the Internet, TLS encryption should be activated for gRPC. The agent must then be configured properly:
|
||||
|
||||
```diff title="docker-compose.yaml"
|
||||
services:
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_GRPC_SECURE=true # defaults to false
|
||||
+ - WOODPECKER_GRPC_VERIFY=true # default
|
||||
```
|
||||
|
||||
As agents execute pipeline steps as Docker containers, they require access to the Docker daemon of the host machine:
|
||||
|
||||
```diff title="docker-compose.yaml"
|
||||
services:
|
||||
[...]
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
+ volumes:
|
||||
+ - /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
Agents require the server address for communication between agents and servers. The agent connects to the gRPC port of the server:
|
||||
|
||||
```diff title="docker-compose.yaml"
|
||||
services:
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
environment:
|
||||
+ - WOODPECKER_SERVER=woodpecker-server:9000
|
||||
```
|
||||
|
||||
The server and the agents use a shared secret to authenticate the communication. This should be a random string, which you should keep secret. You can create such a string with `openssl rand -hex 32`:
|
||||
|
||||
```diff title="docker-compose.yaml"
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
|
||||
woodpecker-agent:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
|
||||
```
|
||||
|
||||
## Handling sensitive data
|
||||
|
||||
There are several options for handling sensitive data in `docker compose` or `docker swarm` configurations:
|
||||
|
||||
For Docker Compose, you can use an `.env` file next to your compose configuration to store the secrets outside the compose file. Although this separates the configuration from the secrets, it is still not very secure.
|
||||
|
||||
Alternatively, you can also use `docker-secrets`. As it can be difficult to use `docker-secrets` for environment variables, Woodpecker allows reading sensitive data from files by providing a `*_FILE` option for all sensitive configuration variables. Woodpecker will then attempt to read the value directly from this file. Note that the original environment variable will overwrite the value read from the file if it is specified at the same time.
|
||||
|
||||
```diff title="docker-compose.yaml"
|
||||
services:
|
||||
woodpecker-server:
|
||||
[...]
|
||||
environment:
|
||||
- [...]
|
||||
+ - WOODPECKER_AGENT_SECRET_FILE=/run/secrets/woodpecker-agent-secret
|
||||
+ secrets:
|
||||
+ - woodpecker-agent-secret
|
||||
+
|
||||
+ secrets:
|
||||
+ woodpecker-agent-secret:
|
||||
+ external: true
|
||||
```
|
||||
|
||||
To store values in a docker secret you can use the following command:
|
||||
|
||||
```bash
|
||||
echo "my_agent_secret_key" | docker secret create woodpecker-agent-secret -
|
||||
```
|
||||
@ -0,0 +1,45 @@
|
||||
# Helm Chart
|
||||
|
||||
Woodpecker provides a [Helm chart](https://github.com/woodpecker-ci/helm) for Kubernetes environments:
|
||||
|
||||
```bash
|
||||
helm repo add woodpecker oci://ghcr.io/woodpecker-ci/helm
|
||||
helm install woodpecker woodpecker/woodpecker
|
||||
```
|
||||
|
||||
## Metrics
|
||||
|
||||
To enable metrics gathering, set the following in values.yml:
|
||||
|
||||
```yaml
|
||||
metrics:
|
||||
enabled: true
|
||||
port: 9001
|
||||
```
|
||||
|
||||
This activates the `/metrics` endpoint on port `9001` without authentication. This port is not exposed externally by default. Use the instructions at Prometheus if you want to enable authenticated external access to metrics.
|
||||
|
||||
To enable both Prometheus pod monitoring discovery, set:
|
||||
|
||||
<!-- cspell:disable -->
|
||||
|
||||
```yaml
|
||||
prometheus:
|
||||
podmonitor:
|
||||
enabled: true
|
||||
interval: 60s
|
||||
labels: {}
|
||||
```
|
||||
|
||||
<!-- cspell:enable -->
|
||||
|
||||
If you are not receiving metrics after following the steps above, verify that your Prometheus configuration includes your namespace explicitly in the podMonitorNamespaceSelector or that the selectors are disabled:
|
||||
|
||||
```yaml
|
||||
# Search all available namespaces
|
||||
podMonitorNamespaceSelector:
|
||||
matchLabels: {}
|
||||
# Enable all available pod monitors
|
||||
podMonitorSelector:
|
||||
matchLabels: {}
|
||||
```
|
||||
@ -0,0 +1,176 @@
|
||||
# Distribution packages
|
||||
|
||||
## Official packages
|
||||
|
||||
- DEB
|
||||
- RPM
|
||||
|
||||
The pre-built packages are available on the [GitHub releases](https://github.com/woodpecker-ci/woodpecker/releases/latest) page. The packages can be installed using the package manager of your distribution.
|
||||
|
||||
```Shell
|
||||
# Debian/Ubuntu
|
||||
curl -L https://github.com/woodpecker-ci/woodpecker/releases/download/${RELEASE_VERSION}/woodpecker_${RELEASE_VERSION}_amd64.deb -o woodpecker-server.deb
|
||||
sudo apt --fix-broken install ./woodpecker-server.deb
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo dnf install https://github.com/woodpecker-ci/woodpecker/releases/download/${RELEASE_VERSION}/woodpecker_${RELEASE_VERSION}_amd64.rpm
|
||||
```
|
||||
|
||||
The package installation will create a systemd service file for the Woodpecker server and agent along with an example environment file. To configure the server, copy the example environment file `/etc/woodpecker/woodpecker-server.env.example` to `/etc/woodpecker/woodpecker-server.env` and adjust the values.
|
||||
|
||||
```ini title="/usr/local/lib/systemd/system/woodpecker-server.service"
|
||||
[Unit]
|
||||
Description=WoodpeckerCI server
|
||||
Documentation=https://woodpecker-ci.org/docs/administration/server-config
|
||||
Requires=network.target
|
||||
After=network.target
|
||||
ConditionFileNotEmpty=/etc/woodpecker/woodpecker-server.env
|
||||
ConditionPathExists=/etc/woodpecker/woodpecker-server.env
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
EnvironmentFile=/etc/woodpecker/woodpecker-server.env
|
||||
User=woodpecker
|
||||
Group=woodpecker
|
||||
ExecStart=/usr/local/bin/woodpecker-server
|
||||
WorkingDirectory=/var/lib/woodpecker/
|
||||
StateDirectory=woodpecker
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
```shell title="/etc/woodpecker/woodpecker-server.env"
|
||||
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}
|
||||
```
|
||||
|
||||
After installing the agent, copy the example environment file `/etc/woodpecker/woodpecker-agent.env.example` to `/etc/woodpecker/woodpecker-agent.env` and adjust the values as well. The agent will automatically register itself with the server.
|
||||
|
||||
```ini title="/usr/local/lib/systemd/system/woodpecker-agent.service"
|
||||
[Unit]
|
||||
Description=WoodpeckerCI agent
|
||||
Documentation=https://woodpecker-ci.org/docs/administration/agent-config
|
||||
Requires=network.target
|
||||
After=network.target
|
||||
ConditionFileNotEmpty=/etc/woodpecker/woodpecker-agent.env
|
||||
ConditionPathExists=/etc/woodpecker/woodpecker-agent.env
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
EnvironmentFile=/etc/woodpecker/woodpecker-agent.env
|
||||
User=woodpecker
|
||||
Group=woodpecker
|
||||
ExecStart=/usr/local/bin/woodpecker-agent
|
||||
WorkingDirectory=/var/lib/woodpecker/
|
||||
StateDirectory=woodpecker
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
```shell title="/etc/woodpecker/woodpecker-agent.env"
|
||||
WOODPECKER_SERVER=localhost:9000
|
||||
WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
|
||||
```
|
||||
|
||||
## Community packages
|
||||
|
||||
:::info
|
||||
Woodpecker itself is not responsible for creating these packages. Please reach out to the people responsible for packaging Woodpecker for the individual distributions.
|
||||
:::
|
||||
|
||||
- [Alpine (Edge)](https://pkgs.alpinelinux.org/packages?name=woodpecker&branch=edge&repo=&arch=&maintainer=)
|
||||
- [Arch Linux](https://archlinux.org/packages/?q=woodpecker)
|
||||
- [openSUSE](https://software.opensuse.org/package/woodpecker)
|
||||
- [YunoHost](https://apps.yunohost.org/app/woodpecker)
|
||||
- [Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html)
|
||||
|
||||
### NixOS
|
||||
|
||||
:::info
|
||||
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.
|
||||
:::
|
||||
|
||||
In theory, the NixOS installation is very similar to the binary installation and supports multiple backends.
|
||||
In practice, the settings are specified declaratively in the NixOS configuration and no manual steps need to be taken.
|
||||
|
||||
<!-- cspell:words Optimisation -->
|
||||
|
||||
```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). There are also some additional resources on how to utilize Woodpecker more effectively with NixOS on the [Awesome Woodpecker](/awesome) page, like using the runners nix-store in the pipeline.
|
||||
@ -1,3 +1,3 @@
|
||||
label: 'Deployment methods'
|
||||
label: 'Installation'
|
||||
collapsible: true
|
||||
collapsed: true
|
||||
File diff suppressed because it is too large
Load Diff
@ -2,13 +2,13 @@
|
||||
toc_max_heading_level: 2
|
||||
---
|
||||
|
||||
# Docker backend
|
||||
# Docker
|
||||
|
||||
This is the original backend used with Woodpecker. The docker backend executes each step inside a separate container started on the agent.
|
||||
|
||||
## Docker credentials
|
||||
## Private registries
|
||||
|
||||
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).
|
||||
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.md#docker_config).
|
||||
|
||||
To add your credential helper to the Woodpecker server container you could use the following code to build a custom image:
|
||||
|
||||
@ -37,7 +37,9 @@ steps:
|
||||
|
||||
The syntax is the same as the [docker run](https://docs.docker.com/engine/reference/run/#user) `--user` flag.
|
||||
|
||||
## Image cleanup
|
||||
## Tips and tricks
|
||||
|
||||
### 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.
|
||||
|
||||
@ -45,80 +47,103 @@ The agent **will not** automatically remove images from the host. This task shou
|
||||
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
|
||||
- Remove all unused images
|
||||
|
||||
<!-- cspell:ignore trunc -->
|
||||
<!-- cspell:ignore trunc -->
|
||||
|
||||
```bash
|
||||
docker image rm $(docker images --filter "dangling=true" -q --no-trunc)
|
||||
```
|
||||
```bash
|
||||
docker image rm $(docker images --filter "dangling=true" -q --no-trunc)
|
||||
```
|
||||
|
||||
### Remove Woodpecker volumes
|
||||
- Remove Woodpecker volumes
|
||||
|
||||
```bash
|
||||
docker volume rm $(docker volume ls --filter name=^wp_* --filter dangling=true -q)
|
||||
```
|
||||
|
||||
## Tips and tricks
|
||||
```bash
|
||||
docker volume rm $(docker volume ls --filter name=^wp_* --filter dangling=true -q)
|
||||
```
|
||||
|
||||
### Podman
|
||||
|
||||
There is no official support for Podman, but one can try to set the environment variable `DOCKER_HOST` to point to the Podman socket. It might work. See also the [Blog posts](https://woodpecker-ci.org/blog).
|
||||
|
||||
## Configuration
|
||||
## Environment variables
|
||||
|
||||
### `WOODPECKER_BACKEND_DOCKER_NETWORK`
|
||||
### BACKEND_DOCKER_NETWORK
|
||||
|
||||
> Default: empty
|
||||
- Name: `WOODPECKER_BACKEND_DOCKER_NETWORK`
|
||||
- Default: none
|
||||
|
||||
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`
|
||||
### BACKEND_DOCKER_ENABLE_IPV6
|
||||
|
||||
- Name: `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
|
||||
### BACKEND_DOCKER_VOLUMES
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_DOCKER_VOLUMES`
|
||||
- Default: none
|
||||
|
||||
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`.
|
||||
|
||||
### `WOODPECKER_BACKEND_DOCKER_LIMIT_MEM_SWAP`
|
||||
---
|
||||
|
||||
> Default: `0`
|
||||
### BACKEND_DOCKER_LIMIT_MEM_SWAP
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_DOCKER_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_BACKEND_DOCKER_LIMIT_MEM`
|
||||
---
|
||||
|
||||
> Default: `0`
|
||||
### BACKEND_DOCKER_LIMIT_MEM
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_DOCKER_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_BACKEND_DOCKER_LIMIT_SHM_SIZE`
|
||||
---
|
||||
|
||||
> Default: `0`
|
||||
### BACKEND_DOCKER_LIMIT_SHM_SIZE
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_DOCKER_LIMIT_SHM_SIZE`
|
||||
- Default: `0`
|
||||
|
||||
The maximum amount of memory of `/dev/shm` allowed in bytes. There is no limit if `0`.
|
||||
|
||||
### `WOODPECKER_BACKEND_DOCKER_LIMIT_CPU_QUOTA`
|
||||
---
|
||||
|
||||
> Default: `0`
|
||||
### BACKEND_DOCKER_LIMIT_CPU_QUOTA
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_DOCKER_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_BACKEND_DOCKER_LIMIT_CPU_SHARES`
|
||||
---
|
||||
|
||||
> Default: `0`
|
||||
### BACKEND_DOCKER_LIMIT_CPU_SHARES
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_DOCKER_LIMIT_CPU_SHARES`
|
||||
- Default: `0`
|
||||
|
||||
The relative weight vs. other containers.
|
||||
|
||||
### `WOODPECKER_BACKEND_DOCKER_LIMIT_CPU_SET`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### BACKEND_DOCKER_LIMIT_CPU_SET
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_DOCKER_LIMIT_CPU_SET`
|
||||
- Default: none
|
||||
|
||||
Comma-separated list to limit the specific CPUs or cores a pipeline container can use.
|
||||
|
||||
@ -2,13 +2,27 @@
|
||||
toc_max_heading_level: 2
|
||||
---
|
||||
|
||||
# Kubernetes backend
|
||||
# Kubernetes
|
||||
|
||||
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
|
||||
## Metadata labels
|
||||
|
||||
In addition to [registries specified in the UI](../../20-usage/41-registries.md), you may provide [registry credentials in Kubernetes Secrets](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) to pull private container images defined in your pipeline YAML.
|
||||
Woodpecker adds some labels to the pods to provide additional context to the workflow. These labels can be used for various purposes, e.g. for simple debugging or as selectors for network policies.
|
||||
|
||||
The following metadata labels are supported:
|
||||
|
||||
- `woodpecker-ci.org/forge-id`
|
||||
- `woodpecker-ci.org/repo-forge-id`
|
||||
- `woodpecker-ci.org/repo-id`
|
||||
- `woodpecker-ci.org/repo-name`
|
||||
- `woodpecker-ci.org/repo-full-name`
|
||||
- `woodpecker-ci.org/branch`
|
||||
- `woodpecker-ci.org/org-id`
|
||||
|
||||
## Private registries
|
||||
|
||||
In addition to [registries specified in the UI](../../../20-usage/41-registries.md), you may provide [registry credentials in Kubernetes Secrets](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) to pull private container images defined in your pipeline YAML.
|
||||
|
||||
Place these Secrets in namespace defined by `WOODPECKER_BACKEND_K8S_NAMESPACE` and provide the Secret names to Agents via `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES`.
|
||||
|
||||
@ -94,7 +108,7 @@ And then overwrite the `nodeSelector` in the `backend_options` section of the st
|
||||
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
|
||||
You can use [WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR](#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
|
||||
@ -256,7 +270,7 @@ backend_options:
|
||||
```
|
||||
|
||||
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).
|
||||
[WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS_ALLOW_FROM_STEP](#backend_k8s_pod_annotations_allow_from_step) and/or [WOODPECKER_BACKEND_K8S_POD_LABELS_ALLOW_FROM_STEP](#backend_k8s_pod_labels_allow_from_step).
|
||||
|
||||
## Tips and tricks
|
||||
|
||||
@ -279,72 +293,105 @@ 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
|
||||
## Environment variables
|
||||
|
||||
These env vars can be set in the `env:` sections of the agent.
|
||||
|
||||
### `WOODPECKER_BACKEND_K8S_NAMESPACE`
|
||||
---
|
||||
|
||||
> Default: `woodpecker`
|
||||
### BACKEND_K8S_NAMESPACE
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_K8S_NAMESPACE`
|
||||
- Default: `woodpecker`
|
||||
|
||||
The namespace to create worker Pods in.
|
||||
|
||||
### `WOODPECKER_BACKEND_K8S_VOLUME_SIZE`
|
||||
---
|
||||
|
||||
> Default: `10G`
|
||||
### BACKEND_K8S_VOLUME_SIZE
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_K8S_VOLUME_SIZE`
|
||||
- Default: `10G`
|
||||
|
||||
The volume size of the pipeline volume.
|
||||
|
||||
### `WOODPECKER_BACKEND_K8S_STORAGE_CLASS`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### BACKEND_K8S_STORAGE_CLASS
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_K8S_STORAGE_CLASS`
|
||||
- Default: none
|
||||
|
||||
The storage class to use for the pipeline volume.
|
||||
|
||||
### `WOODPECKER_BACKEND_K8S_STORAGE_RWX`
|
||||
---
|
||||
|
||||
> Default: `true`
|
||||
### BACKEND_K8S_STORAGE_RWX
|
||||
|
||||
- Name: `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
|
||||
### BACKEND_K8S_POD_LABELS
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_K8S_POD_LABELS`
|
||||
- Default: none
|
||||
|
||||
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`
|
||||
### BACKEND_K8S_POD_LABELS_ALLOW_FROM_STEP
|
||||
|
||||
- Name: `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
|
||||
### BACKEND_K8S_POD_ANNOTATIONS
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS`
|
||||
- Default: none
|
||||
|
||||
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`
|
||||
### BACKEND_K8S_POD_ANNOTATIONS_ALLOW_FROM_STEP
|
||||
|
||||
- Name: `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
|
||||
### BACKEND_K8S_POD_NODE_SELECTOR
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR`
|
||||
- Default: none
|
||||
|
||||
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` <!-- cspell:ignore SECCTX NONROOT -->
|
||||
---
|
||||
|
||||
> Default: `false`
|
||||
### BACKEND_K8S_SECCTX_NONROOT <!-- cspell:ignore SECCTX NONROOT -->
|
||||
|
||||
- Name: `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
|
||||
### BACKEND_K8S_PULL_SECRET_NAMES
|
||||
|
||||
- Name: `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES`
|
||||
- Default: none
|
||||
|
||||
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/).
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
toc_max_heading_level: 3
|
||||
toc_max_heading_level: 2
|
||||
---
|
||||
|
||||
# Local backend
|
||||
# Local
|
||||
|
||||
:::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.
|
||||
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).
|
||||
:::
|
||||
|
||||
@ -27,13 +27,7 @@ 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
|
||||
```
|
||||
## Step specific configuration
|
||||
|
||||
### Shell
|
||||
|
||||
@ -58,10 +52,11 @@ steps:
|
||||
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
|
||||
## Environment variables
|
||||
|
||||
#### `WOODPECKER_BACKEND_LOCAL_TEMP_DIR`
|
||||
### BACKEND_LOCAL_TEMP_DIR
|
||||
|
||||
> Default: default temp directory
|
||||
- Name: `WOODPECKER_BACKEND_LOCAL_TEMP_DIR`
|
||||
- Default: default temp directory
|
||||
|
||||
Directory to create folders for workflows.
|
||||
@ -0,0 +1,18 @@
|
||||
# Custom
|
||||
|
||||
If none of our backends fit your use case, you can write your own. To do this, implement the interface `“go.woodpecker-ci.org/woodpecker/woodpecker/v3/pipeline/backend/types”.backend` and create a custom agent that uses your backend:
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"go.woodpecker-ci.org/woodpecker/v3/cmd/agent/core"
|
||||
backendTypes "go.woodpecker-ci.org/woodpecker/v3/pipeline/backend/types"
|
||||
)
|
||||
|
||||
func main() {
|
||||
core.RunAgent([]backendTypes.Backend{
|
||||
yourBackend,
|
||||
})
|
||||
}
|
||||
```
|
||||
@ -1,13 +1,13 @@
|
||||
# Addon forges
|
||||
# Custom
|
||||
|
||||
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.
|
||||
If the forge you are using does not meet the [Woodpecker requirements](../../../92-development/02-core-ideas.md#forges) or your setup is too specific to be included in the Woodpecker core, you can write 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.
|
||||
You must trust the author of the addon forge you are using. They may have access to authentication codes and other potentially sensitive information.
|
||||
:::
|
||||
|
||||
## Usage
|
||||
@ -26,9 +26,7 @@ If you experience bugs, please check which component has the issue. If it's the
|
||||
|
||||
## List of addon forges
|
||||
|
||||
### Radicle Forge
|
||||
|
||||
[Radicle](https://radicle.xyz/) is an open source, peer-to-peer code collaboration stack built on Git. Radicle addon for Woodpecker CI can be found at [this repo](https://explorer.radicle.gr/nodes/seed.radicle.gr/rad:z39Cf1XzrvCLRZZJRUZnx9D1fj5ws).
|
||||
- [Radicle](https://radicle.xyz/): Open source, peer-to-peer code collaboration stack built on Git. Radicle addon for Woodpecker CI can be found at [this repo](https://explorer.radicle.gr/nodes/seed.radicle.gr/rad:z39Cf1XzrvCLRZZJRUZnx9D1fj5ws).
|
||||
|
||||
## Creating addon forges
|
||||
|
||||
@ -43,6 +41,10 @@ Directly import Woodpecker's Go packages (`go.woodpecker-ci.org/woodpecker/v3`)
|
||||
In the `main` function, just call `"go.woodpecker-ci.org/woodpecker/v3/server/forge/addon".Serve` with a `"go.woodpecker-ci.org/woodpecker/v3/server/forge".Forge` as argument.
|
||||
This will take care of connecting the addon forge to the server.
|
||||
|
||||
:::note
|
||||
It is not possible to access global variables from Woodpecker, for example the server configuration. You must therefore parse the environment variables in your addon. The reason for this is that the addon runs in a completely separate process.
|
||||
:::
|
||||
|
||||
### Example structure
|
||||
|
||||
```go
|
||||
@ -0,0 +1,15 @@
|
||||
# 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: |
|
||||
|
||||
¹ The deployment event can be triggered for all forges from Woodpecker directly. However, only GitHub can trigger them using webhooks.
|
||||
@ -36,54 +36,81 @@ Use this one for the `WOODPECKER_GITHUB_SECRET` environment variable.
|
||||
|
||||
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`
|
||||
### GITHUB
|
||||
|
||||
- Name: `WOODPECKER_GITHUB`
|
||||
- Default: `false`
|
||||
|
||||
Enables the GitHub driver.
|
||||
|
||||
### `WOODPECKER_GITHUB_URL`
|
||||
---
|
||||
|
||||
> Default: `https://github.com`
|
||||
### GITHUB_URL
|
||||
|
||||
- Name: `WOODPECKER_GITHUB_URL`
|
||||
- Default: `https://github.com`
|
||||
|
||||
Configures the GitHub server address.
|
||||
|
||||
### `WOODPECKER_GITHUB_CLIENT`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### GITHUB_CLIENT
|
||||
|
||||
- Name: `WOODPECKER_GITHUB_CLIENT`
|
||||
- Default: none
|
||||
|
||||
Configures the GitHub OAuth client id to authorize access.
|
||||
|
||||
### `WOODPECKER_GITHUB_CLIENT_FILE`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### GITHUB_CLIENT_FILE
|
||||
|
||||
- Name: `WOODPECKER_GITHUB_CLIENT_FILE`
|
||||
- Default: none
|
||||
|
||||
Read the value for `WOODPECKER_GITHUB_CLIENT` from the specified filepath.
|
||||
|
||||
### `WOODPECKER_GITHUB_SECRET`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### GITHUB_SECRET
|
||||
|
||||
- Name: `WOODPECKER_GITHUB_SECRET`
|
||||
- Default: none
|
||||
|
||||
Configures the GitHub OAuth client secret. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_GITHUB_SECRET_FILE`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### GITHUB_SECRET_FILE
|
||||
|
||||
- Name: `WOODPECKER_GITHUB_SECRET_FILE`
|
||||
- Default: none
|
||||
|
||||
Read the value for `WOODPECKER_GITHUB_SECRET` from the specified filepath.
|
||||
|
||||
### `WOODPECKER_GITHUB_MERGE_REF`
|
||||
---
|
||||
|
||||
> Default: `true`
|
||||
### GITHUB_MERGE_REF
|
||||
|
||||
### `WOODPECKER_GITHUB_SKIP_VERIFY`
|
||||
- Name: `WOODPECKER_GITHUB_MERGE_REF`
|
||||
- Default: `true`
|
||||
|
||||
> Default: `false`
|
||||
---
|
||||
|
||||
### GITHUB_SKIP_VERIFY
|
||||
|
||||
- Name: `WOODPECKER_GITHUB_SKIP_VERIFY`
|
||||
- Default: `false`
|
||||
|
||||
Configure if SSL verification should be skipped.
|
||||
|
||||
### `WOODPECKER_GITHUB_PUBLIC_ONLY`
|
||||
---
|
||||
|
||||
> Default: `false`
|
||||
### GITHUB_PUBLIC_ONLY
|
||||
|
||||
- Name: `WOODPECKER_GITHUB_PUBLIC_ONLY`
|
||||
- Default: `false`
|
||||
|
||||
Configures the GitHub OAuth client to only obtain a token that can manage public repositories.
|
||||
@ -54,44 +54,65 @@ Make sure your Gitea configuration allows requesting the API with a fixed page l
|
||||
|
||||
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`
|
||||
### GITEA
|
||||
|
||||
- Name: `WOODPECKER_GITEA`
|
||||
- Default: `false`
|
||||
|
||||
Enables the Gitea driver.
|
||||
|
||||
### `WOODPECKER_GITEA_URL`
|
||||
---
|
||||
|
||||
> Default: `https://try.gitea.io`
|
||||
### GITEA_URL
|
||||
|
||||
- Name: `WOODPECKER_GITEA_URL`
|
||||
- Default: `https://try.gitea.io`
|
||||
|
||||
Configures the Gitea server address.
|
||||
|
||||
### `WOODPECKER_GITEA_CLIENT`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### GITEA_CLIENT
|
||||
|
||||
- Name: `WOODPECKER_GITEA_CLIENT`
|
||||
- Default: none
|
||||
|
||||
Configures the Gitea OAuth client id. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_GITEA_CLIENT_FILE`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### GITEA_CLIENT_FILE
|
||||
|
||||
- Name: `WOODPECKER_GITEA_CLIENT_FILE`
|
||||
- Default: none
|
||||
|
||||
Read the value for `WOODPECKER_GITEA_CLIENT` from the specified filepath
|
||||
|
||||
### `WOODPECKER_GITEA_SECRET`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### GITEA_SECRET
|
||||
|
||||
- Name: `WOODPECKER_GITEA_SECRET`
|
||||
- Default: none
|
||||
|
||||
Configures the Gitea OAuth client secret. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_GITEA_SECRET_FILE`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### GITEA_SECRET_FILE
|
||||
|
||||
- Name: `WOODPECKER_GITEA_SECRET_FILE`
|
||||
- Default: none
|
||||
|
||||
Read the value for `WOODPECKER_GITEA_SECRET` from the specified filepath
|
||||
|
||||
### `WOODPECKER_GITEA_SKIP_VERIFY`
|
||||
---
|
||||
|
||||
> Default: `false`
|
||||
### GITEA_SKIP_VERIFY
|
||||
|
||||
- Name: `WOODPECKER_GITEA_SKIP_VERIFY`
|
||||
- Default: `false`
|
||||
|
||||
Configure if SSL verification should be skipped.
|
||||
@ -54,44 +54,65 @@ Make sure your Forgejo configuration allows requesting the API with a fixed page
|
||||
|
||||
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`
|
||||
### FORGEJO
|
||||
|
||||
- Name: `WOODPECKER_FORGEJO`
|
||||
- Default: `false`
|
||||
|
||||
Enables the Forgejo driver.
|
||||
|
||||
### `WOODPECKER_FORGEJO_URL`
|
||||
---
|
||||
|
||||
> Default: `https://next.forgejo.org`
|
||||
### FORGEJO_URL
|
||||
|
||||
- Name: `WOODPECKER_FORGEJO_URL`
|
||||
- Default: `https://next.forgejo.org`
|
||||
|
||||
Configures the Forgejo server address.
|
||||
|
||||
### `WOODPECKER_FORGEJO_CLIENT`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### FORGEJO_CLIENT
|
||||
|
||||
- Name: `WOODPECKER_FORGEJO_CLIENT`
|
||||
- Default: none
|
||||
|
||||
Configures the Forgejo OAuth client id. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_FORGEJO_CLIENT_FILE`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### FORGEJO_CLIENT_FILE
|
||||
|
||||
- Name: `WOODPECKER_FORGEJO_CLIENT_FILE`
|
||||
- Default: none
|
||||
|
||||
Read the value for `WOODPECKER_FORGEJO_CLIENT` from the specified filepath
|
||||
|
||||
### `WOODPECKER_FORGEJO_SECRET`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### FORGEJO_SECRET
|
||||
|
||||
- Name: `WOODPECKER_FORGEJO_SECRET`
|
||||
- Default: none
|
||||
|
||||
Configures the Forgejo OAuth client secret. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_FORGEJO_SECRET_FILE`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### FORGEJO_SECRET_FILE
|
||||
|
||||
- Name: `WOODPECKER_FORGEJO_SECRET_FILE`
|
||||
- Default: none
|
||||
|
||||
Read the value for `WOODPECKER_FORGEJO_SECRET` from the specified filepath
|
||||
|
||||
### `WOODPECKER_FORGEJO_SKIP_VERIFY`
|
||||
---
|
||||
|
||||
> Default: `false`
|
||||
### FORGEJO_SKIP_VERIFY
|
||||
|
||||
- Name: `WOODPECKER_FORGEJO_SKIP_VERIFY`
|
||||
- Default: `false`
|
||||
|
||||
Configure if SSL verification should be skipped.
|
||||
@ -25,44 +25,65 @@ If you run the Woodpecker CI server on a private IP (RFC1918) or use a non stand
|
||||
|
||||
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`
|
||||
### GITLAB
|
||||
|
||||
- Name: `WOODPECKER_GITLAB`
|
||||
- Default: `false`
|
||||
|
||||
Enables the GitLab driver.
|
||||
|
||||
### `WOODPECKER_GITLAB_URL`
|
||||
---
|
||||
|
||||
> Default: `https://gitlab.com`
|
||||
### GITLAB_URL
|
||||
|
||||
- Name: `WOODPECKER_GITLAB_URL`
|
||||
- Default: `https://gitlab.com`
|
||||
|
||||
Configures the GitLab server address.
|
||||
|
||||
### `WOODPECKER_GITLAB_CLIENT`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### GITLAB_CLIENT
|
||||
|
||||
- Name: `WOODPECKER_GITLAB_CLIENT`
|
||||
- Default: none
|
||||
|
||||
Configures the GitLab OAuth client id. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_GITLAB_CLIENT_FILE`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### GITLAB_CLIENT_FILE
|
||||
|
||||
- Name: `WOODPECKER_GITLAB_CLIENT_FILE`
|
||||
- Default: none
|
||||
|
||||
Read the value for `WOODPECKER_GITLAB_CLIENT` from the specified filepath
|
||||
|
||||
### `WOODPECKER_GITLAB_SECRET`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### GITLAB_SECRET
|
||||
|
||||
- Name: `WOODPECKER_GITLAB_SECRET`
|
||||
- Default: none
|
||||
|
||||
Configures the GitLab OAuth client secret. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_GITLAB_SECRET_FILE`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### GITLAB_SECRET_FILE
|
||||
|
||||
- Name: `WOODPECKER_GITLAB_SECRET_FILE`
|
||||
- Default: none
|
||||
|
||||
Read the value for `WOODPECKER_GITLAB_SECRET` from the specified filepath
|
||||
|
||||
### `WOODPECKER_GITLAB_SKIP_VERIFY`
|
||||
---
|
||||
|
||||
> Default: `false`
|
||||
### GITLAB_SKIP_VERIFY
|
||||
|
||||
- Name: `WOODPECKER_GITLAB_SKIP_VERIFY`
|
||||
- Default: `false`
|
||||
|
||||
Configure if SSL verification should be skipped.
|
||||
@ -39,33 +39,48 @@ Please also be sure to check the following permissions:
|
||||
|
||||
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`
|
||||
### BITBUCKET
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET`
|
||||
- Default: `false`
|
||||
|
||||
Enables the Bitbucket driver.
|
||||
|
||||
### `WOODPECKER_BITBUCKET_CLIENT`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### BITBUCKET_CLIENT
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET_CLIENT`
|
||||
- Default: none
|
||||
|
||||
Configures the Bitbucket OAuth client key. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_BITBUCKET_CLIENT_FILE`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### BITBUCKET_CLIENT_FILE
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET_CLIENT_FILE`
|
||||
- Default: none
|
||||
|
||||
Read the value for `WOODPECKER_BITBUCKET_CLIENT` from the specified filepath
|
||||
|
||||
### `WOODPECKER_BITBUCKET_SECRET`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### BITBUCKET_SECRET
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET_SECRET`
|
||||
- Default: none
|
||||
|
||||
Configures the Bitbucket OAuth client secret. This is used to authorize access.
|
||||
|
||||
### `WOODPECKER_BITBUCKET_SECRET_FILE`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### BITBUCKET_SECRET_FILE
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET_SECRET_FILE`
|
||||
- Default: none
|
||||
|
||||
Read the value for `WOODPECKER_BITBUCKET_SECRET` from the specified filepath
|
||||
|
||||
@ -44,56 +44,83 @@ See also [Configure an incoming link](https://confluence.atlassian.com/bitbucket
|
||||
|
||||
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`
|
||||
### BITBUCKET_DC
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET_DC`
|
||||
- Default: `false`
|
||||
|
||||
Enables the Bitbucket Server driver.
|
||||
|
||||
### `WOODPECKER_BITBUCKET_DC_URL`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### BITBUCKET_DC_URL
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET_DC_URL`
|
||||
- Default: none
|
||||
|
||||
Configures the Bitbucket Server address.
|
||||
|
||||
### `WOODPECKER_BITBUCKET_DC_CLIENT_ID`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### BITBUCKET_DC_CLIENT_ID
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET_DC_CLIENT_ID`
|
||||
- Default: none
|
||||
|
||||
Configures your Bitbucket Server OAUth 2.0 client id.
|
||||
|
||||
### `WOODPECKER_BITBUCKET_DC_CLIENT_SECRET`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### BITBUCKET_DC_CLIENT_SECRET
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET_DC_CLIENT_SECRET`
|
||||
- Default: none
|
||||
|
||||
Configures your Bitbucket Server OAUth 2.0 client secret.
|
||||
|
||||
### `WOODPECKER_BITBUCKET_DC_GIT_USERNAME`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### BITBUCKET_DC_GIT_USERNAME
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET_DC_GIT_USERNAME`
|
||||
- Default: none
|
||||
|
||||
This username is used to authenticate and clone all private repositories.
|
||||
|
||||
### `WOODPECKER_BITBUCKET_DC_GIT_USERNAME_FILE`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### BITBUCKET_DC_GIT_USERNAME_FILE
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET_DC_GIT_USERNAME_FILE`
|
||||
- Default: none
|
||||
|
||||
Read the value for `WOODPECKER_BITBUCKET_DC_GIT_USERNAME` from the specified filepath
|
||||
|
||||
### `WOODPECKER_BITBUCKET_DC_GIT_PASSWORD`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### BITBUCKET_DC_GIT_PASSWORD
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET_DC_GIT_PASSWORD`
|
||||
- Default: none
|
||||
|
||||
The password is used to authenticate and clone all private repositories.
|
||||
|
||||
### `WOODPECKER_BITBUCKET_DC_GIT_PASSWORD_FILE`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### BITBUCKET_DC_GIT_PASSWORD_FILE
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET_DC_GIT_PASSWORD_FILE`
|
||||
- Default: none
|
||||
|
||||
Read the value for `WOODPECKER_BITBUCKET_DC_GIT_PASSWORD` from the specified filepath
|
||||
|
||||
### `WOODPECKER_BITBUCKET_DC_SKIP_VERIFY`
|
||||
---
|
||||
|
||||
> Default: `false`
|
||||
### BITBUCKET_DC_SKIP_VERIFY
|
||||
|
||||
- Name: `WOODPECKER_BITBUCKET_DC_SKIP_VERIFY`
|
||||
- Default: `false`
|
||||
|
||||
Configure if SSL verification should be skipped.
|
||||
|
Before 
(image error) Size: 29 KiB After 
(image error) Size: 29 KiB
|
|
Before 
(image error) Size: 20 KiB After 
(image error) Size: 20 KiB
|
|
Before 
(image error) Size: 129 KiB After 
(image error) Size: 129 KiB
|
|
Before 
(image error) Size: 25 KiB After 
(image error) Size: 25 KiB
|
@ -1,8 +1,8 @@
|
||||
---
|
||||
toc_max_heading_level: 2
|
||||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Agent configuration
|
||||
# Agent
|
||||
|
||||
Agents are configured by the command line or environment variables. At the minimum you need the following information:
|
||||
|
||||
@ -56,147 +56,203 @@ To get an _agent token_ you have to register the agent manually in the server us
|
||||
1. The agent will connect to the server using the provided token and will update its status in the UI:
|
||||
|
||||
|
||||
## All agent configuration options
|
||||
## Environment variables
|
||||
|
||||
Here is the full list of configuration options and their default variables.
|
||||
### SERVER
|
||||
|
||||
### `WOODPECKER_SERVER`
|
||||
|
||||
> Default: `localhost:9000`
|
||||
- Name: `WOODPECKER_SERVER`
|
||||
- Default: `localhost:9000`
|
||||
|
||||
Configures gRPC address of the server.
|
||||
|
||||
### `WOODPECKER_USERNAME`
|
||||
---
|
||||
|
||||
> Default: `x-oauth-basic`
|
||||
### USERNAME
|
||||
|
||||
- Name: `WOODPECKER_USERNAME`
|
||||
- Default: `x-oauth-basic`
|
||||
|
||||
The gRPC username.
|
||||
|
||||
### `WOODPECKER_AGENT_SECRET`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### 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`.
|
||||
|
||||
### `WOODPECKER_AGENT_SECRET_FILE`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### AGENT_SECRET_FILE
|
||||
|
||||
- Name: `WOODPECKER_AGENT_SECRET_FILE`
|
||||
- Default: none
|
||||
|
||||
Read the value for `WOODPECKER_AGENT_SECRET` from the specified filepath, e.g. `/etc/woodpecker/agent-secret.conf`
|
||||
|
||||
### `WOODPECKER_LOG_LEVEL`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### 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.
|
||||
|
||||
### `WOODPECKER_DEBUG_PRETTY`
|
||||
---
|
||||
|
||||
> Default: `false`
|
||||
### DEBUG_PRETTY
|
||||
|
||||
- Name: `WOODPECKER_DEBUG_PRETTY`
|
||||
- Default: `false`
|
||||
|
||||
Enable pretty-printed debug output.
|
||||
|
||||
### `WOODPECKER_DEBUG_NOCOLOR`
|
||||
---
|
||||
|
||||
> Default: `true`
|
||||
### DEBUG_NOCOLOR
|
||||
|
||||
- Name: `WOODPECKER_DEBUG_NOCOLOR`
|
||||
- Default: `true`
|
||||
|
||||
Disable colored debug output.
|
||||
|
||||
### `WOODPECKER_HOSTNAME`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### HOSTNAME
|
||||
|
||||
- Name: `WOODPECKER_HOSTNAME`
|
||||
- Default: none
|
||||
|
||||
Configures the agent hostname.
|
||||
|
||||
### `WOODPECKER_AGENT_CONFIG_FILE`
|
||||
---
|
||||
|
||||
> Default: `/etc/woodpecker/agent.conf`
|
||||
### AGENT_CONFIG_FILE
|
||||
|
||||
- Name: `WOODPECKER_AGENT_CONFIG_FILE`
|
||||
- Default: `/etc/woodpecker/agent.conf`
|
||||
|
||||
Configures the path of the agent config file.
|
||||
|
||||
### `WOODPECKER_MAX_WORKFLOWS`
|
||||
---
|
||||
|
||||
> Default: `1`
|
||||
### MAX_WORKFLOWS
|
||||
|
||||
- Name: `WOODPECKER_MAX_WORKFLOWS`
|
||||
- Default: `1`
|
||||
|
||||
Configures the number of parallel workflows.
|
||||
|
||||
### `WOODPECKER_AGENT_LABELS`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### AGENT_LABELS
|
||||
|
||||
- Name: `WOODPECKER_AGENT_LABELS`
|
||||
- Default: none
|
||||
|
||||
Configures custom labels for the agent, to let workflows filter by it.
|
||||
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).
|
||||
To learn how labels work, check out the [pipeline syntax page](../../20-usage/20-workflow-syntax.md#labels).
|
||||
|
||||
### `WOODPECKER_HEALTHCHECK`
|
||||
---
|
||||
|
||||
> Default: `true`
|
||||
### HEALTHCHECK
|
||||
|
||||
- Name: `WOODPECKER_HEALTHCHECK`
|
||||
- Default: `true`
|
||||
|
||||
Enable healthcheck endpoint.
|
||||
|
||||
### `WOODPECKER_HEALTHCHECK_ADDR`
|
||||
---
|
||||
|
||||
> Default: `:3000`
|
||||
### HEALTHCHECK_ADDR
|
||||
|
||||
- Name: `WOODPECKER_HEALTHCHECK_ADDR`
|
||||
- Default: `:3000`
|
||||
|
||||
Configures healthcheck endpoint address.
|
||||
|
||||
### `WOODPECKER_KEEPALIVE_TIME`
|
||||
---
|
||||
|
||||
> Default: empty
|
||||
### KEEPALIVE_TIME
|
||||
|
||||
- Name: `WOODPECKER_KEEPALIVE_TIME`
|
||||
- Default: none
|
||||
|
||||
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`
|
||||
### KEEPALIVE_TIMEOUT
|
||||
|
||||
- Name: `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`
|
||||
### GRPC_SECURE
|
||||
|
||||
- Name: `WOODPECKER_GRPC_SECURE`
|
||||
- Default: `false`
|
||||
|
||||
Configures if the connection to `WOODPECKER_SERVER` should be made using a secure transport.
|
||||
|
||||
### `WOODPECKER_GRPC_VERIFY`
|
||||
---
|
||||
|
||||
> Default: `true`
|
||||
### GRPC_VERIFY
|
||||
|
||||
- Name: `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`
|
||||
### BACKEND
|
||||
|
||||
- Name: `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_*`
|
||||
### BACKEND_DOCKER\_\*
|
||||
|
||||
See [Docker backend configuration](./22-backends/10-docker.md#configuration)
|
||||
See [Docker backend configuration](./11-backends/10-docker.md#environment-variables)
|
||||
|
||||
### `WOODPECKER_BACKEND_K8S_*`
|
||||
---
|
||||
|
||||
See [Kubernetes backend configuration](./22-backends/40-kubernetes.md#configuration)
|
||||
### BACKEND_K8S\_\*
|
||||
|
||||
### `WOODPECKER_BACKEND_LOCAL_*`
|
||||
See [Kubernetes backend configuration](./11-backends/20-kubernetes.md#environment-variables)
|
||||
|
||||
See [Local backend configuration](./22-backends/20-local.md#options)
|
||||
---
|
||||
|
||||
## Advanced Settings
|
||||
### BACKEND_LOCAL\_\*
|
||||
|
||||
See [Local backend configuration](./11-backends/30-local.md#environment-variables)
|
||||
|
||||
### Advanced Settings
|
||||
|
||||
:::warning
|
||||
Only change these If you know what you do.
|
||||
:::
|
||||
|
||||
### `WOODPECKER_CONNECT_RETRY_COUNT`
|
||||
#### CONNECT_RETRY_COUNT
|
||||
|
||||
> Default: `5`
|
||||
- Name: `WOODPECKER_CONNECT_RETRY_COUNT`
|
||||
- Default: `5`
|
||||
|
||||
Configures number of times agent retries to connect to the server.
|
||||
|
||||
### `WOODPECKER_CONNECT_RETRY_DELAY`
|
||||
#### CONNECT_RETRY_DELAY
|
||||
|
||||
> Default: `2s`
|
||||
- Name: `WOODPECKER_CONNECT_RETRY_DELAY`
|
||||
- Default: `2s`
|
||||
|
||||
Configures delay between agent connection retries to the server.
|
||||
@ -0,0 +1,3 @@
|
||||
label: 'Configuration'
|
||||
collapsible: true
|
||||
collapsed: true
|
||||
|
Before 
(image error) Size: 5.3 KiB After 
(image error) Size: 5.3 KiB
|
|
Before 
(image error) Size: 4.4 KiB After 
(image error) Size: 4.4 KiB
|
|
Before 
(image error) Size: 25 KiB After 
(image error) Size: 25 KiB
|
File diff suppressed because it is too large
Load Diff
@ -81,7 +81,7 @@ WOODPECKER_HEALTHCHECK=false
|
||||
|
||||
### Setup OAuth
|
||||
|
||||
Create an OAuth app for your forge as described in the [forges documentation](../30-administration/11-forges/11-overview.md).
|
||||
Create an OAuth app for your forge as described in the [forges documentation](../30-administration/10-configuration/12-forges/11-overview.md).
|
||||
|
||||
## Developing with VS Code
|
||||
|
||||
@ -8,8 +8,8 @@
|
||||
## Addons and extensions
|
||||
|
||||
If you are wondering whether your contribution will be accepted to be merged in the Woodpecker core, or whether it's better to write an
|
||||
[addon forge](../30-administration/11-forges/100-addon.md), [extension](../30-administration/40-advanced/100-external-configuration-api.md) or an
|
||||
[external custom backend](../30-administration/22-backends/50-custom-backends.md), please check these points:
|
||||
[addon forge](../30-administration/10-configuration/12-forges/100-addon.md), [extension](../30-administration/10-configuration/10-server.md#external-configuration-api) or an
|
||||
[external custom backend](../30-administration/10-configuration/11-backends/50-custom.md), please check these points:
|
||||
|
||||
- Is your change very specific to your setup and unlikely to be used by anyone else?
|
||||
- Does your change violate the [guidelines](#guidelines)?
|
||||
|
Before 
(image error) Size: 7.5 KiB After 
(image error) Size: 7.5 KiB
|
|
Before 
(image error) Size: 17 KiB After 
(image error) Size: 17 KiB
|
|
Before 
(image error) Size: 11 KiB After 
(image error) Size: 11 KiB
|
|
Before 
(image error) Size: 61 KiB After 
(image error) Size: 61 KiB
|
@ -1,6 +1,6 @@
|
||||
[
|
||||
"3.5",
|
||||
"3.4",
|
||||
"3.3",
|
||||
"3.2",
|
||||
"2.8"
|
||||
]
|
||||
|
||||
Loading…
Reference in New Issue
Block a user