### Install and Run Docusaurus Docs

Source: https://woodpecker-ci.org/docs/development/docs

Navigate to the docs directory, install dependencies, build necessary plugins, and then start the Docusaurus development server with hot-reloading or build the static documentation.

```bash
cd docs/  


pnpm install  

# build plugins used by the docs  
pnpm build:woodpecker-plugins  

# start docs with hot-reloading, so you can change the docs and directly see the changes in the browser without reloading it manually  
pnpm start  

# or build the docs to deploy it to some static page hosting  
pnpm build  
```

--------------------------------

### Install UI Dependencies

Source: https://woodpecker-ci.org/docs/development/ui

Navigate to the web directory and install all necessary dependencies using pnpm.

```bash
cd web/
pnpm install
```

--------------------------------

### start

Source: https://woodpecker-ci.org/docs/cli

Starts a pipeline, allowing custom parameters to be injected into the step environment.

```APIDOC
## start
start a pipeline
### Parameters
#### Query Parameters
- **--param, -p** (string) - Optional - custom parameters to inject into the step environment. Format: KEY=value
```

--------------------------------

### Full Docker in Docker (dind) Example

Source: https://woodpecker-ci.org/docs/usage/advanced-usage

A complete configuration combining the Docker client step and the Docker in Docker service setup for end-to-end TLS-secured Docker operations.

```yaml
steps:
  - name: test
    image: docker:cli # use 'docker:<major-version>-cli' or similar in production
    environment:
      DOCKER_HOST: 'tcp://docker:2376'
      DOCKER_CERT_PATH: '/dind-certs/client'
      DOCKER_TLS_VERIFY: '1'
    volumes:
      - /opt/woodpeckerci/dind-certs:/dind-certs
    commands:
      - docker version
  
services:
  - name: docker
    image: docker:dind # use 'docker:<major-version>-dind' or similar in production
    privileged: true
    environment:
      DOCKER_TLS_CERTDIR: /dind-certs
    volumes:
      - /opt/woodpeckerci/dind-certs:/dind-certs
    ports:
      - 2376
```

--------------------------------

### Complete Pipeline Example with Services

Source: https://woodpecker-ci.org/docs/usage/services

An example of a complete pipeline demonstrating service definition, environment configuration, and interaction with a service container.

```yaml
services:  
  - name: database  
    image: mysql  
    environment:  
      MYSQL_DATABASE: test  
      MYSQL_ROOT_PASSWORD: example  
steps:  
  - name: get-version  
    image: ubuntu  
    commands:  
      - ( apt update && apt dist-upgrade -y && apt install -y mysql-client 2>&1 )> /dev/null  
      - sleep 30s # need to wait for mysql-server init  
      - echo 'SHOW VARIABLES LIKE "version"' | mysql -u root -h database test -p example  
```

--------------------------------

### Docker Command Example

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

An incomplete example demonstrating how the generated shell script is executed within a Docker container using the 'docker run' command.

```docker
docker run --entrypoint=build.sh golang
```

--------------------------------

### Kubernetes Headless Service Example

Source: https://woodpecker-ci.org/docs/administration/configuration/backends/kubernetes

Example of configuring steps to use a headless service for inter-step communication via DNS. Ensure Docker CLI and Docker DIND images are versioned appropriately for production.

```yaml
steps:
  - name: test
    image: docker:cli # use 'docker:<major-version>-cli' or similar in production
    environment:
      DOCKER_HOST: 'tcp://docker:2376'
      DOCKER_CERT_PATH: '/woodpecker/dind-certs/client'
      DOCKER_TLS_VERIFY: '1'
    commands:
      - docker run hello-world

  - name: docker
    image: docker:dind # use 'docker:<major-version>-dind' or similar in production
    detached: true
    privileged: true
    environment:
      DOCKER_TLS_CERTDIR: /woodpecker/dind-certs
```

--------------------------------

### Start UI Server with Remote Server Config

Source: https://woodpecker-ci.org/docs/development/ui

Start the UI development server with environment variables to proxy requests to a remote Woodpecker server. This allows testing UI changes against a live, complex data environment.

```bash
VITE_DEV_PROXY=<your server URL> VITE_DEV_USER_SESS_COOKIE=<user session cookie value> pnpm start
```

--------------------------------

### Complex plugin settings example

Source: https://woodpecker-ci.org/docs/usage/plugins/creating-plugins

Demonstrates how to define complex settings for a plugin, which are converted to JSON and passed as environment variables.

```yaml
steps:
  - name: plugin
    image: foo/plugin
    settings:
      complex:
        abc: 2
        list:
          - 2
          - 3
```

--------------------------------

### Woodpecker Server Environment Configuration

Source: https://woodpecker-ci.org/docs/administration/installation/packages

