From 57c4ee1bc9e9491b7f12f6cdad76980a0b68f111 Mon Sep 17 00:00:00 2001 From: Anbraten <6918444+anbraten@users.noreply.github.com> Date: Tue, 18 Nov 2025 13:22:50 +0100 Subject: [PATCH] Add docs for 3.12 (#5763) --- .woodpecker/docs.yaml | 20 +- docs/src/pages/versions.md | 1 + .../10-intro/index.md | 0 .../20-usage/10-intro.md | 0 .../20-usage/100-troubleshooting.md | 0 .../15-terminology/architecture.excalidraw | 0 .../20-usage/15-terminology/architecture.svg | 0 .../20-usage/15-terminology/index.md | 0 .../pipeline-workflow-step.excalidraw | 0 .../15-terminology/pipeline-workflow-step.svg | 0 .../20-usage/20-workflow-syntax.md | 3 +- .../20-usage/25-workflows.md | 0 .../20-usage/30-matrix-workflows.md | 0 .../20-usage/40-secrets.md | 0 .../20-usage/41-registries.md | 0 .../20-usage/45-cron.md | 0 .../version-3.12/20-usage/50-environment.md | 259 +++++++++++++++ .../51-plugins/20-creating-plugins.md | 0 .../20-usage/51-plugins/51-overview.md | 0 .../20-usage/51-plugins/_category_.yaml | 0 .../20-usage/60-services.md | 0 .../20-usage/70-volumes.md | 0 .../40-configuration-extension.md | 160 ++++++++++ .../20-usage/72-extensions/_category_.yaml | 7 + .../20-usage/72-extensions/index.md | 34 ++ .../20-usage/72-linter.md | 0 .../20-usage/75-project-settings.md | 0 .../20-usage/80-badges.md | 0 .../20-usage/90-advanced-usage.md | 0 .../20-usage/_category_.yaml | 0 .../20-usage/cron-settings.png | Bin .../20-usage/linter-warnings-errors.png | Bin .../20-usage/pipeline.png | Bin .../20-usage/project-settings.png | Bin .../20-usage/repo-new.png | Bin .../20-usage/secrets-plugins-filter.png | Bin .../30-administration/00-general.md | 0 .../05-installation/10-docker-compose.md | 0 .../05-installation/20-helm-chart.md | 21 +- .../05-installation/30-packages.md | 1 + .../05-installation/_category_.yaml | 0 .../10-configuration/10-server.md | 29 +- .../10-configuration/100-addons.md | 42 +++ .../10-configuration/11-backends/10-docker.md | 0 .../11-backends/20-kubernetes.md | 38 +++ .../10-configuration/11-backends/30-local.md | 0 .../10-configuration/11-backends/50-custom.md | 0 .../11-backends/_category_.yaml | 0 .../10-configuration/12-forges/11-overview.md | 18 ++ .../10-configuration/12-forges/20-github.md | 0 .../10-configuration/12-forges/30-gitea.md | 0 .../10-configuration/12-forges/35-forgejo.md | 0 .../10-configuration/12-forges/40-gitlab.md | 0 .../12-forges/50-bitbucket.md | 4 + .../12-forges/60-bitbucket_datacenter.md | 10 + .../12-forges/_category_.yaml | 0 .../12-forges/bitbucket_oauth.png | Bin .../12-forges/bitbucket_permissions.png | Bin .../12-forges/gitea_oauth.gif | Bin .../12-forges/github_oauth.png | Bin .../10-configuration/30-agent.md | 3 +- .../10-configuration/40-autoscaler.md | 0 .../10-configuration/_category_.yaml | 0 .../10-configuration/new-agent-connected.png | Bin .../10-configuration/new-agent-created.png | Bin .../new-agent-registration.png | Bin .../30-administration/_category_.yaml | 0 .../{version-3.9 => version-3.12}/40-cli.md | 297 +++++++----------- .../92-development/01-getting-started.md | 0 .../92-development/02-core-ideas.md | 2 +- .../92-development/03-ui.md | 0 .../92-development/04-docs.md | 0 .../92-development/05-architecture.md | 0 .../92-development/06-conventions.md | 0 .../92-development/07-guides.md | 0 .../92-development/08-translations.md | 0 .../92-development/09-openapi.md | 0 .../92-development/09-testing.md | 0 .../92-development/100-addons.md} | 39 +-- .../92-development/_category_.yaml | 0 .../92-development/ui-proxy.svg | 0 .../92-development/vscode-debug.png | Bin .../92-development/vscode-run-test.png | Bin .../woodpecker-architecture.png | Bin .../version-3.9/20-usage/50-environment.md | 225 ------------- .../10-configuration/12-forges/11-overview.md | 15 - ...debars.json => version-3.12-sidebars.json} | 0 docs/versions.json | 2 +- 88 files changed, 743 insertions(+), 487 deletions(-) rename docs/versioned_docs/{version-3.9 => version-3.12}/10-intro/index.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/10-intro.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/100-troubleshooting.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/15-terminology/architecture.excalidraw (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/15-terminology/architecture.svg (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/15-terminology/index.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/15-terminology/pipeline-workflow-step.excalidraw (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/15-terminology/pipeline-workflow-step.svg (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/20-workflow-syntax.md (99%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/25-workflows.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/30-matrix-workflows.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/40-secrets.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/41-registries.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/45-cron.md (100%) create mode 100644 docs/versioned_docs/version-3.12/20-usage/50-environment.md rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/51-plugins/20-creating-plugins.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/51-plugins/51-overview.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/51-plugins/_category_.yaml (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/60-services.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/70-volumes.md (100%) create mode 100644 docs/versioned_docs/version-3.12/20-usage/72-extensions/40-configuration-extension.md create mode 100644 docs/versioned_docs/version-3.12/20-usage/72-extensions/_category_.yaml create mode 100644 docs/versioned_docs/version-3.12/20-usage/72-extensions/index.md rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/72-linter.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/75-project-settings.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/80-badges.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/90-advanced-usage.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/_category_.yaml (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/cron-settings.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/linter-warnings-errors.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/pipeline.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/project-settings.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/repo-new.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/20-usage/secrets-plugins-filter.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/00-general.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/05-installation/10-docker-compose.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/05-installation/20-helm-chart.md (73%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/05-installation/30-packages.md (98%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/05-installation/_category_.yaml (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/10-server.md (97%) create mode 100644 docs/versioned_docs/version-3.12/30-administration/10-configuration/100-addons.md rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/11-backends/10-docker.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/11-backends/20-kubernetes.md (92%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/11-backends/30-local.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/11-backends/50-custom.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/11-backends/_category_.yaml (100%) create mode 100644 docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/11-overview.md rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/12-forges/20-github.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/12-forges/30-gitea.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/12-forges/35-forgejo.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/12-forges/40-gitlab.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/12-forges/50-bitbucket.md (85%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.md (87%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/12-forges/_category_.yaml (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/12-forges/bitbucket_oauth.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/12-forges/bitbucket_permissions.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/12-forges/gitea_oauth.gif (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/12-forges/github_oauth.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/30-agent.md (95%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/40-autoscaler.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/_category_.yaml (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/new-agent-connected.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/new-agent-created.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/10-configuration/new-agent-registration.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/30-administration/_category_.yaml (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/40-cli.md (70%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/01-getting-started.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/02-core-ideas.md (85%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/03-ui.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/04-docs.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/05-architecture.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/06-conventions.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/07-guides.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/08-translations.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/09-openapi.md (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/09-testing.md (100%) rename docs/versioned_docs/{version-3.9/30-administration/10-configuration/12-forges/100-addon.md => version-3.12/92-development/100-addons.md} (54%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/_category_.yaml (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/ui-proxy.svg (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/vscode-debug.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/vscode-run-test.png (100%) rename docs/versioned_docs/{version-3.9 => version-3.12}/92-development/woodpecker-architecture.png (100%) delete mode 100644 docs/versioned_docs/version-3.9/20-usage/50-environment.md delete mode 100644 docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/11-overview.md rename docs/versioned_sidebars/{version-3.9-sidebars.json => version-3.12-sidebars.json} (100%) diff --git a/.woodpecker/docs.yaml b/.woodpecker/docs.yaml index 2d7795fe6..1da4213fd 100644 --- a/.woodpecker/docs.yaml +++ b/.woodpecker/docs.yaml @@ -37,7 +37,7 @@ when: evaluate: 'TASK == "docs"' steps: - install-dependencies: + - name: install-dependencies image: *node_image directory: docs/ commands: @@ -48,7 +48,7 @@ steps: event: [tag, pull_request, push] - event: manual - format-check: + - name: format-check image: *node_image directory: docs/ commands: @@ -58,7 +58,7 @@ steps: - path: *when_path event: pull_request - build-cli: + - name: build-cli image: *golang_image commands: - make generate-docs @@ -67,7 +67,7 @@ steps: event: [tag, pull_request, push] - event: manual - build: + - name: build image: *node_image directory: docs/ commands: @@ -78,7 +78,7 @@ steps: event: [tag, pull_request, push] - event: manual - deploy-preview: + - name: deploy-preview image: docker.io/woodpeckerci/plugin-surge-preview:1.4.1 settings: path: 'docs/build/' @@ -91,7 +91,7 @@ steps: - event: [pull_request, pull_request_closed] path: *when_path - deploy-prepare: + - name: deploy-prepare image: *alpine_image environment: BOT_PRIVATE_KEY: @@ -112,7 +112,7 @@ steps: - event: [manual, tag] # update latest and next version - version-next: + - name: version-next image: *alpine_image commands: - apk add jq @@ -123,7 +123,7 @@ steps: path: *docker_path branch: ${CI_REPO_DEFAULT_BRANCH} - version-release: + - name: version-release image: *alpine_image commands: - apk add jq @@ -133,7 +133,7 @@ steps: when: - event: tag - copy-files: + - name: copy-files image: *alpine_image commands: - apk add rsync @@ -145,7 +145,7 @@ steps: branch: ${CI_REPO_DEFAULT_BRANCH} - event: manual - deploy: + - name: deploy image: *alpine_image environment: BOT_PRIVATE_KEY: diff --git a/docs/src/pages/versions.md b/docs/src/pages/versions.md index f8457ba2c..6c5064680 100644 --- a/docs/src/pages/versions.md +++ b/docs/src/pages/versions.md @@ -33,6 +33,7 @@ Here you can find documentation for previous versions of Woodpecker. | | | | | ------- | ---------- | ------------------------------------------------------------------------------------- | +| 3.12.0 | 2025-11-18 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.12.0/docs/docs/) | | 3.11.0 | 2025-10-19 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.11.0/docs/docs/) | | 3.10.0 | 2025-09-28 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.10.0/docs/docs/) | | 3.9.0 | 2025-08-20 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.9.0/docs/docs/) | diff --git a/docs/versioned_docs/version-3.9/10-intro/index.md b/docs/versioned_docs/version-3.12/10-intro/index.md similarity index 100% rename from docs/versioned_docs/version-3.9/10-intro/index.md rename to docs/versioned_docs/version-3.12/10-intro/index.md diff --git a/docs/versioned_docs/version-3.9/20-usage/10-intro.md b/docs/versioned_docs/version-3.12/20-usage/10-intro.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/10-intro.md rename to docs/versioned_docs/version-3.12/20-usage/10-intro.md diff --git a/docs/versioned_docs/version-3.9/20-usage/100-troubleshooting.md b/docs/versioned_docs/version-3.12/20-usage/100-troubleshooting.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/100-troubleshooting.md rename to docs/versioned_docs/version-3.12/20-usage/100-troubleshooting.md diff --git a/docs/versioned_docs/version-3.9/20-usage/15-terminology/architecture.excalidraw b/docs/versioned_docs/version-3.12/20-usage/15-terminology/architecture.excalidraw similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/15-terminology/architecture.excalidraw rename to docs/versioned_docs/version-3.12/20-usage/15-terminology/architecture.excalidraw diff --git a/docs/versioned_docs/version-3.9/20-usage/15-terminology/architecture.svg b/docs/versioned_docs/version-3.12/20-usage/15-terminology/architecture.svg similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/15-terminology/architecture.svg rename to docs/versioned_docs/version-3.12/20-usage/15-terminology/architecture.svg diff --git a/docs/versioned_docs/version-3.9/20-usage/15-terminology/index.md b/docs/versioned_docs/version-3.12/20-usage/15-terminology/index.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/15-terminology/index.md rename to docs/versioned_docs/version-3.12/20-usage/15-terminology/index.md diff --git a/docs/versioned_docs/version-3.9/20-usage/15-terminology/pipeline-workflow-step.excalidraw b/docs/versioned_docs/version-3.12/20-usage/15-terminology/pipeline-workflow-step.excalidraw similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/15-terminology/pipeline-workflow-step.excalidraw rename to docs/versioned_docs/version-3.12/20-usage/15-terminology/pipeline-workflow-step.excalidraw diff --git a/docs/versioned_docs/version-3.9/20-usage/15-terminology/pipeline-workflow-step.svg b/docs/versioned_docs/version-3.12/20-usage/15-terminology/pipeline-workflow-step.svg similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/15-terminology/pipeline-workflow-step.svg rename to docs/versioned_docs/version-3.12/20-usage/15-terminology/pipeline-workflow-step.svg diff --git a/docs/versioned_docs/version-3.9/20-usage/20-workflow-syntax.md b/docs/versioned_docs/version-3.12/20-usage/20-workflow-syntax.md similarity index 99% rename from docs/versioned_docs/version-3.9/20-usage/20-workflow-syntax.md rename to docs/versioned_docs/version-3.12/20-usage/20-workflow-syntax.md index 9c5c21d95..f97d87e4f 100644 --- a/docs/versioned_docs/version-3.9/20-usage/20-workflow-syntax.md +++ b/docs/versioned_docs/version-3.12/20-usage/20-workflow-syntax.md @@ -284,6 +284,7 @@ The available events are: - `push`: triggered when a commit is pushed to a branch. - `pull_request`: triggered when a pull request is opened or a new commit is pushed to it. - `pull_request_closed`: triggered when a pull request is closed or merged. +- `pull_request_metadata`: triggered when a pull request metadata has changed (e.g. title, body, label, milestone, ...). - `tag`: triggered when a tag is pushed. - `release`: triggered when a release, pre-release or draft is created. (You can apply further filters using [evaluate](#evaluate) with [environment variables](./50-environment.md#built-in-environment-variables).) - `deployment`: triggered when a deployment is created in the repository. (This event can be triggered from Woodpecker directly. GitHub also supports webhook triggers.) @@ -392,7 +393,7 @@ when: #### `path` :::info -Path conditions are applied only to **push** and **pull_request** events. This feature is currently available for all forges except Bitbucket Cloud. +Path conditions are applied only to **push** and **pull_request** events. ::: Execute a step only on a pipeline with certain files being changed: diff --git a/docs/versioned_docs/version-3.9/20-usage/25-workflows.md b/docs/versioned_docs/version-3.12/20-usage/25-workflows.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/25-workflows.md rename to docs/versioned_docs/version-3.12/20-usage/25-workflows.md diff --git a/docs/versioned_docs/version-3.9/20-usage/30-matrix-workflows.md b/docs/versioned_docs/version-3.12/20-usage/30-matrix-workflows.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/30-matrix-workflows.md rename to docs/versioned_docs/version-3.12/20-usage/30-matrix-workflows.md diff --git a/docs/versioned_docs/version-3.9/20-usage/40-secrets.md b/docs/versioned_docs/version-3.12/20-usage/40-secrets.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/40-secrets.md rename to docs/versioned_docs/version-3.12/20-usage/40-secrets.md diff --git a/docs/versioned_docs/version-3.9/20-usage/41-registries.md b/docs/versioned_docs/version-3.12/20-usage/41-registries.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/41-registries.md rename to docs/versioned_docs/version-3.12/20-usage/41-registries.md diff --git a/docs/versioned_docs/version-3.9/20-usage/45-cron.md b/docs/versioned_docs/version-3.12/20-usage/45-cron.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/45-cron.md rename to docs/versioned_docs/version-3.12/20-usage/45-cron.md diff --git a/docs/versioned_docs/version-3.12/20-usage/50-environment.md b/docs/versioned_docs/version-3.12/20-usage/50-environment.md new file mode 100644 index 000000000..b6d2690d9 --- /dev/null +++ b/docs/versioned_docs/version-3.12/20-usage/50-environment.md @@ -0,0 +1,259 @@ +# Environment variables + +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: + - name: 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: + - name: build + image: golang +- environment: +- - PATH=$PATH:/go + commands: ++ - export PATH=$PATH:/go + - go build + - go test +``` + +:::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: + - name: build + image: golang + commands: +- - export PATH=${PATH}:/go ++ - export PATH=$${PATH}:/go + - go build + - go test +``` + +## Built-in environment variables + +This is the reference list of all environment variables available to your pipeline containers. These are injected into your pipeline step and plugins containers, at runtime. + +| NAME | Description | Example | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | +| `CI` | CI environment name | `woodpecker` | +| | **Repository** | | +| `CI_REPO` | repository full name `/` | `john-doe/my-repo` | +| `CI_REPO_OWNER` | repository owner | `john-doe` | +| `CI_REPO_NAME` | repository name | `my-repo` | +| `CI_REPO_REMOTE_ID` | repository remote ID, is the UID it has in the forge | `82` | +| `CI_REPO_URL` | repository web URL | `https://git.example.com/john-doe/my-repo` | +| `CI_REPO_CLONE_URL` | repository clone URL | `https://git.example.com/john-doe/my-repo.git` | +| `CI_REPO_CLONE_SSH_URL` | repository SSH clone URL | `git@git.example.com:john-doe/my-repo.git` | +| `CI_REPO_DEFAULT_BRANCH` | repository default branch | `main` | +| `CI_REPO_PRIVATE` | repository is private | `true` | +| `CI_REPO_TRUSTED_NETWORK` | repository has trusted network access | `false` | +| `CI_REPO_TRUSTED_VOLUMES` | repository has trusted volumes access | `false` | +| `CI_REPO_TRUSTED_SECURITY` | repository has trusted security access | `false` | +| | **Current Commit** | | +| `CI_COMMIT_SHA` | commit SHA | `eba09b46064473a1d345da7abf28b477468e8dbd` | +| `CI_COMMIT_REF` | commit ref | `refs/heads/main` | +| `CI_COMMIT_REFSPEC` | commit ref spec | `issue-branch:main` | +| `CI_COMMIT_BRANCH` | commit branch (equals target branch for pull requests) | `main` | +| `CI_COMMIT_SOURCE_BRANCH` | commit source branch (set only for pull request events) | `issue-branch` | +| `CI_COMMIT_TARGET_BRANCH` | commit target branch (set only for pull request events) | `main` | +| `CI_COMMIT_TAG` | commit tag name (empty if event is not `tag`) | `v1.10.3` | +| `CI_COMMIT_PULL_REQUEST` | commit pull request number (set only for pull request events) | `1` | +| `CI_COMMIT_PULL_REQUEST_LABELS` | labels assigned to pull request (set only for pull request events) | `server` | +| `CI_COMMIT_PULL_REQUEST_MILESTONE` | milestone assigned to pull request (set only for `pull_request` and `pull_request_closed` events) | `summer-sprint` | +| `CI_COMMIT_MESSAGE` | commit message | `Initial commit` | +| `CI_COMMIT_AUTHOR` | commit author username | `john-doe` | +| `CI_COMMIT_AUTHOR_EMAIL` | commit author email address | `john-doe@example.com` | +| `CI_COMMIT_PRERELEASE` | release is a pre-release (empty if event is not `release`) | `false` | +| | **Current pipeline** | | +| `CI_PIPELINE_NUMBER` | pipeline number | `8` | +| `CI_PIPELINE_PARENT` | number of parent pipeline | `0` | +| `CI_PIPELINE_EVENT` | pipeline event (see [`event`](../20-usage/20-workflow-syntax.md#event)) | `push`, `pull_request`, `pull_request_closed`, `pull_request_metadata`, `tag`, `release`, `manual`, `cron` | +| `CI_PIPELINE_EVENT_REASON` | exact reason why `pull_request_metadata` event was send. it is forge instance specific and can change | `label_updated`, `milestoned`, `demilestoned`, `assigned`, `edited`, ... | +| `CI_PIPELINE_URL` | link to the web UI for the pipeline | `https://ci.example.com/repos/7/pipeline/8` | +| `CI_PIPELINE_FORGE_URL` | link to the forge's web UI for the commit(s) or tag that triggered the pipeline | `https://git.example.com/john-doe/my-repo/commit/eba09b46064473a1d345da7abf28b477468e8dbd` | +| `CI_PIPELINE_DEPLOY_TARGET` | pipeline deploy target for `deployment` events | `production` | +| `CI_PIPELINE_DEPLOY_TASK` | pipeline deploy task for `deployment` events | `migration` | +| `CI_PIPELINE_CREATED` | pipeline created UNIX timestamp | `1722617519` | +| `CI_PIPELINE_STARTED` | pipeline started UNIX timestamp | `1722617519` | +| `CI_PIPELINE_FILES` | changed files (empty if event is not `push` or `pull_request`), it is undefined if more than 500 files are touched | `[]`, `[".woodpecker.yml","README.md"]` | +| `CI_PIPELINE_AUTHOR` | pipeline author username | `octocat` | +| `CI_PIPELINE_AVATAR` | pipeline author avatar | `https://git.example.com/avatars/5dcbcadbce6f87f8abef` | +| | **Current workflow** | | +| `CI_WORKFLOW_NAME` | workflow name | `release` | +| | **Current step** | | +| `CI_STEP_NAME` | step name | `build package` | +| `CI_STEP_NUMBER` | step number | `0` | +| `CI_STEP_STARTED` | step started UNIX timestamp | `1722617519` | +| `CI_STEP_URL` | URL to step in UI | `https://ci.example.com/repos/7/pipeline/8` | +| | **Previous commit** | | +| `CI_PREV_COMMIT_SHA` | previous commit SHA | `15784117e4e103f36cba75a9e29da48046eb82c4` | +| `CI_PREV_COMMIT_REF` | previous commit ref | `refs/heads/main` | +| `CI_PREV_COMMIT_REFSPEC` | previous commit ref spec | `issue-branch:main` | +| `CI_PREV_COMMIT_BRANCH` | previous commit branch | `main` | +| `CI_PREV_COMMIT_SOURCE_BRANCH` | previous commit source branch (set only for pull request events) | `issue-branch` | +| `CI_PREV_COMMIT_TARGET_BRANCH` | previous commit target branch (set only for pull request events) | `main` | +| `CI_PREV_COMMIT_URL` | previous commit link in forge | `https://git.example.com/john-doe/my-repo/commit/15784117e4e103f36cba75a9e29da48046eb82c4` | +| `CI_PREV_COMMIT_MESSAGE` | previous commit message | `test` | +| `CI_PREV_COMMIT_AUTHOR` | previous commit author username | `john-doe` | +| `CI_PREV_COMMIT_AUTHOR_EMAIL` | previous commit author email address | `john-doe@example.com` | +| | **Previous pipeline** | | +| `CI_PREV_PIPELINE_NUMBER` | previous pipeline number | `7` | +| `CI_PREV_PIPELINE_PARENT` | previous pipeline number of parent pipeline | `0` | +| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (see [`event`](../20-usage/20-workflow-syntax.md#event)) | `push`, `pull_request`, `pull_request_closed`, `pull_request_metadata`, `tag`, `release`, `manual`, `cron` | +| `CI_PREV_PIPELINE_EVENT_REASON` | previous exact reason `pull_request_metadata` event was send. it is forge instance specific and can change | `label_updated`, `milestoned`, `demilestoned`, `assigned`, `edited`, ... | +| `CI_PREV_PIPELINE_URL` | previous pipeline link in CI | `https://ci.example.com/repos/7/pipeline/7` | +| `CI_PREV_PIPELINE_FORGE_URL` | previous pipeline link to event in forge | `https://git.example.com/john-doe/my-repo/commit/15784117e4e103f36cba75a9e29da48046eb82c4` | +| `CI_PREV_PIPELINE_DEPLOY_TARGET` | previous pipeline deploy target for `deployment` events | `production` | +| `CI_PREV_PIPELINE_DEPLOY_TASK` | previous pipeline deploy task for `deployment` events | `migration` | +| `CI_PREV_PIPELINE_STATUS` | previous pipeline status | `success`, `failure` | +| `CI_PREV_PIPELINE_CREATED` | previous pipeline created UNIX timestamp | `1722610173` | +| `CI_PREV_PIPELINE_STARTED` | previous pipeline started UNIX timestamp | `1722610173` | +| `CI_PREV_PIPELINE_FINISHED` | previous pipeline finished UNIX timestamp | `1722610383` | +| `CI_PREV_PIPELINE_AUTHOR` | previous pipeline author username | `octocat` | +| `CI_PREV_PIPELINE_AVATAR` | previous pipeline author avatar | `https://git.example.com/avatars/5dcbcadbce6f87f8abef` | +| |   | | +| `CI_WORKSPACE` | Path of the workspace where source code gets cloned to | `/woodpecker/src/git.example.com/john-doe/my-repo` | +| | **System** | | +| `CI_SYSTEM_NAME` | name of the CI system | `woodpecker` | +| `CI_SYSTEM_URL` | link to CI system | `https://ci.example.com` | +| `CI_SYSTEM_HOST` | hostname of CI server | `ci.example.com` | +| `CI_SYSTEM_VERSION` | version of the server | `2.7.0` | +| | **Forge** | | +| `CI_FORGE_TYPE` | name of forge | `bitbucket` , `bitbucket_dc` , `forgejo` , `gitea` , `github` , `gitlab` | +| `CI_FORGE_URL` | root URL of configured forge | `https://git.example.com` | +| | **Internal** - Please don't use! | | +| `CI_SCRIPT` | Internal script path. Used to call pipeline step commands. | | +| `CI_NETRC_USERNAME` | Credentials for private repos to be able to clone data. (Only available for specific images) | | +| `CI_NETRC_PASSWORD` | Credentials for private repos to be able to clone data. (Only available for specific images) | | +| `CI_NETRC_MACHINE` | Credentials for private repos to be able to clone data. (Only available for specific images) | | + +## Global environment variables + +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. + +```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: + - name: build +- image: golang:1.18 ++ image: golang:${GOLANG_VERSION} + commands: + - [...] +``` + +## String Substitution + +Woodpecker provides the ability to substitute environment variables at runtime. This gives us the ability to use dynamic settings, commands and filters in our pipeline configuration. + +Example commit substitution: + +```diff + steps: + - name: s3 + image: woodpeckerci/plugin-s3 + settings: ++ target: /target/${CI_COMMIT_SHA} +``` + +Example tag substitution: + +```diff + steps: + - name: s3 + image: woodpeckerci/plugin-s3 + settings: ++ target: /target/${CI_COMMIT_TAG} +``` + +## String Operations + +Woodpecker also emulates bash string operations. This gives us the ability to manipulate the strings prior to substitution. Example use cases might include substring and stripping prefix or suffix values. + +| OPERATION | DESCRIPTION | +| ------------------ | ------------------------------------------------ | +| `${param}` | parameter substitution | +| `${param,}` | parameter substitution with lowercase first char | +| `${param,,}` | parameter substitution with lowercase | +| `${param^}` | parameter substitution with uppercase first char | +| `${param^^}` | parameter substitution with uppercase | +| `${param:pos}` | parameter substitution with substring | +| `${param:pos:len}` | parameter substitution with substring and length | +| `${param=default}` | parameter substitution with default | +| `${param##prefix}` | parameter substitution with prefix removal | +| `${param%%suffix}` | parameter substitution with suffix removal | +| `${param/old/new}` | parameter substitution with find and replace | + +Example variable substitution with substring: + +```diff + steps: + - name: s3 + image: woodpeckerci/plugin-s3 + settings: ++ target: /target/${CI_COMMIT_SHA:0:8} +``` + +Example variable substitution strips `v` prefix from `v.1.0.0`: + +```diff + steps: + - name: s3 + image: woodpeckerci/plugin-s3 + settings: ++ target: /target/${CI_COMMIT_TAG##v} +``` + +## `pull_request_metadata` specific event reason values + +For the `pull_request_metadata` event, the exact reason a metadata change was detected is passe through in `CI_PIPELINE_EVENT_REASON`. + +**GitLab** merges metadata updates into one webhook. Event reasons are separated by `,` as a list. + +:::note +Event reason values are forge-specific and may change between versions. +::: + +| Event | GitHub | Gitea | Forgejo | GitLab | Bitbucket | Bitbucket Datacenter | Description | +| -------------------- | ------------------ | ------------------ | ------------------ | ------------------ | --------- | -------------------- | ------------------------------------------------------------------------------ | +| `assigned` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | Pull request was assigned to a user | +| `converted_to_draft` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Pull request was converted to a draft | +| `demilestoned` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | Pull request was removed from a milestone | +| `description_edited` | :x: | :x: | :x: | :white_check_mark: | :x: | :x: | Description edited | +| `edited` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | :x: | The title or body of a pull request was edited, or the base branch was changed | +| `label_added` | :x: | :x: | :x: | :white_check_mark: | :x: | :x: | Pull had no labels and now got label(s) added | +| `label_cleared` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | All labels removed | +| `label_updated` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | New label(s) added / label(s) changed | +| `locked` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Conversation on a pull request was locked | +| `milestoned` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | Pull request was added to a milestone | +| `ready_for_review` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Draft pull request was marked as ready for review | +| `review_requested` | :x: | :x: | :x: | :white_check_mark: | :x: | :x: | New review was requested | +| `title_edited` | :x: | :x: | :x: | :white_check_mark: | :x: | :x: | Title edited | +| `unassigned` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | User was unassigned from a pull request | +| `unlabeled` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Label was removed from a pull request | +| `unlocked` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Conversation on a pull request was unlocked | + +**Bitbucket** and **Bitbucket Datacenter** [are not supported at the moment](https://github.com/woodpecker-ci/woodpecker/pull/5214). diff --git a/docs/versioned_docs/version-3.9/20-usage/51-plugins/20-creating-plugins.md b/docs/versioned_docs/version-3.12/20-usage/51-plugins/20-creating-plugins.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/51-plugins/20-creating-plugins.md rename to docs/versioned_docs/version-3.12/20-usage/51-plugins/20-creating-plugins.md diff --git a/docs/versioned_docs/version-3.9/20-usage/51-plugins/51-overview.md b/docs/versioned_docs/version-3.12/20-usage/51-plugins/51-overview.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/51-plugins/51-overview.md rename to docs/versioned_docs/version-3.12/20-usage/51-plugins/51-overview.md diff --git a/docs/versioned_docs/version-3.9/20-usage/51-plugins/_category_.yaml b/docs/versioned_docs/version-3.12/20-usage/51-plugins/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/51-plugins/_category_.yaml rename to docs/versioned_docs/version-3.12/20-usage/51-plugins/_category_.yaml diff --git a/docs/versioned_docs/version-3.9/20-usage/60-services.md b/docs/versioned_docs/version-3.12/20-usage/60-services.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/60-services.md rename to docs/versioned_docs/version-3.12/20-usage/60-services.md diff --git a/docs/versioned_docs/version-3.9/20-usage/70-volumes.md b/docs/versioned_docs/version-3.12/20-usage/70-volumes.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/70-volumes.md rename to docs/versioned_docs/version-3.12/20-usage/70-volumes.md diff --git a/docs/versioned_docs/version-3.12/20-usage/72-extensions/40-configuration-extension.md b/docs/versioned_docs/version-3.12/20-usage/72-extensions/40-configuration-extension.md new file mode 100644 index 000000000..63d806117 --- /dev/null +++ b/docs/versioned_docs/version-3.12/20-usage/72-extensions/40-configuration-extension.md @@ -0,0 +1,160 @@ +# Configuration extension + +The configuration extension can be used to modify or generate Woodpeckers pipeline configurations. You can configure an HTTP endpoint in the repository settings in the extensions tab. + +Using such an extension can be useful if you want to: + + + +- Preprocess the original configuration file with something like Go templating +- Convert custom attributes to Woodpecker attributes +- Add defaults to the configuration like default steps +- Convert configuration files from a totally different format like Gitlab CI config, Starlark, Jsonnet, ... +- Centralize configuration for multiple repositories in one place + +## Security + +:::warning +As Woodpecker will pass private information like tokens and will execute the returned configuration, it is extremely important to secure the external extension. Therefore Woodpecker signs every request. Read more about it in the [security section](./index.md#security). +::: + +## Global configuration + +In addition to the ability to configure the extension per repository, you can also configure a global endpoint in the Woodpecker server configuration. This can be useful if you want to use the extension for all repositories. Be careful if +you share your Woodpecker server with others as they will also use your configuration extension. + +The global configuration will be called before the repository specific configuration extension if both are configured. + +```ini title="Server" +WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig +``` + +## How it works + +When a pipeline is triggered Woodpecker will fetch the pipeline configuration from the repository, then make a HTTP POST request to the configured extension with a JSON payload containing some data like the repository, pipeline information and the current config files retrieved from the repository. The extension can then send back modified or even new pipeline configurations following Woodpeckers official yaml format that should be used. + +### Request + +The extension receives an HTTP POST request with the following JSON payload: + +```ts +class Request { + repo: Repo; + pipeline: Pipeline; + netrc: Netrc; + configuration: { + name: string; // filename of the configuration file + data: string; // content of the configuration file + }[]; +} +``` + +Checkout the following models for more information: + +- [repo model](https://github.com/woodpecker-ci/woodpecker/blob/main/server/model/repo.go) +- [pipeline model](https://github.com/woodpecker-ci/woodpecker/blob/main/server/model/pipeline.go) +- [netrc model](https://github.com/woodpecker-ci/woodpecker/blob/main/server/model/netrc.go) + +:::tip +The `netrc` data is pretty powerful as it contains credentials to access the repository. You can use this to clone the repository or even use the forge (Github or Gitlab, ...) API to get more information about the repository. +::: + +Example request: + +```json +{ + "repo": { + "id": 100, + "uid": "", + "user_id": 0, + "namespace": "", + "name": "woodpecker-test-pipeline", + "slug": "", + "scm": "git", + "git_http_url": "", + "git_ssh_url": "", + "link": "", + "default_branch": "", + "private": true, + "visibility": "private", + "active": true, + "config": "", + "trusted": false, + "protected": false, + "ignore_forks": false, + "ignore_pulls": false, + "cancel_pulls": false, + "timeout": 60, + "counter": 0, + "synced": 0, + "created": 0, + "updated": 0, + "version": 0 + }, + "pipeline": { + "author": "myUser", + "author_avatar": "https://myforge.com/avatars/d6b3f7787a685fcdf2a44e2c685c7e03", + "author_email": "my@email.com", + "branch": "main", + "changed_files": ["some-filename.txt"], + "commit": "2fff90f8d288a4640e90f05049fe30e61a14fd50", + "created_at": 0, + "deploy_to": "", + "enqueued_at": 0, + "error": "", + "event": "push", + "finished_at": 0, + "id": 0, + "link_url": "https://myforge.com/myUser/woodpecker-testpipe/commit/2fff90f8d288a4640e90f05049fe30e61a14fd50", + "message": "test old config\n", + "number": 0, + "parent": 0, + "ref": "refs/heads/main", + "refspec": "", + "clone_url": "", + "reviewed_at": 0, + "reviewed_by": "", + "sender": "myUser", + "signed": false, + "started_at": 0, + "status": "", + "timestamp": 1645962783, + "title": "", + "updated_at": 0, + "verified": false + }, + "configs": [ + { + "name": ".woodpecker.yaml", + "data": "steps:\n - name: backend\n image: alpine\n commands:\n - echo \"Hello there from Repo (.woodpecker.yaml)\"\n" + } + ] +} +``` + +### Response + +The extension should respond with a JSON payload containing the new configuration files in Woodpecker's official YAML format. +If the extension wants to keep the existing configuration files, it can respond with HTTP status `204 No Content`. + +```ts +class Response { + configs: { + name: string; // filename of the configuration file + data: string; // content of the configuration file + }[]; +} +``` + +Example response: + +```json +{ + "configs": [ + { + "name": "central-override", + "data": "steps:\n - name: backend\n image: alpine\n commands:\n - echo \"Hello there from ConfigAPI\"\n" + } + ] +} +``` diff --git a/docs/versioned_docs/version-3.12/20-usage/72-extensions/_category_.yaml b/docs/versioned_docs/version-3.12/20-usage/72-extensions/_category_.yaml new file mode 100644 index 000000000..9c351c633 --- /dev/null +++ b/docs/versioned_docs/version-3.12/20-usage/72-extensions/_category_.yaml @@ -0,0 +1,7 @@ +label: 'Extensions' +# position: 3 +collapsible: true +collapsed: true +link: + type: 'doc' + id: 'index' diff --git a/docs/versioned_docs/version-3.12/20-usage/72-extensions/index.md b/docs/versioned_docs/version-3.12/20-usage/72-extensions/index.md new file mode 100644 index 000000000..e30cb53f4 --- /dev/null +++ b/docs/versioned_docs/version-3.12/20-usage/72-extensions/index.md @@ -0,0 +1,34 @@ +# Extensions + +Woodpecker allows you to replace internal logic with external extensions by using pre-defined http endpoints. + +There is currently one type of extension available: + +- [Configuration extension](./40-configuration-extension.md) to modify or generate pipeline configurations on the fly. + +## Security + +:::warning +You need to trust the extensions as they are receiving private information like secrets and tokens and might return harmful +data like malicious pipeline configurations that could be executed. +::: + +To prevent your extensions from such attacks, Woodpecker is signing all HTTP requests using [HTTP signatures](https://tools.ietf.org/html/draft-cavage-http-signatures). Woodpecker therefore uses a public-private ed25519 key pair. +To verify the requests your extension has to verify the signature of all request using the public key with some library like [httpsign](https://github.com/yaronf/httpsign). +You can get the public Woodpecker key by opening `http://my-woodpecker.tld/api/signature/public-key` or by visiting the Woodpecker UI, going to you repo settings and opening the extensions page. + +## Example extensions + +A simplistic service providing endpoints for a config and secrets extension can be found here: [https://github.com/woodpecker-ci/example-extensions](https://github.com/woodpecker-ci/example-extensions) + +## Configuration + +To prevent extensions from calling local services by default only external hosts / ip-addresses are allowed. You can change this behavior by setting the `WOODPECKER_EXTENSIONS_ALLOWED_HOSTS` environment variable. You can use a comma separated list of: + +- Built-in networks: + - `loopback`: 127.0.0.0/8 for IPv4 and ::1/128 for IPv6, localhost is included. + - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and RFC 4193 (FC00::/7). Also called LAN/Intranet. + - `external`: A valid non-private unicast IP, you can access all hosts on public internet. + - `*`: All hosts are allowed. +- CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6 +- (Wildcard) hosts: `example.com`, `*.example.com`, `192.168.100.*` diff --git a/docs/versioned_docs/version-3.9/20-usage/72-linter.md b/docs/versioned_docs/version-3.12/20-usage/72-linter.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/72-linter.md rename to docs/versioned_docs/version-3.12/20-usage/72-linter.md diff --git a/docs/versioned_docs/version-3.9/20-usage/75-project-settings.md b/docs/versioned_docs/version-3.12/20-usage/75-project-settings.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/75-project-settings.md rename to docs/versioned_docs/version-3.12/20-usage/75-project-settings.md diff --git a/docs/versioned_docs/version-3.9/20-usage/80-badges.md b/docs/versioned_docs/version-3.12/20-usage/80-badges.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/80-badges.md rename to docs/versioned_docs/version-3.12/20-usage/80-badges.md diff --git a/docs/versioned_docs/version-3.9/20-usage/90-advanced-usage.md b/docs/versioned_docs/version-3.12/20-usage/90-advanced-usage.md similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/90-advanced-usage.md rename to docs/versioned_docs/version-3.12/20-usage/90-advanced-usage.md diff --git a/docs/versioned_docs/version-3.9/20-usage/_category_.yaml b/docs/versioned_docs/version-3.12/20-usage/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/_category_.yaml rename to docs/versioned_docs/version-3.12/20-usage/_category_.yaml diff --git a/docs/versioned_docs/version-3.9/20-usage/cron-settings.png b/docs/versioned_docs/version-3.12/20-usage/cron-settings.png similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/cron-settings.png rename to docs/versioned_docs/version-3.12/20-usage/cron-settings.png diff --git a/docs/versioned_docs/version-3.9/20-usage/linter-warnings-errors.png b/docs/versioned_docs/version-3.12/20-usage/linter-warnings-errors.png similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/linter-warnings-errors.png rename to docs/versioned_docs/version-3.12/20-usage/linter-warnings-errors.png diff --git a/docs/versioned_docs/version-3.9/20-usage/pipeline.png b/docs/versioned_docs/version-3.12/20-usage/pipeline.png similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/pipeline.png rename to docs/versioned_docs/version-3.12/20-usage/pipeline.png diff --git a/docs/versioned_docs/version-3.9/20-usage/project-settings.png b/docs/versioned_docs/version-3.12/20-usage/project-settings.png similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/project-settings.png rename to docs/versioned_docs/version-3.12/20-usage/project-settings.png diff --git a/docs/versioned_docs/version-3.9/20-usage/repo-new.png b/docs/versioned_docs/version-3.12/20-usage/repo-new.png similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/repo-new.png rename to docs/versioned_docs/version-3.12/20-usage/repo-new.png diff --git a/docs/versioned_docs/version-3.9/20-usage/secrets-plugins-filter.png b/docs/versioned_docs/version-3.12/20-usage/secrets-plugins-filter.png similarity index 100% rename from docs/versioned_docs/version-3.9/20-usage/secrets-plugins-filter.png rename to docs/versioned_docs/version-3.12/20-usage/secrets-plugins-filter.png diff --git a/docs/versioned_docs/version-3.9/30-administration/00-general.md b/docs/versioned_docs/version-3.12/30-administration/00-general.md similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/00-general.md rename to docs/versioned_docs/version-3.12/30-administration/00-general.md diff --git a/docs/versioned_docs/version-3.9/30-administration/05-installation/10-docker-compose.md b/docs/versioned_docs/version-3.12/30-administration/05-installation/10-docker-compose.md similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/05-installation/10-docker-compose.md rename to docs/versioned_docs/version-3.12/30-administration/05-installation/10-docker-compose.md diff --git a/docs/versioned_docs/version-3.9/30-administration/05-installation/20-helm-chart.md b/docs/versioned_docs/version-3.12/30-administration/05-installation/20-helm-chart.md similarity index 73% rename from docs/versioned_docs/version-3.9/30-administration/05-installation/20-helm-chart.md rename to docs/versioned_docs/version-3.12/30-administration/05-installation/20-helm-chart.md index 00f1c8b5d..d421f8959 100644 --- a/docs/versioned_docs/version-3.9/30-administration/05-installation/20-helm-chart.md +++ b/docs/versioned_docs/version-3.12/30-administration/05-installation/20-helm-chart.md @@ -3,26 +3,11 @@ Woodpecker provides a [Helm chart](https://github.com/woodpecker-ci/helm) for Kubernetes environments: ```bash -helm install woodpecker oci://ghcr.io/woodpecker-ci/helm/woodpecker +helm repo add woodpecker oci://ghcr.io/woodpecker-ci/helm +helm install woodpecker woodpecker/woodpecker ``` -## Configuration - -To fetch all configurable options with detailed comments: - -```bash -helm show values oci://ghcr.io/woodpecker-ci/helm/woodpecker > values.yaml -``` - -Install using custom values: - -```bash -helm install woodpecker \ - oci://ghcr.io/woodpecker-ci/helm/woodpecker \ - -f values.yaml -``` - -### Metrics +## Metrics To enable metrics gathering, set the following in values.yml: diff --git a/docs/versioned_docs/version-3.9/30-administration/05-installation/30-packages.md b/docs/versioned_docs/version-3.12/30-administration/05-installation/30-packages.md similarity index 98% rename from docs/versioned_docs/version-3.9/30-administration/05-installation/30-packages.md rename to docs/versioned_docs/version-3.12/30-administration/05-installation/30-packages.md index 3a28dfa04..ca4c55e2f 100644 --- a/docs/versioned_docs/version-3.9/30-administration/05-installation/30-packages.md +++ b/docs/versioned_docs/version-3.12/30-administration/05-installation/30-packages.md @@ -91,6 +91,7 @@ Woodpecker itself is not responsible for creating these packages. Please reach o - [openSUSE](https://software.opensuse.org/package/woodpecker) - [YunoHost](https://apps.yunohost.org/app/woodpecker) - [Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html) +- [Easypanel](https://easypanel.io/docs/templates/woodpeckerci) ### NixOS diff --git a/docs/versioned_docs/version-3.9/30-administration/05-installation/_category_.yaml b/docs/versioned_docs/version-3.12/30-administration/05-installation/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/05-installation/_category_.yaml rename to docs/versioned_docs/version-3.12/30-administration/05-installation/_category_.yaml diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/10-server.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/10-server.md similarity index 97% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/10-server.md rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/10-server.md index f47ac222c..61e67b109 100644 --- a/docs/versioned_docs/version-3.9/30-administration/10-configuration/10-server.md +++ b/docs/versioned_docs/version-3.12/30-administration/10-configuration/10-server.md @@ -808,6 +808,15 @@ The default setting for allowing pull requests on a repo. --- +### DEFAULT_APPROVAL_MODE + +- Name: `WOODPECKER_DEFAULT_APPROVAL_MODE` +- Default: `forks` + +The default setting for the approval mode on a repo. Possible values: `none`, `forks`, `pull_requests` or `all_events`. + +--- + ### DEFAULT_CANCEL_PREVIOUS_PIPELINE_EVENTS - Name: `WOODPECKER_DEFAULT_CANCEL_PREVIOUS_PIPELINE_EVENTS` @@ -1062,6 +1071,15 @@ Specify a configuration service endpoint, see [Configuration Extension](#externa --- +### EXTENSIONS_ALLOWED_HOSTS + +- Name: `WOODPECKER_EXTENSIONS_ALLOWED_HOSTS` +- Default: `external` + +Comma-separated list of hosts that are allowed to be contacted by extensions. Possible values are `loopback`, `private`, `external`, `*` or CIDR list. + +--- + ### FORGE_TIMEOUT - Name: `WOODPECKER_FORGE_TIMEOUT` @@ -1103,7 +1121,11 @@ Disable version check in admin web UI. - Name: `WOODPECKER_LOG_STORE` - Default: `database` -Where to store logs. Possible values: `database` or `file`. +Where to store logs. Possible values: + +- `database`: stores the logs in the database +- `file`: stores logs in JSON files on the files system +- `addon`: uses an [addon](./100-addons.md#log) to store logs --- @@ -1112,7 +1134,10 @@ Where to store logs. Possible values: `database` or `file`. - Name: `WOODPECKER_LOG_STORE_FILE_PATH` - Default: none -Directory to store logs in if [`WOODPECKER_LOG_STORE`](#log_store) is `file`. +If [`WOODPECKER_LOG_STORE`](#log_store) is: + +- `file`: Directory to store logs in +- `addon`: The path to the addon executable --- diff --git a/docs/versioned_docs/version-3.12/30-administration/10-configuration/100-addons.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/100-addons.md new file mode 100644 index 000000000..12d297e7f --- /dev/null +++ b/docs/versioned_docs/version-3.12/30-administration/10-configuration/100-addons.md @@ -0,0 +1,42 @@ +# Addons + +Addons can be used to extend the Woodpecker server. Currently, they can be used for forges and the log service. + +:::warning +Addon forges are still experimental. Their implementation can change and break at any time. +::: + +:::danger +You must trust the author of the addon forge you are using. They may have access to authentication codes and other potentially sensitive information. +::: + +## Usage + +To use an addon forge, download the correct addon version. + +### Forge + +Use this in your `.env`: + +```ini +WOODPECKER_ADDON_FORGE=/path/to/your/addon/forge/file +``` + +In case you run Woodpecker as container, you probably want to mount the addon binary to `/opt/addons/`. + +#### List of addon forges + +- [Radicle](https://radicle.xyz/): Open source, peer-to-peer code collaboration stack built on Git. Radicle addon for Woodpecker CI can be found at [this repo](https://explorer.radicle.gr/nodes/seed.radicle.gr/rad:z39Cf1XzrvCLRZZJRUZnx9D1fj5ws). + +### Log + +Use this in your `.env`: + +```ini +WOODPECKER_LOG_STORE=addon +WOODPECKER_LOG_STORE_FILE_PATH=/path/to/your/addon/forge/file +``` + +## Developing addon forges + +See [Addons](../../92-development/100-addons.md). diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/11-backends/10-docker.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/11-backends/10-docker.md similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/11-backends/10-docker.md rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/11-backends/10-docker.md diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/11-backends/20-kubernetes.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/11-backends/20-kubernetes.md similarity index 92% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/11-backends/20-kubernetes.md rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/11-backends/20-kubernetes.md index f7afbc406..8ba332322 100644 --- a/docs/versioned_docs/version-3.9/30-administration/10-configuration/11-backends/20-kubernetes.md +++ b/docs/versioned_docs/version-3.12/30-administration/10-configuration/11-backends/20-kubernetes.md @@ -19,6 +19,8 @@ The following metadata labels are supported: - `woodpecker-ci.org/repo-full-name` - `woodpecker-ci.org/branch` - `woodpecker-ci.org/org-id` +- `woodpecker-ci.org/task-uuid` +- `woodpecker-ci.org/step` ## Private registries @@ -250,6 +252,15 @@ backend_options: localhostProfile: k8s-apparmor-example-deny-write ``` +or configure a specific `fsGroupChangePolicy` (Kubernetes defaults to 'Always') + +```yaml +backend_options: + kubernetes: + securityContext: + fsGroupChangePolicy: OnRootMismatch +``` + :::note The feature requires Kubernetes v1.30 or above. ::: @@ -380,6 +391,24 @@ Determines if Pod annotations can be defined from a step's backend options. --- +### BACKEND_K8S_POD_TOLERATIONS + +- Name: `WOODPECKER_BACKEND_K8S_POD_TOLERATIONS` +- Default: none + +Additional tolerations to apply to worker Pods. Must be a YAML object, e.g. `[{"effect":"NoSchedule","key":"jobs","operator":"Exists"}]`. + +--- + +### BACKEND_K8S_POD_TOLERATIONS_ALLOW_FROM_STEP + +- Name: `WOODPECKER_BACKEND_K8S_POD_TOLERATIONS_ALLOW_FROM_STEP` +- Default: `true` + +Determines if Pod tolerations can be defined from a step's backend options. + +--- + ### BACKEND_K8S_POD_NODE_SELECTOR - Name: `WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR` @@ -404,3 +433,12 @@ Determines if containers must be required to run as non-root users. - Default: none Secret names to pull images from private repositories. See, how to [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). + +--- + +### BACKEND_K8S_PRIORITY_CLASS + +- Name: `WOODPECKER_BACKEND_K8S_PRIORITY_CLASS` +- Default: none, which will use the default priority class configured in Kubernetes + +Which [Kubernetes PriorityClass](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/priority-class-v1/) to assign to created job pods. diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/11-backends/30-local.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/11-backends/30-local.md similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/11-backends/30-local.md rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/11-backends/30-local.md diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/11-backends/50-custom.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/11-backends/50-custom.md similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/11-backends/50-custom.md rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/11-backends/50-custom.md diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/11-backends/_category_.yaml b/docs/versioned_docs/version-3.12/30-administration/10-configuration/11-backends/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/11-backends/_category_.yaml rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/11-backends/_category_.yaml diff --git a/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/11-overview.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/11-overview.md new file mode 100644 index 000000000..f384cefc4 --- /dev/null +++ b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/11-overview.md @@ -0,0 +1,18 @@ +# 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: | +| [Event: Pull-Request-Metadata](../../../20-usage/50-environment.md#pull_request_metadata-specific-event-reason-values) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :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: | :white_check_mark: | :white_check_mark: | + +¹ The deployment event can be triggered for all forges from Woodpecker directly. However, only GitHub can trigger them using webhooks. + +In addition to this, Woodpecker supports [addon forges](../100-addons.md) if the forge you are using does not meet the [Woodpecker requirements](../../../92-development/02-core-ideas.md#forges) or your setup is too specific to be included in the Woodpecker core. diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/20-github.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/20-github.md similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/20-github.md rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/20-github.md diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/30-gitea.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/30-gitea.md similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/30-gitea.md rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/30-gitea.md diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/35-forgejo.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/35-forgejo.md similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/35-forgejo.md rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/35-forgejo.md diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/40-gitlab.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/40-gitlab.md similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/40-gitlab.md rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/40-gitlab.md diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/50-bitbucket.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/50-bitbucket.md similarity index 85% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/50-bitbucket.md rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/50-bitbucket.md index 7df547193..3c0acbd86 100644 --- a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/50-bitbucket.md +++ b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/50-bitbucket.md @@ -84,6 +84,10 @@ Configures the Bitbucket OAuth client secret. This is used to authorize access. Read the value for `WOODPECKER_BITBUCKET_SECRET` from the specified filepath +## Known Issues + +Bitbucket build keys are limited to 40 characters: [issue #5176](https://github.com/woodpecker-ci/woodpecker/issues/5176). If a job exceeds this limit, you can adjust the key by modifying the `WOODPECKER_STATUS_CONTEXT` or `WOODPECKER_STATUS_CONTEXT_FORMAT` variables. See the [environment variables documentation](../10-server.md#environment-variables) for more details. + ## Missing Features Path filters for pull requests are not supported. We are interested in patches to include this functionality. diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.md similarity index 87% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.md rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.md index 0b6927a38..a144aa979 100644 --- a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.md +++ b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.md @@ -22,6 +22,7 @@ To enable Bitbucket Server you should configure the Woodpecker container using t + - WOODPECKER_BITBUCKET_DC_CLIENT_ID=xxx + - WOODPECKER_BITBUCKET_DC_CLIENT_SECRET=yyy + - WOODPECKER_BITBUCKET_DC_URL=http://stash.mycompany.com ++ - WOODPECKER_BITBUCKET_DC_ENABLE_OAUTH2_SCOPE_PROJECT_ADMIN=true woodpecker-agent: [...] @@ -124,3 +125,12 @@ Read the value for `WOODPECKER_BITBUCKET_DC_GIT_PASSWORD` from the specified fil - Default: `false` Configure if SSL verification should be skipped. + +--- + +### BITBUCKET_DC_ENABLE_OAUTH2_SCOPE_PROJECT_ADMIN + +- Name: `WOODPECKER_BITBUCKET_DC_ENABLE_OAUTH2_SCOPE_PROJECT_ADMIN` +- Default: `false` + +When enabled, the Bitbucket Application Link for Woodpecker should include the `PROJECT_ADMIN` scope. Enabling this feature flag will allow the users of Bitbucket Datacenter to use organization secrets and properly list repositories within the organization. diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/_category_.yaml b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/_category_.yaml rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/_category_.yaml diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/bitbucket_oauth.png b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/bitbucket_oauth.png similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/bitbucket_oauth.png rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/bitbucket_oauth.png diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/bitbucket_permissions.png b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/bitbucket_permissions.png similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/bitbucket_permissions.png rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/bitbucket_permissions.png diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/gitea_oauth.gif b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/gitea_oauth.gif similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/gitea_oauth.gif rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/gitea_oauth.gif diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/github_oauth.png b/docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/github_oauth.png similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/github_oauth.png rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/12-forges/github_oauth.png diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/30-agent.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/30-agent.md similarity index 95% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/30-agent.md rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/30-agent.md index 2b88600e0..589c57b83 100644 --- a/docs/versioned_docs/version-3.9/30-administration/10-configuration/30-agent.md +++ b/docs/versioned_docs/version-3.12/30-administration/10-configuration/30-agent.md @@ -155,7 +155,8 @@ Configures the number of parallel workflows. Configures custom labels for the agent, to let workflows filter by it. Use a list of key-value pairs like `key=value,second-key=*`. `*` can be used as a wildcard. -By default, agents provide three additional labels `platform=os/arch`, `hostname=my-agent` and `repo=*` which can be overwritten if needed. +If you use `!` as key prefix it is mandatory for the workflow to have that label set (without !) set and matched. +By default, agents provide four additional labels `platform=os/arch`, `hostname=my-agent`, `backend=my-backend` and `repo=*` which can be overwritten if needed. To learn how labels work, check out the [pipeline syntax page](../../20-usage/20-workflow-syntax.md#labels). --- diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/40-autoscaler.md b/docs/versioned_docs/version-3.12/30-administration/10-configuration/40-autoscaler.md similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/40-autoscaler.md rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/40-autoscaler.md diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/_category_.yaml b/docs/versioned_docs/version-3.12/30-administration/10-configuration/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/_category_.yaml rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/_category_.yaml diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/new-agent-connected.png b/docs/versioned_docs/version-3.12/30-administration/10-configuration/new-agent-connected.png similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/new-agent-connected.png rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/new-agent-connected.png diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/new-agent-created.png b/docs/versioned_docs/version-3.12/30-administration/10-configuration/new-agent-created.png similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/new-agent-created.png rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/new-agent-created.png diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/new-agent-registration.png b/docs/versioned_docs/version-3.12/30-administration/10-configuration/new-agent-registration.png similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/new-agent-registration.png rename to docs/versioned_docs/version-3.12/30-administration/10-configuration/new-agent-registration.png diff --git a/docs/versioned_docs/version-3.9/30-administration/_category_.yaml b/docs/versioned_docs/version-3.12/30-administration/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.9/30-administration/_category_.yaml rename to docs/versioned_docs/version-3.12/30-administration/_category_.yaml diff --git a/docs/versioned_docs/version-3.9/40-cli.md b/docs/versioned_docs/version-3.12/40-cli.md similarity index 70% rename from docs/versioned_docs/version-3.9/40-cli.md rename to docs/versioned_docs/version-3.12/40-cli.md index 9bae357b4..6e57d43c3 100644 --- a/docs/versioned_docs/version-3.9/40-cli.md +++ b/docs/versioned_docs/version-3.12/40-cli.md @@ -36,26 +36,27 @@ woodpecker-cli [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...] **--config, -c**="": path to config file -**--disable-update-check**: disable update check +**--disable-update-check**: disable update check (default: false) **--log-file**="": Output destination for logs. 'stdout' and 'stderr' can be used as special keywords. (default: stderr) **--log-level**="": set logging level (default: info) -**--nocolor**: disable colored debug output, only has effect if pretty output is set too +**--nocolor**: disable colored debug output, only has effect if pretty output is set too (default: false) -**--pretty**: enable pretty-printed debug output +**--pretty**: enable pretty-printed debug output (default: true) **--server, -s**="": server address -**--skip-verify**: skip ssl verification +**--skip-verify**: skip ssl verification (default: false) **--socks-proxy**="": socks proxy address -**--socks-proxy-off**: socks proxy ignored +**--socks-proxy-off**: socks proxy ignored (default: false) **--token, -t**="": server auth token + # COMMANDS ## admin @@ -66,6 +67,16 @@ manage server settings retrieve log level from server, or set it with [level] +### org + +manage organizations + +#### ls + +list organizations + +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Name }} \x1b[0m\nOrganization ID: {{ .ID }}\n) + ### registry manage global registries @@ -90,19 +101,13 @@ remove a registry list registries -**--format**="": format output (deprecated) (default: {{ .Address }}  -Username: {{ .Username }} -Email: {{ .Email }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Address }} \x1b[0m\nUsername: {{ .Username }}\nEmail: {{ .Email }}\n) #### show show registry information -**--format**="": format output (deprecated) (default: {{ .Address }}  -Username: {{ .Username }} -Email: {{ .Email }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Address }} \x1b[0m\nUsername: {{ .Username }}\nEmail: {{ .Email }}\n) **--hostname**="": registry hostname (default: docker.io) @@ -126,9 +131,9 @@ manage global secrets add a secret -**--event**="": secret limited to these events (default: []) +**--event**="": secret limited to these events -**--image**="": secret limited to these images (default: []) +**--image**="": secret limited to these images **--name**="": secret name @@ -144,27 +149,13 @@ remove a secret list secrets -**--format**="": format output (deprecated) (default: {{ .Name }}  -Events: {{ list .Events }} -{{- if .Images }} -Images: {{ list .Images }} -{{- else }} -Images: -{{- end }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Name }} \x1b[0m\nEvents: {{ list .Events }}\n{{- if .Images }}\nImages: {{ list .Images }}\n{{- else }}\nImages: \n{{- end }}\n) #### show show secret information -**--format**="": format output (deprecated) (default: {{ .Name }}  -Events: {{ list .Events }} -{{- if .Images }} -Images: {{ list .Images }} -{{- else }} -Images: -{{- end }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Name }} \x1b[0m\nEvents: {{ list .Events }}\n{{- if .Images }}\nImages: {{ list .Images }}\n{{- else }}\nImages: \n{{- end }}\n) **--name**="": secret name @@ -172,9 +163,9 @@ Images: update a secret -**--event**="": secret limited to these events (default: []) +**--event**="": secret limited to these events -**--image**="": secret limited to these images (default: []) +**--image**="": secret limited to these images **--name**="": secret name @@ -202,8 +193,7 @@ remove a user show user information -**--format**="": format output (default: User: {{ .Login }} -Email: {{ .Email }}) +**--format**="": format output (default: User: {{ .Login }}\nEmail: {{ .Email }}) ## exec @@ -215,7 +205,7 @@ execute a local pipeline **--backend-docker-host**="": path to docker socket or url to the docker server -**--backend-docker-ipv6**: backend docker enable IPV6 +**--backend-docker-ipv6**: backend docker enable IPV6 (default: false) **--backend-docker-limit-cpu-quota**="": impose a cpu quota (default: 0) @@ -231,7 +221,7 @@ execute a local pipeline **--backend-docker-network**="": backend docker network -**--backend-docker-tls-verify**: enable or disable TLS verification for connecting to docker server +**--backend-docker-tls-verify**: enable or disable TLS verification for connecting to docker server (default: true) **--backend-docker-volumes**="": backend docker volumes (comma separated) @@ -241,33 +231,39 @@ execute a local pipeline **--backend-https-proxy**="": if set, pass the environment variable down as "HTTPS_PROXY" to steps -**--backend-k8s-allow-native-secrets**: whether to allow existing Kubernetes secrets to be referenced from steps +**--backend-k8s-allow-native-secrets**: whether to allow existing Kubernetes secrets to be referenced from steps (default: false) **--backend-k8s-namespace**="": backend k8s namespace, if used with WOODPECKER_BACKEND_K8S_NAMESPACE_PER_ORGANIZATION, this will be the prefix for the namespace appended with the organization name. (default: woodpecker) -**--backend-k8s-namespace-per-org**: Whether to enable namespace segregation per organization feature. When enabled, Woodpecker will create the Kubernetes resources to separated Kubernetes namespaces per Woodpecker organization. +**--backend-k8s-namespace-per-org**: Whether to enable namespace segregation per organization feature. When enabled, Woodpecker will create the Kubernetes resources to separated Kubernetes namespaces per Woodpecker organization. (default: false) **--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-annotations-allow-from-step**: whether to allow using annotations from step's backend options (default: false) -**--backend-k8s-pod-image-pull-secret-names**="": backend k8s pull secret names for private registries (default: []) +**--backend-k8s-pod-image-pull-secret-names**="": backend k8s pull secret names for private registries **--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-labels-allow-from-step**: whether to allow using labels from step's backend options (default: false) **--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-pod-tolerations**="": backend k8s Agent-wide worker pod tolerations + +**--backend-k8s-pod-tolerations-allow-from-step**: whether to allow using tolerations from step's backend options (default: true) + +**--backend-k8s-priority-class**="": which kubernetes priority class to assign to created job pods + +**--backend-k8s-secctx-nonroot**: `run as non root` Kubernetes security context option (default: false) **--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-storage-rwx**: backend k8s storage access mode, should ReadWriteMany (RWX) instead of ReadWriteOnce (RWO) be used? (default: true) (default: true) **--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: system temporary directory) **--backend-no-proxy**="": if set, pass the environment variable down as "NO_PROXY" to steps @@ -281,33 +277,35 @@ execute a local pipeline **--commit-message**="": Set the metadata environment variable "CI_COMMIT_MESSAGE". -**--commit-pull-labels**="": Set the metadata environment variable "CI_COMMIT_PULL_REQUEST_LABELS". (default: []) +**--commit-pull-labels**="": Set the metadata environment variable "CI_COMMIT_PULL_REQUEST_LABELS". + +**--commit-pull-milestone**="": Set the metadata environment variable "CI_COMMIT_PULL_REQUEST_MILESTONE". **--commit-ref**="": Set the metadata environment variable "CI_COMMIT_REF". **--commit-refspec**="": Set the metadata environment variable "CI_COMMIT_REFSPEC". -**--commit-release-is-pre**: Set the metadata environment variable "CI_COMMIT_PRERELEASE". +**--commit-release-is-pre**: Set the metadata environment variable "CI_COMMIT_PRERELEASE". (default: false) **--commit-sha**="": Set the metadata environment variable "CI_COMMIT_SHA". -**--env**="": Set the metadata environment variable "CI_ENV". (default: []) +**--env**="": Set the metadata environment variable "CI_ENV". **--forge-type**="": Set the metadata environment variable "CI_FORGE_TYPE". **--forge-url**="": Set the metadata environment variable "CI_FORGE_URL". -**--local**: run from local directory +**--local**: run from local directory (default: true) **--metadata-file**="": path to pipeline metadata file (normally downloaded from UI). Parameters can be adjusted by applying additional cli flags -**--netrc-machine**="": +**--netrc-machine**="": -**--netrc-password**="": +**--netrc-password**="": -**--netrc-username**="": +**--netrc-username**="": -**--network**="": external networks (default: []) +**--network**="": external networks **--pipeline-changed-files**="": Set the metadata environment variable "CI_PIPELINE_FILES", either json formatted list of strings, or comma separated string list. @@ -327,7 +325,7 @@ execute a local pipeline **--pipeline-url**="": Set the metadata environment variable "CI_PIPELINE_FORGE_URL". -**--plugins-privileged**="": Allow plugins to run in privileged mode, if environment variable is defined but empty there will be none (default: []) +**--plugins-privileged**="": Allow plugins to run in privileged mode, if environment variable is defined but empty there will be none **--prev-commit-author-avatar**="": Set the metadata environment variable "CI_PREV_COMMIT_AUTHOR_AVATAR". @@ -377,15 +375,17 @@ execute a local pipeline **--repo-remote-id**="": Set the metadata environment variable "CI_REPO_REMOTE_ID". -**--repo-trusted-network**: Set the metadata environment variable "CI_REPO_TRUSTED_NETWORK". +**--repo-trusted-network**: Set the metadata environment variable "CI_REPO_TRUSTED_NETWORK". (default: false) -**--repo-trusted-security**: Set the metadata environment variable "CI_REPO_TRUSTED_SECURITY". +**--repo-trusted-security**: Set the metadata environment variable "CI_REPO_TRUSTED_SECURITY". (default: false) -**--repo-trusted-volumes**: Set the metadata environment variable "CI_REPO_TRUSTED_VOLUMES". +**--repo-trusted-volumes**: Set the metadata environment variable "CI_REPO_TRUSTED_VOLUMES". (default: false) **--repo-url**="": Set the metadata environment variable "CI_REPO_URL". -**--secrets**="": map of secrets, ex. 'secret="val",secret2="value2"' (default: map[]) +**--secrets**="": map of secrets, ex. 'secret="val",secret2="value2"' + +**--secrets**="": path to yaml file with secrets map **--system-host**="": Set the metadata environment variable "CI_SYSTEM_HOST". @@ -397,32 +397,31 @@ execute a local pipeline **--timeout**="": pipeline timeout (default: 1h0m0s) -**--volumes**="": pipeline volumes (default: []) +**--volumes**="": pipeline volumes **--workflow-name**="": Set the metadata environment variable "CI_WORKFLOW_NAME". **--workflow-number**="": Set the metadata environment variable "CI_WORKFLOW_NUMBER". (default: 0) -**--workspace-base**="": (default: /woodpecker) +**--workspace-base**="": (default: /woodpecker) -**--workspace-path**="": (default: src) +**--workspace-path**="": (default: src) ## info show information about the current user -**--format**="": format output (deprecated) (default: User: {{ .Login }} -Email: {{ .Email }}) +**--format**="": format output (deprecated) (default: User: {{ .Login }}\nEmail: {{ .Email }}) ## lint lint a pipeline configuration file -**--plugins-privileged**="": allow plugins to run in privileged mode, if set empty, there is no (default: []) +**--plugins-privileged**="": allow plugins to run in privileged mode, if set empty, there is no -**--plugins-trusted-clone**="": plugins that are trusted to handle Git credentials in cloning steps (default: [docker.io/woodpeckerci/plugin-git:2.6.5 docker.io/woodpeckerci/plugin-git quay.io/woodpeckerci/plugin-git]) +**--plugins-trusted-clone**="": plugins that are trusted to handle Git credentials in cloning steps (default: "docker.io/woodpeckerci/plugin-git:2.7.0", "docker.io/woodpeckerci/plugin-git", "quay.io/woodpeckerci/plugin-git") -**--strict**: treat warnings as errors +**--strict**: treat warnings as errors (default: false) ## org @@ -456,10 +455,7 @@ remove a registry list registries -**--format**="": format output (deprecated) (default: {{ .Address }}  -Username: {{ .Username }} -Email: {{ .Email }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Address }} \x1b[0m\nUsername: {{ .Username }}\nEmail: {{ .Email }}\n) **--organization, --org**="": organization id or full name (e.g. 123 or octocat) @@ -467,10 +463,7 @@ Email: {{ .Email }} show registry information -**--format**="": format output (deprecated) (default: {{ .Address }}  -Username: {{ .Username }} -Email: {{ .Email }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Address }} \x1b[0m\nUsername: {{ .Username }}\nEmail: {{ .Email }}\n) **--hostname**="": registry hostname (default: docker.io) @@ -496,9 +489,9 @@ manage secrets add a secret -**--event**="": secret limited to these events (default: []) +**--event**="": secret limited to these events -**--image**="": secret limited to these images (default: []) +**--image**="": secret limited to these images **--name**="": secret name @@ -518,14 +511,7 @@ remove a secret list secrets -**--format**="": format output (deprecated) (default: {{ .Name }}  -Events: {{ list .Events }} -{{- if .Images }} -Images: {{ list .Images }} -{{- else }} -Images: -{{- end }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Name }} \x1b[0m\nEvents: {{ list .Events }}\n{{- if .Images }}\nImages: {{ list .Images }}\n{{- else }}\nImages: \n{{- end }}\n) **--organization, --org**="": organization id or full name (e.g. 123 or octocat) @@ -533,14 +519,7 @@ Images: show secret information -**--format**="": format output (deprecated) (default: {{ .Name }}  -Events: {{ list .Events }} -{{- if .Images }} -Images: {{ list .Images }} -{{- else }} -Images: -{{- end }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Name }} \x1b[0m\nEvents: {{ list .Events }}\n{{- if .Images }}\nImages: {{ list .Images }}\n{{- else }}\nImages: \n{{- end }}\n) **--name**="": secret name @@ -550,9 +529,9 @@ Images: update a secret -**--event**="": limit secret to these event (default: []) +**--event**="": limit secret to these event -**--image**="": limit secret to these image (default: []) +**--image**="": limit secret to these image **--name**="": secret name @@ -576,9 +555,9 @@ create new pipeline **--output**="": output format (default: table) -**--output-no-headers**: don't print headers +**--output-no-headers**: don't print headers (default: false) -**--var**="": key=value (default: []) +**--var**="": key=value ### decline @@ -592,17 +571,9 @@ trigger a pipeline with the 'deployment' event **--event**="": event filter (default: push) -**--format**="": format output (default: Number: {{ .Number }} -Status: {{ .Status }} -Commit: {{ .Commit }} -Branch: {{ .Branch }} -Ref: {{ .Ref }} -Message: {{ .Message }} -Author: {{ .Author }} -Target: {{ .Deploy }} -) +**--format**="": format output (default: Number: {{ .Number }}\nStatus: {{ .Status }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\nTarget: {{ .Deploy }}\n) -**--param, -p**="": custom parameters to inject into the step environment. Format: KEY=value (default: []) +**--param, -p**="": custom parameters to inject into the step environment. Format: KEY=value **--status**="": status filter (default: success) @@ -614,15 +585,15 @@ show latest pipeline information **--output**="": output format (default: table) -**--output-no-headers**: don't print headers +**--output-no-headers**: don't print headers (default: false) ### ls show pipeline history -**--after**="": only return pipelines after this date (RFC3339) (default: 0001-01-01 00:00:00 +0000 UTC) +**--after**="": only return pipelines after this date (RFC3339) -**--before**="": only return pipelines before this date (RFC3339) (default: 0001-01-01 00:00:00 +0000 UTC) +**--before**="": only return pipelines before this date (RFC3339) **--branch**="": branch filter @@ -632,7 +603,7 @@ show pipeline history **--output**="": output format (default: table) -**--output-no-headers**: don't print headers +**--output-no-headers**: don't print headers (default: false) **--status**="": status filter @@ -652,37 +623,25 @@ show pipeline logs show pipeline steps -**--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 }} -) +**--format**="": format output (default: \x1b[33m{{ .workflow.Name }} > {{ .step.Name }} (#{{ .step.PID }}):\x1b[0m\nStep: {{ .step.Name }}\nStarted: {{ .step.Started }}\nStopped: {{ .step.Stopped }}\nType: {{ .step.Type }}\nState: {{ .step.State }}\n) ### purge purge pipelines -**--dry-run**: disable non-read api calls +**--branch**="": remove pipelines of this branch only + +**--dry-run**: disable non-read api calls (default: false) **--keep-min**="": minimum number of pipelines to keep (default: 10) -**--older-than**="": remove pipelines older than the specified time limit +**--older-than**="": remove pipelines older than the specified time limit (default: 0s) ### queue show pipeline queue -**--format**="": format output (default: {{ .FullName }} #{{ .Number }}  -Status: {{ .Status }} -Event: {{ .Event }} -Commit: {{ .Commit }} -Branch: {{ .Branch }} -Ref: {{ .Ref }} -Author: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }} -Message: {{ .Message }} -) +**--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) ### show @@ -690,13 +649,13 @@ show pipeline information **--output**="": output format (default: table) -**--output-no-headers**: don't print headers +**--output-no-headers**: don't print headers (default: false) ### start start a pipeline -**--param, -p**="": custom parameters to inject into the step environment. Format: KEY=value (default: []) +**--param, -p**="": custom parameters to inject into the step environment. Format: KEY=value ### stop @@ -724,12 +683,7 @@ add a cron job **--branch**="": cron branch -**--format**="": format output (deprecated) (default: {{ .Name }}  -ID: {{ .ID }} -Branch: {{ .Branch }} -Schedule: {{ .Schedule }} -NextExec: {{ .NextExec }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Name }} \x1b[0m\nID: {{ .ID }}\nBranch: {{ .Branch }}\nSchedule: {{ .Schedule }}\nNextExec: {{ .NextExec }}\n) **--name**="": cron name @@ -749,12 +703,7 @@ remove a cron job list cron jobs -**--format**="": format output (deprecated) (default: {{ .Name }}  -ID: {{ .ID }} -Branch: {{ .Branch }} -Schedule: {{ .Schedule }} -NextExec: {{ .NextExec }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Name }} \x1b[0m\nID: {{ .ID }}\nBranch: {{ .Branch }}\nSchedule: {{ .Schedule }}\nNextExec: {{ .NextExec }}\n) **--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world) @@ -762,12 +711,7 @@ NextExec: {{ .NextExec }} show cron job information -**--format**="": format output (deprecated) (default: {{ .Name }}  -ID: {{ .ID }} -Branch: {{ .Branch }} -Schedule: {{ .Schedule }} -NextExec: {{ .NextExec }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Name }} \x1b[0m\nID: {{ .ID }}\nBranch: {{ .Branch }}\nSchedule: {{ .Schedule }}\nNextExec: {{ .NextExec }}\n) **--id**="": cron id @@ -779,12 +723,7 @@ update a cron job **--branch**="": cron branch -**--format**="": format output (deprecated) (default: {{ .Name }}  -ID: {{ .ID }} -Branch: {{ .Branch }} -Schedule: {{ .Schedule }} -NextExec: {{ .NextExec }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Name }} \x1b[0m\nID: {{ .ID }}\nBranch: {{ .Branch }}\nSchedule: {{ .Schedule }}\nNextExec: {{ .NextExec }}\n) **--id**="": cron id @@ -798,7 +737,7 @@ NextExec: {{ .NextExec }} list all repos -**--all**: query all repos, including inactive ones +**--all**: query all repos, including inactive ones (default: false) **--format**="": format output (deprecated) @@ -806,7 +745,7 @@ list all repos **--output**="": output format (default: table) -**--output-no-headers**: don't print headers +**--output-no-headers**: don't print headers (default: false) ### registry @@ -836,10 +775,7 @@ remove a registry list registries -**--format**="": format output (deprecated) (default: {{ .Address }}  -Username: {{ .Username }} -Email: {{ .Email }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Address }} \x1b[0m\nUsername: {{ .Username }}\nEmail: {{ .Email }}\n) **--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world) @@ -847,10 +783,7 @@ Email: {{ .Email }} show registry information -**--format**="": format output (deprecated) (default: {{ .Address }}  -Username: {{ .Username }} -Email: {{ .Email }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Address }} \x1b[0m\nUsername: {{ .Username }}\nEmail: {{ .Email }}\n) **--hostname**="": registry hostname (default: docker.io) @@ -884,9 +817,9 @@ manage secrets add a secret -**--event**="": limit secret to these events (default: []) +**--event**="": limit secret to these events -**--image**="": limit secret to these images (default: []) +**--image**="": limit secret to these images **--name**="": secret name @@ -906,14 +839,7 @@ remove a secret list secrets -**--format**="": format output (deprecated) (default: {{ .Name }}  -Events: {{ list .Events }} -{{- if .Images }} -Images: {{ list .Images }} -{{- else }} -Images: -{{- end }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Name }} \x1b[0m\nEvents: {{ list .Events }}\n{{- if .Images }}\nImages: {{ list .Images }}\n{{- else }}\nImages: \n{{- end }}\n) **--repository, --repo**="": repository id or full name (e.g. 134 or octocat/hello-world) @@ -921,14 +847,7 @@ Images: show secret information -**--format**="": format output (deprecated) (default: {{ .Name }}  -Events: {{ list .Events }} -{{- if .Images }} -Images: {{ list .Images }} -{{- else }} -Images: -{{- end }} -) +**--format**="": format output (deprecated) (default: \x1b[33m{{ .Name }} \x1b[0m\nEvents: {{ list .Events }}\n{{- if .Images }}\nImages: {{ list .Images }}\n{{- else }}\nImages: \n{{- end }}\n) **--name**="": secret name @@ -938,9 +857,9 @@ Images: update a secret -**--event**="": limit secret to these events (default: []) +**--event**="": limit secret to these events -**--image**="": limit secret to these images (default: []) +**--image**="": limit secret to these images **--name**="": secret name @@ -954,13 +873,13 @@ show repository information **--output**="": output format (default: table) -**--output-no-headers**: don't print headers +**--output-no-headers**: don't print headers (default: false) ### sync synchronize the repository list -**--format**="": format output (default: {{ .FullName }} (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }}, isActive: {{ .IsActive }})) +**--format**="": format output (default: \x1b[33m{{ .FullName }}\x1b[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }}, isActive: {{ .IsActive }})) ### update @@ -974,9 +893,9 @@ update a repository **--timeout**="": repository timeout (default: 0s) -**--trusted**: repository is trusted +**--trusted**: repository is trusted (default: false) -**--unsafe**: allow unsafe operations +**--unsafe**: allow unsafe operations (default: false) **--visibility**="": repository visibility @@ -992,4 +911,4 @@ setup the woodpecker-cli for the first time update the woodpecker-cli to the latest version -**--force**: force update even if the latest version is already installed +**--force**: force update even if the latest version is already installed (default: false) diff --git a/docs/versioned_docs/version-3.9/92-development/01-getting-started.md b/docs/versioned_docs/version-3.12/92-development/01-getting-started.md similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/01-getting-started.md rename to docs/versioned_docs/version-3.12/92-development/01-getting-started.md diff --git a/docs/versioned_docs/version-3.9/92-development/02-core-ideas.md b/docs/versioned_docs/version-3.12/92-development/02-core-ideas.md similarity index 85% rename from docs/versioned_docs/version-3.9/92-development/02-core-ideas.md rename to docs/versioned_docs/version-3.12/92-development/02-core-ideas.md index fce17ab24..2f9570685 100644 --- a/docs/versioned_docs/version-3.9/92-development/02-core-ideas.md +++ b/docs/versioned_docs/version-3.12/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/10-configuration/12-forges/100-addon.md), [extension](../30-administration/10-configuration/10-server.md#external-configuration-api) or an +[addon](../30-administration/10-configuration/100-addons.md), [extension](../30-administration/10-configuration/10-server.md#external-configuration-api) or an [external custom backend](../30-administration/10-configuration/11-backends/50-custom.md), please check these points: - Is your change very specific to your setup and unlikely to be used by anyone else? diff --git a/docs/versioned_docs/version-3.9/92-development/03-ui.md b/docs/versioned_docs/version-3.12/92-development/03-ui.md similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/03-ui.md rename to docs/versioned_docs/version-3.12/92-development/03-ui.md diff --git a/docs/versioned_docs/version-3.9/92-development/04-docs.md b/docs/versioned_docs/version-3.12/92-development/04-docs.md similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/04-docs.md rename to docs/versioned_docs/version-3.12/92-development/04-docs.md diff --git a/docs/versioned_docs/version-3.9/92-development/05-architecture.md b/docs/versioned_docs/version-3.12/92-development/05-architecture.md similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/05-architecture.md rename to docs/versioned_docs/version-3.12/92-development/05-architecture.md diff --git a/docs/versioned_docs/version-3.9/92-development/06-conventions.md b/docs/versioned_docs/version-3.12/92-development/06-conventions.md similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/06-conventions.md rename to docs/versioned_docs/version-3.12/92-development/06-conventions.md diff --git a/docs/versioned_docs/version-3.9/92-development/07-guides.md b/docs/versioned_docs/version-3.12/92-development/07-guides.md similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/07-guides.md rename to docs/versioned_docs/version-3.12/92-development/07-guides.md diff --git a/docs/versioned_docs/version-3.9/92-development/08-translations.md b/docs/versioned_docs/version-3.12/92-development/08-translations.md similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/08-translations.md rename to docs/versioned_docs/version-3.12/92-development/08-translations.md diff --git a/docs/versioned_docs/version-3.9/92-development/09-openapi.md b/docs/versioned_docs/version-3.12/92-development/09-openapi.md similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/09-openapi.md rename to docs/versioned_docs/version-3.12/92-development/09-openapi.md diff --git a/docs/versioned_docs/version-3.9/92-development/09-testing.md b/docs/versioned_docs/version-3.12/92-development/09-testing.md similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/09-testing.md rename to docs/versioned_docs/version-3.12/92-development/09-testing.md diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/100-addon.md b/docs/versioned_docs/version-3.12/92-development/100-addons.md similarity index 54% rename from docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/100-addon.md rename to docs/versioned_docs/version-3.12/92-development/100-addons.md index 2434fee06..fe5b62a95 100644 --- a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/100-addon.md +++ b/docs/versioned_docs/version-3.12/92-development/100-addons.md @@ -1,34 +1,16 @@ -# Custom +# Addons -If the forge you are using does not meet the [Woodpecker requirements](../../../92-development/02-core-ideas.md#forges) or your setup is too specific to be included in the Woodpecker core, you can write an addon forge. +The Woodpecker server supports addons for forges and the log store. :::warning -Addon forges are still experimental. Their implementation can change and break at any time. +Addons are still experimental. Their implementation can change and break at any time. ::: -:::danger -You must trust the author of the addon forge you are using. They may have access to authentication codes and other potentially sensitive information. -::: - -## Usage - -To use an addon forge, download the correct addon version. Then, you can add the following to your configuration: - -```ini -WOODPECKER_ADDON_FORGE=/path/to/your/addon/forge/file -``` - -In case you run Woodpecker as container, you probably want to mount the addon binary to `/opt/addons/`. - -### Bug reports +## Bug reports If you experience bugs, please check which component has the issue. If it's the addon, **do not raise an issue in the main repository**, but rather use the separate addon repositories. To check which component is responsible for the bug, look at the logs. Logs from addons are marked with a special field `addon` containing their addon file name. -## List of addon forges - -- [Radicle](https://radicle.xyz/): Open source, peer-to-peer code collaboration stack built on Git. Radicle addon for Woodpecker CI can be found at [this repo](https://explorer.radicle.gr/nodes/seed.radicle.gr/rad:z39Cf1XzrvCLRZZJRUZnx9D1fj5ws). - -## Creating addon forges +## Creating addons Addons use RPC to communicate to the server and are implemented using the [`go-plugin` library](https://github.com/hashicorp/go-plugin). @@ -38,7 +20,7 @@ This example will use the Go language. Directly import Woodpecker's Go packages (`go.woodpecker-ci.org/woodpecker/v3`) and use the interfaces and types defined there. -In the `main` function, just call `"go.woodpecker-ci.org/woodpecker/v3/server/forge/addon".Serve` with a `"go.woodpecker-ci.org/woodpecker/v3/server/forge".Forge` as argument. +In the `main` function, just call the `Serve` method in the corresponding [addon package](#addon-types) with the service as argument. This will take care of connecting the addon forge to the server. :::note @@ -47,6 +29,8 @@ It is not possible to access global variables from Woodpecker, for example the s ### Example structure +This is an example for a forge addon. + ```go package main @@ -68,3 +52,10 @@ type config struct { // `config` must implement `"go.woodpecker-ci.org/woodpecker/v3/server/forge".Forge`. You must directly use Woodpecker's packages - see imports above. ``` + +### Addon types + +| Type | Addon package | Service interface | +| --------- | ------------------------------------------------------------- | ----------------------------------------------------------------- | +| Forge | `go.woodpecker-ci.org/woodpecker/v3/server/forge/addon` | `"go.woodpecker-ci.org/woodpecker/v3/server/forge".Forge` | +| Log store | `go.woodpecker-ci.org/woodpecker/v3/server/service/log/addon` | `"go.woodpecker-ci.org/woodpecker/v3/server/service/log".Service` | diff --git a/docs/versioned_docs/version-3.9/92-development/_category_.yaml b/docs/versioned_docs/version-3.12/92-development/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/_category_.yaml rename to docs/versioned_docs/version-3.12/92-development/_category_.yaml diff --git a/docs/versioned_docs/version-3.9/92-development/ui-proxy.svg b/docs/versioned_docs/version-3.12/92-development/ui-proxy.svg similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/ui-proxy.svg rename to docs/versioned_docs/version-3.12/92-development/ui-proxy.svg diff --git a/docs/versioned_docs/version-3.9/92-development/vscode-debug.png b/docs/versioned_docs/version-3.12/92-development/vscode-debug.png similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/vscode-debug.png rename to docs/versioned_docs/version-3.12/92-development/vscode-debug.png diff --git a/docs/versioned_docs/version-3.9/92-development/vscode-run-test.png b/docs/versioned_docs/version-3.12/92-development/vscode-run-test.png similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/vscode-run-test.png rename to docs/versioned_docs/version-3.12/92-development/vscode-run-test.png diff --git a/docs/versioned_docs/version-3.9/92-development/woodpecker-architecture.png b/docs/versioned_docs/version-3.12/92-development/woodpecker-architecture.png similarity index 100% rename from docs/versioned_docs/version-3.9/92-development/woodpecker-architecture.png rename to docs/versioned_docs/version-3.12/92-development/woodpecker-architecture.png diff --git a/docs/versioned_docs/version-3.9/20-usage/50-environment.md b/docs/versioned_docs/version-3.9/20-usage/50-environment.md deleted file mode 100644 index 858d5dd2c..000000000 --- a/docs/versioned_docs/version-3.9/20-usage/50-environment.md +++ /dev/null @@ -1,225 +0,0 @@ -# Environment variables - -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: - - name: 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: - - name: build - image: golang -- environment: -- - PATH=$PATH:/go - commands: -+ - export PATH=$PATH:/go - - go build - - go test -``` - -:::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: - - name: build - image: golang - commands: -- - export PATH=${PATH}:/go -+ - export PATH=$${PATH}:/go - - go build - - go test -``` - -## Built-in environment variables - -This is the reference list of all environment variables available to your pipeline containers. These are injected into your pipeline step and plugins containers, at runtime. - -| NAME | Description | Example | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | -| `CI` | CI environment name | `woodpecker` | -| | **Repository** | | -| `CI_REPO` | repository full name `/` | `john-doe/my-repo` | -| `CI_REPO_OWNER` | repository owner | `john-doe` | -| `CI_REPO_NAME` | repository name | `my-repo` | -| `CI_REPO_REMOTE_ID` | repository remote ID, is the UID it has in the forge | `82` | -| `CI_REPO_URL` | repository web URL | `https://git.example.com/john-doe/my-repo` | -| `CI_REPO_CLONE_URL` | repository clone URL | `https://git.example.com/john-doe/my-repo.git` | -| `CI_REPO_CLONE_SSH_URL` | repository SSH clone URL | `git@git.example.com:john-doe/my-repo.git` | -| `CI_REPO_DEFAULT_BRANCH` | repository default branch | `main` | -| `CI_REPO_PRIVATE` | repository is private | `true` | -| `CI_REPO_TRUSTED_NETWORK` | repository has trusted network access | `false` | -| `CI_REPO_TRUSTED_VOLUMES` | repository has trusted volumes access | `false` | -| `CI_REPO_TRUSTED_SECURITY` | repository has trusted security access | `false` | -| | **Current Commit** | | -| `CI_COMMIT_SHA` | commit SHA | `eba09b46064473a1d345da7abf28b477468e8dbd` | -| `CI_COMMIT_REF` | commit ref | `refs/heads/main` | -| `CI_COMMIT_REFSPEC` | commit ref spec | `issue-branch:main` | -| `CI_COMMIT_BRANCH` | commit branch (equals target branch for pull requests) | `main` | -| `CI_COMMIT_SOURCE_BRANCH` | commit source branch (set only for `pull_request` and `pull_request_closed` events) | `issue-branch` | -| `CI_COMMIT_TARGET_BRANCH` | commit target branch (set only for `pull_request` and `pull_request_closed` events) | `main` | -| `CI_COMMIT_TAG` | commit tag name (empty if event is not `tag`) | `v1.10.3` | -| `CI_COMMIT_PULL_REQUEST` | commit pull request number (set only for `pull_request` and `pull_request_closed` events) | `1` | -| `CI_COMMIT_PULL_REQUEST_LABELS` | labels assigned to pull request (set only for `pull_request` and `pull_request_closed` events) | `server` | -| `CI_COMMIT_MESSAGE` | commit message | `Initial commit` | -| `CI_COMMIT_AUTHOR` | commit author username | `john-doe` | -| `CI_COMMIT_AUTHOR_EMAIL` | commit author email address | `john-doe@example.com` | -| `CI_COMMIT_PRERELEASE` | release is a pre-release (empty if event is not `release`) | `false` | -| | **Current pipeline** | | -| `CI_PIPELINE_NUMBER` | pipeline number | `8` | -| `CI_PIPELINE_PARENT` | number of parent pipeline | `0` | -| `CI_PIPELINE_EVENT` | pipeline event (see [`event`](../20-usage/20-workflow-syntax.md#event)) | `push`, `pull_request`, `pull_request_closed`, `tag`, `release`, `manual`, `cron` | -| `CI_PIPELINE_URL` | link to the web UI for the pipeline | `https://ci.example.com/repos/7/pipeline/8` | -| `CI_PIPELINE_FORGE_URL` | link to the forge's web UI for the commit(s) or tag that triggered the pipeline | `https://git.example.com/john-doe/my-repo/commit/eba09b46064473a1d345da7abf28b477468e8dbd` | -| `CI_PIPELINE_DEPLOY_TARGET` | pipeline deploy target for `deployment` events | `production` | -| `CI_PIPELINE_DEPLOY_TASK` | pipeline deploy task for `deployment` events | `migration` | -| `CI_PIPELINE_CREATED` | pipeline created UNIX timestamp | `1722617519` | -| `CI_PIPELINE_STARTED` | pipeline started UNIX timestamp | `1722617519` | -| `CI_PIPELINE_FILES` | changed files (empty if event is not `push` or `pull_request`), it is undefined if more than 500 files are touched | `[]`, `[".woodpecker.yml","README.md"]` | -| `CI_PIPELINE_AUTHOR` | pipeline author username | `octocat` | -| `CI_PIPELINE_AVATAR` | pipeline author avatar | `https://git.example.com/avatars/5dcbcadbce6f87f8abef` | -| | **Current workflow** | | -| `CI_WORKFLOW_NAME` | workflow name | `release` | -| | **Current step** | | -| `CI_STEP_NAME` | step name | `build package` | -| `CI_STEP_NUMBER` | step number | `0` | -| `CI_STEP_STARTED` | step started UNIX timestamp | `1722617519` | -| `CI_STEP_URL` | URL to step in UI | `https://ci.example.com/repos/7/pipeline/8` | -| | **Previous commit** | | -| `CI_PREV_COMMIT_SHA` | previous commit SHA | `15784117e4e103f36cba75a9e29da48046eb82c4` | -| `CI_PREV_COMMIT_REF` | previous commit ref | `refs/heads/main` | -| `CI_PREV_COMMIT_REFSPEC` | previous commit ref spec | `issue-branch:main` | -| `CI_PREV_COMMIT_BRANCH` | previous commit branch | `main` | -| `CI_PREV_COMMIT_SOURCE_BRANCH` | previous commit source branch (set only for `pull_request` and `pull_request_closed` events) | `issue-branch` | -| `CI_PREV_COMMIT_TARGET_BRANCH` | previous commit target branch (set only for `pull_request` and `pull_request_closed` events) | `main` | -| `CI_PREV_COMMIT_URL` | previous commit link in forge | `https://git.example.com/john-doe/my-repo/commit/15784117e4e103f36cba75a9e29da48046eb82c4` | -| `CI_PREV_COMMIT_MESSAGE` | previous commit message | `test` | -| `CI_PREV_COMMIT_AUTHOR` | previous commit author username | `john-doe` | -| `CI_PREV_COMMIT_AUTHOR_EMAIL` | previous commit author email address | `john-doe@example.com` | -| | **Previous pipeline** | | -| `CI_PREV_PIPELINE_NUMBER` | previous pipeline number | `7` | -| `CI_PREV_PIPELINE_PARENT` | previous pipeline number of parent pipeline | `0` | -| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (see [`event`](../20-usage/20-workflow-syntax.md#event)) | `push`, `pull_request`, `pull_request_closed`, `tag`, `release`, `manual`, `cron` | -| `CI_PREV_PIPELINE_URL` | previous pipeline link in CI | `https://ci.example.com/repos/7/pipeline/7` | -| `CI_PREV_PIPELINE_FORGE_URL` | previous pipeline link to event in forge | `https://git.example.com/john-doe/my-repo/commit/15784117e4e103f36cba75a9e29da48046eb82c4` | -| `CI_PREV_PIPELINE_DEPLOY_TARGET` | previous pipeline deploy target for `deployment` events | `production` | -| `CI_PREV_PIPELINE_DEPLOY_TASK` | previous pipeline deploy task for `deployment` events | `migration` | -| `CI_PREV_PIPELINE_STATUS` | previous pipeline status | `success`, `failure` | -| `CI_PREV_PIPELINE_CREATED` | previous pipeline created UNIX timestamp | `1722610173` | -| `CI_PREV_PIPELINE_STARTED` | previous pipeline started UNIX timestamp | `1722610173` | -| `CI_PREV_PIPELINE_FINISHED` | previous pipeline finished UNIX timestamp | `1722610383` | -| `CI_PREV_PIPELINE_AUTHOR` | previous pipeline author username | `octocat` | -| `CI_PREV_PIPELINE_AVATAR` | previous pipeline author avatar | `https://git.example.com/avatars/5dcbcadbce6f87f8abef` | -| |   | | -| `CI_WORKSPACE` | Path of the workspace where source code gets cloned to | `/woodpecker/src/git.example.com/john-doe/my-repo` | -| | **System** | | -| `CI_SYSTEM_NAME` | name of the CI system | `woodpecker` | -| `CI_SYSTEM_URL` | link to CI system | `https://ci.example.com` | -| `CI_SYSTEM_HOST` | hostname of CI server | `ci.example.com` | -| `CI_SYSTEM_VERSION` | version of the server | `2.7.0` | -| | **Forge** | | -| `CI_FORGE_TYPE` | name of forge | `bitbucket` , `bitbucket_dc` , `forgejo` , `gitea` , `github` , `gitlab` | -| `CI_FORGE_URL` | root URL of configured forge | `https://git.example.com` | -| | **Internal** - Please don't use! | | -| `CI_SCRIPT` | Internal script path. Used to call pipeline step commands. | | -| `CI_NETRC_USERNAME` | Credentials for private repos to be able to clone data. (Only available for specific images) | | -| `CI_NETRC_PASSWORD` | Credentials for private repos to be able to clone data. (Only available for specific images) | | -| `CI_NETRC_MACHINE` | Credentials for private repos to be able to clone data. (Only available for specific images) | | - -## Global environment variables - -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. - -```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: - - name: build -- image: golang:1.18 -+ image: golang:${GOLANG_VERSION} - commands: - - [...] -``` - -## String Substitution - -Woodpecker provides the ability to substitute environment variables at runtime. This gives us the ability to use dynamic settings, commands and filters in our pipeline configuration. - -Example commit substitution: - -```diff - steps: - - name: s3 - image: woodpeckerci/plugin-s3 - settings: -+ target: /target/${CI_COMMIT_SHA} -``` - -Example tag substitution: - -```diff - steps: - - name: s3 - image: woodpeckerci/plugin-s3 - settings: -+ target: /target/${CI_COMMIT_TAG} -``` - -## String Operations - -Woodpecker also emulates bash string operations. This gives us the ability to manipulate the strings prior to substitution. Example use cases might include substring and stripping prefix or suffix values. - -| OPERATION | DESCRIPTION | -| ------------------ | ------------------------------------------------ | -| `${param}` | parameter substitution | -| `${param,}` | parameter substitution with lowercase first char | -| `${param,,}` | parameter substitution with lowercase | -| `${param^}` | parameter substitution with uppercase first char | -| `${param^^}` | parameter substitution with uppercase | -| `${param:pos}` | parameter substitution with substring | -| `${param:pos:len}` | parameter substitution with substring and length | -| `${param=default}` | parameter substitution with default | -| `${param##prefix}` | parameter substitution with prefix removal | -| `${param%%suffix}` | parameter substitution with suffix removal | -| `${param/old/new}` | parameter substitution with find and replace | - -Example variable substitution with substring: - -```diff - steps: - - name: s3 - image: woodpeckerci/plugin-s3 - settings: -+ target: /target/${CI_COMMIT_SHA:0:8} -``` - -Example variable substitution strips `v` prefix from `v.1.0.0`: - -```diff - steps: - - name: s3 - image: woodpeckerci/plugin-s3 - settings: -+ target: /target/${CI_COMMIT_TAG##v} -``` diff --git a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/11-overview.md b/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/11-overview.md deleted file mode 100644 index e819ea73d..000000000 --- a/docs/versioned_docs/version-3.9/30-administration/10-configuration/12-forges/11-overview.md +++ /dev/null @@ -1,15 +0,0 @@ -# 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: | :white_check_mark: | - -¹ The deployment event can be triggered for all forges from Woodpecker directly. However, only GitHub can trigger them using webhooks. diff --git a/docs/versioned_sidebars/version-3.9-sidebars.json b/docs/versioned_sidebars/version-3.12-sidebars.json similarity index 100% rename from docs/versioned_sidebars/version-3.9-sidebars.json rename to docs/versioned_sidebars/version-3.12-sidebars.json diff --git a/docs/versions.json b/docs/versions.json index 429ce1954..2988f8fd6 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1 +1 @@ -["3.11", "3.10", "3.9", "2.8"] +["3.12", "3.11", "3.10", "2.8"]