mirror of
https://github.com/woodpecker-ci/woodpecker.git
synced 2025-04-27 03:10:58 +00:00
Add missing docs for 3.x minor versions (#4992)
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
6ffca93fa0
commit
b812f4a0d6
@ -49,7 +49,7 @@ Woodpecker is a simple, yet powerful CI/CD engine with great extensibility.
|
|||||||
|
|
||||||
## Installation & Resources
|
## Installation & Resources
|
||||||
|
|
||||||
Woodpecker can be installed in various ways (see the [Installation Instructions](https://woodpecker-ci.org/docs/administration/getting-started)) and runs with SQLite as database by default.
|
Woodpecker can be installed in various ways (see the [Installation Instructions](https://woodpecker-ci.org/docs/administration/general)) and runs with SQLite as database by default.
|
||||||
It requires around 100 MB of RAM (Server) and 30 MB (Agent) at runtime in idle mode.
|
It requires around 100 MB of RAM (Server) and 30 MB (Agent) at runtime in idle mode.
|
||||||
|
|
||||||
## Support
|
## Support
|
||||||
|
|||||||
@ -132,7 +132,7 @@ const config = {
|
|||||||
},
|
},
|
||||||
{
|
{
|
||||||
label: 'Administration',
|
label: 'Administration',
|
||||||
to: '/docs/administration/getting-started',
|
to: '/docs/administration/general',
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
to: '/migrations', // Always point to newest migration guide
|
to: '/migrations', // Always point to newest migration guide
|
||||||
|
|||||||
@ -8,13 +8,13 @@ To enhance the usability of Woodpecker and meet evolving security standards, occ
|
|||||||
- Deprecated several labels in favor of equivalents with the `woodpecker-ci.org/` prefix. The deprecated labels will be removed in a future update.
|
- Deprecated several labels in favor of equivalents with the `woodpecker-ci.org/` prefix. The deprecated labels will be removed in a future update.
|
||||||
The following labels are affected:
|
The following labels are affected:
|
||||||
|
|
||||||
| Deprecated labels | New labels |
|
| Deprecated labels | New labels |
|
||||||
|-------------------|------------------------------------|
|
| ----------------- | ---------------------------------- |
|
||||||
| `repo` | `woodpecker-ci.org/repo-full-name` |
|
| `repo` | `woodpecker-ci.org/repo-full-name` |
|
||||||
| `platform` | `woodpecker-ci.org/platform` |
|
| `platform` | `woodpecker-ci.org/platform` |
|
||||||
| `hostname` | `woodpecker-ci.org/hostname` |
|
| `hostname` | `woodpecker-ci.org/hostname` |
|
||||||
| `backend` | `woodpecker-ci.org/backend` |
|
| `backend` | `woodpecker-ci.org/backend` |
|
||||||
| `org-id` | `woodpecker-ci.org/org-id` |
|
| `org-id` | `woodpecker-ci.org/org-id` |
|
||||||
|
|
||||||
## 3.0.0
|
## 3.0.0
|
||||||
|
|
||||||
@ -242,7 +242,7 @@ Read more about it in [#4213](https://github.com/woodpecker-ci/woodpecker/pull/4
|
|||||||
|
|
||||||
## 1.0.0
|
## 1.0.0
|
||||||
|
|
||||||
- The signature used to verify extension calls (like those used for the [config-extension](/docs/administration/advanced/external-configuration-api)) done by the Woodpecker server switched from using a shared-secret HMac to an ed25519 key-pair. Read more about it at the [config-extensions](/docs/administration/advanced/external-configuration-api) documentation.
|
- The signature used to verify extension calls (like those used for the [config-extension](/docs/administration/configuration/server#external-configuration-api)) done by the Woodpecker server switched from using a shared-secret HMac to an ed25519 key-pair. Read more about it at the [config-extensions](/docs/administration/configuration/server#external-configuration-api) documentation.
|
||||||
- Refactored support for old agent filter labels and expressions. Learn how to use the new [filter](/docs/usage/workflow-syntax#labels)
|
- Refactored support for old agent filter labels and expressions. Learn how to use the new [filter](/docs/usage/workflow-syntax#labels)
|
||||||
- Renamed step environment variable `CI_SYSTEM_ARCH` to `CI_SYSTEM_PLATFORM`. Same applies for the cli exec variable.
|
- Renamed step environment variable `CI_SYSTEM_ARCH` to `CI_SYSTEM_PLATFORM`. Same applies for the cli exec variable.
|
||||||
- Renamed environment variables `CI_BUILD_*` and `CI_PREV_BUILD_*` to `CI_PIPELINE_*` and `CI_PREV_PIPELINE_*`, old ones are still available but deprecated
|
- Renamed environment variables `CI_BUILD_*` and `CI_PREV_BUILD_*` to `CI_PIPELINE_*` and `CI_PREV_PIPELINE_*`, old ones are still available but deprecated
|
||||||
|
|||||||
@ -1,133 +0,0 @@
|
|||||||
# Secrets
|
|
||||||
|
|
||||||
Woodpecker provides the ability to store named parameters external to the YAML configuration file, in a central secret store. These secrets can be passed to individual steps of the pipeline at runtime.
|
|
||||||
|
|
||||||
Woodpecker provides three different levels to add secrets to your pipeline. The following list shows the priority of the different levels. If a secret is defined in multiple levels, will be used following this priorities: Repository secrets > Organization secrets > Global secrets.
|
|
||||||
|
|
||||||
1. **Repository secrets**: They are available to all pipelines of an repository.
|
|
||||||
2. **Organization secrets**: They are available to all pipelines of an organization.
|
|
||||||
3. **Global secrets**: Can be configured by an instance admin.
|
|
||||||
They are available to all pipelines of the **whole** Woodpecker instance and should therefore **only** be used for secrets that are allowed to be read by **all** users.
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
### Use secrets in commands
|
|
||||||
|
|
||||||
Secrets are exposed to your pipeline steps and plugins as uppercase environment variables and can therefore be referenced in the commands section of your pipeline,
|
|
||||||
once their usage is declared in the `secrets` section:
|
|
||||||
|
|
||||||
```diff
|
|
||||||
steps:
|
|
||||||
- name: docker
|
|
||||||
image: docker
|
|
||||||
commands:
|
|
||||||
+ - echo $docker_username
|
|
||||||
+ - echo $DOCKER_PASSWORD
|
|
||||||
+ secrets: [ docker_username, DOCKER_PASSWORD ]
|
|
||||||
```
|
|
||||||
|
|
||||||
The case of the environment variables is not changed, but secret matching is done case-insensitively. In the example above, `DOCKER_PASSWORD` would also match if the secret is called `docker_password`.
|
|
||||||
|
|
||||||
### Use secrets in settings and environment
|
|
||||||
|
|
||||||
You can set an setting or environment value from secrets using the `from_secret` syntax.
|
|
||||||
|
|
||||||
In this example, the secret named `secret_token` would be passed to the setting named `token`,which will be available in the plugin as environment variable named `PLUGIN_TOKEN` (See [plugins](./51-plugins/20-creating-plugins.md#settings) for details), and to the environment variable `TOKEN_ENV`.
|
|
||||||
|
|
||||||
```diff
|
|
||||||
steps:
|
|
||||||
- name: docker
|
|
||||||
image: my-plugin
|
|
||||||
+ environment:
|
|
||||||
+ TOKEN_ENV:
|
|
||||||
+ from_secret: secret_token
|
|
||||||
+ settings:
|
|
||||||
+ token:
|
|
||||||
+ from_secret: secret_token
|
|
||||||
```
|
|
||||||
|
|
||||||
### Note about parameter pre-processing
|
|
||||||
|
|
||||||
Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped.
|
|
||||||
|
|
||||||
```diff
|
|
||||||
steps:
|
|
||||||
- name: docker
|
|
||||||
image: docker
|
|
||||||
commands:
|
|
||||||
- - echo ${docker_username}
|
|
||||||
- - echo ${DOCKER_PASSWORD}
|
|
||||||
+ - echo $${docker_username}
|
|
||||||
+ - echo $${DOCKER_PASSWORD}
|
|
||||||
secrets: [ docker_username, DOCKER_PASSWORD ]
|
|
||||||
```
|
|
||||||
|
|
||||||
### Use in Pull Requests events
|
|
||||||
|
|
||||||
Secrets are not exposed to pull requests by default. You can override this behavior by creating the secret and enabling the `pull_request` event type, either in UI or by CLI, see below.
|
|
||||||
|
|
||||||
:::note
|
|
||||||
Please be careful when exposing secrets to pull requests. If your repository is open source and accepts pull requests your secrets are not safe. A bad actor can submit a malicious pull request that exposes your secrets.
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Image filter
|
|
||||||
|
|
||||||
To prevent abusing your secrets from malicious usage, you can limit a secret to a list of images. If enabled they are not available to any other plugin (steps without user-defined commands). If you or an attacker defines explicit commands, the secrets will not be available to the container to prevent leaking them.
|
|
||||||
|
|
||||||
## Adding Secrets
|
|
||||||
|
|
||||||
Secrets are added to the Woodpecker in the UI or with 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 secret add \
|
|
||||||
-repository octocat/hello-world \
|
|
||||||
-name aws_access_key_id \
|
|
||||||
-value <value>
|
|
||||||
```
|
|
||||||
|
|
||||||
Create the secret and limit to a single image:
|
|
||||||
|
|
||||||
```diff
|
|
||||||
woodpecker-cli secret add \
|
|
||||||
-repository octocat/hello-world \
|
|
||||||
+ -image plugins/s3 \
|
|
||||||
-name aws_access_key_id \
|
|
||||||
-value <value>
|
|
||||||
```
|
|
||||||
|
|
||||||
Create the secrets and limit to a set of images:
|
|
||||||
|
|
||||||
```diff
|
|
||||||
woodpecker-cli secret add \
|
|
||||||
-repository octocat/hello-world \
|
|
||||||
+ -image plugins/s3 \
|
|
||||||
+ -image peloton/woodpecker-ecs \
|
|
||||||
-name aws_access_key_id \
|
|
||||||
-value <value>
|
|
||||||
```
|
|
||||||
|
|
||||||
Create the secret and enable for multiple hook events:
|
|
||||||
|
|
||||||
```diff
|
|
||||||
woodpecker-cli secret add \
|
|
||||||
-repository octocat/hello-world \
|
|
||||||
-image plugins/s3 \
|
|
||||||
+ -event pull_request \
|
|
||||||
+ -event push \
|
|
||||||
+ -event tag \
|
|
||||||
-name aws_access_key_id \
|
|
||||||
-value <value>
|
|
||||||
```
|
|
||||||
|
|
||||||
Loading secrets from file using curl `@` syntax. This is the recommended approach for loading secrets from file to preserve newlines:
|
|
||||||
|
|
||||||
```diff
|
|
||||||
woodpecker-cli secret add \
|
|
||||||
-repository octocat/hello-world \
|
|
||||||
-name ssh_key \
|
|
||||||
+ -value @/root/ssh/id_rsa
|
|
||||||
```
|
|
||||||
@ -1,129 +0,0 @@
|
|||||||
# Advanced usage
|
|
||||||
|
|
||||||
## Advanced YAML syntax
|
|
||||||
|
|
||||||
YAML has some advanced syntax features that can be used like variables to reduce duplication in your pipeline config:
|
|
||||||
|
|
||||||
### Anchors & aliases
|
|
||||||
|
|
||||||
You can use [YAML anchors & aliases](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) as variables in your pipeline config.
|
|
||||||
|
|
||||||
To convert this:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
steps:
|
|
||||||
- name: test
|
|
||||||
image: golang:1.18
|
|
||||||
commands: go test ./...
|
|
||||||
- name: build
|
|
||||||
image: golang:1.18
|
|
||||||
commands: build
|
|
||||||
```
|
|
||||||
|
|
||||||
Just add a new section called **variables** like this:
|
|
||||||
|
|
||||||
```diff
|
|
||||||
+variables:
|
|
||||||
+ - &golang_image 'golang:1.18'
|
|
||||||
|
|
||||||
steps:
|
|
||||||
- name: test
|
|
||||||
- image: golang:1.18
|
|
||||||
+ image: *golang_image
|
|
||||||
commands: go test ./...
|
|
||||||
- name: build
|
|
||||||
- image: golang:1.18
|
|
||||||
+ image: *golang_image
|
|
||||||
commands: build
|
|
||||||
```
|
|
||||||
|
|
||||||
### Map merges and overwrites
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
variables:
|
|
||||||
- &base-plugin-settings
|
|
||||||
target: dist
|
|
||||||
recursive: false
|
|
||||||
try: true
|
|
||||||
- &special-setting
|
|
||||||
special: true
|
|
||||||
- &some-plugin codeberg.org/6543/docker-images/print_env
|
|
||||||
|
|
||||||
steps:
|
|
||||||
- name: develop
|
|
||||||
image: *some-plugin
|
|
||||||
settings:
|
|
||||||
<<: [*base-plugin-settings, *special-setting] # merge two maps into an empty map
|
|
||||||
when:
|
|
||||||
branch: develop
|
|
||||||
|
|
||||||
- name: main
|
|
||||||
image: *some-plugin
|
|
||||||
settings:
|
|
||||||
<<: *base-plugin-settings # merge one map and ...
|
|
||||||
try: false # ... overwrite original value
|
|
||||||
ongoing: false # ... adding a new value
|
|
||||||
when:
|
|
||||||
branch: main
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sequence merges
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
variables:
|
|
||||||
pre_cmds: &pre_cmds
|
|
||||||
- echo start
|
|
||||||
- whoami
|
|
||||||
post_cmds: &post_cmds
|
|
||||||
- echo stop
|
|
||||||
hello_cmd: &hello_cmd
|
|
||||||
- echo hello
|
|
||||||
|
|
||||||
steps:
|
|
||||||
- name: step1
|
|
||||||
image: debian
|
|
||||||
commands:
|
|
||||||
- <<: *pre_cmds # prepend a sequence
|
|
||||||
- echo exec step now do dedicated things
|
|
||||||
- <<: *post_cmds # append a sequence
|
|
||||||
- name: step2
|
|
||||||
image: debian
|
|
||||||
commands:
|
|
||||||
- <<: [*pre_cmds, *hello_cmd] # prepend two sequences
|
|
||||||
- echo echo from second step
|
|
||||||
- <<: *post_cmds
|
|
||||||
```
|
|
||||||
|
|
||||||
### References
|
|
||||||
|
|
||||||
- [Official YAML specification](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases)
|
|
||||||
- [YAML Cheatsheet](https://learnxinyminutes.com/docs/yaml)
|
|
||||||
|
|
||||||
## Persisting environment data between steps
|
|
||||||
|
|
||||||
One can create a file containing environment variables, and then source it in each step that needs them.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
steps:
|
|
||||||
- name: init
|
|
||||||
image: bash
|
|
||||||
commands:
|
|
||||||
- echo "FOO=hello" >> envvars
|
|
||||||
- echo "BAR=world" >> envvars
|
|
||||||
|
|
||||||
- name: debug
|
|
||||||
image: bash
|
|
||||||
commands:
|
|
||||||
- source envvars
|
|
||||||
- echo $FOO
|
|
||||||
```
|
|
||||||
|
|
||||||
## Declaring global variables
|
|
||||||
|
|
||||||
As described in [Global environment variables](./50-environment.md#global-environment-variables), you can define global variables:
|
|
||||||
|
|
||||||
```ini
|
|
||||||
WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2
|
|
||||||
```
|
|
||||||
|
|
||||||
Note that this tightly couples the server and app configurations (where the app is a completely separate application). But this is a good option for truly global variables which should apply to all steps in all pipelines for all apps.
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 165 KiB |
@ -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,147 +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"
|
|
||||||
version: '3'
|
|
||||||
|
|
||||||
services:
|
|
||||||
woodpecker-server:
|
|
||||||
image: woodpeckerci/woodpecker-server:latest
|
|
||||||
ports:
|
|
||||||
- 8000:8000
|
|
||||||
volumes:
|
|
||||||
- woodpecker-server-data:/var/lib/woodpecker/
|
|
||||||
environment:
|
|
||||||
- WOODPECKER_OPEN=true
|
|
||||||
- WOODPECKER_HOST=${WOODPECKER_HOST}
|
|
||||||
- WOODPECKER_GITHUB=true
|
|
||||||
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
|
|
||||||
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
|
|
||||||
- WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
|
|
||||||
|
|
||||||
woodpecker-agent:
|
|
||||||
image: woodpeckerci/woodpecker-agent:latest
|
|
||||||
command: agent
|
|
||||||
restart: always
|
|
||||||
depends_on:
|
|
||||||
- woodpecker-server
|
|
||||||
volumes:
|
|
||||||
- woodpecker-agent-config:/etc/woodpecker
|
|
||||||
- /var/run/docker.sock:/var/run/docker.sock
|
|
||||||
environment:
|
|
||||||
- WOODPECKER_SERVER=woodpecker-server:9000
|
|
||||||
- WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
|
|
||||||
|
|
||||||
volumes:
|
|
||||||
woodpecker-server-data:
|
|
||||||
woodpecker-agent-config:
|
|
||||||
```
|
|
||||||
|
|
||||||
Woodpecker needs to know its own address. You must therefore provide the public address of it in `<scheme>://<hostname>` format. Please omit trailing slashes:
|
|
||||||
|
|
||||||
```diff title="docker-compose.yaml"
|
|
||||||
version: '3'
|
|
||||||
|
|
||||||
services:
|
|
||||||
woodpecker-server:
|
|
||||||
[...]
|
|
||||||
environment:
|
|
||||||
- [...]
|
|
||||||
+ - WOODPECKER_HOST=${WOODPECKER_HOST}
|
|
||||||
```
|
|
||||||
|
|
||||||
Woodpecker can also have its port's configured. It uses a separate port for gRPC and for HTTP. The agent performs gRPC calls and connects to the gRPC port.
|
|
||||||
They can be configured with `*_ADDR` variables:
|
|
||||||
|
|
||||||
```diff title="docker-compose.yaml"
|
|
||||||
version: '3'
|
|
||||||
services:
|
|
||||||
woodpecker-server:
|
|
||||||
[...]
|
|
||||||
environment:
|
|
||||||
- [...]
|
|
||||||
+ - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR}
|
|
||||||
+ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR}
|
|
||||||
```
|
|
||||||
|
|
||||||
Reverse proxying can also be [configured for gRPC](../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"
|
|
||||||
version: '3'
|
|
||||||
services:
|
|
||||||
woodpecker-server:
|
|
||||||
[...]
|
|
||||||
environment:
|
|
||||||
- [...]
|
|
||||||
+ - WOODPECKER_GRPC_SECURE=true # defaults to false
|
|
||||||
+ - WOODPECKER_GRPC_VERIFY=true # default
|
|
||||||
```
|
|
||||||
|
|
||||||
As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon:
|
|
||||||
|
|
||||||
```diff title="docker-compose.yaml"
|
|
||||||
version: '3'
|
|
||||||
|
|
||||||
services:
|
|
||||||
[...]
|
|
||||||
woodpecker-agent:
|
|
||||||
[...]
|
|
||||||
+ volumes:
|
|
||||||
+ - /var/run/docker.sock:/var/run/docker.sock
|
|
||||||
```
|
|
||||||
|
|
||||||
Agents require the server address for agent-to-server communication. The agent connects to the server's gRPC port:
|
|
||||||
|
|
||||||
```diff title="docker-compose.yaml"
|
|
||||||
version: '3'
|
|
||||||
|
|
||||||
services:
|
|
||||||
woodpecker-agent:
|
|
||||||
[...]
|
|
||||||
environment:
|
|
||||||
+ - WOODPECKER_SERVER=woodpecker-server:9000
|
|
||||||
```
|
|
||||||
|
|
||||||
The server and agents use a shared secret to authenticate communication. This should be a random string of your choosing and should be kept private. You can generate such string with `openssl rand -hex 32`:
|
|
||||||
|
|
||||||
```diff title="docker-compose.yaml"
|
|
||||||
version: '3'
|
|
||||||
|
|
||||||
services:
|
|
||||||
woodpecker-server:
|
|
||||||
[...]
|
|
||||||
environment:
|
|
||||||
- [...]
|
|
||||||
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
|
|
||||||
woodpecker-agent:
|
|
||||||
[...]
|
|
||||||
environment:
|
|
||||||
- [...]
|
|
||||||
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Docker images
|
|
||||||
|
|
||||||
Image variants:
|
|
||||||
|
|
||||||
- The `latest` image is the latest stable release
|
|
||||||
- The `vX.X.X` images are stable releases
|
|
||||||
- The `vX.X` images are based on the current release branch (e.g. `release/v1.0`) and can be used to get bugfixes asap
|
|
||||||
- The `next` images are based on the current `main` branch
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# server
|
|
||||||
docker pull woodpeckerci/woodpecker-server:latest
|
|
||||||
docker pull woodpeckerci/woodpecker-server:latest-alpine
|
|
||||||
|
|
||||||
# agent
|
|
||||||
docker pull woodpeckerci/woodpecker-agent:latest
|
|
||||||
docker pull woodpeckerci/woodpecker-agent:latest-alpine
|
|
||||||
|
|
||||||
# cli
|
|
||||||
docker pull woodpeckerci/woodpecker-cli:latest
|
|
||||||
docker pull woodpeckerci/woodpecker-cli:latest-alpine
|
|
||||||
```
|
|
||||||
@ -1,9 +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 subcharts, `server` and `agent` which are automatically configured as needed.
|
|
||||||
The chart started off with two independent charts but was merged into one to simplify the deployment at start of 2023.
|
|
||||||
|
|
||||||
A couple of backend-specific config env vars exists which are described in the [kubernetes backend docs](../22-backends/40-kubernetes.md).
|
|
||||||
@ -1,12 +0,0 @@
|
|||||||
# Third-party installation methods
|
|
||||||
|
|
||||||
:::info
|
|
||||||
These installation methods are not officially supported. If you experience issues with them, please open issues in the specific repositories.
|
|
||||||
:::
|
|
||||||
|
|
||||||
- [Using NixOS](./40-nixos.md) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker)
|
|
||||||
- [On Alpine Edge](https://pkgs.alpinelinux.org/packages?name=woodpecker&branch=edge&repo=&arch=&maintainer=)
|
|
||||||
- [On Arch Linux](https://archlinux.org/packages/?q=woodpecker)
|
|
||||||
- [On openSUSE](https://software.opensuse.org/package/woodpecker)
|
|
||||||
- [Using YunoHost](https://apps.yunohost.org/app/woodpecker)
|
|
||||||
- [On Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html)
|
|
||||||
@ -1,88 +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
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{ config
|
|
||||||
, ...
|
|
||||||
}:
|
|
||||||
let
|
|
||||||
domain = "woodpecker.example.org";
|
|
||||||
in
|
|
||||||
{
|
|
||||||
# This automatically sets up certificates via let's encrypt
|
|
||||||
security.acme.defaults.email = "acme@example.com";
|
|
||||||
security.acme.acceptTerms = true;
|
|
||||||
security.acme.certs."${domain}" = { };
|
|
||||||
|
|
||||||
# Setting up a nginx proxy that handles tls for us
|
|
||||||
networking.firewall.allowedTCPPorts = [ 80 443 ];
|
|
||||||
services.nginx = {
|
|
||||||
enable = true;
|
|
||||||
recommendedTlsSettings = true;
|
|
||||||
recommendedOptimisation = true;
|
|
||||||
recommendedProxySettings = true;
|
|
||||||
virtualHosts."${domain}" = {
|
|
||||||
enableACME = true;
|
|
||||||
forceSSL = true;
|
|
||||||
locations."/" = {
|
|
||||||
proxyPass = "http://localhost:3007";
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
|
|
||||||
services.woodpecker-server = {
|
|
||||||
enable = true;
|
|
||||||
environment = {
|
|
||||||
WOODPECKER_HOST = "https://${domain}";
|
|
||||||
WOODPECKER_SERVER_ADDR = ":3007";
|
|
||||||
WOODPECKER_OPEN = "true";
|
|
||||||
};
|
|
||||||
# You can pass a file with env vars to the system it could look like:
|
|
||||||
# WOODPECKER_AGENT_SECRET=XXXXXXXXXXXXXXXXXXXXXX
|
|
||||||
environmentFile = "/path/to/my/secrets/file";
|
|
||||||
};
|
|
||||||
|
|
||||||
# This sets up a woodpecker agent
|
|
||||||
services.woodpecker-agents.agents."docker" = {
|
|
||||||
enable = true;
|
|
||||||
# We need this to talk to the podman socket
|
|
||||||
extraGroups = [ "podman" ];
|
|
||||||
environment = {
|
|
||||||
WOODPECKER_SERVER = "localhost:9000";
|
|
||||||
WOODPECKER_MAX_WORKFLOWS = "4";
|
|
||||||
DOCKER_HOST = "unix:///run/podman/podman.sock";
|
|
||||||
WOODPECKER_BACKEND = "docker";
|
|
||||||
};
|
|
||||||
# Same as with woodpecker-server
|
|
||||||
environmentFile = [ "/var/lib/secrets/woodpecker.env" ];
|
|
||||||
};
|
|
||||||
|
|
||||||
# Here we setup podman and enable dns
|
|
||||||
virtualisation.podman = {
|
|
||||||
enable = true;
|
|
||||||
defaultNetwork.settings = {
|
|
||||||
dns_enabled = true;
|
|
||||||
};
|
|
||||||
};
|
|
||||||
# This is needed for podman to be able to talk over dns
|
|
||||||
networking.firewall.interfaces."podman0" = {
|
|
||||||
allowedUDPPorts = [ 53 ];
|
|
||||||
allowedTCPPorts = [ 53 ];
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
All configuration options can be found via [NixOS Search](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker)
|
|
||||||
|
|
||||||
## Tips and tricks
|
|
||||||
|
|
||||||
There are some resources on how to utilize Woodpecker more effectively with NixOS on the [Awesome Woodpecker](../../92-awesome.md) page, like using the runners nix-store in the pipeline.
|
|
||||||
@ -1,53 +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"
|
|
||||||
version: '3'
|
|
||||||
|
|
||||||
services:
|
|
||||||
woodpecker-server:
|
|
||||||
[...]
|
|
||||||
+ volumes:
|
|
||||||
+ - woodpecker-server-data:/var/lib/woodpecker/
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configure MySQL/MariaDB
|
|
||||||
|
|
||||||
The below example demonstrates MySQL database configuration. See the official driver [documentation](https://github.com/go-sql-driver/mysql#dsn-data-source-name) for configuration options and examples.
|
|
||||||
The minimum version of MySQL/MariaDB required is determined by the `go-sql-driver/mysql` - see [it's README](https://github.com/go-sql-driver/mysql#requirements) for more information.
|
|
||||||
|
|
||||||
```ini
|
|
||||||
WOODPECKER_DATABASE_DRIVER=mysql
|
|
||||||
WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configure Postgres
|
|
||||||
|
|
||||||
The below example demonstrates Postgres database configuration. See the official driver [documentation](https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING) for configuration options and examples.
|
|
||||||
Please use Postgres versions equal or higher than **11**.
|
|
||||||
|
|
||||||
```ini
|
|
||||||
WOODPECKER_DATABASE_DRIVER=postgres
|
|
||||||
WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/postgres?sslmode=disable
|
|
||||||
```
|
|
||||||
|
|
||||||
## Database Creation
|
|
||||||
|
|
||||||
Woodpecker does not create your database automatically. If you are using the MySQL or Postgres driver you will need to manually create your database using `CREATE DATABASE`.
|
|
||||||
|
|
||||||
## Database Migration
|
|
||||||
|
|
||||||
Woodpecker automatically handles database migration, including the initial creation of tables and indexes. New versions of Woodpecker will automatically upgrade the database unless otherwise specified in the release notes.
|
|
||||||
|
|
||||||
## Database Backups
|
|
||||||
|
|
||||||
Woodpecker does not perform database backups. This should be handled by separate third party tools provided by your database vendor of choice.
|
|
||||||
|
|
||||||
## Database Archiving
|
|
||||||
|
|
||||||
Woodpecker does not perform data archival; it considered out-of-scope for the project. Woodpecker is rather conservative with the amount of data it stores, however, you should expect the database logs to grow the size of your database considerably.
|
|
||||||
@ -1,578 +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=johnsmith,janedoe
|
|
||||||
```
|
|
||||||
|
|
||||||
### Only allow registration of users, who are members of approved organizations
|
|
||||||
|
|
||||||
```ini
|
|
||||||
WOODPECKER_OPEN=true
|
|
||||||
WOODPECKER_ORGS=dolores,dogpatch
|
|
||||||
```
|
|
||||||
|
|
||||||
## Administrators
|
|
||||||
|
|
||||||
Administrators should also be enumerated in your configuration.
|
|
||||||
|
|
||||||
```ini
|
|
||||||
WOODPECKER_ADMIN=johnsmith,janedoe
|
|
||||||
```
|
|
||||||
|
|
||||||
## Filtering repositories
|
|
||||||
|
|
||||||
Woodpecker operates with the user's OAuth permission. Due to the coarse permission handling of GitHub, you may end up syncing more repos into Woodpecker than preferred.
|
|
||||||
|
|
||||||
Use the `WOODPECKER_REPO_OWNERS` variable to filter which GitHub user's repos should be synced only. You typically want to put here your company's GitHub name.
|
|
||||||
|
|
||||||
```ini
|
|
||||||
WOODPECKER_REPO_OWNERS=mycompany,mycompanyossgithubuser
|
|
||||||
```
|
|
||||||
|
|
||||||
## Global registry setting
|
|
||||||
|
|
||||||
If you want to make available a specific private registry to all pipelines, use the `WOODPECKER_DOCKER_CONFIG` server configuration.
|
|
||||||
Point it to your server's docker config.
|
|
||||||
|
|
||||||
```ini
|
|
||||||
WOODPECKER_DOCKER_CONFIG=/root/.docker/config.json
|
|
||||||
```
|
|
||||||
|
|
||||||
## Handling sensitive data in docker-compose and docker-swarm
|
|
||||||
|
|
||||||
To handle sensitive data in docker-compose or docker-swarm configurations there are several options:
|
|
||||||
|
|
||||||
For docker-compose you can use a `.env` file next to your compose configuration to store the secrets outside of the compose file. While this separates configuration from secrets it is still not very secure.
|
|
||||||
|
|
||||||
Alternatively use docker-secrets. As it may be difficult to use docker secrets for environment variables Woodpecker allows to read sensible data from files by providing a `*_FILE` option of all sensible configuration variables. Woodpecker will try to read the value directly from this file. Keep in mind that when the original environment variable gets specified at the same time it will override the value read from the file.
|
|
||||||
|
|
||||||
```diff title="docker-compose.yaml"
|
|
||||||
version: '3'
|
|
||||||
|
|
||||||
services:
|
|
||||||
woodpecker-server:
|
|
||||||
[...]
|
|
||||||
environment:
|
|
||||||
- [...]
|
|
||||||
+ - WOODPECKER_AGENT_SECRET_FILE=/run/secrets/woodpecker-agent-secret
|
|
||||||
+ secrets:
|
|
||||||
+ - woodpecker-agent-secret
|
|
||||||
+
|
|
||||||
+ secrets:
|
|
||||||
+ woodpecker-agent-secret:
|
|
||||||
+ external: true
|
|
||||||
```
|
|
||||||
|
|
||||||
Store a value to a docker secret like this:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
echo "my_agent_secret_key" | docker secret create woodpecker-agent-secret -
|
|
||||||
```
|
|
||||||
|
|
||||||
or generate a random one like this:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
openssl rand -hex 32 | docker secret create woodpecker-agent-secret -
|
|
||||||
```
|
|
||||||
|
|
||||||
## Custom JavaScript and CSS
|
|
||||||
|
|
||||||
Woodpecker supports custom JS and CSS files.
|
|
||||||
These files must be present in the server's filesystem.
|
|
||||||
They can be backed in a Docker image or mounted from a ConfigMap inside a Kubernetes environment.
|
|
||||||
The configuration variables are independent of each other, which means it can be just one file present, or both.
|
|
||||||
|
|
||||||
```ini
|
|
||||||
WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.css
|
|
||||||
WOODPECKER_CUSTOM_JS_FILE=/usr/local/www/woodpecker.js
|
|
||||||
```
|
|
||||||
|
|
||||||
The examples below show how to place a banner message in the top navigation bar of Woodpecker.
|
|
||||||
|
|
||||||
### `woodpecker.css`
|
|
||||||
|
|
||||||
```css
|
|
||||||
.banner-message {
|
|
||||||
position: absolute;
|
|
||||||
width: 280px;
|
|
||||||
height: 40px;
|
|
||||||
margin-left: 240px;
|
|
||||||
margin-top: 5px;
|
|
||||||
padding-top: 5px;
|
|
||||||
font-weight: bold;
|
|
||||||
background: red no-repeat;
|
|
||||||
text-align: center;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### `woodpecker.js`
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
// place/copy a minified version of jQuery or ZeptoJS here ...
|
|
||||||
!(function () {
|
|
||||||
'use strict';
|
|
||||||
function e() {} /*...*/
|
|
||||||
})();
|
|
||||||
|
|
||||||
$().ready(function () {
|
|
||||||
$('.app nav img').first().htmlAfter("<div class='banner-message'>This is a demo banner message :)</div>");
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## All server configuration options
|
|
||||||
|
|
||||||
The following list describes all available server configuration options.
|
|
||||||
|
|
||||||
### `WOODPECKER_LOG_LEVEL`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty.
|
|
||||||
|
|
||||||
### `WOODPECKER_LOG_FILE`
|
|
||||||
|
|
||||||
> Default: `stderr`
|
|
||||||
|
|
||||||
Output destination for logs.
|
|
||||||
'stdout' and 'stderr' can be used as special keywords.
|
|
||||||
|
|
||||||
### `WOODPECKER_LOG_XORM`
|
|
||||||
|
|
||||||
> Default: `false`
|
|
||||||
|
|
||||||
Enable XORM logs.
|
|
||||||
|
|
||||||
### `WOODPECKER_LOG_XORM_SQL`
|
|
||||||
|
|
||||||
> Default: `false`
|
|
||||||
|
|
||||||
Enable XORM SQL command logs.
|
|
||||||
|
|
||||||
### `WOODPECKER_DEBUG_PRETTY`
|
|
||||||
|
|
||||||
> Default: `false`
|
|
||||||
|
|
||||||
Enable pretty-printed debug output.
|
|
||||||
|
|
||||||
### `WOODPECKER_DEBUG_NOCOLOR`
|
|
||||||
|
|
||||||
> Default: `true`
|
|
||||||
|
|
||||||
Disable colored debug output.
|
|
||||||
|
|
||||||
### `WOODPECKER_HOST`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Server fully qualified URL of the user-facing hostname, port (if not default for HTTP/HTTPS) and path prefix.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
- `WOODPECKER_HOST=http://woodpecker.example.org`
|
|
||||||
- `WOODPECKER_HOST=http://example.org/woodpecker`
|
|
||||||
- `WOODPECKER_HOST=http://example.org:1234/woodpecker`
|
|
||||||
|
|
||||||
### `WOODPECKER_WEBHOOK_HOST`
|
|
||||||
|
|
||||||
> Default: value from `WOODPECKER_HOST` config env
|
|
||||||
|
|
||||||
Server fully qualified URL of the Webhook-facing hostname and path prefix.
|
|
||||||
|
|
||||||
Example: `WOODPECKER_WEBHOOK_HOST=http://woodpecker-server.cicd.svc.cluster.local:8000`
|
|
||||||
|
|
||||||
### `WOODPECKER_SERVER_ADDR`
|
|
||||||
|
|
||||||
> Default: `:8000`
|
|
||||||
|
|
||||||
Configures the HTTP listener port.
|
|
||||||
|
|
||||||
### `WOODPECKER_SERVER_ADDR_TLS`
|
|
||||||
|
|
||||||
> Default: `:443`
|
|
||||||
|
|
||||||
Configures the HTTPS listener port when SSL is enabled.
|
|
||||||
|
|
||||||
### `WOODPECKER_SERVER_CERT`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Path to an SSL certificate used by the server to accept HTTPS requests.
|
|
||||||
|
|
||||||
Example: `WOODPECKER_SERVER_CERT=/path/to/cert.pem`
|
|
||||||
|
|
||||||
### `WOODPECKER_SERVER_KEY`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Path to an SSL certificate key used by the server to accept HTTPS requests.
|
|
||||||
|
|
||||||
Example: `WOODPECKER_SERVER_KEY=/path/to/key.pem`
|
|
||||||
|
|
||||||
### `WOODPECKER_CUSTOM_CSS_FILE`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
File path for the server to serve a custom .CSS file, used for customizing the UI.
|
|
||||||
Can be used for showing banner messages, logos, or environment-specific hints (a.k.a. white-labeling).
|
|
||||||
The file must be UTF-8 encoded, to ensure all special characters are preserved.
|
|
||||||
|
|
||||||
Example: `WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.css`
|
|
||||||
|
|
||||||
### `WOODPECKER_CUSTOM_JS_FILE`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
File path for the server to serve a custom .JS file, used for customizing the UI.
|
|
||||||
Can be used for showing banner messages, logos, or environment-specific hints (a.k.a. white-labeling).
|
|
||||||
The file must be UTF-8 encoded, to ensure all special characters are preserved.
|
|
||||||
|
|
||||||
Example: `WOODPECKER_CUSTOM_JS_FILE=/usr/local/www/woodpecker.js`
|
|
||||||
|
|
||||||
### `WOODPECKER_LETS_ENCRYPT`
|
|
||||||
|
|
||||||
> Default: `false`
|
|
||||||
|
|
||||||
Automatically generates an SSL certificate using Let's Encrypt, and configures the server to accept HTTPS requests.
|
|
||||||
|
|
||||||
### `WOODPECKER_GRPC_ADDR`
|
|
||||||
|
|
||||||
> Default: `:9000`
|
|
||||||
|
|
||||||
Configures the gRPC listener port.
|
|
||||||
|
|
||||||
### `WOODPECKER_GRPC_SECRET`
|
|
||||||
|
|
||||||
> Default: `secret`
|
|
||||||
|
|
||||||
Configures the gRPC JWT secret.
|
|
||||||
|
|
||||||
### `WOODPECKER_GRPC_SECRET_FILE`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Read the value for `WOODPECKER_GRPC_SECRET` from the specified filepath.
|
|
||||||
|
|
||||||
### `WOODPECKER_METRICS_SERVER_ADDR`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Configures an unprotected metrics endpoint. An empty value disables the metrics endpoint completely.
|
|
||||||
|
|
||||||
Example: `:9001`
|
|
||||||
|
|
||||||
### `WOODPECKER_ADMIN`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Comma-separated list of admin accounts.
|
|
||||||
|
|
||||||
Example: `WOODPECKER_ADMIN=user1,user2`
|
|
||||||
|
|
||||||
### `WOODPECKER_ORGS`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Comma-separated list of approved organizations.
|
|
||||||
|
|
||||||
Example: `org1,org2`
|
|
||||||
|
|
||||||
### `WOODPECKER_REPO_OWNERS`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Repositories by those owners will be allowed to be used in woodpecker.
|
|
||||||
|
|
||||||
Example: `user1,user2`
|
|
||||||
|
|
||||||
### `WOODPECKER_OPEN`
|
|
||||||
|
|
||||||
> Default: `false`
|
|
||||||
|
|
||||||
Enable to allow user registration.
|
|
||||||
|
|
||||||
### `WOODPECKER_AUTHENTICATE_PUBLIC_REPOS`
|
|
||||||
|
|
||||||
> Default: `false`
|
|
||||||
|
|
||||||
Always use authentication to clone repositories even if they are public. Needed if the forge requires to always authenticate as used by many companies.
|
|
||||||
|
|
||||||
### `WOODPECKER_DEFAULT_CANCEL_PREVIOUS_PIPELINE_EVENTS`
|
|
||||||
|
|
||||||
> Default: `pull_request, push`
|
|
||||||
|
|
||||||
List of event names that will be canceled when a new pipeline for the same context (tag, branch) is created.
|
|
||||||
|
|
||||||
### `WOODPECKER_DEFAULT_CLONE_IMAGE`
|
|
||||||
|
|
||||||
> Default is defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go)
|
|
||||||
|
|
||||||
The default docker image to be used when cloning the repo
|
|
||||||
|
|
||||||
### `WOODPECKER_DEFAULT_PIPELINE_TIMEOUT`
|
|
||||||
|
|
||||||
> 60 (minutes)
|
|
||||||
|
|
||||||
The default time for a repo in minutes before a pipeline gets killed
|
|
||||||
|
|
||||||
### `WOODPECKER_MAX_PIPELINE_TIMEOUT`
|
|
||||||
|
|
||||||
> 120 (minutes)
|
|
||||||
|
|
||||||
The maximum time in minutes you can set in the repo settings before a pipeline gets killed
|
|
||||||
|
|
||||||
### `WOODPECKER_SESSION_EXPIRES`
|
|
||||||
|
|
||||||
> Default: `72h`
|
|
||||||
|
|
||||||
Configures the session expiration time.
|
|
||||||
Context: when someone does log into Woodpecker, a temporary session token is created.
|
|
||||||
As long as the session is valid (until it expires or log-out),
|
|
||||||
a user can log into Woodpecker, without re-authentication.
|
|
||||||
|
|
||||||
### `WOODPECKER_ESCALATE`
|
|
||||||
|
|
||||||
> Defaults are defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go)
|
|
||||||
|
|
||||||
Docker images to run in privileged mode. Only change if you are sure what you do!
|
|
||||||
|
|
||||||
<!--
|
|
||||||
### `WOODPECKER_VOLUME`
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Comma-separated list of Docker volumes that are mounted into every pipeline step.
|
|
||||||
|
|
||||||
Example: `WOODPECKER_VOLUME=/path/on/host:/path/in/container:rw`|
|
|
||||||
-->
|
|
||||||
|
|
||||||
### `WOODPECKER_DOCKER_CONFIG`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Configures a specific private registry config for all pipelines.
|
|
||||||
|
|
||||||
Example: `WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json`
|
|
||||||
|
|
||||||
<!--
|
|
||||||
### `WOODPECKER_ENVIRONMENT`
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
TODO
|
|
||||||
|
|
||||||
### `WOODPECKER_NETWORK`
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Comma-separated list of Docker networks that are attached to every pipeline step.
|
|
||||||
|
|
||||||
Example: `WOODPECKER_NETWORK=network1,network2`
|
|
||||||
-->
|
|
||||||
|
|
||||||
### `WOODPECKER_AGENT_SECRET`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
A shared secret used by server and agents to authenticate communication. A secret can be generated by `openssl rand -hex 32`.
|
|
||||||
|
|
||||||
### `WOODPECKER_AGENT_SECRET_FILE`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Read the value for `WOODPECKER_AGENT_SECRET` from the specified filepath
|
|
||||||
|
|
||||||
### `WOODPECKER_KEEPALIVE_MIN_TIME`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Server-side enforcement policy on the minimum amount of time a client should wait before sending a keepalive ping.
|
|
||||||
|
|
||||||
Example: `WOODPECKER_KEEPALIVE_MIN_TIME=10s`
|
|
||||||
|
|
||||||
### `WOODPECKER_DATABASE_DRIVER`
|
|
||||||
|
|
||||||
> Default: `sqlite3`
|
|
||||||
|
|
||||||
The database driver name. Possible values are `sqlite3`, `mysql` or `postgres`.
|
|
||||||
|
|
||||||
### `WOODPECKER_DATABASE_DATASOURCE`
|
|
||||||
|
|
||||||
> Default: `woodpecker.sqlite` if not running inside a container, `/var/lib/woodpecker/woodpecker.sqlite` if running inside a container
|
|
||||||
|
|
||||||
The database connection string. The default value is the path of the embedded SQLite database file.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# MySQL
|
|
||||||
# https://github.com/go-sql-driver/mysql#dsn-data-source-name
|
|
||||||
WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true
|
|
||||||
|
|
||||||
# PostgreSQL
|
|
||||||
# https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING
|
|
||||||
WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker?sslmode=disable
|
|
||||||
```
|
|
||||||
|
|
||||||
### `WOODPECKER_DATABASE_DATASOURCE_FILE`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Read the value for `WOODPECKER_DATABASE_DATASOURCE` from the specified filepath
|
|
||||||
|
|
||||||
### `WOODPECKER_PROMETHEUS_AUTH_TOKEN`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Token to secure the Prometheus metrics endpoint.
|
|
||||||
Must be set to enable the endpoint.
|
|
||||||
|
|
||||||
### `WOODPECKER_PROMETHEUS_AUTH_TOKEN_FILE`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Read the value for `WOODPECKER_PROMETHEUS_AUTH_TOKEN` from the specified filepath
|
|
||||||
|
|
||||||
### `WOODPECKER_STATUS_CONTEXT`
|
|
||||||
|
|
||||||
> Default: `ci/woodpecker`
|
|
||||||
|
|
||||||
Context prefix Woodpecker will use to publish status messages to SCM. You probably will only need to change it if you run multiple Woodpecker instances for a single repository.
|
|
||||||
|
|
||||||
### `WOODPECKER_STATUS_CONTEXT_FORMAT`
|
|
||||||
|
|
||||||
> Default: `{{ .context }}/{{ .event }}/{{ .workflow }}{{if not (eq .axis_id 0)}}/{{.axis_id}}{{end}}`
|
|
||||||
|
|
||||||
Template for the status messages published to forges, uses [Go templates](https://pkg.go.dev/text/template) as template language.
|
|
||||||
Supported variables:
|
|
||||||
|
|
||||||
- `context`: Woodpecker's context (see `WOODPECKER_STATUS_CONTEXT`)
|
|
||||||
- `event`: the event which started the pipeline
|
|
||||||
- `workflow`: the workflow's name
|
|
||||||
- `owner`: the repo's owner
|
|
||||||
- `repo`: the repo's name
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `WOODPECKER_LIMIT_MEM_SWAP`
|
|
||||||
|
|
||||||
> Default: `0`
|
|
||||||
|
|
||||||
The maximum amount of memory a single pipeline container is allowed to swap to disk, configured in bytes. There is no limit if `0`.
|
|
||||||
|
|
||||||
### `WOODPECKER_LIMIT_MEM`
|
|
||||||
|
|
||||||
> Default: `0`
|
|
||||||
|
|
||||||
The maximum amount of memory a single pipeline container can use, configured in bytes. There is no limit if `0`.
|
|
||||||
|
|
||||||
### `WOODPECKER_LIMIT_SHM_SIZE`
|
|
||||||
|
|
||||||
> Default: `0`
|
|
||||||
|
|
||||||
The maximum amount of memory of `/dev/shm` allowed in bytes. There is no limit if `0`.
|
|
||||||
|
|
||||||
### `WOODPECKER_LIMIT_CPU_QUOTA`
|
|
||||||
|
|
||||||
> Default: `0`
|
|
||||||
|
|
||||||
The number of microseconds per CPU period that the container is limited to before throttled. There is no limit if `0`.
|
|
||||||
|
|
||||||
### `WOODPECKER_LIMIT_CPU_SHARES`
|
|
||||||
|
|
||||||
> Default: `0`
|
|
||||||
|
|
||||||
The relative weight vs. other containers.
|
|
||||||
|
|
||||||
### `WOODPECKER_LIMIT_CPU_SET`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Comma-separated list to limit the specific CPUs or cores a pipeline container can use.
|
|
||||||
|
|
||||||
Example: `WOODPECKER_LIMIT_CPU_SET=1,2`
|
|
||||||
|
|
||||||
### `WOODPECKER_CONFIG_SERVICE_ENDPOINT`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Specify a configuration service endpoint, see [Configuration Extension](./40-advanced/100-external-configuration-api.md)
|
|
||||||
|
|
||||||
### `WOODPECKER_FORGE_TIMEOUT`
|
|
||||||
|
|
||||||
> Default: 3s
|
|
||||||
|
|
||||||
Specify timeout when fetching the Woodpecker configuration from forge. See <https://pkg.go.dev/time#ParseDuration> for syntax reference.
|
|
||||||
|
|
||||||
### `WOODPECKER_FORGE_RETRY`
|
|
||||||
|
|
||||||
> Default: 3
|
|
||||||
|
|
||||||
Specify how many retries of fetching the Woodpecker configuration from a forge are done before we fail.
|
|
||||||
|
|
||||||
### `WOODPECKER_ENABLE_SWAGGER`
|
|
||||||
|
|
||||||
> Default: true
|
|
||||||
|
|
||||||
Enable the Swagger UI for API documentation.
|
|
||||||
|
|
||||||
### `WOODPECKER_DISABLE_VERSION_CHECK`
|
|
||||||
|
|
||||||
> Default: false
|
|
||||||
|
|
||||||
Disable version check in admin web UI.
|
|
||||||
|
|
||||||
### `WOODPECKER_LOG_STORE`
|
|
||||||
|
|
||||||
> Default: `database`
|
|
||||||
|
|
||||||
Where to store logs. Possible values: `database` or `file`.
|
|
||||||
|
|
||||||
### `WOODPECKER_LOG_STORE_FILE_PATH`
|
|
||||||
|
|
||||||
> Default empty
|
|
||||||
|
|
||||||
Directory to store logs in if [`WOODPECKER_LOG_STORE`](#woodpecker_log_store) is `file`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `WOODPECKER_GITHUB_...`
|
|
||||||
|
|
||||||
See [GitHub configuration](./11-forges/20-github.md#configuration)
|
|
||||||
|
|
||||||
### `WOODPECKER_GITEA_...`
|
|
||||||
|
|
||||||
See [Gitea configuration](./11-forges/30-gitea.md#configuration)
|
|
||||||
|
|
||||||
### `WOODPECKER_BITBUCKET_...`
|
|
||||||
|
|
||||||
See [Bitbucket configuration](./11-forges/50-bitbucket.md#configuration)
|
|
||||||
|
|
||||||
### `WOODPECKER_GITLAB_...`
|
|
||||||
|
|
||||||
See [GitLab configuration](./11-forges/40-gitlab.md#configuration)
|
|
||||||
|
|
||||||
### `WOODPECKER_ADDON_FORGE`
|
|
||||||
|
|
||||||
See [addon forges](./11-forges/100-addon.md).
|
|
||||||
@ -1,13 +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: |
|
|
||||||
@ -1,64 +0,0 @@
|
|||||||
---
|
|
||||||
toc_max_heading_level: 2
|
|
||||||
---
|
|
||||||
|
|
||||||
# Docker backend
|
|
||||||
|
|
||||||
This is the original backend used with Woodpecker. The docker backend executes each step inside a separate container started on the agent.
|
|
||||||
|
|
||||||
## Docker credentials
|
|
||||||
|
|
||||||
Woodpecker supports [Docker credentials](https://github.com/docker/docker-credential-helpers) to securely store registry credentials. Install your corresponding credential helper and configure it in your Docker config file passed via [`WOODPECKER_DOCKER_CONFIG`](../10-server-config.md#woodpecker_docker_config).
|
|
||||||
|
|
||||||
To add your credential helper to the Woodpecker server container you could use the following code to build a custom image:
|
|
||||||
|
|
||||||
```dockerfile
|
|
||||||
FROM woodpeckerci/woodpecker-server:latest-alpine
|
|
||||||
|
|
||||||
RUN apk add -U --no-cache docker-credential-ecr-login
|
|
||||||
```
|
|
||||||
|
|
||||||
## Podman support
|
|
||||||
|
|
||||||
While the agent was developed with Docker/Moby, Podman can also be used by setting the environment variable `DOCKER_HOST` to point to the Podman socket. In order to work without workarounds, Podman 4.0 (or above) is required.
|
|
||||||
|
|
||||||
## Image cleanup
|
|
||||||
|
|
||||||
The agent **will not** automatically remove images from the host. This task should be managed by the host system. For example, you can use a cron job to periodically do clean-up tasks for the CI runner.
|
|
||||||
|
|
||||||
:::danger
|
|
||||||
The following commands **are destructive** and **irreversible** it is highly recommended that you test these commands on your system before running them in production via a cron job or other automation.
|
|
||||||
:::
|
|
||||||
|
|
||||||
### Remove all unused images
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker image rm $(docker images --filter "dangling=true" -q --no-trunc)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Remove Woodpecker volumes
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker volume rm $(docker volume ls --filter name=^wp_* --filter dangling=true -q)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
### `WOODPECKER_BACKEND_DOCKER_NETWORK`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
Set to the name of an existing network which will be attached to all your pipeline containers (steps). Please be careful as this allows the containers of different pipelines to access each other!
|
|
||||||
|
|
||||||
### `WOODPECKER_BACKEND_DOCKER_ENABLE_IPV6`
|
|
||||||
|
|
||||||
> Default: `false`
|
|
||||||
|
|
||||||
Enable IPv6 for the networks used by pipeline containers (steps). Make sure you configured your docker daemon to support IPv6.
|
|
||||||
|
|
||||||
### `WOODPECKER_BACKEND_DOCKER_VOLUMES`
|
|
||||||
|
|
||||||
> Default: empty
|
|
||||||
|
|
||||||
List of default volumes separated by comma to be mounted to all pipeline containers (steps). For example to use custom CA
|
|
||||||
certificates installed on host and host timezone use `/etc/ssl/certs:/etc/ssl/certs:ro,/etc/timezone:/etc/timezone`.
|
|
||||||
@ -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/v2/pipeline/backend/types".Backend` and
|
|
||||||
build a custom agent using your backend with this `main.go`:
|
|
||||||
|
|
||||||
```go
|
|
||||||
package main
|
|
||||||
|
|
||||||
import (
|
|
||||||
"go.woodpecker-ci.org/woodpecker/v2/cmd/agent/core"
|
|
||||||
backendTypes "go.woodpecker-ci.org/woodpecker/v2/pipeline/backend/types"
|
|
||||||
)
|
|
||||||
|
|
||||||
func main() {
|
|
||||||
core.RunAgent([]backendTypes.Backend{
|
|
||||||
yourBackend,
|
|
||||||
})
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
It is also possible to use multiple backends, you can select with [`WOODPECKER_BACKEND`](../15-agent-config.md#woodpecker_backend) between them.
|
|
||||||
@ -1,199 +0,0 @@
|
|||||||
# Proxy
|
|
||||||
|
|
||||||
## Apache
|
|
||||||
|
|
||||||
This guide provides a brief overview for installing Woodpecker server behind the Apache2 web-server. This is an example configuration:
|
|
||||||
|
|
||||||
```apacheconf
|
|
||||||
ProxyPreserveHost On
|
|
||||||
|
|
||||||
RequestHeader set X-Forwarded-Proto "https"
|
|
||||||
|
|
||||||
ProxyPass / http://127.0.0.1:8000/
|
|
||||||
ProxyPassReverse / http://127.0.0.1:8000/
|
|
||||||
```
|
|
||||||
|
|
||||||
You must have these Apache modules installed:
|
|
||||||
|
|
||||||
- `proxy`
|
|
||||||
- `proxy_http`
|
|
||||||
|
|
||||||
You must configure Apache to set `X-Forwarded-Proto` when using https.
|
|
||||||
|
|
||||||
```diff
|
|
||||||
ProxyPreserveHost On
|
|
||||||
|
|
||||||
+RequestHeader set X-Forwarded-Proto "https"
|
|
||||||
|
|
||||||
ProxyPass / http://127.0.0.1:8000/
|
|
||||||
ProxyPassReverse / http://127.0.0.1:8000/
|
|
||||||
```
|
|
||||||
|
|
||||||
## Nginx
|
|
||||||
|
|
||||||
This guide provides a basic overview for installing Woodpecker server behind the Nginx web-server. For more advanced configuration options please consult the official Nginx [documentation](https://docs.nginx.com/nginx/admin-guide).
|
|
||||||
|
|
||||||
Example configuration:
|
|
||||||
|
|
||||||
```nginx
|
|
||||||
server {
|
|
||||||
listen 80;
|
|
||||||
server_name woodpecker.example.com;
|
|
||||||
|
|
||||||
location / {
|
|
||||||
proxy_set_header X-Forwarded-For $remote_addr;
|
|
||||||
proxy_set_header X-Forwarded-Proto $scheme;
|
|
||||||
proxy_set_header Host $http_host;
|
|
||||||
|
|
||||||
proxy_pass http://127.0.0.1:8000;
|
|
||||||
proxy_redirect off;
|
|
||||||
proxy_http_version 1.1;
|
|
||||||
proxy_buffering off;
|
|
||||||
|
|
||||||
chunked_transfer_encoding off;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
You must configure the proxy to set `X-Forwarded` proxy headers:
|
|
||||||
|
|
||||||
```diff
|
|
||||||
server {
|
|
||||||
listen 80;
|
|
||||||
server_name woodpecker.example.com;
|
|
||||||
|
|
||||||
location / {
|
|
||||||
+ proxy_set_header X-Forwarded-For $remote_addr;
|
|
||||||
+ proxy_set_header X-Forwarded-Proto $scheme;
|
|
||||||
|
|
||||||
proxy_pass http://127.0.0.1:8000;
|
|
||||||
proxy_redirect off;
|
|
||||||
proxy_http_version 1.1;
|
|
||||||
proxy_buffering off;
|
|
||||||
|
|
||||||
chunked_transfer_encoding off;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Caddy
|
|
||||||
|
|
||||||
This guide provides a brief overview for installing Woodpecker server behind the [Caddy web-server](https://caddyserver.com/). This is an example caddyfile proxy configuration:
|
|
||||||
|
|
||||||
```caddy
|
|
||||||
# expose WebUI and API
|
|
||||||
woodpecker.example.com {
|
|
||||||
reverse_proxy woodpecker-server:8000
|
|
||||||
}
|
|
||||||
|
|
||||||
# expose gRPC
|
|
||||||
woodpeckeragent.example.com {
|
|
||||||
reverse_proxy h2c://woodpecker-server:9000
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
:::note
|
|
||||||
Above configuration shows how to create reverse-proxies for web and agent communication. If your agent uses SSL do not forget to enable [`WOODPECKER_GRPC_SECURE`](../15-agent-config.md#woodpecker_grpc_secure).
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Tunnelmole
|
|
||||||
|
|
||||||
[Tunnelmole](https://github.com/robbie-cahill/tunnelmole-client) is an open source tunneling tool.
|
|
||||||
|
|
||||||
Start by [installing tunnelmole](https://github.com/robbie-cahill/tunnelmole-client#installation).
|
|
||||||
|
|
||||||
After the installation, run the following command to start tunnelmole:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
tmole 8000
|
|
||||||
```
|
|
||||||
|
|
||||||
It will start a tunnel and will give a response like this:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
➜ ~ tmole 8000
|
|
||||||
http://bvdo5f-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:8000
|
|
||||||
https://bvdo5f-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:8000
|
|
||||||
```
|
|
||||||
|
|
||||||
Set `WOODPECKER_HOST` to the Tunnelmole URL (`xxx.tunnelmole.net`) and start the server.
|
|
||||||
|
|
||||||
## Ngrok
|
|
||||||
|
|
||||||
[Ngrok](https://ngrok.com/) is a popular closed source tunnelling tool. After installing ngrok, open a new console and run the following command:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ngrok http 8000
|
|
||||||
```
|
|
||||||
|
|
||||||
Set `WOODPECKER_HOST` to the ngrok URL (usually xxx.ngrok.io) and start the server.
|
|
||||||
|
|
||||||
## Traefik
|
|
||||||
|
|
||||||
To install the Woodpecker server behind a [Traefik](https://traefik.io/) load balancer, you must expose both the `http` and the `gRPC` ports. Here is a comprehensive example, considering you are running Traefik with docker swarm and want to do TLS termination and automatic redirection from http to https.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
version: '3.8'
|
|
||||||
|
|
||||||
services:
|
|
||||||
server:
|
|
||||||
image: woodpeckerci/woodpecker-server:latest
|
|
||||||
environment:
|
|
||||||
- WOODPECKER_OPEN=true
|
|
||||||
- WOODPECKER_ADMIN=your_admin_user
|
|
||||||
# other settings ...
|
|
||||||
|
|
||||||
networks:
|
|
||||||
- dmz # externally defined network, so that traefik can connect to the server
|
|
||||||
volumes:
|
|
||||||
- woodpecker-server-data:/var/lib/woodpecker/
|
|
||||||
|
|
||||||
deploy:
|
|
||||||
labels:
|
|
||||||
- traefik.enable=true
|
|
||||||
|
|
||||||
# web server
|
|
||||||
- traefik.http.services.woodpecker-service.loadbalancer.server.port=8000
|
|
||||||
|
|
||||||
- traefik.http.routers.woodpecker-secure.rule=Host(`cd.yourdomain.com`)
|
|
||||||
- traefik.http.routers.woodpecker-secure.tls=true
|
|
||||||
- traefik.http.routers.woodpecker-secure.tls.certresolver=letsencrypt
|
|
||||||
- traefik.http.routers.woodpecker-secure.entrypoints=websecure
|
|
||||||
- traefik.http.routers.woodpecker-secure.service=woodpecker-service
|
|
||||||
|
|
||||||
- traefik.http.routers.woodpecker.rule=Host(`cd.yourdomain.com`)
|
|
||||||
- traefik.http.routers.woodpecker.entrypoints=web
|
|
||||||
- traefik.http.routers.woodpecker.service=woodpecker-service
|
|
||||||
|
|
||||||
- traefik.http.middlewares.woodpecker-redirect.redirectscheme.scheme=https
|
|
||||||
- traefik.http.middlewares.woodpecker-redirect.redirectscheme.permanent=true
|
|
||||||
- traefik.http.routers.woodpecker.middlewares=woodpecker-redirect@docker
|
|
||||||
|
|
||||||
# gRPC service
|
|
||||||
- traefik.http.services.woodpecker-grpc.loadbalancer.server.port=9000
|
|
||||||
- traefik.http.services.woodpecker-grpc.loadbalancer.server.scheme=h2c
|
|
||||||
|
|
||||||
- traefik.http.routers.woodpecker-grpc-secure.rule=Host(`woodpecker-grpc.yourdomain.com`)
|
|
||||||
- traefik.http.routers.woodpecker-grpc-secure.tls=true
|
|
||||||
- traefik.http.routers.woodpecker-grpc-secure.tls.certresolver=letsencrypt
|
|
||||||
- traefik.http.routers.woodpecker-grpc-secure.entrypoints=websecure
|
|
||||||
- traefik.http.routers.woodpecker-grpc-secure.service=woodpecker-grpc
|
|
||||||
|
|
||||||
- traefik.http.routers.woodpecker-grpc.rule=Host(`woodpecker-grpc.yourdomain.com`)
|
|
||||||
- traefik.http.routers.woodpecker-grpc.entrypoints=web
|
|
||||||
- traefik.http.routers.woodpecker-grpc.service=woodpecker-grpc
|
|
||||||
|
|
||||||
- traefik.http.middlewares.woodpecker-grpc-redirect.redirectscheme.scheme=https
|
|
||||||
- traefik.http.middlewares.woodpecker-grpc-redirect.redirectscheme.permanent=true
|
|
||||||
- traefik.http.routers.woodpecker-grpc.middlewares=woodpecker-grpc-redirect@docker
|
|
||||||
|
|
||||||
volumes:
|
|
||||||
woodpecker-server-data:
|
|
||||||
driver: local
|
|
||||||
|
|
||||||
networks:
|
|
||||||
dmz:
|
|
||||||
external: true
|
|
||||||
```
|
|
||||||
|
|
||||||
You should pass `WOODPECKER_GRPC_SECURE=true` and `WOODPECKER_GRPC_VERIFY=true` to your agent when using this configuration.
|
|
||||||
@ -1,104 +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/draft-cavage-http-signatures) by a private key (ed25519) generated on the first start of the Woodpecker server. You can get the public key for the verification of the http-signature from `http(s)://your-woodpecker-server/api/signature/public-key`.
|
|
||||||
|
|
||||||
A simplistic example configuration service can be found here: [https://github.com/woodpecker-ci/example-config-service](https://github.com/woodpecker-ci/example-config-service)
|
|
||||||
|
|
||||||
:::warning
|
|
||||||
You need to trust the external config service as it is getting secret information about the repository and pipeline and has the ability to change pipeline configs that could run malicious tasks.
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Config
|
|
||||||
|
|
||||||
```ini title="Server"
|
|
||||||
WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig
|
|
||||||
```
|
|
||||||
|
|
||||||
### Example request made by Woodpecker
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"repo": {
|
|
||||||
"id": 100,
|
|
||||||
"uid": "",
|
|
||||||
"user_id": 0,
|
|
||||||
"namespace": "",
|
|
||||||
"name": "woodpecker-testpipe",
|
|
||||||
"slug": "",
|
|
||||||
"scm": "git",
|
|
||||||
"git_http_url": "",
|
|
||||||
"git_ssh_url": "",
|
|
||||||
"link": "",
|
|
||||||
"default_branch": "",
|
|
||||||
"private": true,
|
|
||||||
"visibility": "private",
|
|
||||||
"active": true,
|
|
||||||
"config": "",
|
|
||||||
"trusted": false,
|
|
||||||
"protected": false,
|
|
||||||
"ignore_forks": false,
|
|
||||||
"ignore_pulls": false,
|
|
||||||
"cancel_pulls": false,
|
|
||||||
"timeout": 60,
|
|
||||||
"counter": 0,
|
|
||||||
"synced": 0,
|
|
||||||
"created": 0,
|
|
||||||
"updated": 0,
|
|
||||||
"version": 0
|
|
||||||
},
|
|
||||||
"pipeline": {
|
|
||||||
"author": "myUser",
|
|
||||||
"author_avatar": "https://myforge.com/avatars/d6b3f7787a685fcdf2a44e2c685c7e03",
|
|
||||||
"author_email": "my@email.com",
|
|
||||||
"branch": "main",
|
|
||||||
"changed_files": ["somefilename.txt"],
|
|
||||||
"commit": "2fff90f8d288a4640e90f05049fe30e61a14fd50",
|
|
||||||
"created_at": 0,
|
|
||||||
"deploy_to": "",
|
|
||||||
"enqueued_at": 0,
|
|
||||||
"error": "",
|
|
||||||
"event": "push",
|
|
||||||
"finished_at": 0,
|
|
||||||
"id": 0,
|
|
||||||
"link_url": "https://myforge.com/myUser/woodpecker-testpipe/commit/2fff90f8d288a4640e90f05049fe30e61a14fd50",
|
|
||||||
"message": "test old config\n",
|
|
||||||
"number": 0,
|
|
||||||
"parent": 0,
|
|
||||||
"ref": "refs/heads/main",
|
|
||||||
"refspec": "",
|
|
||||||
"clone_url": "",
|
|
||||||
"reviewed_at": 0,
|
|
||||||
"reviewed_by": "",
|
|
||||||
"sender": "myUser",
|
|
||||||
"signed": false,
|
|
||||||
"started_at": 0,
|
|
||||||
"status": "",
|
|
||||||
"timestamp": 1645962783,
|
|
||||||
"title": "",
|
|
||||||
"updated_at": 0,
|
|
||||||
"verified": false
|
|
||||||
},
|
|
||||||
"configs": [
|
|
||||||
{
|
|
||||||
"name": ".woodpecker.yaml",
|
|
||||||
"data": "steps:\n - name: backend\n image: alpine\n commands:\n - echo \"Hello there from Repo (.woodpecker.yaml)\"\n"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Example response structure
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"configs": [
|
|
||||||
{
|
|
||||||
"name": "central-override",
|
|
||||||
"data": "steps:\n - name: backend\n image: alpine\n commands:\n - echo \"Hello there from ConfigAPI\"\n"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
@ -1,90 +0,0 @@
|
|||||||
# SSL
|
|
||||||
|
|
||||||
Woodpecker supports two ways of enabling SSL communication. You can either use Let's Encrypt to get automated SSL support with
|
|
||||||
renewal or provide your own SSL certificates.
|
|
||||||
|
|
||||||
## Let's Encrypt
|
|
||||||
|
|
||||||
Woodpecker supports automated SSL configuration and updates using Let's Encrypt.
|
|
||||||
|
|
||||||
You can enable Let's Encrypt by making the following modifications to your server configuration:
|
|
||||||
|
|
||||||
```ini
|
|
||||||
WOODPECKER_LETS_ENCRYPT=true
|
|
||||||
WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld
|
|
||||||
```
|
|
||||||
|
|
||||||
Note that Woodpecker uses the hostname from the `WOODPECKER_HOST` environment variable when requesting certificates. For example, if `WOODPECKER_HOST=https://example.com` is set the certificate is requested for `example.com`. To receive emails before certificates expire Let's Encrypt requires an email address. You can set it with `WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld`.
|
|
||||||
|
|
||||||
The SSL certificates are stored in `$HOME/.local/share/certmagic` for binary versions of Woodpecker and in `/var/lib/woodpecker` for the Container versions of it. You can set a custom path by setting `XDG_DATA_HOME` if required.
|
|
||||||
|
|
||||||
> Once enabled you can visit the Woodpecker UI with http and the HTTPS address. HTTP will be redirected to HTTPS.
|
|
||||||
|
|
||||||
### Certificate Cache
|
|
||||||
|
|
||||||
Woodpecker writes the certificates to `/var/lib/woodpecker/certmagic/`.
|
|
||||||
|
|
||||||
### Certificate Updates
|
|
||||||
|
|
||||||
Woodpecker uses the official Go acme library which will handle certificate upgrades. There should be no addition configuration or management required.
|
|
||||||
|
|
||||||
## SSL with own certificates
|
|
||||||
|
|
||||||
Woodpecker supports SSL configuration by mounting certificates into your container.
|
|
||||||
|
|
||||||
```ini
|
|
||||||
WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
|
|
||||||
WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key
|
|
||||||
```
|
|
||||||
|
|
||||||
### Certificate Chain
|
|
||||||
|
|
||||||
The most common problem encountered is providing a certificate file without the intermediate chain.
|
|
||||||
|
|
||||||
> LoadX509KeyPair reads and parses a public/private key pair from a pair of files. The files must contain PEM encoded data. The certificate file may contain intermediate certificates following the leaf certificate to form a certificate chain.
|
|
||||||
|
|
||||||
### Certificate Errors
|
|
||||||
|
|
||||||
SSL support is provided using the [ListenAndServeTLS](https://golang.org/pkg/net/http/#ListenAndServeTLS) function from the Go standard library. If you receive certificate errors or warnings please examine your configuration more closely.
|
|
||||||
|
|
||||||
### Running in containers
|
|
||||||
|
|
||||||
Update your configuration to expose the following ports:
|
|
||||||
|
|
||||||
```diff title="docker-compose.yaml"
|
|
||||||
version: '3'
|
|
||||||
|
|
||||||
services:
|
|
||||||
woodpecker-server:
|
|
||||||
[...]
|
|
||||||
ports:
|
|
||||||
+ - 80:80
|
|
||||||
+ - 443:443
|
|
||||||
- 9000:9000
|
|
||||||
```
|
|
||||||
|
|
||||||
Update your configuration to mount your certificate and key:
|
|
||||||
|
|
||||||
```diff title="docker-compose.yaml"
|
|
||||||
version: '3'
|
|
||||||
|
|
||||||
services:
|
|
||||||
woodpecker-server:
|
|
||||||
[...]
|
|
||||||
volumes:
|
|
||||||
+ - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt
|
|
||||||
+ - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key
|
|
||||||
```
|
|
||||||
|
|
||||||
Update your configuration to provide the paths of your certificate and key:
|
|
||||||
|
|
||||||
```diff title="docker-compose.yaml"
|
|
||||||
version: '3'
|
|
||||||
|
|
||||||
services:
|
|
||||||
woodpecker-server:
|
|
||||||
[...]
|
|
||||||
environment:
|
|
||||||
+ - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
|
|
||||||
+ - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key
|
|
||||||
```
|
|
||||||
@ -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="mkdocs",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3
|
|
||||||
# HELP woodpecker_pipeline_time Build time.
|
|
||||||
# TYPE woodpecker_pipeline_time gauge
|
|
||||||
woodpecker_pipeline_time{branch="main",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 116
|
|
||||||
woodpecker_pipeline_time{branch="mkdocs",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 155
|
|
||||||
# HELP woodpecker_pipeline_total_count Total number of builds.
|
|
||||||
# TYPE woodpecker_pipeline_total_count gauge
|
|
||||||
woodpecker_pipeline_total_count 1025
|
|
||||||
# HELP woodpecker_pending_steps Total number of pending pipeline steps.
|
|
||||||
# TYPE woodpecker_pending_steps gauge
|
|
||||||
woodpecker_pending_steps 0
|
|
||||||
# HELP woodpecker_repo_count Total number of repos.
|
|
||||||
# TYPE woodpecker_repo_count gauge
|
|
||||||
woodpecker_repo_count 9
|
|
||||||
# HELP woodpecker_running_steps Total number of running pipeline steps.
|
|
||||||
# TYPE woodpecker_running_steps gauge
|
|
||||||
woodpecker_running_steps 0
|
|
||||||
# HELP woodpecker_user_count Total number of users.
|
|
||||||
# TYPE woodpecker_user_count gauge
|
|
||||||
woodpecker_user_count 1
|
|
||||||
# HELP woodpecker_waiting_steps Total number of pipeline waiting on deps.
|
|
||||||
# TYPE woodpecker_waiting_steps gauge
|
|
||||||
woodpecker_waiting_steps 0
|
|
||||||
# HELP woodpecker_worker_count Total number of workers.
|
|
||||||
# TYPE woodpecker_worker_count gauge
|
|
||||||
woodpecker_worker_count 4
|
|
||||||
```
|
|
||||||
@ -1,795 +0,0 @@
|
|||||||
# CLI
|
|
||||||
|
|
||||||
# NAME
|
|
||||||
|
|
||||||
woodpecker-cli - command line utility
|
|
||||||
|
|
||||||
# SYNOPSIS
|
|
||||||
|
|
||||||
woodpecker-cli
|
|
||||||
|
|
||||||
```
|
|
||||||
[--config|-c]=[value]
|
|
||||||
[--disable-update-check]
|
|
||||||
[--log-file]=[value]
|
|
||||||
[--log-level]=[value]
|
|
||||||
[--nocolor]
|
|
||||||
[--pretty]
|
|
||||||
[--server|-s]=[value]
|
|
||||||
[--token|-t]=[value]
|
|
||||||
```
|
|
||||||
|
|
||||||
# DESCRIPTION
|
|
||||||
|
|
||||||
Woodpecker command line utility
|
|
||||||
|
|
||||||
**Usage**:
|
|
||||||
|
|
||||||
```
|
|
||||||
woodpecker-cli [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...]
|
|
||||||
```
|
|
||||||
|
|
||||||
# GLOBAL OPTIONS
|
|
||||||
|
|
||||||
**--config, -c**="": path to config file
|
|
||||||
|
|
||||||
**--disable-update-check**: disable update check
|
|
||||||
|
|
||||||
**--log-file**="": Output destination for logs. 'stdout' and 'stderr' can be used as special keywords. (default: stderr)
|
|
||||||
|
|
||||||
**--log-level**="": set logging level (default: info)
|
|
||||||
|
|
||||||
**--nocolor**: disable colored debug output, only has effect if pretty output is set too
|
|
||||||
|
|
||||||
**--pretty**: enable pretty-printed debug output
|
|
||||||
|
|
||||||
**--server, -s**="": server address
|
|
||||||
|
|
||||||
**--token, -t**="": server auth token
|
|
||||||
|
|
||||||
# COMMANDS
|
|
||||||
|
|
||||||
## admin
|
|
||||||
|
|
||||||
administer server settings
|
|
||||||
|
|
||||||
### registry
|
|
||||||
|
|
||||||
manage global registries
|
|
||||||
|
|
||||||
#### add
|
|
||||||
|
|
||||||
adds a registry
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--password**="": registry password
|
|
||||||
|
|
||||||
**--username**="": registry username
|
|
||||||
|
|
||||||
#### rm
|
|
||||||
|
|
||||||
remove a registry
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
#### update
|
|
||||||
|
|
||||||
update a registry
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
|
||||||
|
|
||||||
**--password**="": registry password
|
|
||||||
|
|
||||||
**--username**="": registry username
|
|
||||||
|
|
||||||
#### info
|
|
||||||
|
|
||||||
display registry info
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
#### ls
|
|
||||||
|
|
||||||
list registries
|
|
||||||
|
|
||||||
## org
|
|
||||||
|
|
||||||
manage organizations
|
|
||||||
|
|
||||||
### registry
|
|
||||||
|
|
||||||
manage organization registries
|
|
||||||
|
|
||||||
#### add
|
|
||||||
|
|
||||||
adds a registry
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
|
||||||
|
|
||||||
**--password**="": registry password
|
|
||||||
|
|
||||||
**--username**="": registry username
|
|
||||||
|
|
||||||
#### rm
|
|
||||||
|
|
||||||
remove a registry
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
|
||||||
|
|
||||||
#### update
|
|
||||||
|
|
||||||
update a registry
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
|
||||||
|
|
||||||
**--password**="": registry password
|
|
||||||
|
|
||||||
**--username**="": registry username
|
|
||||||
|
|
||||||
#### info
|
|
||||||
|
|
||||||
display registry info
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
|
||||||
|
|
||||||
#### ls
|
|
||||||
|
|
||||||
list registries
|
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
|
||||||
|
|
||||||
## repo
|
|
||||||
|
|
||||||
manage repositories
|
|
||||||
|
|
||||||
### ls
|
|
||||||
|
|
||||||
list all repos
|
|
||||||
|
|
||||||
**--format**="": format output (default: [33m{{ .FullName }}[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }}))
|
|
||||||
|
|
||||||
**--org**="": filter by organization
|
|
||||||
|
|
||||||
### info
|
|
||||||
|
|
||||||
show repository details
|
|
||||||
|
|
||||||
**--format**="": format output (default: Owner: {{ .Owner }}
|
|
||||||
Repo: {{ .Name }}
|
|
||||||
URL: {{ .ForgeURL }}
|
|
||||||
Config path: {{ .Config }}
|
|
||||||
Visibility: {{ .Visibility }}
|
|
||||||
Private: {{ .IsSCMPrivate }}
|
|
||||||
Trusted: {{ .IsTrusted }}
|
|
||||||
Gated: {{ .IsGated }}
|
|
||||||
Clone url: {{ .Clone }}
|
|
||||||
Allow pull-requests: {{ .AllowPullRequests }}
|
|
||||||
)
|
|
||||||
|
|
||||||
### add
|
|
||||||
|
|
||||||
add a repository
|
|
||||||
|
|
||||||
### update
|
|
||||||
|
|
||||||
update a repository
|
|
||||||
|
|
||||||
**--config**="": repository configuration path (e.g. .woodpecker.yml)
|
|
||||||
|
|
||||||
**--gated**: repository is gated
|
|
||||||
|
|
||||||
**--pipeline-counter**="": repository starting pipeline number (default: 0)
|
|
||||||
|
|
||||||
**--timeout**="": repository timeout (default: 0s)
|
|
||||||
|
|
||||||
**--trusted**: repository is trusted
|
|
||||||
|
|
||||||
**--unsafe**: validate updating the pipeline-counter is unsafe
|
|
||||||
|
|
||||||
**--visibility**="": repository visibility
|
|
||||||
|
|
||||||
### rm
|
|
||||||
|
|
||||||
remove a repository
|
|
||||||
|
|
||||||
### repair
|
|
||||||
|
|
||||||
repair repository webhooks
|
|
||||||
|
|
||||||
### chown
|
|
||||||
|
|
||||||
assume ownership of a repository
|
|
||||||
|
|
||||||
### sync
|
|
||||||
|
|
||||||
synchronize the repository list
|
|
||||||
|
|
||||||
**--format**="": format output (default: [33m{{ .FullName }}[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }}))
|
|
||||||
|
|
||||||
### registry
|
|
||||||
|
|
||||||
manage registries
|
|
||||||
|
|
||||||
#### add
|
|
||||||
|
|
||||||
adds a registry
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--password**="": registry password
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
**--username**="": registry username
|
|
||||||
|
|
||||||
#### rm
|
|
||||||
|
|
||||||
remove a registry
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
#### update
|
|
||||||
|
|
||||||
update a registry
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--password**="": registry password
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
**--username**="": registry username
|
|
||||||
|
|
||||||
#### info
|
|
||||||
|
|
||||||
display registry info
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
#### ls
|
|
||||||
|
|
||||||
list registries
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
## pipeline
|
|
||||||
|
|
||||||
manage pipelines
|
|
||||||
|
|
||||||
### ls
|
|
||||||
|
|
||||||
show pipeline history
|
|
||||||
|
|
||||||
**--branch**="": branch filter
|
|
||||||
|
|
||||||
**--event**="": event filter
|
|
||||||
|
|
||||||
**--limit**="": limit the list size (default: 25)
|
|
||||||
|
|
||||||
**--output**="": output format (default: table)
|
|
||||||
|
|
||||||
**--output-no-headers**: don't print headers
|
|
||||||
|
|
||||||
**--status**="": status filter
|
|
||||||
|
|
||||||
### last
|
|
||||||
|
|
||||||
show latest pipeline details
|
|
||||||
|
|
||||||
**--branch**="": branch name (default: main)
|
|
||||||
|
|
||||||
**--output**="": output format (default: table)
|
|
||||||
|
|
||||||
**--output-no-headers**: don't print headers
|
|
||||||
|
|
||||||
### logs
|
|
||||||
|
|
||||||
show pipeline logs
|
|
||||||
|
|
||||||
### info
|
|
||||||
|
|
||||||
show pipeline details
|
|
||||||
|
|
||||||
**--output**="": output format (default: table)
|
|
||||||
|
|
||||||
**--output-no-headers**: don't print headers
|
|
||||||
|
|
||||||
### stop
|
|
||||||
|
|
||||||
stop a pipeline
|
|
||||||
|
|
||||||
### start
|
|
||||||
|
|
||||||
start a pipeline
|
|
||||||
|
|
||||||
**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value (default: [])
|
|
||||||
|
|
||||||
### approve
|
|
||||||
|
|
||||||
approve a pipeline
|
|
||||||
|
|
||||||
### decline
|
|
||||||
|
|
||||||
decline a pipeline
|
|
||||||
|
|
||||||
### queue
|
|
||||||
|
|
||||||
show pipeline queue
|
|
||||||
|
|
||||||
**--format**="": format output (default: [33m{{ .FullName }} #{{ .Number }} [0m
|
|
||||||
Status: {{ .Status }}
|
|
||||||
Event: {{ .Event }}
|
|
||||||
Commit: {{ .Commit }}
|
|
||||||
Branch: {{ .Branch }}
|
|
||||||
Ref: {{ .Ref }}
|
|
||||||
Author: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}
|
|
||||||
Message: {{ .Message }}
|
|
||||||
)
|
|
||||||
|
|
||||||
### ps
|
|
||||||
|
|
||||||
show pipeline steps
|
|
||||||
|
|
||||||
**--format**="": format output (default: [33m{{ .workflow.Name }} > {{ .step.Name }} (#{{ .step.PID }}):[0m
|
|
||||||
Step: {{ .step.Name }}
|
|
||||||
Started: {{ .step.Started }}
|
|
||||||
Stopped: {{ .step.Stopped }}
|
|
||||||
Type: {{ .step.Type }}
|
|
||||||
State: {{ .step.State }}
|
|
||||||
)
|
|
||||||
|
|
||||||
### create
|
|
||||||
|
|
||||||
create new pipeline
|
|
||||||
|
|
||||||
**--branch**="": branch to create pipeline from
|
|
||||||
|
|
||||||
**--output**="": output format (default: table)
|
|
||||||
|
|
||||||
**--output-no-headers**: don't print headers
|
|
||||||
|
|
||||||
**--var**="": key=value (default: [])
|
|
||||||
|
|
||||||
## log
|
|
||||||
|
|
||||||
manage logs
|
|
||||||
|
|
||||||
### purge
|
|
||||||
|
|
||||||
purge a log
|
|
||||||
|
|
||||||
## deploy
|
|
||||||
|
|
||||||
trigger a pipeline with the 'deployment' event
|
|
||||||
|
|
||||||
**--branch**="": branch filter
|
|
||||||
|
|
||||||
**--event**="": event filter (default: push)
|
|
||||||
|
|
||||||
**--format**="": format output (default: Number: {{ .Number }}
|
|
||||||
Status: {{ .Status }}
|
|
||||||
Commit: {{ .Commit }}
|
|
||||||
Branch: {{ .Branch }}
|
|
||||||
Ref: {{ .Ref }}
|
|
||||||
Message: {{ .Message }}
|
|
||||||
Author: {{ .Author }}
|
|
||||||
Target: {{ .Deploy }}
|
|
||||||
)
|
|
||||||
|
|
||||||
**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value (default: [])
|
|
||||||
|
|
||||||
**--status**="": status filter (default: success)
|
|
||||||
|
|
||||||
## exec
|
|
||||||
|
|
||||||
execute a local pipeline
|
|
||||||
|
|
||||||
**--backend-docker-api-version**="": the version of the API to reach, leave empty for latest.
|
|
||||||
|
|
||||||
**--backend-docker-cert**="": path to load the TLS certificates for connecting to docker server
|
|
||||||
|
|
||||||
**--backend-docker-host**="": path to docker socket or url to the docker server
|
|
||||||
|
|
||||||
**--backend-docker-ipv6**: backend docker enable IPV6
|
|
||||||
|
|
||||||
**--backend-docker-network**="": backend docker network
|
|
||||||
|
|
||||||
**--backend-docker-tls-verify**: enable or disable TLS verification for connecting to docker server
|
|
||||||
|
|
||||||
**--backend-docker-volumes**="": backend docker volumes (comma separated)
|
|
||||||
|
|
||||||
**--backend-engine**="": backend engine to run pipelines on (default: auto-detect)
|
|
||||||
|
|
||||||
**--backend-http-proxy**="": if set, pass the environment variable down as "HTTP_PROXY" to steps
|
|
||||||
|
|
||||||
**--backend-https-proxy**="": if set, pass the environment variable down as "HTTPS_PROXY" to steps
|
|
||||||
|
|
||||||
**--backend-k8s-allow-native-secrets**: whether to allow existing Kubernetes secrets to be referenced from steps
|
|
||||||
|
|
||||||
**--backend-k8s-namespace**="": backend k8s namespace (default: woodpecker)
|
|
||||||
|
|
||||||
**--backend-k8s-pod-annotations**="": backend k8s additional Agent-wide worker pod annotations
|
|
||||||
|
|
||||||
**--backend-k8s-pod-annotations-allow-from-step**: whether to allow using annotations from step's backend options
|
|
||||||
|
|
||||||
**--backend-k8s-pod-image-pull-secret-names**="": backend k8s pull secret names for private registries (default: [regcred])
|
|
||||||
|
|
||||||
**--backend-k8s-pod-labels**="": backend k8s additional Agent-wide worker pod labels
|
|
||||||
|
|
||||||
**--backend-k8s-pod-labels-allow-from-step**: whether to allow using labels from step's backend options
|
|
||||||
|
|
||||||
**--backend-k8s-pod-node-selector**="": backend k8s Agent-wide worker pod node selector
|
|
||||||
|
|
||||||
**--backend-k8s-secctx-nonroot**: `run as non root` Kubernetes security context option
|
|
||||||
|
|
||||||
**--backend-k8s-storage-class**="": backend k8s storage class
|
|
||||||
|
|
||||||
**--backend-k8s-storage-rwx**: backend k8s storage access mode, should ReadWriteMany (RWX) instead of ReadWriteOnce (RWO) be used? (default: true)
|
|
||||||
|
|
||||||
**--backend-k8s-volume-size**="": backend k8s volume size (default 10G) (default: 10G)
|
|
||||||
|
|
||||||
**--backend-local-temp-dir**="": set a different temp dir to clone workflows into (default: /tmp/nix-shell.kGX6ZV)
|
|
||||||
|
|
||||||
**--backend-no-proxy**="": if set, pass the environment variable down as "NO_PROXY" to steps
|
|
||||||
|
|
||||||
**--commit-author-avatar**="":
|
|
||||||
|
|
||||||
**--commit-author-email**="":
|
|
||||||
|
|
||||||
**--commit-author-name**="":
|
|
||||||
|
|
||||||
**--commit-branch**="":
|
|
||||||
|
|
||||||
**--commit-message**="":
|
|
||||||
|
|
||||||
**--commit-ref**="":
|
|
||||||
|
|
||||||
**--commit-refspec**="":
|
|
||||||
|
|
||||||
**--commit-sha**="":
|
|
||||||
|
|
||||||
**--env**="": (default: [])
|
|
||||||
|
|
||||||
**--forge-type**="":
|
|
||||||
|
|
||||||
**--forge-url**="":
|
|
||||||
|
|
||||||
**--local**: run from local directory
|
|
||||||
|
|
||||||
**--netrc-machine**="":
|
|
||||||
|
|
||||||
**--netrc-password**="":
|
|
||||||
|
|
||||||
**--netrc-username**="":
|
|
||||||
|
|
||||||
**--network**="": external networks (default: [])
|
|
||||||
|
|
||||||
**--pipeline-created**="": (default: 0)
|
|
||||||
|
|
||||||
**--pipeline-deploy-task**="":
|
|
||||||
|
|
||||||
**--pipeline-deploy-to**="":
|
|
||||||
|
|
||||||
**--pipeline-event**="": (default: manual)
|
|
||||||
|
|
||||||
**--pipeline-finished**="": (default: 0)
|
|
||||||
|
|
||||||
**--pipeline-number**="": (default: 0)
|
|
||||||
|
|
||||||
**--pipeline-parent**="": (default: 0)
|
|
||||||
|
|
||||||
**--pipeline-started**="": (default: 0)
|
|
||||||
|
|
||||||
**--pipeline-status**="":
|
|
||||||
|
|
||||||
**--pipeline-url**="":
|
|
||||||
|
|
||||||
**--prev-commit-author-avatar**="":
|
|
||||||
|
|
||||||
**--prev-commit-author-email**="":
|
|
||||||
|
|
||||||
**--prev-commit-author-name**="":
|
|
||||||
|
|
||||||
**--prev-commit-branch**="":
|
|
||||||
|
|
||||||
**--prev-commit-message**="":
|
|
||||||
|
|
||||||
**--prev-commit-ref**="":
|
|
||||||
|
|
||||||
**--prev-commit-refspec**="":
|
|
||||||
|
|
||||||
**--prev-commit-sha**="":
|
|
||||||
|
|
||||||
**--prev-pipeline-created**="": (default: 0)
|
|
||||||
|
|
||||||
**--prev-pipeline-event**="":
|
|
||||||
|
|
||||||
**--prev-pipeline-finished**="": (default: 0)
|
|
||||||
|
|
||||||
**--prev-pipeline-number**="": (default: 0)
|
|
||||||
|
|
||||||
**--prev-pipeline-started**="": (default: 0)
|
|
||||||
|
|
||||||
**--prev-pipeline-status**="":
|
|
||||||
|
|
||||||
**--prev-pipeline-url**="":
|
|
||||||
|
|
||||||
**--privileged**="": privileged plugins (default: [plugins/docker plugins/gcr plugins/ecr woodpeckerci/plugin-docker-buildx codeberg.org/woodpecker-plugins/docker-buildx])
|
|
||||||
|
|
||||||
**--repo**="": full repo name
|
|
||||||
|
|
||||||
**--repo-clone-ssh-url**="":
|
|
||||||
|
|
||||||
**--repo-clone-url**="":
|
|
||||||
|
|
||||||
**--repo-path**="": path to local repository
|
|
||||||
|
|
||||||
**--repo-private**="":
|
|
||||||
|
|
||||||
**--repo-remote-id**="":
|
|
||||||
|
|
||||||
**--repo-trusted**:
|
|
||||||
|
|
||||||
**--repo-url**="":
|
|
||||||
|
|
||||||
**--step-name**="": (default: 0)
|
|
||||||
|
|
||||||
**--system-name**="": (default: woodpecker)
|
|
||||||
|
|
||||||
**--system-platform**="":
|
|
||||||
|
|
||||||
**--system-url**="": (default: https://github.com/woodpecker-ci/woodpecker)
|
|
||||||
|
|
||||||
**--timeout**="": pipeline timeout (default: 1h0m0s)
|
|
||||||
|
|
||||||
**--volumes**="": pipeline volumes (default: [])
|
|
||||||
|
|
||||||
**--workflow-name**="": (default: 0)
|
|
||||||
|
|
||||||
**--workflow-number**="": (default: 0)
|
|
||||||
|
|
||||||
**--workspace-base**="": (default: /woodpecker)
|
|
||||||
|
|
||||||
**--workspace-path**="": (default: src)
|
|
||||||
|
|
||||||
## info
|
|
||||||
|
|
||||||
show information about the current user
|
|
||||||
|
|
||||||
## registry
|
|
||||||
|
|
||||||
manage registries
|
|
||||||
|
|
||||||
### add
|
|
||||||
|
|
||||||
adds a registry
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--password**="": registry password
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
**--username**="": registry username
|
|
||||||
|
|
||||||
### rm
|
|
||||||
|
|
||||||
remove a registry
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
### update
|
|
||||||
|
|
||||||
update a registry
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--password**="": registry password
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
**--username**="": registry username
|
|
||||||
|
|
||||||
### info
|
|
||||||
|
|
||||||
display registry info
|
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
### ls
|
|
||||||
|
|
||||||
list registries
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
## secret
|
|
||||||
|
|
||||||
manage secrets
|
|
||||||
|
|
||||||
### add
|
|
||||||
|
|
||||||
adds a secret
|
|
||||||
|
|
||||||
**--event**="": secret limited to these events (default: [])
|
|
||||||
|
|
||||||
**--global**: global secret
|
|
||||||
|
|
||||||
**--image**="": secret limited to these images (default: [])
|
|
||||||
|
|
||||||
**--name**="": secret name
|
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
**--value**="": secret value
|
|
||||||
|
|
||||||
### rm
|
|
||||||
|
|
||||||
remove a secret
|
|
||||||
|
|
||||||
**--global**: global secret
|
|
||||||
|
|
||||||
**--name**="": secret name
|
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
### update
|
|
||||||
|
|
||||||
update a secret
|
|
||||||
|
|
||||||
**--event**="": secret limited to these events (default: [])
|
|
||||||
|
|
||||||
**--global**: global secret
|
|
||||||
|
|
||||||
**--image**="": secret limited to these images (default: [])
|
|
||||||
|
|
||||||
**--name**="": secret name
|
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
**--value**="": secret value
|
|
||||||
|
|
||||||
### info
|
|
||||||
|
|
||||||
display secret info
|
|
||||||
|
|
||||||
**--global**: global secret
|
|
||||||
|
|
||||||
**--name**="": secret name
|
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
### ls
|
|
||||||
|
|
||||||
list secrets
|
|
||||||
|
|
||||||
**--global**: global secret
|
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
## user
|
|
||||||
|
|
||||||
manage users
|
|
||||||
|
|
||||||
### ls
|
|
||||||
|
|
||||||
list all users
|
|
||||||
|
|
||||||
**--format**="": format output (default: {{ .Login }})
|
|
||||||
|
|
||||||
### info
|
|
||||||
|
|
||||||
show user details
|
|
||||||
|
|
||||||
**--format**="": format output (default: User: {{ .Login }}
|
|
||||||
Email: {{ .Email }})
|
|
||||||
|
|
||||||
### add
|
|
||||||
|
|
||||||
adds a user
|
|
||||||
|
|
||||||
### rm
|
|
||||||
|
|
||||||
remove a user
|
|
||||||
|
|
||||||
## lint
|
|
||||||
|
|
||||||
lint a pipeline configuration file
|
|
||||||
|
|
||||||
## log-level
|
|
||||||
|
|
||||||
get the logging level of the server, or set it with [level]
|
|
||||||
|
|
||||||
## cron
|
|
||||||
|
|
||||||
manage cron jobs
|
|
||||||
|
|
||||||
### add
|
|
||||||
|
|
||||||
add a cron job
|
|
||||||
|
|
||||||
**--branch**="": cron branch
|
|
||||||
|
|
||||||
**--name**="": cron name
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
**--schedule**="": cron schedule
|
|
||||||
|
|
||||||
### rm
|
|
||||||
|
|
||||||
remove a cron job
|
|
||||||
|
|
||||||
**--id**="": cron id
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
### update
|
|
||||||
|
|
||||||
update a cron job
|
|
||||||
|
|
||||||
**--branch**="": cron branch
|
|
||||||
|
|
||||||
**--id**="": cron id
|
|
||||||
|
|
||||||
**--name**="": cron name
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
**--schedule**="": cron schedule
|
|
||||||
|
|
||||||
### info
|
|
||||||
|
|
||||||
display info about a cron job
|
|
||||||
|
|
||||||
**--id**="": cron id
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
### ls
|
|
||||||
|
|
||||||
list cron jobs
|
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
|
||||||
|
|
||||||
## setup
|
|
||||||
|
|
||||||
setup the woodpecker-cli for the first time
|
|
||||||
|
|
||||||
**--server**="": The URL of the woodpecker server
|
|
||||||
|
|
||||||
**--token**="": The token to authenticate with the woodpecker server
|
|
||||||
|
|
||||||
## update
|
|
||||||
|
|
||||||
update the woodpecker-cli to the latest version
|
|
||||||
|
|
||||||
**--force**: force update even if the latest version is already installed
|
|
||||||
@ -1,18 +0,0 @@
|
|||||||
# About
|
|
||||||
|
|
||||||
Woodpecker has been originally forked from Drone 0.8 as the Drone CI license was changed after the 0.8 release from Apache 2.0 to a proprietary license. Woodpecker is based on this latest freely available version.
|
|
||||||
|
|
||||||
## History
|
|
||||||
|
|
||||||
Woodpecker was originally forked by [@laszlocph](https://github.com/laszlocph) in 2019.
|
|
||||||
|
|
||||||
A few important time points:
|
|
||||||
|
|
||||||
- [`2fbaa56`](https://github.com/woodpecker-ci/woodpecker/commit/2fbaa56eee0f4be7a3ca4be03dbd00c1bf5d1274) is the first commit of the fork, made on Apr 3, 2019.
|
|
||||||
- The first release [v0.8.91](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.8.91) was published on Apr 6, 2019.
|
|
||||||
- On Aug 27, 2019, the project was renamed to "Woodpecker" ([`630c383`](https://github.com/woodpecker-ci/woodpecker/commit/630c383181b10c4ec375e500c812c4b76b3c52b8)).
|
|
||||||
- The first release under the name "Woodpecker" was published on Sep 9, 2019 ([v0.8.104](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.8.104)).
|
|
||||||
|
|
||||||
## Differences to Drone
|
|
||||||
|
|
||||||
Woodpecker is a community-focused software that still stay free and open source forever, while Drone is managed by [Harness](https://harness.io/) and published under [Polyform Small Business](https://polyformproject.org/licenses/small-business/1.0.0/) license.
|
|
||||||
@ -1,160 +0,0 @@
|
|||||||
# Migrations
|
|
||||||
|
|
||||||
Some versions need some changes to the server configuration or the pipeline configuration files.
|
|
||||||
|
|
||||||
<!--
|
|
||||||
## 3.0.0
|
|
||||||
|
|
||||||
- Update all webhooks by pressing the "Repair all" button in the admin settings as the webhook token claims have changed
|
|
||||||
|
|
||||||
-->
|
|
||||||
|
|
||||||
## `next`
|
|
||||||
|
|
||||||
- Deprecated `steps.[name].group` in favor of `steps.[name].depends_on` (see [workflow syntax](./20-usage/20-workflow-syntax.md#depends_on) to learn how to set dependencies)
|
|
||||||
- Removed `WOODPECKER_ROOT_PATH` and `WOODPECKER_ROOT_URL` config variables. Use `WOODPECKER_HOST` with a path instead
|
|
||||||
- Pipelines without a config file will now be skipped instead of failing
|
|
||||||
- Deprecated `includes` and `excludes` support from **event** filter
|
|
||||||
- Deprecated uppercasing all secret env vars, instead, the value of the `secrets` property is used. [Read more](./20-usage/40-secrets.md#use-secrets-in-commands)
|
|
||||||
- Deprecated alternative names for secrets, use `environment` with `from_secret`
|
|
||||||
- Deprecated slice definition for env vars
|
|
||||||
- Deprecated `environment` filter, use `when.evaluate`
|
|
||||||
- Use `WOODPECKER_EXPERT_FORGE_OAUTH_HOST` instead of `WOODPECKER_DEV_GITEA_OAUTH_URL` or `WOODPECKER_DEV_OAUTH_HOST`
|
|
||||||
- Deprecated `WOODPECKER_WEBHOOK_HOST` in favor of `WOODPECKER_EXPERT_WEBHOOK_HOST`
|
|
||||||
|
|
||||||
## 2.0.0
|
|
||||||
|
|
||||||
- Dropped deprecated `CI_BUILD_*`, `CI_PREV_BUILD_*`, `CI_JOB_*`, `*_LINK`, `CI_SYSTEM_ARCH`, `CI_REPO_REMOTE` built-in environment variables
|
|
||||||
- Deprecated `platform:` filter in favor of `labels:`, [read more](./20-usage/20-workflow-syntax.md#filter-by-platform)
|
|
||||||
- Secrets `event` property was renamed to `events` and `image` to `images` as both are lists. The new property `events` / `images` has to be used in the api. The old properties `event` and `image` were removed.
|
|
||||||
- The secrets `plugin_only` option was removed. Secrets with images are now always only available for plugins using listed by the `images` property. Existing secrets with a list of `images` will now only be available to the listed images if they are used as a plugin.
|
|
||||||
- Removed `build` alias for `pipeline` command in CLI
|
|
||||||
- Removed `ssh` backend. Use an agent directly on the SSH machine using the `local` backend.
|
|
||||||
- Removed `/hook` and `/stream` API paths in favor of `/api/(hook|stream)`. You may need to use the "Repair repository" button in the repo settings or "Repair all" in the admin settings to recreate the forge hook.
|
|
||||||
- Removed `WOODPECKER_DOCS` config variable
|
|
||||||
- Renamed `link` to `url` (including all API fields)
|
|
||||||
- Deprecated `CI_COMMIT_URL` env var, use `CI_PIPELINE_FORGE_URL`
|
|
||||||
|
|
||||||
## 1.0.0
|
|
||||||
|
|
||||||
- The signature used to verify extension calls (like those used for the [config-extension](./30-administration/40-advanced/100-external-configuration-api.md)) done by the Woodpecker server switched from using a shared-secret HMac to an ed25519 key-pair. Read more about it at the [config-extensions](./30-administration/40-advanced/100-external-configuration-api.md) documentation.
|
|
||||||
- Refactored support for old agent filter labels and expressions. Learn how to use the new [filter](./20-usage/20-workflow-syntax.md#labels)
|
|
||||||
- Renamed step environment variable `CI_SYSTEM_ARCH` to `CI_SYSTEM_PLATFORM`. Same applies for the cli exec variable.
|
|
||||||
- Renamed environment variables `CI_BUILD_*` and `CI_PREV_BUILD_*` to `CI_PIPELINE_*` and `CI_PREV_PIPELINE_*`, old ones are still available but deprecated
|
|
||||||
- Renamed environment variables `CI_JOB_*` to `CI_STEP_*`, old ones are still available but deprecated
|
|
||||||
- Renamed environment variable `CI_REPO_REMOTE` to `CI_REPO_CLONE_URL`, old is still available but deprecated
|
|
||||||
- Renamed environment variable `*_LINK` to `*_URL`, old ones are still available but deprecated
|
|
||||||
- Renamed API endpoints for pipelines (`<owner>/<repo>/builds/<buildId>` -> `<owner>/<repo>/pipelines/<pipelineId>`), old ones are still available but deprecated
|
|
||||||
- Updated Prometheus gauge `build_*` to `pipeline_*`
|
|
||||||
- Updated Prometheus gauge `*_job_*` to `*_step_*`
|
|
||||||
- Renamed config env `WOODPECKER_MAX_PROCS` to `WOODPECKER_MAX_WORKFLOWS` (still available as fallback)
|
|
||||||
- The pipelines are now also read from `.yaml` files, the new default order is `.woodpecker/*.yml` and `.woodpecker/*.yaml` (without any prioritization) -> `.woodpecker.yml` -> `.woodpecker.yaml`
|
|
||||||
- Dropped support for [Coding](https://coding.net/), [Gogs](https://gogs.io) and Bitbucket Server (Stash).
|
|
||||||
- `/api/queue/resume` & `/api/queue/pause` endpoint methods were changed from `GET` to `POST`
|
|
||||||
- rename `pipeline:` key in your workflow config to `steps:`
|
|
||||||
- If you want to migrate old logs to the new format, watch the error messages on start. If there are none we are good to go, else you have to plan a migration that can take hours. Set `WOODPECKER_MIGRATIONS_ALLOW_LONG` to true and let it run.
|
|
||||||
- Using `repo-id` in favor of `owner/repo` combination
|
|
||||||
- :warning: The api endpoints `/api/repos/{owner}/{repo}/...` were replaced by new endpoints using the repos id `/api/repos/{repo-id}`
|
|
||||||
- To find the id of a repo use the `/api/repos/lookup/{repo-full-name-with-slashes}` endpoint.
|
|
||||||
- The existing badge endpoint `/api/badges/{owner}/{repo}` will still work, but whenever possible try to use the new endpoint using the `repo-id`: `/api/badges/{repo-id}`.
|
|
||||||
- The UI urls for a repository changed from `/repos/{owner}/{repo}/...` to `/repos/{repo-id}/...`. You will be redirected automatically when using the old url.
|
|
||||||
- The woodpecker-go api-client is now using the `repo-id` instead of `owner/repo` for all functions
|
|
||||||
- Using `org-id` in favour of `owner` name
|
|
||||||
- :warning: The api endpoints `/api/orgs/{owner}/...` were replaced by new endpoints using the orgs id `/api/repos/{org-id}`
|
|
||||||
- To find the id of orgs use the `/api/orgs/lookup/{org_full_name}` endpoint.
|
|
||||||
- The UI urls for a organization changed from `/org/{owner}/...` to `/orgs/{org-id}/...`. You will be redirected automatically when using the old url.
|
|
||||||
- The woodpecker-go api-client is now using the `org-id` instead of `org name` for all functions
|
|
||||||
- The `command:` field has been removed from steps. If you were using it, please check if the entrypoint of the image you used is a shell.
|
|
||||||
- If it is a shell, simply rename `command:` to `commands:`.
|
|
||||||
- If it's not, you need to prepend the entrypoint before and also rename it (e.g., `commands: <entrypoint> <cmd>`).
|
|
||||||
|
|
||||||
## 0.15.0
|
|
||||||
|
|
||||||
- Default value for custom pipeline path is now empty / un-set which results in following resolution:
|
|
||||||
|
|
||||||
`.woodpecker/*.yml` -> `.woodpecker.yml` -> `.drone.yml`
|
|
||||||
|
|
||||||
Only projects created after updating will have an empty value by default. Existing projects will stick to the current pipeline path which is `.drone.yml` in most cases.
|
|
||||||
|
|
||||||
Read more about it at the [Project Settings](./20-usage/75-project-settings.md#pipeline-path)
|
|
||||||
|
|
||||||
- From version `0.15.0` ongoing there will be three types of docker images: `latest`, `next` and `x.x.x` with an alpine variant for each type like `latest-alpine`.
|
|
||||||
If you used `latest` before to try pre-release features you should switch to `next` after this release.
|
|
||||||
|
|
||||||
- Dropped support for `DRONE_*` environment variables. The according `WOODPECKER_*` variables must be used instead.
|
|
||||||
Additionally some alternative namings have been removed to simplify maintenance:
|
|
||||||
|
|
||||||
- `WOODPECKER_AGENT_SECRET` replaces `WOODPECKER_SECRET`, `DRONE_SECRET`, `WOODPECKER_PASSWORD`, `DRONE_PASSWORD` and `DRONE_AGENT_SECRET`.
|
|
||||||
- `WOODPECKER_HOST` replaces `DRONE_HOST` and `DRONE_SERVER_HOST`.
|
|
||||||
- `WOODPECKER_DATABASE_DRIVER` replaces `DRONE_DATABASE_DRIVER` and `DATABASE_DRIVER`.
|
|
||||||
- `WOODPECKER_DATABASE_DATASOURCE` replaces `DRONE_DATABASE_DATASOURCE` and `DATABASE_CONFIG`.
|
|
||||||
|
|
||||||
- Dropped support for `DRONE_*` environment variables in pipeline steps. Pipeline meta-data can be accessed with `CI_*` variables.
|
|
||||||
|
|
||||||
- `CI_*` prefix replaces `DRONE_*`
|
|
||||||
- `CI` value is now `woodpecker`
|
|
||||||
- `DRONE=true` has been removed
|
|
||||||
- Some variables got deprecated and will be removed in future versions. Please migrate to the new names. Same applies for `DRONE_` of them.
|
|
||||||
- CI_ARCH => use CI_SYSTEM_ARCH
|
|
||||||
- CI_COMMIT => CI_COMMIT_SHA
|
|
||||||
- CI_TAG => CI_COMMIT_TAG
|
|
||||||
- CI_PULL_REQUEST => CI_COMMIT_PULL_REQUEST
|
|
||||||
- CI_REMOTE_URL => use CI_REPO_REMOTE
|
|
||||||
- CI_REPO_BRANCH => use CI_REPO_DEFAULT_BRANCH
|
|
||||||
- CI_PARENT_BUILD_NUMBER => use CI_BUILD_PARENT
|
|
||||||
- CI_BUILD_TARGET => use CI_BUILD_DEPLOY_TARGET
|
|
||||||
- CI_DEPLOY_TO => use CI_BUILD_DEPLOY_TARGET
|
|
||||||
- CI_COMMIT_AUTHOR_NAME => use CI_COMMIT_AUTHOR
|
|
||||||
- CI_PREV_COMMIT_AUTHOR_NAME => use CI_PREV_COMMIT_AUTHOR
|
|
||||||
- CI_SYSTEM => use CI_SYSTEM_NAME
|
|
||||||
- CI_BRANCH => use CI_COMMIT_BRANCH
|
|
||||||
- CI_SOURCE_BRANCH => use CI_COMMIT_SOURCE_BRANCH
|
|
||||||
- CI_TARGET_BRANCH => use CI_COMMIT_TARGET_BRANCH
|
|
||||||
|
|
||||||
For all available variables and their descriptions have a look at [built-in-environment-variables](./20-usage/50-environment.md#built-in-environment-variables).
|
|
||||||
|
|
||||||
- Prometheus metrics have been changed from `drone_*` to `woodpecker_*`
|
|
||||||
|
|
||||||
- Base path has moved from `/var/lib/drone` to `/var/lib/woodpecker`
|
|
||||||
|
|
||||||
- Default workspace base path has moved from `/drone` to `/woodpecker`
|
|
||||||
|
|
||||||
- Default SQLite database location has changed:
|
|
||||||
|
|
||||||
- `/var/lib/drone/drone.sqlite` -> `/var/lib/woodpecker/woodpecker.sqlite`
|
|
||||||
- `drone.sqlite` -> `woodpecker.sqlite`
|
|
||||||
|
|
||||||
- Plugin Settings moved into `settings` section:
|
|
||||||
|
|
||||||
```diff
|
|
||||||
steps:
|
|
||||||
something:
|
|
||||||
image: my/plugin
|
|
||||||
- setting1: foo
|
|
||||||
- setting2: bar
|
|
||||||
+ settings:
|
|
||||||
+ setting1: foo
|
|
||||||
+ setting2: bar
|
|
||||||
```
|
|
||||||
|
|
||||||
- `WOODPECKER_DEBUG` option for server and agent got removed in favor of `WOODPECKER_LOG_LEVEL=debug`
|
|
||||||
|
|
||||||
- Remove unused server flags which can safely be removed from your server config: `WOODPECKER_QUIC`, `WOODPECKER_GITHUB_SCOPE`, `WOODPECKER_GITHUB_GIT_USERNAME`, `WOODPECKER_GITHUB_GIT_PASSWORD`, `WOODPECKER_GITHUB_PRIVATE_MODE`, `WOODPECKER_GITEA_GIT_USERNAME`, `WOODPECKER_GITEA_GIT_PASSWORD`, `WOODPECKER_GITEA_PRIVATE_MODE`, `WOODPECKER_GITLAB_GIT_USERNAME`, `WOODPECKER_GITLAB_GIT_PASSWORD`, `WOODPECKER_GITLAB_PRIVATE_MODE`
|
|
||||||
|
|
||||||
- Dropped support for manually setting the agents platform with `WOODPECKER_PLATFORM`. The platform is now automatically detected.
|
|
||||||
|
|
||||||
- Use `WOODPECKER_STATUS_CONTEXT` instead of the deprecated options `WOODPECKER_GITHUB_CONTEXT` and `WOODPECKER_GITEA_CONTEXT`.
|
|
||||||
|
|
||||||
## 0.14.0
|
|
||||||
|
|
||||||
No breaking changes
|
|
||||||
|
|
||||||
## From Drone
|
|
||||||
|
|
||||||
:::warning
|
|
||||||
Migration from Drone is only possible if you were running Drone <= v0.8.
|
|
||||||
:::
|
|
||||||
|
|
||||||
1. Make sure you are already running Drone v0.8
|
|
||||||
2. Upgrade to Woodpecker v0.14.4, migration will be done during startup
|
|
||||||
3. Upgrade to the latest Woodpecker version. Pay attention to the breaking changes listed above.
|
|
||||||
@ -1,67 +0,0 @@
|
|||||||
# Awesome Woodpecker
|
|
||||||
|
|
||||||
A curated list of awesome things related to Woodpecker CI.
|
|
||||||
|
|
||||||
If you have some missing resources, please feel free to [open a pull-request](https://github.com/woodpecker-ci/woodpecker/edit/main/docs/docs/92-awesome.md) and add them.
|
|
||||||
|
|
||||||
## Official Resources
|
|
||||||
|
|
||||||
- [Woodpecker CI pipeline configs](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) - Complex setup containing different kind of pipelines
|
|
||||||
- [Golang tests](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/test.yaml)
|
|
||||||
- [Typescript, eslint & Vue](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/web.yaml)
|
|
||||||
- [Docusaurus & publishing to GitHub Pages](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docs.yaml)
|
|
||||||
- [Docker container building](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docker.yaml)
|
|
||||||
|
|
||||||
## Projects using Woodpecker
|
|
||||||
|
|
||||||
- [Woodpecker CI](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) itself
|
|
||||||
- [All official plugins](https://github.com/woodpecker-ci?q=plugin&type=all)
|
|
||||||
- [dessalines/thumb-key](https://github.com/dessalines/thumb-key/blob/main/.woodpecker.yml) - Android Jetpack compose linting and building
|
|
||||||
- [Vieter](https://git.rustybever.be/vieter-v/vieter) - Archlinux/Pacman repository server & automated package build system
|
|
||||||
- [Rieter](https://git.rustybever.be/Chewing_Bever/rieter) - Rewrite of the Vieter project in Rust
|
|
||||||
- [Alex](https://git.rustybever.be/Chewing_Bever/alex) - Minecraft server wrapper designed to automate backups & complement Docker installations
|
|
||||||
|
|
||||||
## Tools
|
|
||||||
|
|
||||||
- [Convert Drone CI pipelines to Woodpecker CI](https://codeberg.org/lafriks/woodpecker-pipeline-transform)
|
|
||||||
- [Ansible NAS](https://github.com/davestephens/ansible-nas/) - a homelab Ansible playbook that can set up Woodpecker CI and Gitea
|
|
||||||
- [picus](https://github.com/windsource/picus) - Picus connects to a Woodpecker CI server and creates an agent in the cloud when there are pending workflows.
|
|
||||||
- [Hetzner cloud](https://www.hetzner.com/cloud) based [Woodpecker compatible autoscaler](https://git.ljoonal.xyz/ljoonal/hetzner-ci-autoscaler) - Creates and destroys VPS instances based on the count of pending & running jobs.
|
|
||||||
- [woodpecker-lint](https://git.schmidl.dev/schtobia/woodpecker-lint) - A repository for linting a Woodpecker config file via pre-commit hook
|
|
||||||
- [Grafana Dashboard](https://github.com/Janik-Haag/woodpecker-grafana-dashboard) - A dashboard visualizing information exposed by the Woodpecker prometheus endpoint.
|
|
||||||
- [woodpecker-autoscaler](https://github.com/Lerentis/woodpecker-autoscaler) - Yet another Woodpecker autoscaler currently targeting [Hetzner cloud](https://www.hetzner.com/cloud) that works in parallel to other autoscaler implementations.
|
|
||||||
|
|
||||||
## Configuration Services
|
|
||||||
|
|
||||||
- [Dynamic Pipelines for Nix Flakes](https://github.com/pinpox/woodpecker-flake-pipeliner) - Define pipelines as Nix Flake outputs
|
|
||||||
|
|
||||||
## Pipelines
|
|
||||||
|
|
||||||
- [Collection of pipeline examples](https://codeberg.org/Codeberg-CI/examples)
|
|
||||||
|
|
||||||
## Posts & tutorials
|
|
||||||
|
|
||||||
- [Setup Gitea with Woodpecker CI](https://containers.fan/posts/setup-gitea-with-woodpecker-ci/)
|
|
||||||
- [Step-by-step guide to modern, secure and Open-source CI setup](https://devforth.io/blog/step-by-step-guide-to-modern-secure-ci-setup/)
|
|
||||||
- [Using Woodpecker CI for my static sites](https://jan.wildeboer.net/2022/07/Woodpecker-CI-Jekyll/)
|
|
||||||
- [Woodpecker CI @ Codeberg](https://www.sarkasti.eu/articles/post/woodpecker/)
|
|
||||||
- [Deploy Docker/Compose using Woodpecker CI](https://hinty.io/vverenko/deploy-docker-compose-using-woodpecker-ci/)
|
|
||||||
- [Installing Woodpecker CI in your personal homelab](https://pwa.io/articles/installing-woodpecker-in-your-homelab/)
|
|
||||||
- [Locally Cached Nix CI with Woodpecker](https://blog.kotatsu.dev/posts/2023-04-21-woodpecker-nix-caching/)
|
|
||||||
- [How to run Cypress auto-tests on Woodpecker CI and report results to Slack](https://devforth.io/blog/how-to-run-cypress-auto-tests-on-woodpecker-ci-and-report-results-to-slack/)
|
|
||||||
- [Quest For CICD - WoodpeckerCI](https://omaramin.me/posts/woodpecker/)
|
|
||||||
- [Getting started with Woodpecker CI](https://systeemkabouter.eu/getting-started-with-woodpecker-ci.html)
|
|
||||||
- [Installing gitea and woodpecker using binary packages](https://neelex.com/2023/03/26/Installing-gitea-using-binary-packages/)
|
|
||||||
- [Deploying mdbook to codeberg pages using woodpecker CI](https://www.markpitblado.me/blog/deploying-mdbook-to-codeberg-pages-using-woodpecker-ci/)
|
|
||||||
- [Deploy a Fly app with Woodpecker CI](https://joeroe.io/2024/01/09/deploy-fly-woodpecker-ci.html)
|
|
||||||
- [Ansible - using Woodpecker as an alternative to Semaphore](https://pat-s.me/ansible-using-woodpecker-as-an-alternative-to-semaphore/)
|
|
||||||
|
|
||||||
## Videos
|
|
||||||
|
|
||||||
- [Replace Ansible Semaphore with Woodpecker CI](https://www.youtube.com/watch?v=d610YPvCB0E)
|
|
||||||
- ["unexpected EOF" error when trying to pair Woodpecker CI served through the Caddy with Gitea](https://www.youtube.com/watch?v=n7Hyvt71Np0)
|
|
||||||
- [CICD Environment in Docker Swarm behind Caddy Server - Part 2 Woodpeckerci](https://www.youtube.com/watch?v=rkbw_k7JvS0)
|
|
||||||
|
|
||||||
## Plugins
|
|
||||||
|
|
||||||
We have a separate [index](/plugins) for plugins.
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 209 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 70 KiB |
@ -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.
|
|
||||||
|
Before Width: | Height: | Size: 31 KiB After Width: | Height: | Size: 31 KiB |
|
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 21 KiB |
|
Before Width: | Height: | Size: 40 KiB After Width: | Height: | Size: 40 KiB |
|
Before Width: | Height: | Size: 113 KiB After Width: | Height: | Size: 113 KiB |
|
Before Width: | Height: | Size: 430 KiB After Width: | Height: | Size: 430 KiB |
|
Before Width: | Height: | Size: 353 KiB After Width: | Height: | Size: 353 KiB |
|
Before Width: | Height: | Size: 351 KiB After Width: | Height: | Size: 351 KiB |
|
Before Width: | Height: | Size: 29 KiB After Width: | Height: | Size: 29 KiB |
@ -18,13 +18,13 @@ This was done to prevent accidental major version upgrades.
|
|||||||
|
|
||||||
Images are pushed to DockerHub and Quay.
|
Images are pushed to DockerHub and Quay.
|
||||||
|
|
||||||
[woodpecker-server (DockerHub)](https://hub.docker.com/r/woodpeckerci/woodpecker-server)
|
[woodpecker-server (DockerHub)](https://hub.docker.com/r/docker/woodpeckerci/woodpecker-server)
|
||||||
[woodpecker-server (Quay)](https://quay.io/repository/woodpeckerci/woodpecker-server)
|
[woodpecker-server (Quay)](https://quay.io/repository/woodpeckerci/woodpecker-server)
|
||||||
|
|
||||||
[woodpecker-agent (DockerHub)](https://hub.docker.com/r/woodpeckerci/woodpecker-agent)
|
[woodpecker-agent (DockerHub)](https://hub.docker.com/r/docker/woodpeckerci/woodpecker-agent)
|
||||||
[woodpecker-agent (Quay)](https://quay.io/repository/woodpeckerci/woodpecker-agent)
|
[woodpecker-agent (Quay)](https://quay.io/repository/woodpeckerci/woodpecker-agent)
|
||||||
|
|
||||||
[woodpecker-cli (DockerHub)](https://hub.docker.com/r/woodpeckerci/woodpecker-cli)
|
[woodpecker-cli (DockerHub)](https://hub.docker.com/r/docker/woodpeckerci/woodpecker-cli)
|
||||||
[woodpecker-cli (Quay)](https://quay.io/repository/woodpeckerci/woodpecker-cli)
|
[woodpecker-cli (Quay)](https://quay.io/repository/woodpeckerci/woodpecker-cli)
|
||||||
|
|
||||||
[woodpecker-autoscaler (DockerHub)](https://hub.docker.com/r/woodpeckerci/autoscaler)
|
[woodpecker-autoscaler (DockerHub)](https://hub.docker.com/r/docker/woodpeckerci/autoscaler)
|
||||||
@ -337,6 +337,12 @@ Enable to allow user registration.
|
|||||||
|
|
||||||
Always use authentication to clone repositories even if they are public. Needed if the forge requires to always authenticate as used by many companies.
|
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`
|
### `WOODPECKER_DEFAULT_CANCEL_PREVIOUS_PIPELINE_EVENTS`
|
||||||
|
|
||||||
> Default: `pull_request, push`
|
> Default: `pull_request, push`
|
||||||
@ -33,7 +33,7 @@ To configure the Docker network if the network's name is `forgejo`, configure it
|
|||||||
|
|
||||||
## Registration
|
## Registration
|
||||||
|
|
||||||
Register your application with Forgejo to create your client id and secret. You can find the OAuth applications settings of Forgejo at `https://forgejo.<host>/user/settings/`. It is very important that the authorization callback URL matches your http(s) scheme and hostname exactly with `https://<host>/authorize` as the path.
|
Register your application with Forgejo to create your client id and secret. You can find the OAuth applications settings of Forgejo at `https://forgejo.<host>/user/settings/`. It is very important that authorization callback URL matches your http(s) scheme and hostname exactly with `https://<host>/authorize` as the path.
|
||||||
|
|
||||||
If you run the Woodpecker CI server on the same host as the Forgejo instance, you might also need to allow local connections in Forgejo. Otherwise webhooks will fail. Add the following lines to your Forgejo configuration (usually at `/etc/forgejo/conf/app.ini`).
|
If you run the Woodpecker CI server on the same host as the Forgejo instance, you might also need to allow local connections in Forgejo. Otherwise webhooks will fail. Add the following lines to your Forgejo configuration (usually at `/etc/forgejo/conf/app.ini`).
|
||||||
|
|
||||||
|
Before Width: | Height: | Size: 29 KiB After Width: | Height: | Size: 29 KiB |
|
Before Width: | Height: | Size: 20 KiB After Width: | Height: | Size: 20 KiB |
|
Before Width: | Height: | Size: 129 KiB After Width: | Height: | Size: 129 KiB |
|
Before Width: | Height: | Size: 25 KiB After Width: | Height: | Size: 25 KiB |
@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
If none of our backends fits your usecase, you can write your own.
|
If none of our backends fits your usecase, you can write your own.
|
||||||
|
|
||||||
Therefore, implement the interface `"go.woodpecker-ci.org/woodpecker/woodpecker/v2/pipeline/backend/types".Backend` and
|
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`:
|
build a custom agent using your backend with this `main.go`:
|
||||||
|
|
||||||
```go
|
```go
|
||||||
|
Before Width: | Height: | Size: 5.3 KiB After Width: | Height: | Size: 5.3 KiB |
|
Before Width: | Height: | Size: 4.4 KiB After Width: | Height: | Size: 4.4 KiB |
|
Before Width: | Height: | Size: 25 KiB After Width: | Height: | Size: 25 KiB |
@ -91,10 +91,20 @@ remove a registry
|
|||||||
|
|
||||||
list registries
|
list registries
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Address }} [0m
|
||||||
|
Username: {{ .Username }}
|
||||||
|
Email: {{ .Email }}
|
||||||
|
)
|
||||||
|
|
||||||
#### show
|
#### show
|
||||||
|
|
||||||
show registry information
|
show registry information
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Address }} [0m
|
||||||
|
Username: {{ .Username }}
|
||||||
|
Email: {{ .Email }}
|
||||||
|
)
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
**--hostname**="": registry hostname (default: docker.io)
|
||||||
|
|
||||||
#### update
|
#### update
|
||||||
@ -133,10 +143,28 @@ remove a secret
|
|||||||
|
|
||||||
list secrets
|
list secrets
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Name }} [0m
|
||||||
|
Events: {{ list .Events }}
|
||||||
|
{{- if .Images }}
|
||||||
|
Images: {{ list .Images }}
|
||||||
|
{{- else }}
|
||||||
|
Images: <any>
|
||||||
|
{{- end }}
|
||||||
|
)
|
||||||
|
|
||||||
#### show
|
#### show
|
||||||
|
|
||||||
show secret information
|
show secret information
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Name }} [0m
|
||||||
|
Events: {{ list .Events }}
|
||||||
|
{{- if .Images }}
|
||||||
|
Images: {{ list .Images }}
|
||||||
|
{{- else }}
|
||||||
|
Images: <any>
|
||||||
|
{{- end }}
|
||||||
|
)
|
||||||
|
|
||||||
**--name**="": secret name
|
**--name**="": secret name
|
||||||
|
|
||||||
#### update
|
#### update
|
||||||
@ -378,13 +406,16 @@ execute a local pipeline
|
|||||||
|
|
||||||
show information about the current user
|
show information about the current user
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: User: {{ .Login }}
|
||||||
|
Email: {{ .Email }})
|
||||||
|
|
||||||
## lint
|
## lint
|
||||||
|
|
||||||
lint a pipeline configuration file
|
lint a pipeline configuration file
|
||||||
|
|
||||||
**--plugins-privileged**="": allow plugins to run in privileged mode, if set empty, there is no (default: [])
|
**--plugins-privileged**="": allow plugins to run in privileged mode, if set empty, there is no (default: [])
|
||||||
|
|
||||||
**--plugins-trusted-clone**="": plugins that are trusted to handle Git credentials in cloning steps (default: [docker.io/woodpeckerci/plugin-git:2.6.0 docker.io/woodpeckerci/plugin-git quay.io/woodpeckerci/plugin-git])
|
**--plugins-trusted-clone**="": plugins that are trusted to handle Git credentials in cloning steps (default: [docker.io/woodpeckerci/plugin-git:2.6.2 docker.io/woodpeckerci/plugin-git quay.io/woodpeckerci/plugin-git])
|
||||||
|
|
||||||
**--strict**: treat warnings as errors
|
**--strict**: treat warnings as errors
|
||||||
|
|
||||||
@ -420,12 +451,22 @@ remove a registry
|
|||||||
|
|
||||||
list registries
|
list registries
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Address }} [0m
|
||||||
|
Username: {{ .Username }}
|
||||||
|
Email: {{ .Email }}
|
||||||
|
)
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
||||||
|
|
||||||
#### show
|
#### show
|
||||||
|
|
||||||
show registry information
|
show registry information
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Address }} [0m
|
||||||
|
Username: {{ .Username }}
|
||||||
|
Email: {{ .Email }}
|
||||||
|
)
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
**--hostname**="": registry hostname (default: docker.io)
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
||||||
@ -472,12 +513,30 @@ remove a secret
|
|||||||
|
|
||||||
list secrets
|
list secrets
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Name }} [0m
|
||||||
|
Events: {{ list .Events }}
|
||||||
|
{{- if .Images }}
|
||||||
|
Images: {{ list .Images }}
|
||||||
|
{{- else }}
|
||||||
|
Images: <any>
|
||||||
|
{{- end }}
|
||||||
|
)
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
||||||
|
|
||||||
#### show
|
#### show
|
||||||
|
|
||||||
show secret information
|
show secret information
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Name }} [0m
|
||||||
|
Events: {{ list .Events }}
|
||||||
|
{{- if .Images }}
|
||||||
|
Images: {{ list .Images }}
|
||||||
|
{{- else }}
|
||||||
|
Images: <any>
|
||||||
|
{{- end }}
|
||||||
|
)
|
||||||
|
|
||||||
**--name**="": secret name
|
**--name**="": secret name
|
||||||
|
|
||||||
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
|
||||||
@ -660,6 +719,13 @@ add a cron job
|
|||||||
|
|
||||||
**--branch**="": cron branch
|
**--branch**="": cron branch
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Name }} [0m
|
||||||
|
ID: {{ .ID }}
|
||||||
|
Branch: {{ .Branch }}
|
||||||
|
Schedule: {{ .Schedule }}
|
||||||
|
NextExec: {{ .NextExec }}
|
||||||
|
)
|
||||||
|
|
||||||
**--name**="": cron name
|
**--name**="": cron name
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
||||||
@ -678,12 +744,26 @@ remove a cron job
|
|||||||
|
|
||||||
list cron jobs
|
list cron jobs
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Name }} [0m
|
||||||
|
ID: {{ .ID }}
|
||||||
|
Branch: {{ .Branch }}
|
||||||
|
Schedule: {{ .Schedule }}
|
||||||
|
NextExec: {{ .NextExec }}
|
||||||
|
)
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
||||||
|
|
||||||
#### show
|
#### show
|
||||||
|
|
||||||
show cron job information
|
show cron job information
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Name }} [0m
|
||||||
|
ID: {{ .ID }}
|
||||||
|
Branch: {{ .Branch }}
|
||||||
|
Schedule: {{ .Schedule }}
|
||||||
|
NextExec: {{ .NextExec }}
|
||||||
|
)
|
||||||
|
|
||||||
**--id**="": cron id
|
**--id**="": cron id
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
||||||
@ -694,6 +774,13 @@ update a cron job
|
|||||||
|
|
||||||
**--branch**="": cron branch
|
**--branch**="": cron branch
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Name }} [0m
|
||||||
|
ID: {{ .ID }}
|
||||||
|
Branch: {{ .Branch }}
|
||||||
|
Schedule: {{ .Schedule }}
|
||||||
|
NextExec: {{ .NextExec }}
|
||||||
|
)
|
||||||
|
|
||||||
**--id**="": cron id
|
**--id**="": cron id
|
||||||
|
|
||||||
**--name**="": cron name
|
**--name**="": cron name
|
||||||
@ -708,10 +795,14 @@ list all repos
|
|||||||
|
|
||||||
**--all**: query all repos, including inactive ones
|
**--all**: query all repos, including inactive ones
|
||||||
|
|
||||||
**--format**="": format output (default: [33m{{ .FullName }}[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }}, isActive: {{ .IsActive }}))
|
**--format**="": format output (deprecated)
|
||||||
|
|
||||||
**--org**="": filter by organization
|
**--org**="": filter by organization
|
||||||
|
|
||||||
|
**--output**="": output format (default: table)
|
||||||
|
|
||||||
|
**--output-no-headers**: don't print headers
|
||||||
|
|
||||||
### registry
|
### registry
|
||||||
|
|
||||||
manage registries
|
manage registries
|
||||||
@ -740,12 +831,22 @@ remove a registry
|
|||||||
|
|
||||||
list registries
|
list registries
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Address }} [0m
|
||||||
|
Username: {{ .Username }}
|
||||||
|
Email: {{ .Email }}
|
||||||
|
)
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
||||||
|
|
||||||
#### show
|
#### show
|
||||||
|
|
||||||
show registry information
|
show registry information
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Address }} [0m
|
||||||
|
Username: {{ .Username }}
|
||||||
|
Email: {{ .Email }}
|
||||||
|
)
|
||||||
|
|
||||||
**--hostname**="": registry hostname (default: docker.io)
|
**--hostname**="": registry hostname (default: docker.io)
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
||||||
@ -800,12 +901,30 @@ remove a secret
|
|||||||
|
|
||||||
list secrets
|
list secrets
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Name }} [0m
|
||||||
|
Events: {{ list .Events }}
|
||||||
|
{{- if .Images }}
|
||||||
|
Images: {{ list .Images }}
|
||||||
|
{{- else }}
|
||||||
|
Images: <any>
|
||||||
|
{{- end }}
|
||||||
|
)
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
||||||
|
|
||||||
#### show
|
#### show
|
||||||
|
|
||||||
show secret information
|
show secret information
|
||||||
|
|
||||||
|
**--format**="": format output (deprecated) (default: [33m{{ .Name }} [0m
|
||||||
|
Events: {{ list .Events }}
|
||||||
|
{{- if .Images }}
|
||||||
|
Images: {{ list .Images }}
|
||||||
|
{{- else }}
|
||||||
|
Images: <any>
|
||||||
|
{{- end }}
|
||||||
|
)
|
||||||
|
|
||||||
**--name**="": secret name
|
**--name**="": secret name
|
||||||
|
|
||||||
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
|
||||||
@ -828,18 +947,9 @@ update a secret
|
|||||||
|
|
||||||
show repository information
|
show repository information
|
||||||
|
|
||||||
**--format**="": format output (default: Owner: {{ .Owner }}
|
**--output**="": output format (default: table)
|
||||||
Repo: {{ .Name }}
|
|
||||||
URL: {{ .ForgeURL }}
|
**--output-no-headers**: don't print headers
|
||||||
Config path: {{ .Config }}
|
|
||||||
Visibility: {{ .Visibility }}
|
|
||||||
Private: {{ .IsSCMPrivate }}
|
|
||||||
Trusted: {{ .IsTrusted }}
|
|
||||||
Gated: {{ .IsGated }}
|
|
||||||
Require approval for: {{ .RequireApproval }}
|
|
||||||
Clone url: {{ .Clone }}
|
|
||||||
Allow pull-requests: {{ .AllowPullRequests }}
|
|
||||||
)
|
|
||||||
|
|
||||||
### sync
|
### sync
|
||||||
|
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user