Example environment file for configuring the Woodpecker server. Adjust these variables to match your setup, especially for authentication and host settings.

```ini
WOODPECKER_OPEN=true
WOODPECKER_HOST=${WOODPECKER_HOST}
WOODPECKER_GITHUB=true
WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}

```

--------------------------------

### Webhook plugin configuration example

Source: https://woodpecker-ci.org/docs/usage/plugins/creating-plugins

Shows how an end-user would configure a webhook plugin in their Woodpecker CI pipeline YAML.

```yaml
steps:
  - name: webhook
    image: foo/webhook
    settings:
      url: https://example.com
      method: post
      body: |
        hello world
```

--------------------------------

### Tunnelmole Output Example

Source: https://woodpecker-ci.org/docs/administration/configuration/server

Example output from the `tmole` command, showing the public URLs that forward to the local service.

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

--------------------------------

### Define Workflow Steps

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

Example of defining two distinct steps, 'backend' and 'frontend', each with its own image and commands. Step names are arbitrary and can be omitted.

```yaml
steps:
  - name: backend
    image: golang
    commands:
      - go build
      - go test
  - name: frontend
    image: node
    commands:
      - npm install
      - npm run test
      - npm run build
```

--------------------------------

### Start UI Development Server

Source: https://woodpecker-ci.org/docs/development/ui

Run the UI development server with hot-reloading enabled. This is used in conjunction with the Woodpecker server's dev-proxy.

```bash
pnpm start
```

--------------------------------

### Configure a Plugin in .woodpecker.yaml

Source: https://woodpecker-ci.org/docs/usage/plugins/overview

This example shows how to configure a custom plugin named 'deploy-to-k8s' in your .woodpecker.yaml file, specifying its image and settings.

```yaml
steps:  
  - name: deploy-to-k8s  
    image: cloud/my-k8s-plugin  
    settings:  
      template: config/k8s/service.yaml  
```

--------------------------------

### Install Woodpecker Helm Chart

Source: https://woodpecker-ci.org/docs/administration/installation/helm-chart

Use this command to install the Woodpecker Helm chart from its OCI registry. Replace <VERSION> with the desired chart version.

```bash
helm install woodpecker oci://ghcr.io/woodpecker-ci/helm/woodpecker --version <VERSION>
```

--------------------------------

### Woodpecker Prometheus Metrics Example

Source: https://woodpecker-ci.org/docs/administration/configuration/server

Example output of Woodpecker's Prometheus metrics endpoint, showing pipeline counts and build times.

```text
# HELP woodpecker_pipeline_count Pipeline count.
# TYPE woodpecker_pipeline_count counter
woodpecker_pipeline_count{branch="main",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3
woodpecker_pipeline_count{branch="dev",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3
# HELP woodpecker_pipeline_time Build time.
# TYPE woodpecker_pipeline_time gauge
woodpecker_pipeline_time{branch="main",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 116
woodpecker_pipeline_time{branch="dev",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 155
# HELP woodpecker_pipeline_total_count Total number of builds.

```

--------------------------------

### Build Web Component

Source: https://woodpecker-ci.org/docs/development/guides

Steps to build the web component for Woodpecker-CI. Ensure to run `make vendor` before installing dependencies.

```bash
make vendor
cd web/ 
pnpm install --frozen-lockfile
pnpm build
cd ..
```

--------------------------------

### Example Request Payload

Source: https://woodpecker-ci.org/docs/usage/extensions/configuration-extension

An example of a complete JSON request payload sent to the configuration extension, including repository, pipeline, configuration, and netrc details.

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

--------------------------------

### Forge Addon Example Structure in Go

Source: https://woodpecker-ci.org/docs/development/addons

This Go code demonstrates the basic structure for a Woodpecker-CI forge addon. It imports necessary Woodpecker packages and uses `addon.Serve` to connect the addon to the server. Ensure you parse environment variables as addons run in separate processes.

```go
package main  

  

import (  

  "context"  

  "net/http"  

  

  "go.woodpecker-ci.org/woodpecker/v3/server/forge/addon"  

  forgeTypes "go.woodpecker-ci.org/woodpecker/v3/server/forge/types"  

  "go.woodpecker-ci.org/woodpecker/v3/server/model"  

)

  

func main() {  

  addon.Serve(config{})  

}  

  
type config struct {  

}

  

// `config` must implement "go.woodpecker-ci.org/woodpecker/v3/server/forge". Forge. You must directly use Woodpecker's packages - see imports above.  


```

--------------------------------

### Example Pipeline with Prettier and S3 Plugins

Source: https://woodpecker-ci.org/docs/usage/plugins/overview

This pipeline demonstrates using the Prettier plugin for code formatting and the S3 plugin for publishing artifacts. It includes a build step, a prettier step, and a publish step with specific settings for the S3 plugin.

