You've already forked woodpecker
mirror of
https://github.com/woodpecker-ci/woodpecker.git
synced 2025-10-30 23:27:39 +02:00
Add 3.10 docs (#5564)
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
This commit is contained in:
Robert Kaussow
GitHub
@@ -9,6 +9,7 @@ repos:
|
||||
hooks:
|
||||
- id: end-of-file-fixer
|
||||
- id: trailing-whitespace
|
||||
exclude: ^docs/versioned_docs/.+/40-cli.md$
|
||||
- repo: https://github.com/golangci/golangci-lint
|
||||
rev: v2.5.0
|
||||
hooks:
|
||||
|
||||
@@ -2,5 +2,5 @@ pnpm-lock.yaml
|
||||
dist
|
||||
LICENSE
|
||||
openapi.json
|
||||
docs/40-cli.md
|
||||
40-cli.md
|
||||
build/
|
||||
|
||||
19001
docs/package-lock.json
generated
Normal file
19001
docs/package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load Diff
@@ -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.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/) |
|
||||
|
||||
|
Before Width: | Height: | Size: 31 KiB After Width: | Height: | Size: 31 KiB |
|
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 21 KiB |
@@ -103,9 +103,8 @@ When using the `local` backend, the `image` entry is used to specify the shell,
|
||||
- go build
|
||||
- go test
|
||||
|
||||
- name: publish
|
||||
+ image: woodpeckerci/plugin-kaniko
|
||||
repo: foo/bar
|
||||
- name: prettier
|
||||
+ image: woodpeckerci/plugin-prettier
|
||||
|
||||
services:
|
||||
- name: database
|
||||
@@ -285,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.)
|
||||
@@ -393,8 +393,7 @@ when:
|
||||
#### `path`
|
||||
|
||||
:::info
|
||||
Path conditions are applied only to **push** and **pull_request** events.
|
||||
It is currently **only available** for GitHub, GitLab and Gitea (version 1.18.0 and newer)
|
||||
Path conditions are applied only to **push** and **pull_request** events. This feature is currently available for all forges except Bitbucket Cloud.
|
||||
:::
|
||||
|
||||
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
|
||||
|
||||
- name: deploy
|
||||
image: woodpeckerci/plugin-kaniko
|
||||
image: woodpeckerci/plugin-s3
|
||||
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
|
||||
|
||||
- name: test # test will be executed immediately as no dependencies are set
|
||||
259
docs/versioned_docs/version-3.10/20-usage/50-environment.md
Normal file
259
docs/versioned_docs/version-3.10/20-usage/50-environment.md
Normal 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` |
|
||||
| |   | |
|
||||
| `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).
|
||||
@@ -23,7 +23,7 @@ steps:
|
||||
template: config/k8s/service.yaml
|
||||
```
|
||||
|
||||
Example pipeline using the Docker and Prettier plugins:
|
||||
Example pipeline using the Prettier and S3 plugins:
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
@@ -37,10 +37,11 @@ steps:
|
||||
image: woodpeckerci/plugin-prettier
|
||||
|
||||
- name: publish
|
||||
image: woodpeckerci/plugin-kaniko
|
||||
image: woodpeckerci/plugin-s3
|
||||
settings:
|
||||
repo: foo/bar
|
||||
tags: latest
|
||||
bucket: my-bucket-name
|
||||
source: some-file-name
|
||||
target: /target/some-file
|
||||
```
|
||||
|
||||
## Plugin Isolation
|
||||
|
Before Width: | Height: | Size: 40 KiB After Width: | Height: | Size: 40 KiB |
|
Before Width: | Height: | Size: 113 KiB After Width: | Height: | Size: 113 KiB |
|
Before Width: | Height: | Size: 430 KiB After Width: | Height: | Size: 430 KiB |
|
Before Width: | Height: | Size: 353 KiB After Width: | Height: | Size: 353 KiB |
|
Before Width: | Height: | Size: 351 KiB After Width: | Height: | Size: 351 KiB |
|
Before Width: | Height: | Size: 29 KiB After Width: | Height: | Size: 29 KiB |
@@ -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"
|
||||
[Unit]
|
||||
Description=WoodpeckerCI agent
|
||||
Documentation=https://woodpecker-ci.org/docs/administration/agent-config
|
||||
Documentation=https://woodpecker-ci.org/docs/administration/configuration/agent
|
||||
Requires=network.target
|
||||
After=network.target
|
||||
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)
|
||||
- [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
|
||||
|
||||
@@ -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`
|
||||
@@ -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.
|
||||
:::
|
||||
@@ -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
|
||||
|
||||
- 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
|
||||
|
||||
- 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
|
||||
|
||||
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,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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
Before Width: | Height: | Size: 29 KiB After Width: | Height: | Size: 29 KiB |
|
Before Width: | Height: | Size: 20 KiB After Width: | Height: | Size: 20 KiB |
|
Before Width: | Height: | Size: 129 KiB After Width: | Height: | Size: 129 KiB |
|
Before Width: | Height: | Size: 25 KiB After Width: | Height: | Size: 25 KiB |
|
Before Width: | Height: | Size: 5.3 KiB After Width: | Height: | Size: 5.3 KiB |
|
Before Width: | Height: | Size: 4.4 KiB After Width: | Height: | Size: 4.4 KiB |
|
Before Width: | Height: | Size: 25 KiB After Width: | Height: | Size: 25 KiB |
@@ -56,6 +56,7 @@ woodpecker-cli [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...]
|
||||
|
||||
**--token, -t**="": server auth token
|
||||
|
||||
|
||||
# COMMANDS
|
||||
|
||||
## admin
|
||||
@@ -66,6 +67,18 @@ manage server settings
|
||||
|
||||
retrieve log level from server, or set it with [level]
|
||||
|
||||
### org
|
||||
|
||||
manage organizations
|
||||
|
||||
#### ls
|
||||
|
||||
list organizations
|
||||
|
||||
**--format**="": format output (deprecated) (default: [33m{{ .Name }} [0m
|
||||
Organization ID: {{ .ID }}
|
||||
)
|
||||
|
||||
### registry
|
||||
|
||||
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-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
|
||||
|
||||
@@ -257,6 +272,12 @@ execute a local pipeline
|
||||
|
||||
**--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-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
|
||||
|
||||
**--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-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-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".
|
||||
@@ -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
|
||||
|
||||
**--netrc-machine**="":
|
||||
**--netrc-machine**="":
|
||||
|
||||
**--netrc-password**="":
|
||||
**--netrc-password**="":
|
||||
|
||||
**--netrc-username**="":
|
||||
**--netrc-username**="":
|
||||
|
||||
**--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: [])
|
||||
|
||||
**--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-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".
|
||||
|
||||
**--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-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)
|
||||
|
||||
**--workspace-base**="": (default: /woodpecker)
|
||||
**--workspace-base**="": (default: /woodpecker)
|
||||
|
||||
**--workspace-path**="": (default: src)
|
||||
**--workspace-path**="": (default: src)
|
||||
|
||||
## 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-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
|
||||
|
||||
@@ -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.
|
||||
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
|
||||
|
||||
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.
|
||||
|
Before Width: | Height: | Size: 7.5 KiB After Width: | Height: | Size: 7.5 KiB |
|
Before Width: | Height: | Size: 17 KiB After Width: | Height: | Size: 17 KiB |
|
Before Width: | Height: | Size: 11 KiB After Width: | Height: | Size: 11 KiB |
|
Before Width: | Height: | Size: 61 KiB After Width: | Height: | Size: 61 KiB |
@@ -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` |
|
||||
| |   | |
|
||||
| `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}
|
||||
```
|
||||
@@ -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.
|
||||
@@ -1 +1 @@
|
||||
["3.9", "3.8", "3.7", "2.8"]
|
||||
["3.10", "3.9", "3.8", "2.8"]
|
||||
|
||||
Reference in New Issue
Block a user