github/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2026-02-13 21:00:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add 3.10 docs (#5564)

Browse Source 
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
This commit is contained in:
Robert Kaussow
2025-09-28 22:07:29 +02:00
committed by GitHub
parent 15360ab0f1
commit 9ee7754f2b
86 changed files with 19415 additions and 259 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.pre-commit-config.yaml
View File

@@ -9,6 +9,7 @@ repos:
hooks: hooks:
- id: end-of-file-fixer - id: end-of-file-fixer
- id: trailing-whitespace - id: trailing-whitespace
exclude: ^docs/versioned_docs/.+/40-cli.md$
- repo: https://github.com/golangci/golangci-lint - repo: https://github.com/golangci/golangci-lint
rev: v2.5.0 rev: v2.5.0
hooks: hooks:

2
docs/.prettierignore
View File

@@ -2,5 +2,5 @@ pnpm-lock.yaml
dist dist
LICENSE LICENSE
openapi.json openapi.json
docs/40-cli.md 40-cli.md
build/ build/

19001
docs/package-lock.json generated Normal file
View File

File diff suppressed because it is too large Load Diff

4
docs/src/pages/versions.md
View File

@@ -33,6 +33,10 @@ Here you can find documentation for previous versions of Woodpecker.
| | | | | | | |
| ------- | ---------- | ------------------------------------------------------------------------------------- | | ------- | ---------- | ------------------------------------------------------------------------------------- |
| 3.10.0 | 2025-29-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/) |
| 3.8.0 | 2025-07-05 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.8.0/docs/docs/) |
| 3.7.0 | 2025-06-06 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.7.0/docs/docs/) |
| 3.6.0 | 2025-05-06 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.6.0/docs/docs/) | | 3.6.0 | 2025-05-06 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.6.0/docs/docs/) |
| 3.5.0 | 2025-04-02 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.5.0/docs/docs/) | | 3.5.0 | 2025-04-02 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.5.0/docs/docs/) |
| 3.4.0 | 2025-03-17 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.4.0/docs/docs/) | | 3.4.0 | 2025-03-17 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.4.0/docs/docs/) |

0
docs/versioned_docs/version-3.7/10-intro/index.md → docs/versioned_docs/version-3.10/10-intro/index.md
View File

0
docs/versioned_docs/version-3.7/20-usage/10-intro.md → docs/versioned_docs/version-3.10/20-usage/10-intro.md
View File

0
docs/versioned_docs/version-3.7/20-usage/100-troubleshooting.md → docs/versioned_docs/version-3.10/20-usage/100-troubleshooting.md
View File

0
docs/versioned_docs/version-3.7/20-usage/15-terminology/architecture.excalidraw → docs/versioned_docs/version-3.10/20-usage/15-terminology/architecture.excalidraw
View File

0
docs/versioned_docs/version-3.7/20-usage/15-terminology/architecture.svg → docs/versioned_docs/version-3.10/20-usage/15-terminology/architecture.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 31 KiB

0
docs/versioned_docs/version-3.7/20-usage/15-terminology/index.md → docs/versioned_docs/version-3.10/20-usage/15-terminology/index.md
View File

0
docs/versioned_docs/version-3.7/20-usage/15-terminology/pipeline-workflow-step.excalidraw → docs/versioned_docs/version-3.10/20-usage/15-terminology/pipeline-workflow-step.excalidraw
View File

0
docs/versioned_docs/version-3.7/20-usage/15-terminology/pipeline-workflow-step.svg → docs/versioned_docs/version-3.10/20-usage/15-terminology/pipeline-workflow-step.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 21 KiB

15
docs/versioned_docs/version-3.7/20-usage/20-workflow-syntax.md → docs/versioned_docs/version-3.10/20-usage/20-workflow-syntax.md
View File

