Improve migration notes (#4291)

.cspell.json

@@ -245,7 +245,6 @@
     "**/testdata/**",
     "docs/versioned_docs/",
     "package.json",
-    "91-migrations.md",
     // generated
     "go.sum",
     "flake.lock",

docs/blog/2023-11-09-release-v2.0.0/index.md

@@ -53,7 +53,7 @@ Security is pretty important to us and we want to make sure that no one can stea
 
 ## Migration notes
 
-There have been a few more breaking changes. [Read more about what you need to do when upgrading!](../docs/migrations#200)
+There have been a few more breaking changes. [Read more about what you need to do when upgrading!](/migrations#200)
 
 ## New features
 

docs/blog/2023-12-12-podman-image-builds/index.md

@@ -14,6 +14,8 @@ tags: [community, image, podman]
 
 I run Woodpecker CI with podman backend instead of docker and just figured out how to build images with buildah. Since I couldn't find this anywhere documented, I thought I might as well just share it here.
 
+<!-- truncate -->
+
 It's actually pretty straight forward. Here's what my repository structure looks like:
 
 ```bash

docs/blog/2023-12-13-debug-pipeline-steps/index.md

@@ -15,6 +15,8 @@ tags: [community, debug]
 Sometimes you want to debug a pipeline.
 Therefore I recently discovered: <https://github.com/ekzhang/sshx>
 
+<!-- truncate -->
+
 A simple step like should allow you to debug:
 
 ```yaml

docs/blog/2023-12-15-podman-sigstore/index.md

@@ -14,6 +14,8 @@ tags: [community, image, podman, sigstore, signature]
 
 This example shows how to build a container image with podman while verifying the base image and signing the resulting image.
 
+<!-- truncate -->
+
 The image being pulled uses a keyless signature, while the image being built will be signed by a pre-generated private key.
 
 ## Prerequisites

docs/blog/2024-05-27-release-v2.5.0/index.md

@@ -87,4 +87,4 @@ be removed in the next major release:
 - Use `WOODPECKER_EXPERT_FORGE_OAUTH_HOST` instead of `WOODPECKER_DEV_GITEA_OAUTH_URL` or `WOODPECKER_DEV_OAUTH_HOST`
 - Deprecated `WOODPECKER_WEBHOOK_HOST` in favor of `WOODPECKER_EXPERT_WEBHOOK_HOST`
 
-For a full list of deprecations that will be dropped in the `next` major release `3.0.0` (no eta yet), please check the [migrations](/docs/migrations#next) section.
+For a full list of deprecations that will be dropped in the `next` major release `3.0.0` (no eta yet), please check the [migrations](/migrations#next) section.

docs/docs/30-administration/05-deployment-methods/40-nixos.md

@@ -87,4 +87,4 @@ All configuration options can be found via [NixOS Search](https://search.nixos.o
 
 ## Tips and tricks
 
-There are some resources on how to utilize Woodpecker more effectively with NixOS on the [Awesome Woodpecker](../../92-awesome.md) page, like using the runners nix-store in the pipeline.
+There are some resources on how to utilize Woodpecker more effectively with NixOS on the [Awesome Woodpecker](/awesome) page, like using the runners nix-store in the pipeline.

docs/docusaurus.config.ts

@@ -50,13 +50,13 @@ const config: Config = {
           position: 'left',
           items: [
             {
-              to: '/docs/next/migrations', // Always point to newest migration guide
+              to: '/migrations', // Always point to newest migration guide
-              activeBaseRegex: 'docs/(next/)?migrations',
+              activeBaseRegex: 'migrations',
               label: 'Migrations',
             },
             {
-              to: '/docs/next/awesome', // Always point to newest awesome list
+              to: '/awesome', // Always point to newest awesome list
-              activeBaseRegex: 'docs/(next/)?awesome',
+              activeBaseRegex: 'awesome',
               label: 'Awesome',
             },
             {

docs/src/pages/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/src/pages/migrations.md

@@ -1,50 +1,79 @@
 # Migrations
 
-Some versions need some changes to the server configuration or the pipeline configuration files.
+Some versions need some changes to the server configuration or the pipeline configuration files. If you are an user check the `User migrations` section of an version. As an admin of a Woodpecker server or agent check the `Admin migrations` section.
 
 ## `next`
 
-- Deprecate `WOODPECKER_FILTER_LABELS` use `WOODPECKER_AGENT_LABELS`
+:::info
+This will be the next version of Woodpecker.
+:::
+
+## User migrations
+
 - Removed built-in environment variables:
   - `CI_COMMIT_URL` use `CI_PIPELINE_FORGE_URL`
   - `CI_STEP_FINISHED` as empty during execution
   - `CI_PIPELINE_FINISHED` as empty during execution
   - `CI_PIPELINE_STATUS` was always `success`
   - `CI_STEP_STATUS` was always `success`
-- Set `/woodpecker` as defautl workdir for the **woodpecker-cli** container
+- Set `/woodpecker` as default workdir for the **woodpecker-cli** container
-- Move docker resource limit settings from server into agent configuration
-- Rename server environment variable `WOODPECKER_ESCALATE` to `WOODPECKER_PLUGINS_PRIVILEGED`
-- All default privileged plugins (like `woodpeckerci/plugin-docker-buildx`) were removed. Please carefully [re-add those plugins](./30-administration/10-server-config.md#woodpecker_plugins_privileged) you trust and rely on.
-- `WOODPECKER_DEFAULT_CLONE_IMAGE` got depricated use `WOODPECKER_DEFAULT_CLONE_PLUGIN`
-- Check trusted-clone- and privileged-plugins by image name and tag (if tag is set)
 - Secret filters for plugins now check against tag if specified
-- Removed `WOODPECKER_DEV_OAUTH_HOST` and `WOODPECKER_DEV_GITEA_OAUTH_URL` use `WOODPECKER_EXPERT_FORGE_OAUTH_HOST`
 - Compatibility mode of deprecated `pipeline:`, `platform:` and `branches:` pipeline config options are now removed and pipeline will now fail if still in use.
-- Removed `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 `steps.[name].group` in favor of `steps.[name].depends_on` (see [workflow syntax](/docs/usage/workflow-syntax#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
-- Removed implicitly defined `regcred` image pull secret name. Set it explicitly via `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES`
 - Removed `includes` and `excludes` support from **event** filter
-- Removed uppercasing all secret env vars, instead, the value of the `secrets` property is used. [Read more](./20-usage/40-secrets.md#usage)
+- Removed upper-casing all secret env vars, instead, the value of the `secrets` property is used. [Read more](/docs/usage/secrets#usage)
 - Removed alternative names for secrets, use `environment` with `from_secret`
-- Removed slice definition for env vars
 - Removed `environment` filter, use `when.evaluate`
 - Removed `WOODPECKER_WEBHOOK_HOST` in favor of `WOODPECKER_EXPERT_WEBHOOK_HOST`
-- Migrated to rfc9421 for webhook signatures
 - Renamed `start_time`, `end_time`, `created_at`, `started_at`, `finished_at` and `reviewed_at` JSON fields to `started`, `finished`, `created`, `started`, `finished`, `reviewed`
 - JSON field `trusted` on repo model was changed from boolean to object
 - Update all webhooks by pressing the "Repair all" button in the admin settings as the webhook token claims have changed
 - Crons now use standard Linux syntax without seconds
-- Replaced `configs` object by `netrc` in external configuration APIs
 - Removed old API routes: `registry/` -> `registries`, `/authorize/token`
 - Replaced `registry` command with `repo registry` in cli
-- Disallow upgrades from 1.x, upgrade to 2.x first
 - Deprecated `secrets`, use `environment` with `from_secret`
 
+## Admin migrations
+
+- Deprecate `WOODPECKER_FILTER_LABELS` use `WOODPECKER_AGENT_LABELS`
+- Move docker resource limit settings from server into agent configuration
+- Rename server environment variable `WOODPECKER_ESCALATE` to `WOODPECKER_PLUGINS_PRIVILEGED`
+- All default privileged plugins (like `woodpeckerci/plugin-docker-buildx`) were removed. Please carefully [re-add those plugins](/docs/next/administration/server-config#woodpecker_plugins_privileged) you trust and rely on.
+- `WOODPECKER_DEFAULT_CLONE_IMAGE` got deprecated use `WOODPECKER_DEFAULT_CLONE_PLUGIN`
+- Check trusted-clone- and privileged-plugins by image name and tag (if tag is set)
+- Removed `WOODPECKER_DEV_OAUTH_HOST` and `WOODPECKER_DEV_GITEA_OAUTH_URL` use `WOODPECKER_EXPERT_FORGE_OAUTH_HOST`
+- Removed `WOODPECKER_ROOT_PATH` and `WOODPECKER_ROOT_URL` config variables. Use `WOODPECKER_HOST` with a path instead
+- Removed implicitly defined `regcred` image pull secret name. Set it explicitly via `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES`
+- Removed slice definition for env vars
+- Migrated to rfc9421 for webhook signatures
+- Replaced `configs` object by `netrc` in external configuration APIs
+- Disallow upgrades from 1.x, upgrade to 2.x first
+
+## 2.7.2
+
+To secure your instance, set `WOODPECKER_PLUGINS_PRIVILEGED` to only allow specific versions of the `woodpeckerci/plugin-docker-buildx` plugin, use version 5.0.0 or above. This prevents older, potentially unstable versions from being privileged.
+
+For example, to allow only version 5.0.0, use:
+
+```bash
+WOODPECKER_PLUGINS_PRIVILEGED=woodpeckerci/plugin-docker-buildx:5.0.0
+```
+
+To allow multiple versions, you can separate them with commas:
+
+```bash
+WOODPECKER_PLUGINS_PRIVILEGED=woodpeckerci/plugin-docker-buildx:5.0.0,woodpeckerci/plugin-docker-buildx:5.1.0
+```
+
+This setup ensures only specified, stable plugin versions are given privileged access.
+
+Read more about it in [#4213](https://github.com/woodpecker-ci/woodpecker/pull/4213)
+
 ## 2.0.0
 
 - Dropped deprecated `CI_BUILD_*`, `CI_PREV_BUILD_*`, `CI_JOB_*`, `*_LINK`, `CI_SYSTEM_ARCH`, `CI_REPO_REMOTE` built-in environment variables
-- Deprecated `platform:` filter in favor of `labels:`, [read more](./20-usage/20-workflow-syntax.md#filter-by-platform)
+- Deprecated `platform:` filter in favor of `labels:`, [read more](/docs/usage/workflow-syntax#filter-by-platform)
 - Secrets `event` property was renamed to `events` and `image` to `images` as both are lists. The new property `events` / `images` has to be used in the api. The old properties `event` and `image` were removed.
 - The secrets `plugin_only` option was removed. Secrets with images are now always only available for plugins using listed by the `images` property. Existing secrets with a list of `images` will now only be available to the listed images if they are used as a plugin.
 - Removed `build` alias for `pipeline` command in CLI
@@ -56,8 +85,8 @@ 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/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.
+- The signature used to verify extension calls (like those used for the [config-extension](/docs/administration/advanced/external-configuration-api)) 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](/docs/administration/advanced/external-configuration-api) documentation.
-- Refactored support for old agent filter labels and expressions. Learn how to use the new [filter](./20-usage/20-workflow-syntax.md#labels)
+- Refactored support for old agent filter labels and expressions. Learn how to use the new [filter](/docs/usage/workflow-syntax#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
 - Renamed environment variables `CI_JOB_*` to `CI_STEP_*`, old ones are still available but deprecated
@@ -66,7 +95,7 @@ Some versions need some changes to the server configuration or the pipeline conf
 - Renamed API endpoints for pipelines (`<owner>/<repo>/builds/<buildId>` -> `<owner>/<repo>/pipelines/<pipelineId>`), old ones are still available but deprecated
 - Updated Prometheus gauge `build_*` to `pipeline_*`
 - Updated Prometheus gauge `*_job_*` to `*_step_*`
-- Renamed config env `WOODPECKER_MAX_PROCS` to `WOODPECKER_MAX_WORKFLOWS` (still available as fallback)
+- Renamed config env `WOODPECKER_MAX_PROCS` to `WOODPECKER_MAX_WORKFLOWS` (still available as fallback) <!-- cspell:ignore PROCS -->
 - The pipelines are now also read from `.yaml` files, the new default order is `.woodpecker/*.yml` and `.woodpecker/*.yaml` (without any prioritization) -> `.woodpecker.yml` -> `.woodpecker.yaml`
 - Dropped support for [Coding](https://coding.net/), [Gogs](https://gogs.io) and Bitbucket Server (Stash).
 - `/api/queue/resume` & `/api/queue/pause` endpoint methods were changed from `GET` to `POST`
@@ -95,7 +124,7 @@ Some versions need some changes to the server configuration or the pipeline conf
 
   Only projects created after updating will have an empty value by default. Existing projects will stick to the current pipeline path which is `.drone.yml` in most cases.
 
-  Read more about it at the [Project Settings](./20-usage/75-project-settings.md#pipeline-path)
+  Read more about it at the [Project Settings](/docs/usage/project-settings#pipeline-path)
 
 - From version `0.15.0` ongoing there will be three types of docker images: `latest`, `next` and `x.x.x` with an alpine variant for each type like `latest-alpine`.
   If you used `latest` before to try pre-release features you should switch to `next` after this release.
@@ -130,7 +159,7 @@ Some versions need some changes to the server configuration or the pipeline conf
     - CI_SOURCE_BRANCH => use CI_COMMIT_SOURCE_BRANCH
     - CI_TARGET_BRANCH => use CI_COMMIT_TARGET_BRANCH
 
-  For all available variables and their descriptions have a look at [built-in-environment-variables](./20-usage/50-environment.md#built-in-environment-variables).
+  For all available variables and their descriptions have a look at [built-in-environment-variables](/docs/usage/environment#built-in-environment-variables).
 
 - Prometheus metrics have been changed from `drone_*` to `woodpecker_*`
 

docs/src/pages/versions.md

@@ -19,7 +19,7 @@ the actual release will be about a week later.
 
 ### Deprecations & migrations
 
-All deprecations and migrations for Woodpecker users and instance admins are documented in the [migration guide](/docs/next/migrations).
+All deprecations and migrations for Woodpecker users and instance admins are documented in the [migration guide](/migrations).
 
 ## Next version (current state of the `main` branch)
 
@@ -33,7 +33,11 @@ Here you can find documentation for previous versions of Woodpecker.
 
 |         |            |                                                                                       |
 | ------- | ---------- | ------------------------------------------------------------------------------------- |
-| 2.6.0   | 2024-07-18 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.6.0/docs/docs/)   |
+| 2.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/)   |
+| 2.6.1   | 2024-07-19 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.6.1/docs/docs/)   |
+| 2.6.0   | 2024-06-13 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.6.0/docs/docs/)   |
 | 2.5.0   | 2024-06-01 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.5.0/docs/docs/)   |
 | 2.4.1   | 2024-03-20 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.4.1/docs/docs/)   |
 | 2.4.0   | 2024-03-19 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.4.0/docs/docs/)   |