### Install Dependencies and Run Docusaurus

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/04-docs.md

Navigate to the docs directory, install Node.js dependencies using pnpm, build necessary plugins, and then start the Docusaurus development server for hot-reloading. Alternatively, build the documentation for static deployment.

```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://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/03-ui.md

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

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

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

### Kubernetes Headless Services Example

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/10-configuration/11-backends/20-kubernetes.md

Example demonstrating the use of headless services for inter-step communication within Kubernetes. This setup allows steps to reach each other via DNS using the step name as the hostname.

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

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

### Full Docker in Docker (dind) Example

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/90-advanced-usage.md

A complete Woodpecker CI pipeline configuration demonstrating the setup for Docker in Docker (dind) with TLS enabled. This includes both the client step for running Docker commands and the dind service configuration.

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

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

### Start Local Development Server

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/README.md

Starts a local development server for the website. Changes are reflected live without requiring a server restart.

```bash
pnpm start
```

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

### Complete Pipeline Example with Services

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/60-services.md

An example of a complete pipeline configuration including a database service with environment variables and a step that interacts with it after a delay.

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

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

### Install Project Dependencies

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/README.md

Installs all necessary project dependencies using pnpm. This should be run before any other commands.

```bash
pnpm install
```

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

### Install Make on Ubuntu

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/01-getting-started.md

Use this command to install the GNU Make utility on Ubuntu systems. Make is used for controlling the generation of executables and other non-source files from source files.

```bash
apt install make
```

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

### Custom Entrypoint Example

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/blog/2024-05-27-release-v2.5.0/index.md

Demonstrates how to define a custom entrypoint to override the default behavior. The commands section is ignored when a custom entrypoint is provided.

```yaml
entrypoint: ["/bin/my-script", ""]
```

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

### Example Response Payload

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/72-extensions/40-configuration-extension.md

An example of the JSON payload returned by the Configuration Extension, providing new configuration data.

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

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

### Configure Database Connection String (MySQL)

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/10-configuration/10-server.md

Example of setting the WOODPECKER_DATABASE_DATASOURCE for a MySQL connection. Ensure the DSN format is correct for the go-sql-driver.

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

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

### Configure Database Connection String (PostgreSQL)

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/10-configuration/10-server.md

Example of setting the WOODPECKER_DATABASE_DATASOURCE for a PostgreSQL connection. Ensure the connection string format is correct for libpq.

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

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

### Complex Plugin Settings Example

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/51-plugins/20-creating-plugins.md

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

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

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

### Example Pipeline with Prettier and S3 Plugins

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/51-plugins/51-overview.md

Demonstrates a pipeline utilizing the Prettier plugin for code formatting and the S3 plugin for artifact publishing.

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

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

### Enable Apache Proxy Modules

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/10-configuration/10-server.md

Ensure the 'proxy' and 'proxy_http' Apache modules are installed for reverse proxy functionality.

```diff
 ProxyPreserveHost On

+RequestHeader set X-Forwarded-Proto "https"

 ProxyPass / http://127.0.0.1:8000/
 ProxyPassReverse / http://127.0.0.1:8000/
```

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

### Start Woodpecker Server

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/01-getting-started.md

Launches the Woodpecker server application from the project root. This command is used for running the server locally.

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

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

### Example Request Payload

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/72-extensions/40-configuration-extension.md

An example of the JSON payload sent to the Configuration Extension, including repository, pipeline, and optional 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)\"\n"
    }
  ],
  "netrc": {
    "machine": "myforge.com",
    "login": "myUser",
    "password": "forge-access-token"
  }
}
```

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

### Git Clone Command

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/20-workflow-syntax.md

Example of cloning a Git repository into a specified directory, demonstrating how the path attribute is used.

```bash
git clone https://github.com/octocat/hello-world \
  /go/src/github.com/octocat/hello-world
```

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

### Install Woodpecker Helm Chart

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/05-installation/20-helm-chart.md

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

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

### Example Pipeline with Dummy Backend

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/09-testing.md

