Versioned Docs for v2.8.0 Release (#4469)

docs/docusaurus.config.ts

@@ -236,25 +236,25 @@ const config: Config = {
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl: 'https://github.com/woodpecker-ci/woodpecker/edit/main/docs/',
           includeCurrentVersion: true,
-          lastVersion: '2.7',
+          lastVersion: '2.8',
           onlyIncludeVersions:
-            process.env.NODE_ENV === 'development' ? ['current', '2.7'] : ['current', '2.7', '2.6', '2.5', '1.0'],
+            process.env.NODE_ENV === 'development' ? ['current', '2.8'] : ['current', '2.8', '2.7', '2.6', '1.0'],
           versions: {
             current: {
               label: 'Next 🚧',
               banner: 'unreleased',
             },
+            '2.8': {
+              label: '2.8.x',
+            },
             '2.7': {
               label: '2.7.x',
+              banner: 'unmaintained',
             },
             '2.6': {
               label: '2.6.x 💀',
               banner: 'unmaintained',
             },
-            '2.5': {
-              label: '2.5.x 💀',
-              banner: 'unmaintained',
-            },
             '1.0': {
               label: '1.0.x 💀',
               banner: 'unmaintained',

docs/src/pages/versions.md

@@ -33,6 +33,7 @@ Here you can find documentation for previous versions of Woodpecker.
 
 |         |            |                                                                                       |
 | ------- | ---------- | ------------------------------------------------------------------------------------- |
+| 2.7.3   | 2024-11-28 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.7.3/docs/docs/)   |
 | 2.7.2   | 2024-11-03 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.7.2/docs/docs/)   |
 | 2.7.1   | 2024-09-07 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.7.1/docs/docs/)   |
 | 2.7.0   | 2024-07-18 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.7.0/docs/docs/)   |

docs/versioned_docs/version-2.5/10-intro.md

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

docs/versioned_docs/version-2.5/20-usage/10-intro.md

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

docs/versioned_docs/version-2.5/30-administration/00-deployment/00-overview.md

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

docs/versioned_docs/version-2.5/30-administration/11-forges/11-overview.md

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

docs/versioned_docs/version-2.8/10-intro/index.md

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

docs/versioned_docs/version-2.8/20-usage/10-intro.md

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

docs/versioned_docs/version-2.8/20-usage/100-troubleshooting.md

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

docs/versioned_docs/version-2.8/20-usage/15-terminology/index.md

@@ -1,13 +1,5 @@
 # Terminology
 
-## Woodpecker architecture
-
-![Woodpecker architecture](architecture.svg)
-
-## Pipeline, workflow & step
-
-![Relation between pipelines, workflows and steps](pipeline-workflow-step.svg)
-
 ## Glossary
 
 - **Woodpecker CI**: The project name around Woodpecker.
@@ -33,6 +25,14 @@
 - **Status**: Status refers to the outcome of a step or [workflow][Workflow] after it has been executed, determined by the internal command exit code. At the end of a [workflow][Workflow], its status is sent to the [forge][Forge].
 - **Service extension**: Some parts of Woodpecker internal services like secrets storage or config fetcher can be replaced through service extensions.
 
+## Woodpecker architecture
+
+![Woodpecker architecture](architecture.svg)
+
+## Pipeline, workflow & step
+
+![Relation between pipelines, workflows and steps](pipeline-workflow-step.svg)
+
 ## Pipeline events
 
 - `push`: A push event is triggered when a commit is pushed to a branch.

docs/versioned_docs/version-2.8/20-usage/20-workflow-syntax.md

