diff --git a/docs/src/pages/versions.md b/docs/src/pages/versions.md index 19e3fc771..f73f3cc4d 100644 --- a/docs/src/pages/versions.md +++ b/docs/src/pages/versions.md @@ -33,6 +33,7 @@ Here you can find documentation for previous versions of Woodpecker. | | | | | ------- | ---------- | ------------------------------------------------------------------------------------- | +| 3.17.0 | 2026-07-31 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.17.0/docs/docs/) | | 3.16.0 | 2026-06-27 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.16.0/docs/docs/) | | 3.15.0 | 2026-05-28 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.15.0/docs/docs/) | | 3.14.0 | 2026-05-01 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.14.0/docs/docs/) | diff --git a/docs/versioned_docs/version-3.15/20-usage/50-environment.md b/docs/versioned_docs/version-3.15/20-usage/50-environment.md deleted file mode 100644 index 794348de2..000000000 --- a/docs/versioned_docs/version-3.15/20-usage/50-environment.md +++ /dev/null @@ -1,262 +0,0 @@ -# Environment variables - -Woodpecker provides the ability to pass environment variables to individual pipeline steps. Note that these can't overwrite any existing, built-in variables. Example pipeline step with custom environment variables: - -```diff - steps: - - name: build - image: golang -+ environment: -+ CGO: 0 -+ GOOS: linux -+ GOARCH: amd64 - commands: - - go build - - go test -``` - -Please note that the environment section is not able to expand environment variables. If you need to expand variables they should be exported in the commands section. - -```diff - steps: - - name: build - image: golang -- environment: -- - PATH=$PATH:/go - commands: -+ - export PATH=$PATH:/go - - go build - - go test -``` - -:::warning -`${variable}` expressions are subject to pre-processing. If you do not want the pre-processor to evaluate your expression it must be escaped: -::: - -```diff - steps: - - name: build - image: golang - commands: -- - export PATH=${PATH}:/go -+ - export PATH=$${PATH}:/go - - go build - - go test -``` - -## Built-in environment variables - -This is the reference list of all environment variables available to your pipeline containers. These are injected into your pipeline step and plugins containers, at runtime. - -| NAME | Description | Example | -| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | -| `CI` | CI environment name | `woodpecker` | -| | **Repository** | | -| `CI_REPO` | repository full name `/` | `john-doe/my-repo` | -| `CI_REPO_OWNER` | repository owner | `john-doe` | -| `CI_REPO_NAME` | repository name | `my-repo` | -| `CI_REPO_REMOTE_ID` | repository remote ID, is the UID it has in the forge | `82` | -| `CI_REPO_URL` | repository web URL | `https://git.example.com/john-doe/my-repo` | -| `CI_REPO_CLONE_URL` | repository clone URL | `https://git.example.com/john-doe/my-repo.git` | -| `CI_REPO_CLONE_SSH_URL` | repository SSH clone URL | `git@git.example.com:john-doe/my-repo.git` | -| `CI_REPO_DEFAULT_BRANCH` | repository default branch | `main` | -| `CI_REPO_PRIVATE` | repository is private | `true` | -| `CI_REPO_TRUSTED_NETWORK` | repository has trusted network access | `false` | -| `CI_REPO_TRUSTED_VOLUMES` | repository has trusted volumes access | `false` | -| `CI_REPO_TRUSTED_SECURITY` | repository has trusted security access | `false` | -| | **Current Commit** | | -| `CI_COMMIT_SHA` | commit SHA | `eba09b46064473a1d345da7abf28b477468e8dbd` | -| `CI_COMMIT_REF` | commit ref | `refs/heads/main` | -| `CI_COMMIT_REFSPEC` | commit ref spec | `issue-branch:main` | -| `CI_COMMIT_BRANCH` | commit branch (equals target branch for pull requests) | `main` | -| `CI_COMMIT_SOURCE_BRANCH` | commit source branch (set only for pull request 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_STATUS` | state of the workflow right before the step was started | `success`, `failure` | -| `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` | -| `CI_PIPELINE_RERUNS` | number of times the pipeline has been restarted; not set on the initial run, `1` after the first restart, incremented on each subsequent restart | `1` | -| | **Current workflow** | | -| `CI_WORKFLOW_NAME` | workflow name | `release` | -| | **Current step** | | -| `CI_STEP_NAME` | step name | `build package` | -| `CI_STEP_TYPE` | step type (`commands`, `plugin`, `service`, `clone` or `cache`) | `commands` | -| `CI_STEP_NUMBER` | step number | `0` | -| `CI_STEP_STARTED` | step started UNIX timestamp | `1722617519` | -| `CI_STEP_URL` | URL to step in UI | `https://ci.example.com/repos/7/pipeline/8` | -| | **Previous commit** | | -| `CI_PREV_COMMIT_SHA` | previous commit SHA | `15784117e4e103f36cba75a9e29da48046eb82c4` | -| `CI_PREV_COMMIT_REF` | previous commit ref | `refs/heads/main` | -| `CI_PREV_COMMIT_REFSPEC` | previous commit ref spec | `issue-branch:main` | -| `CI_PREV_COMMIT_BRANCH` | previous commit branch | `main` | -| `CI_PREV_COMMIT_SOURCE_BRANCH` | previous commit source branch (set only for pull request events) | `issue-branch` | -| `CI_PREV_COMMIT_TARGET_BRANCH` | previous commit target branch (set only for pull request events) | `main` | -| `CI_PREV_COMMIT_URL` | previous commit link in forge | `https://git.example.com/john-doe/my-repo/commit/15784117e4e103f36cba75a9e29da48046eb82c4` | -| `CI_PREV_COMMIT_MESSAGE` | previous commit message | `test` | -| `CI_PREV_COMMIT_AUTHOR` | previous commit author username | `john-doe` | -| `CI_PREV_COMMIT_AUTHOR_EMAIL` | previous commit author email address | `john-doe@example.com` | -| | **Previous pipeline** | | -| `CI_PREV_PIPELINE_NUMBER` | previous pipeline number | `7` | -| `CI_PREV_PIPELINE_PARENT` | previous pipeline number of parent pipeline | `0` | -| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (see [`event`](../20-usage/20-workflow-syntax.md#event)) | `push`, `pull_request`, `pull_request_closed`, `pull_request_metadata`, `tag`, `release`, `manual`, `cron` | -| `CI_PREV_PIPELINE_EVENT_REASON` | previous exact reason `pull_request_metadata` event was send. it is forge instance specific and can change | `label_updated`, `milestoned`, `demilestoned`, `assigned`, `edited`, ... | -| `CI_PREV_PIPELINE_URL` | previous pipeline link in CI | `https://ci.example.com/repos/7/pipeline/7` | -| `CI_PREV_PIPELINE_FORGE_URL` | previous pipeline link to event in forge | `https://git.example.com/john-doe/my-repo/commit/15784117e4e103f36cba75a9e29da48046eb82c4` | -| `CI_PREV_PIPELINE_DEPLOY_TARGET` | previous pipeline deploy target for `deployment` events | `production` | -| `CI_PREV_PIPELINE_DEPLOY_TASK` | previous pipeline deploy task for `deployment` events | `migration` | -| `CI_PREV_PIPELINE_STATUS` | previous pipeline status | `success`, `failure` | -| `CI_PREV_PIPELINE_CREATED` | previous pipeline created UNIX timestamp | `1722610173` | -| `CI_PREV_PIPELINE_STARTED` | previous pipeline started UNIX timestamp | `1722610173` | -| `CI_PREV_PIPELINE_FINISHED` | previous pipeline finished UNIX timestamp | `1722610383` | -| `CI_PREV_PIPELINE_AUTHOR` | previous pipeline author username | `octocat` | -| `CI_PREV_PIPELINE_AVATAR` | previous pipeline author avatar | `https://git.example.com/avatars/5dcbcadbce6f87f8abef` | -| |   | | -| `CI_WORKSPACE` | Path of the workspace where source code gets cloned to | `/woodpecker/src/git.example.com/john-doe/my-repo` | -| | **System** | | -| `CI_SYSTEM_NAME` | name of the CI system | `woodpecker` | -| `CI_SYSTEM_URL` | link to CI system | `https://ci.example.com` | -| `CI_SYSTEM_HOST` | hostname of CI server | `ci.example.com` | -| `CI_SYSTEM_VERSION` | version of the server | `2.7.0` | -| | **Forge** | | -| `CI_FORGE_TYPE` | name of forge | `bitbucket` , `bitbucket_dc` , `forgejo` , `gitea` , `github` , `gitlab` | -| `CI_FORGE_URL` | root URL of configured forge | `https://git.example.com` | -| | **Internal** - Please don't use! | | -| `CI_SCRIPT` | Internal script path. Used to call pipeline step commands. | | -| `CI_NETRC_USERNAME` | Credentials for private repos to be able to clone data. (Only available for specific images) | | -| `CI_NETRC_PASSWORD` | Credentials for private repos to be able to clone data. (Only available for specific images) | | -| `CI_NETRC_MACHINE` | Credentials for private repos to be able to clone data. (Only available for specific images) | | - -## Global environment variables - -If you want specific environment variables to be available in all of your pipelines use the `WOODPECKER_ENVIRONMENT` setting on the Woodpecker server. Note that these can't overwrite any existing, built-in variables. - -```ini -WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2 -``` - -These can be used, for example, to manage the image tag used by multiple projects. - -```ini -WOODPECKER_ENVIRONMENT=GOLANG_VERSION:1.18 -``` - -```diff - steps: - - name: build -- image: golang:1.18 -+ image: golang:${GOLANG_VERSION} - commands: - - [...] -``` - -## String Substitution - -Woodpecker provides the ability to substitute environment variables at runtime. This gives us the ability to use dynamic settings, commands and filters in our pipeline configuration. - -Example commit substitution: - -```diff - steps: - - name: s3 - image: woodpeckerci/plugin-s3 - settings: -+ target: /target/${CI_COMMIT_SHA} -``` - -Example tag substitution: - -```diff - steps: - - name: s3 - image: woodpeckerci/plugin-s3 - settings: -+ target: /target/${CI_COMMIT_TAG} -``` - -## String Operations - -Woodpecker also emulates bash string operations. This gives us the ability to manipulate the strings prior to substitution. Example use cases might include substring and stripping prefix or suffix values. - -| OPERATION | DESCRIPTION | -| ------------------ | ------------------------------------------------ | -| `${param}` | parameter substitution | -| `${param,}` | parameter substitution with lowercase first char | -| `${param,,}` | parameter substitution with lowercase | -| `${param^}` | parameter substitution with uppercase first char | -| `${param^^}` | parameter substitution with uppercase | -| `${param:pos}` | parameter substitution with substring | -| `${param:pos:len}` | parameter substitution with substring and length | -| `${param=default}` | parameter substitution with default | -| `${param##prefix}` | parameter substitution with prefix removal | -| `${param%%suffix}` | parameter substitution with suffix removal | -| `${param/old/new}` | parameter substitution with find and replace | - -Example variable substitution with substring: - -```diff - steps: - - name: s3 - image: woodpeckerci/plugin-s3 - settings: -+ target: /target/${CI_COMMIT_SHA:0:8} -``` - -Example variable substitution strips `v` prefix from `v.1.0.0`: - -```diff - steps: - - name: s3 - image: woodpeckerci/plugin-s3 - settings: -+ target: /target/${CI_COMMIT_TAG##v} -``` - -## `pull_request_metadata` specific event reason values - -For the `pull_request_metadata` event, the exact reason a metadata change was detected is passe through in `CI_PIPELINE_EVENT_REASON`. - -**GitLab** merges metadata updates into one webhook. Event reasons are separated by `,` as a list. - -:::note -Event reason values are forge-specific and may change between versions. -::: - -| Event | GitHub | Gitea | Forgejo | GitLab | Bitbucket | Bitbucket Datacenter | Description | -| -------------------- | ------------------ | ------------------ | ------------------ | ------------------ | --------- | -------------------- | ------------------------------------------------------------------------------ | -| `assigned` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | Pull request was assigned to a user | -| `converted_to_draft` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Pull request was converted to a draft | -| `demilestoned` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | Pull request was removed from a milestone | -| `description_edited` | :x: | :x: | :x: | :white_check_mark: | :x: | :x: | Description edited | -| `edited` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | :x: | The title or body of a pull request was edited, or the base branch was changed | -| `label_added` | :x: | :x: | :x: | :white_check_mark: | :x: | :x: | Pull had no labels and now got label(s) added | -| `label_cleared` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | All labels removed | -| `label_updated` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | New label(s) added / label(s) changed | -| `locked` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Conversation on a pull request was locked | -| `milestoned` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | Pull request was added to a milestone | -| `ready_for_review` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Draft pull request was marked as ready for review | -| `review_requested` | :x: | :x: | :x: | :white_check_mark: | :x: | :x: | New review was requested | -| `title_edited` | :x: | :x: | :x: | :white_check_mark: | :x: | :x: | Title edited | -| `unassigned` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | User was unassigned from a pull request | -| `unlabeled` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Label was removed from a pull request | -| `unlocked` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Conversation on a pull request was unlocked | - -**Bitbucket** and **Bitbucket Datacenter** [are not supported at the moment](https://github.com/woodpecker-ci/woodpecker/pull/5214). diff --git a/docs/versioned_docs/version-3.15/92-development/woodpecker-architecture.svg b/docs/versioned_docs/version-3.15/92-development/woodpecker-architecture.svg deleted file mode 100644 index 5bb308a59..000000000 --- a/docs/versioned_docs/version-3.15/92-development/woodpecker-architecture.svg +++ /dev/null @@ -1,352 +0,0 @@ - - - - - - -WoodpeckerArchitecture - - -cluster_ui - -UI - - -cluster_sdk - -SDK (woodpecker-go) - - -cluster_cli - -woodpecker-cli - - -cluster_agent - -woodpecker-agent - - -cluster_pipelines - -Pipelines - - -cluster_server - -woodpecker-server - - -cluster_shared - -Shared Libs - - -cluster_external - -External Systems - - - -ui_web - -web/ - - - -srv_router - -server/router/ - - - -ui_web->srv_router - - -HTTP - - - -srv_api - -server/api/ - - - -ui_web->srv_api - - -REST API - - - -sdk - -woodpecker-go - - - -sdk->srv_api - - -REST API - - - -cli_cmd - -cmd/cli/ - - - -cli_core - -cli/ - - - -cli_cmd->cli_core - - - - - -cli_core->sdk - - - - - -agent_cmd - -cmd/agent/ - - - -agent_core - -agent/ - - - -agent_cmd->agent_core - - - - - -pipe_backend - -pipeline/backend/ -(exec engines) - - - -agent_core->pipe_backend - - -execute steps - - - -srv_grpc - -server/rpc/ - - - -agent_core->srv_grpc - - -gRPC connect - - - -srv_queue - -server/queue/ - - - -agent_core->srv_queue - - -poll work - - - -pipe_core - -pipeline/ - - - -pipe_core->pipe_backend - - - - - -shared_util - -shared/util/ - - - -pipe_core->shared_util - - - - - -pipe_frontend - -pipeline/frontend/ -(yaml) - - - -pipe_frontend->pipe_core - - - - - -srv_cmd - -cmd/server/ - - - -srv_cmd->srv_router - - - - - -srv_router->srv_api - - - - - -shared_token - -shared/token/ - - - -srv_router->shared_token - - - - - -srv_api->srv_queue - - - - - -srv_pubsub - -server/pubsub/ - - - -srv_api->srv_pubsub - - - - - -srv_store - -server/store/ - - - -srv_api->srv_store - - - - - -shared_http - -shared/httputil/ - - - -srv_api->shared_http - - - - - -srv_grpc->srv_queue - - - - - -shared_log - -shared/logger/ - - - -srv_grpc->shared_log - - - - - -srv_model - -server/model/ - - - -srv_store->srv_model - - - - - -ext_db - - -Database - - - -srv_store->ext_db - - -SQL - - - -srv_forge - -server/forge/ - - - -ext_scm - -SCM Providers - - - -srv_forge->ext_scm - - -SCM API - - - diff --git a/docs/versioned_docs/version-3.15/10-intro/index.md b/docs/versioned_docs/version-3.18/10-intro/index.md similarity index 89% rename from docs/versioned_docs/version-3.15/10-intro/index.md rename to docs/versioned_docs/version-3.18/10-intro/index.md index 025bd1f85..a8e00c742 100644 --- a/docs/versioned_docs/version-3.15/10-intro/index.md +++ b/docs/versioned_docs/version-3.18/10-intro/index.md @@ -24,3 +24,5 @@ Then you might want to jump directly into it and [start creating your first pipe ## Want to start from scratch and deploy your own Woodpecker instance? Woodpecker is lightweight and even runs on a Raspberry Pi. You can follow the [deployment guide](../30-administration/00-general.md) to set up your own Woodpecker instance. + +If you want to try a pipeline before installing a server, you can also run workflow files locally with [`woodpecker-cli exec`](../20-usage/73-local-execution.md). diff --git a/docs/versioned_docs/version-3.15/20-usage/10-intro.md b/docs/versioned_docs/version-3.18/20-usage/10-intro.md similarity index 82% rename from docs/versioned_docs/version-3.15/20-usage/10-intro.md rename to docs/versioned_docs/version-3.18/20-usage/10-intro.md index 095528b4e..4a2f2d250 100644 --- a/docs/versioned_docs/version-3.15/20-usage/10-intro.md +++ b/docs/versioned_docs/version-3.18/20-usage/10-intro.md @@ -25,12 +25,12 @@ steps: image: debian commands: - echo "This is the build step" - - echo "binary-data-123" > executable + - echo "some-data" > some-file.txt - name: a-test-step - image: golang:1.16 + image: alpine commands: - echo "Testing ..." - - ./executable + - cat some-file.txt ``` **So what did we do here?** @@ -51,9 +51,9 @@ steps: The steps are executed in the order they are defined, so `build` will be executed first and then `a-test-step`. -In the `build` step we use the `debian` image and build a "binary file" called `executable`. +In the `build` step we use the `debian` image and create a file called `some-file.txt`. -In the `a-test-step` we use the `golang:1.16` image and run the `executable` file to test it. +In the `a-test-step` we use the `alpine` image and output the `some-file.txt` file contents. You can use any image from registries like the [Docker Hub](https://hub.docker.com/search?type=image) you have access to: @@ -66,7 +66,17 @@ You can use any image from registries like the [Docker Hub](https://hub.docker.c - aws help ``` -## 3. Push the file and trigger first pipeline +## 3. Run the workflow locally + +If you have `woodpecker-cli` and a supported backend installed, you can run the workflow before pushing it: + +```shell +woodpecker-cli exec .woodpecker/my-first-workflow.yaml +``` + +This is useful for checking workflow syntax, command output, and metadata conditions while you are still editing the file. For more examples, including secrets and downloaded metadata, see [local pipeline execution](./73-local-execution.md). + +## 4. Push the file and trigger first pipeline If you push this file to your repository now, Woodpecker will already execute your first pipeline. @@ -79,7 +89,7 @@ As you probably noticed, there is another step in called `clone` which is execut This for example allows the first step to build your application using your source code and as the second step will receive the same workspace it can use the previously built binary and test it. -## 4. Use a plugin for reusable tasks +## 5. Use a plugin for reusable tasks Sometimes you have some tasks that you need to do in every project. For example, deploying to Kubernetes or sending a Slack message. Therefore you can use one of the [official and community plugins](/plugins) or simply [create your own](./51-plugins/20-creating-plugins.md). diff --git a/docs/versioned_docs/version-3.15/20-usage/100-troubleshooting.md b/docs/versioned_docs/version-3.18/20-usage/100-troubleshooting.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/100-troubleshooting.md rename to docs/versioned_docs/version-3.18/20-usage/100-troubleshooting.md diff --git a/docs/versioned_docs/version-3.15/20-usage/15-terminology/architecture.excalidraw b/docs/versioned_docs/version-3.18/20-usage/15-terminology/architecture.excalidraw similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/15-terminology/architecture.excalidraw rename to docs/versioned_docs/version-3.18/20-usage/15-terminology/architecture.excalidraw diff --git a/docs/versioned_docs/version-3.15/20-usage/15-terminology/architecture.svg b/docs/versioned_docs/version-3.18/20-usage/15-terminology/architecture.svg similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/15-terminology/architecture.svg rename to docs/versioned_docs/version-3.18/20-usage/15-terminology/architecture.svg diff --git a/docs/versioned_docs/version-3.15/20-usage/15-terminology/index.md b/docs/versioned_docs/version-3.18/20-usage/15-terminology/index.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/15-terminology/index.md rename to docs/versioned_docs/version-3.18/20-usage/15-terminology/index.md diff --git a/docs/versioned_docs/version-3.15/20-usage/15-terminology/pipeline-workflow-step.excalidraw b/docs/versioned_docs/version-3.18/20-usage/15-terminology/pipeline-workflow-step.excalidraw similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/15-terminology/pipeline-workflow-step.excalidraw rename to docs/versioned_docs/version-3.18/20-usage/15-terminology/pipeline-workflow-step.excalidraw diff --git a/docs/versioned_docs/version-3.15/20-usage/15-terminology/pipeline-workflow-step.svg b/docs/versioned_docs/version-3.18/20-usage/15-terminology/pipeline-workflow-step.svg similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/15-terminology/pipeline-workflow-step.svg rename to docs/versioned_docs/version-3.18/20-usage/15-terminology/pipeline-workflow-step.svg diff --git a/docs/versioned_docs/version-3.15/20-usage/20-workflow-syntax.md b/docs/versioned_docs/version-3.18/20-usage/20-workflow-syntax.md similarity index 98% rename from docs/versioned_docs/version-3.15/20-usage/20-workflow-syntax.md rename to docs/versioned_docs/version-3.18/20-usage/20-workflow-syntax.md index 282fe22f7..e98615bcd 100644 --- a/docs/versioned_docs/version-3.15/20-usage/20-workflow-syntax.md +++ b/docs/versioned_docs/version-3.18/20-usage/20-workflow-syntax.md @@ -426,7 +426,9 @@ when: You can use [glob patterns](https://github.com/bmatcuk/doublestar#patterns) to match the changed files and specify if the step should run if a file matching that pattern has been changed `include` or if some files have **not** been changed `exclude`. -For pipelines without file changes (empty commits or on events without file changes like `tag`), you can use `on_empty` to set whether this condition should be **true** _(default)_ or **false** in these cases. +`pull_request` events always contain all changed files of the pull request **not** just the files from the last pushed commit. + +For pipelines without file changes (empty commits), you can use `on_empty` to set whether this condition should be **true** _(default)_ or **false** in these cases. ```yaml when: @@ -520,6 +522,10 @@ steps: ::: +:::warning +As soon as one step uses `depends_on`, steps are looked up by name, so all step names of the workflow must be unique. Duplicate names are rejected. +::: + ### `volumes` Woodpecker gives the ability to define Docker volumes in the YAML. You can use this parameter to mount files or folders on the host machine into your containers. diff --git a/docs/versioned_docs/version-3.15/20-usage/25-workflows.md b/docs/versioned_docs/version-3.18/20-usage/25-workflows.md similarity index 71% rename from docs/versioned_docs/version-3.15/20-usage/25-workflows.md rename to docs/versioned_docs/version-3.18/20-usage/25-workflows.md index e74088142..919705b5f 100644 --- a/docs/versioned_docs/version-3.15/20-usage/25-workflows.md +++ b/docs/versioned_docs/version-3.18/20-usage/25-workflows.md @@ -144,3 +144,45 @@ The same syntax works at the step level within a workflow: if a step uses `depen Some workflows don't need the source code, like creating a notification on failure. Read more about `skip_clone` at [pipeline syntax](./20-workflow-syntax.md#skip_clone) ::: + +## Concurrency + +By default workflows run with no concurrency limit. Some workflows, however, must not run more than a given number of times at once. A typical example is a deployment workflow: running two deployments at the same time can cause race conditions or corrupt state. Cancelling the previous pipeline is often not an option either, since it could interrupt an ongoing deployment. + +The `concurrency` setting limits how many instances of a workflow may run at the same time. When the limit is reached, additional instances stay queued and start only once a running one has finished. Nothing is cancelled. + +```yaml title=".woodpecker/deploy.yaml" +steps: + - name: deploy + image: debian:stable-slim + commands: + - echo deploying + +depends_on: + - test + +concurrency: + limit: 1 +``` + +You can also use the shorthand form to only set the limit: + +```yaml +concurrency: 1 +``` + +### Ordering + +Queued workflows of the same group start in the order their pipelines were created, **not** in the order they become ready to run. This matters when a workflow depends on other workflows (via `depends_on`) whose duration varies: even if a later pipeline's checks finish first, its limited workflow will not overtake an earlier pipeline that is still waiting. This guarantees that, for example, deployments happen in commit order. + +### Groups + +By default, the limit applies per workflow within a repository. Different runs of the same workflow are limited against each other, while different workflows (and other repositories) are unaffected. + +Setting a `group` is optional. You can set a custom `group` to share a limit across workflows or to make the limit more specific. The group supports [environment variable substitution](./50-environment.md), so you can, for example, limit concurrency per branch or per deployment target: + +```yaml +concurrency: + limit: 1 + group: deploy-${CI_COMMIT_BRANCH} +``` diff --git a/docs/versioned_docs/version-3.15/20-usage/30-matrix-workflows.md b/docs/versioned_docs/version-3.18/20-usage/30-matrix-workflows.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/30-matrix-workflows.md rename to docs/versioned_docs/version-3.18/20-usage/30-matrix-workflows.md diff --git a/docs/versioned_docs/version-3.15/20-usage/40-secrets.md b/docs/versioned_docs/version-3.18/20-usage/40-secrets.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/40-secrets.md rename to docs/versioned_docs/version-3.18/20-usage/40-secrets.md diff --git a/docs/versioned_docs/version-3.15/20-usage/41-registries.md b/docs/versioned_docs/version-3.18/20-usage/41-registries.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/41-registries.md rename to docs/versioned_docs/version-3.18/20-usage/41-registries.md diff --git a/docs/versioned_docs/version-3.15/20-usage/45-cron.md b/docs/versioned_docs/version-3.18/20-usage/45-cron.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/45-cron.md rename to docs/versioned_docs/version-3.18/20-usage/45-cron.md diff --git a/docs/versioned_docs/version-3.18/20-usage/50-environment.md b/docs/versioned_docs/version-3.18/20-usage/50-environment.md new file mode 100644 index 000000000..b6c807866 --- /dev/null +++ b/docs/versioned_docs/version-3.18/20-usage/50-environment.md @@ -0,0 +1,289 @@ +# 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. + +The **Scope** column documents when each variable can be used: + +- `config`: the variable is available at config-evaluation time, when the pipeline configuration is parsed. It can be referenced in [`when`](./20-workflow-syntax.md#when---conditional-execution) filters and expanded via [string substitution](#string-substitution) (e.g. `${CI_COMMIT_SHA}`). +- `runtime`: the variable is available as an environment variable inside the running step. + +Most variables are available in both scopes. Variables scoped only to `runtime` (e.g. the step-specific variables and `CI_PIPELINE_STATUS`) are not populated while the configuration is evaluated, so they cannot be used in `when` filters or substitutions. + +| NAME | Scope | Description | Example | +| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | +| `CI` | `config, runtime` | CI environment name | `woodpecker` | +| | | **Repository** | | +| `CI_REPO` | `config, runtime` | repository full name `/` | `john-doe/my-repo` | +| `CI_REPO_OWNER` | `config, runtime` | repository owner | `john-doe` | +| `CI_REPO_NAME` | `config, runtime` | repository name | `my-repo` | +| `CI_REPO_REMOTE_ID` | `config, runtime` | repository remote ID, is the UID it has in the forge | `82` | +| `CI_REPO_URL` | `config, runtime` | repository web URL | `https://git.example.com/john-doe/my-repo` | +| `CI_REPO_CLONE_URL` | `config, runtime` | repository clone URL | `https://git.example.com/john-doe/my-repo.git` | +| `CI_REPO_CLONE_SSH_URL` | `config, runtime` | repository SSH clone URL | `git@git.example.com:john-doe/my-repo.git` | +| `CI_REPO_DEFAULT_BRANCH` | `config, runtime` | repository default branch | `main` | +| `CI_REPO_PRIVATE` | `config, runtime` | repository is private | `true` | +| `CI_REPO_TRUSTED_NETWORK` | `config, runtime` | repository has trusted network access | `false` | +| `CI_REPO_TRUSTED_VOLUMES` | `config, runtime` | repository has trusted volumes access | `false` | +| `CI_REPO_TRUSTED_SECURITY` | `config, runtime` | repository has trusted security access | `false` | +| | | **Current Commit** | | +| `CI_COMMIT_SHA` | `config, runtime` | commit SHA | `deadbee...` | +| `CI_COMMIT_REF` | `config, runtime` | commit ref | `refs/heads/main` | +| `CI_COMMIT_REFSPEC` | `config, runtime` | commit ref spec | `issue-branch:main` | +| `CI_COMMIT_BRANCH` | `config, runtime` | commit branch (equals target branch for pull requests) | `main` | +| `CI_COMMIT_SOURCE_BRANCH` | `config, runtime` | commit source branch (set only for pull request events) | `issue-branch` | +| `CI_COMMIT_TARGET_BRANCH` | `config, runtime` | commit target branch (set only for pull request events) | `main` | +| `CI_COMMIT_TAG` | `config, runtime` | commit tag name (empty if event is not `tag`) | `v1.10.3` | +| `CI_COMMIT_PULL_REQUEST` | `config, runtime` | commit pull request number (set only for pull request events) | `1` | +| `CI_COMMIT_PULL_REQUEST_LABELS` | `config, runtime` | labels assigned to pull request (set only for pull request events) | `server` | +| `CI_COMMIT_PULL_REQUEST_MILESTONE` | `config, runtime` | milestone assigned to pull request (set only for `pull_request` and `pull_request_closed` events) | `summer-sprint` | +| `CI_COMMIT_PULL_REQUEST_DRAFT` | `config, runtime` | whether the pull request is a draft (set only for pull request events; see [forge support](#ci_commit_pull_request_draft-forge-support)) | `true`, `false` | +| `CI_COMMIT_MESSAGE` | `config, runtime` | commit message | `Initial commit` | +| `CI_COMMIT_TIMESTAMP` | `config, runtime` | commit UNIX timestamp | `1722617519` | +| `CI_COMMIT_AUTHOR` | `config, runtime` | commit author username | `john-doe` | +| `CI_COMMIT_AUTHOR_EMAIL` | `config, runtime` | commit author email address | `john-doe@example.com` | +| `CI_COMMIT_PRERELEASE` | `config, runtime` | release is a pre-release (empty if event is not `release`) โ€” **deprecated**, use `CI_PIPELINE_RELEASE_PRE` | `false` | +| | | **Current pipeline** | | +| `CI_PIPELINE_NUMBER` | `config, runtime` | pipeline number | `8` | +| `CI_PIPELINE_PARENT` | `config, runtime` | number of parent pipeline | `0` | +| `CI_PIPELINE_STATUS` | `runtime` | state of the workflow right before the step was started | `success`, `failure` | +| `CI_PIPELINE_EVENT` | `config, runtime` | 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` | `config, runtime` | 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` | `config, runtime` | link to the web UI for the pipeline | `https://ci.example.com/repos/7/pipeline/8` | +| `CI_PIPELINE_FORGE_URL` | `config, runtime` | 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/deadbee...` | +| `CI_PIPELINE_DEPLOY_TARGET` | `config, runtime` | pipeline deploy target for `deployment` events | `production` | +| `CI_PIPELINE_DEPLOY_TASK` | `config, runtime` | pipeline deploy task for `deployment` events | `migration` | +| `CI_PIPELINE_RELEASE_TITLE` | `config, runtime` | release title (empty if event is not `release`) | `v1.10.3` | +| `CI_PIPELINE_RELEASE_PRE` | `config, runtime` | release is a pre-release (empty if event is not `release`) | `false` | +| `CI_PIPELINE_CREATED` | `config, runtime` | pipeline created UNIX timestamp | `1722617519` | +| `CI_PIPELINE_STARTED` | `config, runtime` | pipeline started UNIX timestamp | `1722617519` | +| `CI_PIPELINE_FILES` | `config, runtime` | 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` | `config, runtime` | pipeline author username | `octocat` | +| `CI_PIPELINE_AVATAR` | `config, runtime` | pipeline author avatar | `https://git.example.com/avatars/5dcbcadbce6f87f8abef` | +| `CI_PIPELINE_RERUNS` | `config, runtime` | number of times the pipeline has been restarted; not set on the initial run, `1` after the first restart, incremented on each subsequent restart | `1` | +| | | **Current workflow** | | +| `CI_WORKFLOW_NAME` | `config, runtime` | workflow name | `release` | +| | | **Current step** | | +| `CI_STEP_NAME` | `runtime` | step name | `build package` | +| `CI_STEP_TYPE` | `runtime` | step type (`commands`, `plugin`, `service`, `clone` or `cache`) | `commands` | +| `CI_STEP_NUMBER` | `runtime` | step number | `0` | +| `CI_STEP_STARTED` | `runtime` | step started UNIX timestamp | `1722617519` | +| `CI_STEP_URL` | `runtime` | URL to step in UI | `https://ci.example.com/repos/7/pipeline/8` | +| | | **Previous commit** | | +| `CI_PREV_COMMIT_SHA` | `config, runtime` | previous commit SHA | `deadbee...` | +| `CI_PREV_COMMIT_REF` | `config, runtime` | previous commit ref | `refs/heads/main` | +| `CI_PREV_COMMIT_REFSPEC` | `config, runtime` | previous commit ref spec | `issue-branch:main` | +| `CI_PREV_COMMIT_BRANCH` | `config, runtime` | previous commit branch | `main` | +| `CI_PREV_COMMIT_SOURCE_BRANCH` | `config, runtime` | previous commit source branch (set only for pull request events) | `issue-branch` | +| `CI_PREV_COMMIT_TARGET_BRANCH` | `config, runtime` | previous commit target branch (set only for pull request events) | `main` | +| `CI_PREV_COMMIT_URL` | `config, runtime` | previous commit link in forge | `https://git.example.com/john-doe/my-repo/commit/deadbee...` | +| `CI_PREV_COMMIT_MESSAGE` | `config, runtime` | previous commit message | `test` | +| `CI_PREV_COMMIT_TIMESTAMP` | `config, runtime` | previous commit UNIX timestamp | `1722617519` | +| `CI_PREV_COMMIT_AUTHOR` | `config, runtime` | previous commit author username | `john-doe` | +| `CI_PREV_COMMIT_AUTHOR_EMAIL` | `config, runtime` | previous commit author email address | `john-doe@example.com` | +| | | **Previous pipeline** | | +| `CI_PREV_PIPELINE_NUMBER` | `config, runtime` | previous pipeline number | `7` | +| `CI_PREV_PIPELINE_PARENT` | `config, runtime` | previous pipeline number of parent pipeline | `0` | +| `CI_PREV_PIPELINE_EVENT` | `config, runtime` | 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` | `config, runtime` | 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` | `config, runtime` | previous pipeline link in CI | `https://ci.example.com/repos/7/pipeline/7` | +| `CI_PREV_PIPELINE_FORGE_URL` | `config, runtime` | previous pipeline link to event in forge | `https://git.example.com/john-doe/my-repo/commit/deadbee...` | +| `CI_PREV_PIPELINE_DEPLOY_TARGET` | `config, runtime` | previous pipeline deploy target for `deployment` events | `production` | +| `CI_PREV_PIPELINE_DEPLOY_TASK` | `config, runtime` | previous pipeline deploy task for `deployment` events | `migration` | +| `CI_PREV_PIPELINE_STATUS` | `config, runtime` | previous pipeline status | `success`, `failure` | +| `CI_PREV_PIPELINE_CREATED` | `config, runtime` | previous pipeline created UNIX timestamp | `1722610173` | +| `CI_PREV_PIPELINE_STARTED` | `config, runtime` | previous pipeline started UNIX timestamp | `1722610173` | +| `CI_PREV_PIPELINE_FINISHED` | `config, runtime` | previous pipeline finished UNIX timestamp | `1722610383` | +| `CI_PREV_PIPELINE_AUTHOR` | `config, runtime` | previous pipeline author username | `octocat` | +| `CI_PREV_PIPELINE_AVATAR` | `config, runtime` | previous pipeline author avatar | `https://git.example.com/avatars/5dcbcadbce6f87f8abef` | +| | |   | | +| `CI_WORKSPACE` | `runtime` | Path of the workspace where source code gets cloned to | `/woodpecker/src/git.example.com/john-doe/my-repo` | +| | | **System** | | +| `CI_SYSTEM_NAME` | `config, runtime` | name of the CI system | `woodpecker` | +| `CI_SYSTEM_URL` | `config, runtime` | link to CI system | `https://ci.example.com` | +| `CI_SYSTEM_HOST` | `config, runtime` | hostname of CI server | `ci.example.com` | +| `CI_SYSTEM_VERSION` | `config, runtime` | version of the server | `2.7.0` | +| | | **Forge** | | +| `CI_FORGE_TYPE` | `config, runtime` | name of forge | `bitbucket`
`bitbucket_dc`
`forgejo`
`gitea`
`github`
`gitlab` | +| `CI_FORGE_URL` | `config, runtime` | root URL of configured forge | `https://git.example.com` | +| | | **Internal** - Please don't use! | | +| `CI_SCRIPT` | `runtime` | Internal script path. Used to call pipeline step commands. | | +| `CI_NETRC_USERNAME` | `runtime` | Credentials for private repos to be able to clone data. (Only available for specific images) | | +| `CI_NETRC_PASSWORD` | `runtime` | Credentials for private repos to be able to clone data. (Only available for specific images) | | +| `CI_NETRC_MACHINE` | `runtime` | 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} +``` + +## `CI_COMMIT_PULL_REQUEST_DRAFT` forge support + +For pull request events, `CI_COMMIT_PULL_REQUEST_DRAFT` is set to `true` or `false` depending on whether the pull request is a draft. + +| Forge | Supported | Notes | +| -------------------- | ------------------ | ----------------------------------------------------------------- | +| GitHub | :white_check_mark: | | +| Gitea | :white_check_mark: | | +| GitLab | :white_check_mark: | Uses `draft`; falls back to legacy `work_in_progress` when needed | +| Forgejo | :x: | Webhook payloads include draft status, but it is not exposed yet | +| Bitbucket | :x: | Webhook payloads include draft status, but it is not exposed yet | +| Bitbucket Datacenter | :x: | Webhook payloads include draft status, but it is not exposed yet | + +On unsupported forges the variable is still set to `false`. + +## `pull_request_metadata` specific event reason values + +For the `pull_request_metadata` event, the exact reason a metadata change was detected is passe through in `CI_PIPELINE_EVENT_REASON`. + +**GitLab** merges metadata updates into one webhook. Event reasons are separated by `,` as a list. + +:::note +Event reason values are forge-specific and may change between versions. +::: + +| Event | GitHub | Gitea | Forgejo | GitLab | Bitbucket | Bitbucket Datacenter | Description | +| -------------------- | ------------------ | ------------------ | ------------------ | ------------------ | --------- | -------------------- | ------------------------------------------------------------------------------ | +| `assigned` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | Pull request was assigned to a user | +| `converted_to_draft` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Pull request was converted to a draft | +| `demilestoned` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | Pull request was removed from a milestone | +| `description_edited` | :x: | :x: | :x: | :white_check_mark: | :x: | :x: | Description edited | +| `edited` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | :x: | The title or body of a pull request was edited, or the base branch was changed | +| `label_added` | :x: | :x: | :x: | :white_check_mark: | :x: | :x: | Pull had no labels and now got label(s) added | +| `label_cleared` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | All labels removed | +| `label_updated` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | New label(s) added / label(s) changed | +| `locked` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Conversation on a pull request was locked | +| `milestoned` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | Pull request was added to a milestone | +| `ready_for_review` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Draft pull request was marked as ready for review | +| `review_requested` | :x: | :x: | :x: | :white_check_mark: | :x: | :x: | New review was requested | +| `title_edited` | :x: | :x: | :x: | :white_check_mark: | :x: | :x: | Title edited | +| `unassigned` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | User was unassigned from a pull request | +| `unlabeled` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Label was removed from a pull request | +| `unlocked` | :white_check_mark: | :x: | :x: | :x: | :x: | :x: | Conversation on a pull request was unlocked | + +**Bitbucket** and **Bitbucket Datacenter** [are not supported at the moment](https://github.com/woodpecker-ci/woodpecker/pull/5214). diff --git a/docs/versioned_docs/version-3.15/20-usage/51-plugins/20-creating-plugins.md b/docs/versioned_docs/version-3.18/20-usage/51-plugins/20-creating-plugins.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/51-plugins/20-creating-plugins.md rename to docs/versioned_docs/version-3.18/20-usage/51-plugins/20-creating-plugins.md diff --git a/docs/versioned_docs/version-3.15/20-usage/51-plugins/51-overview.md b/docs/versioned_docs/version-3.18/20-usage/51-plugins/51-overview.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/51-plugins/51-overview.md rename to docs/versioned_docs/version-3.18/20-usage/51-plugins/51-overview.md diff --git a/docs/versioned_docs/version-3.15/20-usage/51-plugins/_category_.yaml b/docs/versioned_docs/version-3.18/20-usage/51-plugins/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/51-plugins/_category_.yaml rename to docs/versioned_docs/version-3.18/20-usage/51-plugins/_category_.yaml diff --git a/docs/versioned_docs/version-3.15/20-usage/60-services.md b/docs/versioned_docs/version-3.18/20-usage/60-services.md similarity index 91% rename from docs/versioned_docs/version-3.15/20-usage/60-services.md rename to docs/versioned_docs/version-3.18/20-usage/60-services.md index fa243f70f..5a7cb41f0 100644 --- a/docs/versioned_docs/version-3.15/20-usage/60-services.md +++ b/docs/versioned_docs/version-3.18/20-usage/60-services.md @@ -5,6 +5,8 @@ The below configuration composes database and cache containers. Services are accessed using custom hostnames. In the example below, the MySQL service is assigned the hostname `database` and is available at `database:3306`. +Because the name becomes the hostname, every service in the list syntax must set `name` explicitly. In the map syntax the map key is used as the name. +Service names must be unique within a workflow, otherwise the hostname would resolve to an arbitrary one of them. ```yaml steps: diff --git a/docs/versioned_docs/version-3.15/20-usage/70-volumes.md b/docs/versioned_docs/version-3.18/20-usage/70-volumes.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/70-volumes.md rename to docs/versioned_docs/version-3.18/20-usage/70-volumes.md diff --git a/docs/versioned_docs/version-3.15/20-usage/72-extensions/40-configuration-extension.md b/docs/versioned_docs/version-3.18/20-usage/72-extensions/40-configuration-extension.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/72-extensions/40-configuration-extension.md rename to docs/versioned_docs/version-3.18/20-usage/72-extensions/40-configuration-extension.md diff --git a/docs/versioned_docs/version-3.15/20-usage/72-extensions/50-registry-extension.md b/docs/versioned_docs/version-3.18/20-usage/72-extensions/50-registry-extension.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/72-extensions/50-registry-extension.md rename to docs/versioned_docs/version-3.18/20-usage/72-extensions/50-registry-extension.md diff --git a/docs/versioned_docs/version-3.15/20-usage/72-extensions/55-secret-extension.md b/docs/versioned_docs/version-3.18/20-usage/72-extensions/55-secret-extension.md similarity index 98% rename from docs/versioned_docs/version-3.15/20-usage/72-extensions/55-secret-extension.md rename to docs/versioned_docs/version-3.18/20-usage/72-extensions/55-secret-extension.md index 910dae4d6..f1d9634e4 100644 --- a/docs/versioned_docs/version-3.15/20-usage/72-extensions/55-secret-extension.md +++ b/docs/versioned_docs/version-3.18/20-usage/72-extensions/55-secret-extension.md @@ -171,4 +171,4 @@ Example response: These extensions are neither developed nor verified by Woodpecker CI. Make sure you trust them before using. ::: -- [OpenBao extension](https://github.com/vcheesbrough/woodpecker-openbao-broker) +_Add your extension here!_ diff --git a/docs/versioned_docs/version-3.15/20-usage/72-extensions/_category_.yaml b/docs/versioned_docs/version-3.18/20-usage/72-extensions/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/72-extensions/_category_.yaml rename to docs/versioned_docs/version-3.18/20-usage/72-extensions/_category_.yaml diff --git a/docs/versioned_docs/version-3.15/20-usage/72-extensions/index.md b/docs/versioned_docs/version-3.18/20-usage/72-extensions/index.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/72-extensions/index.md rename to docs/versioned_docs/version-3.18/20-usage/72-extensions/index.md diff --git a/docs/versioned_docs/version-3.15/20-usage/72-linter.md b/docs/versioned_docs/version-3.18/20-usage/72-linter.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/72-linter.md rename to docs/versioned_docs/version-3.18/20-usage/72-linter.md diff --git a/docs/versioned_docs/version-3.18/20-usage/73-local-execution.md b/docs/versioned_docs/version-3.18/20-usage/73-local-execution.md new file mode 100644 index 000000000..8563dab24 --- /dev/null +++ b/docs/versioned_docs/version-3.18/20-usage/73-local-execution.md @@ -0,0 +1,91 @@ +# Local pipeline execution + +`woodpecker-cli exec` runs workflow files from your local checkout. Use it to test pipeline changes before pushing them, to debug a workflow without waiting for a server run, or to replay a server pipeline with downloaded metadata. + +## Requirements + +- Install `woodpecker-cli` from the [distribution packages](../30-administration/05-installation/30-packages.md) or a release archive. +- Run the command from the repository checkout, or pass `--repo-path` to point at it. +- Make sure the backend you want to use is available locally. The Docker backend needs access to a Docker daemon. The local backend runs commands directly on your host and does not reproduce the container image environment. + +## Run a workflow file + +Create or edit a workflow file, then run it directly: + +```shell +woodpecker-cli exec .woodpecker/my-first-workflow.yaml +``` + +You can also run every `.yaml` and `.yml` file in a workflow directory: + +```shell +woodpecker-cli exec .woodpecker/ +``` + +By default, Woodpecker auto-detects a backend. Select one explicitly when you want the local run to match a specific agent backend: + +```shell +woodpecker-cli exec --backend-engine docker .woodpecker/my-first-workflow.yaml +woodpecker-cli exec --backend-engine local .woodpecker/my-first-workflow.yaml +``` + +## Pass metadata + +Metadata values are set automatically, but you can override them to test conditions such as branches, pull requests, tags, and events: + +```shell +woodpecker-cli exec \ + --pipeline-event push \ + --commit-branch main \ + --commit-sha "$(git rev-parse HEAD)" \ + --repo octocat/hello-world \ + .woodpecker/my-first-workflow.yaml +``` + +If you downloaded pipeline metadata from the Woodpecker UI, pass it with `--metadata-file` and adjust individual values with other flags when needed: + +```shell +woodpecker-cli exec \ + --metadata-file pipeline-metadata.json \ + --pipeline-event pull_request \ + .woodpecker/my-first-workflow.yaml +``` + +:::warning +The metadata file is not a stable, portable API: its format is only guaranteed for the same server and CLI version it came from. Use it to replay against a matching version, and re-download after upgrades instead of reusing old files. +::: + +## Pass environment variables and secrets + +Use `--env` for regular environment variables: + +```shell +woodpecker-cli exec \ + --env GOFLAGS=-mod=readonly \ + .woodpecker/test.yaml +``` + +Secrets are not downloaded from the server. Pass the values needed for local debugging explicitly: + +```shell +woodpecker-cli exec \ + --secrets deploy_token="$DEPLOY_TOKEN" \ + .woodpecker/deploy.yaml +``` + +For multiple secrets, keep them in a local YAML file that is ignored by Git: + +```yaml title=".woodpecker/local-secrets.yaml" +deploy_token: ghp_example +registry_password: example-password +``` + +```shell +woodpecker-cli exec \ + --secrets-file .woodpecker/local-secrets.yaml \ + .woodpecker/deploy.yaml +``` + +## More options + +See the generated [CLI reference](../40-cli.md#exec) for the full list of `exec` flags. diff --git a/docs/versioned_docs/version-3.15/20-usage/75-project-settings.md b/docs/versioned_docs/version-3.18/20-usage/75-project-settings.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/75-project-settings.md rename to docs/versioned_docs/version-3.18/20-usage/75-project-settings.md diff --git a/docs/versioned_docs/version-3.15/20-usage/80-badges.md b/docs/versioned_docs/version-3.18/20-usage/80-badges.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/80-badges.md rename to docs/versioned_docs/version-3.18/20-usage/80-badges.md diff --git a/docs/versioned_docs/version-3.15/20-usage/90-advanced-usage.md b/docs/versioned_docs/version-3.18/20-usage/90-advanced-usage.md similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/90-advanced-usage.md rename to docs/versioned_docs/version-3.18/20-usage/90-advanced-usage.md diff --git a/docs/versioned_docs/version-3.15/20-usage/_category_.yaml b/docs/versioned_docs/version-3.18/20-usage/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/_category_.yaml rename to docs/versioned_docs/version-3.18/20-usage/_category_.yaml diff --git a/docs/versioned_docs/version-3.15/20-usage/cron-settings.png b/docs/versioned_docs/version-3.18/20-usage/cron-settings.png similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/cron-settings.png rename to docs/versioned_docs/version-3.18/20-usage/cron-settings.png diff --git a/docs/versioned_docs/version-3.15/20-usage/linter-warnings-errors.png b/docs/versioned_docs/version-3.18/20-usage/linter-warnings-errors.png similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/linter-warnings-errors.png rename to docs/versioned_docs/version-3.18/20-usage/linter-warnings-errors.png diff --git a/docs/versioned_docs/version-3.15/20-usage/pipeline.png b/docs/versioned_docs/version-3.18/20-usage/pipeline.png similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/pipeline.png rename to docs/versioned_docs/version-3.18/20-usage/pipeline.png diff --git a/docs/versioned_docs/version-3.15/20-usage/project-settings.png b/docs/versioned_docs/version-3.18/20-usage/project-settings.png similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/project-settings.png rename to docs/versioned_docs/version-3.18/20-usage/project-settings.png diff --git a/docs/versioned_docs/version-3.15/20-usage/repo-new.png b/docs/versioned_docs/version-3.18/20-usage/repo-new.png similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/repo-new.png rename to docs/versioned_docs/version-3.18/20-usage/repo-new.png diff --git a/docs/versioned_docs/version-3.15/20-usage/secrets-plugins-filter.png b/docs/versioned_docs/version-3.18/20-usage/secrets-plugins-filter.png similarity index 100% rename from docs/versioned_docs/version-3.15/20-usage/secrets-plugins-filter.png rename to docs/versioned_docs/version-3.18/20-usage/secrets-plugins-filter.png diff --git a/docs/versioned_docs/version-3.15/30-administration/00-general.md b/docs/versioned_docs/version-3.18/30-administration/00-general.md similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/00-general.md rename to docs/versioned_docs/version-3.18/30-administration/00-general.md diff --git a/docs/versioned_docs/version-3.15/30-administration/05-installation/05-supported-platforms.md b/docs/versioned_docs/version-3.18/30-administration/05-installation/05-supported-platforms.md similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/05-installation/05-supported-platforms.md rename to docs/versioned_docs/version-3.18/30-administration/05-installation/05-supported-platforms.md diff --git a/docs/versioned_docs/version-3.15/30-administration/05-installation/10-docker-compose.md b/docs/versioned_docs/version-3.18/30-administration/05-installation/10-docker-compose.md similarity index 99% rename from docs/versioned_docs/version-3.15/30-administration/05-installation/10-docker-compose.md rename to docs/versioned_docs/version-3.18/30-administration/05-installation/10-docker-compose.md index 3567dd9d3..9b6893bd8 100644 --- a/docs/versioned_docs/version-3.15/30-administration/05-installation/10-docker-compose.md +++ b/docs/versioned_docs/version-3.18/30-administration/05-installation/10-docker-compose.md @@ -74,7 +74,7 @@ If the agents establish a connection via the Internet, TLS encryption should be environment: - [...] + - WOODPECKER_GRPC_SECURE=true # defaults to false -+ - WOODPECKER_GRPC_VERIFY=true # default ++ - WOODPECKER_GRPC_SKIP_VERIFY=false # default ``` As agents execute pipeline steps as Docker containers, they require access to the Docker daemon of the host machine: diff --git a/docs/versioned_docs/version-3.15/30-administration/05-installation/20-helm-chart.md b/docs/versioned_docs/version-3.18/30-administration/05-installation/20-helm-chart.md similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/05-installation/20-helm-chart.md rename to docs/versioned_docs/version-3.18/30-administration/05-installation/20-helm-chart.md diff --git a/docs/versioned_docs/version-3.15/30-administration/05-installation/30-packages.md b/docs/versioned_docs/version-3.18/30-administration/05-installation/30-packages.md similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/05-installation/30-packages.md rename to docs/versioned_docs/version-3.18/30-administration/05-installation/30-packages.md diff --git a/docs/versioned_docs/version-3.15/30-administration/05-installation/_category_.yaml b/docs/versioned_docs/version-3.18/30-administration/05-installation/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/05-installation/_category_.yaml rename to docs/versioned_docs/version-3.18/30-administration/05-installation/_category_.yaml diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/10-server.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/10-server.md similarity index 86% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/10-server.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/10-server.md index bcf4a0c78..4f7621b19 100644 --- a/docs/versioned_docs/version-3.15/30-administration/10-configuration/10-server.md +++ b/docs/versioned_docs/version-3.18/30-administration/10-configuration/10-server.md @@ -18,7 +18,7 @@ You can also restrict the registration: WOODPECKER_ADMIN=john.smith,jane_doe ``` -- open registration and filtering by organizational affiliation with the setting `WOODPECKER_ORGS` +- open registration and filtering by organizational affiliation with the setting `WOODPECKER_ORGS`. For GitLab forges group names have to exact match, so members of group `group` are not permitted access if you set `WOODPECKER_ORGS=group/subgroup`. ```ini WOODPECKER_OPEN=true @@ -400,8 +400,27 @@ woodpecker_waiting_steps 0 # HELP woodpecker_worker_count Total number of workers. # TYPE woodpecker_worker_count gauge woodpecker_worker_count 4 +# HELP woodpecker_step_failures_total Total number of pipeline step failures. +# TYPE woodpecker_step_failures_total counter +woodpecker_step_failures_total{repo="woodpecker-ci/woodpecker",step="deploy",workflow="woodpecker"} 1 +# HELP woodpecker_step_duration_seconds Step duration in seconds. +# TYPE woodpecker_step_duration_seconds histogram +woodpecker_step_duration_seconds_bucket{repo="woodpecker-ci/woodpecker",step="deploy",workflow="woodpecker",le="1"} 0 +woodpecker_step_duration_seconds_bucket{repo="woodpecker-ci/woodpecker",step="deploy",workflow="woodpecker",le="5"} 0 +woodpecker_step_duration_seconds_bucket{repo="woodpecker-ci/woodpecker",step="deploy",workflow="woodpecker",le="10"} 0 +woodpecker_step_duration_seconds_bucket{repo="woodpecker-ci/woodpecker",step="deploy",workflow="woodpecker",le="30"} 1 +woodpecker_step_duration_seconds_bucket{repo="woodpecker-ci/woodpecker",step="deploy",workflow="woodpecker",le="60"} 1 +woodpecker_step_duration_seconds_bucket{repo="woodpecker-ci/woodpecker",step="deploy",workflow="woodpecker",le="300"} 1 +woodpecker_step_duration_seconds_bucket{repo="woodpecker-ci/woodpecker",step="deploy",workflow="woodpecker",le="600"} 1 +woodpecker_step_duration_seconds_bucket{repo="woodpecker-ci/woodpecker",step="deploy",workflow="woodpecker",le="1800"} 1 +woodpecker_step_duration_seconds_bucket{repo="woodpecker-ci/woodpecker",step="deploy",workflow="woodpecker",le="3600"} 1 +woodpecker_step_duration_seconds_bucket{repo="woodpecker-ci/woodpecker",step="deploy",workflow="woodpecker",le="+Inf"} 1 +woodpecker_step_duration_seconds_sum{repo="woodpecker-ci/woodpecker",step="deploy",workflow="woodpecker"} 12 +woodpecker_step_duration_seconds_count{repo="woodpecker-ci/woodpecker",step="deploy",workflow="woodpecker"} 1 ``` +Step-level metrics are exported as long as `WOODPECKER_STEP_LEVEL_METRICS` is not disabled. + #### Example response structure ```json @@ -558,7 +577,7 @@ Examples: - Name: `WOODPECKER_SERVER_ADDR` - Default: `:8000` -Configures the HTTP listener port. +Configures the HTTP listener, supports unix socket via unix:// prefix". --- @@ -624,16 +643,27 @@ Example: `WOODPECKER_CUSTOM_JS_FILE=/usr/local/www/woodpecker.js` - Name: `WOODPECKER_GRPC_ADDR` - Default: `:9000` -Configures the gRPC listener port. +Configures the gRPC listener. Use `localhost:9000` or any IP address to bind it to a specific interface. +If you want an unix socket use `unix://` prefix, for example `unix:///run/woodpecker-grcp.sock`. --- ### GRPC_SECRET - Name: `WOODPECKER_GRPC_SECRET` -- Default: `secret` +- Default: none -Configures the gRPC JWT secret. +Configures the secret used to sign JWTs for gRPC connections. + +If this setting is empty, the server generates a secure temporary secret and logs a warning. The generated secret is not persisted and changes each time the server starts. Configure and persist a secret to keep it stable across restarts. Setting this explicitly is important for high availability (HA) setups with multiple server replicas: each replica would otherwise generate its own secret and reject the gRPC tokens issued by the other replicas. Generate a secure secret with: + +```shell +openssl rand -hex 32 +``` + +Store the generated value securely and provide it through `WOODPECKER_GRPC_SECRET` or `WOODPECKER_GRPC_SECRET_FILE`. + +After this secret is rotated, connected agents reauthenticate when the server rejects their old token. Agents do not need to be restarted as long as `WOODPECKER_AGENT_SECRET` remains unchanged. --- @@ -642,7 +672,7 @@ Configures the gRPC JWT secret. - Name: `WOODPECKER_GRPC_SECRET_FILE` - Default: none -Read the value for `WOODPECKER_GRPC_SECRET` from the specified filepath. +Read the value for `WOODPECKER_GRPC_SECRET` from the specified filepath. The file should be stored persistently and only be readable by the Woodpecker server. --- @@ -657,6 +687,15 @@ Example: `:9001` --- +### STEP_LEVEL_METRICS + +- Name: `WOODPECKER_STEP_LEVEL_METRICS` +- Default: `true` + +Enable step-level metrics, including failed step counters and step duration histograms. + +--- + ### ADMIN - Name: `WOODPECKER_ADMIN` @@ -673,10 +712,13 @@ Example: `WOODPECKER_ADMIN=user1,user2` - Name: `WOODPECKER_ORGS` - Default: none -Comma-separated list of approved organizations. +Comma-separated list of approved organizations. For GitLab forges this is the `full_path` [attribute](https://docs.gitlab.com/api/groups/). Example: `org1,org2` +This setting applies to all [forges](./12-forges/11-overview.md). A forge can allow further organizations in addition, configured in the admin UI (`Settings` -> `Forges` -> `Advanced options`). As organization names are only unique within a single forge, someone could create an organization with a name from this setting on another connected forge to gain access. +If you connected more than one forge, you should therefore leave this setting empty and configure the allowed organizations per forge. See [restricting who can log in](./12-forges/11-overview.md#restricting-who-can-log-in) for details. + --- ### REPO_OWNERS @@ -708,6 +750,19 @@ Always use authentication to clone repositories even if they are public. Needed --- +### ASYNC_REPOSITORY_UPDATE + +- Name: `WOODPECKER_ASYNC_REPOSITORY_UPDATE` +- Default: `false` + +Enable asynchronous fetching user permissions for repositories. Will drastically improve login speed for user login if the organisation has many git repositories. + +When disabled (default) users will have to wait for all repository access information before being redirected to the Woodpecker homepage. Choose this for strong consistency. + +When enabled users will immediately be redirected to the Woodpecker homepage, but might see outdated information if repository access changed or new repositories were added. Choose this for eventual consistency. + +--- + ### DEFAULT_ALLOW_PULL_REQUESTS - Name: `WOODPECKER_DEFAULT_ALLOW_PULL_REQUESTS` diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/100-addons.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/100-addons.md similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/100-addons.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/100-addons.md diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/11-backends/10-docker.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/11-backends/10-docker.md similarity index 95% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/11-backends/10-docker.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/11-backends/10-docker.md index 1885258f8..9ed5f3dab 100644 --- a/docs/versioned_docs/version-3.15/30-administration/10-configuration/11-backends/10-docker.md +++ b/docs/versioned_docs/version-3.18/30-administration/10-configuration/11-backends/10-docker.md @@ -95,6 +95,15 @@ certificates installed on host and host timezone use `/etc/ssl/certs:/etc/ssl/ce --- +### BACKEND_DOCKER_APPARMOR_PROFILE + +- Name: `WOODPECKER_BACKEND_DOCKER_APPARMOR_PROFILE` +- Default: none + +Set an AppArmor profile for pipeline containers (steps). If unset, Docker applies its default AppArmor behavior. + +--- + ### BACKEND_DOCKER_LIMIT_MEM_SWAP - Name: `WOODPECKER_BACKEND_DOCKER_LIMIT_MEM_SWAP` diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/11-backends/20-kubernetes.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/11-backends/20-kubernetes.md similarity index 85% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/11-backends/20-kubernetes.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/11-backends/20-kubernetes.md index e2796f5ba..1122aa6a5 100644 --- a/docs/versioned_docs/version-3.15/30-administration/10-configuration/11-backends/20-kubernetes.md +++ b/docs/versioned_docs/version-3.18/30-administration/10-configuration/11-backends/20-kubernetes.md @@ -81,6 +81,12 @@ steps: To give steps access to the Kubernetes API via service account, take a look at [RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) +By default, setting `serviceAccountName` from a step's backend options is **not allowed** for security reasons, as it would let any user with push access run pipeline pods under an arbitrary service account and inherit its permissions. To enable it, set [`WOODPECKER_BACKEND_K8S_SERVICE_ACCOUNT_NAME_ALLOW_FROM_STEP`](#backend_k8s_service_account_name_allow_from_step) on the agent. + +:::warning +Enabling `WOODPECKER_BACKEND_K8S_SERVICE_ACCOUNT_NAME_ALLOW_FROM_STEP` in multi-tenant environments allows pipeline authors to run pods as any service account in the namespace, which may lead to privilege escalation. Only enable it if you trust everyone with push access. +::: + ### Workspace volume `workspaceVolume` controls whether the default workspace volume is mounted into a service Pod. It only affects service @@ -97,6 +103,29 @@ services: workspaceVolume: false ``` +### User namespaces + +`hostUsers` controls whether the Pod uses the host's user namespace. When set to `false`, Kubernetes runs the Pod in a dedicated user namespace where UID 0 inside the container maps to a non-root UID on the host, providing an additional layer of isolation. + +See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/workloads/pods/user-namespaces/) for more information on user namespaces. + +```yaml +steps: + - name: build + image: alpine + commands: + - whoami + backend_options: + kubernetes: + hostUsers: false + securityContext: + runAsUser: 0 +``` + +:::note +User namespaces require Kubernetes v1.25+ with the `UserNamespacesSupport` feature gate enabled, and a compatible container runtime (e.g. CRI-O, containerd v2.0+). +::: + ### Node selector `nodeSelector` specifies the labels which are used to select the node on which the step will be executed. @@ -129,6 +158,8 @@ And then overwrite the `nodeSelector` in the `backend_options` section of the st You can use [WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR](#backend_k8s_pod_node_selector) if you want to set the node selector per Agent or [PodNodeSelector](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#podnodeselector) admission controller if you want to set the node selector by per-namespace basis. +By default, setting `nodeSelector` from a step's backend options is **not allowed**, as it would otherwise let any user with push access pin pipeline pods onto chosen nodes. To enable it, set [`WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR_ALLOW_FROM_STEP`](#backend_k8s_pod_node_selector_allow_from_step) on the agent. + ### Tolerations When you use `nodeSelector` and the node pool is configured with Taints, you need to specify the Tolerations. Tolerations allow the scheduler to schedule Pods with matching taints. @@ -456,7 +487,7 @@ steps: - name: docker image: docker:dind # use 'docker:-dind' or similar in production - detached: true + detach: true privileged: true environment: DOCKER_TLS_CERTDIR: /woodpecker/dind-certs @@ -488,6 +519,19 @@ Enables namespace isolation per Woodpecker organization. When enabled, each orga 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_CLUSTER_DOMAIN + +- Name: `WOODPECKER_BACKEND_K8S_CLUSTER_DOMAIN` +- Default: `cluster.local` + +The DNS domain of the Kubernetes cluster. It is used to build the DNS search entry that lets a step reach a service by its hostname. + +Set this value if your cluster was installed with a custom cluster domain. + +--- + ### BACKEND_K8S_VOLUME_SIZE - Name: `WOODPECKER_BACKEND_K8S_VOLUME_SIZE` @@ -578,6 +622,15 @@ Additional node selector to apply to worker pods. Must be a YAML object, e.g. `{ --- +### BACKEND_K8S_POD_NODE_SELECTOR_ALLOW_FROM_STEP + +- Name: `WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR_ALLOW_FROM_STEP` +- Default: `false` + +Determines if the Pod `nodeSelector` can be defined from a step's backend options. Disabled by default, as it would otherwise let any user with push access pin pipeline pods onto chosen nodes. + +--- + ### BACKEND_K8S_SECCTX_NONROOT - Name: `WOODPECKER_BACKEND_K8S_SECCTX_NONROOT` @@ -602,3 +655,30 @@ Secret names to pull images from private repositories. See, how to [Pull an Imag - 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. + +--- + +### BACKEND_K8S_PERMISSION_INIT_IMAGE + +- Name: `WOODPECKER_BACKEND_K8S_PERMISSION_INIT_IMAGE` +- Default: 'busybox:stable-musl' + +Container image used for the workspace permission init container, which is used to create the workspace directory and ensure correct permissions when running steps as non-root users. + +--- + +### BACKEND_K8S_SERVICE_ACCOUNT_NAME_ALLOW_FROM_STEP + +- Name: `WOODPECKER_BACKEND_K8S_SERVICE_ACCOUNT_NAME_ALLOW_FROM_STEP` +- Default: `false` + +Determines if the Pod `serviceAccountName` can be defined from a step's backend options. Disabled by default, as it would otherwise allow any user with push access to run pods under an arbitrary service account and escalate privileges. + +--- + +### BACKEND_K8S_RUNTIME_CLASS_ALLOW_FROM_STEP + +- Name: `WOODPECKER_BACKEND_K8S_RUNTIME_CLASS_ALLOW_FROM_STEP` +- Default: `false` + +Determines if the Pod `runtimeClassName` can be defined from a step's backend options. Disabled by default, as it would otherwise allow any user with push access to run pods under an arbitrary runtime class. diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/11-backends/30-local.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/11-backends/30-local.md similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/11-backends/30-local.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/11-backends/30-local.md diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/11-backends/50-custom.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/11-backends/50-custom.md similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/11-backends/50-custom.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/11-backends/50-custom.md diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/11-backends/_category_.yaml b/docs/versioned_docs/version-3.18/30-administration/10-configuration/11-backends/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/11-backends/_category_.yaml rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/11-backends/_category_.yaml diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/11-overview.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/11-overview.md similarity index 61% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/11-overview.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/11-overview.md index f384cefc4..d936c6b48 100644 --- a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/11-overview.md +++ b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/11-overview.md @@ -16,3 +16,26 @@ ยน The deployment event can be triggered for all forges from Woodpecker directly. However, only GitHub can trigger them using webhooks. In addition to this, Woodpecker supports [addon forges](../100-addons.md) if the forge you are using does not meet the [Woodpecker requirements](../../../92-development/02-core-ideas.md#forges) or your setup is too specific to be included in the Woodpecker core. + +## Multiple forges + +:::danger +Support for connecting multiple forges is not finished yet and has to be considered experimental. Please do not use it in public or otherwise untrusted environments. See [known limitations](#known-limitations) below. +::: + +Only **one** forge can be configured using environment variables. Enabling several forge drivers at once does not create several forges. All other forges have to be added by an admin under `Settings` -> `Forges` and exist in the database only. The forge from the environment is written back on every server start, so changing its driver replaces it instead of adding a new one. + +### Restricting who can log in + +[`WOODPECKER_ORGS`](../10-server.md#orgs) applies to all connected forges. In addition, each forge can carry its own list under `Settings` -> `Forges` -> `Advanced options` -> `Allowed organizations`. Members of an organization on that list may log in using that forge, on top of everyone allowed by `WOODPECKER_ORGS`. A forge without an own list only uses `WOODPECKER_ORGS`; if neither is set, organizations are not checked at all. + +As organization names are only unique within a single forge, someone could create an organization with a name from `WOODPECKER_ORGS` on another connected forge to gain access. If you connected more than one forge, keep `WOODPECKER_ORGS` empty and configure the allowed organizations of each forge instead, including the one from the environment. + +The forge configured through environment variables has no own environment setting for this, its list is edited in the admin UI like the one of any other forge. Only the options listed in its docs are written back on server start, the allowed organizations are kept. + +Use the organization name, for GitLab the group's [`full_path`](https://docs.gitlab.com/api/groups/) like `my-group/my-subgroup`. Matching is case-insensitive and only happens while logging in. + +### Known limitations + +- [`WOODPECKER_ADMIN`](../10-server.md#admin) is matched by login name only. A user with a matching login on **any** connected forge becomes an admin. +- Users are stored per forge, so the same person logging in through two forges gets two independent accounts. diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/20-github.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/20-github.md similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/20-github.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/20-github.md diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/30-gitea.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/30-gitea.md similarity index 98% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/30-gitea.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/30-gitea.md index 7631101fa..fcacf9b95 100644 --- a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/30-gitea.md +++ b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/30-gitea.md @@ -63,7 +63,7 @@ If you run the Woodpecker CI server on the same host as the Gitea instance, you ALLOWED_HOST_LIST=external,loopback ``` -For reference see [Configuration Cheat Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/#webhook-webhook). +For reference see [Configuration Cheat Sheet](https://docs.gitea.com/administration/config-cheat-sheet#webhook-webhook). ![gitea oauth setup](gitea_oauth.gif) diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/35-forgejo.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/35-forgejo.md similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/35-forgejo.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/35-forgejo.md diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/40-gitlab.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/40-gitlab.md similarity index 77% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/40-gitlab.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/40-gitlab.md index 896030e33..8d2d8d20b 100644 --- a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/40-gitlab.md +++ b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/40-gitlab.md @@ -21,6 +21,14 @@ Please use `http://woodpecker.mycompany.com/authorize` as the Authorization call If you run the Woodpecker CI server on a private IP (RFC1918) or use a non standard TLD (e.g. `.local`, `.intern`) with your GitLab instance, you might also need to allow local connections in GitLab, otherwise API requests will fail. In GitLab, navigate to the Admin dashboard, then go to `Settings > Network > Outbound requests` and enable `Allow requests to the local network from web hooks and services`. +## Allowed organizations + +If you restrict logins using [`WOODPECKER_ORGS`](../10-server.md#orgs) or the [allowed organizations of a forge](11-overview.md#restricting-who-can-log-in), GitLab groups are matched by their [`full_path`](https://docs.gitlab.com/api/groups/) and not by their name. For a subgroup you have to use the complete path, e.g. `my-group/my-subgroup`; the name of a single path segment does not match. + +:::warning +Woodpecker only considers GitLab groups in which the user has at least the `Developer` role. A user holding a lower role, such as `Guest` or `Reporter`, is not seen as a member of that group and is denied access even if the group is on the list. +::: + ## Configuration This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations. diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/50-bitbucket.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/50-bitbucket.md similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/50-bitbucket.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/50-bitbucket.md diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.md similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.md diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/_category_.yaml b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/_category_.yaml rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/_category_.yaml diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/bitbucket_oauth.png b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/bitbucket_oauth.png similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/bitbucket_oauth.png rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/bitbucket_oauth.png diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/bitbucket_permissions.png b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/bitbucket_permissions.png similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/bitbucket_permissions.png rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/bitbucket_permissions.png diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/gitea_oauth.gif b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/gitea_oauth.gif similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/gitea_oauth.gif rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/gitea_oauth.gif diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/github_oauth.png b/docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/github_oauth.png similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/12-forges/github_oauth.png rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/12-forges/github_oauth.png diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/30-agent.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/30-agent.md similarity index 92% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/30-agent.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/30-agent.md index 6c4d2bdb8..1614f0357 100644 --- a/docs/versioned_docs/version-3.15/30-administration/10-configuration/30-agent.md +++ b/docs/versioned_docs/version-3.18/30-administration/10-configuration/30-agent.md @@ -63,7 +63,7 @@ To get an _agent token_ you have to register the agent manually in the server us - Name: `WOODPECKER_SERVER` - Default: `localhost:9000` -Configures gRPC address of the server. +Configures gRPC address to the server. If you want to use an unix socket add `unix://` prefix and the path. --- @@ -215,13 +215,13 @@ After pinging for a keepalive check, the agent waits for a duration of this time - Name: `WOODPECKER_GRPC_SECURE` - Default: `false` -Configures if the connection to `WOODPECKER_SERVER` should be made using a secure transport. +Configures if the connection to `WOODPECKER_SERVER` should be made using a secure transport (tls). --- -### GRPC_VERIFY +### GRPC_SKIP_VERIFY -- Name: `WOODPECKER_GRPC_VERIFY` +- Name: `WOODPECKER_GRPC_SKIP_VERIFY` - Default: `true` Configures if the gRPC server certificate should be verified, only valid when `WOODPECKER_GRPC_SECURE` is `true`. @@ -241,6 +241,20 @@ If set to 0 we retry forever. --- +## LOG_ENTRY_STREAM_BUFFER_SIZE + +- Name: `WOODPECKER_LOG_ENTRY_STREAM_BUFFER_SIZE` +- Default: `100` + +Set how many log lines an agent can buffer before it blocks io.Pipe, expect logentries to reach 1 MB in worst case. +If used with local backend, tis can increase your performance in special cases significantly. + +:::warning +If set to 0 we are always blocking. +::: + +--- + ### BACKEND - Name: `WOODPECKER_BACKEND` diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/40-autoscaler.md b/docs/versioned_docs/version-3.18/30-administration/10-configuration/40-autoscaler.md similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/40-autoscaler.md rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/40-autoscaler.md diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/_category_.yaml b/docs/versioned_docs/version-3.18/30-administration/10-configuration/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/_category_.yaml rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/_category_.yaml diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/new-agent-connected.png b/docs/versioned_docs/version-3.18/30-administration/10-configuration/new-agent-connected.png similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/new-agent-connected.png rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/new-agent-connected.png diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/new-agent-created.png b/docs/versioned_docs/version-3.18/30-administration/10-configuration/new-agent-created.png similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/new-agent-created.png rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/new-agent-created.png diff --git a/docs/versioned_docs/version-3.15/30-administration/10-configuration/new-agent-registration.png b/docs/versioned_docs/version-3.18/30-administration/10-configuration/new-agent-registration.png similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/10-configuration/new-agent-registration.png rename to docs/versioned_docs/version-3.18/30-administration/10-configuration/new-agent-registration.png diff --git a/docs/versioned_docs/version-3.15/30-administration/_category_.yaml b/docs/versioned_docs/version-3.18/30-administration/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.15/30-administration/_category_.yaml rename to docs/versioned_docs/version-3.18/30-administration/_category_.yaml diff --git a/docs/versioned_docs/version-3.15/40-cli.md b/docs/versioned_docs/version-3.18/40-cli.md similarity index 89% rename from docs/versioned_docs/version-3.15/40-cli.md rename to docs/versioned_docs/version-3.18/40-cli.md index 67818a14e..ec832bb4b 100644 --- a/docs/versioned_docs/version-3.15/40-cli.md +++ b/docs/versioned_docs/version-3.18/40-cli.md @@ -1,5 +1,48 @@ # CLI +# CONFIGURATION + +woodpecker-cli stores named contexts in a `contexts.json` file under the user's configuration directory. `XDG_CONFIG_HOME` overrides the base directory. The default paths are: + +| Platform | Path | +| --- | --- | +| Linux and other Unix systems | `~/.config/woodpecker/contexts.json` | +| macOS | `~/Library/Application Support/woodpecker/contexts.json` | +| Windows | `C:\Users\\AppData\Local\woodpecker\contexts.json` | + +The file records the selected context and its non-secret connection settings: + +```json +{ + "current_context": "production", + "contexts": { + "production": { + "name": "production", + "server_url": "https://ci.example.test", + "log_level": "info" + } + } +} +``` + +`current_context` must name an entry in `contexts`. The `woodpecker-cli context use` command changes that selection. Authentication tokens are never written to this JSON file; they are stored in the operating system's keyring and looked up by server URL. + +## Legacy configuration + +If no usable current context can be loaded, woodpecker-cli falls back to the legacy `config.json` file in the same configuration directory. `--config` or `WOODPECKER_CONFIG` selects a different legacy file. The legacy JSON accepts `server_url` and `log_level`; its token is also read from the operating system's keyring, not from JSON. + +## Precedence + +Command-line flags take precedence over their matching environment variables, and either source takes precedence over stored context or legacy values: + +| Flag | Environment variable | +| --- | --- | +| `--server` | `WOODPECKER_SERVER` | +| `--token` | `WOODPECKER_TOKEN` | +| `--log-level` | `WOODPECKER_LOG_LEVEL` | + +The `--config` flag and `WOODPECKER_CONFIG` only choose the legacy configuration file; they do not replace or select a context. + # NAME woodpecker-cli - command line utility @@ -227,6 +270,8 @@ execute a local pipeline **--backend-docker-api-version**="": the version of the API to reach, leave empty for latest. +**--backend-docker-apparmor-profile**="": AppArmor profile applied to backend Docker containers + **--backend-docker-cert**="": path to load the TLS certificates for connecting to docker server **--backend-docker-host**="": path to docker socket or url to the docker server @@ -261,10 +306,14 @@ execute a local pipeline **--backend-k8s-allow-native-secrets**: whether to allow existing Kubernetes secrets to be referenced from steps (default: false) +**--backend-k8s-cluster-domain**="": backend k8s cluster domain, used to build the DNS search entry (default: cluster.local) + **--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. (default: false) +**--backend-k8s-permission-init-image**="": image used by the workspace permission init container (default: busybox:stable-musl) + **--backend-k8s-pod-affinity**="": backend k8s Agent-wide worker pod affinity, in YAML format **--backend-k8s-pod-affinity-allow-from-step**: whether to allow using affinity from step's backend options (default: false) @@ -281,14 +330,20 @@ execute a local pipeline **--backend-k8s-pod-node-selector**="": backend k8s Agent-wide worker pod node selector +**--backend-k8s-pod-node-selector-allow-from-step**: whether to allow using node selector from step's backend options (default: false) + **--backend-k8s-pod-tolerations**="": backend k8s Agent-wide worker pod tolerations **--backend-k8s-pod-tolerations-allow-from-step**: whether to allow using tolerations from step's backend options (default: true) **--backend-k8s-priority-class**="": which kubernetes priority class to assign to created job pods +**--backend-k8s-runtime-class-allow-from-step**: whether to allow using runtime class name from step's backend options (default: false) + **--backend-k8s-secctx-nonroot**: `run as non root` Kubernetes security context option (default: false) +**--backend-k8s-service-account-name-allow-from-step**: whether to allow using service account name from step's backend options (default: false) + **--backend-k8s-stop-timeout**="": seconds Woodpecker waits for pods to stop gracefully before forcefully killing them (default: 20) **--backend-k8s-storage-class**="": backend k8s storage class @@ -313,6 +368,8 @@ execute a local pipeline **--commit-message**="": Set the metadata environment variable "CI_COMMIT_MESSAGE". +**--commit-pull-draft**: Set the metadata environment variable "CI_COMMIT_PULL_REQUEST_DRAFT". (default: false) + **--commit-pull-labels**="": Set the metadata environment variable "CI_COMMIT_PULL_REQUEST_LABELS". **--commit-pull-milestone**="": Set the metadata environment variable "CI_COMMIT_PULL_REQUEST_MILESTONE". @@ -321,10 +378,12 @@ execute a local pipeline **--commit-refspec**="": Set the metadata environment variable "CI_COMMIT_REFSPEC". -**--commit-release-is-pre**: Set the metadata environment variable "CI_COMMIT_PRERELEASE". (default: false) +**--commit-release-is-pre**: Set the metadata environment variable "CI_PIPELINE_RELEASE_PRE". (default: false) **--commit-sha**="": Set the metadata environment variable "CI_COMMIT_SHA". +**--commit-timestamp**="": Set the metadata environment variable "CI_COMMIT_TIMESTAMP". (default: 0) + **--env**="": Set the metadata environment variable "CI_ENV". **--forge-type**="": Set the metadata environment variable "CI_FORGE_TYPE". @@ -333,7 +392,7 @@ execute a local pipeline **--local**: run from local directory (default: true) -**--metadata-file**="": path to pipeline metadata file (normally downloaded from UI). Parameters can be adjusted by applying additional cli flags +**--metadata-file**="": path to pipeline metadata file (normally downloaded from UI). Parameters can be adjusted by applying additional cli flags. The metadata format is only expected to work with the same Woodpecker version it was downloaded from and is not intended to be portable between versions **--netrc-machine**="": @@ -357,6 +416,8 @@ execute a local pipeline **--pipeline-parent**="": Set the metadata environment variable "CI_PIPELINE_PARENT". (default: 0) +**--pipeline-release**="": Set the metadata environment variable "CI_PIPELINE_RELEASE_TITLE". + **--pipeline-started**="": Set the metadata environment variable "CI_PIPELINE_STARTED". (default: 0) **--pipeline-url**="": Set the metadata environment variable "CI_PIPELINE_FORGE_URL". @@ -373,6 +434,8 @@ execute a local pipeline **--prev-commit-message**="": Set the metadata environment variable "CI_PREV_COMMIT_MESSAGE". +**--prev-commit-message**="": Set the metadata environment variable "CI_PREV_COMMIT_TIMESTAMP". (default: 0) + **--prev-commit-ref**="": Set the metadata environment variable "CI_PREV_COMMIT_REF". **--prev-commit-refspec**="": Set the metadata environment variable "CI_PREV_COMMIT_REFSPEC". @@ -455,7 +518,7 @@ lint a pipeline configuration file **--plugins-privileged**="": allow plugins to run in privileged mode, if set empty, there is no -**--plugins-trusted-clone**="": plugins that are trusted to handle Git credentials in cloning steps (default: "docker.io/woodpeckerci/plugin-git:2.9.1", "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.9.3", "docker.io/woodpeckerci/plugin-git", "quay.io/woodpeckerci/plugin-git") **--strict**: treat warnings as errors (default: false) diff --git a/docs/versioned_docs/version-3.15/92-development/01-getting-started.md b/docs/versioned_docs/version-3.18/92-development/01-getting-started.md similarity index 77% rename from docs/versioned_docs/version-3.15/92-development/01-getting-started.md rename to docs/versioned_docs/version-3.18/92-development/01-getting-started.md index ed8020202..068fda0f1 100644 --- a/docs/versioned_docs/version-3.15/92-development/01-getting-started.md +++ b/docs/versioned_docs/version-3.18/92-development/01-getting-started.md @@ -1,28 +1,10 @@ # Getting started -You can develop on your local computer by following the [steps below](#preparation-for-local-development) or you can start with a fully prepared online setup using [Gitpod](https://github.com/gitpod-io/gitpod) and [Gitea](https://github.com/go-gitea/gitea). - -## Gitpod - -If you want to start development or updating docs as easy as possible, you can use our pre-configured setup for Woodpecker using [Gitpod](https://github.com/gitpod-io/gitpod). Gitpod starts a complete development setup in the cloud containing: - -- An IDE in the browser or bridged to your local VS-Code or Jetbrains -- A pre-configured [Gitea](https://github.com/go-gitea/gitea) instance as forge -- A pre-configured Woodpecker server -- A single pre-configured Woodpecker agent node -- Our docs preview server - -Start Woodpecker in Gitpod by clicking on the following badge. You can log in with `woodpecker` and `password`. - -[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/woodpecker-ci/woodpecker) - -## Preparation for local development - -### Install Go +## Install Go Install Golang as described by [this guide](https://go.dev/doc/install). -### Install make +## Install make > GNU Make is a tool which controls the generation of executables and other non-source files of a program from the program's source files (). @@ -32,19 +14,19 @@ Install make on: - [Windows](https://stackoverflow.com/a/32127632/8461267) - Mac OS: `brew install make` -### Install Node.js & `pnpm` +## Install Node.js & `pnpm` Install [Node.js](https://nodejs.org/en/download/package-manager) if you want to build Woodpecker's UI or documentation. For dependency installation (`node_modules`) of UI and documentation of Woodpecker the package manager pnpm is used. [This guide](https://pnpm.io/installation) describes the installation of `pnpm`. -### Install `pre-commit` (optional) +## Install `pre-commit` (optional) Woodpecker uses [`pre-commit`](https://pre-commit.com/) to allow you to easily autofix your code. To apply it during local development, take a look at [`pre-commit`s documentation](https://pre-commit.com/#usage). -### Create a `.env` file with your development configuration +## Create a `.env` file with your development configuration Similar to the environment variables you can set for your production setup of Woodpecker, you can create a `.env` file in the root of the Woodpecker project and add any needed config to it. @@ -79,7 +61,7 @@ WOODPECKER_HEALTHCHECK=false # WOODPECKER_LOG_LEVEL=trace ``` -### Setup OAuth +## Setup OAuth Create an OAuth app for your forge as described in the [forges documentation](../30-administration/10-configuration/12-forges/11-overview.md). @@ -102,26 +84,31 @@ The Woodpecker source code already includes launch configurations for the Woodpe To test or lint parts of Woodpecker, you can run one of the following commands: -```bash -# test server code +```bash title="test server code" make test-server +``` -# test agent code +```bash title="test agent code" make test-agent +``` -# test cli code +```bash title="test cli code" make test-cli +``` -# test datastore / database related code like migrations of the server +```bash title="test datastore/database related code like migrations of the server" make test-server-datastore +``` -# lint go code +```bash title="lint go code" make lint +``` -# lint UI code +```bash title="lint UI code" make lint-frontend +``` -# test UI code +```bash title="test UI code" make test-frontend ``` diff --git a/docs/versioned_docs/version-3.15/92-development/02-core-ideas.md b/docs/versioned_docs/version-3.18/92-development/02-core-ideas.md similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/02-core-ideas.md rename to docs/versioned_docs/version-3.18/92-development/02-core-ideas.md diff --git a/docs/versioned_docs/version-3.15/92-development/03-ui.md b/docs/versioned_docs/version-3.18/92-development/03-ui.md similarity index 82% rename from docs/versioned_docs/version-3.15/92-development/03-ui.md rename to docs/versioned_docs/version-3.18/92-development/03-ui.md index 8186b63f3..520e157aa 100644 --- a/docs/versioned_docs/version-3.15/92-development/03-ui.md +++ b/docs/versioned_docs/version-3.18/92-development/03-ui.md @@ -41,6 +41,26 @@ The following list contains some tools and frameworks used by the Woodpecker UI. - [Volar & vue-tsc](https://github.com/johnsoncodehk/volar/) for type-checking in .vue file - use the take-over mode of Volar as described by [this guide](https://github.com/johnsoncodehk/volar/discussions/471) +## Form components + +Reusable form controls live in `web/src/components/form/`. They are all built to be placed inside an `InputField`, which renders the label, the optional description and a docs link, and passes down the `id` the control has to attach to its input: + +```vue + + + + +``` + +Besides the single-value controls (`TextField`, `NumberField`, `Checkbox`, `SelectField`, `RadioField`) there are two editors for collections: + +- `ListEditor` for a list of strings, such as plugin images or usernames +- `KeyValueEditor` for a `Record`, such as environment variables + ## Messages and Translations Woodpecker uses [Vue I18n](https://vue-i18n.intlify.dev/) as translation library. New translations have to be added to `web/src/assets/locales/en.json`. The English source file will be automatically imported into [Weblate](https://translate.woodpecker-ci.org/) (the translation system used by Woodpecker) where all other languages will be translated by the community based on the English source. diff --git a/docs/versioned_docs/version-3.15/92-development/04-docs.md b/docs/versioned_docs/version-3.18/92-development/04-docs.md similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/04-docs.md rename to docs/versioned_docs/version-3.18/92-development/04-docs.md diff --git a/docs/versioned_docs/version-3.15/92-development/05-architecture.md b/docs/versioned_docs/version-3.18/92-development/05-architecture.md similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/05-architecture.md rename to docs/versioned_docs/version-3.18/92-development/05-architecture.md diff --git a/docs/versioned_docs/version-3.15/92-development/06-conventions.md b/docs/versioned_docs/version-3.18/92-development/06-conventions.md similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/06-conventions.md rename to docs/versioned_docs/version-3.18/92-development/06-conventions.md diff --git a/docs/versioned_docs/version-3.15/92-development/07-guides.md b/docs/versioned_docs/version-3.18/92-development/07-guides.md similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/07-guides.md rename to docs/versioned_docs/version-3.18/92-development/07-guides.md diff --git a/docs/versioned_docs/version-3.15/92-development/08-translations.md b/docs/versioned_docs/version-3.18/92-development/08-translations.md similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/08-translations.md rename to docs/versioned_docs/version-3.18/92-development/08-translations.md diff --git a/docs/versioned_docs/version-3.15/92-development/09-openapi.md b/docs/versioned_docs/version-3.18/92-development/09-openapi.md similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/09-openapi.md rename to docs/versioned_docs/version-3.18/92-development/09-openapi.md diff --git a/docs/versioned_docs/version-3.15/92-development/09-testing.md b/docs/versioned_docs/version-3.18/92-development/09-testing.md similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/09-testing.md rename to docs/versioned_docs/version-3.18/92-development/09-testing.md diff --git a/docs/versioned_docs/version-3.15/92-development/10-packaging.md b/docs/versioned_docs/version-3.18/92-development/10-packaging.md similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/10-packaging.md rename to docs/versioned_docs/version-3.18/92-development/10-packaging.md diff --git a/docs/versioned_docs/version-3.15/92-development/100-addons.md b/docs/versioned_docs/version-3.18/92-development/100-addons.md similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/100-addons.md rename to docs/versioned_docs/version-3.18/92-development/100-addons.md diff --git a/docs/versioned_docs/version-3.15/92-development/40-deprecations.md b/docs/versioned_docs/version-3.18/92-development/40-deprecations.md similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/40-deprecations.md rename to docs/versioned_docs/version-3.18/92-development/40-deprecations.md diff --git a/docs/versioned_docs/version-3.15/92-development/_category_.yaml b/docs/versioned_docs/version-3.18/92-development/_category_.yaml similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/_category_.yaml rename to docs/versioned_docs/version-3.18/92-development/_category_.yaml diff --git a/docs/versioned_docs/version-3.15/92-development/ui-proxy.svg b/docs/versioned_docs/version-3.18/92-development/ui-proxy.svg similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/ui-proxy.svg rename to docs/versioned_docs/version-3.18/92-development/ui-proxy.svg diff --git a/docs/versioned_docs/version-3.15/92-development/vscode-debug.png b/docs/versioned_docs/version-3.18/92-development/vscode-debug.png similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/vscode-debug.png rename to docs/versioned_docs/version-3.18/92-development/vscode-debug.png diff --git a/docs/versioned_docs/version-3.15/92-development/vscode-run-test.png b/docs/versioned_docs/version-3.18/92-development/vscode-run-test.png similarity index 100% rename from docs/versioned_docs/version-3.15/92-development/vscode-run-test.png rename to docs/versioned_docs/version-3.18/92-development/vscode-run-test.png diff --git a/docs/versioned_docs/version-3.15/92-development/woodpecker-architecture.dot b/docs/versioned_docs/version-3.18/92-development/woodpecker-architecture.dot similarity index 83% rename from docs/versioned_docs/version-3.15/92-development/woodpecker-architecture.dot rename to docs/versioned_docs/version-3.18/92-development/woodpecker-architecture.dot index e72bede01..4ef873a1d 100644 --- a/docs/versioned_docs/version-3.15/92-development/woodpecker-architecture.dot +++ b/docs/versioned_docs/version-3.18/92-development/woodpecker-architecture.dot @@ -81,15 +81,16 @@ digraph WoodpeckerArchitecture { fontcolor="black" style="rounded,filled" - srv_cmd [label="cmd/server/"] - srv_router [label="server/router/"] - srv_api [label="server/api/"] - srv_grpc [label="server/rpc/"] - srv_queue [label="server/queue/"] - srv_pubsub [label="server/pubsub/"] - srv_store [label="server/store/"] - srv_model [label="server/model/"] - srv_forge [label="server/forge/"] + srv_cmd [label="cmd/server/"] + srv_router [label="server/router/"] + srv_api [label="server/api/"] + srv_grpc [label="server/rpc/"] + srv_scheduler [label="server/scheduler/"] + srv_queue [label="server/queue/"] + srv_pubsub [label="server/pubsub/"] + srv_store [label="server/store/"] + srv_model [label="server/model/"] + srv_forge [label="server/forge/"] } /* ===================== Shared Libs ===================== */ @@ -137,13 +138,14 @@ digraph WoodpeckerArchitecture { pipe_core -> pipe_backend /* Server internal flow */ - srv_cmd -> srv_router - srv_router -> srv_api - srv_api -> srv_store - srv_api -> srv_pubsub - srv_api -> srv_queue - srv_grpc -> srv_queue - srv_store -> srv_model + srv_cmd -> srv_router + srv_router -> srv_api + srv_api -> srv_store + srv_api -> srv_scheduler + srv_grpc -> srv_scheduler + srv_scheduler -> srv_queue + srv_scheduler -> srv_pubsub + srv_store -> srv_model /* External integrations */ srv_forge -> ext_scm [xlabel="SCM API"] diff --git a/docs/versioned_docs/version-3.18/92-development/woodpecker-architecture.svg b/docs/versioned_docs/version-3.18/92-development/woodpecker-architecture.svg new file mode 100644 index 000000000..e1ba00037 --- /dev/null +++ b/docs/versioned_docs/version-3.18/92-development/woodpecker-architecture.svg @@ -0,0 +1,364 @@ + + + + + + +WoodpeckerArchitecture + + +cluster_ui + +UI + + +cluster_sdk + +SDK (woodpecker-go) + + +cluster_cli + +woodpecker-cli + + +cluster_agent + +woodpecker-agent + + +cluster_pipelines + +Pipelines + + +cluster_server + +woodpecker-server + + +cluster_shared + +Shared Libs + + +cluster_external + +External Systems + + + +ui_web + +web/ + + + +srv_router + +server/router/ + + + +ui_web->srv_router + + +HTTP + + + +srv_api + +server/api/ + + + +ui_web->srv_api + + +REST API + + + +sdk + +woodpecker-go + + + +sdk->srv_api + + +REST API + + + +cli_cmd + +cmd/cli/ + + + +cli_core + +cli/ + + + +cli_cmd->cli_core + + + + + +cli_core->sdk + + + + + +agent_cmd + +cmd/agent/ + + + +agent_core + +agent/ + + + +agent_cmd->agent_core + + + + + +pipe_backend + +pipeline/backend/ +(exec engines) + + + +agent_core->pipe_backend + + +execute steps + + + +srv_grpc + +server/rpc/ + + + +agent_core->srv_grpc + + +gRPC connect + + + +srv_queue + +server/queue/ + + + +agent_core->srv_queue + + +poll work + + + +pipe_core + +pipeline/ + + + +pipe_core->pipe_backend + + + + + +shared_util + +shared/util/ + + + +pipe_core->shared_util + + + + + +pipe_frontend + +pipeline/frontend/ +(yaml) + + + +pipe_frontend->pipe_core + + + + + +srv_cmd + +cmd/server/ + + + +srv_cmd->srv_router + + + + + +srv_router->srv_api + + + + + +shared_token + +shared/token/ + + + +srv_router->shared_token + + + + + +srv_scheduler + +server/scheduler/ + + + +srv_api->srv_scheduler + + + + + +srv_store + +server/store/ + + + +srv_api->srv_store + + + + + +shared_http + +shared/httputil/ + + + +srv_api->shared_http + + + + + +srv_grpc->srv_scheduler + + + + + +shared_log + +shared/logger/ + + + +srv_grpc->shared_log + + + + + +srv_scheduler->srv_queue + + + + + +srv_pubsub + +server/pubsub/ + + + +srv_scheduler->srv_pubsub + + + + + +srv_model + +server/model/ + + + +srv_store->srv_model + + + + + +ext_db + + +Database + + + +srv_store->ext_db + + +SQL + + + +srv_forge + +server/forge/ + + + +ext_scm + +SCM Providers + + + +srv_forge->ext_scm + + +SCM API + + + diff --git a/docs/versioned_sidebars/version-3.15-sidebars.json b/docs/versioned_sidebars/version-3.18-sidebars.json similarity index 100% rename from docs/versioned_sidebars/version-3.15-sidebars.json rename to docs/versioned_sidebars/version-3.18-sidebars.json diff --git a/docs/versions.json b/docs/versions.json index d3bed3cb5..7aee59a6c 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1 +1 @@ -["3.17", "3.16", "3.15", "2.8"] +["3.18", "3.17", "3.16", "2.8"]