This YAML configuration demonstrates a pipeline that uses the 'dummy' image for steps and services. It's useful for testing pipeline logic without executing actual commands.

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

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

### Example Containerfile

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/blog/2023-12-15-podman-sigstore/index.md

A basic Containerfile that copies a built application binary and sets it as the default command. The base image 'gcr.io/distroless/static-debian12:nonroot' will be verified when pulled.

```dockerfile
FROM gcr.io/distroless/static-debian12:nonroot
COPY app /app
CMD ["/app"]
```

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

### Example Registry Extension Response Payload

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/72-extensions/50-registry-extension.md

An example of a JSON response from the registry extension, providing credentials for the docker.io registry.

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

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

### Mount Docker Socket as Volume

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/70-volumes.md

This example shows how to mount the Docker socket into a container, which is often necessary for Docker-in-Docker or Docker-out-of-Docker scenarios.

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

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

### Install Make on Mac OS

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/01-getting-started.md

Use this command to install the GNU Make utility on macOS using Homebrew. Make is used for controlling the generation of executables and other non-source files from source files.

```bash
brew install make
```

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

### User API Endpoint Documentation Example

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/09-openapi.md

Example of Swagger annotations for documenting a user API endpoint, including summary, description, router, response type, tags, and parameters.

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

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

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

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

### Download and Install DEB/RPM Packages

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/05-installation/30-packages.md

Fetches the latest release version and downloads the DEB or RPM packages for Woodpecker server, agent, and CLI. Installs the DEB packages using apt or RPM packages using dnf.

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

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

### Webhook Plugin Configuration Example

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/51-plugins/20-creating-plugins.md

Shows how an end-user would configure a webhook plugin in their Woodpecker CI YAML file, specifying URL, method, and body.

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

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

### Start Woodpecker Agent

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/01-getting-started.md

Launches the Woodpecker agent application from the project root. This command is used for running the agent locally.

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

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

### Docker Volume Creation

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/20-workflow-syntax.md

Example of creating a named Docker volume, which can be used to persist data across container runs.

```bash
docker volume create my-named-volume
```

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

### Dummy Backend Execution Log Output

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/09-testing.md

Example log output from executing a pipeline with the 'dummy' backend. This helps in understanding the execution flow and debugging.

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

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

### Start UI Server for Remote Testing

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/03-ui.md

Run the UI development server with environment variables for connecting to a remote Woodpecker server. VITE_DEV_PROXY should be set to the remote server URL, and VITE_DEV_USER_SESS_COOKIE to the value of the user session cookie.

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

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

### CRON Definition Migration Example

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/src/pages/migrations.md

Shows the difference in CRON job definition syntax between Woodpecker CI 2.x and 3.x, highlighting the removal of the seconds field.

```sh
2.x:

```sh
0 0 8 * * *
```
```

```sh
3.x:

```sh
0 8 * * *
```
```

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

### Forge Addon Main Function Example (Go)

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/100-addons.md

This is a basic structure for a Woodpecker forge addon. It demonstrates the necessary imports and the `addon.Serve` call with a configuration struct. Ensure your config struct implements the `Forge` interface.

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

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

### Registry Extension Configuration

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/72-extensions/50-registry-extension.md

Configuration example for setting the registry extension endpoint in the Woodpecker server.

```APIDOC
## Global configuration

In addition to the ability to configure the extension per repository, you can also configure a global endpoint in the Woodpecker server configuration. This can be useful if you want to use the extension for all repositories. Be careful if
you share your Woodpecker server with others as they will also use your registry extension.

If both the global and the repo-level extension return credentials for a registry, it will use the credentials from the repo extension.

```ini title="Server"
WOODPECKER_REGISTRY_EXTENSION_ENDPOINT=https://example.com/ciconfig
```
```

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

### Configure Docker Client Step for DIND

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/90-advanced-usage.md

Set up a pipeline step to communicate with the Docker daemon. Configure `DOCKER_HOST`, `DOCKER_CERT_PATH`, and `DOCKER_TLS_VERIFY` environment variables, and mount the volume containing the TLS certificates. This setup is framework-agnostic and respects standard Docker environment variables.

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

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