```yaml
steps:  
  - name: build  
    image: golang  
    commands:  
      - go build  
      - go test  
  
  - name: prettier  
    image: woodpeckerci/plugin-prettier  
  
  - name: publish  
    image: woodpeckerci/plugin-s3  
    settings:  
      bucket: my-bucket-name  
      source: some-file-name  
      target: /target/some-file  
```

--------------------------------

### Example Response Payload

Source: https://woodpecker-ci.org/docs/usage/extensions/configuration-extension

An example of a JSON response payload from the configuration extension, providing new configuration files in Woodpecker's YAML format.

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

--------------------------------

### Pipeline Configuration Syntax Deprecation Example

Source: https://woodpecker-ci.org/docs/development/deprecations

Illustrates the transition from an old syntax `secrets: [token]` to a new syntax `environment: { TOKEN: { from_secret: token } }` for pipeline configuration. This change is managed through a phased deprecation process starting with warnings and progressing to errors and code removal.

```yaml
secrets: [token]
```

```yaml
environment: { TOKEN: { from_secret: token } }
```

--------------------------------

### Start Woodpecker Server

Source: https://woodpecker-ci.org/docs/development/getting-started

Run the Woodpecker server application from your terminal. This command is used to start the main server process.

```bash
go run ./cmd/server
```

--------------------------------

### Configure Server Hostname

Source: https://woodpecker-ci.org/docs/administration/configuration/server

Set the fully qualified URL for the user-facing hostname, including port and path prefix if necessary. Examples show different configurations.

```bash
WOODPECKER_HOST=http://woodpecker.example.org
```

```bash
WOODPECKER_HOST=http://example.org/woodpecker
```

```bash
WOODPECKER_HOST=http://example.org:1234/woodpecker
```

--------------------------------

### Example Registry Extension Response Payload

Source: https://woodpecker-ci.org/docs/usage/extensions/registry-extension

An example of the JSON payload a registry extension should return to Woodpecker, providing credentials for a Docker registry.

```json
{
  "registries": [
    {
      "address": "docker.io",
      "username": "woodpecker-bot",
      "password": "your-pass-word-123"
    }
  ]
}
```

--------------------------------

### Download and Install Woodpecker Packages

Source: https://woodpecker-ci.org/docs/administration/installation/packages

Fetches the latest release version and downloads the appropriate DEB or RPM packages for your distribution. Use apt for Debian/Ubuntu and dnf for CentOS/RHEL.

```bash
RELEASE_VERSION=$(curl -s https://api.github.com/repos/woodpecker-ci/woodpecker/releases/latest | grep -Po '"tag_name":\s"v\K[^"].+')  

# Debian/Ubuntu (x86_64)  

curl -fLOOO "https://github.com/woodpecker-ci/woodpecker/releases/download/v${RELEASE_VERSION}/woodpecker-{server,agent,cli}_${RELEASE_VERSION}_amd64.deb"  

sudo apt --fix-broken install ./woodpecker-{server,agent,cli}_${RELEASE_VERSION}_amd64.deb  

# CentOS/RHEL (x86_64)  

sudo dnf install https://github.com/woodpecker-ci/woodpecker/releases/download/v${RELEASE_VERSION}/woodpecker-{server,agent,cli}-${RELEASE_VERSION}.x86_64.rpm  
```

--------------------------------

### Dockerfile for webhook plugin

Source: https://woodpecker-ci.org/docs/usage/plugins/creating-plugins

A Dockerfile to package the webhook plugin's shell script, install dependencies, and set the entrypoint.

```dockerfile
# please pin the version, e.g. alpine:3.19
FROM alpine
ADD script.sh /bin/
RUN chmod +x /bin/script.sh
RUN apk -Uuv add curl ca-certificates
ENTRYPOINT /bin/script.sh
```

--------------------------------

### Basic Docker Compose Setup

Source: https://woodpecker-ci.org/docs/administration/installation/docker-compose

This is the primary Docker Compose configuration for a Woodpecker instance connected to GitHub. It sets up persistent volumes for server and agent data, configures environment variables, and exposes the server port.

```yaml
services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:v3
    ports:
      - 8000:8000
    volumes:
      - woodpecker-server-data:/var/lib/woodpecker/
    environment:
      - WOODPECKER_OPEN=true
      - WOODPECKER_HOST=${WOODPECKER_HOST}
      - WOODPECKER_GITHUB=true
      - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
      - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:v3
    command: agent
    restart: always
    depends_on:
      - woodpecker-server
    volumes:
      - woodpecker-agent-config:/etc/woodpecker
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
volumes:
  woodpecker-server-data:
  woodpecker-agent-config:

```

--------------------------------

### YAML After Matrix Interpolation