@@ -103,9 +103,8 @@ When using the `local` backend, the `image` entry is used to specify the shell,
- go build - go build
- go test - go test
- name: publish - name: prettier
+ image: woodpeckerci/plugin-kaniko + image: woodpeckerci/plugin-prettier
repo: foo/bar
services: services:
- name: database - name: database
@@ -285,6 +284,7 @@ The available events are:
- `push`: triggered when a commit is pushed to a branch. - `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`: 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_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. - `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).) - `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.) - `deployment`: triggered when a deployment is created in the repository. (This event can be triggered from Woodpecker directly. GitHub also supports webhook triggers.)
@@ -393,8 +393,7 @@ when:
#### `path` #### `path`
:::info :::info
Path conditions are applied only to **push** and **pull_request** events. Path conditions are applied only to **push** and **pull_request** events. This feature is currently available for all forges except Bitbucket Cloud.
It is currently **only available** for GitHub, GitLab and Gitea (version 1.18.0 and newer)
::: :::
Execute a step only on a pipeline with certain files being changed: Execute a step only on a pipeline with certain files being changed:
@@ -474,9 +473,11 @@ Normally steps of a workflow are executed serially in the order in which they ar
- go build - go build
- name: deploy - name: deploy
image: woodpeckerci/plugin-kaniko image: woodpeckerci/plugin-s3
settings: settings:
repo: foo/bar bucket: my-bucket-name
source: some-file-name
target: /target/some-file
+ depends_on: [build, test] # deploy will be executed after build and test finished + depends_on: [build, test] # deploy will be executed after build and test finished
- name: test # test will be executed immediately as no dependencies are set - name: test # test will be executed immediately as no dependencies are set

0
docs/versioned_docs/version-3.7/20-usage/25-workflows.md → docs/versioned_docs/version-3.10/20-usage/25-workflows.md
View File

0
docs/versioned_docs/version-3.7/20-usage/30-matrix-workflows.md → docs/versioned_docs/version-3.10/20-usage/30-matrix-workflows.md
View File

0
docs/versioned_docs/version-3.7/20-usage/40-secrets.md → docs/versioned_docs/version-3.10/20-usage/40-secrets.md
View File

0
docs/versioned_docs/version-3.7/20-usage/41-registries.md → docs/versioned_docs/version-3.10/20-usage/41-registries.md
View File

0
docs/versioned_docs/version-3.7/20-usage/45-cron.md → docs/versioned_docs/version-3.10/20-usage/45-cron.md
View File

259
docs/versioned_docs/version-3.10/20-usage/50-environment.md Normal file
View File