### Dockerfile for Plugin Packaging

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/51-plugins/20-creating-plugins.md

A Dockerfile to package a shell script plugin, installing necessary tools like curl and setting the script as 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
```

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

### Woodpecker Server Environment Configuration

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/05-installation/30-packages.md

Example environment file for the Woodpecker server. Adjust the values, especially secrets and host configuration, according to your environment.

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

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

### Configure Prometheus Namespace and Pod Selectors

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/05-installation/20-helm-chart.md

If metrics are not received, verify your Prometheus configuration. These examples show how to select all namespaces or all pod monitors by disabling selectors.

```yaml
# Search all available namespaces
podMonitorNamespaceSelector:
  matchLabels: {}
# Enable all available pod monitors
podMonitorSelector:
  matchLabels: {}
```

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

### Woodpecker Agent Environment Configuration

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/05-installation/30-packages.md

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

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

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

### Update Build Image

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/10-intro.md

Example of changing the Docker image used in the 'build' step to 'my-company/image-with-aws_cli' and updating the commands to use 'aws help'. This demonstrates how to customize build environments.

```yaml
steps:
  - name: build
    image: my-company/image-with-aws_cli
    commands:
      - aws help
```

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

### Initialize and Use Woodpecker Go Client

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/woodpecker-go/README.md

Demonstrates how to create an authenticated HTTP client and use it to initialize the Woodpecker client. It then shows how to fetch the current user and repository information.

```Go
import (
  "go.woodpecker-ci.org/woodpecker/v3/woodpecker-go/woodpecker"
  "golang.org/x/oauth2"
)

const (
  token = "dummyToken"
  host  = "http://woodpecker.company.tld"
)

func main() {
  // create an http client with oauth authentication.
  config := new(oauth2.Config)
  authenticator := config.Client(
    oauth2.NoContext,
    &oauth2.Token{
      AccessToken: token,
    },
  )

  // create the woodpecker client with authenticator
  client := woodpecker.NewClient(host, authenticator)

  // gets the current user
  user, err := client.Self()
  fmt.Println(user, err)

  // gets the named repository information
  repo, err := client.RepoLookup("woodpecker-ci/woodpecker")
  fmt.Println(repo, err)
}
```

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

### Docker Compose Setup for Woodpecker CI

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/05-installation/10-docker-compose.md

This is the main docker-compose.yaml file for deploying Woodpecker server and agent. It configures persistent volumes, environment variables for GitHub integration, and network settings.

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

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

### Set Workflow Concurrency Limit

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/25-workflows.md

Use the `concurrency` setting to limit the number of simultaneous runs for a workflow. When the limit is reached, new instances are queued and start only after a running instance finishes. This example sets a limit of 1 for the deploy workflow.

```yaml
steps:
  - name: deploy
    image: debian:stable-slim
    commands:
      - echo deploying

depends_on:
  - test

concurrency:
  limit: 1
```

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

### Example Registry Extension Request Payload

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/72-extensions/50-registry-extension.md

An example of the JSON payload Woodpecker sends to the registry extension. Note that this example may be outdated; refer to the linked models 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/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"
  }
}
```

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

### Build Web Component and Server

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/07-guides.md

Steps to build the web component and cross-compile the server for Docker. Requires a amd64 host for xgo.

```shell
### build web component
make vendor
cd web/
pnpm install --frozen-lockfile
pnpm build
cd ..

### define the platforms to build for (e.g. linux/amd64)
# (the | is not a typo here)
export PLATFORMS='linux|amd64'
make cross-compile-server

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

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

### Start Tunnelmole Tunnel

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/10-configuration/10-server.md

Use the 'tmole' command to start a tunnel to your local Woodpecker server, typically on port 8000.

```bash
tmole 8000
```

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

### Basic Step Definition

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/20-workflow-syntax.md

Defines a step named 'backend' using the 'golang' image and specifies build and test commands to be executed sequentially.

```yaml
steps:
  - name: backend
    image: golang
    commands:
      - go build
      - go test