Source: https://woodpecker-ci.org/docs/usage/matrix-workflows

This example shows the YAML structure after matrix variables have been interpolated, demonstrating how images and environment variables are updated.

```yaml
steps:
  - name: build
    image: golang:1.4
    commands:
      - go get
      - go build
      - go test
    environment:
      - GO_VERSION=1.4
      - DATABASE=mysql:8

services:
  - name: database
    image: mysql:8
```

--------------------------------

### Execute step for multiple platforms using wildcards

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

The `platform` filter supports wildcards for flexible platform matching. This example runs on any Linux distribution or specifically on Windows AMD64.

```yaml
when:
  - platform: [linux/*, windows/amd64]
```

--------------------------------

### Configure Database Connection

Source: https://woodpecker-ci.org/docs/administration/configuration/server

Set the WOODPECKER_DATABASE_DATASOURCE environment variable to configure the database connection string. Examples for MySQL and PostgreSQL are provided.

```bash
# MySQL  
# https://github.com/go-sql-driver/mysql#dsn-data-source-name  
WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true  
  
# PostgreSQL  
# https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING  
WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker?sslmode=disable  
```

--------------------------------

### Build Custom Docker Image with Credential Helper

Source: https://woodpecker-ci.org/docs/administration/configuration/backends/docker

Use this Dockerfile to build a custom server image that includes a Docker credential helper for private registries. Ensure the credential helper is installed and configured.

```dockerfile
FROM woodpeckerci/woodpecker-server:latest-alpine  

RUN apk add -U --no-cache docker-credential-ecr-login  
```

--------------------------------

### Tunnelmole Command

Source: https://woodpecker-ci.org/docs/administration/configuration/server

Start a tunnel to expose a local port (e.g., 8000) to the internet using Tunnelmole. The output provides URLs to access the service externally.

```bash
tmole 8000
```

--------------------------------

### Woodpecker Agent Environment Configuration

Source: https://woodpecker-ci.org/docs/administration/installation/packages

Example environment file for configuring the Woodpecker agent. Ensure the WOODPECKER_SERVER and WOODPECKER_AGENT_SECRET are correctly set to connect to your Woodpecker server.

```ini
WOODPECKER_SERVER=localhost:9000
WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}

```

--------------------------------

### Docker Image Formats

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

Provides examples of various valid Docker image formats that can be used in Woodpecker CI configurations, including different registries and tag specifications.

```yaml
image: golang
image: golang:1.7
image: library/golang:1.7
image: index.docker.io/library/golang
image: index.docker.io/library/golang:1.7
```

--------------------------------

### Docker Compose Setup for Autoscaler

Source: https://woodpecker-ci.org/docs/administration/configuration/autoscaler

Integrate the autoscaler service into your existing docker-compose.yaml. Ensure to replace placeholders with your actual server URL, API token, and desired configuration values. The autoscaler requires specific environment variables to connect to the Woodpecker server and manage agent provisioning.

```yaml
services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:next
    [...]
  woodpecker-autoscaler:
    image: woodpeckerci/autoscaler:next
    restart: always
    depends_on:
      - woodpecker-server
    environment:
      - WOODPECKER_SERVER=https://your-woodpecker-server.tld # the url of your woodpecker server / could also be a public url
      - WOODPECKER_TOKEN=${WOODPECKER_TOKEN} # the api token you can get from the UI https://your-woodpecker-server.tld/user
      - WOODPECKER_MIN_AGENTS=0
      - WOODPECKER_MAX_AGENTS=3
      - WOODPECKER_WORKFLOWS_PER_AGENT=2 # the number of workflows each agent can run at the same time
      - WOODPECKER_GRPC_ADDR=grpc.your-woodpecker-server.tld # the grpc address of your woodpecker server, publicly accessible from the agents. See https://woodpecker-ci.org/docs/administration/configuration/server#caddy for an example of how to expose it. Do not include "https://" in the value.
      - WOODPECKER_GRPC_SECURE=true
      - WOODPECKER_AGENT_ENV= # optional environment variables to pass to the agents
      - WOODPECKER_PROVIDER=hetznercloud # set the provider, you can find all the available ones down below
      - WOODPECKER_HETZNERCLOUD_API_TOKEN=${WOODPECKER_HETZNERCLOUD_API_TOKEN} # your api token for the Hetzner cloud
```

--------------------------------

### Use S3 Plugin for Uploads

Source: https://woodpecker-ci.org/docs/usage/intro

This example demonstrates using the woodpeckerci/plugin-s3 plugin to upload files to an S3 bucket. It configures the bucket name, access key, secret key (retrieved from Woodpecker secrets), source files, and target location within the bucket.