@@ -6,6 +6,11 @@ The Workflow section defines a list of steps to build, test and deploy your code
 An exception to this rule are steps with a [`status: [failure]`](#status) condition, which ensures that they are executed in the case of a failed run.
 :::
 
+:::note
+We support most of YAML 1.2, but preserve some behavior from 1.1 for backward compatibility.
+Read more at: [https://github.com/go-yaml/yaml](https://github.com/go-yaml/yaml/tree/v3)
+:::
+
 Example steps:
 
 ```yaml
@@ -518,7 +523,9 @@ 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 pattern `/woodpecker/src/github.com/octocat/hello-world`, based on your repository URL.
+The workspace defines the shared volume and working directory shared by all workflow steps.
+The default workspace base is `/woodpecker` and the path is extended with the repository URL (`src/{url-without-schema}`).
+So an example would be `/woodpecker/src/github.com/octocat/hello-world`.
 
 The workspace can be customized using the workspace block in the YAML file:
 
@@ -535,6 +542,10 @@ The workspace can be customized using the workspace block in the YAML file:
        - go test
 ```
 
+:::note
+Plugins will always have the workspace base at `/woodpecker`
+:::
+
 The base attribute defines a shared base volume available to all steps. This ensures your source code, dependencies and compiled binaries are persisted and shared between steps.
 
 ```diff

docs/versioned_docs/version-2.8/20-usage/51-plugins/51-overview.md

@@ -4,6 +4,24 @@ Plugins are pipeline steps that perform pre-defined tasks and are configured as
 
 They are automatically pulled from the default container registry the agent's have configured.
 
+```dockerfile title="Dockerfile"
+FROM laszlocloud/kubectl
+COPY deploy /usr/local/deploy
+ENTRYPOINT ["/usr/local/deploy"]
+```
+
+```bash title="deploy"
+kubectl apply -f $PLUGIN_TEMPLATE
+```
+
+```yaml title=".woodpecker.yaml"
+steps:
+  - name: deploy-to-k8s
+    image: laszlocloud/my-k8s-plugin
+    settings:
+      template: config/k8s/service.yaml
+```
+
 Example pipeline using the Docker and Slack plugins:
 
 ```yaml
@@ -29,6 +47,12 @@ steps:
 ## Plugin Isolation
 
 Plugins are just pipeline steps. They share the build workspace, mounted as a volume, and therefore have access to your source tree.
+While normal steps are all about arbitrary code execution, plugins should only allow the functions intended by the plugin author.
+
+That's why there are a few limitations. The workspace base is always mounted at `/woodpecker`, but the working directory is dynamically
+adjusted accordingly, as user of a plugin you should not have to care about this. Also, you cannot use the plugin together with `commands`
+or `entrypoint` which will fail. Using `secrets` or `environment` is possible, but in this case, the plugin is internally not treated as plugin
+anymore. The container then cannot access secrets with plugin filter anymore and the containers won't be privileged without explicit definition.
 
 ## Finding Plugins
 

docs/versioned_docs/version-2.8/20-usage/75-project-settings.md

@@ -25,10 +25,9 @@ Only activate this option if you trust all users who have push access to your re
 Otherwise, these users will be able to steal secrets that are only available for `deploy` events.
 :::
 
-## Protected
+## Require approval for
 
-Every pipeline initiated by an webhook event needs to be approved by a project members with push permissions before being executed.
-The protected option can be used as an additional review process before running potentially harmful pipelines. Especially if pipelines can be executed by third-parties through pull-requests.
+To prevent malicious pipelines from extracting secrets or running harmful commands or to prevent accidental pipeline runs, you can require approval for an additional review process. Depending on the enabled option, a pipeline will be put on hold after creation and will only continue after approval. The default restrictive setting is `All pull requests`.
 
 ## Trusted
 
@@ -40,16 +39,9 @@ Only server admins can set this option. If you are not a server admin this optio
 
 :::
 
-## Only inject Git credentials into trusted clone plugins
+## Only inject netrc credentials into trusted containers
 
-The clone step may require Git credentials (e.g. for private repos) which are injected via `netrc`.
-
-By default, they are only injected into trusted clone plugins listed in the env var `WOODPECKER_PLUGINS_TRUSTED_CLONE`.
-If this option is disabled, the Git credentials are injected into every clone plugin, regardless of whether it is trusted or not.
-
-:::note
-This option has no effect on steps other than the clone step.
-:::
+Cloning pipeline step may need git credentials. They are injected via netrc. By default, they're only injected if this option is enabled, the repo is trusted ([see above](#trusted)) or the image is a trusted clone image. If you uncheck the option, git credentials will be injected into any container in clone step.
 
 ## Project visibility
 

docs/versioned_docs/version-2.8/30-administration/00-getting-started.md

@@ -0,0 +1,59 @@
+# Gettings started
+
+A Woodpecker deployment consists of two parts:
+
+- A server which is the heart of Woodpecker and ships the web interface.
+- Next to one server, you can deploy any number of agents which will run the pipelines.
+
+Each agent is able to process one [workflow](../20-usage/15-terminology/index.md) by default. If you have 4 agents installed and connected to the Woodpecker server, your system will process four workflows (not pipelines) in parallel.
+
+:::tip
+You can add more agents to increase the number of parallel workflows or set the agent's `WOODPECKER_MAX_WORKFLOWS=1` environment variable to increase the number of parallel workflows per agent.
+:::
+
+## Which version of Woodpecker should I use?
+
+Woodpecker is having two different kinds of releases: **stable** and **next**.
+
+Find more information about the different versions [here](/versions).
+
+## Hardware Requirements
+
+Below are minimal resources requirements for Woodpecker components itself:
+
+| Component | Memory | CPU |
+| --------- | ------ | --- |
+| Server    | 200 MB | 1   |
+| Agent     | 32 MB  | 1   |
+
+Note, that those values do not include the operating system or workload (pipelines execution) resource consumption.
+
+In addition you need at least some kind of database which requires additional resources depending on the selected database system.
+
+## Installation
+
+You can install Woodpecker on multiple ways. If you are not sure which one to choose, we recommend using the [docker-compose](./05-deployment-methods/10-docker-compose.md) method for the beginning:
+
+- Using [docker-compose](./05-deployment-methods/10-docker-compose.md) with the official [container images](./05-deployment-methods/10-docker-compose.md#docker-images)
+- Using [Kubernetes](./05-deployment-methods/20-kubernetes.md) via the Woodpecker Helm chart
+- Using binaries, DEBs or RPMs you can download from [latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest)
+- Or using a [third-party installation method](./05-deployment-methods/30-third-party.md)
+
+## Database
+
+By default Woodpecker uses a SQLite database which requires zero installation or configuration. See the [database settings](./10-database.md) page if you want to use a different database system like MySQL or PostgreSQL.
+
+## Forge
+
+What would be a CI/CD system without any code? By connecting Woodpecker to your [forge](../20-usage/15-terminology/index.md) like GitHub or Gitea you can start running pipelines on events like pushes or pull requests. Woodpecker will also use your forge for authentication and to report back the status of your pipelines. See the [forge settings](./11-forges/11-overview.md) to conntect it to Woodpecker.
+
+## Configuration
+
+Check the [server configuration](./10-server-config.md) and [agent configuration](./15-agent-config.md) pages to see if you need to adjust any additional parts and after that you should be ready to start with [your first pipeline](../20-usage/10-intro.md).
+
+## Agent
+
+The agent is the worker which executes the [workflows](../20-usage/15-terminology/index.md).
+Woodpecker agents can execute work using a [backend](../20-usage/15-terminology/index.md) like [docker](./22-backends/10-docker.md) or [kubernetes](./22-backends/40-kubernetes.md).
+By default if you choose to deploy an agent using [docker-compose](./05-deployment-methods/10-docker-compose.md) the agent simply use docker for the backend as well.
+So nothing to worry about here. If you still prefer to adjust the agent to your needs, check the [agent configuration](./15-agent-config.md) page.

docs/versioned_docs/version-2.8/30-administration/05-deployment-methods/10-docker-compose.md

@@ -67,7 +67,7 @@ They can be configured with `*_ADDR` variables:
 +      - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR}
 ```
 
-Reverse proxying can also be [configured for gRPC](../70-proxy.md#caddy). If the agents are connecting over the internet, it should also be SSL encrypted. The agent then needs to be configured to be secure:
+Reverse proxying can also be [configured for gRPC](../40-advanced/10-proxy.md#caddy). If the agents are connecting over the internet, it should also be SSL encrypted. The agent then needs to be configured to be secure:
 
 ```diff title="docker-compose.yaml"
  version: '3'

docs/versioned_docs/version-2.8/30-administration/05-deployment-methods/30-third-party.md

@@ -0,0 +1,12 @@
+# Third-party installation methods
+
+:::info
+These installation methods are not officially supported. If you experience issues with them, please open issues in the specific repositories.
+:::
+
+- [Using NixOS](./40-nixos.md) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker)
+- [On Alpine Edge](https://pkgs.alpinelinux.org/packages?name=woodpecker&branch=edge&repo=&arch=&maintainer=)
+- [On Arch Linux](https://archlinux.org/packages/?q=woodpecker)
+- [On openSUSE](https://software.opensuse.org/package/woodpecker)
+- [Using YunoHost](https://apps.yunohost.org/app/woodpecker)
+- [On Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html)

docs/versioned_docs/version-2.8/30-administration/05-deployment-methods/_category_.yaml

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

docs/versioned_docs/version-2.8/30-administration/10-server-config.md

@@ -360,6 +360,8 @@ a user can log into Woodpecker, without re-authentication.
 
 Docker images to run in privileged mode. Only change if you are sure what you do!
 
+You should specify the tag of your images too, as this enforces exact matches.
+
 <!--
 ### `WOODPECKER_VOLUME`
 > Default: empty
@@ -517,7 +519,7 @@ Example: `WOODPECKER_LIMIT_CPU_SET=1,2`
 
 > Default: empty
 
-Specify a configuration service endpoint, see [Configuration Extension](./100-external-configuration-api.md)
+Specify a configuration service endpoint, see [Configuration Extension](./40-advanced/100-external-configuration-api.md)
 
 ### `WOODPECKER_FORGE_TIMEOUT`
 
@@ -543,6 +545,18 @@ Enable the Swagger UI for API documentation.
 
 Disable version check in admin web UI.
 
+### `WOODPECKER_LOG_STORE`
+
+> Default: `database`
+
+Where to store logs. Possible values: `database` or `file`.
+
+### `WOODPECKER_LOG_STORE_FILE_PATH`
+
+> Default empty
+
+Directory to store logs in if [`WOODPECKER_LOG_STORE`](#woodpecker_log_store) is `file`.
+
 ---
 
 ### `WOODPECKER_GITHUB_...`

docs/versioned_docs/version-2.8/30-administration/11-forges/11-overview.md

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

docs/versioned_docs/version-2.8/30-administration/11-forges/30-gitea.md

@@ -2,9 +2,9 @@
 toc_max_heading_level: 2
 ---
 
-# Gitea / Forgejo
+# Gitea
 
-Woodpecker comes with built-in support for Gitea and the "soft" fork Forgejo. To enable Gitea you should configure the Woodpecker container using the following environment variables:
+Woodpecker comes with built-in support for Gitea. To enable Gitea you should configure the Woodpecker container using the following environment variables:
 
 ```ini
 WOODPECKER_GITEA=true

docs/versioned_docs/version-2.8/30-administration/11-forges/35-forgejo.md

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

docs/versioned_docs/version-2.8/30-administration/22-backends/20-local.md

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

docs/versioned_docs/version-2.8/30-administration/22-backends/40-kubernetes.md

@@ -79,7 +79,8 @@ And then overwrite the `nodeSelector` in the `backend_options` section of the st
           kubernetes.io/arch: "${ARCH}"
 ```
 
-You can use [PodNodeSelector](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#podnodeselector) admission controller if you want to set the node selector by per-namespace basis.
+You can use [WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR](#woodpecker_backend_k8s_pod_node_selector) if you want to set the node selector per Agent
+or [PodNodeSelector](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#podnodeselector) admission controller if you want to set the node selector by per-namespace basis.
 
 ### Tolerations
 
@@ -227,6 +228,12 @@ workspace:
 
 See [this issue](https://github.com/woodpecker-ci/woodpecker/issues/2510) for more details.
 
+### `KUBERNETES_SERVICE_HOST` environment variable
+
+Like the below env vars used for configuration, this can be set in the environment fonfiguration of the agent. It configures the address of the Kubernetes API server to connect to.
+
+If running the agent within Kubernetes, this will already be set and you don't have to add it manually.
+
 ## Configuration
 
 These env vars can be set in the `env:` sections of the agent.
@@ -279,6 +286,12 @@ Additional annotations to apply to worker Pods. Must be a YAML object, e.g. `{"e
 
 Determines if Pod annotations can be defined from a step's backend options.
 
+### `WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR`
+
+> Default: empty
+
+Additional node selector to apply to worker pods. Must be a YAML object, e.g. `{"topology.kubernetes.io/region":"eu-central-1"}`.
+
 ### `WOODPECKER_BACKEND_K8S_SECCTX_NONROOT`
 
 > Default: `false`

docs/versioned_docs/version-2.8/30-administration/40-advanced/10-proxy.md

@@ -93,7 +93,7 @@ woodpeckeragent.example.com {
 ```
 
 :::note
-Above configuration shows how to create reverse-proxies for web and agent communication. If your agent uses SSL do not forget to enable [`WOODPECKER_GRPC_SECURE`](./15-agent-config.md#woodpecker_grpc_secure).
+Above configuration shows how to create reverse-proxies for web and agent communication. If your agent uses SSL do not forget to enable [`WOODPECKER_GRPC_SECURE`](../15-agent-config.md#woodpecker_grpc_secure).
 :::
 
 ## Tunnelmole

docs/versioned_docs/version-2.8/30-administration/40-advanced/40-advanced.md

@@ -0,0 +1,25 @@
+# Adavanced options
+
+Why should we be happy with a default setup? We should not! Woodpecker offers a lot of advanced options to configure it to your needs.
+
+## Behind a proxy
+
+See the [proxy guide](./10-proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok.
+
+In the case you need to use Woodpecker with a URL path prefix (like: <https://example.org/woodpecker/>), add the root path to [`WOODPECKER_HOST`](../10-server-config.md#woodpecker_host).
+
+## SSL
+
+Woodpecker supports SSL configuration by using Let's encrypt or by using own certificates. See the [SSL guide](./20-ssl.md).
+
+## Metrics
+
+A [Prometheus endpoint](./90-prometheus.md) is exposed by Woodpecker to collect metrics.
+
+## Autoscaling
+
+The [autoscaler](./30-autoscaler.md) can be used to deploy new agents to a cloud provider based on the current workload your server is experiencing.
+
+## Configuration service
+
+Sometime the normal yaml configuration compiler isn't enough. You can use the [configuration service](./100-external-configuration-api.md) to process your configuration files by your own.

docs/versioned_docs/version-2.8/30-administration/40-advanced/_category_.yaml

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

docs/versioned_docs/version-2.8/40-cli.md

@@ -2,7 +2,7 @@
 
 # NAME
 
-woodpecker-cli - A new cli application
+woodpecker-cli - command line utility
 
 # SYNOPSIS
 
@@ -26,7 +26,7 @@ Woodpecker command line utility
 **Usage**:
 
 ```
-woodpecker-cli [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
+woodpecker-cli [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...]
 ```
 
 # GLOBAL OPTIONS
@@ -35,9 +35,9 @@ woodpecker-cli [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
 
 **--disable-update-check**: disable update check
 
-**--log-file**="": Output destination for logs. 'stdout' and 'stderr' can be used as special keywords. (default: "stderr")
+**--log-file**="": Output destination for logs. 'stdout' and 'stderr' can be used as special keywords. (default: stderr)
 
-**--log-level**="": set logging level (default: "info")
+**--log-level**="": set logging level (default: info)
 
 **--nocolor**: disable colored debug output, only has effect if pretty output is set too
 
@@ -47,9 +47,229 @@ woodpecker-cli [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
 
 **--token, -t**="": server auth token
 
-
 # COMMANDS
 
+## admin
+
+administer server settings
+
+### registry
+
+manage global registries
+
+#### add
+
+adds a registry
+
+**--hostname**="": registry hostname (default: docker.io)
+
+**--password**="": registry password
+
+**--username**="": registry username
+
+#### rm
+
+remove a registry
+
+**--hostname**="": registry hostname (default: docker.io)
+
+#### update
+
+update a registry
+
+**--hostname**="": registry hostname (default: docker.io)
+
+**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
+
+**--password**="": registry password
+
+**--username**="": registry username
+
+#### info
+
+display registry info
+
+**--hostname**="": registry hostname (default: docker.io)
+
+#### ls
+
+list registries
+
+## org
+
+manage organizations
+
+### registry
+
+manage organization registries
+
+#### add
+
+adds a registry
+
+**--hostname**="": registry hostname (default: docker.io)
+
+**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
+
+**--password**="": registry password
+
+**--username**="": registry username
+
+#### rm
+
+remove a registry
+
+**--hostname**="": registry hostname (default: docker.io)
+
+**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
+
+#### update
+
+update a registry
+
+**--hostname**="": registry hostname (default: docker.io)
+
+**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
+
+**--password**="": registry password
+
+**--username**="": registry username
+
+#### info
+
+display registry info
+
+**--hostname**="": registry hostname (default: docker.io)
+
+**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
+
+#### ls
+
+list registries
+
+**--organization, --org**="": organization id or full name (e.g. 123 or octocat)
+
+## repo
+
+manage repositories
+
+### ls
+
+list all repos
+
+**--format**="": format output (default: {{ .FullName }} (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }}))
+
+**--org**="": filter by organization
+
+### info
+
+show repository details
+
+**--format**="": format output (default: Owner: {{ .Owner }}
+Repo: {{ .Name }}
+URL: {{ .ForgeURL }}
+Config path: {{ .Config }}
+Visibility: {{ .Visibility }}
+Private: {{ .IsSCMPrivate }}
+Trusted: {{ .IsTrusted }}
+Gated: {{ .IsGated }}
+Require approval for: {{ .RequireApproval }}
+Clone url: {{ .Clone }}
+Allow pull-requests: {{ .AllowPullRequests }}
+)
+
+### add
+
+add a repository
+
+### update
+
+update a repository
+
+**--config**="": repository configuration path (e.g. .woodpecker.yml)
+
+**--gated**: [deprecated] repository is gated
+
+**--pipeline-counter**="": repository starting pipeline number (default: 0)
+
+**--require-approval**="": repository requires approval for
+
+**--timeout**="": repository timeout (default: 0s)
+
+**--trusted**: repository is trusted
+
+**--unsafe**: validate updating the pipeline-counter is unsafe
+
+**--visibility**="": repository visibility
+
+### rm
+
+remove a repository
+
+### repair
+
+repair repository webhooks
+
+### chown
+
+assume ownership of a repository
+
+### sync
+
+synchronize the repository list
+
+**--format**="": format output (default: {{ .FullName }} (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }}))
+
+### registry
+
+manage registries
+
+#### add
+
+adds a registry
+
+**--hostname**="": registry hostname (default: docker.io)
+
+**--password**="": registry password
+
+**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
+
+**--username**="": registry username
+
+#### rm
+
+remove a registry
+
+**--hostname**="": registry hostname (default: docker.io)
+
+**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
+
+#### update
+
+update a registry
+
+**--hostname**="": registry hostname (default: docker.io)
+
+**--password**="": registry password
+
+**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
+
+**--username**="": registry username
+
+#### info
+
+display registry info
+
+**--hostname**="": registry hostname (default: docker.io)
+
+**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
+
+#### ls
+
+list registries
+
+**--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
+
 ## pipeline
 
 manage pipelines
@@ -64,7 +284,7 @@ show pipeline history
 
 **--limit**="": limit the list size (default: 25)
 
-**--output**="": output format (default: "table")
+**--output**="": output format (default: table)
 
 **--output-no-headers**: don't print headers
 
@@ -74,9 +294,9 @@ show pipeline history
 
 show latest pipeline details
 
-**--branch**="": branch name (default: "main")
+**--branch**="": branch name (default: main)
 
-**--output**="": output format (default: "table")
+**--output**="": output format (default: table)
 
 **--output-no-headers**: don't print headers
 
@@ -88,7 +308,7 @@ show pipeline logs
 
 show pipeline details
 
-**--output**="": output format (default: "table")
+**--output**="": output format (default: table)
 
 **--output-no-headers**: don't print headers
 
@@ -100,7 +320,7 @@ stop a pipeline
 
 start a pipeline
 
-**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value
+**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value (default: [])
 
 ### approve
 
@@ -114,13 +334,27 @@ decline a pipeline
 
 show pipeline queue
 
-**--format**="": format output (default: "\x1b[33m{{ .FullName }} #{{ .Number }} \x1b[0m\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nAuthor: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}\nMessage: {{ .Message }}\n")
+**--format**="": format output (default: {{ .FullName }} #{{ .Number }} 
+Status: {{ .Status }}
+Event: {{ .Event }}
+Commit: {{ .Commit }}
+Branch: {{ .Branch }}
+Ref: {{ .Ref }}
+Author: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}
+Message: {{ .Message }}
+)
 
 ### ps
 
 show pipeline steps
 
-**--format**="": format output (default: "\x1b[33mStep #{{ .PID }} \x1b[0m\nStep: {{ .Name }}\nState: {{ .State }}\n")
+**--format**="": format output (default: {{ .workflow.Name }} > {{ .step.Name }} (#{{ .step.PID }}):
+Step: {{ .step.Name }}
+Started: {{ .step.Started }}
+Stopped: {{ .step.Stopped }}
+Type: {{ .step.Type }}
+State: {{ .step.State }}
+)
 
 ### create
 
@@ -128,11 +362,11 @@ create new pipeline
 
 **--branch**="": branch to create pipeline from
 
-**--output**="": output format (default: "table")
+**--output**="": output format (default: table)
 
 **--output-no-headers**: don't print headers
 
-**--var**="": key=value
+**--var**="": key=value (default: [])
 
 ## log
 
@@ -144,17 +378,25 @@ purge a log
 
 ## deploy
 
-deploy code
+trigger a pipeline with the 'deployment' event
 
-**--branch**="": branch filter (default: "main")
+**--branch**="": branch filter
 
-**--event**="": event filter (default: "push")
+**--event**="": event filter (default: push)
 
-**--format**="": format output (default: "Number: {{ .Number }}\nStatus: {{ .Status }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\nTarget: {{ .Deploy }}\n")
+**--format**="": format output (default: Number: {{ .Number }}
+Status: {{ .Status }}
+Commit: {{ .Commit }}
+Branch: {{ .Branch }}
+Ref: {{ .Ref }}
+Message: {{ .Message }}
+Author: {{ .Author }}
+Target: {{ .Deploy }}
+)
 
-**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value
+**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value (default: [])
 
-**--status**="": status filter (default: "success")
+**--status**="": status filter (default: success)
 
 ## exec
 
@@ -174,33 +416,37 @@ execute a local pipeline
 
 **--backend-docker-volumes**="": backend docker volumes (comma separated)
 
-**--backend-engine**="": backend engine to run pipelines on (default: "auto-detect")
+**--backend-engine**="": backend engine to run pipelines on (default: auto-detect)
 
 **--backend-http-proxy**="": if set, pass the environment variable down as "HTTP_PROXY" to steps
 
 **--backend-https-proxy**="": if set, pass the environment variable down as "HTTPS_PROXY" to steps
 
-**--backend-k8s-namespace**="": backend k8s namespace (default: "woodpecker")
+**--backend-k8s-allow-native-secrets**: whether to allow existing Kubernetes secrets to be referenced from steps
+
+**--backend-k8s-namespace**="": backend k8s namespace (default: woodpecker)
 
 **--backend-k8s-pod-annotations**="": backend k8s additional Agent-wide worker pod annotations
 
 **--backend-k8s-pod-annotations-allow-from-step**: whether to allow using annotations from step's backend options
 
-**--backend-k8s-pod-image-pull-secret-names**="": backend k8s pull secret names for private registries (default: "regcred")
+**--backend-k8s-pod-image-pull-secret-names**="": backend k8s pull secret names for private registries (default: [regcred])
 
 **--backend-k8s-pod-labels**="": backend k8s additional Agent-wide worker pod labels
 
 **--backend-k8s-pod-labels-allow-from-step**: whether to allow using labels from step's backend options
 
+**--backend-k8s-pod-node-selector**="": backend k8s Agent-wide worker pod node selector
+
 **--backend-k8s-secctx-nonroot**: `run as non root` Kubernetes security context option
 
 **--backend-k8s-storage-class**="": backend k8s storage class
 
 **--backend-k8s-storage-rwx**: backend k8s storage access mode, should ReadWriteMany (RWX) instead of ReadWriteOnce (RWO) be used? (default: true)
 
-**--backend-k8s-volume-size**="": backend k8s volume size (default 10G) (default: "10G")
+**--backend-k8s-volume-size**="": backend k8s volume size (default 10G) (default: 10G)
 
-**--backend-local-temp-dir**="": set a different temp dir to clone workflows into (default: "/tmp")
+**--backend-local-temp-dir**="": set a different temp dir to clone workflows into (default: /tmp/nix-shell.OgDG7Z)
 
 **--backend-no-proxy**="": if set, pass the environment variable down as "NO_PROXY" to steps
 
@@ -220,7 +466,7 @@ execute a local pipeline
 
 **--commit-sha**="":
 
-**--env**="":
+**--env**="": (default: [])
 
 **--forge-type**="":
 
@@ -234,11 +480,15 @@ execute a local pipeline
 
 **--netrc-username**="":
 
-**--network**="": external networks
+**--network**="": external networks (default: [])
 
 **--pipeline-created**="": (default: 0)
 
-**--pipeline-event**="":  (default: "manual")
+**--pipeline-deploy-task**="":
+
+**--pipeline-deploy-to**="":
+
+**--pipeline-event**="": (default: manual)
 
 **--pipeline-finished**="": (default: 0)
 
@@ -250,10 +500,6 @@ execute a local pipeline
 
 **--pipeline-status**="":
 
-**--pipeline-target**="":
-
-**--pipeline-task**="":
-
 **--pipeline-url**="":
 
 **--prev-commit-author-avatar**="":
@@ -286,7 +532,7 @@ execute a local pipeline
 
 **--prev-pipeline-url**="":
 
-**--privileged**="": privileged plugins (default: "plugins/docker", "plugins/gcr", "plugins/ecr", "woodpeckerci/plugin-docker-buildx", "codeberg.org/woodpecker-plugins/docker-buildx")
+**--privileged**="": privileged plugins (default: [plugins/docker plugins/gcr plugins/ecr woodpeckerci/plugin-docker-buildx codeberg.org/woodpecker-plugins/docker-buildx])
 
 **--repo**="": full repo name
 
@@ -306,23 +552,23 @@ execute a local pipeline
 
 **--step-name**="": (default: 0)
 
-**--system-name**="":  (default: "woodpecker")
+**--system-name**="": (default: woodpecker)
 
 **--system-platform**="":
 
-**--system-url**="":  (default: "https://github.com/woodpecker-ci/woodpecker")
+**--system-url**="": (default: https://github.com/woodpecker-ci/woodpecker)
 
 **--timeout**="": pipeline timeout (default: 1h0m0s)
 
-**--volumes**="": pipeline volumes
+**--volumes**="": pipeline volumes (default: [])
 
 **--workflow-name**="": (default: 0)
 
 **--workflow-number**="": (default: 0)
 
-**--workspace-base**="":  (default: "/woodpecker")
+**--workspace-base**="": (default: /woodpecker)
 
-**--workspace-path**="":  (default: "src")
+**--workspace-path**="": (default: src)
 
 ## info
 
@@ -336,7 +582,7 @@ manage registries
 
 adds a registry
 
-**--hostname**="": registry hostname (default: "docker.io")
+**--hostname**="": registry hostname (default: docker.io)
 
 **--password**="": registry password
 
@@ -348,7 +594,7 @@ adds a registry
 
 remove a registry
 
-**--hostname**="": registry hostname (default: "docker.io")
+**--hostname**="": registry hostname (default: docker.io)
 
 **--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
 
@@ -356,7 +602,7 @@ remove a registry
 
 update a registry
 
-**--hostname**="": registry hostname (default: "docker.io")
+**--hostname**="": registry hostname (default: docker.io)
 
 **--password**="": registry password
 
@@ -368,7 +614,7 @@ update a registry
 
 display registry info
 
-**--hostname**="": registry hostname (default: "docker.io")
+**--hostname**="": registry hostname (default: docker.io)
 
 **--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
 
@@ -386,11 +632,11 @@ manage secrets
 
 adds a secret
 
-**--event**="": secret limited to these events
+**--event**="": secret limited to these events (default: [])
 
 **--global**: global secret
 
-**--image**="": secret limited to these images
+**--image**="": secret limited to these images (default: [])
 
 **--name**="": secret name
 
@@ -416,11 +662,11 @@ remove a secret
 
 update a secret
 
-**--event**="": secret limited to these events
+**--event**="": secret limited to these events (default: [])
 
 **--global**: global secret
 
-**--image**="": secret limited to these images
+**--image**="": secret limited to these images (default: [])
 
 **--name**="": secret name
 
@@ -452,64 +698,6 @@ list secrets
 
 **--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world)
 
-## repo
-
-manage repositories
-
-### ls
-
-list all repos
-
-**--format**="": format output (default: "\x1b[33m{{ .FullName }}\x1b[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }})")
-
-**--org**="": filter by organization
-
-### info
-
-show repository details
-
-**--format**="": format output (default: "Owner: {{ .Owner }}\nRepo: {{ .Name }}\nURL: {{ .ForgeURL }}\nConfig path: {{ .Config }}\nVisibility: {{ .Visibility }}\nPrivate: {{ .IsSCMPrivate }}\nTrusted: {{ .IsTrusted }}\nGated: {{ .IsGated }}\nClone url: {{ .Clone }}\nAllow pull-requests: {{ .AllowPullRequests }}\n")
-
-### add
-
-add a repository
-
-### update
-
-update a repository
-
-**--config**="": repository configuration path (e.g. .woodpecker.yml)
-
-**--gated**: repository is gated
-
-**--pipeline-counter**="": repository starting pipeline number (default: 0)
-
-**--timeout**="": repository timeout (default: 0s)
-
-**--trusted**: repository is trusted
-
-**--unsafe**: validate updating the pipeline-counter is unsafe
-
-**--visibility**="": repository visibility
-
-### rm
-
-remove a repository
-
-### repair
-
-repair repository webhooks
-
-### chown
-
-assume ownership of a repository
-
-### sync
-
-synchronize the repository list
-
-**--format**="": format output (default: "\x1b[33m{{ .FullName }}\x1b[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }})")
-
 ## user
 
 manage users
@@ -518,13 +706,14 @@ manage users
 
 list all users
 
-**--format**="": format output (default: "{{ .Login }}")
+**--format**="": format output (default: {{ .Login }})
 
 ### info
 
 show user details
 
-**--format**="": format output (default: "User: {{ .Login }}\nEmail: {{ .Email }}")
+**--format**="": format output (default: User: {{ .Login }}
+Email: {{ .Email }})
 
 ### add
 
@@ -598,7 +787,7 @@ list cron jobs
 
 setup the woodpecker-cli for the first time
 
-**--server-url**="": The URL of the woodpecker server
+**--server**="": The URL of the woodpecker server
 
 **--token**="": The token to authenticate with the woodpecker server
 

docs/versioned_docs/version-2.8/50-about.md

@@ -0,0 +1,18 @@
+# About
+
+Woodpecker has been originally forked from Drone 0.8 as the Drone CI license was changed after the 0.8 release from Apache 2.0 to a proprietary license. Woodpecker is based on this latest freely available version.
+
+## History
+
+Woodpecker was originally forked by [@laszlocph](https://github.com/laszlocph) in 2019.
+
+A few important time points:
+
+- [`2fbaa56`](https://github.com/woodpecker-ci/woodpecker/commit/2fbaa56eee0f4be7a3ca4be03dbd00c1bf5d1274) is the first commit of the fork, made on Apr 3, 2019.
+- The first release [v0.8.91](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.8.91) was published on Apr 6, 2019.
+- On Aug 27, 2019, the project was renamed to "Woodpecker" ([`630c383`](https://github.com/woodpecker-ci/woodpecker/commit/630c383181b10c4ec375e500c812c4b76b3c52b8)).
+- The first release under the name "Woodpecker" was published on Sep 9, 2019 ([v0.8.104](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.8.104)).
+
+## Differences to Drone
+
+Woodpecker is a community-focused software that still stay free and open source forever, while Drone is managed by [Harness](https://harness.io/) and published under [Polyform Small Business](https://polyformproject.org/licenses/small-business/1.0.0/) license.

docs/versioned_docs/version-2.8/91-migrations.md

@@ -2,8 +2,16 @@
 
 Some versions need some changes to the server configuration or the pipeline configuration files.
 
+<!--
+## 3.0.0
+
+- Update all webhooks by pressing the "Repair all" button in the admin settings as the webhook token claims have changed
+
+-->
+
 ## `next`
 
+- Deprecated `gated` repo settings option, use `require-approval`
 - Deprecated `steps.[name].group` in favor of `steps.[name].depends_on` (see [workflow syntax](./20-usage/20-workflow-syntax.md#depends_on) to learn how to set dependencies)
 - Removed `WOODPECKER_ROOT_PATH` and `WOODPECKER_ROOT_URL` config variables. Use `WOODPECKER_HOST` with a path instead
 - Pipelines without a config file will now be skipped instead of failing
@@ -30,7 +38,7 @@ Some versions need some changes to the server configuration or the pipeline conf
 
 ## 1.0.0
 
-- The signature used to verify extension calls (like those used for the [config-extension](./30-administration/100-external-configuration-api.md)) done by the Woodpecker server switched from using a shared-secret HMac to an ed25519 key-pair. Read more about it at the [config-extensions](./30-administration/100-external-configuration-api.md) documentation.
+- The signature used to verify extension calls (like those used for the [config-extension](./30-administration/40-advanced/100-external-configuration-api.md)) done by the Woodpecker server switched from using a shared-secret HMac to an ed25519 key-pair. Read more about it at the [config-extensions](./30-administration/40-advanced/100-external-configuration-api.md) documentation.
 - Refactored support for old agent filter labels and expressions. Learn how to use the new [filter](./20-usage/20-workflow-syntax.md#labels)
 - Renamed step environment variable `CI_SYSTEM_ARCH` to `CI_SYSTEM_PLATFORM`. Same applies for the cli exec variable.
 - Renamed environment variables `CI_BUILD_*` and `CI_PREV_BUILD_*` to `CI_PIPELINE_*` and `CI_PREV_PIPELINE_*`, old ones are still available but deprecated

docs/versioned_docs/version-2.8/92-awesome.md

@@ -43,7 +43,7 @@ If you have some missing resources, please feel free to [open a pull-request](ht
 
 - [Setup Gitea with Woodpecker CI](https://containers.fan/posts/setup-gitea-with-woodpecker-ci/)
 - [Step-by-step guide to modern, secure and Open-source CI setup](https://devforth.io/blog/step-by-step-guide-to-modern-secure-ci-setup/)
-- [Using Woodpecker CI for my static sites](https://web.archive.org/web/20240212182516/https://jan.wildeboer.net/2022/07/Woodpecker-CI-Jekyll/)
+- [Using Woodpecker CI for my static sites](https://jan.wildeboer.net/2022/07/Woodpecker-CI-Jekyll/)
 - [Woodpecker CI @ Codeberg](https://www.sarkasti.eu/articles/post/woodpecker/)
 - [Deploy Docker/Compose using Woodpecker CI](https://hinty.io/vverenko/deploy-docker-compose-using-woodpecker-ci/)
 - [Installing Woodpecker CI in your personal homelab](https://pwa.io/articles/installing-woodpecker-in-your-homelab/)

docs/versioned_docs/version-2.8/92-development/02-core-ideas.md

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

docs/versioned_docs/version-2.8/92-development/03-ui.md

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

docs/versioned_docs/version-2.8/92-development/06-conventions.md

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

docs/versioned_docs/version-2.8/92-development/09-testing.md

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

docs/versions.json

@@ -1 +1 @@
-["2.7", "2.6", "2.5", "1.0"]
+["2.8", "2.7", "2.6", "1.0"]