Add docs for v2.7.0 (#3921)

This commit is contained in:
6543 2024-07-18 05:57:03 -07:00 committed by GitHub
parent 1274de2b2d
commit c81a6d67b1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
102 changed files with 1680 additions and 1133 deletions

View file

@ -34,7 +34,7 @@ const config: Config = {
items: [
{
type: 'doc',
docId: 'intro',
docId: 'intro/index',
activeBaseRegex: 'docs/(?!migrations|awesome)',
position: 'left',
label: 'Docs',
@ -104,7 +104,7 @@ const config: Config = {
},
{
label: 'Server setup',
to: '/docs/administration/deployment/overview',
to: '/docs/administration/getting-started',
},
],
},
@ -236,25 +236,25 @@ const config: Config = {
sidebarPath: require.resolve('./sidebars.js'),
editUrl: 'https://github.com/woodpecker-ci/woodpecker/edit/main/docs/',
includeCurrentVersion: true,
lastVersion: '2.6',
lastVersion: '2.7',
onlyIncludeVersions:
process.env.NODE_ENV === 'development' ? ['current', '2.6'] : ['current', '2.6', '2.5', '2.4', '1.0'],
process.env.NODE_ENV === 'development' ? ['current', '2.7'] : ['current', '2.7', '2.6', '2.5', '1.0'],
versions: {
current: {
label: 'Next 🚧',
banner: 'unreleased',
},
'2.7': {
label: '2.7.x',
},
'2.6': {
label: '2.6.x',
label: '2.6.x 💀',
banner: 'unmaintained',
},
'2.5': {
label: '2.5.x 💀',
banner: 'unmaintained',
},
'2.4': {
label: '2.4.x 💀',
banner: 'unmaintained',
},
'1.0': {
label: '1.0.x 💀',
banner: 'unmaintained',

View file

@ -33,6 +33,7 @@ Here you can find documentation for previous versions of Woodpecker.
| | | |
| ------- | ---------- | ------------------------------------------------------------------------------------- |
| 2.6.0 | 2024-07-18 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.6.0/docs/docs/) |
| 2.5.0 | 2024-06-01 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.5.0/docs/docs/) |
| 2.4.1 | 2024-03-20 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.4.1/docs/docs/) |
| 2.4.0 | 2024-03-19 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.4.0/docs/docs/) |

View file

@ -1,89 +0,0 @@
# Welcome to Woodpecker
Woodpecker is a simple yet powerful CI/CD engine with great extensibility. It focuses on executing pipelines inside [containers](https://opencontainers.org/).
If you are already using containers in your daily workflow, you'll for sure love Woodpecker.
![woodpecker](woodpecker.png)
## `.woodpecker.yaml`
- Place your pipeline in a file named `.woodpecker.yaml` in your repository
- Pipeline steps can be named as you like
- Run any command in the commands section
```yaml title=".woodpecker.yaml"
steps:
- name: build
image: debian
commands:
- echo "This is the build step"
- name: a-test-step
image: debian
commands:
- echo "Testing.."
```
### Steps are containers
- Define any container image as context
- either use your own and install the needed tools in a custom image
- or search for available images that are already tailored for your needs in image registries like [Docker Hub](https://hub.docker.com/search?type=image)
- List the commands that should be executed in the container
```diff
steps:
- name: build
- image: debian
+ image: mycompany/image-with-awscli
commands:
- aws help
```
### File changes are incremental
- Woodpecker clones the source code in the beginning
- File changes are persisted throughout individual steps as the same volume is being mounted in all steps
```yaml title=".woodpecker.yaml"
steps:
- name: build
image: debian
commands:
- touch myfile
- name: a-test-step
image: debian
commands:
- cat myfile
```
## Plugins are straightforward
- If you copy the same shell script from project to project
- Pack it into a plugin instead
- And make the yaml declarative
- Plugins are Docker images with your script as an entrypoint
```dockerfile title="Dockerfile"
FROM laszlocloud/kubectl
COPY deploy /usr/local/deploy
ENTRYPOINT ["/usr/local/deploy"]
```
```bash title="deploy"
kubectl apply -f $PLUGIN_TEMPLATE
```
```yaml title=".woodpecker.yaml"
steps:
deploy-to-k8s:
image: laszlocloud/my-k8s-plugin
settings:
template: config/k8s/service.yaml
```
See [plugin docs](./20-usage/51-plugins/10-overview.md).
## Continue reading
- [Create a Woodpecker pipeline for your repository](./20-usage/10-intro.md)
- [Setup your own Woodpecker instance](./30-administration/00-deployment/00-overview.md)

View file

@ -1,72 +0,0 @@
# Getting started
## Repository Activation
To activate your project navigate to your account settings. You will see a list of repositories which can be activated with a simple toggle. When you activate your repository, Woodpecker automatically adds webhooks to your forge (e.g. GitHub, Gitea, ...).
Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your forge will automatically send a webhook to Woodpecker which will in turn trigger the pipeline execution.
![repository list](repo-list.png)
## Required Permissions
The user who enables a repo in Woodpecker must have `Admin` rights on that repo, so that Woodpecker can add the webhook.
:::note
Note that manually creating webhooks yourself is not possible.
This is because webhooks are signed using a per-repository secret key which is not exposed to end users.
:::
## Configuration
To configure your pipeline you must create a `.woodpecker.yaml` file in the root of your repository. The `.woodpecker.yaml` file is used to define your pipeline steps.
:::note
We support most of YAML 1.2, but preserve some behavior from 1.1 for backward compatibility.
Read more at: [https://github.com/go-yaml/yaml](https://github.com/go-yaml/yaml/tree/v3)
:::
Example pipeline configuration:
```yaml
steps:
- name: build
image: golang
commands:
- go get
- go build
- go test
services:
- name: postgres
image: postgres:9.4.5
environment:
- POSTGRES_USER=myapp
```
Example pipeline configuration with multiple, serial steps:
```yaml
steps:
- name: backend
image: golang
commands:
- go get
- go build
- go test
- name: frontend
image: node:6
commands:
- npm install
- npm test
- name: notify
image: plugins/slack
channel: developers
username: woodpecker
```
## Execution
To trigger your first pipeline execution you can push code to your repository, open a pull request, or push a tag. Any of these events triggers a webhook from your forge and execute your pipeline.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 21 KiB

View file

@ -1,90 +0,0 @@
# Deployment
A Woodpecker deployment consists of two parts:
- A server which is the heart of Woodpecker and ships the web interface.
- Next to one server, you can deploy any number of agents which will run the pipelines.
Each agent is able to process one pipeline step by default.
If you have four agents installed and connected to the Woodpecker server, your system will process four workflows in parallel.
:::tip
You can add more agents to increase the number of parallel workflows or set the agent's `WOODPECKER_MAX_WORKFLOWS=1` environment variable to increase the number of parallel workflows for that agent.
:::
## Which version of Woodpecker should I use?
Woodpecker is having two different kinds of releases: **stable** and **next**.
### Stable releases
We release a new version every four weeks and will release the current state of the `main` branch.
If there are security fixes or critical bug fixes, we'll release them directly.
There are no backports or similar.
#### Versioning
We use [Semantic Versioning](https://semver.org/) to be able,
to communicate when admins have to do manual migration steps and when they can just bump versions up.
#### Breaking changes
As of semver guidelines, breaking changes will be released as a major version. We will hold back
breaking changes to not release many majors each containing just a few breaking changes.
Prior to the release of a major version, a release candidate (RC) will be published to allow easy testing,
the actual release will be about a week later.
## Hardware Requirements
Below are minimal resources requirements for Woodpecker components itself:
| Component | Memory | CPU |
| --------- | ------ | --- |
| Server | 200 MB | 1 |
| Agent | 32 MB | 1 |
Note, that those values do not include the operating system or workload (pipelines execution) resources consumption.
In addition you need at least some kind of database which requires additional resources depending on the selected database system.
## Installation
You can install Woodpecker on multiple ways:
- Using [docker-compose](./10-docker-compose.md) with the official [container images](./10-docker-compose.md#docker-images)
- Using [Kubernetes](./20-kubernetes.md) via the Woodpecker Helm chart
- Using binaries, DEBs or RPMs you can download from [latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest)
## Authentication
Authentication is done using OAuth and is delegated to your forge which is configured using environment variables.
See the complete reference for all supported forges [here](../11-forges/10-overview.md).
## Database
By default Woodpecker uses a SQLite database which requires zero installation or configuration. See the [database settings](../30-database.md) page to further configure it or use MySQL or Postgres.
## SSL
Woodpecker supports SSL configuration by using Let's encrypt or by using own certificates. See the [SSL guide](../60-ssl.md). You can also put it behind a [reverse proxy](#behind-a-proxy)
## Metrics
A [Prometheus endpoint](../90-prometheus.md) is exposed.
## Behind a proxy
See the [proxy guide](../70-proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok.
In the case you need to use Woodpecker with a URL path prefix (like: <https://example.org/woodpecker/>), add the root path to [`WOODPECKER_HOST`](../10-server-config.md#woodpecker_host).
## Third-party installation methods
:::info
These installation methods are not officially supported. If you experience issues with them, please open issues in the specific repositories.
:::
- Using [NixOS](./30-nixos.md) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker)
- [Using YunoHost](https://apps.yunohost.org/app/woodpecker)
- [On Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html)

View file

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

View file

@ -1,13 +0,0 @@
# Forges
## Supported features
| Feature | [GitHub](20-github.md) | [Gitea / Forgejo](30-gitea.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: |
| Event: Tag | :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: |
| Event: Release | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: |
| Event: Deploy | :white_check_mark: | :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: |
| [when.path filter](../../20-usage/20-workflow-syntax.md#path) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: |

View file

@ -1,40 +0,0 @@
# Addons
:::warning
Addons are still experimental. Their implementation can change and break at any time.
:::
:::danger
You need to trust the author of the addons you use. Depending on their type, addons can access forge authentication codes, your secrets or other sensitive information.
:::
To adapt Woodpecker to your needs beyond the [configuration](../10-server-config.md), Woodpecker has its own **addon** system, built ontop of [Go's internal plugin system](https://go.dev/pkg/plugin).
Addons can be used for:
- Forges
## Restrictions
Addons are restricted by how Go plugins work. This includes the following restrictions:
- only supported on Linux, FreeBSD, and macOS
- addons must have been built for the correct Woodpecker version. If an addon is not provided specifically for this version, you likely won't be able to use it.
## Usage
To use an addon, download the addon version built for your Woodpecker version. Then, you can add the following to your configuration:
```ini
WOODPECKER_ADDONS=/path/to/your/addon/file.so
```
In case you run Woodpecker as container, you probably want to mount the addon binaries to `/opt/addons/`.
You can list multiple addons, Woodpecker will automatically determine their type. If you specify multiple addons with the same type, only the first one will be used.
Using an addon always overwrites Woodpecker's internal setup. This means, that a forge addon will be used if specified, no matter what's configured for the forges natively supported by Woodpecker.
### Bug reports
If you experience bugs, please check which component has the issue. If it's the addon, **do not raise an issue in the main repository**, but rather use the separate addon repositories. To check which component is responsible for the bug, look at the logs. Logs from addons are marked with a special field `addon` containing their addon file name.

View file

@ -1,97 +0,0 @@
# Creating addons
Addons are written in Go.
## Writing your code
An addon consists of two variables/functions in Go.
1. The `Type` variable. Specifies the type of the addon and must be directly accessed from `shared/addons/types/types.go`.
2. The `Addon` function which is the main point of your addon.
This function takes the `zerolog` logger you should use to log errors, warnings, etc. as argument.
It returns two values:
1. The actual addon. For type reference see [table below](#return-types).
2. An error. If this error is not `nil`, Woodpecker exits.
Directly import Woodpecker's Go package (`go.woodpecker-ci.org/woodpecker/woodpecker/v2`) and use the interfaces and types defined there.
### Return types
| Addon type | Return type |
| ---------- | -------------------------------------------------------------------- |
| `Forge` | `"go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/forge".Forge` |
### Using configurations
If you write a plugin for the server (`Forge` and the services), you can access the server config.
Therefore, use the `"go.woodpecker-ci.org/woodpecker/v2/server".Config` variable.
:::warning
The config is not available when your addon is initialized, i.e., the `Addon` function is called.
Only use the config in the interface methods.
:::
## Compiling
After you write your addon code, compile your addon:
```sh
go build -buildmode plugin
```
The output file is your addon that is now ready to be used.
## Restrictions
Addons must directly depend on Woodpecker's core (`go.woodpecker-ci.org/woodpecker/woodpecker/v2`).
The addon must have been built with **exactly the same code** as the Woodpecker instance you'd like to use it on. This means: If you build your addon with a specific commit from Woodpecker `next`, you can likely only use it with the Woodpecker version compiled from this commit.
Also, if you change something inside Woodpecker without committing, it might fail because you need to recompile your addon with this code first.
In addition to this, addons are only supported on Linux, FreeBSD, and macOS.
:::info
It is recommended to at least support the latest version of Woodpecker.
:::
### Compile for different versions
As long as there are no changes to Woodpecker's interfaces,
or they are backwards-compatible, you can compile the addon for multiple versions
by changing the version of `go.woodpecker-ci.org/woodpecker/woodpecker/v2` using `go get` before compiling.
## Logging
The entrypoint receives a `zerolog.Logger` as input. **Do not use any other logging solution.** This logger follows the configuration of the Woodpecker instance and adds a special field `addon` to the log entries which allows users to find out which component is writing the log messages.
## Example structure
```go
package main
import (
"context"
"net/http"
"github.com/rs/zerolog"
"go.woodpecker-ci.org/woodpecker/v2/server/forge"
forge_types "go.woodpecker-ci.org/woodpecker/v2/server/forge/types"
"go.woodpecker-ci.org/woodpecker/v2/server/model"
addon_types "go.woodpecker-ci.org/woodpecker/v2/shared/addon/types"
)
var Type = addon_types.TypeForge
func Addon(logger zerolog.Logger) (forge.Forge, error) {
logger.Info().Msg("hello world from addon")
return &config{l: logger}, nil
}
type config struct {
l zerolog.Logger
}
// In this case, `config` must implement `forge.Forge`. You must directly use Woodpecker's packages - see imports above.
```

View file

@ -1,595 +0,0 @@
# CLI
# NAME
woodpecker-cli - A new cli application
# 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
## pipeline
manage pipelines
### ls
show pipeline history
**--branch**="": branch filter
**--event**="": event filter
**--format**="": format output (default: "\x1b[33mPipeline #{{ .Number }} \x1b[0m\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nAuthor: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}\nMessage: {{ .Message }}\n")
**--limit**="": limit the list size (default: 25)
**--status**="": status filter
### last
show latest pipeline details
**--branch**="": branch name (default: "main")
**--format**="": format output (default: "Number: {{ .Number }}\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\n")
### logs
show pipeline logs
### info
show pipeline details
**--format**="": format output (default: "Number: {{ .Number }}\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\n")
### stop
stop a pipeline
### start
start a pipeline
**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value
### approve
approve a pipeline
### decline
decline a pipeline
### queue
show pipeline queue
**--format**="": format output (default: "\x1b[33m{{ .FullName }} #{{ .Number }} \x1b[0m\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nAuthor: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}\nMessage: {{ .Message }}\n")
### ps
show pipeline steps
**--format**="": format output (default: "\x1b[33mStep #{{ .PID }} \x1b[0m\nStep: {{ .Name }}\nState: {{ .State }}\n")
### create
create new pipeline
**--branch**="": branch to create pipeline from
**--format**="": format output (default: "\x1b[33mPipeline #{{ .Number }} \x1b[0m\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nAuthor: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}\nMessage: {{ .Message }}\n")
**--var**="": key=value
## log
manage logs
### purge
purge a log
## deploy
deploy code
**--branch**="": branch filter (default: "main")
**--event**="": event filter (default: "push")
**--format**="": format output (default: "Number: {{ .Number }}\nStatus: {{ .Status }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\nTarget: {{ .Deploy }}\n")
**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value
**--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-namespace**="": backend k8s namespace (default: "woodpecker")
**--backend-k8s-pod-annotations**="": backend k8s additional worker pod annotations
**--backend-k8s-pod-image-pull-secret-names**="": backend k8s pull secret names for private registries (default: "regcred")
**--backend-k8s-pod-labels**="": backend k8s additional worker pod labels
**--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")
**--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**="":
**--forge-type**="":
**--forge-url**="":
**--local**: run from local directory
**--netrc-machine**="":
**--netrc-password**="":
**--netrc-username**="":
**--network**="": external networks
**--pipeline-created**="": (default: 0)
**--pipeline-event**="": (default: "manual")
**--pipeline-finished**="": (default: 0)
**--pipeline-number**="": (default: 0)
**--pipeline-parent**="": (default: 0)
**--pipeline-started**="": (default: 0)
**--pipeline-status**="":
**--pipeline-target**="":
**--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
**--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
**--global**: global secret
**--image**="": secret limited to these images
**--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
**--global**: global secret
**--image**="": secret limited to these images
**--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)
## repo
manage repositories
### ls
list all repos
**--format**="": format output (default: "\x1b[33m{{ .FullName }}\x1b[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }})")
**--org**="": filter by organization
### info
show repository details
**--format**="": format output (default: "Owner: {{ .Owner }}\nRepo: {{ .Name }}\nURL: {{ .ForgeURL }}\nConfig path: {{ .Config }}\nVisibility: {{ .Visibility }}\nPrivate: {{ .IsSCMPrivate }}\nTrusted: {{ .IsTrusted }}\nGated: {{ .IsGated }}\nClone url: {{ .Clone }}\nAllow pull-requests: {{ .AllowPullRequests }}\n")
### 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: "\x1b[33m{{ .FullName }}\x1b[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }})")
## user
manage users
### ls
list all users
**--format**="": format output (default: "{{ .Login }}")
### info
show user details
**--format**="": format output (default: "User: {{ .Login }}\nEmail: {{ .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-url**="": 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

View file

@ -0,0 +1,26 @@
# Welcome to Woodpecker
Woodpecker is a CI/CD tool. It is designed to be lightweight, simple to use and fast. Before we dive into the details, let's have a look at some of the basics.
## Have you ever heard of CI/CD or pipelines?
Don't worry if you haven't. We'll guide you through the basics. CI/CD stands for Continuous Integration and Continuous Deployment. It's basically like a conveyor belt that moves your code from development to production doing all kinds of
checks, tests and routines along the way. A typical pipeline might include the following steps:
1. Running tests
2. Building your application
3. Deploying your application
[Have a deeper look into the idea of CI/CD](https://www.redhat.com/en/topics/devops/what-is-ci-cd)
## Do you know containers?
If you are already using containers in your daily workflow, you'll for sure love Woodpecker. If not yet, you'll be amazed how easy it is to get started with [containers](https://opencontainers.org/).
## Already have access to a Woodpecker instace?
Then you might want to jump directly into it and [start creating your first pipelines](../20-usage/10-intro.md).
## Want to start from scratch and deploy your own Woodpecker instance?
Woodpecker is [pretty lightweight](../30-administration/00-getting-started.md#hardware-requirements) and will even run on your Raspberry Pi. You can follow the [deployment guide](../30-administration/00-getting-started.md) to set up your own Woodpecker instance.

View file

@ -0,0 +1,109 @@
# Your first pipeline
Let's get started and create your first pipeline.
## 1. Repository Activation
To activate your repository in Woodpecker navigate to the repository list and `New repository`. You will see a list of repositories from your forge (GitHub, Gitlab, ...) which can be activated with a simple click.
![new repository list](repo-new.png)
To enable a repository in Woodpecker you must have `Admin` rights on that repository, so that Woodpecker can add something
that is called a webhook (Woodpecker needs it to know about actions like pushes, pull requests, tags, etc.).
## 2. Define first workflow
After enabling a repository Woodpecker will listen for changes in your repository. When a change is detected, Woodpecker will check for a pipeline configuration. So let's create a file at `.woodpecker/my-first-workflow.yaml` inside your repository:
```yaml title=".woodpecker/my-first-workflow.yaml"
when:
- event: push
branch: main
steps:
- name: build
image: debian
commands:
- echo "This is the build step"
- echo "binary-data-123" > executable
- name: a-test-step
image: golang:1.16
commands:
- echo "Testing ..."
- ./executable
```
**So what did we do here?**
1. We defined your first workflow file `my-first-workflow.yaml`.
2. This workflow will be executed when a push event happens on the `main` branch,
because we added a filter using the `when` section:
```diff
+ when:
+ - event: push
+ branch: main
...
```
3. We defined two steps: `build` and `a-test-step`
The steps are executed in the order they are defined, so `build` will be executed first and then `a-test-step`.
In the `build` step we use the `debian` image and build a "binary file" called `executable`.
In the `a-test-step` we use the `golang:1.16` image and run the `executable` file to test it.
You can use any image from registries like the [Docker Hub](https://hub.docker.com/search?type=image) you have access to:
```diff
steps:
- name: build
- image: debian
+ image: mycompany/image-with-awscli
commands:
- aws help
```
## 3. Push the file and trigger first pipeline
If you push this file to your repository now, Woodpecker will already execute your first pipeline.
You can check the pipeline execution in the Woodpecker UI by navigating to the `Pipelines` section of your repository.
![pipeline view](./pipeline.png)
As you probably noticed, there is another step in called `clone` which is executed before your steps. This step clones your repository into a folder called `workspace` which is available throughout all steps.
This for example allows the first step to build your application using your source code and as the second step will receive
the same workspace it can use the previously built binary and test it.
## 4. Use a plugin for reusable tasks
Sometimes you have some tasks that you need to do in every project. For example, deploying to Kubernetes or sending a Slack message. Therefore you can use one of the [official and community plugins](/plugins) or simply [create your own](./51-plugins/20-creating-plugins.md).
If you want to get a Slack notification after your pipeline has finished, you can add a Slack plugin to your pipeline:
```yaml
---
- name: notify me on Slack
image: plugins/slack
settings:
channel: developers
username: woodpecker
password:
from_secret: slack_token
when:
status: [success, failure] # This will execute the step on success and failure
```
To configure a plugin you can use the `settings` section.
Sometime you need to provide secrets to the plugin. You can do this by using the `from_secret` key. The secret must be defined in the Woodpecker UI. You can find more information about secrets [here](./40-secrets.md).
Similar to the `when` section at the top of the file which is for the complete workflow, you can use the `when` section for each step to define when a step should be executed.
Learn more about [plugins](./51-plugins/51-overview.md).
As you now have a basic understanding of how to create a pipeline, you can dive deeper into the [workflow syntax](./20-workflow-syntax.md) and [plugins](./51-plugins/51-overview.md).

View file

@ -0,0 +1,37 @@
# Troubleshooting
## How to debug clone issues
(And what to do with an error message like `fatal: could not read Username for 'https://<url>': No such device or address`)
This error can have multiple causes. If you use internal repositories you might have to enable `WOODPECKER_AUTHENTICATE_PUBLIC_REPOS`:
```ini
WOODPECKER_AUTHENTICATE_PUBLIC_REPOS=true
```
If that does not work, try to make sure the container can reach your git server. In order to do that disable git checkout and make the container "hang":
```yaml
skip_clone: true
steps:
build:
image: debian:stable-backports
commands:
- apt update
- apt install -y inetutils-ping wget
- ping -c 4 git.example.com
- wget git.example.com
- sleep 9999999
```
Get the container id using `docker ps` and copy the id from the first column. Enter the container with: `docker exec -it 1234asdf bash` (replace `1234asdf` with the docker id). Then try to clone the git repository with the commands from the failing pipeline:
```bash
git init
git remote add origin https://git.example.com/username/repo.git
git fetch --no-tags origin +refs/heads/branch:
```
(replace the url AND the branch with the correct values, use your username and password as log in values)

View file

@ -1,13 +1,5 @@
# Terminology
## Woodpecker architecture
![Woodpecker architecture](architecture.svg)
## Pipeline, workflow & step
![Relation between pipelines, workflows and steps](pipeline-workflow-step.svg)
## Glossary
- **Woodpecker CI**: The project name around Woodpecker.
@ -31,7 +23,15 @@
- **YAML File**: A file format used to define and configure [workflows][Workflow].
- **Dependency**: [Workflows][Workflow] can depend on each other, and if possible, they are executed in parallel.
- **Status**: Status refers to the outcome of a step or [workflow][Workflow] after it has been executed, determined by the internal command exit code. At the end of a [workflow][Workflow], its status is sent to the [forge][Forge].
- **Service extension**: Some parts of woodpecker internal services like secrets storage or config fetcher can be replaced through service extensions.
- **Service extension**: Some parts of Woodpecker internal services like secrets storage or config fetcher can be replaced through service extensions.
## Woodpecker architecture
![Woodpecker architecture](architecture.svg)
## Pipeline, workflow & step
![Relation between pipelines, workflows and steps](pipeline-workflow-step.svg)
## Pipeline events
@ -50,13 +50,14 @@ Sometimes there are multiple terms that can be used to describe something. This
- Environment variables `*_LINK` should be called `*_URL`. In the code use `URL()` instead of `Link()`
- Use the term **pipelines** instead of the previous **builds**
- Use the term **steps** instead of the previous **jobs**
- Use the prefix `WOODPECKER_EXPERT_` for advanced environment variables that are normally not required to be set by users
<!-- References -->
[Pipeline]: ../20-workflow-syntax.md
[Workflow]: ../25-workflows.md
[Forge]: ../../30-administration/11-forges/10-overview.md
[Plugin]: ../51-plugins/10-overview.md
[Forge]: ../../30-administration/11-forges/11-overview.md
[Plugin]: ../51-plugins/51-overview.md
[Workspace]: ../20-workflow-syntax.md#workspace
[Matrix]: ../30-matrix-workflows.md
[Docker]: ../../30-administration/22-backends/10-docker.md

View file

@ -1,6 +1,15 @@
# Workflow syntax
The workflow section defines a list of steps to build, test and deploy your code. Steps are executed serially, in the order in which they are defined. If a step returns a non-zero exit code, the workflow and therefore all other workflows and the pipeline immediately aborts and returns a failure status.
The Workflow section defines a list of steps to build, test and deploy your code. The steps are executed serially in the order in which they are defined. If a step returns a non-zero exit code, the workflow and therefore the entire pipeline terminates immediately and returns an error status.
:::note
An exception to this rule are steps with a [`status: [failure]`](#status) condition, which ensures that they are executed in the case of a failed run.
:::
:::note
We support most of YAML 1.2, but preserve some behavior from 1.1 for backward compatibility.
Read more at: [https://github.com/go-yaml/yaml](https://github.com/go-yaml/yaml/tree/v3)
:::
Example steps:
@ -161,6 +170,9 @@ Only build steps can define commands. You cannot use commands with plugins or se
Allows you to specify the entrypoint for containers. Note that this must be a list of the command and its arguments (e.g. `["/bin/sh", "-c"]`).
If you define [`commands`](#commands), the default entrypoint will be `["/bin/sh", "-c", "echo $CI_SCRIPT | base64 -d | /bin/sh -e"]`.
You can also use a custom shell with `CI_SCRIPT` (Base64-encoded) if you set `commands`.
### `environment`
Woodpecker provides the ability to pass environment variables to individual steps.
@ -189,7 +201,8 @@ Some of the steps may be allowed to fail without causing the whole workflow and
### `when` - Conditional Execution
Woodpecker supports defining a list of conditions for a step by using a `when` block. If at least one of the conditions in the `when` block evaluate to true the step is executed, otherwise it is skipped. A condition can be a check like:
Woodpecker supports defining a list of conditions for a step by using a `when` block. If at least one of the conditions in the `when` block evaluate to true the step is executed, otherwise it is skipped. A condition is evaluated to true if _all_ subconditions are true.
A condition can be a check like:
```diff
steps:
@ -204,6 +217,11 @@ Woodpecker supports defining a list of conditions for a step by using a `when` b
+ branch: main
```
The `slack` step is executed if one of these conditions is met:
1. The pipeline is executed from a pull request in the repo `test/test`
2. The pipeline is executed from a push to `maiǹ`
#### `repo`
Example conditional execution by repository:
@ -353,20 +371,6 @@ when:
- platform: [linux/*, windows/amd64]
```
<!-- markdownlint-disable no-duplicate-heading -->
#### `environment`
<!-- markdownlint-enable no-duplicate-heading -->
Execute a step for deployment events matching the target deployment environment:
```yaml
when:
- environment: production
- event: deployment
```
#### `matrix`
Execute a step for a single matrix permutation:
@ -403,16 +407,19 @@ when:
You can use [glob patterns](https://github.com/bmatcuk/doublestar#patterns) to match the changed files and specify if the step should run if a file matching that pattern has been changed `include` or if some files have **not** been changed `exclude`.
For pipelines without file changes (empty commits or on events without file changes like `tag`), you can use `on_empty` to set whether this condition should be **true** _(default)_ or **false** in these cases.
```yaml
when:
- path:
include: ['.woodpecker/*.yaml', '*.ini']
exclude: ['*.md', 'docs/**']
ignore_message: '[ALL]'
on_empty: true
```
:::info
Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions.
Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions and the `on_empty` setting.
:::
#### `evaluate`
@ -640,7 +647,7 @@ You can manually configure the clone step in your workflow for customization:
```diff
+clone:
+ - name: git
+ git:
+ image: woodpeckerci/plugin-git
steps:
@ -716,7 +723,7 @@ skip_clone: true
## `when` - Global workflow conditions
Woodpecker gives the ability to skip whole workflows (not just steps #when---conditional-execution-1) based on certain conditions by a `when` block. If all conditions in the `when` block evaluate to true the workflow is executed, otherwise it is skipped, but treated as successful and other workflows depending on it will still continue.
Woodpecker gives the ability to skip whole workflows ([not just steps](#when---conditional-execution)) based on certain conditions by a `when` block. If all conditions in the `when` block evaluate to true the workflow is executed, otherwise it is skipped, but treated as successful and other workflows depending on it will still continue.
For more information about the specific filters, take a look at the [step-specific `when` filters](#when---conditional-execution).
@ -752,7 +759,7 @@ Workflows that should run even on failure should set the `runs_on` tag. See [her
Woodpecker gives the ability to configure privileged mode in the YAML. You can use this parameter to launch containers with escalated capabilities.
:::info
Privileged mode is only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./71-project-settings.md#trusted) to enable trusted mode.
Privileged mode is only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./75-project-settings.md#trusted) to enable trusted mode.
:::
```diff

View file

@ -6,7 +6,7 @@ In case there is a single configuration in `.woodpecker.yaml` Woodpecker will cr
By placing the configurations in a folder which is by default named `.woodpecker/` Woodpecker will create a pipeline with multiple workflows each named by the file they are defined in. Only `.yml` and `.yaml` files will be used and files in any subfolders like `.woodpecker/sub-folder/test.yaml` will be ignored.
You can also set some custom path like `.my-ci/pipelines/` instead of `.woodpecker/` in the [project settings](./71-project-settings.md).
You can also set some custom path like `.my-ci/pipelines/` instead of `.woodpecker/` in the [project settings](./75-project-settings.md).
## Benefits of using workflows
@ -18,7 +18,7 @@ You can also set some custom path like `.my-ci/pipelines/` instead of `.woodpeck
:::warning
Please note that files are only shared between steps of the same workflow (see [File changes are incremental](./20-workflow-syntax.md#file-changes-are-incremental)). That means you cannot access artifacts e.g. from the `build` workflow in the `deploy` workflow.
If you still need to pass artifacts between the workflows you need use some storage [plugin](./51-plugins/10-overview.md) (e.g. one which stores files in an Amazon S3 bucket).
If you still need to pass artifacts between the workflows you need use some storage [plugin](./51-plugins/51-overview.md) (e.g. one which stores files in an Amazon S3 bucket).
:::
```bash

View file

@ -19,11 +19,11 @@ To configure cron jobs you need at least push access to the repository.
+ cron: "name of the cron job" # if you only want to execute this step by a specific cron job
```
1. Create a new cron job in the repository settings:
2. Create a new cron job in the repository settings:
![cron settings](./cron-settings.png)
The supported schedule syntax can be found at <https://pkg.go.dev/github.com/robfig/cron?utm_source=godoc#hdr-CRON_Expression_Format>. If you need general understanding of the cron syntax <https://crontab.guru/> is a good place to start and experiment.
The supported schedule syntax can be found at <https://pkg.go.dev/github.com/robfig/cron?utm_source=godoc#hdr-CRON_Expression_Format>. If you need general understanding of the cron syntax <https://it-tools.tech/crontab-generator> is a good place to start and experiment.
Examples: `@every 5m`, `@daily`, `0 30 * * * *` ...

View file

@ -81,10 +81,11 @@ This is the reference list of all environment variables available to your pipeli
| | **Current pipeline** |
| `CI_PIPELINE_NUMBER` | pipeline number |
| `CI_PIPELINE_PARENT` | number of parent pipeline |
| `CI_PIPELINE_EVENT` | pipeline event (see [pipeline events](../20-usage/15-terminiology/index.md#pipeline-events)) |
| `CI_PIPELINE_EVENT` | pipeline event (see [pipeline events](../20-usage/15-terminology/index.md#pipeline-events)) |
| `CI_PIPELINE_URL` | link to the web UI for the pipeline |
| `CI_PIPELINE_FORGE_URL` | link to the forge's web UI for the commit(s) or tag that triggered the pipeline |
| `CI_PIPELINE_DEPLOY_TARGET` | pipeline deploy target for `deployment` events (i.e. production) |
| `CI_PIPELINE_DEPLOY_TASK` | pipeline deploy task for `deployment` events (i.e. migration) |
| `CI_PIPELINE_STATUS` | pipeline status (success, failure) |
| `CI_PIPELINE_CREATED` | pipeline created UNIX timestamp |
| `CI_PIPELINE_STARTED` | pipeline started UNIX timestamp |
@ -114,10 +115,11 @@ This is the reference list of all environment variables available to your pipeli
| | **Previous pipeline** |
| `CI_PREV_PIPELINE_NUMBER` | previous pipeline number |
| `CI_PREV_PIPELINE_PARENT` | previous pipeline number of parent pipeline |
| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (see [pipeline events](../20-usage/15-terminiology/index.md#pipeline-events)) |
| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (see [pipeline events](../20-usage/15-terminology/index.md#pipeline-events)) |
| `CI_PREV_PIPELINE_URL` | previous pipeline link in CI |
| `CI_PREV_PIPELINE_FORGE_URL` | previous pipeline link to event in forge |
| `CI_PREV_PIPELINE_DEPLOY_TARGET` | previous pipeline deploy target for `deployment` events (ie production) |
| `CI_PREV_PIPELINE_DEPLOY_TASK` | previous pipeline deploy task for `deployment` events (ie migration) |
| `CI_PREV_PIPELINE_STATUS` | previous pipeline status (success, failure) |
| `CI_PREV_PIPELINE_CREATED` | previous pipeline created UNIX timestamp |
| `CI_PREV_PIPELINE_STARTED` | previous pipeline started UNIX timestamp |

View file

@ -48,6 +48,23 @@ Secrets should be passed as settings too. Therefore, users should use [`from_sec
For Go, we provide a plugin library you can use to get easy access to internal env vars and your settings. See <https://codeberg.org/woodpecker-plugins/go-plugin>.
## Metadata
In your documentation, you can use a Markdown header to define metadata for your plugin. This data is used by [our plugin index](/plugins).
Supported metadata:
- `name`: The plugin's full name
- `icon`: URL to your plugin's icon
- `description`: A short description of what it's doing
- `author`: Your name
- `tags`: List of keywords (e.g. `[git, clone]` for the clone plugin)
- `containerImage`: name of the container image
- `containerImageUrl`: link to the container image
- `url`: homepage or repository of your plugin
If you want your plugin to be listed in the index, you should add as many fields as possible, but only `name` is required.
## Example plugin
This provides a brief tutorial for creating a Woodpecker webhook plugin, using simple shell scripting, to make HTTP requests during the build pipeline.
@ -118,5 +135,5 @@ docker run --rm \
These should also be built for different OS/architectures.
- Use [built-in env vars](../50-environment.md#built-in-environment-variables) where possible.
- Do not use any configuration except settings (and internal env vars). This means: Don't require using [`environment`](../50-environment.md) and don't require specific secret names.
- Add a `docs.md` file, listing all your settings and plugin metadata ([example](https://codeberg.org/woodpecker-plugins/plugin-docker-buildx/src/branch/main/docs.md)).
- Add your plugin to the [plugin index](/plugins) using your `docs.md` ([the example above in the index](https://woodpecker-ci.org/plugins/Docker%20Buildx)).
- Add a `docs.md` file, listing all your settings and plugin metadata ([example](https://github.com/woodpecker-ci/plugin-git/blob/main/docs.md)).
- Add your plugin to the [plugin index](/plugins) using your `docs.md` ([the example above in the index](https://woodpecker-ci.org/plugins/Git%20Clone)).

View file

@ -4,6 +4,24 @@ Plugins are pipeline steps that perform pre-defined tasks and are configured as
They are automatically pulled from the default container registry the agent's have configured.
```dockerfile title="Dockerfile"
FROM laszlocloud/kubectl
COPY deploy /usr/local/deploy
ENTRYPOINT ["/usr/local/deploy"]
```
```bash title="deploy"
kubectl apply -f $PLUGIN_TEMPLATE
```
```yaml title=".woodpecker.yaml"
steps:
- name: deploy-to-k8s
image: laszlocloud/my-k8s-plugin
settings:
template: config/k8s/service.yaml
```
Example pipeline using the Docker and Slack plugins:
```yaml

View file

@ -3,7 +3,7 @@
Woodpecker gives the ability to define Docker volumes in the YAML. You can use this parameter to mount files or folders on the host machine into your containers.
:::note
Volumes are only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./71-project-settings.md#trusted) to enable trusted mode.
Volumes are only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./75-project-settings.md#trusted) to enable trusted mode.
:::
```diff

View file

@ -0,0 +1,62 @@
# Linter
Woodpecker automatically lints your workflow files for errors, deprecations and bad habits. Errors and warnings are shown in the UI for any pipelines.
![errors and warnings in UI](./linter-warnings-errors.png)
## Running the linter from CLI
You can run the linter also manually from the CLI:
```shell
woodpecker-cli lint <workflow files>
```
## Bad habit warnings
Woodpecker warns you if your configuration contains some bad habits.
### Event filter for all steps
All your items in `when` blocks should have an `event` filter, so no step runs on all events. This is recommended because if new events are added, your steps probably shouldn't run on those as well.
Examples of an **incorrect** config for this rule:
```yaml
when:
- branch: main
- event: tag
```
This will trigger the warning because the first item (`branch: main`) does not filter with an event.
```yaml
steps:
- name: test
when:
branch: main
- name: deploy
when:
event: tag
```
Examples of a **correct** config for this rule:
```yaml
when:
- branch: main
event: push
- event: tag
```
```yaml
steps:
- name: test
when:
event: [tag, push]
- name: deploy
when:
- event: tag
```

View file

@ -16,6 +16,15 @@ Your Version-Control-System will notify Woodpecker about events via webhooks. If
Enables handling webhook's pull request event. If disabled, then pipeline won't run for pull requests.
## Allow deployments
Enables a pipeline to be started with the `deploy` event from a successful pipeline.
:::danger
Only activate this option if you trust all users who have push access to your repository.
Otherwise, these users will be able to steal secrets that are only available for `deploy` events.
:::
## Protected
Every pipeline initiated by an webhook event needs to be approved by a project members with push permissions before being executed.

View file

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 40 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 113 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 430 KiB

View file

Before

Width:  |  Height:  |  Size: 165 KiB

After

Width:  |  Height:  |  Size: 165 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 351 KiB

View file

@ -0,0 +1,59 @@
# Gettings 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 conntect 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.

View file

@ -67,7 +67,7 @@ They can be configured with `*_ADDR` variables:
+ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR}
```
Reverse proxying can also be [configured for gRPC](../70-proxy.md#caddy). If the agents are connecting over the internet, it should also be SSL encrypted. The agent then needs to be configured to be secure:
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'

View file

@ -0,0 +1,12 @@
# 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)

View file

@ -1,7 +1,7 @@
# NixOS
:::info
Note that this module is not maintained by the woodpecker-developers.
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.
:::
@ -85,4 +85,4 @@ All configuration options can be found via [NixOS Search](https://search.nixos.o
## 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
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.

View file

@ -0,0 +1,3 @@
label: 'Deployment methods'
collapsible: true
collapsed: true

View file

@ -6,7 +6,7 @@ toc_max_heading_level: 2
## User registration
Woodpecker does not have its own user registry; users are provided from your [forge](./11-forges/10-overview.md) (using OAuth2).
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.
@ -69,7 +69,7 @@ To handle sensitive data in docker-compose or docker-swarm configurations there
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.
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'
@ -473,12 +473,6 @@ Supported variables:
- `owner`: the repo's owner
- `repo`: the repo's name
### `WOODPECKER_ADDONS`
> Default: empty
List of addon files. See [addons](./75-addons/00-overview.md).
---
### `WOODPECKER_LIMIT_MEM_SWAP`
@ -523,7 +517,7 @@ Example: `WOODPECKER_LIMIT_CPU_SET=1,2`
> Default: empty
Specify a configuration service endpoint, see [Configuration Extension](./100-external-configuration-api.md)
Specify a configuration service endpoint, see [Configuration Extension](./40-advanced/100-external-configuration-api.md)
### `WOODPECKER_FORGE_TIMEOUT`
@ -531,6 +525,12 @@ Specify a configuration service endpoint, see [Configuration Extension](./100-ex
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
@ -543,6 +543,18 @@ Enable the Swagger UI for API documentation.
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_...`
@ -559,4 +571,8 @@ See [Bitbucket configuration](./11-forges/50-bitbucket.md#configuration)
### `WOODPECKER_GITLAB_...`
See [Gitlab configuration](./11-forges/40-gitlab.md#configuration)
See [GitLab configuration](./11-forges/40-gitlab.md#configuration)
### `WOODPECKER_ADDON_FORGE`
See [addon forges](./11-forges/100-addon.md).

View file

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

View file

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

View file

@ -81,3 +81,9 @@ Read the value for `WOODPECKER_GITHUB_SECRET` from the specified filepath.
> Default: `false`
Configure if SSL verification should be skipped.
### `WOODPECKER_GITHUB_PUBLIC_ONLY`
> Default: `false`
Configures the GitHub OAuth client to only obtain a token that can manage public repositories.

View file

@ -2,9 +2,9 @@
toc_max_heading_level: 2
---
# Gitea / Forgejo
# Gitea
Woodpecker comes with built-in support for Gitea and the "soft" fork Forgejo. To enable Gitea you should configure the Woodpecker container using the following environment variables:
Woodpecker comes with built-in support for Gitea. To enable Gitea you should configure the Woodpecker container using the following environment variables:
```ini
WOODPECKER_GITEA=true
@ -16,7 +16,7 @@ WOODPECKER_GITEA_SECRET=YOUR_GITEA_CLIENT_SECRET
## Gitea on the same host with containers
If you have Gitea also running on the same host within a container, make sure the agent does have access to it.
The agent tries to clone using the URL which Gitea reports through its API. For simplified connectivity, you should add the woodpecker agent to the same docker network as Gitea is in.
The agent tries to clone using the URL which Gitea reports through its API. For simplified connectivity, you should add the Woodpecker agent to the same docker network as Gitea is in.
Otherwise, the communication should go via the `docker0` gateway (usually 172.17.0.1).
To configure the Docker network if the network's name is `gitea`, configure it like this:
@ -93,3 +93,11 @@ Read the value for `WOODPECKER_GITEA_SECRET` from the specified filepath
> Default: `false`
Configure if SSL verification should be skipped.
## Advanced options
### `WOODPECKER_DEV_GITEA_OAUTH_URL`
> Default: value of `WOODPECKER_GITEA_URL`
Configures the user-facing Gitea server address. Should be used if `WOODPECKER_GITEA_URL` points to an internal URL used for API requests.

View file

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

View file

@ -14,7 +14,7 @@ WOODPECKER_BITBUCKET_SECRET=...
## Registration
You must register an OAuth application at Bitbucket in order to get a key and secret combination for woodpecker. Navigate to your workspace settings and choose `OAuth consumers` from the menu, and finally click `Add Consumer` (the url should be like: `https://bitbucket.org/[your-project-name]/workspace/settings/api`).
You must register an OAuth application at Bitbucket in order to get a key and secret combination for Woodpecker. Navigate to your workspace settings and choose `OAuth consumers` from the menu, and finally click `Add Consumer` (the url should be like: `https://bitbucket.org/[your-project-name]/workspace/settings/api`).
Please set a name and set the `Callback URL` like this:

View file

@ -10,24 +10,23 @@ Woodpecker comes with experimental support for Bitbucket Datacenter / Server, fo
To enable Bitbucket Server you should configure the Woodpecker container using the following environment variables:
```diff
# docker-compose.yml
version: '3'
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_BITBUCKET_DC=true
+ - WOODPECKER_BITBUCKET_DC_GIT_USERNAME=foo
+ - WOODPECKER_BITBUCKET_DC_GIT_PASSWORD=bar
+ - WOODPECKER_BITBUCKET_DC_CLIENT_ID=xxx
+ - WOODPECKER_BITBUCKET_DC_CLIENT_SECRET=yyy
+ - WOODPECKER_BITBUCKET_DC_URL=http://stash.mycompany.com
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_BITBUCKET_DC=true
+ - WOODPECKER_BITBUCKET_DC_GIT_USERNAME=foo
+ - WOODPECKER_BITBUCKET_DC_GIT_PASSWORD=bar
+ - WOODPECKER_BITBUCKET_DC_CLIENT_ID=xxx
+ - WOODPECKER_BITBUCKET_DC_CLIENT_SECRET=yyy
+ - WOODPECKER_BITBUCKET_DC_URL=http://stash.mycompany.com
woodpecker-agent:
[...]
woodpecker-agent:
[...]
```
## Service Account

View file

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

View file

@ -4,19 +4,19 @@ toc_max_heading_level: 2
# Kubernetes backend
The kubernetes backend executes steps inside standalone pods. A temporary PVC is created for the lifetime of the pipeline to transfer files between steps.
The Kubernetes backend executes steps inside standalone Pods. A temporary PVC is created for the lifetime of the pipeline to transfer files between steps.
## Images from private registries
In order to pull private container images defined in your pipeline YAML you must provide [registry credentials in Kubernetes secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).
As the secret is Agent-wide, it has to be placed in namespace defined by `WOODPECKER_BACKEND_K8S_NAMESPACE`.
Besides, you need to provide the secret name to Agent via `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES`.
In order to pull private container images defined in your pipeline YAML you must provide [registry credentials in Kubernetes Secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).
As the Secret is Agent-wide, it has to be placed in namespace defined by `WOODPECKER_BACKEND_K8S_NAMESPACE`.
Besides, you need to provide the Secret name to Agent via `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES`.
## Job specific configuration
### Resources
The kubernetes backend also allows for specifying requests and limits on a per-step basic, most commonly for CPU and memory.
The Kubernetes backend also allows for specifying requests and limits on a per-step basic, most commonly for CPU and memory.
We recommend to add a `resources` definition to all steps to ensure efficient scheduling.
Here is an example definition with an arbitrary `resources` definition below the `backend_options` section:
@ -40,10 +40,15 @@ steps:
You can use [Limit Ranges](https://kubernetes.io/docs/concepts/policy/limit-range/) if you want to set the limits by per-namespace basis.
### Runtime class
`runtimeClassName` specifies the name of the RuntimeClass which will be used to run this Pod. If no `runtimeClassName` is specified, the default RuntimeHandler will be used.
See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/containers/runtime-class/) for more information on specifying runtime classes.
### Service account
`serviceAccountName` specifies the name of the ServiceAccount which the pod will mount. This service account must be created externally.
See the [kubernetes documentation](https://kubernetes.io/docs/concepts/security/service-accounts/) for more information on using service accounts.
`serviceAccountName` specifies the name of the ServiceAccount which the Pod will mount. This service account must be created externally.
See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/security/service-accounts/) for more information on using service accounts.
### Node selector
@ -74,12 +79,13 @@ And then overwrite the `nodeSelector` in the `backend_options` section of the st
kubernetes.io/arch: "${ARCH}"
```
You can use [PodNodeSelector](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#podnodeselector) admission controller if you want to set the node selector by per-namespace basis.
You can use [WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR](#woodpecker_backend_k8s_pod_node_selector) if you want to set the node selector per Agent
or [PodNodeSelector](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#podnodeselector) admission controller if you want to set the node selector by per-namespace basis.
### Tolerations
When you use `nodeSelector` and the node pool is configured with Taints, you need to specify the Tolerations. Tolerations allow the scheduler to schedule pods with matching taints.
See the [kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for more information on using tolerations.
When you use `nodeSelector` and the node pool is configured with Taints, you need to specify the Tolerations. Tolerations allow the scheduler to schedule Pods with matching taints.
See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for more information on using tolerations.
Example pipeline configuration:
@ -112,7 +118,7 @@ steps:
### Volumes
To mount volumes a persistent volume (PV) and persistent volume claim (PVC) are needed on the cluster which can be referenced in steps via the `volumes` option.
To mount volumes a PersistentVolume (PV) and PersistentVolumeClaim (PVC) are needed on the cluster which can be referenced in steps via the `volumes` option.
Assuming a PVC named `woodpecker-cache` exists, it can be referenced as follows in a step:
```yaml
@ -129,7 +135,7 @@ steps:
### Security context
Use the following configuration to set the [Security Context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for the pod/container running a given pipeline step:
Use the following configuration to set the [Security Context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for the Pod/container running a given pipeline step:
```yaml
steps:
@ -146,9 +152,9 @@ steps:
[...]
```
Note that the `backend_options.kubernetes.securityContext` object allows you to set both pod and container level security context options in one object.
By default, the properties will be set at the pod level. Properties that are only supported on the container level will be set there instead. So, the
configuration shown above will result in something like the following pod spec:
Note that the `backend_options.kubernetes.securityContext` object allows you to set both Pod and container level security context options in one object.
By default, the properties will be set at the Pod level. Properties that are only supported on the container level will be set there instead. So, the
configuration shown above will result in something like the following Pod spec:
```yaml
kind: Pod
@ -190,6 +196,24 @@ backend_options:
AppArmor syntax follows [KEP-24](https://github.com/kubernetes/enhancements/blob/fddcbb9cbf3df39ded03bad71228265ac6e5215f/keps/sig-node/24-apparmor/README.md).
:::
### Annotations and labels
You can specify arbitrary [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) and [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to be set on the Pod definition for a given workflow step using the following configuration:
```yaml
backend_options:
kubernetes:
annotations:
workflow-group: alpha
io.kubernetes.cri-o.Devices: /dev/fuse
labels:
environment: ci
app.kubernetes.io/name: builder
```
In order to enable this configuration you need to set the appropriate environment variables to `true` on the woodpecker agent:
[WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS_ALLOW_FROM_STEP](#woodpecker_backend_k8s_pod_annotations_allow_from_step) and/or [WOODPECKER_BACKEND_K8S_POD_LABELS_ALLOW_FROM_STEP](#woodpecker_backend_k8s_pod_labels_allow_from_step).
## Tips and tricks
### CRI-O
@ -204,6 +228,12 @@ workspace:
See [this issue](https://github.com/woodpecker-ci/woodpecker/issues/2510) for more details.
### `KUBERNETES_SERVICE_HOST` environment variable
Like the below env vars used for configuration, this can be set in the environment fonfiguration of the agent. It configures the address of the Kubernetes API server to connect to.
If running the agent within Kubernetes, this will already be set and you don't have to add it manually.
## Configuration
These env vars can be set in the `env:` sections of the agent.
@ -212,7 +242,7 @@ These env vars can be set in the `env:` sections of the agent.
> Default: `woodpecker`
The namespace to create worker pods in.
The namespace to create worker Pods in.
### `WOODPECKER_BACKEND_K8S_VOLUME_SIZE`
@ -236,13 +266,31 @@ Determines if `RWX` should be used for the pipeline volume's [access mode](https
> Default: empty
Additional labels to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-label":"test-value"}`.
Additional labels to apply to worker Pods. Must be a YAML object, e.g. `{"example.com/test-label":"test-value"}`.
### `WOODPECKER_BACKEND_K8S_POD_LABELS_ALLOW_FROM_STEP`
> Default: `false`
Determines if additional Pod labels can be defined from a step's backend options.
### `WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS`
> Default: empty
Additional annotations to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-annotation":"test-value"}`.
Additional annotations to apply to worker Pods. Must be a YAML object, e.g. `{"example.com/test-annotation":"test-value"}`.
### `WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS_ALLOW_FROM_STEP`
> Default: `false`
Determines if Pod annotations can be defined from a step's backend options.
### `WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR`
> Default: empty
Additional node selector to apply to worker pods. Must be a YAML object, e.g. `{"topology.kubernetes.io/region":"eu-central-1"}`.
### `WOODPECKER_BACKEND_K8S_SECCTX_NONROOT`

View file

@ -31,7 +31,7 @@ You must configure Apache to set `X-Forwarded-Proto` when using https.
## 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://www.nginx.com/resources/admin-guide/).
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:
@ -93,7 +93,7 @@ woodpeckeragent.example.com {
```
:::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).
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

View file

@ -0,0 +1,25 @@
# Adavanced 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.

View file

@ -1,6 +1,6 @@
label: 'Addons'
label: 'Advanced'
collapsible: true
collapsed: true
link:
type: 'doc'
id: 'overview'
id: 'advanced'

View file

@ -0,0 +1,792 @@
# 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: {{ .FullName }} (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: {{ .FullName }} (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: {{ .FullName }} #{{ .Number }} 
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: Step #{{ .PID }} 
Step: {{ .Name }}
State: {{ .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

View file

@ -0,0 +1,18 @@
# 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.

View file

@ -2,6 +2,13 @@
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)
@ -11,6 +18,9 @@ Some versions need some changes to the server configuration or the pipeline conf
- 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
@ -27,7 +37,7 @@ Some versions need some changes to the server configuration or the pipeline conf
## 1.0.0
- The signature used to verify extension calls (like those used for the [config-extension](./30-administration/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/100-external-configuration-api.md) documentation.
- 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
@ -66,7 +76,7 @@ Some versions need some changes to the server configuration or the pipeline conf
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/71-project-settings.md#pipeline-path)
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.

View file

@ -1,6 +1,6 @@
# Awesome Woodpecker
A curated list of awesome things related to Woodpecker-CI.
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.
@ -14,7 +14,7 @@ If you have some missing resources, please feel free to [open a pull-request](ht
## Projects using Woodpecker
- [Woodpecker-CI](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) itself
- [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
@ -24,12 +24,12 @@ If you have some missing resources, please feel free to [open a pull-request](ht
## 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
- [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.
- [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
@ -50,8 +50,11 @@ If you have some missing resources, please feel free to [open a pull-request](ht
- [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://blog.lutra-it.eu/getting-started-with-woodpecker-ci.html)
- [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

View file

@ -82,7 +82,7 @@ WOODPECKER_HEALTHCHECK=false
### Setup OAuth
Create an OAuth app for your forge as described in the [forges documentation](../30-administration/11-forges/10-overview.md). If you set `WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000` you can use that address with the path as explained for the specific forge to login without the need for a public address. For example for GitHub you would use `http://localhost:8000/authorize` as authorization callback URL.
Create an OAuth app for your forge as described in the [forges documentation](../30-administration/11-forges/11-overview.md). If you set `WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000` you can use that address with the path as explained for the specific forge to login without the need for a public address. For example for GitHub you would use `http://localhost:8000/authorize` as authorization callback URL.
## Developing with VS Code

View file

@ -8,7 +8,7 @@
## Addons and extensions
If you are wondering whether your contribution will be accepted to be merged in the Woodpecker core, or whether it's better to write an
[addon](../30-administration/75-addons/00-overview.md), [extension](../30-administration/100-external-configuration-api.md) or an
[addon forge](../30-administration/11-forges/100-addon.md), [extension](../30-administration/40-advanced/100-external-configuration-api.md) or an
[external custom backend](../30-administration/22-backends/50-custom-backends.md), please check these points:
- Is your change very specific to your setup and unlikely to be used by anyone else?

View file

@ -36,4 +36,4 @@ The following list contains some tools and frameworks used by the Woodpecker UI.
Woodpecker uses [Vue I18n](https://vue-i18n.intlify.dev/) as translation library. New translations have to be added to `web/src/assets/locales/en.json`. The English source file will be automatically imported into [Weblate](https://translate.woodpecker-ci.org/) (the translation system used by Woodpecker) where all other languages will be translated by the community based on the English source.
You must not provide translations except English in PRs, otherwise weblate could put git into conflicts (when someone has translated in that language file and changes are not into main branch yet)
For more information about translations see [Translations](./07-translations.md).
For more information about translations see [Translations](./08-translations.md).

View file

@ -0,0 +1,7 @@
# Conventions
## Database naming
Database tables are named plural, columns don't have any prefix.
Example: Table name `agent`, columns `id`, `name`.

View file

@ -3,7 +3,6 @@
## ORM
Woodpecker uses [Xorm](https://xorm.io/) as ORM for the database connection.
You can find its documentation at [gobook.io/read/gitea.com/xorm](https://gobook.io/read/gitea.com/xorm/manual-en-US/).
## Add a new migration

View file

@ -0,0 +1,81 @@
# Testing
## Backend
### Unit Tests
[We use default golang unit tests](https://go.dev/doc/tutorial/add-a-test)
with [`"github.com/stretchr/testify/assert"`](https://pkg.go.dev/github.com/stretchr/testify@v1.9.0/assert) to simplify testing.
### Integration Tests
### Dummy backend
There is a special backend called **`dummy`** which does not execute any commands, but emulates how a typical backend should behave.
To enable it you need to build the agent or cli with the `test` build tag.
An example pipeline config would be:
```yaml
when:
event: manual
steps:
- name: echo
image: dummy
commands: echo "hello woodpecker"
environment:
SLEEP: '1s'
services:
echo:
image: dummy
commands: echo "i am a sevice"
```
This could be executed via `woodpecker-cli --log-level trace exec --backend-engine dummy example.yaml`:
```none
9:18PM DBG pipeline/pipeline.go:94 > executing 2 stages, in order of: CLI=exec
9:18PM DBG pipeline/pipeline.go:104 > stage CLI=exec StagePos=0 Steps=echo
9:18PM DBG pipeline/pipeline.go:104 > stage CLI=exec StagePos=1 Steps=echo
9:18PM TRC pipeline/backend/dummy/dummy.go:75 > create workflow environment taskUUID=01J10P578JQE6E25VV1EQF0745
9:18PM DBG pipeline/pipeline.go:176 > prepare CLI=exec step=echo
9:18PM DBG pipeline/pipeline.go:203 > executing CLI=exec step=echo
9:18PM TRC pipeline/backend/dummy/dummy.go:81 > start step echo taskUUID=01J10P578JQE6E25VV1EQF0745
9:18PM TRC pipeline/backend/dummy/dummy.go:167 > tail logs of step echo taskUUID=01J10P578JQE6E25VV1EQF0745
9:18PM DBG pipeline/pipeline.go:209 > complete CLI=exec step=echo
[echo:L0:0s] StepName: echo
[echo:L1:0s] StepType: service
[echo:L2:0s] StepUUID: 01J10P578JQE6E25VV1A2DNQN9
[echo:L3:0s] StepCommands:
[echo:L4:0s] ------------------
[echo:L5:0s] echo ja
[echo:L6:0s] ------------------
[echo:L7:0s] 9:18PM DBG pipeline/pipeline.go:176 > prepare CLI=exec step=echo
9:18PM DBG pipeline/pipeline.go:203 > executing CLI=exec step=echo
9:18PM TRC pipeline/backend/dummy/dummy.go:81 > start step echo taskUUID=01J10P578JQE6E25VV1EQF0745
9:18PM TRC pipeline/backend/dummy/dummy.go:167 > tail logs of step echo taskUUID=01J10P578JQE6E25VV1EQF0745
[echo:L0:0s] StepName: echo
[echo:L1:0s] StepType: commands
[echo:L2:0s] StepUUID: 01J10P578JQE6E25VV1DFSXX1Y
[echo:L3:0s] StepCommands:
[echo:L4:0s] ------------------
[echo:L5:0s] echo ja
[echo:L6:0s] ------------------
[echo:L7:0s] 9:18PM TRC pipeline/backend/dummy/dummy.go:108 > wait for step echo taskUUID=01J10P578JQE6E25VV1EQF0745
9:18PM TRC pipeline/backend/dummy/dummy.go:187 > stop step echo taskUUID=01J10P578JQE6E25VV1EQF0745
9:18PM DBG pipeline/pipeline.go:209 > complete CLI=exec step=echo
9:18PM TRC pipeline/backend/dummy/dummy.go:208 > delete workflow environment taskUUID=01J10P578JQE6E25VV1EQF0745
```
There are also environment variables to alter step behaviour:
- `SLEEP: 10` will let the step wait 10 seconds
- `EXPECT_TYPE` allows to check if a step is a `clone`, `service`, `plugin` or `commands`
- `STEP_START_FAIL: true` if set will simulate a step to fail before actually being started (e.g. happens when the container image can not be pulled)
- `STEP_TAIL_FAIL: true` if set will error when we simulate to read from stdout for logs
- `STEP_EXIT_CODE: 2` if set will be used as exit code, default is 0
- `STEP_OOM_KILLED: true` simulates a step being killed by memory constrains
You can let the setup of a whole workflow fail by setting it's UUID to `WorkflowSetupShouldFail`.

View file

Before

Width:  |  Height:  |  Size: 7.5 KiB

After

Width:  |  Height:  |  Size: 7.5 KiB

View file

Before

Width:  |  Height:  |  Size: 17 KiB

After

Width:  |  Height:  |  Size: 17 KiB

View file

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 209 KiB

View file

Before

Width:  |  Height:  |  Size: 70 KiB

After

Width:  |  Height:  |  Size: 70 KiB

Some files were not shown because too many files have changed in this diff Show more