```yaml
steps:
  - name: upload
    image: woodpeckerci/plugin-s3
    settings:
      bucket: my-bucket-name
      access_key: a50d28f4dd477bc184fbd10b376de753
      secret_key:
        from_secret: aws_secret_key
      source: public/**/*
      target: /target/location
```

--------------------------------

### Kubernetes Pod Security Context Example

Source: https://woodpecker-ci.org/docs/administration/configuration/backends/kubernetes

Illustrates the resulting Kubernetes Pod specification after applying security context options. User and group IDs are set at the pod level, while privileged mode is set at the container level.

```yaml
kind: Pod
spec:
  securityContext:
    runAsUser: 999
    runAsGroup: 999
  containers:
    - name: wp-01hcd83q7be5ymh89k5accn3k6-0-step-0
      image: alpine
      securityContext:
        privileged: true
  [...]
```

--------------------------------

### Example Registry Extension Request Payload

Source: https://woodpecker-ci.org/docs/usage/extensions/registry-extension

An example of the JSON payload Woodpecker sends to the registry extension. Note that this example may be outdated; refer to the latest models for the current structure.

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

--------------------------------

### Correct Event Filter Configuration

Source: https://woodpecker-ci.org/docs/usage/linter

Examples of correct 'when' block configurations that adhere to the event filtering best practice. Ensuring all 'when' conditions include an 'event' filter prevents steps from running on unexpected events.

```yaml
when:
  - branch: main
    event: push
  - event: tag
```

```yaml
steps:
  - name: test
    when:
      event: [tag, push]
  
  - name: deploy
    when:
      - event: tag
```

--------------------------------

### Example Secret Extension Request Payload

Source: https://woodpecker-ci.org/docs/usage/extensions/secret-extension

An example of the JSON payload sent to the secret extension. Note that the `netrc` field is omitted if netrc sending is not enabled. This example may be outdated; refer to the model definitions for the latest structure.

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

// Note: the "netrc" field is omitted when netrc sending is not enabled.
```

--------------------------------

### Start Woodpecker Agent

Source: https://woodpecker-ci.org/docs/development/getting-started

Run the Woodpecker agent application from your terminal. This command is used to start a worker agent.

```bash
go run ./cmd/agent
```

--------------------------------

### Example Secret Extension JSON Response

Source: https://woodpecker-ci.org/docs/usage/extensions/secret-extension

An example of a JSON response containing two secrets, one with event restrictions.

```json
{
  "secrets": [
    {
      "name": "docker_password",
      "value": "your-secret-password-123"
    },
    {
      "name": "deploy_token",
      "value": "super-secret-token",
      "events": ["push", "tag"]
    }
  ]
}
```

--------------------------------

### Use Named Volumes

Source: https://woodpecker-ci.org/docs/usage/volumes

Demonstrates the use of named volumes, which are mounted from the host machine. Ensure you use absolute paths for volume configurations.

```yaml
- volumes: [ some_volume_name:/var/run/volume ]
```

--------------------------------

### Configure Service Container Environment Variables

Source: https://woodpecker-ci.org/docs/usage/services

Customize service container startup using environment variables. Refer to the official image documentation for available variables.

```yaml
services:  
  - name: database  
    image: mysql  
+    environment:  
+      MYSQL_DATABASE: test  
+      MYSQL_ALLOW_EMPTY_PASSWORD: yes  
  
  - name: cache  
    image: redis  
```

--------------------------------

### Woodpecker Custom CSS Example

Source: https://woodpecker-ci.org/docs/administration/configuration/server

Example CSS to add a banner message to the Woodpecker UI. Ensure the file is placed at the path specified by WOODPECKER_CUSTOM_CSS_FILE.

```css
.banner-message {
  position: absolute;
  width: 280px;
  height: 40px;
  margin-left: 240px;
  margin-top: 5px;
  padding-top: 5px;
  font-weight: bold;
  background: red no-repeat;
  text-align: center;
}
```

--------------------------------

### Equivalent Docker Commands for Workspace

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

Illustrates the underlying Docker commands that are executed when a custom workspace base is defined, showing volume creation and container runs with the specified volume mount.

```bash
docker volume create my-named-volume  
  
docker run --volume=my-named-volume:/go golang:latest  
docker run --volume=my-named-volume:/go node:latest  
```

--------------------------------

### Build and push Docker image

Source: https://woodpecker-ci.org/docs/usage/plugins/creating-plugins

Commands to build the Docker image for the plugin and push it to a Docker registry.

```shell
docker build -t foo/webhook .
docker push foo/webhook
```

--------------------------------

### Build Server Docker Image

Source: https://woodpecker-ci.org/docs/development/guides

Builds a multi-architecture Docker image for the Woodpecker-CI server. Use `--push` to push the image to a registry.

```bash
docker buildx build --platform linux/amd64 -t username/repo:tag -f docker/Dockerfile.server.multiarch.rootless --push .
```

--------------------------------

### Woodpecker Custom JavaScript Example

Source: https://woodpecker-ci.org/docs/administration/configuration/server

Example JavaScript to add a banner message to the Woodpecker UI. Ensure the file is placed at the path specified by WOODPECKER_CUSTOM_JS_FILE. This snippet assumes a lightweight JavaScript library is included.

```javascript
// place/copy a minified version of your preferred lightweight JavaScript library here ... 
!(function () {
  'use strict';
  function e() {} /*...*/
})();