@@ -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 `<owner>/<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` |
| | &emsp; | |
| `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).

0
docs/versioned_docs/version-3.7/20-usage/51-plugins/20-creating-plugins.md → docs/versioned_docs/version-3.10/20-usage/51-plugins/20-creating-plugins.md
View File

9
docs/versioned_docs/version-3.7/20-usage/51-plugins/51-overview.md → docs/versioned_docs/version-3.10/20-usage/51-plugins/51-overview.md
View File

@@ -23,7 +23,7 @@ steps:
template: config/k8s/service.yaml template: config/k8s/service.yaml
``` ```
Example pipeline using the Docker and Prettier plugins: Example pipeline using the Prettier and S3 plugins:
```yaml ```yaml
steps: steps:
@@ -37,10 +37,11 @@ steps:
image: woodpeckerci/plugin-prettier image: woodpeckerci/plugin-prettier
- name: publish - name: publish
image: woodpeckerci/plugin-kaniko image: woodpeckerci/plugin-s3
settings: settings:
repo: foo/bar bucket: my-bucket-name
tags: latest source: some-file-name
target: /target/some-file
``` ```
## Plugin Isolation ## Plugin Isolation

0
docs/versioned_docs/version-3.7/20-usage/51-plugins/_category_.yaml → docs/versioned_docs/version-3.10/20-usage/51-plugins/_category_.yaml
View File

0
docs/versioned_docs/version-3.7/20-usage/60-services.md → docs/versioned_docs/version-3.10/20-usage/60-services.md
View File

0
docs/versioned_docs/version-3.7/20-usage/70-volumes.md → docs/versioned_docs/version-3.10/20-usage/70-volumes.md
View File

0
docs/versioned_docs/version-3.7/20-usage/72-linter.md → docs/versioned_docs/version-3.10/20-usage/72-linter.md
View File

0
docs/versioned_docs/version-3.7/20-usage/75-project-settings.md → docs/versioned_docs/version-3.10/20-usage/75-project-settings.md
View File

0
docs/versioned_docs/version-3.7/20-usage/80-badges.md → docs/versioned_docs/version-3.10/20-usage/80-badges.md
View File

0
docs/versioned_docs/version-3.7/20-usage/90-advanced-usage.md → docs/versioned_docs/version-3.10/20-usage/90-advanced-usage.md
View File

0
docs/versioned_docs/version-3.7/20-usage/_category_.yaml → docs/versioned_docs/version-3.10/20-usage/_category_.yaml
View File

0
docs/versioned_docs/version-3.7/20-usage/cron-settings.png → docs/versioned_docs/version-3.10/20-usage/cron-settings.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 40 KiB

0
docs/versioned_docs/version-3.7/20-usage/linter-warnings-errors.png → docs/versioned_docs/version-3.10/20-usage/linter-warnings-errors.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 113 KiB

After

Width:  |  Height:  |  Size: 113 KiB

0
docs/versioned_docs/version-3.7/20-usage/pipeline.png → docs/versioned_docs/version-3.10/20-usage/pipeline.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 430 KiB

After

Width:  |  Height:  |  Size: 430 KiB

0
docs/versioned_docs/version-3.7/20-usage/project-settings.png → docs/versioned_docs/version-3.10/20-usage/project-settings.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 353 KiB

After

Width:  |  Height:  |  Size: 353 KiB

0
docs/versioned_docs/version-3.7/20-usage/repo-new.png → docs/versioned_docs/version-3.10/20-usage/repo-new.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 351 KiB

After

Width:  |  Height:  |  Size: 351 KiB

0
docs/versioned_docs/version-3.7/20-usage/secrets-plugins-filter.png → docs/versioned_docs/version-3.10/20-usage/secrets-plugins-filter.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 29 KiB

After

Width:  |  Height:  |  Size: 29 KiB

0
docs/versioned_docs/version-3.7/30-administration/00-general.md → docs/versioned_docs/version-3.10/30-administration/00-general.md
View File

0
docs/versioned_docs/version-3.7/30-administration/05-installation/10-docker-compose.md → docs/versioned_docs/version-3.10/30-administration/05-installation/10-docker-compose.md
View File

0
docs/versioned_docs/version-3.7/30-administration/05-installation/20-helm-chart.md → docs/versioned_docs/version-3.10/30-administration/05-installation/20-helm-chart.md
View File

3
docs/versioned_docs/version-3.7/30-administration/05-installation/30-packages.md → docs/versioned_docs/version-3.10/30-administration/05-installation/30-packages.md
View File

@@ -56,7 +56,7 @@ After installing the agent, copy the example environment file `/etc/woodpecker/w
```ini title="/usr/local/lib/systemd/system/woodpecker-agent.service" ```ini title="/usr/local/lib/systemd/system/woodpecker-agent.service"
[Unit] [Unit]
Description=WoodpeckerCI agent Description=WoodpeckerCI agent
Documentation=https://woodpecker-ci.org/docs/administration/agent-config Documentation=https://woodpecker-ci.org/docs/administration/configuration/agent
Requires=network.target Requires=network.target
After=network.target After=network.target
ConditionFileNotEmpty=/etc/woodpecker/woodpecker-agent.env ConditionFileNotEmpty=/etc/woodpecker/woodpecker-agent.env
@@ -91,6 +91,7 @@ Woodpecker itself is not responsible for creating these packages. Please reach o
- [openSUSE](https://software.opensuse.org/package/woodpecker) - [openSUSE](https://software.opensuse.org/package/woodpecker)
- [YunoHost](https://apps.yunohost.org/app/woodpecker) - [YunoHost](https://apps.yunohost.org/app/woodpecker)
- [Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html) - [Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html)
- [Easypanel](https://easypanel.io/docs/templates/woodpeckerci)
### NixOS ### NixOS

0
docs/versioned_docs/version-3.7/30-administration/05-installation/_category_.yaml → docs/versioned_docs/version-3.10/30-administration/05-installation/_category_.yaml
View File

9
docs/versioned_docs/version-3.7/30-administration/10-configuration/10-server.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/10-server.md
View File

@@ -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 ### DEFAULT_CANCEL_PREVIOUS_PIPELINE_EVENTS
- Name: `WOODPECKER_DEFAULT_CANCEL_PREVIOUS_PIPELINE_EVENTS` - Name: `WOODPECKER_DEFAULT_CANCEL_PREVIOUS_PIPELINE_EVENTS`

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/11-backends/10-docker.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/11-backends/10-docker.md
View File

47
docs/versioned_docs/version-3.7/30-administration/10-configuration/11-backends/20-kubernetes.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/11-backends/20-kubernetes.md
View File

@@ -19,6 +19,8 @@ The following metadata labels are supported:
- `woodpecker-ci.org/repo-full-name` - `woodpecker-ci.org/repo-full-name`
- `woodpecker-ci.org/branch` - `woodpecker-ci.org/branch`
- `woodpecker-ci.org/org-id` - `woodpecker-ci.org/org-id`
- `woodpecker-ci.org/task-uuid`
- `woodpecker-ci.org/step`
## Private registries ## Private registries
@@ -250,6 +252,15 @@ backend_options:
localhostProfile: k8s-apparmor-example-deny-write localhostProfile: k8s-apparmor-example-deny-write
``` ```
or configure a specific `fsGroupChangePolicy` (Kubernetes defaults to 'Always')
```yaml
backend_options:
kubernetes:
securityContext:
fsGroupChangePolicy: OnRootMismatch
```
:::note :::note
The feature requires Kubernetes v1.30 or above. The feature requires Kubernetes v1.30 or above.
::: :::
@@ -308,6 +319,15 @@ The namespace to create worker Pods in.
--- ---
### BACKEND_K8S_NAMESPACE_PER_ORGANIZATION
- Name: `WOODPECKER_BACKEND_K8S_NAMESPACE_PER_ORGANIZATION`
- Default: `false`
Enables namespace isolation per Woodpecker organization. When enabled, each organization gets its own dedicated Kubernetes namespace for improved security and resource isolation.
With this feature enabled, Woodpecker creates separate Kubernetes namespaces for each organization using the format `{WOODPECKER_BACKEND_K8S_NAMESPACE}-{organization-id}`. Namespaces are created automatically when needed, but they are not automatically deleted when organizations are removed from Woodpecker.
### BACKEND_K8S_VOLUME_SIZE ### BACKEND_K8S_VOLUME_SIZE
- Name: `WOODPECKER_BACKEND_K8S_VOLUME_SIZE` - Name: `WOODPECKER_BACKEND_K8S_VOLUME_SIZE`
@@ -371,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 ### BACKEND_K8S_POD_NODE_SELECTOR
- Name: `WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR` - Name: `WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR`
@@ -395,3 +433,12 @@ Determines if containers must be required to run as non-root users.
- Default: none - 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/). 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.

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/11-backends/30-local.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/11-backends/30-local.md
View File

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/11-backends/50-custom.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/11-backends/50-custom.md
View File

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/11-backends/_category_.yaml → docs/versioned_docs/version-3.10/30-administration/10-configuration/11-backends/_category_.yaml
View File

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/12-forges/100-addon.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/12-forges/100-addon.md
View File

16
docs/versioned_docs/version-3.10/30-administration/10-configuration/12-forges/11-overview.md Normal file
View File

@@ -0,0 +1,16 @@
# 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: | :x: | :white_check_mark: |
¹ The deployment event can be triggered for all forges from Woodpecker directly. However, only GitHub can trigger them using webhooks.

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/12-forges/20-github.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/12-forges/20-github.md
View File

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/12-forges/30-gitea.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/12-forges/30-gitea.md
View File

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/12-forges/35-forgejo.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/12-forges/35-forgejo.md
View File

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/12-forges/40-gitlab.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/12-forges/40-gitlab.md
View File

4
docs/versioned_docs/version-3.7/30-administration/10-configuration/12-forges/50-bitbucket.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/12-forges/50-bitbucket.md
View File

@@ -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 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 ## Missing Features
Path filters for pull requests are not supported. We are interested in patches to include this functionality. Path filters for pull requests are not supported. We are interested in patches to include this functionality.

10
docs/versioned_docs/version-3.7/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.md
View File

@@ -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_ID=xxx
+ - WOODPECKER_BITBUCKET_DC_CLIENT_SECRET=yyy + - WOODPECKER_BITBUCKET_DC_CLIENT_SECRET=yyy
+ - WOODPECKER_BITBUCKET_DC_URL=http://stash.mycompany.com + - WOODPECKER_BITBUCKET_DC_URL=http://stash.mycompany.com
+ - WOODPECKER_BITBUCKET_DC_ENABLE_OAUTH2_SCOPE_PROJECT_ADMIN=true
woodpecker-agent: woodpecker-agent:
[...] [...]
@@ -124,3 +125,12 @@ Read the value for `WOODPECKER_BITBUCKET_DC_GIT_PASSWORD` from the specified fil
- Default: `false` - Default: `false`
Configure if SSL verification should be skipped. 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.

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/12-forges/_category_.yaml → docs/versioned_docs/version-3.10/30-administration/10-configuration/12-forges/_category_.yaml
View File

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/12-forges/bitbucket_oauth.png → docs/versioned_docs/version-3.10/30-administration/10-configuration/12-forges/bitbucket_oauth.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 29 KiB

After

Width:  |  Height:  |  Size: 29 KiB

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/12-forges/bitbucket_permissions.png → docs/versioned_docs/version-3.10/30-administration/10-configuration/12-forges/bitbucket_permissions.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 20 KiB

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/12-forges/gitea_oauth.gif → docs/versioned_docs/version-3.10/30-administration/10-configuration/12-forges/gitea_oauth.gif
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 129 KiB

After

Width:  |  Height:  |  Size: 129 KiB

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/12-forges/github_oauth.png → docs/versioned_docs/version-3.10/30-administration/10-configuration/12-forges/github_oauth.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 25 KiB

After

Width:  |  Height:  |  Size: 25 KiB

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/30-agent.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/30-agent.md
View File

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/40-autoscaler.md → docs/versioned_docs/version-3.10/30-administration/10-configuration/40-autoscaler.md
View File

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/_category_.yaml → docs/versioned_docs/version-3.10/30-administration/10-configuration/_category_.yaml
View File

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/new-agent-connected.png → docs/versioned_docs/version-3.10/30-administration/10-configuration/new-agent-connected.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.3 KiB

After

Width:  |  Height:  |  Size: 5.3 KiB

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/new-agent-created.png → docs/versioned_docs/version-3.10/30-administration/10-configuration/new-agent-created.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.4 KiB

After

Width:  |  Height:  |  Size: 4.4 KiB

0
docs/versioned_docs/version-3.7/30-administration/10-configuration/new-agent-registration.png → docs/versioned_docs/version-3.10/30-administration/10-configuration/new-agent-registration.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 25 KiB

After

Width:  |  Height:  |  Size: 25 KiB

0
docs/versioned_docs/version-3.7/30-administration/_category_.yaml → docs/versioned_docs/version-3.10/30-administration/_category_.yaml
View File

45
docs/versioned_docs/version-3.7/40-cli.md → docs/versioned_docs/version-3.10/40-cli.md
View File

@@ -56,6 +56,7 @@ woodpecker-cli [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...]
**--token, -t**="": server auth token **--token, -t**="": server auth token
# COMMANDS # COMMANDS
## admin ## admin
@@ -66,6 +67,18 @@ manage server settings
retrieve log level from server, or set it with [level] retrieve log level from server, or set it with [level]
### org
manage organizations
#### ls
list organizations
**--format**="": format output (deprecated) (default: {{ .Name }} 
Organization ID: {{ .ID }}
)
### registry ### registry
manage global registries manage global registries
@@ -243,7 +256,9 @@ execute a local pipeline
**--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
**--backend-k8s-namespace**="": backend k8s namespace (default: woodpecker) **--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-pod-annotations**="": backend k8s additional Agent-wide worker pod annotations **--backend-k8s-pod-annotations**="": backend k8s additional Agent-wide worker pod annotations
@@ -257,6 +272,12 @@ execute a local pipeline
**--backend-k8s-pod-node-selector**="": backend k8s Agent-wide worker pod node selector **--backend-k8s-pod-node-selector**="": backend k8s Agent-wide worker pod node selector
**--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
**--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 **--backend-k8s-secctx-nonroot**: `run as non root` Kubernetes security context option
**--backend-k8s-storage-class**="": backend k8s storage class **--backend-k8s-storage-class**="": backend k8s storage class
@@ -269,6 +290,8 @@ execute a local pipeline
**--backend-no-proxy**="": if set, pass the environment variable down as "NO_PROXY" to steps **--backend-no-proxy**="": if set, pass the environment variable down as "NO_PROXY" to steps
**--commit-author-avatar**="": Set the metadata environment variable "CI_COMMIT_AUTHOR_AVATAR".
**--commit-author-email**="": Set the metadata environment variable "CI_COMMIT_AUTHOR_EMAIL". **--commit-author-email**="": Set the metadata environment variable "CI_COMMIT_AUTHOR_EMAIL".
**--commit-author-name**="": Set the metadata environment variable "CI_COMMIT_AUTHOR". **--commit-author-name**="": Set the metadata environment variable "CI_COMMIT_AUTHOR".
@@ -279,6 +302,8 @@ execute a local pipeline
**--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". (default: [])
**--commit-pull-milestone**="": Set the metadata environment variable "CI_COMMIT_PULL_REQUEST_MILESTONE".
**--commit-ref**="": Set the metadata environment variable "CI_COMMIT_REF". **--commit-ref**="": Set the metadata environment variable "CI_COMMIT_REF".
**--commit-refspec**="": Set the metadata environment variable "CI_COMMIT_REFSPEC". **--commit-refspec**="": Set the metadata environment variable "CI_COMMIT_REFSPEC".
@@ -297,11 +322,11 @@ execute a local pipeline
**--metadata-file**="": path to pipeline metadata file (normally downloaded from UI). Parameters can be adjusted by applying additional cli flags **--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 (default: [])
@@ -325,6 +350,8 @@ execute a local pipeline
**--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 (default: [])
**--prev-commit-author-avatar**="": Set the metadata environment variable "CI_PREV_COMMIT_AUTHOR_AVATAR".
**--prev-commit-author-email**="": Set the metadata environment variable "CI_PREV_COMMIT_AUTHOR_EMAIL". **--prev-commit-author-email**="": Set the metadata environment variable "CI_PREV_COMMIT_AUTHOR_EMAIL".
**--prev-commit-author-name**="": Set the metadata environment variable "CI_PREV_COMMIT_AUTHOR". **--prev-commit-author-name**="": Set the metadata environment variable "CI_PREV_COMMIT_AUTHOR".
@@ -379,6 +406,10 @@ execute a local pipeline
**--repo-url**="": Set the metadata environment variable "CI_REPO_URL". **--repo-url**="": Set the metadata environment variable "CI_REPO_URL".
**--secrets**="": map of secrets, ex. 'secret="val",secret2="value2"' (default: map[])
**--secrets**="": path to yaml file with secrets map
**--system-host**="": Set the metadata environment variable "CI_SYSTEM_HOST". **--system-host**="": Set the metadata environment variable "CI_SYSTEM_HOST".
**--system-name**="": Set the metadata environment variable "CI_SYSTEM_NAME". (default: woodpecker) **--system-name**="": Set the metadata environment variable "CI_SYSTEM_NAME". (default: woodpecker)
@@ -395,9 +426,9 @@ execute a local pipeline
**--workflow-number**="": Set the metadata environment variable "CI_WORKFLOW_NUMBER". (default: 0) **--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 ## info
@@ -412,7 +443,7 @@ 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 (default: [])
**--plugins-trusted-clone**="": plugins that are trusted to handle Git credentials in cloning steps (default: [docker.io/woodpeckerci/plugin-git:2.6.3 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.6.5 docker.io/woodpeckerci/plugin-git quay.io/woodpeckerci/plugin-git])
**--strict**: treat warnings as errors **--strict**: treat warnings as errors

0
docs/versioned_docs/version-3.7/92-development/01-getting-started.md → docs/versioned_docs/version-3.10/92-development/01-getting-started.md
View File

0
docs/versioned_docs/version-3.7/92-development/02-core-ideas.md → docs/versioned_docs/version-3.10/92-development/02-core-ideas.md
View File

9
docs/versioned_docs/version-3.7/92-development/03-ui.md → docs/versioned_docs/version-3.10/92-development/03-ui.md
View File

@@ -13,6 +13,15 @@ Testing UI changes would require us to rebuild the UI after each adjustment to t
Start the UI server locally with [hot-reloading](https://stackoverflow.com/a/41429055/8461267) by running: `pnpm start`. To enable the forwarding of requests to the UI server you have to enable the dev-proxy inside the Woodpecker server by adding `WOODPECKER_DEV_WWW_PROXY=http://localhost:8010` to your `.env` file. Start the UI server locally with [hot-reloading](https://stackoverflow.com/a/41429055/8461267) by running: `pnpm start`. To enable the forwarding of requests to the UI server you have to enable the dev-proxy inside the Woodpecker server by adding `WOODPECKER_DEV_WWW_PROXY=http://localhost:8010` to your `.env` file.
After starting the Woodpecker server as explained in the [debugging](./01-getting-started.md#debugging-woodpecker) section, you should now be able to access the UI under [http://localhost:8000](http://localhost:8000). After starting the Woodpecker server as explained in the [debugging](./01-getting-started.md#debugging-woodpecker) section, you should now be able to access the UI under [http://localhost:8000](http://localhost:8000).
### Usage with remote server
If you would like to test your UI changes on a "real-world" Woodpecker server which probably has more complex data than local test instances, you can run `pnpm start` with these environment variables:
- `VITE_DEV_PROXY`: your server URL, for example `https://ci.woodpecker-ci.org`
- `VITE_DEV_USER_SESS_COOKIE`: the value `user_sess` cookie in your browser
Then, open the UI at `http://localhost:8010`.
## Tools and frameworks ## Tools and frameworks
The following list contains some tools and frameworks used by the Woodpecker UI. For some points we added some guidelines / hints to help you developing. The following list contains some tools and frameworks used by the Woodpecker UI. For some points we added some guidelines / hints to help you developing.

0
docs/versioned_docs/version-3.7/92-development/04-docs.md → docs/versioned_docs/version-3.10/92-development/04-docs.md
View File

0
docs/versioned_docs/version-3.7/92-development/05-architecture.md → docs/versioned_docs/version-3.10/92-development/05-architecture.md
View File

0
docs/versioned_docs/version-3.7/92-development/06-conventions.md → docs/versioned_docs/version-3.10/92-development/06-conventions.md
View File

0
docs/versioned_docs/version-3.7/92-development/07-guides.md → docs/versioned_docs/version-3.10/92-development/07-guides.md
View File

0
docs/versioned_docs/version-3.7/92-development/08-translations.md → docs/versioned_docs/version-3.10/92-development/08-translations.md
View File

0
docs/versioned_docs/version-3.7/92-development/09-openapi.md → docs/versioned_docs/version-3.10/92-development/09-openapi.md
View File

0
docs/versioned_docs/version-3.7/92-development/09-testing.md → docs/versioned_docs/version-3.10/92-development/09-testing.md
View File

0
docs/versioned_docs/version-3.7/92-development/_category_.yaml → docs/versioned_docs/version-3.10/92-development/_category_.yaml
View File

0
docs/versioned_docs/version-3.7/92-development/ui-proxy.svg → docs/versioned_docs/version-3.10/92-development/ui-proxy.svg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.5 KiB

After

Width:  |  Height:  |  Size: 7.5 KiB

0
docs/versioned_docs/version-3.7/92-development/vscode-debug.png → docs/versioned_docs/version-3.10/92-development/vscode-debug.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 17 KiB

After

Width:  |  Height:  |  Size: 17 KiB

0
docs/versioned_docs/version-3.7/92-development/vscode-run-test.png → docs/versioned_docs/version-3.10/92-development/vscode-run-test.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

0
docs/versioned_docs/version-3.7/92-development/woodpecker-architecture.png → docs/versioned_docs/version-3.10/92-development/woodpecker-architecture.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 61 KiB

After

Width:  |  Height:  |  Size: 61 KiB

223
docs/versioned_docs/version-3.7/20-usage/50-environment.md
View File

@@ -1,223 +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 `<owner>/<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_AUTHOR_AVATAR` | commit author avatar | `https://git.example.com/avatars/5dcbcadbce6f87f8abef` |
| `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"]` |
| | **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` |
| `CI_PREV_COMMIT_AUTHOR_AVATAR` | previous commit author avatar | `https://git.example.com/avatars/12` |
| | **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` |
| | &emsp; | |
| `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: docker
image: woodpeckerci/plugin-kaniko
settings:
+ tags: ${CI_COMMIT_SHA}
```
Example tag substitution:
```diff
steps:
- name: docker
image: woodpeckerci/plugin-kaniko
settings:
+ tags: ${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: docker
image: woodpeckerci/plugin-kaniko
settings:
+ tags: ${CI_COMMIT_SHA:0:8}
```
Example variable substitution strips `v` prefix from `v.1.0.0`:
```diff
steps:
- name: docker
image: woodpeckerci/plugin-kaniko
settings:
+ tags: ${CI_COMMIT_TAG##v}
```

15
docs/versioned_docs/version-3.7/30-administration/10-configuration/12-forges/11-overview.md
View File

@@ -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: | :x: |
¹ The deployment event can be triggered for all forges from Woodpecker directly. However, only GitHub can trigger them using webhooks.

0
docs/versioned_sidebars/version-3.7-sidebars.json → docs/versioned_sidebars/version-3.10-sidebars.json
View File

2
docs/versions.json
View File

@@ -1 +1 @@
["3.9", "3.8", "3.7", "2.8"] ["3.10", "3.9", "3.8", "2.8"]