```

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

### Example Woodpecker Configuration API Response

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/10-configuration/10-server.md

An example JSON response structure from the Woodpecker Configuration API, showing a pipeline configuration with a backend step.

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

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

### Example Secret Extension Response Payload

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/72-extensions/55-secret-extension.md

An example of the JSON response payload that the secret extension should return, containing a list of secrets with their names, values, and optional event restrictions.

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

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

### Running Plugin Locally for Testing

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/51-plugins/20-creating-plugins.md

Demonstrates how to run the Docker plugin locally, simulating the environment variables that Woodpecker CI would provide during a build.

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

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

### Example Secret Extension Request Payload

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/72-extensions/55-secret-extension.md

An example of the JSON request payload sent to the secret extension, including repository, pipeline, and optional netrc details. Note that the structure may differ from the latest models.

```json
// Please check the latest structure in the models mentioned above.
// This example is likely outdated.

{
  "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"
  }
}
// Note: the "netrc" field is omitted when netrc sending is not enabled.
```

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

### Deploy Website Manually

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/README.md

Manually builds the website and pushes it to the deployment branch. Ensure environment variables are set correctly for the bot user and SSH.

```bash
GIT_USER=woodpecker-bot USE_SSH=true DEPLOYMENT_BRANCH=main pnpm deploy
```

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

### Build CLI Docker Image

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/07-guides.md

Instructions for building the Woodpecker CI command-line interface. This involves building the CLI binary and then constructing its Docker image.

```shell
### build the CLI
make build-cli

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

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

### Override Clone Depth

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/20-workflow-syntax.md

Customize the clone step settings to override the default depth, for example, to fetch a specific number of commits.

```yaml
clone:
  - name: git
    image: woodpeckerci/plugin-git
    settings:
      partial: false
      depth: 50
```

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

### Configure Service Environment Variables

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/60-services.md

Customize service container startup by defining 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
```

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

### Select a backend engine for local execution

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/73-local-execution.md

Explicitly choose the backend engine (e.g., docker, local) for your local run to match a specific agent configuration.

```shell
woodpecker-cli exec --backend-engine docker .woodpecker/my-first-workflow.yaml
```

```shell
woodpecker-cli exec --backend-engine local .woodpecker/my-first-workflow.yaml
```

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

### Configure MySQL/MariaDB Database Connection

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/10-configuration/10-server.md

Set the database driver to 'mysql' and provide the data source name (DSN) for your MySQL/MariaDB instance. Ensure the database is created manually and meets the minimum version requirements of the go-sql-driver/mysql.

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

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

### Filter Tags by Reference Pattern

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/20-workflow-syntax.md

Execute a step for tag events where the git reference matches a specific pattern, such as starting with 'v'.

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

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

### Directory Structure for Image Build

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/blog/2023-12-12-podman-image-builds/index.md

This bash snippet shows a typical project directory structure for building a container image, including the application source code and the CI configuration files.

```bash
. 
├── roundcube
│   ├── Containerfile
│   ├── docker-entrypoint.sh
│   └── php.ini
└── .woodpecker
    └── .build_roundcube.yml
```

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

### Caddy Reverse Proxy Configuration

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/10-configuration/10-server.md

Example Caddyfile configuration to proxy WebUI and API traffic to the Woodpecker server, and gRPC traffic separately.

```caddy
# expose WebUI and API
woodpecker.example.com {
  reverse_proxy woodpecker-server:8000
}

# expose gRPC
woodpecker-agent.example.com {
  reverse_proxy h2c://woodpecker-server:9000
}
```

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

### Execute Step for Multiple Platforms

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/20-workflow-syntax.md

Use a list to specify multiple platforms for which a step should execute. Wildcards can be used.

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

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

### Specifying Docker Image Versions

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/20-workflow-syntax.md

Shows how to specify exact image versions for steps and services, including plugin images.

```yaml
steps:
  - name: build
    image: golang:1.6
    commands:
      - go build
      - go test

  - name: prettier
    image: woodpeckerci/plugin-prettier

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

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

### Building and Publishing Docker Plugin

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/51-plugins/20-creating-plugins.md