$().ready(function () {
  $('.app nav img').first().htmlAfter("<div class='banner-message'>This is a demo banner message :)</div>");
});
```

--------------------------------

### Run webhook plugin locally

Source: https://woodpecker-ci.org/docs/usage/plugins/creating-plugins

How to run the built Docker plugin locally for testing, passing settings as environment variables.

```shell
docker run --rm \
  -e PLUGIN_METHOD=post \
  -e PLUGIN_URL=https://example.com \
  -e PLUGIN_BODY="hello world" \
  foo/webhook
```

--------------------------------

### Define a Basic Workflow

Source: https://woodpecker-ci.org/docs/usage/intro

This YAML configuration defines a pipeline that runs on a push event to the main branch. It includes two steps: 'build' which echoes messages and creates an executable, and 'a-test-step' which uses a Go image to run the created executable.

```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
```

--------------------------------

### Get a user

Source: https://woodpecker-ci.org/docs/development/openapi

Returns a user with the specified login name. Requires admin rights. Supports pagination.

```APIDOC
## GET /users/{login}

### Description
Returns a user with the specified login name. Requires admin rights.

### Method
GET

### Endpoint
/users/{login}

### Parameters
#### Path Parameters
- **login** (string) - Required - the user's login name

#### Query Parameters
- **foobar** (string) - Optional - optional foobar parameter
- **page** (int) - Optional - for response pagination, page offset number (default: 1)
- **perPage** (int) - Optional - for response pagination, max items per page (default: 50)

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **User** (object) - User object

#### Response Example
{
  "example": "{\"id\": 1, \"login\": \"testuser\", \"name\": \"Test User\", \"email\": \"test@example.com\"}"
}

### Headers
- **Authorization** (string) - Required - Insert your personal access token (default: Bearer <personal access token>)
```

--------------------------------

### Build with External Web UI Path

Source: https://woodpecker-ci.org/docs/development/packaging

Use this command to build the Woodpecker server with the web UI distributed in a custom directory. Add the 'external_web' tag and specify the web UI root path using the -X flag.

```bash
go build -tags 'external_web' -ldflags '-s -w -extldflags "-static" -X go.woodpecker-ci.org/woodpecker/v3/version.Version=3.12.0 -X go.woodpecker-ci.org/woodpecker/v3/web.webUIRoot=/nix/store/maaajlp8h5gy9zyjgfhaipzj07qnnmrl-woodpecker-WebUI-3.12.0' -o dist/woodpecker-server go.woodpecker-ci.org/woodpecker/v3/cmd/server
```

--------------------------------

### Conditional Step Execution by Git Reference

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

Execute a step only for tag events where the git reference starts with 'refs/tags/v'.

```yaml
when:
  - event: tag
    ref: refs/tags/v*
```

--------------------------------

### Executing Pipeline with Dummy Backend

Source: https://woodpecker-ci.org/docs/development/testing

This command executes a pipeline configuration using the dummy backend engine. It's useful for testing pipeline logic and step execution flow.

```bash
woodpecker-cli --log-level trace exec --backend-engine dummy example.yaml
```

--------------------------------

### Configure Docker Client Step for TLS Connection

Source: https://woodpecker-ci.org/docs/usage/advanced-usage

Set up a step to use the Docker CLI, configuring it to connect to the dind service via TLS. This requires setting DOCKER_HOST, DOCKER_CERT_PATH, and DOCKER_TLS_VERIFY environment variables, and mounting the certificate volume.

```yaml
steps:
  - name: test
    image: docker:cli # in production use something like 'docker:<major version>-cli'
    environment:
      DOCKER_HOST: "tcp://docker:2376"
      DOCKER_CERT_PATH: "/dind-certs/client"
      DOCKER_TLS_VERIFY: "1"
    volumes:
      - /opt/woodpeckerci/dind-certs:/dind-certs
    commands:
      - docker version
```

--------------------------------

### context list, ls

Source: https://woodpecker-ci.org/docs/cli

List all contexts.

```APIDOC
## context list, ls

list all contexts

### Options

