Cleanups + prefer .yaml (#3069)

Co-authored-by: Robert Kaussow <xoxys@rknet.org>

.gitpod.yml

@@ -37,7 +37,7 @@ tasks:
       go run go.woodpecker-ci.org/woodpecker/v2/cmd/agent
   - name: Gitea
     command: |
-      export DOCKER_COMPOSE_CMD="docker-compose -f docker-compose.gitpod.yml -p woodpecker"
+      export DOCKER_COMPOSE_CMD="docker-compose -f docker-compose.gitpod.yaml -p woodpecker"
       export GITEA_CLI_CMD="$DOCKER_COMPOSE_CMD exec -u git gitea gitea"
       $DOCKER_COMPOSE_CMD up -d
       until curl --output /dev/null --silent --head --fail http://localhost:3000; do printf '.'; sleep 1; done

.pre-commit-config.yaml

@@ -35,6 +35,14 @@ repos:
     hooks:
       - id: yamllint
         args: [--strict, -c=.yamllint.yaml]
+  - repo: local
+    hooks:
+      - id: yaml-file-extension
+        name: Check if YAML files has *.yaml extension.
+        entry: YAML filenames must have .yaml extension.
+        language: fail
+        files: .yml$
+        exclude: '^.gitpod.yml$'
 
 ci:
   autofix_commit_msg: |

.woodpecker/docs.yaml

@@ -4,7 +4,7 @@ variables:
   - &alpine_image 'docker.io/alpine:3.19'
   - path: &when_path
       - 'docs/**'
-      - '.woodpecker/docs.yml'
+      - '.woodpecker/docs.yaml'
       # since we generate docs for cli tool we have to watch this too
       - 'cli/**'
       - 'cmd/cli/**'

.woodpecker/test.yaml

@@ -9,7 +9,7 @@ variables:
   - &golang_image 'docker.io/golang:1.21.5'
   - &when
     - path: &when_path # related config files
-        - '.woodpecker/test.yml'
+        - '.woodpecker/test.yaml'
         - '.golangci.yaml'
         # go source code
         - '**/*.go'

.woodpecker/web.yaml

@@ -8,7 +8,7 @@ variables:
   - &when
     path:
       # related config files
-      - '.woodpecker/web.yml'
+      - '.woodpecker/web.yaml'
       # web source code
       - 'web/**'
       # api source code

CONTRIBUTING.md

@@ -77,8 +77,3 @@ As of semver guidelines, breaking changes will be released as a major version. W
 breaking changes to not release many majors each containing just a few breaking changes.
 Prior to the release of a major version, a release candidate (RC) will be published to allow easy testing,
 the actual release will be about a week later.
-
-## Development
-
-[pre-commit](https://pre-commit.com/) is used in this repository.
-To apply it during local development, take a look at [`pre-commit`s documentation](https://pre-commit.com/#usage)

Makefile

@@ -276,16 +276,16 @@ bundle-prepare: ## Prepare the bundles
 	go install github.com/goreleaser/nfpm/v2/cmd/nfpm@v2.6.0
 
 bundle-agent: bundle-prepare ## Create bundles for agent
-	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-agent.yml --target ./dist --packager deb
-	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-agent.yml --target ./dist --packager rpm
+	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/agent.yaml --target ./dist --packager deb
+	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/agent.yaml --target ./dist --packager rpm
 
 bundle-server: bundle-prepare ## Create bundles for server
-	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-server.yml --target ./dist --packager deb
-	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-server.yml --target ./dist --packager rpm
+	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/server.yaml --target ./dist --packager deb
+	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/server.yaml --target ./dist --packager rpm
 
 bundle-cli: bundle-prepare ## Create bundles for cli
-	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-cli.yml --target ./dist --packager deb
-	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-cli.yml --target ./dist --packager rpm
+	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/cli.yaml --target ./dist --packager deb
+	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/cli.yaml --target ./dist --packager rpm
 
 .PHONY: bundle
 bundle: bundle-agent bundle-server bundle-cli ## Create all bundles

SECURITY.md

@@ -1,7 +1,7 @@
 # Security
 
 We take security seriously.
-If you discover a security issue, please bring it to their attention right away!
+If you discover a security issue, please bring it to our attention right away!
 
 ## Reporting a Vulnerability
 

docs/docs/10-intro.md

@@ -5,13 +5,13 @@ If you are already using containers in your daily workflow, you'll for sure love
 
 ![woodpecker](woodpecker.png)
 
-## .woodpecker.yml
+## `.woodpecker.yaml`
 
-- Place your pipeline in a file named `.woodpecker.yml` in your repository
+- Place your pipeline in a file named `.woodpecker.yaml` in your repository
 - Pipeline steps can be named as you like
 - Run any command in the commands section
 
-```yaml title=".woodpecker.yml"
+```yaml title=".woodpecker.yaml"
 steps:
   build:
     image: debian
@@ -31,12 +31,12 @@ steps:
 - List the commands that should be executed in the container
 
 ```diff
-steps:
-  build:
--   image: debian
-+   image: mycompany/image-with-awscli
-    commands:
-      - aws help
+ steps:
+   build:
+-    image: debian
++    image: mycompany/image-with-awscli
+     commands:
+       - aws help
 ```
 
 ### File changes are incremental
@@ -44,7 +44,7 @@ steps:
 - Woodpecker clones the source code in the beginning
 - File changes are persisted throughout individual steps as the same volume is being mounted in all steps
 
-```yaml title=".woodpecker.yml"
+```yaml title=".woodpecker.yaml"
 steps:
   build:
     image: debian
@@ -73,15 +73,15 @@ ENTRYPOINT ["/usr/local/deploy"]
 kubectl apply -f $PLUGIN_TEMPLATE
 ```
 
-```yaml title=".woodpecker.yml"
+```yaml title=".woodpecker.yaml"
 steps:
   deploy-to-k8s:
     image: laszlocloud/my-k8s-plugin
     settings:
-      template: config/k8s/service.yml
+      template: config/k8s/service.yaml
 ```
 
-See [plugin docs](./20-usage/51-plugins/10-plugins.md).
+See [plugin docs](./20-usage/51-plugins/10-overview.md).
 
 ## Continue reading
 

docs/docs/20-usage/10-intro.md

@@ -19,7 +19,7 @@ This is because webhooks are signed using a per-repository secret key which is n
 
 ## Configuration
 
-To configure your pipeline you must create a `.woodpecker.yml` file in the root of your repository. The `.woodpecker.yml` file is used to define your pipeline steps.
+To configure your pipeline you must create a `.woodpecker.yaml` file in the root of your repository. The `.woodpecker.yaml` file is used to define your pipeline steps.
 
 :::note
 We support most of YAML 1.2, but preserve some behavior from 1.1 for backward compatibility.

docs/docs/20-usage/15-terminiology/index.md

@@ -54,7 +54,7 @@ Sometimes there are multiple terms that can be used to describe something. This
 [Pipeline]: ../20-workflow-syntax.md
 [Workflow]: ../25-workflows.md
 [Forge]: ../../30-administration/11-forges/10-overview.md
-[Plugin]: ../51-plugins/10-plugins.md
+[Plugin]: ../51-plugins/10-overview.md
 [Workspace]: ../20-workflow-syntax.md#workspace
 [Matrix]: ../30-matrix-workflows.md
 [Docker]: ../../30-administration/22-backends/10-docker.md

docs/docs/20-usage/20-workflow-syntax.md

@@ -67,7 +67,7 @@ The associated commit is checked out with git to a workspace which is mounted to
 - Woodpecker clones the source code in the beginning of the workflow
 - Changes to files are persisted through steps as the same volume is mounted to all steps
 
-```yaml title=".woodpecker.yml"
+```yaml title=".woodpecker.yaml"
 steps:
   build:
     image: debian
@@ -104,7 +104,7 @@ When using the `local` backend, the `image` entry is used to specify the shell,
 
 Woodpecker supports any valid Docker image from any Docker registry:
 
-```text
+```yaml
 image: golang
 image: golang:1.7
 image: library/golang:1.7
@@ -152,7 +152,9 @@ The above shell script is then executed as the container entrypoint. The below d
 docker run --entrypoint=build.sh golang
 ```
 
-> Please note that only build steps can define commands. You cannot use commands with plugins or services.
+:::note
+Only build steps can define commands. You cannot use commands with plugins or services.
+:::
 
 ### `environment`
 
@@ -220,13 +222,13 @@ Branch conditions are not applied to tags.
 Example conditional execution by branch:
 
 ```diff
-steps:
-  slack:
-    image: plugins/slack
-    settings:
-      channel: dev
-+   when:
-+     - branch: main
+ steps:
+   slack:
+     image: plugins/slack
+     settings:
+       channel: dev
++    when:
++      - branch: main
 ```
 
 > The step now triggers on main branch, but also if the target branch of a pull request is `main`. Add an event condition to limit it further to pushes on main only.
@@ -317,13 +319,13 @@ when:
 There are use cases for executing steps on failure, such as sending notifications for failed workflow / pipeline. Use the status constraint to execute steps even when the workflow fails:
 
 ```diff
-steps:
-  slack:
-    image: plugins/slack
-    settings:
-      channel: dev
-+   when:
-+     - status: [ success, failure ]
+ steps:
+   slack:
+     image: plugins/slack
+     settings:
+       channel: dev
++    when:
++      - status: [ success, failure ]
 ```
 
 #### `platform`
@@ -395,12 +397,14 @@ You can use [glob patterns](https://github.com/bmatcuk/doublestar#patterns) to m
 ```yaml
 when:
   - path:
-      include: ['.woodpecker/*.yml', '*.ini']
+      include: ['.woodpecker/*.yaml', '*.ini']
       exclude: ['*.md', 'docs/**']
       ignore_message: '[ALL]'
 ```
 
-**Hint:** Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions.
+:::info
+Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions.
+:::
 
 #### `evaluate`
 
@@ -490,11 +494,7 @@ For more details check the [services docs](./60-services.md).
 
 ## `workspace`
 
-The workspace defines the shared volume and working directory shared by all workflow steps. The default workspace matches the below pattern, based on your repository URL.
-
-```txt
-/woodpecker/src/github.com/octocat/hello-world
-```
+The workspace defines the shared volume and working directory shared by all workflow steps. The default workspace matches the pattern `/woodpecker/src/github.com/octocat/hello-world`, based on your repository URL.
 
 The workspace can be customized using the workspace block in the YAML file:
 
@@ -547,7 +547,7 @@ The path attribute defines the working directory of your build. This is where yo
 +  path: src/github.com/octocat/hello-world
 ```
 
-```text
+```bash
 git clone https://github.com/octocat/hello-world \
   /go/src/github.com/octocat/hello-world
 ```
@@ -575,12 +575,12 @@ You can add additional labels as a key value map:
 +  weather: sun
 +  hostname: "" # this label will be ignored as it is empty
 
-steps:
-  build:
-    image: golang
-    commands:
-      - go build
-      - go test
+ steps:
+   build:
+     image: golang
+     commands:
+       - go build
+       - go test
 ```
 
 ### Filter by platform
@@ -596,8 +596,8 @@ Assuming we have two agents, one `linux/arm` and one `linux/amd64`. Previously t
 +labels:
 +  platform: linux/arm64
 
-steps:
-  [...]
+ steps:
+   [...]
 ```
 
 ## `variables`
@@ -639,9 +639,9 @@ Example configuration to override depth:
 Example configuration to use a custom clone plugin:
 
 ```diff
-clone:
-  git:
-+   image: octocat/custom-git-plugin
+ clone:
+   git:
++    image: octocat/custom-git-plugin
 ```
 
 Example configuration to clone Mercurial repository:
@@ -726,36 +726,36 @@ Example conditional execution by branch:
        channel: dev
 ```
 
-> The step now triggers on main, but also if the target branch of a pull request is `main`. Add an event condition to limit it further to pushes on main only.
+The step now triggers on `main`, but also if the target branch of a pull request is `main`. Add an event condition to limit it further to pushes on main only.
 
 Execute a step if the branch is `main` or `develop`:
 
-```diff
+```yaml
 when:
   branch: [main, develop]
 ```
 
 Execute a step if the branch starts with `prefix/*`:
 
-```diff
+```yaml
 when:
   branch: prefix/*
 ```
 
 Execute a step using custom include and exclude logic:
 
-```diff
+```yaml
 when:
   branch:
-    include: [ main, release/* ]
-    exclude: [ release/1.0.0, release/1.1.* ]
+    include: [main, release/*]
+    exclude: [release/1.0.0, release/1.1.*]
 ```
 
 ### `event`
 
 Execute a step if the build event is a `tag`:
 
-```diff
+```yaml
 when:
   event: tag
 ```
@@ -763,21 +763,21 @@ when:
 Execute a step if the pipeline event is a `push` to a specified branch:
 
 ```diff
-when:
-  event: push
-+ branch: main
+ when:
+   event: push
++  branch: main
 ```
 
 Execute a step for all non-pull request events:
 
-```diff
+```yaml
 when:
   event: [push, tag, deployment]
 ```
 
 Execute a step for all build events:
 
-```diff
+```yaml
 when:
   event: [push, pull_request, tag, deployment]
 ```
@@ -797,7 +797,7 @@ when:
 
 Execute a step for deployment events matching the target deployment environment:
 
-```diff
+```yaml
 when:
   environment: production
   event: deployment
@@ -807,7 +807,7 @@ when:
 
 Execute a step only on a certain Woodpecker instance matching the specified hostname:
 
-```diff
+```yaml
 when:
   instance: stage.woodpecker.company.com
 ```
@@ -821,22 +821,24 @@ It is currently **only available** for GitHub, GitLab and Gitea (version 1.18.0
 
 Execute a step only on a pipeline with certain files being changed:
 
-```diff
+```yaml
 when:
-  path: "src/*"
+  path: 'src/*'
 ```
 
 You can use [glob patterns](https://github.com/bmatcuk/doublestar#patterns) to match the changed files and specify if the step should run if a file matching that pattern has been changed `include` or if some files have **not** been changed `exclude`.
 
-```diff
+```yaml
 when:
   path:
-    include: [ '.woodpecker/*.yml', '*.ini' ]
-    exclude: [ '*.md', 'docs/**' ]
-    ignore_message: "[ALL]"
+    include: ['.woodpecker/*.yaml', '*.ini']
+    exclude: ['*.md', 'docs/**']
+    ignore_message: '[ALL]'
 ```
 
-**Hint:** Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions.
+:::info
+Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions.
+:::
 
 ## `depends_on`
 
@@ -850,7 +852,9 @@ Workflows that should run even on failure should set the `runs_on` tag. See [her
 
 Woodpecker gives the ability to configure privileged mode in the YAML. You can use this parameter to launch containers with escalated capabilities.
 
-> Privileged mode is only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./71-project-settings.md#trusted) to enable trusted mode.
+:::info
+Privileged mode is only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./71-project-settings.md#trusted) to enable trusted mode.
+:::
 
 ```diff
  steps:

docs/docs/20-usage/25-workflows.md

@@ -1,14 +1,10 @@
 # Workflows
 
-:::info
-This Feature is only available for GitHub, Gitea & GitLab repositories. Follow [this](https://github.com/woodpecker-ci/woodpecker/issues/1138) issue to support further development.
-:::
-
 A pipeline has at least one workflow. A workflow is a set of steps that are executed in sequence using the same workspace which is a shared folder containing the repository and all the generated data from previous steps.
 
-Incase there is a single configuration in `.woodpecker.yml` Woodpecker will create a pipeline with a single workflow.
+In case there is a single configuration in `.woodpecker.yaml` Woodpecker will create a pipeline with a single workflow.
 
-By placing the configurations in a folder which is by default named `.woodpecker/` Woodpecker will create a pipeline with multiple workflows each named by the file they are defined in. Only `.yml` and `.yaml` files will be used and files in any subfolders like `.woodpecker/sub-folder/test.yml` will be ignored.
+By placing the configurations in a folder which is by default named `.woodpecker/` Woodpecker will create a pipeline with multiple workflows each named by the file they are defined in. Only `.yml` and `.yaml` files will be used and files in any subfolders like `.woodpecker/sub-folder/test.yaml` will be ignored.
 
 You can also set some custom path like `.my-ci/pipelines/` instead of `.woodpecker/` in the [project settings](./71-project-settings.md).
 
@@ -22,18 +18,18 @@ You can also set some custom path like `.my-ci/pipelines/` instead of `.woodpeck
 
 :::warning
 Please note that files are only shared between steps of the same workflow (see [File changes are incremental](./20-workflow-syntax.md#file-changes-are-incremental)). That means you cannot access artifacts e.g. from the `build` workflow in the `deploy` workflow.
-If you still need to pass artifacts between the workflows you need use some storage [plugin](./51-plugins/10-plugins.md) (e.g. one which stores files in an Amazon S3 bucket).
+If you still need to pass artifacts between the workflows you need use some storage [plugin](./51-plugins/10-overview.md) (e.g. one which stores files in an Amazon S3 bucket).
 :::
 
 ```bash
 .woodpecker/
-├── .build.yml
-├── .deploy.yml
-├── .lint.yml
-└── .test.yml
+├── .build.yaml
+├── .deploy.yaml
+├── .lint.yaml
+└── .test.yaml
 ```
 
-```yaml title=".woodpecker/.build.yml"
+```yaml title=".woodpecker/.build.yaml"
 steps:
   build:
     image: debian:stable-slim
@@ -42,7 +38,7 @@ steps:
       - sleep 5
 ```
 
-```yaml title=".woodpecker/.deploy.yml"
+```yaml title=".woodpecker/.deploy.yaml"
 steps:
   deploy:
     image: debian:stable-slim
@@ -55,7 +51,7 @@ depends_on:
   - test
 ```
 
-```yaml title=".woodpecker/.test.yml"
+```yaml title=".woodpecker/.test.yaml"
 steps:
   test:
     image: debian:stable-slim
@@ -67,7 +63,7 @@ depends_on:
   - build
 ```
 
-```yaml title=".woodpecker/.lint.yml"
+```yaml title=".woodpecker/.lint.yaml"
 steps:
   lint:
     image: debian:stable-slim
@@ -86,14 +82,14 @@ The workflows run in parallel on separate agents and share nothing.
 
 Dependencies between workflows can be set with the `depends_on` element. A workflow doesn't execute until all of its dependencies finished successfully.
 
-The name for a `depends_on` entry is the filename without the path, leading dots and without the file extension `.yml` or `.yaml`. If the project config for example uses `.woodpecker/` as path for CI files with a file named `.woodpecker/.lint.yml` the corresponding `depends_on` entry would be `lint`.
+The name for a `depends_on` entry is the filename without the path, leading dots and without the file extension `.yml` or `.yaml`. If the project config for example uses `.woodpecker/` as path for CI files with a file named `.woodpecker/.lint.yaml` the corresponding `depends_on` entry would be `lint`.
 
 ```diff
-steps:
-  deploy:
-    image: debian:stable-slim
-    commands:
-      - echo deploying
+ steps:
+   deploy:
+     image: debian:stable-slim
+     commands:
+       - echo deploying
 
 +depends_on:
 +  - lint
@@ -104,14 +100,14 @@ steps:
 Workflows that need to run even on failures should set the `runs_on` tag.
 
 ```diff
-steps:
-  notify:
-    image: debian:stable-slim
-    commands:
-      - echo notifying
+ steps:
+   notify:
+     image: debian:stable-slim
+     commands:
+       - echo notifying
 
-depends_on:
-  - deploy
+ depends_on:
+   - deploy
 
 +runs_on: [ success, failure ]
 ```

docs/docs/20-usage/30-matrix-workflows.md

@@ -58,22 +58,22 @@ services:
 Example YAML file after injecting the matrix parameters:
 
 ```diff
-steps:
-  build:
--   image: golang:${GO_VERSION}
-+   image: golang:1.4
-    commands:
-      - go get
-      - go build
-      - go test
-+   environment:
-+     - GO_VERSION=1.4
-+     - DATABASE=mysql:8
+ steps:
+   build:
+-    image: golang:${GO_VERSION}
++    image: golang:1.4
+     commands:
+       - go get
+       - go build
+       - go test
++    environment:
++      - GO_VERSION=1.4
++      - DATABASE=mysql:8
 
-services:
-  database:
--   image: ${DATABASE}
-+   image: mysql:8
+ services:
+   database:
+-    image: ${DATABASE}
++    image: mysql:8
 ```
 
 ## Examples

docs/docs/20-usage/40-secrets.md

@@ -17,13 +17,13 @@ Secrets are exposed to your pipeline steps and plugins as uppercase environment
 once their usage is declared in the `secrets` section:
 
 ```diff
-steps:
-  docker:
-    image: docker
-    commands:
-+     - echo $DOCKER_USERNAME
-+     - echo $DOCKER_PASSWORD
-+   secrets: [ docker_username, docker_password ]
+ steps:
+   docker:
+     image: docker
+     commands:
++      - echo $DOCKER_USERNAME
++      - echo $DOCKER_PASSWORD
++    secrets: [ docker_username, docker_password ]
 ```
 
 ### Use secrets in settings
@@ -34,12 +34,12 @@ In this example, the secret named `secret_token` would be passed to the setting
 **NOTE:** the `from_secret` syntax only works with the newer `settings` block.
 
 ```diff
-steps:
-  docker:
-    image: my-plugin
-    settings:
-+     token:
-+       from_secret: secret_token
+ steps:
+   docker:
+     image: my-plugin
+     settings:
++      token:
++        from_secret: secret_token
 ```
 
 ### Note about parameter pre-processing
@@ -47,15 +47,15 @@ steps:
 Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped.
 
 ```diff
-steps:
-  docker:
-    image: docker
-    commands:
--     - echo ${DOCKER_USERNAME}
--     - echo ${DOCKER_PASSWORD}
-+     - echo $${DOCKER_USERNAME}
-+     - echo $${DOCKER_PASSWORD}
-    secrets: [ docker_username, docker_password ]
+ steps:
+   docker:
+     image: docker
+     commands:
+-      - echo ${DOCKER_USERNAME}
+-      - echo ${DOCKER_PASSWORD}
++      - echo $${DOCKER_USERNAME}
++      - echo $${DOCKER_PASSWORD}
+     secrets: [ docker_username, docker_password ]
 ```
 
 ### Alternate Names
@@ -63,14 +63,14 @@ steps:
 There may be scenarios where you are required to store secrets using alternate names. You can map the alternate secret name to the expected name using the below syntax:
 
 ```diff
-steps:
-  docker:
-    image: plugins/docker
-    repo: octocat/hello-world
-    tags: latest
-+   secrets:
-+     - source: docker_prod_password
-+       target: docker_password
+ steps:
+   docker:
+     image: plugins/docker
+     repo: octocat/hello-world
+     tags: latest
++    secrets:
++      - source: docker_prod_password
++        target: docker_password
 ```
 
 ### Use in Pull Requests events
@@ -91,7 +91,7 @@ Secrets are added to the Woodpecker in the UI or with the CLI.
 
 Create the secret using default settings. The secret will be available to all images in your pipeline, and will be available to all push, tag, and deployment events (not pull request events).
 
-```diff
+```bash
 woodpecker-cli secret add \
   -repository octocat/hello-world \
   -name aws_access_key_id \
@@ -101,42 +101,42 @@ woodpecker-cli secret add \
 Create the secret and limit to a single image:
 
 ```diff
-woodpecker-cli secret add \
-  -repository octocat/hello-world \
-+ -image plugins/s3 \
-  -name aws_access_key_id \
-  -value <value>
+ woodpecker-cli secret add \
+   -repository octocat/hello-world \
++  -image plugins/s3 \
+   -name aws_access_key_id \
+   -value <value>
 ```
 
 Create the secrets and limit to a set of images:
 
 ```diff
-woodpecker-cli secret add \
-  -repository octocat/hello-world \
-+ -image plugins/s3 \
-+ -image peloton/woodpecker-ecs \
-  -name aws_access_key_id \
-  -value <value>
+ woodpecker-cli secret add \
+   -repository octocat/hello-world \
++  -image plugins/s3 \
++  -image peloton/woodpecker-ecs \
+   -name aws_access_key_id \
+   -value <value>
 ```
 
 Create the secret and enable for multiple hook events:
 
 ```diff
-woodpecker-cli secret add \
-  -repository octocat/hello-world \
-  -image plugins/s3 \
-+ -event pull_request \
-+ -event push \
-+ -event tag \
-  -name aws_access_key_id \
-  -value <value>
+ woodpecker-cli secret add \
+   -repository octocat/hello-world \
+   -image plugins/s3 \
++  -event pull_request \
++  -event push \
++  -event tag \
+   -name aws_access_key_id \
+   -value <value>
 ```
 
 Loading secrets from file using curl `@` syntax. This is the recommended approach for loading secrets from file to preserve newlines:
 
 ```diff
-woodpecker-cli secret add \
-  -repository octocat/hello-world \
-  -name ssh_key \
-+ -value @/root/ssh/id_rsa
+ woodpecker-cli secret add \
+   -repository octocat/hello-world \
+   -name ssh_key \
++  -value @/root/ssh/id_rsa
 ```

docs/docs/20-usage/41-registries.md

@@ -53,7 +53,7 @@ It's possible to build a local image by mounting the docker socket as a volume.
 
 With a `Dockerfile` at the root of the project:
 
-```diff
+```yaml
 steps:
   build-image:
     image: docker

docs/docs/20-usage/50-environment.md

@@ -3,43 +3,45 @@
 Woodpecker provides the ability to pass environment variables to individual pipeline steps. Note that these can't overwrite any existing, built-in variables. Example pipeline step with custom environment variables:
 
 ```diff
-steps:
-  build:
-    image: golang
-+   environment:
-+     - CGO=0
-+     - GOOS=linux
-+     - GOARCH=amd64
-    commands:
-      - go build
-      - go test
+ steps:
+   build:
+     image: golang
++    environment:
++      - CGO=0
++      - GOOS=linux
++      - GOARCH=amd64
+     commands:
+       - go build
+       - go test
 ```
 
 Please note that the environment section is not able to expand environment variables. If you need to expand variables they should be exported in the commands section.
 
 ```diff
-steps:
-  build:
-    image: golang
--   environment:
--     - PATH=$PATH:/go
-    commands:
-+     - export PATH=$PATH:/go
-      - go build
-      - go test
+ steps:
+   build:
+     image: golang
+-    environment:
+-      - PATH=$PATH:/go
+     commands:
++      - export PATH=$PATH:/go
+       - go build
+       - go test
 ```
 
-> Please be warned that `${variable}` expressions are subject to pre-processing. If you do not want the pre-processor to evaluate your expression it must be escaped:
+:::warning
+`${variable}` expressions are subject to pre-processing. If you do not want the pre-processor to evaluate your expression it must be escaped:
+:::
 
 ```diff
-steps:
-  build:
-    image: golang
-    commands:
--     - export PATH=${PATH}:/go
-+     - export PATH=$${PATH}:/go
-      - go build
-      - go test
+ steps:
+   build:
+     image: golang
+     commands:
+-      - export PATH=${PATH}:/go
++      - export PATH=$${PATH}:/go
+       - go build
+       - go test
 ```
 
 ## Built-in environment variables
@@ -139,27 +141,23 @@ This is the reference list of all environment variables available to your pipeli
 
 If you want specific environment variables to be available in all of your pipelines use the `WOODPECKER_ENVIRONMENT` setting on the Woodpecker server. Note that these can't overwrite any existing, built-in variables.
 
-```diff
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2
+```ini
+WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2
 ```
 
 These can be used, for example, to manage the image tag used by multiple projects.
 
+```ini
+WOODPECKER_ENVIRONMENT=GOLANG_VERSION:1.18
+```
+
 ```diff
-steps:
-  build:
--   image: golang:1.18
-+   image: golang:${GOLANG_VERSION}
-    commands:
-      - [...]
-    environment:
-      - [...]
-+     - WOODPECKER_ENVIRONMENT=GOLANG_VERSION:1.18
+ steps:
+   build:
+-    image: golang:1.18
++    image: golang:${GOLANG_VERSION}
+     commands:
+       - [...]
 ```
 
 ## String Substitution
@@ -169,21 +167,21 @@ Woodpecker provides the ability to substitute environment variables at runtime.
 Example commit substitution:
 
 ```diff
-steps:
-  docker:
-    image: plugins/docker
-    settings:
-+     tags: ${CI_COMMIT_SHA}
+ steps:
+   docker:
+     image: plugins/docker
+     settings:
++      tags: ${CI_COMMIT_SHA}
 ```
 
 Example tag substitution:
 
 ```diff
-steps:
-  docker:
-    image: plugins/docker
-    settings:
-+     tags: ${CI_COMMIT_TAG}
+ steps:
+   docker:
+     image: plugins/docker
+     settings:
++      tags: ${CI_COMMIT_TAG}
 ```
 
 ## String Operations
@@ -207,19 +205,19 @@ Woodpecker also emulates bash string operations. This gives us the ability to ma
 Example variable substitution with substring:
 
 ```diff
-steps:
-  docker:
-    image: plugins/docker
-    settings:
-+     tags: ${CI_COMMIT_SHA:0:8}
+ steps:
+   docker:
+     image: plugins/docker
+     settings:
++      tags: ${CI_COMMIT_SHA:0:8}
 ```
 
 Example variable substitution strips `v` prefix from `v.1.0.0`:
 
 ```diff
-steps:
-  docker:
-    image: plugins/docker
-    settings:
-+     tags: ${CI_COMMIT_TAG##v}
+ steps:
+   docker:
+     image: plugins/docker
+     settings:
++      tags: ${CI_COMMIT_TAG##v}
 ```

docs/docs/20-usage/51-plugins/_category_.yaml

@@ -4,4 +4,4 @@ collapsible: true
 collapsed: true
 link:
   type: 'doc'
-  id: 'plugins'
+  id: 'overview'

docs/docs/20-usage/60-services.md

@@ -27,15 +27,15 @@ services:
 Service containers generally expose environment variables to customize service startup such as default usernames, passwords and ports. Please see the official image documentation to learn more.
 
 ```diff
-services:
-  database:
-    image: mysql
-+   environment:
-+     - MYSQL_DATABASE=test
-+     - MYSQL_ALLOW_EMPTY_PASSWORD=yes
+ services:
+   database:
+     image: mysql
++    environment:
++      - MYSQL_DATABASE=test
++      - MYSQL_ALLOW_EMPTY_PASSWORD=yes
 
-  cache:
-    image: redis
+   cache:
+     image: redis
 ```
 
 ## Detachment
@@ -43,21 +43,21 @@ services:
 Service and long running containers can also be included in the pipeline section of the configuration using the detach parameter without blocking other steps. This should be used when explicit control over startup order is required.
 
 ```diff
-steps:
-  build:
-    image: golang
-    commands:
-      - go build
-      - go test
+ steps:
+   build:
+     image: golang
+     commands:
+       - go build
+       - go test
 
-  database:
-    image: redis
-+   detach: true
+   database:
+     image: redis
++    detach: true
 
-  test:
-    image: golang
-    commands:
-      - go test
+   test:
+     image: golang
+     commands:
+       - go test
 ```
 
 Containers from detached steps will terminate when the pipeline ends.
@@ -67,17 +67,17 @@ Containers from detached steps will terminate when the pipeline ends.
 Service containers require time to initialize and begin to accept connections. If you are unable to connect to a service you may need to wait a few seconds or implement a backoff.
 
 ```diff
-steps:
-  test:
-    image: golang
-    commands:
-+     - sleep 15
-      - go get
-      - go test
+ steps:
+   test:
+     image: golang
+     commands:
++      - sleep 15
+       - go get
+       - go test
 
-services:
-  database:
-    image: mysql
+ services:
+   database:
+     image: mysql
 ```
 
 ## Complete Pipeline Example

docs/docs/20-usage/70-volumes.md

@@ -7,21 +7,21 @@ Volumes are only available to trusted repositories and for security reasons shou
 :::
 
 ```diff
-steps:
-  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
+ steps:
+   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
 ```
 
 Please note that Woodpecker mounts volumes on the host machine. This means you must use absolute paths when you configure volumes. Attempting to use relative paths will result in an error.
 
 ```diff
-- volumes: [ ./certs:/etc/ssl/certs ]
-+ volumes: [ /etc/ssl/certs:/etc/ssl/certs ]
+-volumes: [ ./certs:/etc/ssl/certs ]
++volumes: [ /etc/ssl/certs:/etc/ssl/certs ]
 ```

docs/docs/20-usage/71-project-settings.md

@@ -6,7 +6,7 @@ As the owner of a project in Woodpecker you can change project related settings
 
 ## Pipeline path
 
-The path to the pipeline config file or folder. By default it is left empty which will use the following configuration resolution `.woodpecker/*.yml` -> `.woodpecker/*.yaml` -> `.woodpecker.yml` -> `.woodpecker.yaml`. If you set a custom path Woodpecker tries to load your configuration or fails if no configuration could be found at the specified location. To use a [multiple workflows](./25-workflows.md) with a custom path you have to change it to a folder path ending with a `/` like `.woodpecker/`.
+The path to the pipeline config file or folder. By default it is left empty which will use the following configuration resolution `.woodpecker/*.{yaml,yml}` -> `.woodpecker.yaml` -> `.woodpecker.yml`. If you set a custom path Woodpecker tries to load your configuration or fails if no configuration could be found at the specified location. To use a [multiple workflows](./25-workflows.md) with a custom path you have to change it to a folder path ending with a `/` like `.woodpecker/`.
 
 ## Repository hooks
 

docs/docs/20-usage/80-badges.md

@@ -4,7 +4,7 @@ Woodpecker has integrated support for repository status badges. These badges can
 
 ## Badge endpoint
 
-```text
+```uri
 <scheme>://<hostname>/api/badges/<repo-id>/status.svg
 ```
 

docs/docs/20-usage/90-advanced-usage.md

@@ -118,17 +118,12 @@ steps:
       - echo $FOO
 ```
 
-## Declaring global variables in `docker-compose.yml`
+## Declaring global variables
 
-As described in [Global environment variables](./50-environment.md#global-environment-variables), one can define global variables:
+As described in [Global environment variables](./50-environment.md#global-environment-variables), you can define global variables:
 
-```yaml
-services:
-  woodpecker-server:
-    # ...
-    environment:
-      - WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2
-      # ...
+```ini
+WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2
 ```
 
 Note that this tightly couples the server and app configurations (where the app is a completely separate application). But this is a good option for truly global variables which should apply to all steps in all pipelines for all apps.

docs/docs/30-administration/00-deployment/10-docker-compose.md

@@ -4,7 +4,7 @@ The below [docker-compose](https://docs.docker.com/compose/) configuration can b
 
 It relies on a number of environment variables that you must set before running `docker-compose up`. The variables are described below.
 
-```yaml title="docker-compose.yml"
+```yaml title="docker-compose.yaml"
 version: '3'
 
 services:
@@ -42,85 +42,85 @@ volumes:
 
 Woodpecker needs to know its own address. You must therefore provide the public address of it in `<scheme>://<hostname>` format. Please omit trailing slashes:
 
-```diff title="docker-compose.yml"
-version: '3'
+```diff title="docker-compose.yaml"
+ version: '3'
 
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_HOST=${WOODPECKER_HOST}
+ services:
+   woodpecker-server:
+     [...]
+     environment:
+       - [...]
++      - WOODPECKER_HOST=${WOODPECKER_HOST}
 ```
 
 Woodpecker can also have its port's configured. It uses a separate port for gRPC and for HTTP. The agent performs gRPC calls and connects to the gRPC port.
-They can be configured with ADDR variables:
+They can be configured with `*_ADDR` variables:
 
-```diff title="docker-compose.yml"
-version: '3'
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR}
-+     - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR}
+```diff title="docker-compose.yaml"
+ version: '3'
+ services:
+   woodpecker-server:
+     [...]
+     environment:
+       - [...]
++      - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR}
++      - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR}
 ```
 
 Reverse proxying can also be [configured for gRPC](../proxy#caddy). If the agents are connecting over the internet, it should also be SSL encrypted. The agent then needs to be configured to be secure:
 
-```diff title="docker-compose.yml"
-version: '3'
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_GRPC_SECURE=true # defaults to false
-+     - WOODPECKER_GRPC_VERIFY=true # default
+```diff title="docker-compose.yaml"
+ version: '3'
+ services:
+   woodpecker-server:
+     [...]
+     environment:
+       - [...]
++      - WOODPECKER_GRPC_SECURE=true # defaults to false
++      - WOODPECKER_GRPC_VERIFY=true # default
 ```
 
 As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon:
 
-```diff title="docker-compose.yml"
-version: '3'
+```diff title="docker-compose.yaml"
+ version: '3'
 
-services:
-  [...]
-  woodpecker-agent:
-    [...]
-+   volumes:
-+     - /var/run/docker.sock:/var/run/docker.sock
+ services:
+   [...]
+   woodpecker-agent:
+     [...]
++    volumes:
++      - /var/run/docker.sock:/var/run/docker.sock
 ```
 
 Agents require the server address for agent-to-server communication. The agent connects to the server's gRPC port:
 
-```diff title="docker-compose.yml"
-version: '3'
+```diff title="docker-compose.yaml"
+ version: '3'
 
-services:
-  woodpecker-agent:
-    [...]
-    environment:
-+     - WOODPECKER_SERVER=woodpecker-server:9000
+ services:
+   woodpecker-agent:
+     [...]
+     environment:
++      - WOODPECKER_SERVER=woodpecker-server:9000
 ```
 
 The server and agents use a shared secret to authenticate communication. This should be a random string of your choosing and should be kept private. You can generate such string with `openssl rand -hex 32`:
 
-```diff title="docker-compose.yml"
-version: '3'
+```diff title="docker-compose.yaml"
+ version: '3'
 
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
-  woodpecker-agent:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
+ services:
+   woodpecker-server:
+     [...]
+     environment:
+       - [...]
++      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
+   woodpecker-agent:
+     [...]
+     environment:
+       - [...]
++      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
 ```
 
 ## Docker images
@@ -130,7 +130,7 @@ Image variants:
 - The `latest` image is the latest stable release
 - The `vX.X.X` images are stable releases
 - The `vX.X` images are based on the current release branch (e.g. `release/v1.0`) and can be used to get bugfixes asap
-- The `next` images are based on the current `main` branch and should not be used for production environments
+- The `next` images are based on the current `main` branch
 
 ```bash
 # server

docs/docs/30-administration/10-server-config.md

@@ -12,63 +12,36 @@ Registration is closed by default (`WOODPECKER_OPEN=false`). If registration is
 
 To open registration:
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_OPEN=true
+```ini
+WOODPECKER_OPEN=true
 ```
 
-You can **also restrict** registration, by keep registration closed and ...\
-... **adding** new **users manually** via the CLI: `woodpecker-cli user add`, or\
-... allowing specific **admin users** via the `WOODPECKER_ADMIN` setting, or\
-by open registration and **filter by organization** membership through the `WOODPECKER_ORGS` setting.
+You can **also restrict** registration, by keep registration closed and:
 
-### To close registration, but allow specific admin users
+- **adding** new **users manually** via the CLI: `woodpecker-cli user add`
+- allowing specific **admin users** via the `WOODPECKER_ADMIN` setting
+- by open registration and **filter by organization** membership through the `WOODPECKER_ORGS` setting
 
-```diff title="docker-compose.yml"
-version: '3'
+### Close registration, but allow specific admin users
 
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_OPEN=false
-+     - WOODPECKER_ADMIN=johnsmith,janedoe
+```ini
+WOODPECKER_OPEN=false
+WOODPECKER_ADMIN=johnsmith,janedoe
 ```
 
-### To only allow registration of users, who are members of approved organizations
+### Only allow registration of users, who are members of approved organizations
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_OPEN=true
-+     - WOODPECKER_ORGS=dolores,dogpatch
+```ini
+WOODPECKER_OPEN=true
+WOODPECKER_ORGS=dolores,dogpatch
 ```
 
 ## Administrators
 
 Administrators should also be enumerated in your configuration.
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_ADMIN=johnsmith,janedoe
+```ini
+WOODPECKER_ADMIN=johnsmith,janedoe
 ```
 
 ## Filtering repositories
@@ -77,15 +50,8 @@ Woodpecker operates with the user's OAuth permission. Due to the coarse permissi
 
 Use the `WOODPECKER_REPO_OWNERS` variable to filter which GitHub user's repos should be synced only. You typically want to put here your company's GitHub name.
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_REPO_OWNERS=mycompany,mycompanyossgithubuser
+```ini
+WOODPECKER_REPO_OWNERS=mycompany,mycompanyossgithubuser
 ```
 
 ## Global registry setting
@@ -93,67 +59,62 @@ services:
 If you want to make available a specific private registry to all pipelines, use the `WOODPECKER_DOCKER_CONFIG` server configuration.
 Point it to your server's docker config.
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    volumes:
-      - [...]
-+     - /home/user/.docker/config.json:/root/.docker/config.json:ro
-    environment:
-      - [...]
-+     - WOODPECKER_DOCKER_CONFIG=/root/.docker/config.json
+```ini
+WOODPECKER_DOCKER_CONFIG=/root/.docker/config.json
 ```
 
 ## Handling sensitive data in docker-compose and docker-swarm
 
 To handle sensitive data in docker-compose or docker-swarm configurations there are several options:
 
-For docker-compose you can use a .env file next to your compose configuration to store the secrets outside of the compose file. While this separates configuration from secrets it is still not very secure.
+For docker-compose you can use a `.env` file next to your compose configuration to store the secrets outside of the compose file. While this separates configuration from secrets it is still not very secure.
 
 Alternatively use docker-secrets. As it may be difficult to use docker secrets for environment variables woodpecker allows to read sensible data from files by providing a `*_FILE` option of all sensible configuration variables. Woodpecker will try to read the value directly from this file. Keep in mind that when the original environment variable gets specified at the same time it will override the value read from the file.
 
-```diff title="docker-compose.yml"
-version: '3'
+```diff title="docker-compose.yaml"
+ version: '3'
 
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_AGENT_SECRET_FILE=/run/secrets/woodpecker-agent-secret
-+   secrets:
-+     - woodpecker-agent-secret
+ services:
+   woodpecker-server:
+     [...]
+     environment:
+       - [...]
++      - WOODPECKER_AGENT_SECRET_FILE=/run/secrets/woodpecker-agent-secret
++    secrets:
++      - woodpecker-agent-secret
 +
-+secrets:
-+  woodpecker-agent-secret:
-+    external: true
++ secrets:
++   woodpecker-agent-secret:
++     external: true
 ```
 
 Store a value to a docker secret like this:
-`echo "my_agent_secret_key" | docker secret create woodpecker-agent-secret -`
+
+```bash
+echo "my_agent_secret_key" | docker secret create woodpecker-agent-secret -
+```
 
 or generate a random one like this:
 
-`openssl rand -hex 32 | docker secret create woodpecker-agent-secret -`
+```bash
+openssl rand -hex 32 | docker secret create woodpecker-agent-secret -
+```
 
-## Custom Javascript and CSS Styling (a.k.a. white-labeling)
+## Custom JavaScript and CSS
 
-Woodpecker supports custom styling of the Web UI by providing custom JS and CSS files.
+Woodpecker supports custom JS and CSS files.
 These files must be present in the server's filesystem.
 They can be backed in a Docker image or mounted from a ConfigMap inside a Kubernetes environment.
 The configuration variables are independent of each other, which means it can be just one file present, or both.
 
-```text
+```ini
 WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.css
-WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.js
+WOODPECKER_CUSTOM_JS_FILE=/usr/local/www/woodpecker.js
 ```
 
 The examples below show how to place a banner message in the top navigation bar of Woodpecker.
 
-### woodpecker.css
+### `woodpecker.css`
 
 ```css
 .banner-message {
@@ -169,7 +130,7 @@ The examples below show how to place a banner message in the top navigation bar
 }
 ```
 
-### woodpecker.js
+### `woodpecker.js`
 
 ```javascript
 // place/copy a minified version of jQuery or ZeptoJS here ...
@@ -532,7 +493,7 @@ Supported variables:
 - `owner`: the repo's owner
 - `repo`: the repo's name
 
-### WOODPECKER_ADDONS
+### `WOODPECKER_ADDONS`
 
 > Default: empty
 

docs/docs/30-administration/100-external-configuration-api.md

@@ -13,9 +13,7 @@ You need to trust the external config service as it is getting secret informatio
 
 ## Config
 
-```bash
-# Server
-# ...
+```ini title="Server"
 WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig
 ```
 
@@ -85,8 +83,8 @@ WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig
   },
   "configs": [
     {
-      "name": ".woodpecker.yml",
-      "data": "steps:\n  backend:\n    image: alpine\n    commands:\n      - echo \"Hello there from Repo (.woodpecker.yml)\"\n"
+      "name": ".woodpecker.yaml",
+      "data": "steps:\n  backend:\n    image: alpine\n    commands:\n      - echo \"Hello there from Repo (.woodpecker.yaml)\"\n"
     }
   ]
 }

docs/docs/30-administration/11-forges/20-github.md

@@ -3,7 +3,7 @@
 Woodpecker comes with built-in support for GitHub and GitHub Enterprise.
 To use Woodpecker with GitHub the following environment variables should be set for the server component:
 
-```bash
+```ini
 WOODPECKER_GITHUB=true
 WOODPECKER_GITHUB_CLIENT=YOUR_GITHUB_CLIENT_ID
 WOODPECKER_GITHUB_SECRET=YOUR_GITHUB_CLIENT_SECRET

docs/docs/30-administration/11-forges/30-gitea.md

@@ -2,24 +2,14 @@
 
 Woodpecker comes with built-in support for Gitea and the "soft" fork Forgejo. To enable Gitea you should configure the Woodpecker container using the following environment variables:
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_GITEA=true
-+     - WOODPECKER_GITEA_URL=${WOODPECKER_GITEA_URL}
-+     - WOODPECKER_GITEA_CLIENT=${WOODPECKER_GITEA_CLIENT}
-+     - WOODPECKER_GITEA_SECRET=${WOODPECKER_GITEA_SECRET}
-
-  woodpecker-agent:
-    [...]
+```ini
+WOODPECKER_GITEA=true
+WOODPECKER_GITEA_URL=YOUR_GITEA_URL
+WOODPECKER_GITEA_CLIENT=YOUR_GITEA_CLIENT
+WOODPECKER_GITEA_SECRET=YOUR_GITEA_CLIENT_SECRET
 ```
 
-## Gitea on the same host
+## Gitea on the same host with containers
 
 If you have Gitea also running on the same host within a container, make sure the agent does have access to it.
 The agent tries to clone using the URL which Gitea reports through its API. For simplified connectivity, you should add the woodpecker agent to the same docker network as Gitea is in.
@@ -27,16 +17,16 @@ Otherwise, the communication should go via the `docker0` gateway (usually 172.17
 
 To configure the Docker network if the network's name is `gitea`, configure it like this:
 
-```diff title="docker-compose.yml"
-version: '3'
+```diff title="docker-compose.yaml"
+ version: '3'
 
-services:
-  [...]
-  woodpecker-agent:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_BACKEND_DOCKER_NETWORK=gitea
+ services:
+   [...]
+   woodpecker-agent:
+     [...]
+     environment:
+       - [...]
++      - WOODPECKER_BACKEND_DOCKER_NETWORK=gitea
 ```
 
 ## Registration
@@ -46,7 +36,6 @@ Register your application with Gitea to create your client id and secret. You ca
 If you run the Woodpecker CI server on the same host as the Gitea instance, you might also need to allow local connections in Gitea, since version `v1.16`. Otherwise webhooks will fail. Add the following lines to your Gitea configuration (usually at `/etc/gitea/conf/app.ini`).
 
 ```ini
-...
 [webhook]
 ALLOWED_HOST_LIST=external,loopback
 ```

docs/docs/30-administration/11-forges/40-gitlab.md

@@ -2,20 +2,11 @@
 
 Woodpecker comes with built-in support for the GitLab version 8.2 and higher. To enable GitLab you should configure the Woodpecker container using the following environment variables:
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    environment:
-+     - WOODPECKER_GITLAB=true
-+     - WOODPECKER_GITLAB_URL=http://gitlab.mycompany.com
-+     - WOODPECKER_GITLAB_CLIENT=95c0282573633eb25e82
-+     - WOODPECKER_GITLAB_SECRET=30f5064039e6b359e075
-
-  woodpecker-agent:
-    [...]
+```ini
+WOODPECKER_GITLAB=true
+WOODPECKER_GITLAB_URL=http://gitlab.mycompany.com
+WOODPECKER_GITLAB_CLIENT=95c0282573633eb25e82
+WOODPECKER_GITLAB_SECRET=30f5064039e6b359e075
 ```
 
 ## Registration

docs/docs/30-administration/11-forges/50-bitbucket.md

@@ -2,20 +2,10 @@
 
 Woodpecker comes with built-in support for Bitbucket Cloud. To enable Bitbucket Cloud you should configure the Woodpecker container using the following environment variables:
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-+     - WOODPECKER_BITBUCKET=true
-+     - WOODPECKER_BITBUCKET_CLIENT=... # called "Key" in Bitbucket
-+     - WOODPECKER_BITBUCKET_SECRET=...
-
-  woodpecker-agent:
-    [...]
+```ini
+WOODPECKER_BITBUCKET=true
+WOODPECKER_BITBUCKET_CLIENT=... # called "Key" in Bitbucket
+WOODPECKER_BITBUCKET_SECRET=...
 ```
 
 ## Registration
@@ -24,7 +14,7 @@ You must register an OAuth application at Bitbucket in order to get a key and se
 
 Please set a name and set the `Callback URL` like this:
 
-```nohighlight
+```uri
 https://<your-woodpecker-address>/authorize
 ```
 
@@ -32,14 +22,12 @@ https://<your-woodpecker-address>/authorize
 
 Please also be sure to check the following permissions:
 
-```nohighlight
-Account: Email, Read
-Workspace membership: Read
-Projects: Read
-Repositories: Read
-Pull requests: Read
-Webhooks: Read and Write
-```
+- Account: Email, Read
+- Workspace membership: Read
+- Projects: Read
+- Repositories: Read
+- Pull requests: Read
+- Webhooks: Read and Write
 
 ![bitbucket permissions](bitbucket_permissions.png)
 
@@ -79,5 +67,5 @@ Read the value for `WOODPECKER_BITBUCKET_SECRET` from the specified filepath
 
 ## Missing Features
 
-Merge requests are not currently supported. We are interested in patches to include this functionality.
+Path filters for pull requests are not supported. We are interested in patches to include this functionality.
 If you are interested in contributing to Woodpecker and submitting a patch please **contact us** via [Discord](https://discord.gg/fcMQqSMXJy) or [Matrix](https://matrix.to/#/#WoodpeckerCI-Develop:obermui.de).

docs/docs/30-administration/15-agent-config.md

@@ -6,38 +6,24 @@ toc_max_heading_level: 2
 
 Agents are configured by the command line or environment variables. At the minimum you need the following information:
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-agent:
-    [...]
-    volumes:
-      - woodpecker-agent-config:/etc/woodpecker
-    environment:
-+     - WOODPECKER_SERVER=localhost:9000
-+     - WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
+```ini
+WOODPECKER_SERVER=localhost:9000
+WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
 ```
 
 The following are automatically set and can be overridden:
 
-- WOODPECKER_HOSTNAME if not set, becomes the OS' hostname
-- WOODPECKER_MAX_WORKFLOWS if not set, defaults to 1
+- `WOODPECKER_HOSTNAME` if not set, becomes the OS' hostname
+- `WOODPECKER_MAX_WORKFLOWS` if not set, defaults to 1
 
 ## Workflows per agent
 
 By default, the maximum workflows that are executed in parallel on an agent is 1. If required, you can add `WOODPECKER_MAX_WORKFLOWS` to increase your parallel processing for an agent.
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-agent:
-  [...]
-  environment:
-    - WOODPECKER_SERVER=localhost:9000
-    - WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
-+   - WOODPECKER_MAX_WORKFLOWS=4
+```ini
+WOODPECKER_SERVER=localhost:9000
+WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here"
+WOODPECKER_MAX_WORKFLOWS=4
 ```
 
 ## Agent registration
@@ -182,7 +168,7 @@ Configures if the gRPC server certificate should be verified, only valid when `W
 
 Configures the backend engine to run pipelines on. Possible values are `auto-detect`, `docker`, `local` or `kubernetes`.
 
-### WOODPECKER_ADDONS
+### `WOODPECKER_ADDONS`
 
 > Default: empty
 

docs/docs/30-administration/22-backends/10-docker.md

@@ -22,14 +22,12 @@ RUN apk add -U --no-cache docker-credential-ecr-login
 
 While the agent was developed with Docker/Moby, Podman can also be used by setting the environment variable `DOCKER_HOST` to point to the Podman socket. In order to work without workarounds, Podman 4.0 (or above) is required.
 
-## Image Cleanup
+## Image cleanup
 
 The agent **will not** automatically remove images from the host. This task should be managed by the host system. For example, you can use a cron job to periodically do clean-up tasks for the CI runner.
 
 :::danger
-
 The following commands **are destructive** and **irreversible** it is highly recommended that you test these commands on your system before running them in production via a cron job or other automation.
-
 :::
 
 ### Remove all unused images
@@ -38,7 +36,7 @@ The following commands **are destructive** and **irreversible** it is highly rec
 docker image rm $(docker images --filter "dangling=true" -q --no-trunc)
 ```
 
-### Remove Woodpecker Volumes
+### Remove Woodpecker volumes
 
 ```bash
 docker volume rm $(docker volume ls --filter name=^wp_* --filter dangling=true  -q)

docs/docs/30-administration/22-backends/20-local.md

@@ -29,65 +29,29 @@ In order to use this backend, you need to download (or build) the
 [binary](https://github.com/woodpecker-ci/woodpecker/releases/latest) of the
 agent, configure it and run it on the host machine.
 
-## Configuration
+## Usage
 
-### Server
-
-Enable connection to the server from the outside of the docker environment by
-exposing the port 9000:
-
-```yaml title="docker-compose.yml" for the server
-version: '3'
-
-services:
-  woodpecker-server:
-  [...]
-    ports:
-      - 9000:9000
-      [...]
-    environment:
-      - [...]
-```
-
-### Agent
-
-You can use the `.env` file to store environmental variables for configuration.
-At the minimum you need the following information:
+To enable the local backend, add this to your configuration:
 
 ```ini
-# .env for the agent
-WOODPECKER_AGENT_SECRET=replace_with_your_server_secret
-WOODPECKER_SERVER=replace_with_your_server_address:9000
+WOODPECKER_BACKEND=local
 ```
 
-## Running the agent
-
-Start the agent from the directory with the `.env` file:
-
-`woodpecker-agent`
-
-:::note
-When using the `local` backend, the
-[plugin-git](https://github.com/woodpecker-ci/plugin-git) binary must be in
-your `$PATH` for the default clone step to work. If not, you can still write a
-manual clone step.
-:::
-
-## Further configuration
-
-### Specify the shell to be used for a pipeline step
+### Shell
 
 The `image` entry is used to specify the shell, such as Bash or Fish, that is
 used to run the commands.
 
-```yaml title=".woodpecker.yml"
+```yaml title=".woodpecker.yaml"
 steps:
   build:
     image: bash
     commands: [...]
 ```
 
-### Plugins as Executable Binaries
+### Plugins
+
+Plugins are just executable binaries:
 
 ```yaml
 steps:
@@ -98,35 +62,10 @@ steps:
 If no commands are provided, we treat them as plugins in the usual manner.
 In the context of the local backend, plugins are simply executable binaries, which can be located using their name if they are listed in `$PATH`, or through an absolute path.
 
-### Using labels to filter tasks
+### Options
 
-You can use the [agent configuration options](../15-agent-config.md#woodpecker_filter_labels)
-and the [pipeline syntax](../../20-usage/20-workflow-syntax.md#labels) to only run certain
-pipelines on certain agents. Example:
+#### `WOODPECKER_BACKEND_LOCAL_TEMP_DIR`
 
-Define a `label` `type` with value `exec` for a particular agent:
+> Default: default temp directory
 
-```ini
-# .env for the agent
-
-WOODPECKER_FILTER_LABELS=type=exec
-```
-
-Then, use this `label` `type` with value `exec` in the pipeline definition, to
-only run on this agent:
-
-```yaml title=".woodpecker.yml"
-labels:
-  type: exec
-
-steps: [...]
-```
-
-### Change temp directory
-
-We use the default temp directory to create folders for workflows.
-This directory can be changed by:
-
-```env
-WOODPECKER_BACKEND_LOCAL_TEMP_DIR=/some/other/dir
-```
+Directory to create folders for workflows.

docs/docs/30-administration/22-backends/40-kubernetes.md

@@ -32,12 +32,12 @@ steps:
             cpu: 1000m
 ```
 
-### serviceAccountName
+### `serviceAccountName`
 
 Specify the name of the ServiceAccount which the build pod will mount. This serviceAccount must be created externally.
 See the [kubernetes documentation](https://kubernetes.io/docs/concepts/security/service-accounts/) for more information on using serviceAccounts.
 
-### nodeSelector
+### `nodeSelector`
 
 Specifies the label which is used to select the node on which the job will be executed.
 
@@ -66,7 +66,7 @@ And then overwrite the `nodeSelector` in the `backend_options` section of the st
           kubernetes.io/arch: "${ARCH}"
 ```
 
-### tolerations
+### `tolerations`
 
 When you use nodeSelector and the node pool is configured with Taints, you need to specify the Tolerations. Tolerations allow the scheduler to schedule pods with matching taints.
 See the [kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for more information on using tolerations.

docs/docs/30-administration/30-database.md

@@ -4,16 +4,16 @@ The default database engine of Woodpecker is an embedded SQLite database which r
 
 ## Configure SQLite
 
-By default Woodpecker uses a SQLite database stored under `/var/lib/woodpecker/`. You can mount a [data volume](https://docs.docker.com/storage/volumes/#create-and-manage-volumes) to persist the SQLite database.
+By default Woodpecker uses a SQLite database stored under `/var/lib/woodpecker/`. If using containers, you can mount a [data volume](https://docs.docker.com/storage/volumes/#create-and-manage-volumes) to persist the SQLite database.
 
-```diff title="docker-compose.yml"
-version: '3'
+```diff title="docker-compose.yaml"
+ version: '3'
 
-services:
-  woodpecker-server:
-    [...]
-+   volumes:
-+     - woodpecker-server-data:/var/lib/woodpecker/
+ services:
+   woodpecker-server:
+     [...]
++    volumes:
++      - woodpecker-server-data:/var/lib/woodpecker/
 ```
 
 ## Configure MySQL/MariaDB
@@ -21,15 +21,9 @@ services:
 The below example demonstrates MySQL database configuration. See the official driver [documentation](https://github.com/go-sql-driver/mysql#dsn-data-source-name) for configuration options and examples.
 The minimum version of MySQL/MariaDB required is determined by the `go-sql-driver/mysql` - see [it's README](https://github.com/go-sql-driver/mysql#requirements) for more information.
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    environment:
-+     - WOODPECKER_DATABASE_DRIVER=mysql
-+     - WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true
+```ini
+WOODPECKER_DATABASE_DRIVER=mysql
+WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true
 ```
 
 ## Configure Postgres
@@ -37,20 +31,14 @@ services:
 The below example demonstrates Postgres database configuration. See the official driver [documentation](https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING) for configuration options and examples.
 Please use Postgres versions equal or higher than **11**.
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    environment:
-+     - WOODPECKER_DATABASE_DRIVER=postgres
-+     - WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/postgres?sslmode=disable
+```ini
+WOODPECKER_DATABASE_DRIVER=postgres
+WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/postgres?sslmode=disable
 ```
 
 ## Database Creation
 
-Woodpecker does not create your database automatically. If you are using the MySQL or Postgres driver you will need to manually create your database using `CREATE DATABASE`
+Woodpecker does not create your database automatically. If you are using the MySQL or Postgres driver you will need to manually create your database using `CREATE DATABASE`.
 
 ## Database Migration
 

docs/docs/30-administration/60-ssl.md

@@ -9,20 +9,9 @@ Woodpecker supports automated SSL configuration and updates using Let's Encrypt.
 
 You can enable Let's Encrypt by making the following modifications to your server configuration:
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    ports:
-+     - 80:80
-+     - 443:443
-      - 9000:9000
-    environment:
-      - [...]
-+     - WOODPECKER_LETS_ENCRYPT=true
-+     - WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld
+```ini
+WOODPECKER_LETS_ENCRYPT=true
+WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld
 ```
 
 Note that Woodpecker uses the hostname from the `WOODPECKER_HOST` environment variable when requesting certificates. For example, if `WOODPECKER_HOST=https://example.com` is set the certificate is requested for `example.com`. To receive emails before certificates expire Let's Encrypt requires an email address. You can set it with `WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld`.
@@ -43,74 +32,9 @@ Woodpecker uses the official Go acme library which will handle certificate upgra
 
 Woodpecker supports SSL configuration by mounting certificates into your container.
 
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    ports:
-+     - 80:80
-+     - 443:443
-      - 9000:9000
-    volumes:
-+     - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt
-+     - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key
-    environment:
-      - [...]
-+     - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
-+     - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key
-```
-
-Update your configuration to expose the following ports:
-
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    ports:
-+     - 80:80
-+     - 443:443
-      - 9000:9000
-```
-
-Update your configuration to mount your certificate and key:
-
-```diff title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    ports:
-      - 80:80
-      - 443:443
-      - 9000:9000
-    volumes:
-+     - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt
-+     - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key
-```
-
-Update your configuration to provide the paths of your certificate and key:
-
-```yaml title="docker-compose.yml"
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    ports:
-      - 80:80
-      - 443:443
-      - 9000:9000
-    volumes:
-      - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt
-      - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key
-    environment:
-+     - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
-+     - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key
+```ini
+WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
+WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key
 ```
 
 ### Certificate Chain
@@ -122,3 +46,45 @@ The most common problem encountered is providing a certificate file without the
 ### Certificate Errors
 
 SSL support is provided using the [ListenAndServeTLS](https://golang.org/pkg/net/http/#ListenAndServeTLS) function from the Go standard library. If you receive certificate errors or warnings please examine your configuration more closely.
+
+### Running in containers
+
+Update your configuration to expose the following ports:
+
+```diff title="docker-compose.yaml"
+ version: '3'
+
+ services:
+   woodpecker-server:
+     [...]
+     ports:
++      - 80:80
++      - 443:443
+       - 9000:9000
+```
+
+Update your configuration to mount your certificate and key:
+
+```diff title="docker-compose.yaml"
+ version: '3'
+
+ services:
+   woodpecker-server:
+     [...]
+     volumes:
++      - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt
++      - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key
+```
+
+Update your configuration to provide the paths of your certificate and key:
+
+```yaml title="docker-compose.yaml"
+ version: '3'
+
+ services:
+   woodpecker-server:
+     [...]
+     environment:
++      - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
++      - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key
+```

docs/docs/30-administration/70-proxy.md

@@ -13,22 +13,20 @@ ProxyPass / http://127.0.0.1:8000/
 ProxyPassReverse / http://127.0.0.1:8000/
 ```
 
-You must have the below Apache modules installed.
+You must have these Apache modules installed:
 
-```nohighlight
-a2enmod proxy
-a2enmod proxy_http
-```
+- `proxy`
+- `proxy_http`
 
 You must configure Apache to set `X-Forwarded-Proto` when using https.
 
 ```diff
-ProxyPreserveHost On
+ ProxyPreserveHost On
 
 +RequestHeader set X-Forwarded-Proto "https"
 
-ProxyPass / http://127.0.0.1:8000/
-ProxyPassReverse / http://127.0.0.1:8000/
+ ProxyPass / http://127.0.0.1:8000/
+ ProxyPassReverse / http://127.0.0.1:8000/
 ```
 
 ## Nginx
@@ -60,22 +58,22 @@ server {
 You must configure the proxy to set `X-Forwarded` proxy headers:
 
 ```diff
-server {
-    listen 80;
-    server_name woodpecker.example.com;
+ server {
+     listen 80;
+     server_name woodpecker.example.com;
 
-    location / {
-+       proxy_set_header X-Forwarded-For $remote_addr;
-+       proxy_set_header X-Forwarded-Proto $scheme;
+     location / {
++        proxy_set_header X-Forwarded-For $remote_addr;
++        proxy_set_header X-Forwarded-Proto $scheme;
 
-        proxy_pass http://127.0.0.1:8000;
-        proxy_redirect off;
-        proxy_http_version 1.1;
-        proxy_buffering off;
+         proxy_pass http://127.0.0.1:8000;
+         proxy_redirect off;
+         proxy_http_version 1.1;
+         proxy_buffering off;
 
-        chunked_transfer_encoding off;
-    }
-}
+         chunked_transfer_encoding off;
+     }
+ }
 ```
 
 ## Caddy
@@ -95,7 +93,7 @@ woodpeckeragent.example.com {
 ```
 
 :::note
-Above configuration shows how to create reverse-proxies for web and agent communication. If your agent uses SSL do not forget to enable [WOODPECKER_GRPC_SECURE](./15-agent-config.md#woodpecker_grpc_secure).
+Above configuration shows how to create reverse-proxies for web and agent communication. If your agent uses SSL do not forget to enable [`WOODPECKER_GRPC_SECURE`](./15-agent-config.md#woodpecker_grpc_secure).
 :::
 
 ## Tunnelmole
@@ -118,7 +116,7 @@ http://bvdo5f-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:8000
 https://bvdo5f-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:8000
 ```
 
-Set `WOODPECKER_HOST` (for example in `docker-compose.yml`) to the Tunnelmole URL (`xxx.tunnelmole.net`) and start the server.
+Set `WOODPECKER_HOST` to the Tunnelmole URL (`xxx.tunnelmole.net`) and start the server.
 
 ## Ngrok
 
@@ -128,7 +126,7 @@ Set `WOODPECKER_HOST` (for example in `docker-compose.yml`) to the Tunnelmole UR
 ngrok http 8000
 ```
 
-Set `WOODPECKER_HOST` (for example in `docker-compose.yml`) to the ngrok URL (usually xxx.ngrok.io) and start the server.
+Set `WOODPECKER_HOST` to the ngrok URL (usually xxx.ngrok.io) and start the server.
 
 ## Traefik
 

docs/docs/30-administration/75-addons/00-overview.md

@@ -23,22 +23,15 @@ Addons can be used for:
 
 Addons are restricted by how Go plugins work. This includes the following restrictions:
 
-- only supported on Linux, FreeBSD and macOS
+- only supported on Linux, FreeBSD, and macOS
 - addons must have been built for the correct Woodpecker version. If an addon is not provided specifically for this version, you likely won't be able to use it.
 
 ## Usage
 
 To use an addon, download the addon version built for your Woodpecker version. Then, you can add the following to your configuration:
 
-```diff
-# docker-compose.yml
-version: '3'
-
-services:
-  woodpecker-server:
-    [...]
-    environment:
-+     - WOODPECKER_ADDONS=/path/to/your/addon/file.so
+```ini
+WOODPECKER_ADDONS=/path/to/your/addon/file.so
 ```
 
 In case you run Woodpecker as container, you probably want to mount the addon binaries to `/opt/addons/`.

docs/docs/30-administration/75-addons/20-creating-addons.md

@@ -8,7 +8,7 @@ An addon consists of two variables/functions in Go.
 
 1. The `Type` variable. Specifies the type of the addon and must be directly accessed from `shared/addons/types/types.go`.
 2. The `Addon` function which is the main point of your addon.
-   This function takes the zerolog logger you should use to log errors, warnings etc. as argument.
+   This function takes the `zerolog` logger you should use to log errors, warnings, etc. as argument.
 
    It returns two values:
 
@@ -23,11 +23,22 @@ Directly import Woodpecker's Go package (`go.woodpecker-ci.org/woodpecker/woodpe
 | -------------------- | -------------------------------------------------------------------------------- |
 | `Forge`              | `"go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/forge".Forge`             |
 | `Backend`            | `"go.woodpecker-ci.org/woodpecker/woodpecker/v2/pipeline/backend/types".Backend` |
-| `ConfigService`      | `"go.woodpecker-ci.org/woodpecker/v2/server/plugins/config".ConfigService`       |
+| `ConfigService`      | `"go.woodpecker-ci.org/woodpecker/v2/server/plugins/config".Extension`           |
 | `SecretService`      | `"go.woodpecker-ci.org/woodpecker/v2/server/model".SecretService`                |
 | `EnvironmentService` | `"go.woodpecker-ci.org/woodpecker/v2/server/model".EnvironmentService`           |
 | `RegistryService`    | `"go.woodpecker-ci.org/woodpecker/v2/server/model".RegistryService`              |
 
+### Using configurations
+
+If you write a plugin for the server (`Forge` and the services), you can access the server config.
+
+Therefore, use the `"go.woodpecker-ci.org/woodpecker/v2/server".Config` variable.
+
+:::warning
+The config is not available when your addon is initialized, i.e., the `Addon` function is called.
+Only use the config in the interface methods.
+:::
+
 ## Compiling
 
 After you write your addon code, compile your addon:
@@ -36,23 +47,25 @@ After you write your addon code, compile your addon:
 go build -buildmode plugin
 ```
 
-The output file is your addon which is now ready to be used.
+The output file is your addon that is now ready to be used.
 
 ## Restrictions
 
 Addons must directly depend on Woodpecker's core (`go.woodpecker-ci.org/woodpecker/woodpecker/v2`).
-The addon must have been built with **excatly the same code** as the Woodpecker instance you'd like to use it on. This means: If you build your addon with a specific commit from Woodpecker `next`, you can likely only use it with the Woodpecker version compiled from this commit.
-Also, if you change something inside of Woodpecker without committing, it might fail because you need to recompile your addon with this code first.
+The addon must have been built with **exactly the same code** as the Woodpecker instance you'd like to use it on. This means: If you build your addon with a specific commit from Woodpecker `next`, you can likely only use it with the Woodpecker version compiled from this commit.
+Also, if you change something inside Woodpecker without committing, it might fail because you need to recompile your addon with this code first.
 
-In addition to this, addons are only supported on Linux, FreeBSD and macOS.
+In addition to this, addons are only supported on Linux, FreeBSD, and macOS.
 
 :::info
-It is recommended to at least support the latest released version of Woodpecker.
+It is recommended to at least support the latest version of Woodpecker.
 :::
 
 ### Compile for different versions
 
-As long as there are no changes to Woodpecker's interfaces or they are backwards-compatible, you can easily compile the addon for multiple version by changing the version of `go.woodpecker-ci.org/woodpecker/woodpecker/v2` using `go get` before compiling.
+As long as there are no changes to Woodpecker's interfaces,
+or they are backwards-compatible, you can compile the addon for multiple versions
+by changing the version of `go.woodpecker-ci.org/woodpecker/woodpecker/v2` using `go get` before compiling.
 
 ## Logging
 
@@ -68,10 +81,10 @@ import (
   "net/http"
 
   "github.com/rs/zerolog"
-  "go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/forge"
-  forge_types "go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/forge/types"
-  "go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/model"
-  addon_types "go.woodpecker-ci.org/woodpecker/woodpecker/v2/shared/addon/types"
+  "go.woodpecker-ci.org/woodpecker/v2/server/forge"
+  forge_types "go.woodpecker-ci.org/woodpecker/v2/server/forge/types"
+  "go.woodpecker-ci.org/woodpecker/v2/server/model"
+  addon_types "go.woodpecker-ci.org/woodpecker/v2/shared/addon/types"
 )
 
 var Type = addon_types.TypeForge
@@ -85,5 +98,5 @@ type config struct {
   l zerolog.Logger
 }
 
-// ... in this case, `config` must implement `forge.Forge`. You must directly use Woodpecker's packages - see imports above.
+// In this case, `config` must implement `forge.Forge`. You must directly use Woodpecker's packages - see imports above.
 ```

docs/docs/30-administration/80-autoscaler.md

@@ -8,7 +8,7 @@ Please note that the autoscaler is not feature-complete yet. You can follow the
 
 ### docker-compose
 
-If you are using docker-compose you can add the following to your docker-compose.yml file:
+If you are using docker-compose you can add the following to your `docker-compose.yaml` file:
 
 ```yaml
 version: '3'

docs/docs/30-administration/90-prometheus.md

@@ -19,35 +19,31 @@ scrape_configs:
 An administrator will need to generate a user API token and configure in the Prometheus configuration file as a bearer token. Please see the following example:
 
 ```diff
-global:
-  scrape_interval: 60s
+ global:
+   scrape_interval: 60s
 
-scrape_configs:
-  - job_name: 'woodpecker'
-+   bearer_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+ scrape_configs:
+   - job_name: 'woodpecker'
++    bearer_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 
-    static_configs:
-       - targets: ['woodpecker.domain.com']
+     static_configs:
+        - targets: ['woodpecker.domain.com']
 ```
 
 As an alternative, the token can also be read from a file:
 
 ```diff
-global:
-  scrape_interval: 60s
+ global:
+   scrape_interval: 60s
 
-scrape_configs:
-  - job_name: 'woodpecker'
-+   bearer_token_file: /etc/secrets/woodpecker-monitoring-token
+ scrape_configs:
+   - job_name: 'woodpecker'
++    bearer_token_file: /etc/secrets/woodpecker-monitoring-token
 
-    static_configs:
-       - targets: ['woodpecker.domain.com']
+     static_configs:
+        - targets: ['woodpecker.domain.com']
 ```
 
-## Unauthenticated Access
-
-Alternatively, the unprotected `/metrics` endpoint might be exposed on the internal port (Port is configurable via the `WOODPECKER_METRICS_SERVER_ADDR` environment variable, e.g. `:9001`).
-
 ## Metric Reference
 
 List of Prometheus metrics specific to Woodpecker:

docs/docs/92-awesome.md

@@ -7,11 +7,10 @@ If you have some missing resources, please feel free to [open a pull-request](ht
 ## Official Resources
 
 - [Woodpecker CI pipeline configs](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) - Complex setup containing different kind of pipelines
-  - [Golang tests](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/test.yml)
-  - [Typescript, eslint & Vue](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/web.yml)
-  - [Docusaurus & publishing to GitHub Pages](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docs.yml)
-  - [Docker container building](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docker.yml)
-  - [Helm chart linting & releasing](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/helm.yml)
+  - [Golang tests](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/test.yaml)
+  - [Typescript, eslint & Vue](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/web.yaml)
+  - [Docusaurus & publishing to GitHub Pages](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docs.yaml)
+  - [Docker container building](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docker.yaml)
 
 ## Projects using Woodpecker
 

docs/docs/92-development/01-getting-started.md

@@ -4,7 +4,7 @@ You can develop on your local computer by following the [steps below](#preparati
 
 ## Gitpod
 
-If you want to start development or updating docs as easy as possible you can use our preconfigured setup for Woodpecker using [Gitpod](https://github.com/gitpod-io/gitpod). Gitpod starts a complete development setup in the cloud containing:
+If you want to start development or updating docs as easy as possible, you can use our preconfigured setup for Woodpecker using [Gitpod](https://github.com/gitpod-io/gitpod). Gitpod starts a complete development setup in the cloud containing:
 
 - An IDE in the browser or bridged to your local VS-Code or Jetbrains
 - A preconfigured [Gitea](https://github.com/go-gitea/gitea) instance as forge
@@ -12,7 +12,7 @@ If you want to start development or updating docs as easy as possible you can us
 - A single preconfigured Woodpecker agent node
 - Our docs preview server
 
-Simply start Woodpecker in Gitpod by clicking on the following badge. You can login with `woodpecker` and `password`.
+Start Woodpecker in Gitpod by clicking on the following badge. You can log in with `woodpecker` and `password`.
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/woodpecker-ci/woodpecker)
 
@@ -32,11 +32,17 @@ Install make on:
 - [Windows](https://stackoverflow.com/a/32127632/8461267)
 - Mac OS: `brew install make`
 
-### Install Node.js & pnpm
+### Install Node.js & `pnpm`
 
-Install [Node.js (>=14)](https://nodejs.org/en/download/) if you want to build Woodpeckers UI or documentation.
+Install [Node.js (>=14)](https://nodejs.org/en/download/) if you want to build Woodpecker's UI or documentation.
 
-For dependencies installation (node_modules) for the UI and documentation of Woodpecker the package-manager pnpm is used. The installation of pnpm is described by [this guide](https://pnpm.io/installation).
+For dependency installation (`node_modules`) of UI and documentation of Woodpecker the package manager pnpm is used.
+[This guide](https://pnpm.io/installation) describes the installation of `pnpm`.
+
+### Install `pre-commit` (optional)
+
+Woodpecker uses [`pre-commit`](https://pre-commit.com/) to allow you to easily autofix your code.
+To apply it during local development, take a look at [`pre-commit`s documentation](https://pre-commit.com/#usage).
 
 ### Create a `.env` file with your development configuration
 
@@ -74,28 +80,28 @@ WOODPECKER_HEALTHCHECK=false
 # WOODPECKER_LOG_LEVEL=trace
 ```
 
-### Setup O-Auth
+### Setup OAuth
 
-Create an O-Auth app for your forge as describe in the [forges documentation](../30-administration/11-forges/10-overview.md). If you set `WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000` you can use that address with the path as explained for the specific forge to login without the need for a public address. For example for GitHub you would use `http://localhost:8000/authorize` as authorization callback URL.
+Create an OAuth app for your forge as described in the [forges documentation](../30-administration/11-forges/10-overview.md). If you set `WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000` you can use that address with the path as explained for the specific forge to login without the need for a public address. For example for GitHub you would use `http://localhost:8000/authorize` as authorization callback URL.
 
-## Developing with VS-Code
+## Developing with VS Code
 
 You can use different methods for debugging the Woodpecker applications. One of the currently recommended ways to debug and test the Woodpecker application is using [VS-Code](https://code.visualstudio.com/) or [VS-Codium](https://vscodium.com/) (Open-Source binaries of VS-Code) as most maintainers are using it and Woodpecker already includes the needed debug configurations for it.
 
-To launch all needed services for local development you can use "Woodpecker CI" debugging configuration that will launch UI, server and agent in debugging mode. Then open `http://localhost:8000` to access it.
+To launch all needed services for local development, you can use "Woodpecker CI" debugging configuration that will launch UI, server and agent in debugging mode. Then open `http://localhost:8000` to access it.
 
-As a starting guide for programming Go with VS-Code you can use this video guide:
-[![Getting started with Go in VS-Code](https://img.youtube.com/vi/1MXIGYrMk80/0.jpg)](https://www.youtube.com/watch?v=1MXIGYrMk80)
+As a starting guide for programming Go with VS Code, you can use this video guide:
+[![Getting started with Go in VS Code](https://img.youtube.com/vi/1MXIGYrMk80/0.jpg)](https://www.youtube.com/watch?v=1MXIGYrMk80)
 
 ### Debugging Woodpecker
 
 The Woodpecker source code already includes launch configurations for the Woodpecker server and agent. To start debugging you can click on the debug icon in the navigation bar of VS-Code (ctrl-shift-d). On that page you will see the existing launch jobs at the top. Simply select the agent or server and click on the play button. You can set breakpoints in the source files to stop at specific points.
 
-![Woodpecker debugging with VS-Code](./vscode-debug.png)
+![Woodpecker debugging with VS Code](./vscode-debug.png)
 
 ## Testing & linting code
 
-To test or lint parts of Woodpecker you can run one of the following commands:
+To test or lint parts of Woodpecker, you can run one of the following commands:
 
 ```bash
 # test server code
@@ -120,7 +126,7 @@ make lint-frontend
 make test-frontend
 ```
 
-If you want to test a specific go file you can also use:
+If you want to test a specific Go file, you can also use:
 
 ```bash
 go test -race -timeout 30s go.woodpecker-ci.org/woodpecker/v2/<path-to-the-package-or-file-to-test>
@@ -132,7 +138,7 @@ Or you can open the test-file inside [VS-Code](#developing-with-vs-code) and run
 
 ## Run applications from terminal
 
-If you want to run a Woodpecker applications from your terminal you can use one of the following commands from the base of the Woodpecker project. They will execute Woodpecker in a similar way as described in [debugging Woodpecker](#debugging-woodpecker) without the ability to really debug it in your editor.
+If you want to run a Woodpecker applications from your terminal, you can use one of the following commands from the base of the Woodpecker project. They will execute Woodpecker in a similar way as described in [debugging Woodpecker](#debugging-woodpecker) without the ability to really debug it in your editor.
 
 ```bash title="start server"
 go run ./cmd/server

docs/docusaurus.config.ts

@@ -132,7 +132,7 @@ const config: Config = {
               href: 'https://github.com/woodpecker-ci/woodpecker',
             },
             {
-              href: 'https://ci.woodpecker-ci.org/woodpecker-ci/woodpecker',
+              href: 'https://ci.woodpecker-ci.org/repos/3780',
               label: 'CI',
             },
           ],
@@ -143,7 +143,19 @@ const config: Config = {
     prism: {
       theme: themes.github,
       darkTheme: themes.dracula,
-      additionalLanguages: ['diff', 'json', 'docker', 'javascript', 'css', 'bash', 'nginx', 'apacheconf', 'ini', 'nix'],
+      additionalLanguages: [
+        'diff',
+        'json',
+        'docker',
+        'javascript',
+        'css',
+        'bash',
+        'nginx',
+        'apacheconf',
+        'ini',
+        'nix',
+        'uri',
+      ],
     },
     announcementBar: {
       id: 'github-star',

docs/src/pages/faq.md

@@ -28,13 +28,8 @@ If you want all (new) features of Woodpecker and are willing to accept some poss
 
 This error can have multiple causes. If you use internal repositories you might have to enable `WOODPECKER_AUTHENTICATE_PUBLIC_REPOS`:
 
-```yaml
-services:
-  woodpecker-server:
-    [...]
-    environment:
-      - [...]
-      - WOODPECKER_AUTHENTICATE_PUBLIC_REPOS=true
+```ini
+WOODPECKER_AUTHENTICATE_PUBLIC_REPOS=true
 ```
 
 If that does not work, try to make sure the container can reach your git server. In order to do that disable git checkout and make the container "hang":