Commands to build a Docker image for the plugin and push it to a Docker registry, making it available for use in Woodpecker CI.

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

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

### Escape Secrets for Parameter Expressions

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/40-secrets.md

When using secrets within parameter expressions that are evaluated before the pipeline starts, escape them with `$$` to ensure correct processing.

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

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

### Conditional Execution by Branch

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/20-workflow-syntax.md

Limit step execution to specific branches. This example triggers on the 'main' branch or if the target branch of a pull request is 'main'.

```yaml
steps:
  - name: prettier
    image: woodpeckerci/plugin-prettier
    when:
      - branch: main
```

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

### Substring Substitution

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/50-environment.md

Use substring operations to extract a specific part of the CI_COMMIT_SHA for use in pipeline settings. This example takes the first 8 characters.

```yaml
steps:
  - name: s3
    image: woodpeckerci/plugin-s3
    settings:
      target: /target/${CI_COMMIT_SHA:0:8}
```

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

### File Persistence Between Steps

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/20-workflow-syntax.md

Demonstrates how file changes are persisted across steps. The first step creates a file 'myfile', and the second step reads its content.

```yaml
steps:
  - name: build
    image: debian
    commands:
      - echo "test content" > myfile
  - name: a-test-step
    image: debian
    commands:
      - cat myfile
```

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

### Implement Service Initialization Delay

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/60-services.md

Add a `sleep` command to steps that depend on services to allow sufficient time for service initialization and connection establishment. This prevents connection errors due to services not being ready.

```yaml
steps:
  - name: test
    image: golang
    commands:
      - sleep 15
      - go get
      - go test

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

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

### Build Woodpecker with External Web UI

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/92-development/10-packaging.md

Use this command to build the Woodpecker server binary with the web UI distributed in a separate directory. This requires the 'external_web' tag and specifies a custom root path for the web UI using a linker flag.

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

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

### Start Ngrok Tunnel

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/10-configuration/10-server.md

Use the 'ngrok' command to create a secure public URL that forwards to your local Woodpecker server, usually on port 8000.

```bash
ngrok http 8000
```

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

### Configure PostgreSQL Database Connection

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/10-configuration/10-server.md

Set the database driver to 'postgres' and provide the connection string for your PostgreSQL instance. Ensure you are using a PostgreSQL version of 11 or higher and have manually created the database.

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

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

### Execute Step on Branch Pattern

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/20-usage/20-workflow-syntax.md

Use glob patterns to match branch names. Patterns starting with '*' should be quoted, and literal '/' must be escaped.

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

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

### Configure Plugin as Executable

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/10-configuration/11-backends/30-local.md

Plugins are treated as executable binaries. They can be specified by name if they are in the system's `$PATH` or by their absolute path.

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

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

### Woodpecker Server Systemd Service File

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/05-installation/30-packages.md

Configuration for the Woodpecker server systemd service. Ensure the EnvironmentFile path and User/Group match your system setup.

```INI
[Unit]
Description=WoodpeckerCI server
Documentation=https://woodpecker-ci.org/docs/administration/server-config
Requires=network.target
After=network.target
ConditionFileNotEmpty=/etc/woodpecker/woodpecker-server.env
ConditionPathExists=/etc/woodpecker/woodpecker-server.env

[Service]
Type=simple
EnvironmentFile=/etc/woodpecker/woodpecker-server.env
User=woodpecker
Group=woodpecker
ExecStart=/usr/local/bin/woodpecker-server
WorkingDirectory=/var/lib/woodpecker/
StateDirectory=woodpecker

[Install]
WantedBy=multi-user.target
```

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

### Add Bearer Token to Prometheus Config

Source: https://github.com/woodpecker-ci/woodpecker/blob/main/docs/docs/30-administration/10-configuration/10-server.md

Example of adding a bearer token to the Prometheus scrape configuration for Woodpecker. This token should be generated as a user API token.

```diff
 global:
   scrape_interval: 60s

 scrape_configs:
   - job_name: 'woodpecker'
+    bearer_token: dummyToken...

     static_configs:
        - targets: ['woodpecker.domain.com']
```