**--output** = "": output format (default: table)
**--output-no-headers** : do not print headers in output (default: false)
**--output-no-headers** : don't print headers (default: false)
```

--------------------------------

### Define Docker in Docker Service

Source: https://woodpecker-ci.org/docs/usage/advanced-usage

Configure a service to run the Docker daemon in privileged mode. This is the initial setup for dind.

```yaml
services:
  - name: docker
    image: docker:dind # use 'docker:<major-version>-dind' or similar in production
    privileged: true
    ports:
      - 2376
```

--------------------------------

### Configure Open Registration with Organization Filtering

Source: https://woodpecker-ci.org/docs/administration/configuration/server

Enable open registration and filter users by organizational affiliation using WOODPECKER_ORGS. Ensure WOODPECKER_OPEN is set to true.

```bash
WOODPECKER_OPEN=true
```

```bash
WOODPECKER_ORGS=dolores,dog-patch
```

--------------------------------

### show

Source: https://woodpecker-ci.org/docs/cli

Displays pipeline information with options for output format and header display.

```APIDOC
## show
show pipeline information
### Parameters
#### Query Parameters
- **--output** (string) - Optional - output format (default: table)
- **--output-no-headers** (boolean) - Optional - don't print headers (default: false)
```

--------------------------------

### Interpolate Matrix Variables in YAML

Source: https://woodpecker-ci.org/docs/usage/matrix-workflows

Matrix variables are interpolated using `${VARIABLE}` syntax before the YAML is parsed. This example shows a configuration before interpolation.

```yaml
matrix:
  GO_VERSION:
    - 1.4
    - 1.3
  DATABASE:
    - mysql:8
    - mysql:5
    - mariadb:10.1

steps:
  - name: build
    image: golang:${GO_VERSION}
    commands:
      - go get
      - go build
      - go test

services:
  - name: database
    image: ${DATABASE}
```

--------------------------------

### Build UI for Production

Source: https://woodpecker-ci.org/docs/development/ui

Build the UI code for production. This generated code is then integrated into the Woodpecker server using go-embed.

```bash
pnpm build
```

--------------------------------

### Conditional Step Execution for Branch Prefix

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

Execute a step if the branch name starts with 'prefix/'. Branch matching uses doublestar patterns.

```yaml
when:
  - branch: prefix/*
```

--------------------------------

### Name Steps Using Dictionaries

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

Alternative method for naming steps by using a dictionary structure instead of a list with 'name' keys. This provides a more concise syntax for defining steps.

```yaml
steps:
  backend:
    image: golang
    commands:
      - go build
      - go test
  frontend:
    image: node
    commands:
      - npm install
      - npm run test
      - npm run build
```

--------------------------------

### Mount Docker Socket Volume

Source: https://woodpecker-ci.org/docs/usage/volumes

Mount the Docker socket to allow Docker commands within the container. This is a common practice for Docker-in-Docker or Docker-out-of-Docker setups.

```yaml
steps:
  - name: build
    image: docker
    commands:
      - docker build --rm -t octocat/hello-world .
      - docker run --rm octocat/hello-world --test
      - docker push octocat/hello-world
      - docker rmi octocat/hello-world
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
```

--------------------------------

### Evaluate expression for commit author

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

Use the `evaluate` filter to conditionally run a step based on the commit author. This example runs only if the commit author is `woodpecker-ci`.

```yaml
when:
  - evaluate: 'CI_COMMIT_AUTHOR == "woodpecker-ci"'
```

--------------------------------

### Build CLI Docker Image

Source: https://woodpecker-ci.org/docs/development/guides

Builds a multi-architecture Docker image for the Woodpecker-CI CLI. This image is rootless and requires the CLI to be built first.

```bash
make build-cli
docker buildx build --platform linux/amd64 -t username/repo:tag -f docker/Dockerfile.cli.multiarch.rootless --push .
```

--------------------------------

### Manual OpenAPI Code Generation

Source: https://woodpecker-ci.org/docs/development/openapi

Execute these make commands to manually generate or update the server's Go code containing the OpenAPI specifications and to update the Markdown documentation in the ./docs folder.

```bash
make generate-openapi
```

```bash
make generate-docs
```

--------------------------------

### Enable Authentication for Public Repos

Source: https://woodpecker-ci.org/docs/usage/troubleshooting

If you encounter issues with internal repositories, try enabling this setting to authenticate public repositories.

```bash
WOODPECKER_AUTHENTICATE_PUBLIC_REPOS=true
```

--------------------------------

### Enable parallel steps with empty depends_on

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

Setting `depends_on: []` allows a step to start immediately without any dependencies, enabling parallel execution of independent steps.

```yaml
steps:
  - name: check code format
    image: mstruebing/editorconfig-checker
    depends_on: [] # enable parallel steps
  ...
```

--------------------------------

### Basic Agent Configuration

Source: https://woodpecker-ci.org/docs/administration/configuration/agent

Minimum required environment variables for an agent to connect to the Woodpecker server.

```bash
WOODPECKER_SERVER=localhost:9000

WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
```

--------------------------------

### Dummy Backend Pipeline Configuration

Source: https://woodpecker-ci.org/docs/development/testing

Use this configuration to test pipeline steps and services without executing actual commands. Ensure the agent or CLI is built with the 'test' build tag.

```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 service"

```

--------------------------------

### Evaluate expression to conditionally skip a step

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

Use the `evaluate` filter to conditionally skip a step based on a variable. This example skips the step only if `SKIP` is set to `true`.

```yaml
when:
  - evaluate: 'SKIP != "true"'
```

--------------------------------

### Configure MySQL/MariaDB Database

Source: https://woodpecker-ci.org/docs/administration/configuration/server

Set the database driver to MySQL and provide the connection string via WOODPECKER_DATABASE_DATASOURCE. Ensure your database is manually created and meets the minimum version requirements.

```bash
WOODPECKER_DATABASE_DRIVER=mysql
```

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

--------------------------------

### Use Plugins as Executables in Local Backend

Source: https://woodpecker-ci.org/docs/administration/configuration/backends/local

Plugins are treated as executable binaries in the local backend. They can be located by name if in `$PATH` or by absolute path. If no commands are provided, plugins are executed.

```yaml
steps:
  - name: build
    image: /usr/bin/tree
```

--------------------------------

### Ngrok HTTP Tunnel Command

Source: https://woodpecker-ci.org/docs/administration/configuration/server

Start an HTTP tunnel using Ngrok to expose a local port (e.g., 8000) to the internet. The command output will provide a public URL.

```bash
ngrok http 8000
```

--------------------------------

### Configure PostgreSQL Database

Source: https://woodpecker-ci.org/docs/administration/configuration/server

Set the database driver to PostgreSQL and provide the connection string via WOODPECKER_DATABASE_DATASOURCE. Use Postgres versions 11 or higher and ensure the database is manually created.

```bash
WOODPECKER_DATABASE_DRIVER=postgres
```

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

--------------------------------

### Evaluate expression for pull request labels

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

Conditionally run a step based on pull request labels using the `evaluate` filter. This example triggers the step if the pull request has the `deploy` label.

```yaml
when:
  - evaluate: 'CI_COMMIT_PULL_REQUEST_LABELS contains "deploy"'
```

--------------------------------

### Specify Shell for Local Backend

Source: https://woodpecker-ci.org/docs/administration/configuration/backends/local

Use the `image` entry to specify the shell, such as `bash` or `fish`, for running commands in the local backend.

```yaml
steps:
  - name: build
    image: bash
    commands: [...]
```

--------------------------------

### Evaluate expression to skip commits

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

Employ the `evaluate` filter with a `not` condition to skip steps for commits containing specific messages. This example skips the step if the commit message includes `please ignore me`.

```yaml
when:
  - evaluate: 'not (CI_COMMIT_MESSAGE contains "please ignore me")'
```

--------------------------------

### Absolute Path Volume Configuration

Source: https://woodpecker-ci.org/docs/usage/volumes

Illustrates the correct way to configure volumes using absolute paths. Relative paths like './certs' are invalid and will cause errors.

```yaml
-volumes: [ /etc/ssl/certs:/etc/ssl/certs ]
```

--------------------------------

### Escape Secrets in Parameter Expressions

Source: https://woodpecker-ci.org/docs/usage/secrets

When using secrets within parameter expressions that are preprocessed before pipeline execution, escape the secret variable with `$$` to ensure it is correctly evaluated. For example, `${TOKEN_ENV}` becomes `$${TOKEN_ENV}`.

```yaml
steps:
  - name: docker
    image: docker
    commands:
      - echo $${TOKEN_ENV}
    environment:
      TOKEN_ENV:
        from_secret: secret_token
```

--------------------------------

### Configure Addon Log Store

Source: https://woodpecker-ci.org/docs/administration/configuration/addons

Configure Woodpecker-CI to use an addon for its log storage. Set WOODPECKER_LOG_STORE to 'addon' and specify the file path for the addon.

```bash
WOODPECKER_LOG_STORE=addon
WOODPECKER_LOG_STORE_FILE_PATH=/path/to/your/addon/forge/file
```

--------------------------------

### Evaluate custom expressions

Source: https://woodpecker-ci.org/docs/usage/workflow-syntax

The `evaluate` filter allows for complex conditional logic using expressions that can reference built-in CI variables and custom variables. This example runs on pushes to the default branch of a specific repository.

```yaml
when:
  - evaluate: 'CI_PIPELINE_EVENT == "push" && CI_REPO == "owner/repo" && CI_COMMIT_BRANCH == CI_REPO_DEFAULT_BRANCH'
```