diff --git a/docs/docs/30-administration/00-deployment/00-overview.md b/docs/docs/30-administration/00-deployment/00-overview.md index d69c5c643b..aa330f3e08 100644 --- a/docs/docs/30-administration/00-deployment/00-overview.md +++ b/docs/docs/30-administration/00-deployment/00-overview.md @@ -16,29 +16,7 @@ You can add more agents to increase the number of parallel workflows or set the Woodpecker is having two different kinds of releases: **stable** and **next**. -The **stable** releases are official versions following [semver](https://semver.org/). By default, only the latest stable release will receive bug fixes. Once a new major or minor release is available, previous minor versions might only receive security patches, but wont be updated with bug fixes anymore (so called backporting) by default. - -The **next** release contains all bugfixes and features from `main` branch. Normally it should be pretty stable, but as its frequently updated, it might contain some bugs from time to time. There are no binaries for this version. - -If you want all (new) features of Woodpecker and are willing to accept some possible bugs from time to time, you should use the next release, otherwise use the stable release. - -### Stable releases - -We release a new version every four weeks and will release the current state of the `main` branch. -If there are security fixes or critical bug fixes, we'll release them directly. -There are no backports or similar. - -#### Versioning - -We use [Semantic Versioning](https://semver.org/) to be able, -to communicate when admins have to do manual migration steps and when they can just bump versions up. - -#### Breaking changes - -As of semver guidelines, breaking changes will be released as a major version. We will hold back -breaking changes to not release many majors each containing just a few breaking changes. -Prior to the release of a major version, a release candidate (RC) will be published to allow easy testing, -the actual release will be about a week later. +Find more information about the different versions [here](/versions). ## Hardware Requirements diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 60c375d5cc..5bbb8d6405 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -60,6 +60,12 @@ const config: Config = { { type: 'docsVersionDropdown', position: 'right', + dropdownItemsAfter: [ + { + to: '/versions', + label: 'All versions', + }, + ], }, { href: 'https://github.com/woodpecker-ci/woodpecker', @@ -242,34 +248,22 @@ const config: Config = { process.env.NODE_ENV === 'development' ? ['current', '2.5'] : ['current', '2.5', '2.4', '2.3', '1.0'], versions: { current: { - label: 'Next', + label: 'Next 🚧', banner: 'unreleased', }, '2.5': { label: '2.5.x', }, '2.4': { - label: '2.4.x', + label: '2.4.x 💀', banner: 'unmaintained', }, '2.3': { - label: '2.3.x', - banner: 'unmaintained', - }, - '2.2': { - label: '2.2.x', - banner: 'unmaintained', - }, - '2.1': { - label: '2.1.x', - banner: 'unmaintained', - }, - '2.0': { - label: '2.0.x', + label: '2.3.x 💀', banner: 'unmaintained', }, '1.0': { - label: '1.0.x', + label: '1.0.x 💀', banner: 'unmaintained', }, }, diff --git a/docs/src/pages/versions.md b/docs/src/pages/versions.md new file mode 100644 index 0000000000..98f48f1e8e --- /dev/null +++ b/docs/src/pages/versions.md @@ -0,0 +1,69 @@ +# Versions + +Woodpecker is having two different kinds of releases: **stable** and **next**. + +If you want all (new) features of Woodpecker while supporting us with feedback and are willing to accept some possible bugs from time to time, you should use the next release, otherwise use the stable release. + +We plan to release a new version every four weeks and will release the next version as a stable version. + +## Stable version + +The **stable** releases are official versions following [semver](https://semver.org/). By default, only the latest stable release will receive bug fixes. Once a new major or minor release is available, previous minor versions might receive security patches, but wont be updated with bug fixes anymore (so called backporting) by default. + +### Breaking changes + +As of semver guidelines, breaking changes will be released as a major version. We will hold back +breaking changes to not release many majors each containing just a few breaking changes. +Prior to the release of a major version, a release candidate (RC) will be published to allow easy testing, +the actual release will be about a week later. + +### Deprecations & migrations + +All deprecations and migrations for Woodpecker users and instance admins are documented in the [migration guide](/docs/next/migrations). + +## Next version (current state of the `main` branch) + +The **next** version contains all bugfixes and features from `main` branch. Normally it should be pretty stable, but as its frequently updated, it might contain some bugs from time to time. There are no binaries for this version. + +## Past versions (Not maintained anymore) + +Here you can find documentation for previous versions of Woodpecker. + +[Changelog](https://github.com/woodpecker-ci/woodpecker/blob/main/CHANGELOG.md) + +| | | | +| ------- | ---------- | ------------------------------------------------------------------------------------- | +| 2.4.1 | 2024-03-20 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.4.1/docs/docs/) | +| 2.4.0 | 2024-03-19 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.4.0/docs/docs/) | +| 2.3.0 | 2024-01-31 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.3.0/docs/docs/) | +| 2.2.2 | 2024-01-21 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.2.2/docs/docs/) | +| 2.2.1 | 2024-01-21 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.2.1/docs/docs/) | +| 2.2.0 | 2024-01-21 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.2.0/docs/docs/) | +| 2.1.1 | 2023-12-27 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.1.1/docs/docs/) | +| 2.1.0 | 2023-12-26 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.1.0/docs/docs/) | +| 2.0.0 | 2023-12-23 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.0.0/docs/docs/) | +| 1.0.5 | 2023-11-09 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v1.0.5/docs/docs/) | +| 1.0.4 | 2023-11-05 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v1.0.4/docs/docs/) | +| 1.0.3 | 2023-10-14 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v1.0.3/docs/docs/) | +| 1.0.2 | 2023-08-16 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v1.0.2/docs/docs/) | +| 1.0.1 | 2023-08-08 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v1.0.1/docs/docs/) | +| 1.0.0 | 2023-07-29 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v1.0.0/docs/docs/) | +| 0.15.11 | 2023-07-12 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.15.11/docs/docs/) | +| 0.15.10 | 2023-07-09 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.15.10/docs/docs/) | +| 0.15.9 | 2023-05-11 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.15.9/docs/docs/) | +| 0.15.8 | 2023-04-29 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.15.8/docs/docs/) | +| 0.15.7 | 2023-03-14 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.15.7/docs/docs/) | +| 0.15.6 | 2022-12-23 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.15.6/docs/docs/) | +| 0.15.5 | 2022-10-13 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.15.5/docs/docs/) | +| 0.15.4 | 2022-09-06 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.15.4/docs/docs/) | +| 0.15.3 | 2022-06-16 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.15.3/docs/docs/) | +| 0.15.2 | 2022-06-14 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.15.2/docs/docs/) | +| 0.15.1 | 2022-04-13 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.15.1/docs/docs/) | +| 0.15.0 | 2022-02-24 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.15.0/docs/docs/) | +| 0.14.4 | 2022-01-31 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.14.4/docs/docs/) | +| 0.14.3 | 2021-10-30 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.14.3/docs/docs/) | +| 0.14.2 | 2021-10-19 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.14.2/docs/docs/) | +| 0.14.1 | 2021-09-21 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.14.1/docs/docs/) | +| 0.14.0 | 2021-08-01 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v0.14.0/docs/docs/) | + +If you are using an older version of Woodpecker and would like to view docs for this version, please use GitHub to browse the repository at your tag. diff --git a/docs/versioned_docs/version-2.0/10-intro.md b/docs/versioned_docs/version-2.0/10-intro.md deleted file mode 100644 index cc28b1f86d..0000000000 --- a/docs/versioned_docs/version-2.0/10-intro.md +++ /dev/null @@ -1,94 +0,0 @@ -# Welcome to Woodpecker - -Woodpecker is a simple CI engine with great extensibility. It focuses on executing pipelines inside [containers](https://opencontainers.org/). -If you are already using containers in your daily workflow, you'll for sure love Woodpecker. - -![woodpecker](woodpecker.png) - -## .woodpecker.yml - -- Place your pipeline in a file named `.woodpecker.yml` in your repository -- Pipeline steps can be named as you like -- Run any command in the commands section - -```yaml -# .woodpecker.yml -steps: - build: - image: debian - commands: - - echo "This is the build step" - a-test-step: - image: debian - commands: - - echo "Testing.." -``` - -### Steps are containers - -- Define any container image as context - - either use your own and install the needed tools in a custom image - - or search for available images that are already tailored for your needs in image registries like [Docker Hub](https://hub.docker.com/search?type=image) -- List the commands that should be executed in the container - -```diff -steps: - build: -- image: debian -+ image: mycompany/image-with-awscli - commands: - - aws help -``` - -### File changes are incremental - -- Woodpecker clones the source code in the beginning -- File changes are persisted throughout individual steps as the same volume is being mounted in all steps - -```yaml -# .woodpecker.yml -steps: - build: - image: debian - commands: - - touch myfile - a-test-step: - image: debian - commands: - - cat myfile -``` - -## Plugins are straightforward - -- If you copy the same shell script from project to project -- Pack it into a plugin instead -- And make the yaml declarative -- Plugins are Docker images with your script as an entrypoint - -```Dockerfile -# Dockerfile -FROM laszlocloud/kubectl -COPY deploy /usr/local/deploy -ENTRYPOINT ["/usr/local/deploy"] -``` - -```bash -# deploy -kubectl apply -f $PLUGIN_TEMPLATE -``` - -```yaml -# .woodpecker.yml -steps: - deploy-to-k8s: - image: laszlocloud/my-k8s-plugin - settings: - template: config/k8s/service.yml -``` - -See [plugin docs](./20-usage/51-plugins/10-plugins.md). - -## Continue reading - -- [Create a Woodpecker pipeline for your repository](./20-usage/10-intro.md) -- [Setup your own Woodpecker instance](./30-administration/00-deployment/00-overview.md) diff --git a/docs/versioned_docs/version-2.0/20-usage/10-intro.md b/docs/versioned_docs/version-2.0/20-usage/10-intro.md deleted file mode 100644 index 7893696683..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/10-intro.md +++ /dev/null @@ -1,72 +0,0 @@ -# Getting started - -## Repository Activation - -To activate your project navigate to your account settings. You will see a list of repositories which can be activated with a simple toggle. When you activate your repository, Woodpecker automatically adds webhooks to your forge (e.g. GitHub, Gitea, ...). - -Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your forge will automatically send a webhook to Woodpecker which will in turn trigger the pipeline execution. - -![repository list](repo-list.png) - -## Required Permissions - -The user who enables a repo in Woodpecker must have `Admin` rights on that repo, so that Woodpecker can add the webhook. - -:::note -Note that manually creating webhooks yourself is not possible. -This is because webhooks are signed using a per-repository secret key which is not exposed to end users. -::: - -## Configuration - -To configure your pipeline you must create a `.woodpecker.yml` file in the root of your repository. The `.woodpecker.yml` file is used to define your pipeline steps. - -:::note -We support most of YAML 1.2, but preserve some behavior from 1.1 for backward compatibility. -Read more at: [https://github.com/go-yaml/yaml](https://github.com/go-yaml/yaml/tree/v3) -::: - -Example pipeline configuration: - -```yaml -steps: - build: - image: golang - commands: - - go get - - go build - - go test - -services: - postgres: - image: postgres:9.4.5 - environment: - - POSTGRES_USER=myapp -``` - -Example pipeline configuration with multiple, serial steps: - -```yaml -steps: - backend: - image: golang - commands: - - go get - - go build - - go test - - frontend: - image: node:6 - commands: - - npm install - - npm test - - notify: - image: plugins/slack - channel: developers - username: woodpecker -``` - -## Execution - -To trigger your first pipeline execution you can push code to your repository, open a pull request, or push a tag. Any of these events triggers a webhook from your forge and execute your pipeline. diff --git a/docs/versioned_docs/version-2.0/20-usage/15-terminiology/architecture.excalidraw b/docs/versioned_docs/version-2.0/20-usage/15-terminiology/architecture.excalidraw deleted file mode 100644 index b3eba1aab3..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/15-terminiology/architecture.excalidraw +++ /dev/null @@ -1,1549 +0,0 @@ -{ - "type": "excalidraw", - "version": 2, - "source": "https://excalidraw.com", - "elements": [ - { - "type": "rectangle", - "version": 226, - "versionNonce": 1002880859, - "isDeleted": false, - "id": "UczUX5VuNnCB1rVvUJVfm", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 487.098092529257, - "y": 320.8758615860986, - "strokeColor": "#1971c2", - "backgroundColor": "#e7f5ff", - "width": 472.8823858375721, - "height": 183.19688715994928, - "seed": 917720693, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "Kqbwk_qfkALJfhtCIr2eS", - "type": "arrow" - } - ], - "updated": 1697530113380, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 161, - "versionNonce": 286006267, - "isDeleted": false, - "id": "sKPZmBSWUdAYfBs4ByItH", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 539.5451038202509, - "y": 345.2419383247636, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "width": 82.46875, - "height": 32.199999999999996, - "seed": 1485551573, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113380, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Server", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Server", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "rectangle", - "version": 333, - "versionNonce": 448586907, - "isDeleted": false, - "id": "_A8uznhnpXuQBYzjP-iVx", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 649.8080506852966, - "y": 427.60908869342575, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 136, - "height": 60, - "seed": 1783625013, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "r90dckf8trHemYzEwCgCW" - }, - { - "id": "XxfJWnHonmvNOJzMFSlie", - "type": "arrow" - } - ], - "updated": 1697530113380, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 298, - "versionNonce": 1244067771, - "isDeleted": false, - "id": "r90dckf8trHemYzEwCgCW", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 703.8080506852966, - "y": 441.5090886934257, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 28, - "height": 32.199999999999996, - "seed": 660965013, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113383, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "UI", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "_A8uznhnpXuQBYzjP-iVx", - "originalText": "UI", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "rectangle", - "version": 105, - "versionNonce": 265992667, - "isDeleted": false, - "id": "v2eEwSOSRQBZ79O6wyzGf", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 800.9240766836483, - "y": 421.4987043996123, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 135.3671503686619, - "height": 62.2689029398432, - "seed": 1115810805, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "svsVhxCbatcLj7lQLch0P" - }, - { - "id": "TvtonmlV0W8__pnTG-wVZ", - "type": "arrow" - }, - { - "id": "5tl702dfcvJDLz9aIFU0P", - "type": "arrow" - } - ], - "updated": 1697530113380, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 83, - "versionNonce": 1706870395, - "isDeleted": false, - "id": "svsVhxCbatcLj7lQLch0P", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 828.1594096804793, - "y": 436.53315586953386, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 80.896484375, - "height": 32.199999999999996, - "seed": 2074781013, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113380, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "GRPC", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "v2eEwSOSRQBZ79O6wyzGf", - "originalText": "GRPC", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "rectangle", - "version": 270, - "versionNonce": 418660123, - "isDeleted": false, - "id": "hSrrwwnm9y7R-_CnJtaK1", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1065.567103519039, - "y": 556.4146894573112, - "strokeColor": "#2f9e44", - "backgroundColor": "#ebfbee", - "width": 601.932705468054, - "height": 175.07489600604117, - "seed": 1983197877, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "TvtonmlV0W8__pnTG-wVZ", - "type": "arrow" - } - ], - "updated": 1697530113380, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 154, - "versionNonce": 871605179, - "isDeleted": false, - "id": "8tsYgVssKnBd_Zw1QuqNz", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1298.4367898442752, - "y": 566.567242947784, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 96.5234375, - "height": 32.199999999999996, - "seed": 1321669653, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Agent 1", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Agent 1", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "text", - "version": 182, - "versionNonce": 1323136091, - "isDeleted": false, - "id": "eeugZg73_yD_6uLBBgmcX", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 404.5001910129067, - "y": 707.1233710221009, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 210.068359375, - "height": 32.199999999999996, - "seed": 1901447541, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "User => Browser", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "User => Browser", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "ellipse", - "version": 106, - "versionNonce": 1501835515, - "isDeleted": false, - "id": "mlDhl4OOc-H1tNgh77AAW", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 482.5857164810477, - "y": 602.4394551739279, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 46.024748503793035, - "height": 44.21988070606176, - "seed": 791073493, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "line", - "version": 166, - "versionNonce": 627726747, - "isDeleted": false, - "id": "ADEXzdYAhvj-_wVRftTIg", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 459.12202200277807, - "y": 697.1964604319912, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 80.31792517362464, - "height": 31.585599568061298, - "seed": 349155381, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": null, - "endBinding": null, - "lastCommittedPoint": null, - "startArrowhead": null, - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 42.415150610916044, - -28.87829787146393 - ], - [ - 80.31792517362464, - 2.7073016965973693 - ] - ] - }, - { - "type": "rectangle", - "version": 231, - "versionNonce": 801271355, - "isDeleted": false, - "id": "xmz4J-rxLIjfUQ4q19PjD", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 516.8788931508789, - "y": 870.4664542146543, - "strokeColor": "#f08c00", - "backgroundColor": "#fff4e6", - "width": 385.34512717560705, - "height": 60.464035142111264, - "seed": 3531157, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "05EJzh4NLXxemaKAmdi5n", - "type": "arrow" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 93, - "versionNonce": 728690395, - "isDeleted": false, - "id": "gSbpry_947XArfI7b6AAL", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 636.1468430141358, - "y": 878.5884970070326, - "strokeColor": "#f08c00", - "backgroundColor": "transparent", - "width": 132.2890625, - "height": 32.199999999999996, - "seed": 1989076725, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Autoscaler", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Autoscaler", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "text", - "version": 118, - "versionNonce": 1258445691, - "isDeleted": false, - "id": "WVy0mdTGbUx08RuxdQUH8", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 523.3741602213286, - "y": 907.372811672524, - "strokeColor": "#f08c00", - "backgroundColor": "transparent", - "width": 369.1484375, - "height": 18.4, - "seed": 979386453, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "Starts agents based on amount of pending pipelines", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Starts agents based on amount of pending pipelines", - "lineHeight": 1.15, - "baseline": 14 - }, - { - "type": "text", - "version": 373, - "versionNonce": 1254044699, - "isDeleted": false, - "id": "0Y1RcqzVFBFqh-wy-APMI", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1232.1955835481922, - "y": 605.8737363119278, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 292.6171875, - "height": 18.4, - "seed": 561999285, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "Executes pending workflows of a pipeline", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Executes pending workflows of a pipeline", - "lineHeight": 1.15, - "baseline": 14 - }, - { - "type": "text", - "version": 630, - "versionNonce": 983038139, - "isDeleted": false, - "id": "lGumbhMs3xx1vU2632hli", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 505.62283787078286, - "y": 383.42044095379515, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "width": 158.015625, - "height": 36.8, - "seed": 722595605, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "Central unit of a \nWoodpecker instance ", - "textAlign": "center", - "verticalAlign": "top", - "containerId": null, - "originalText": "Central unit of a \nWoodpecker instance ", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "rectangle", - "version": 131, - "versionNonce": 137308507, - "isDeleted": false, - "id": "PbSQXehWVLYcQGXYFpd-B", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 971.7123256059622, - "y": 171.06951064323448, - "strokeColor": "#be4bdb", - "backgroundColor": "#f8f0fc", - "width": 274.3443117379593, - "height": 74.90311522655017, - "seed": 1435321461, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "Kqbwk_qfkALJfhtCIr2eS", - "type": "arrow" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 96, - "versionNonce": 1222067707, - "isDeleted": false, - "id": "2P2tz29C_2sUzVNSpaG17", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1065.5206131439782, - "y": 183.12082907329545, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 73.14453125, - "height": 32.199999999999996, - "seed": 884403669, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Forge", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Forge", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "text", - "version": 141, - "versionNonce": 1133694619, - "isDeleted": false, - "id": "0eYhFYPuRanZ7wkR2OlHO", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 986.864582863368, - "y": 225.1223531590797, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 247.234375, - "height": 18.4, - "seed": 1201957685, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "HK1jmIcPmM6Us6Jrynobb", - "type": "arrow" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "Github, Gitea, Github, Bitbucket, ...", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Github, Gitea, Github, Bitbucket, ...", - "lineHeight": 1.15, - "baseline": 14 - }, - { - "type": "rectangle", - "version": 55, - "versionNonce": 991183675, - "isDeleted": false, - "id": "dihpRzuIc-UoRSsOI33SZ", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 820.419424341303, - "y": 340.29123237109366, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 117, - "height": 60, - "seed": 247151765, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "bcUL-u4zkLA9CLG2YdaeN" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 38, - "versionNonce": 2008949723, - "isDeleted": false, - "id": "bcUL-u4zkLA9CLG2YdaeN", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 831.853994653803, - "y": 358.79123237109366, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 94.130859375, - "height": 23, - "seed": 1638982133, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Webhooks", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "dihpRzuIc-UoRSsOI33SZ", - "originalText": "Webhooks", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 93, - "versionNonce": 295891067, - "isDeleted": false, - "id": "Bphhue86mMXHN4klGamM3", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 697.3018309300141, - "y": 339.607928999312, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 117, - "height": 60, - "seed": 92986197, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "0YxY2hEPyDWFqR8_-f6bn" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 87, - "versionNonce": 2055547163, - "isDeleted": false, - "id": "0YxY2hEPyDWFqR8_-f6bn", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 727.4522215550141, - "y": 358.107928999312, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 56.69921875, - "height": 23, - "seed": 43952309, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "OAuth", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "Bphhue86mMXHN4klGamM3", - "originalText": "OAuth", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "arrow", - "version": 284, - "versionNonce": 1205292475, - "isDeleted": false, - "id": "HK1jmIcPmM6Us6Jrynobb", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1205.6453201409104, - "y": 250.4849674923464, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 272.1094712799886, - "height": 94.31865813977868, - "seed": 982632981, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "uDIWJ5K5mEBL9QaiNk3cS" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": { - "elementId": "0eYhFYPuRanZ7wkR2OlHO", - "focus": -0.8418551162334328, - "gap": 6.962614333266799 - }, - "endBinding": null, - "lastCommittedPoint": null, - "startArrowhead": null, - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - -69.68740859223726, - 65.87860410965993 - ], - [ - -272.1094712799886, - 94.31865813977868 - ] - ] - }, - { - "type": "text", - "version": 53, - "versionNonce": 1803962459, - "isDeleted": false, - "id": "uDIWJ5K5mEBL9QaiNk3cS", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1050.575099048673, - "y": 297.96357160200637, - "strokeColor": "#be4bdb", - "backgroundColor": "#b2f2bb", - "width": 170.765625, - "height": 36.8, - "seed": 1046069109, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113385, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "sends events like push, \ntag, ...", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "HK1jmIcPmM6Us6Jrynobb", - "originalText": "sends events like push, tag, ...", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "arrow", - "version": 487, - "versionNonce": 335895291, - "isDeleted": false, - "id": "Kqbwk_qfkALJfhtCIr2eS", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 792.0835609101814, - "y": 316.38601649373913, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 176.92139414789008, - "height": 122.73778943055902, - "seed": 1681656021, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "yvJTQ64RU50N6-hxEQlkl" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": { - "elementId": "UczUX5VuNnCB1rVvUJVfm", - "focus": -0.03867359238356983, - "gap": 4.489845092359474 - }, - "endBinding": { - "elementId": "PbSQXehWVLYcQGXYFpd-B", - "focus": 0.7798878042817562, - "gap": 2.707370547890605 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 60.422360349016344, - -71.97786730696657 - ], - [ - 176.92139414789008, - -122.73778943055902 - ] - ] - }, - { - "type": "text", - "version": 62, - "versionNonce": 301106427, - "isDeleted": false, - "id": "yvJTQ64RU50N6-hxEQlkl", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 773.7910775091977, - "y": 226.00814918677256, - "strokeColor": "#be4bdb", - "backgroundColor": "#b2f2bb", - "width": 157.4296875, - "height": 36.8, - "seed": 500049461, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113385, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "allows users to login \nusing existing account", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "Kqbwk_qfkALJfhtCIr2eS", - "originalText": "allows users to login using existing account", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "arrow", - "version": 393, - "versionNonce": 598459861, - "isDeleted": false, - "id": "TvtonmlV0W8__pnTG-wVZ", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 936.9267543177084, - "y": 458.95033086418084, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 215.17788326846676, - "height": 93.99151368376693, - "seed": 234198933, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "rFf6NIofw6UBOyAFwg0Kn" - } - ], - "updated": 1697530127259, - "link": null, - "locked": false, - "startBinding": { - "elementId": "v2eEwSOSRQBZ79O6wyzGf", - "focus": -0.30339107267010673, - "gap": 1 - }, - "endBinding": { - "elementId": "hSrrwwnm9y7R-_CnJtaK1", - "focus": -0.14057158065513534, - "gap": 3.4728449093634026 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 130.0760301643047, - 42.90930518030268 - ], - [ - 215.17788326846676, - 93.99151368376693 - ] - ] - }, - { - "type": "text", - "version": 8, - "versionNonce": 1693330843, - "isDeleted": false, - "id": "rFf6NIofw6UBOyAFwg0Kn", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 997.4942845557462, - "y": 473.9409015069133, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 161.4140625, - "height": 36.8, - "seed": 1592253685, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113386, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "receives workflows & \nreturns logs + statuses", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "TvtonmlV0W8__pnTG-wVZ", - "originalText": "receives workflows & returns logs + statuses", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "arrow", - "version": 270, - "versionNonce": 1855882619, - "isDeleted": false, - "id": "5tl702dfcvJDLz9aIFU0P", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 886.0581619083632, - "y": 485.67004123832135, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 174.09447592006472, - "height": 326.4905563076211, - "seed": 1479177813, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "apyMCAv2GIN_yzHXwX4tY" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": { - "elementId": "v2eEwSOSRQBZ79O6wyzGf", - "focus": -0.1341191028023529, - "gap": 1.9024338988657519 - }, - "endBinding": { - "elementId": "pxF49EKDNO6IZq_34i7bY", - "focus": -0.7088661407505865, - "gap": 4.060573862784622 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 44.14165353942735, - 196.18483635907205 - ], - [ - 174.09447592006472, - 326.4905563076211 - ] - ] - }, - { - "type": "text", - "version": 66, - "versionNonce": 2007745083, - "isDeleted": false, - "id": "apyMCAv2GIN_yzHXwX4tY", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 849.4927841977906, - "y": 663.4548775973934, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 161.4140625, - "height": 36.8, - "seed": 882041781, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113386, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "receives workflows & \nreturns logs + statuses", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "5tl702dfcvJDLz9aIFU0P", - "originalText": "receives workflows & returns logs + statuses", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "arrow", - "version": 347, - "versionNonce": 1353818811, - "isDeleted": false, - "id": "XxfJWnHonmvNOJzMFSlie", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 534.9278465333664, - "y": 595.2199151317081, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 113.88020415193023, - "height": 119.81968366814112, - "seed": 944153877, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": null, - "endBinding": { - "elementId": "_A8uznhnpXuQBYzjP-iVx", - "focus": 0.5397285671082249, - "gap": 1 - }, - "lastCommittedPoint": null, - "startArrowhead": null, - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 113.88020415193023, - -119.81968366814112 - ] - ] - }, - { - "type": "rectangle", - "version": 61, - "versionNonce": 1099141979, - "isDeleted": false, - "id": "j56ZKRwmXk72nHrZzLz_1", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1081.8110514012087, - "y": 652.5253283508498, - "strokeColor": "#2f9e44", - "backgroundColor": "#ebfbee", - "width": 566.7373014532342, - "height": 68.58600908319681, - "seed": 112933493, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 82, - "versionNonce": 1879994363, - "isDeleted": false, - "id": "cAVYXfBRnfuGAv7QTQVow", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1300.6584159706863, - "y": 658.8425033454967, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 77.83203125, - "height": 23, - "seed": 951460821, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Backend", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Backend", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "text", - "version": 376,- add some images explaining the architecture & terminology with -pipeline -> workflow -> step -- combine advanced config usage -- rename pipeline syntax to workflow syntax (and most references to -pipeline steps etc as well) -- update agent registration part -- add bug note to secrets encryption setting -- remove usage from readme to point to up-to-date docs page -- typos -- closes #1408 - ---------- - "angle": 0, - "x": 1094.1972977313717, - "y": 681.8988272758752, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 530.9453125, - "height": 55.199999999999996, - "seed": 843899189, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "The backend is the environment (exp. Docker / Kubernetes / local) used to \nexecute workflows in.\n", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "The backend is the environment (exp. Docker / Kubernetes / local) used to \nexecute workflows in.\n", - "lineHeight": 1.15, - "baseline": 50 - }, - { - "type": "rectangle", - "version": 384, - "versionNonce": 1778969915, - "isDeleted": false, - "id": "pxF49EKDNO6IZq_34i7bY", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1064.2132116912126, - "y": 754.5018564383092, - "strokeColor": "#2f9e44", - "backgroundColor": "#ebfbee", - "width": 601.932705468054, - "height": 175.07489600604117, - "seed": 954528405, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "05EJzh4NLXxemaKAmdi5n", - "type": "arrow" - }, - { - "id": "5tl702dfcvJDLz9aIFU0P", - "type": "arrow" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "arrow", - "version": 154, - "versionNonce": 1988988379, - "isDeleted": false, - "id": "05EJzh4NLXxemaKAmdi5n", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 904.0288881242177, - "y": 882.4966027880746, - "strokeColor": "#f08c00", - "backgroundColor": "transparent", - "width": 158.83070714434325, - "height": 32.735025983189644, - "seed": 1228134389, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "yNxAOEPZu_Jl7mnI01OXs" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": { - "elementId": "xmz4J-rxLIjfUQ4q19PjD", - "gap": 1.8048677977312764, - "focus": 0.31250963573550006 - }, - "endBinding": { - "elementId": "pxF49EKDNO6IZq_34i7bY", - "gap": 1.353616422651612, - "focus": 0.36496042109885213 - }, - "lastCommittedPoint": null, - "startArrowhead": null, - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 158.83070714434325, - -32.735025983189644 - ] - ] - }, - { - "type": "text", - "version": 25, - "versionNonce": 1393410779, - "isDeleted": false, - "id": "yNxAOEPZu_Jl7mnI01OXs", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 963.8856479463893, - "y": 856.9290897964797, - "strokeColor": "#f08c00", - "backgroundColor": "#b2f2bb", - "width": 39.1171875, - "height": 18.4, - "seed": 759107925, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113387, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "starts", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "05EJzh4NLXxemaKAmdi5n", - "originalText": "starts", - "lineHeight": 1.15, - "baseline": 14 - }, - { - "type": "text", - "version": 187, - "versionNonce": 671224603, - "isDeleted": false, - "id": "sSj4Pda-fo-BBYM_dzml6", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1296.0854928322988, - "y": 776.6118140041631, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 104.2890625, - "height": 32.199999999999996, - "seed": 1381768885, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Agent ...", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Agent ...", - "lineHeight": 1.15, - "baseline": 25 - } - ], - "appState": { - "gridSize": null, - "viewBackgroundColor": "#ffffff" - }, - "files": {} -} diff --git a/docs/versioned_docs/version-2.0/20-usage/15-terminiology/architecture.svg b/docs/versioned_docs/version-2.0/20-usage/15-terminiology/architecture.svg deleted file mode 100644 index b34e96fdd8..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/15-terminiology/architecture.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - - - - - ServerUIGRPCAgent 1User => BrowserAutoscalerStarts agents based on amount of pending pipelinesExecutes pending workflows of a pipelineCentral unit of a Woodpecker instance ForgeGithub, Gitea, Github, Bitbucket, ...WebhooksOAuthsends events like push, tag, ...allows users to login using existing accountreceives workflows & returns logs + statusesreceives workflows & returns logs + statusesBackendThe backend is the environment (exp. Docker / Kubernetes / local) used to execute workflows in.startsAgent ... diff --git a/docs/versioned_docs/version-2.0/20-usage/15-terminiology/index.md b/docs/versioned_docs/version-2.0/20-usage/15-terminiology/index.md deleted file mode 100644 index 4640ede350..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/15-terminiology/index.md +++ /dev/null @@ -1,52 +0,0 @@ -# Terminology - -## Woodpecker architecture - -![Woodpecker architecture](architecture.svg) - -## Pipeline, workflow & step - -![Relation between pipelines, workflows and steps](pipeline-workflow-step.svg) - -## Glossary - -- **Woodpecker CI**: The project name around Woodpecker. -- **Woodpecker**: An open-source tool that executes [pipelines][Pipeline] on your code. -- **Server**: The component of Woodpecker that handles webhooks from forges, orchestrates agents, and sends status back. It also serves the API and web UI for administration and configuration. -- **Agent**: A component of Woodpecker that executes [pipelines][Pipeline] (specifically one or more [workflows][Workflow]) with a specific backend (e.g. [Docker][], Kubernetes, [local][Local]). It connects to the server via GRPC. -- **CLI**: The Woodpecker command-line interface (CLI) is a terminal tool used to administer the server, to execute pipelines locally for debugging / testing purposes, and to perform tasks like linting pipelines. -- **Pipeline**: A sequence of [workflows][Workflow] that are executed on the code. [Pipelines][Pipeline] are triggered by events. -- **Workflow**: A sequence of steps and services that are executed as part of a [pipeline][Pipeline]. Workflows are represented by YAML files. Each [workflow][Workflow] has its own isolated [workspace][Workspace], and often additional resources like a shared network (docker). -- **Steps**: Individual commands, actions or tasks within a [workflow][Workflow]. -- **Code**: Refers to the files tracked by the version control system used by the [forge][Forge]. -- **Repos**: Short for repositories, these are storage locations where code is stored. -- **Forge**: The hosting platform or service where the repositories are hosted. -- **Workspace**: A folder shared between all steps of a [workflow][Workflow] containing the repository and all the generated data from previous steps. -- **Event**: Triggers the execution of a [pipeline][Pipeline], such as a [forge][Forge] event like `push`, or `manual` triggered manually from the UI. -- **Commit**: A defined state of the code, usually associated with a version control system like Git. -- **Matrix**: A configuration option that allows the execution of [workflows][Workflow] for each value in the [matrix][Matrix]. -- **Service**: A service is a step that is executed from the start of a [workflow][Workflow] until its end. It can be accessed by name via the network from other steps within the same [workflow][Workflow]. -- **Plugins**: [Plugins][Plugin] are extensions that provide pre-defined actions or commands for a step in a [workflow][Workflow]. They can be configured via settings. -- **Container**: A lightweight and isolated environment where commands are executed. -- **YAML File**: A file format used to define and configure [workflows][Workflow]. -- **Dependency**: [Workflows][Workflow] can depend on each other, and if possible, they are executed in parallel. -- **Status**: Status refers to the outcome of a step or [workflow][Workflow] after it has been executed, determined by the internal command exit code. At the end of a [workflow][Workflow], its status is sent to the [forge][Forge]. - -## Conventions - -Sometimes there are multiple terms that can be used to describe something. This section lists the preferred terms to use in Woodpecker: - -- Environment variables `*_LINK` should be called `*_URL`. In the code use `URL()` instead of `Link()` -- Use the term **pipelines** instead of the previous **builds** -- Use the term **steps** instead of the previous **jobs** - - - -[Pipeline]: ../20-workflow-syntax.md -[Workflow]: ../25-workflows.md -[Forge]: ../../30-administration/11-forges/10-overview.md -[Plugin]: ../51-plugins/10-plugins.md -[Workspace]: ../20-workflow-syntax.md#workspace -[Matrix]: ../30-matrix-workflows.md -[Docker]: ../../30-administration/22-backends/10-docker.md -[Local]: ../../30-administration/22-backends/20-local.md diff --git a/docs/versioned_docs/version-2.0/20-usage/15-terminiology/pipeline-workflow-step.excalidraw b/docs/versioned_docs/version-2.0/20-usage/15-terminiology/pipeline-workflow-step.excalidraw deleted file mode 100644 index 28704cff54..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/15-terminiology/pipeline-workflow-step.excalidraw +++ /dev/null @@ -1,1077 +0,0 @@ -{ - "type": "excalidraw", - "version": 2, - "source": "https://excalidraw.com", - "elements": [ - { - "type": "rectangle", - "version": 97, - "versionNonce": 257762037, - "isDeleted": false, - "id": "Y3hYdpX9r1qWfyHWs7AXT", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 393.622323134362, - "y": 336.02197155458475, - "strokeColor": "#1971c2", - "backgroundColor": "#e7f5ff", - "width": 366.3936710429598, - "height": 499.95605689083004, - "seed": 875444373, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 67, - "versionNonce": 369556565, - "isDeleted": false, - "id": "g1Eb010Kx_KFryVqNYWBQ", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 520.0116988873679, - "y": 363.32095846456355, - "strokeColor": "#1971c2", - "backgroundColor": "#b2f2bb", - "width": 99.626953125, - "height": 32.199999999999996, - "seed": 1466195445, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "9laL3864YWOna6NQlVDqq", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Pipeline", - "textAlign": "center", - "verticalAlign": "top", - "containerId": null, - "originalText": "Pipeline", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "rectangle", - "version": 314, - "versionNonce": 1983028731, - "isDeleted": false, - "id": "9o-DNP0YdlIGVz1kEm_hW", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 407.1590381712276, - "y": 410.9252244837219, - "strokeColor": "#be4bdb", - "backgroundColor": "#f8f0fc", - "width": 340.12211164367193, - "height": 199, - "seed": 1869535061, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "FU4jk6Tz6duLaaZE0Z55A", - "type": "arrow" - }, - { - "id": "9laL3864YWOna6NQlVDqq", - "type": "arrow" - } - ], - "updated": 1697530083624, - "link": null, - "locked": false - }, - { - "type": "rectangle", - "version": 156, - "versionNonce": 1495247317, - "isDeleted": false, - "id": "q4TKpiq2KAwPaz19GdhtK", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 490.3194993196821, - "y": 473.52959018719525, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 111355061, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "ya0JzDo-4oscHIq87TZ_D" - }, - { - "id": "1ZbDRqbETCkEx62nCmnpJ", - "type": "arrow" - }, - { - "id": "FU4jk6Tz6duLaaZE0Z55A", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 156, - "versionNonce": 1469425461, - "isDeleted": false, - "id": "ya0JzDo-4oscHIq87TZ_D", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 566.0118821321821, - "y": 478.52959018719525, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 95.615234375, - "height": 23, - "seed": 1084671509, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Clone step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "q4TKpiq2KAwPaz19GdhtK", - "originalText": "Clone step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 236, - "versionNonce": 1535319541, - "isDeleted": false, - "id": "AOJLQFldoHd2vxVtB2jrS", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 491.2218643672577, - "y": 519.7800332298218, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 812596085, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "FRby8A9aUiKvHpM5mCdDN" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 231, - "versionNonce": 28677973, - "isDeleted": false, - "id": "FRby8A9aUiKvHpM5mCdDN", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 583.0324112422577, - "y": 524.7800332298218, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 63.37890625, - "height": 23, - "seed": 1849820373, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "1. Step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "AOJLQFldoHd2vxVtB2jrS", - "originalText": "1. Step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 291, - "versionNonce": 571598005, - "isDeleted": false, - "id": "2WwuMWX7YawqK0i1rDPJo", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 489.6426911083554, - "y": 567.609787233933, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 1840554549, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "UOwxmKIS0W62CFt_ffEy4" - }, - { - "id": "379hO6Dc5rygB38JgDbVo", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 289, - "versionNonce": 4032021, - "isDeleted": false, - "id": "UOwxmKIS0W62CFt_ffEy4", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 581.4532379833554, - "y": 572.609787233933, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 63.37890625, - "height": 23, - "seed": 330077077, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "2. Step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "2WwuMWX7YawqK0i1rDPJo", - "originalText": "2. Step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "arrow", - "version": 296, - "versionNonce": 1539516059, - "isDeleted": false, - "id": "9laL3864YWOna6NQlVDqq", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 630.0635849044402, - "y": 383.14314287821776, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "width": 294.3024370154917, - "height": 36.656016722015465, - "seed": 207575285, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": { - "elementId": "9o-DNP0YdlIGVz1kEm_hW", - "focus": -1.000156025347643, - "gap": 27.782081605504118 - }, - "endBinding": { - "elementId": "vS2PNUbmeBe3EPxl-dID8", - "focus": 0.7761987167055517, - "gap": 8.978940924346716 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 294.3024370154917, - -36.656016722015465 - ] - ] - }, - { - "type": "text", - "version": 249, - "versionNonce": 2076402229, - "isDeleted": false, - "id": "vS2PNUbmeBe3EPxl-dID8", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 933.3449628442786, - "y": 336.02200598023114, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "width": 301.298828125, - "height": 46, - "seed": 1632793173, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "9laL3864YWOna6NQlVDqq", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "A pipeline is triggered by an event\nlike a push, tag, manual", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "A pipeline is triggered by an event\nlike a push, tag, manual", - "lineHeight": 1.15, - "baseline": 41 - }, - { - "type": "arrow", - "version": 751, - "versionNonce": 1371044827, - "isDeleted": false, - "id": "FU4jk6Tz6duLaaZE0Z55A", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 751.1619011845514, - "y": 440.8355079324799, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 160.46519124360202, - "height": 2.2452348338335923, - "seed": 1331388341, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": { - "elementId": "9o-DNP0YdlIGVz1kEm_hW", - "focus": -0.6591700594229558, - "gap": 3.8807513696519322 - }, - "endBinding": { - "elementId": "wfFvnFZuh0npL9hh0ez7o", - "focus": 0.7652411053273549, - "gap": 20.75618622779257 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 160.46519124360202, - -2.2452348338335923 - ] - ] - }, - { - "type": "rectangle", - "version": 440, - "versionNonce": 819540565, - "isDeleted": false, - "id": "TbejdIYo_qNDw15yLP2IB", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 406.0812257713851, - "y": 626.8305540252475, - "strokeColor": "#be4bdb", - "backgroundColor": "#f8f0fc", - "width": 340.12211164367193, - "height": 199, - "seed": 1553965333, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 466, - "versionNonce": 663477, - "isDeleted": false, - "id": "wfFvnFZuh0npL9hh0ez7o", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 932.383278655946, - "y": 424.0107569968011, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 481.2890625, - "height": 115, - "seed": 781497973, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "FU4jk6Tz6duLaaZE0Z55A", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Every pipeline consists of multiple workflows.\nEach defined by a separate YAML file and is named \nafter the filename.\nEach workflow has its own workspace (folder) which is\nused by all steps of that workflow.", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "Every pipeline consists of multiple workflows.\nEach defined by a separate YAML file and is named \nafter the filename.\nEach workflow has its own workspace (folder) which is\nused by all steps of that workflow.", - "lineHeight": 1.15, - "baseline": 110 - }, - { - "type": "arrow", - "version": 464, - "versionNonce": 734626075, - "isDeleted": false, - "id": "1ZbDRqbETCkEx62nCmnpJ", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 741.0645380446722, - "y": 492.31283255558515, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 178.4459423531871, - "height": 83.08707392565111, - "seed": 536879061, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": { - "elementId": "q4TKpiq2KAwPaz19GdhtK", - "focus": -0.7697471991854113, - "gap": 3.7450387249900814 - }, - "endBinding": { - "elementId": "Vu0JJ6ZWuEhEyCfxeHPtc", - "focus": -0.7822252364700005, - "gap": 8.360835317635974 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 178.4459423531871, - 83.08707392565111 - ] - ] - }, - { - "type": "text", - "version": 327, - "versionNonce": 371646421, - "isDeleted": false, - "id": "Vu0JJ6ZWuEhEyCfxeHPtc", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 927.8713157154953, - "y": 563.2132686484658, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 491.357421875, - "height": 46, - "seed": 385310005, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "1ZbDRqbETCkEx62nCmnpJ", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "The default first step of each workflow is the clone step.\nIts fetches the specific code version for a pipeline.", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "The default first step of each workflow is the clone step.\nIts fetches the specific code version for a pipeline.", - "lineHeight": 1.15, - "baseline": 41 - }, - { - "type": "text", - "version": 91, - "versionNonce": 1180085909, - "isDeleted": false, - "id": "0tGx2VdJLNf7W6HD76dtO", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 427.6895298601876, - "y": 432.3583566254258, - "strokeColor": "#9c36b5", - "backgroundColor": "#a5d8ff", - "width": 143.876953125, - "height": 23, - "seed": 450883221, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Workflow \"build\"", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "Workflow \"build\"", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 338, - "versionNonce": 957223925, - "isDeleted": false, - "id": "LQ2h2aO9uzDWyLG6OLn70", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 487.7251825950889, - "y": 685.3516128043414, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 711939061, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "8EqaPnZX2CgLaF08UNZZg" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 340, - "versionNonce": 510774613, - "isDeleted": false, - "id": "8EqaPnZX2CgLaF08UNZZg", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 563.4175654075889, - "y": 690.3516128043414, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 95.615234375, - "height": 23, - "seed": 1370164565, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Clone step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "LQ2h2aO9uzDWyLG6OLn70", - "originalText": "Clone step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 421, - "versionNonce": 97999541, - "isDeleted": false, - "id": "St9t4nwHuXXVlmjDqfn_Z", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 488.62754764266447, - "y": 731.6020558469675, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 2145950389, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "DX10t075MMDu7BLtuUaij" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 417, - "versionNonce": 2011446293, - "isDeleted": false, - "id": "DX10t075MMDu7BLtuUaij", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 580.4380945176645, - "y": 736.6020558469675, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 63.37890625, - "height": 23, - "seed": 500005909, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "1. Step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "St9t4nwHuXXVlmjDqfn_Z", - "originalText": "1. Step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 475, - "versionNonce": 1284370805, - "isDeleted": false, - "id": "XVGBz_X5yN6xjWTosVH2n", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 487.04837438376217, - "y": 779.4318098510787, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 1666134389, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "-xogFSFcP-Vv5cuOSFm8T" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 476, - "versionNonce": 1092221653, - "isDeleted": false, - "id": "-xogFSFcP-Vv5cuOSFm8T", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 578.8589212587622, - "y": 784.4318098510787, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 63.37890625, - "height": 23, - "seed": 1840462549, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "2. Step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "XVGBz_X5yN6xjWTosVH2n", - "originalText": "2. Step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "text", - "version": 125, - "versionNonce": 1310578741, - "isDeleted": false, - "id": "N1a9yL7Pts16hUKY9-vhw", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 424.78852030984035, - "y": 646.2446482189896, - "strokeColor": "#be4bdb", - "backgroundColor": "#a5d8ff", - "width": 133.857421875, - "height": 23, - "seed": 361699381, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Workflow \"test\"", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "Workflow \"test\"", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "arrow", - "version": 184, - "versionNonce": 2127603131, - "isDeleted": false, - "id": "O-YmtRLb8uFNqCAz22EoG", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 737.454940151797, - "y": 535.9141784615474, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 190.41665096887027, - "height": 112.96427727851824, - "seed": 80234901, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": null, - "endBinding": { - "elementId": "0TjxOfERekC91N3yciQIq", - "focus": -0.8392895251910331, - "gap": 2.0300115262207328 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 190.41665096887027, - 112.96427727851824 - ] - ] - }, - { - "type": "arrow", - "version": 327, - "versionNonce": 780710651, - "isDeleted": false, - "id": "379hO6Dc5rygB38JgDbVo", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 738.8084877231549, - "y": 591.3526691276127, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 186.8066399682357, - "height": 57.68023784868956, - "seed": 211046133, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": { - "elementId": "2WwuMWX7YawqK0i1rDPJo", - "focus": -0.5776522830934517, - "gap": 2.1657966147995467 - }, - "endBinding": { - "elementId": "0TjxOfERekC91N3yciQIq", - "focus": -0.7269489945238884, - "gap": 4.286474955497397 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 186.8066399682357, - 57.68023784868956 - ] - ] - }, - { - "type": "text", - "version": 285, - "versionNonce": 1165977685, - "isDeleted": false, - "id": "0TjxOfERekC91N3yciQIq", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 929.901602646888, - "y": 632.4760859429873, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 518.076171875, - "height": 46, - "seed": 997763157, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "O-YmtRLb8uFNqCAz22EoG", - "type": "arrow" - }, - { - "id": "379hO6Dc5rygB38JgDbVo", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Additional steps are used to execute commands or plugins\nlike `make install` or release-to-github", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "Additional steps are used to execute commands or plugins\nlike `make install` or release-to-github", - "lineHeight": 1.15, - "baseline": 41 - } - ], - "appState": { - "gridSize": null, - "viewBackgroundColor": "#ffffff" - }, - "files": {} -} diff --git a/docs/versioned_docs/version-2.0/20-usage/15-terminiology/pipeline-workflow-step.svg b/docs/versioned_docs/version-2.0/20-usage/15-terminiology/pipeline-workflow-step.svg deleted file mode 100644 index 4ea3aab0ac..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/15-terminiology/pipeline-workflow-step.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - - - - - PipelineClone step1. Step2. StepA pipeline is triggered by an eventlike a push, tag, manualEvery pipeline consists of multiple workflows.Each defined by a separate YAML file and is named after the filename.Each workflow has its own workspace (folder) which isused by all steps of that workflow.The default first step of each workflow is the clone step.Its fetches the specific code version for a pipeline.Workflow "build"Clone step1. Step2. StepWorkflow "test"Additional steps are used to execute commands or pluginslike `make install` or release-to-github diff --git a/docs/versioned_docs/version-2.0/20-usage/20-workflow-syntax.md b/docs/versioned_docs/version-2.0/20-usage/20-workflow-syntax.md deleted file mode 100644 index f1f94479a3..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/20-workflow-syntax.md +++ /dev/null @@ -1,875 +0,0 @@ -# Workflow syntax - -The workflow section defines a list of steps to build, test and deploy your code. Steps are executed serially, in the order in which they are defined. If a step returns a non-zero exit code, the workflow and therefore all other workflows and the pipeline immediately aborts and returns a failure status. - -Example steps: - -```yaml -steps: - backend: - image: golang - commands: - - go build - - go test - frontend: - image: node - commands: - - npm install - - npm run test - - npm run build -``` - -In the above example we define two steps, `frontend` and `backend`. The names of these steps are completely arbitrary. - -Another way to name a step is by using the name keyword: - -```yaml -steps: - - name: backend - image: golang - commands: - - go build - - go test - - name: frontend - image: node - commands: - - npm install - - npm run test - - npm run build -``` - -Keep in mind the name is optional, if not added the steps will be numerated. - -## Skip Commits - -Woodpecker gives the ability to skip individual commits by adding `[SKIP CI]` or `[CI SKIP]` to the commit message. Note this is case-insensitive. - -```bash -git commit -m "updated README [CI SKIP]" -``` - -## Steps - -Every step of your workflow executes commands inside a specified container. The defined commands are executed serially. -The associated commit is checked out with git to a workspace which is mounted to every step of the workflow as the working directory. - -```diff - steps: - backend: - image: golang - commands: -+ - go build -+ - go test -``` - -### File changes are incremental - -- Woodpecker clones the source code in the beginning of the workflow -- Changes to files are persisted through steps as the same volume is mounted to all steps - -```yaml -# .woodpecker.yml -steps: - build: - image: debian - commands: - - echo "test content" > myfile - a-test-step: - image: debian - commands: - - cat myfile -``` - -### `image` - -Woodpecker pulls the defined image and uses it as environment to execute the workflow step commands, for plugins and for service containers. - -When using the `local` backend, the `image` entry is used to specify the shell, such as Bash or Fish, that is used to run the commands. - -```diff - steps: - build: -+ image: golang:1.6 - commands: - - go build - - go test - - publish: -+ image: plugins/docker - repo: foo/bar - - services: - database: -+ image: mysql -``` - -Woodpecker supports any valid Docker image from any Docker registry: - -```text -image: golang -image: golang:1.7 -image: library/golang:1.7 -image: index.docker.io/library/golang -image: index.docker.io/library/golang:1.7 -``` - -Woodpecker does not automatically upgrade container images. Example configuration to always pull the latest image when updates are available: - -```diff - steps: - build: - image: golang:latest -+ pull: true -``` - -Learn more how you can use images from [different registries](./41-registries.md). - -### `commands` - -Commands of every step are executed serially as if you would enter them into your local shell. - -```diff - steps: - backend: - image: golang - commands: -+ - go build -+ - go test -``` - -There is no magic here. The above commands are converted to a simple shell script. The commands in the above example are roughly converted to the below script: - -```bash -#!/bin/sh -set -e - -go build -go test -``` - -The above shell script is then executed as the container entrypoint. The below docker command is an (incomplete) example of how the script is executed: - -```bash -docker run --entrypoint=build.sh golang -``` - -> Please note that only build steps can define commands. You cannot use commands with plugins or services. - -### `environment` - -Woodpecker provides the ability to pass environment variables to individual steps. - -For more details check the [environment docs](./50-environment.md). - -### `secrets` - -Woodpecker provides the ability to store named parameters external to the YAML configuration file, in a central secret store. These secrets can be passed to individual steps of the workflow at runtime. - -For more details check the [secrets docs](./40-secrets.md). - -### `failure` - -Some of the steps may be allowed to fail without causing the whole workflow and therefore pipeline to report a failure (e.g., a step executing a linting check). To enable this, add `failure: ignore` to your step. If Woodpecker encounters an error while executing the step, it will report it as failed but still executes the next steps of the workflow, if any, without affecting the status of the workflow. - -```diff - steps: - backend: - image: golang - commands: - - go build - - go test -+ failure: ignore -``` - -### `when` - Conditional Execution - -Woodpecker supports defining a list of conditions for a step by using a `when` block. If at least one of the conditions in the `when` block evaluate to true the step is executed, otherwise it is skipped. A condition can be a check like: - -```diff - steps: - slack: - image: plugins/slack - settings: - channel: dev -+ when: -+ - event: pull_request -+ repo: test/test -+ - event: push -+ branch: main -``` - -#### `repo` - -Example conditional execution by repository: - -```diff - steps: - slack: - image: plugins/slack - settings: - channel: dev -+ when: -+ - repo: test/test -``` - -#### `branch` - -:::note -Branch conditions are not applied to tags. -::: - -Example conditional execution by branch: - -```diff -steps: - slack: - image: plugins/slack - settings: - channel: dev -+ when: -+ - branch: main -``` - -> The step now triggers on main branch, but also if the target branch of a pull request is `main`. Add an event condition to limit it further to pushes on main only. - -Execute a step if the branch is `main` or `develop`: - -```yaml -when: - - branch: [main, develop] -``` - -Execute a step if the branch starts with `prefix/*`: - -```yaml -when: - - branch: prefix/* -``` - -The branch matching is done using [doublestar](https://github.com/bmatcuk/doublestar/#usage), note that a pattern starting with `*` should be put between quotes and a literal `/` needs to be escaped. A few examples: - -- `*\\/*` to match patterns with exactly 1 `/` -- `*\\/**` to match patters with at least 1 `/` -- `*` to match patterns without `/` -- `**` to match everything - -Execute a step using custom include and exclude logic: - -```yaml -when: - - branch: - include: [main, release/*] - exclude: [release/1.0.0, release/1.1.*] -``` - -#### `event` - -Available events: `push`, `pull_request`, `tag`, `deployment`, `cron`, `manual` - -Execute a step if the build event is a `tag`: - -```yaml -when: - - event: tag -``` - -Execute a step if the pipeline event is a `push` to a specified branch: - -```diff -when: - - event: push -+ branch: main -``` - -Execute a step for multiple events: - -```yaml -when: - - event: [push, tag, deployment] -``` - -#### `cron` - -This filter **only** applies to cron events and filters based on the name of a cron job. - -Make sure to have a `event: cron` condition in the `when`-filters as well. - -```yaml -when: - - event: cron - cron: sync_* # name of your cron job -``` - -[Read more about cron](./45-cron.md) - -#### `ref` - -The `ref` filter compares the git reference against which the workflow is executed. -This allows you to filter, for example, tags that must start with **v**: - -```yaml -when: - - event: tag - ref: refs/tags/v* -``` - -#### `status` - -There are use cases for executing steps on failure, such as sending notifications for failed workflow / pipeline. Use the status constraint to execute steps even when the workflow fails: - -```diff -steps: - slack: - image: plugins/slack - settings: - channel: dev -+ when: -+ - status: [ success, failure ] -``` - -#### `platform` - -:::note -This condition should be used in conjunction with a [matrix](./30-matrix-workflows.md#example-matrix-pipeline-using-multiple-platforms) workflow as a regular workflow will only be executed by a single agent which only has one arch. -::: - -Execute a step for a specific platform: - -```yaml -when: - - platform: linux/amd64 -``` - -Execute a step for a specific platform using wildcards: - -```yaml -when: - - platform: [linux/*, windows/amd64] -``` - -#### `environment` - -Execute a step for deployment events matching the target deployment environment: - -```yaml -when: - - environment: production - - event: deployment -``` - -#### `matrix` - -Execute a step for a single matrix permutation: - -```yaml -when: - - matrix: - GO_VERSION: 1.5 - REDIS_VERSION: 2.8 -``` - -#### `instance` - -Execute a step only on a certain Woodpecker instance matching the specified hostname: - -```yaml -when: - - instance: stage.woodpecker.company.com -``` - -#### `path` - -:::info -Path conditions are applied only to **push** and **pull_request** events. -It is currently **only available** for GitHub, GitLab and Gitea (version 1.18.0 and newer) -::: - -Execute a step only on a pipeline with certain files being changed: - -```yaml -when: - - path: 'src/*' -``` - -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`. - -```yaml -when: - - path: - include: ['.woodpecker/*.yml', '*.ini'] - exclude: ['*.md', 'docs/**'] - ignore_message: '[ALL]' -``` - -**Hint:** Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions. - -#### `evaluate` - -Execute a step only if the provided evaluate expression is equal to true. Both built-in [`CI_`](./50-environment.md#built-in-environment-variables) and custom variables can be used inside the expression. - -The expression syntax can be found in [the docs](https://github.com/antonmedv/expr/blob/master/docs/Language-Definition.md) of the underlying library. - -Run on pushes to the default branch for the repository `owner/repo`: - -```yaml -when: - - evaluate: 'CI_PIPELINE_EVENT == "push" && CI_REPO == "owner/repo" && CI_COMMIT_BRANCH == CI_REPO_DEFAULT_BRANCH' -``` - -Run on commits created by user `woodpecker-ci`: - -```yaml -when: - - evaluate: 'CI_COMMIT_AUTHOR == "woodpecker-ci"' -``` - -Skip all commits containing `please ignore me` in the commit message: - -```yaml -when: - - evaluate: 'not (CI_COMMIT_MESSAGE contains "please ignore me")' -``` - -Run on pull requests with the label `deploy`: - -```yaml -when: - - evaluate: 'CI_COMMIT_PULL_REQUEST_LABELS contains "deploy"' -``` - -Skip step only if `SKIP=true`, run otherwise or if undefined: - -```yaml -when: - - evaluate: 'SKIP != "true"' -``` - -### `group` - Parallel execution - -Woodpecker supports parallel step execution for same-machine fan-in and fan-out. Parallel steps are configured using the `group` attribute. This instructs the agent to execute the named group in parallel. - -Example parallel configuration: - -```diff - steps: - backend: -+ group: build - image: golang - commands: - - go build - - go test - frontend: -+ group: build - image: node - commands: - - npm install - - npm run test - - npm run build - publish: - image: plugins/docker - repo: octocat/hello-world -``` - -In the above example, the `frontend` and `backend` steps are executed in parallel. The agent will not execute the `publish` step until the group completes. - -### `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. - -For more details check the [volumes docs](./70-volumes.md). - -### `detach` - -Woodpecker gives the ability to detach steps to run them in background until the workflow finishes. - -For more details check the [service docs](./60-services.md#detachment). - -### `directory` - -Using `directory`, you can set a subdirectory of your repository or an absolute path inside the Docker container in which your commands will run. - -## `services` - -Woodpecker can provide service containers. They can for example be used to run databases or cache containers during the execution of workflow. - -For more details check the [services docs](./60-services.md). - -## `workspace` - -The workspace defines the shared volume and working directory shared by all workflow steps. The default workspace matches the below pattern, based on your repository URL. - -```txt -/woodpecker/src/github.com/octocat/hello-world -``` - -The workspace can be customized using the workspace block in the YAML file: - -```diff -+workspace: -+ base: /go -+ path: src/github.com/octocat/hello-world - - steps: - build: - image: golang:latest - commands: - - go get - - go test -``` - -The base attribute defines a shared base volume available to all steps. This ensures your source code, dependencies and compiled binaries are persisted and shared between steps. - -```diff - workspace: -+ base: /go - path: src/github.com/octocat/hello-world - - steps: - deps: - image: golang:latest - commands: - - go get - - go test - build: - image: node:latest - commands: - - go build -``` - -This would be equivalent to the following docker commands: - -```bash -docker volume create my-named-volume - -docker run --volume=my-named-volume:/go golang:latest -docker run --volume=my-named-volume:/go node:latest -``` - -The path attribute defines the working directory of your build. This is where your code is cloned and will be the default working directory of every step in your build process. The path must be relative and is combined with your base path. - -```diff - workspace: - base: /go -+ path: src/github.com/octocat/hello-world -``` - -```text -git clone https://github.com/octocat/hello-world \ - /go/src/github.com/octocat/hello-world -``` - -## `matrix` - -Woodpecker has integrated support for matrix builds. Woodpecker executes a separate build task for each combination in the matrix, allowing you to build and test a single commit against multiple configurations. - -For more details check the [matrix build docs](./30-matrix-workflows.md). - -## `labels` - -You can set labels for your workflow to select an agent to execute the workflow on. An agent will pick up and run a workflow when **every** label assigned to it matches the agents labels. - -To set additional agent labels check the [agent configuration options](../30-administration/15-agent-config.md#woodpecker_filter_labels). Agents will have at least four default labels: `platform=agent-os/agent-arch`, `hostname=my-agent`, `backend=docker` (type of the agent backend) and `repo=*`. Agents can use a `*` as a wildcard for a label. For example `repo=*` will match every repo. - -Workflow labels with an empty value will be ignored. -By default each workflow has at least the `repo=your-user/your-repo-name` label. If you have set the [platform attribute](#platform) for your workflow it will have a label like `platform=your-os/your-arch` as well. - -You can add additional labels as a key value map: - -```diff -+labels: -+ location: europe # only agents with `location=europe` or `location=*` will be used -+ weather: sun -+ hostname: "" # this label will be ignored as it is empty - -steps: - build: - image: golang - commands: - - go build - - go test -``` - -### Filter by platform - -To configure your workflow to only be executed on an agent with a specific platform, you can use the `platform` key. -Have a look at the official [go docs](https://go.dev/doc/install/source) for the available platforms. The syntax of the platform is `GOOS/GOARCH` like `linux/arm64` or `linux/amd64`. - -Example: - -Assuming we have two agents, one `linux/arm` and one `linux/amd64`. Previously this workflow would have executed on **either agent**, as Woodpecker is not fussy about where it runs the workflows. By setting the following option it will only be executed on an agent with the platform `linux/arm64`. - -```diff -+labels: -+ platform: linux/arm64 - -steps: - [...] -``` - -## `variables` - -Woodpecker supports using [YAML anchors & aliases](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) as variables in the workflow configuration. - -For more details and examples check the [Advanced usage docs](./90-advanced-usage.md) - -## `clone` - -Woodpecker automatically configures a default clone step if not explicitly defined. When using the `local` backend, the [plugin-git](https://github.com/woodpecker-ci/plugin-git) binary must be on your `$PATH` for the default clone step to work. If not, you can still write a manual clone step. - -You can manually configure the clone step in your workflow for customization: - -```diff -+clone: -+ git: -+ image: woodpeckerci/plugin-git - - steps: - build: - image: golang - commands: - - go build - - go test -``` - -Example configuration to override depth: - -```diff - clone: - git: - image: woodpeckerci/plugin-git -+ settings: -+ partial: false -+ depth: 50 -``` - -Example configuration to use a custom clone plugin: - -```diff -clone: - git: -+ image: octocat/custom-git-plugin -``` - -Example configuration to clone Mercurial repository: - -```diff - clone: - hg: -+ image: plugins/hg -+ settings: -+ path: bitbucket.org/foo/bar -``` - -### Git Submodules - -To use the credentials that cloned the repository to clone it's submodules, update `.gitmodules` to use `https` instead of `git`: - -```diff - [submodule "my-module"] - path = my-module --url = git@github.com:octocat/my-module.git -+url = https://github.com/octocat/my-module.git -``` - -To use the ssh git url in `.gitmodules` for users cloning with ssh, and also use the https url in Woodpecker, add `submodule_override`: - -```diff - clone: - git: - image: woodpeckerci/plugin-git - settings: - recursive: true -+ submodule_override: -+ my-module: https://github.com/octocat/my-module.git - -steps: - ... -``` - -## `skip_clone` - -By default Woodpecker is automatically adding a clone step. This clone step can be configured by the [clone](#clone) property. If you do not need a `clone` step at all you can skip it using: - -```yaml -skip_clone: true -``` - -## `when` - Global workflow conditions - -Woodpecker gives the ability to skip whole workflows (not just steps #when---conditional-execution-1) based on certain conditions by a `when` block. If all conditions in the `when` block evaluate to true the workflow is executed, otherwise it is skipped, but treated as successful and other workflows depending on it will still continue. - -### `repo` - -Example conditional execution by repository: - -```diff -+when: -+ repo: test/test -+ - steps: - slack: - image: plugins/slack - settings: - channel: dev -``` - -### `branch` - -:::note -Branch conditions are not applied to tags. -::: - -Example conditional execution by branch: - -```diff -+when: -+ branch: main -+ - steps: - slack: - image: plugins/slack - settings: - channel: dev -``` - -> The step now triggers on main, but also if the target branch of a pull request is `main`. Add an event condition to limit it further to pushes on main only. - -Execute a step if the branch is `main` or `develop`: - -```diff -when: - branch: [main, develop] -``` - -Execute a step if the branch starts with `prefix/*`: - -```diff -when: - branch: prefix/* -``` - -Execute a step using custom include and exclude logic: - -```diff -when: - branch: - include: [ main, release/* ] - exclude: [ release/1.0.0, release/1.1.* ] -``` - -### `event` - -Execute a step if the build event is a `tag`: - -```diff -when: - event: tag -``` - -Execute a step if the pipeline event is a `push` to a specified branch: - -```diff -when: - event: push -+ branch: main -``` - -Execute a step for all non-pull request events: - -```diff -when: - event: [push, tag, deployment] -``` - -Execute a step for all build events: - -```diff -when: - event: [push, pull_request, tag, deployment] -``` - -### `ref` - -The `ref` filter compares the git reference against which the pipeline is executed. -This allows you to filter, for example, tags that must start with **v**: - -```yaml -when: - event: tag - ref: refs/tags/v* -``` - -### `environment` - -Execute a step for deployment events matching the target deployment environment: - -```diff -when: - environment: production - event: deployment -``` - -### `instance` - -Execute a step only on a certain Woodpecker instance matching the specified hostname: - -```diff -when: - instance: stage.woodpecker.company.com -``` - -### `path` - -:::info -Path conditions are applied only to **push** and **pull_request** events. -It is currently **only available** for GitHub, GitLab and Gitea (version 1.18.0 and newer) -::: - -Execute a step only on a pipeline with certain files being changed: - -```diff -when: - path: "src/*" -``` - -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`. - -```diff -when: - path: - include: [ '.woodpecker/*.yml', '*.ini' ] - exclude: [ '*.md', 'docs/**' ] - ignore_message: "[ALL]" -``` - -**Hint:** Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions. - -## `depends_on` - -Woodpecker supports to define multiple workflows for a repository. Those workflows will run independent from each other. To depend them on each other you can use the [`depends_on`](./25-workflows.md#flow-control) keyword. - -## `runs_on` - -Workflows that should run even on failure should set the `runs_on` tag. See [here](./25-workflows.md#flow-control) for an example. - -## Privileged mode - -Woodpecker gives the ability to configure privileged mode in the YAML. You can use this parameter to launch containers with escalated capabilities. - -> Privileged mode is only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./71-project-settings.md#trusted) to enable trusted mode. - -```diff - steps: - build: - image: docker - environment: - - DOCKER_HOST=tcp://docker:2375 - commands: - - docker --tls=false ps - - services: - docker: - image: docker:dind - commands: dockerd-entrypoint.sh --storage-driver=vfs --tls=false -+ privileged: true -``` diff --git a/docs/versioned_docs/version-2.0/20-usage/25-workflows.md b/docs/versioned_docs/version-2.0/20-usage/25-workflows.md deleted file mode 100644 index 0d1523109e..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/25-workflows.md +++ /dev/null @@ -1,130 +0,0 @@ -# Workflows - -:::info -This Feature is only available for GitHub, Gitea & GitLab repositories. Follow [this](https://github.com/woodpecker-ci/woodpecker/issues/1138) issue to support further development. -::: - -A pipeline has at least one workflow. A workflow is a set of steps that are executed in sequence using the same workspace which is a shared folder containing the repository and all the generated data from previous steps. - -Incase there is a single configuration in `.woodpecker.yml` Woodpecker will create a pipeline with a single workflow. - -By placing the configurations in a folder which is by default named `.woodpecker/` Woodpecker will create a pipeline with multiple workflows each named by the file they are defined in. Only `.yml` and `.yaml` files will be used and files in any subfolders like `.woodpecker/sub-folder/test.yml` will be ignored. - -You can also set some custom path like `.my-ci/pipelines/` instead of `.woodpecker/` in the [project settings](./71-project-settings.md). - -## Benefits of using workflows - -- faster lint/test feedback, the workflow doesn't have to run fully to have a lint status pushed to the remote -- better organization of a pipeline along various concerns using one workflow for: testing, linting, building and deploying -- utilizing more agents to speed up the execution of the whole pipeline - -## Example workflow definition - -:::warning -Please note that files are only shared between steps of the same workflow (see [File changes are incremental](./20-workflow-syntax.md#file-changes-are-incremental)). That means you cannot access artifacts e.g. from the `build` workflow in the `deploy` workflow. -If you still need to pass artifacts between the workflows you need use some storage [plugin](./51-plugins/10-plugins.md) (e.g. one which stores files in an Amazon S3 bucket). -::: - -```bash -.woodpecker/ -├── .build.yml -├── .deploy.yml -├── .lint.yml -└── .test.yml -``` - -.woodpecker/.build.yml - -```yaml -steps: - build: - image: debian:stable-slim - commands: - - echo building - - sleep 5 -``` - -.woodpecker/.deploy.yml - -```yaml -steps: - deploy: - image: debian:stable-slim - commands: - - echo deploying - -depends_on: - - lint - - build - - test -``` - -.woodpecker/.test.yml - -```yaml -steps: - test: - image: debian:stable-slim - commands: - - echo testing - - sleep 5 - -depends_on: - - build -``` - -.woodpecker/.lint.yml - -```yaml -steps: - lint: - image: debian:stable-slim - commands: - - echo linting - - sleep 5 -``` - -## Status lines - -Each workflow will report its own status back to your forge. - -## Flow control - -The workflows run in parallel on separate agents and share nothing. - -Dependencies between workflows can be set with the `depends_on` element. A workflow doesn't execute until all of its dependencies finished successfully. - -The name for a `depends_on` entry is the filename without the path, leading dots and without the file extension `.yml` or `.yaml`. If the project config for example uses `.woodpecker/` as path for CI files with a file named `.woodpecker/.lint.yml` the corresponding `depends_on` entry would be `lint`. - -```diff -steps: - deploy: - image: debian:stable-slim - commands: - - echo deploying - -+depends_on: -+ - lint -+ - build -+ - test -``` - -Workflows that need to run even on failures should set the `runs_on` tag. - -```diff -steps: - notify: - image: debian:stable-slim - commands: - - echo notifying - -depends_on: - - deploy - -+runs_on: [ success, failure ] -``` - -:::info -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) -::: diff --git a/docs/versioned_docs/version-2.0/20-usage/30-matrix-workflows.md b/docs/versioned_docs/version-2.0/20-usage/30-matrix-workflows.md deleted file mode 100644 index 1abe0bcc58..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/30-matrix-workflows.md +++ /dev/null @@ -1,143 +0,0 @@ -# Matrix workflows - -Woodpecker has integrated support for matrix workflows. Woodpecker executes a separate workflow for each combination in the matrix, allowing you to build and test against multiple configurations. - -Example matrix definition: - -```yaml -matrix: - GO_VERSION: - - 1.4 - - 1.3 - REDIS_VERSION: - - 2.6 - - 2.8 - - 3.0 -``` - -Example matrix definition containing only specific combinations: - -```yaml -matrix: - include: - - GO_VERSION: 1.4 - REDIS_VERSION: 2.8 - - GO_VERSION: 1.5 - REDIS_VERSION: 2.8 - - GO_VERSION: 1.6 - REDIS_VERSION: 3.0 -``` - -## Interpolation - -Matrix variables are interpolated in the YAML using the `${VARIABLE}` syntax, before the YAML is parsed. This is an example YAML file before interpolating matrix parameters: - -```yaml -matrix: - GO_VERSION: - - 1.4 - - 1.3 - DATABASE: - - mysql:8 - - mysql:5 - - mariadb:10.1 - -steps: - build: - image: golang:${GO_VERSION} - commands: - - go get - - go build - - go test - -services: - database: - image: ${DATABASE} -``` - -Example YAML file after injecting the matrix parameters: - -```diff -steps: - build: -- image: golang:${GO_VERSION} -+ image: golang:1.4 - commands: - - go get - - go build - - go test -+ environment: -+ - GO_VERSION=1.4 -+ - DATABASE=mysql:8 - -services: - database: -- image: ${DATABASE} -+ image: mysql:8 -``` - -## Examples - -### Example matrix pipeline based on Docker image tag - -```yaml -matrix: - TAG: - - 1.7 - - 1.8 - - latest - -steps: - build: - image: golang:${TAG} - commands: - - go build - - go test -``` - -### Example matrix pipeline based on container image - -```yaml -matrix: - IMAGE: - - golang:1.7 - - golang:1.8 - - golang:latest - -steps: - build: - image: ${IMAGE} - commands: - - go build - - go test -``` - -### Example matrix pipeline using multiple platforms - -```yaml -matrix: - platform: - - linux/amd64 - - linux/arm64 - -labels: - platform: ${platform} - -steps: - test: - image: alpine - commands: - - echo "I am running on ${platform}" - - test-arm-only: - image: alpine - commands: - - echo "I am running on ${platform}" - - echo "Arm is cool!" - when: - platform: linux/arm* -``` - -:::note -If you want to control the architecture of a pipeline on a Kubernetes runner, see [the nodeSelector documentation of the Kubernetes backend](../30-administration/22-backends/40-kubernetes.md#nodeselector). -::: diff --git a/docs/versioned_docs/version-2.0/20-usage/40-secrets.md b/docs/versioned_docs/version-2.0/20-usage/40-secrets.md deleted file mode 100644 index 4f2a3ae54b..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/40-secrets.md +++ /dev/null @@ -1,142 +0,0 @@ -# Secrets - -Woodpecker provides the ability to store named parameters external to the YAML configuration file, in a central secret store. These secrets can be passed to individual steps of the pipeline at runtime. - -Woodpecker provides three different levels to add secrets to your pipeline. The following list shows the priority of the different levels. If a secret is defined in multiple levels, will be used following this priorities: Repository secrets > Organization secrets > Global secrets. - -1. **Repository secrets**: They are available to all pipelines of an repository. -2. **Organization secrets**: They are available to all pipelines of an organization. -3. **Global secrets**: Can be configured by an instance admin. - They are available to all pipelines of the **whole** Woodpecker instance and should therefore **only** be used for secrets that are allowed to be read by **all** users. - -## Usage - -### Use secrets in commands - -Secrets are exposed to your pipeline steps and plugins as uppercase environment variables and can therefore be referenced in the commands section of your pipeline, -once their usage is declared in the `secrets` section: - -```diff -steps: - docker: - image: docker - commands: -+ - echo $DOCKER_USERNAME -+ - echo $DOCKER_PASSWORD -+ secrets: [ docker_username, docker_password ] -``` - -### Use secrets in settings - -Alternatively, you can get a `setting` from secrets using the `from_secret` syntax. -In this example, the secret named `secret_token` would be passed to the setting named `token`, which will be available in the plugin as environment variable named `PLUGIN_TOKEN`. See [Plugins](./plugins/sample-plugin#write-the-logic) for details. - -**NOTE:** the `from_secret` syntax only works with the newer `settings` block. - -```diff -steps: - docker: - image: my-plugin - settings: -+ token: -+ from_secret: secret_token -``` - -### Note about parameter pre-processing - -Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped. - -```diff -steps: - docker: - image: docker - commands: -- - echo ${DOCKER_USERNAME} -- - echo ${DOCKER_PASSWORD} -+ - echo $${DOCKER_USERNAME} -+ - echo $${DOCKER_PASSWORD} - secrets: [ docker_username, docker_password ] -``` - -### Alternate Names - -There may be scenarios where you are required to store secrets using alternate names. You can map the alternate secret name to the expected name using the below syntax: - -```diff -steps: - docker: - image: plugins/docker - repo: octocat/hello-world - tags: latest -+ secrets: -+ - source: docker_prod_password -+ target: docker_password -``` - -### Use in Pull Requests events - -Secrets are not exposed to pull requests by default. You can override this behavior by creating the secret and enabling the `pull_request` event type, either in UI or by CLI, see below. - -**NOTE:** Please be careful when exposing secrets to pull requests. If your repository is open source and accepts pull requests your secrets are not safe. A bad actor can submit a malicious pull request that exposes your secrets. - -## Image filter - -To prevent abusing your secrets from malicious usage, you can limit a secret to a list of images. If enabled they are not available to any other plugin (steps without user-defined commands). If you or an attacker defines explicit commands, the secrets will not be available to the container to prevent leaking them. - -## Adding Secrets - -Secrets are added to the Woodpecker in the UI or with the CLI. - -### CLI Examples - -Create the secret using default settings. The secret will be available to all images in your pipeline, and will be available to all push, tag, and deployment events (not pull request events). - -```diff -woodpecker-cli secret add \ - -repository octocat/hello-world \ - -name aws_access_key_id \ - -value -``` - -Create the secret and limit to a single image: - -```diff -woodpecker-cli secret add \ - -repository octocat/hello-world \ -+ -image plugins/s3 \ - -name aws_access_key_id \ - -value -``` - -Create the secrets and limit to a set of images: - -```diff -woodpecker-cli secret add \ - -repository octocat/hello-world \ -+ -image plugins/s3 \ -+ -image peloton/woodpecker-ecs \ - -name aws_access_key_id \ - -value -``` - -Create the secret and enable for multiple hook events: - -```diff -woodpecker-cli secret add \ - -repository octocat/hello-world \ - -image plugins/s3 \ -+ -event pull_request \ -+ -event push \ -+ -event tag \ - -name aws_access_key_id \ - -value -``` - -Loading secrets from file using curl `@` syntax. This is the recommended approach for loading secrets from file to preserve newlines: - -```diff -woodpecker-cli secret add \ - -repository octocat/hello-world \ - -name ssh_key \ -+ -value @/root/ssh/id_rsa -``` diff --git a/docs/versioned_docs/version-2.0/20-usage/41-registries.md b/docs/versioned_docs/version-2.0/20-usage/41-registries.md deleted file mode 100644 index f0a69d6b66..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/41-registries.md +++ /dev/null @@ -1,69 +0,0 @@ -# Registries - -Woodpecker provides the ability to add container registries in the settings of your repository. Adding a registry allows you to authenticate and pull private images from a container registry when using these images as a step inside your pipeline. Using registry credentials can also help you avoid rate limiting when pulling images from public registries. - -## Images from private registries - -You must provide registry credentials in the UI in order to pull private container images defined in your YAML configuration file. - -These credentials are never exposed to your steps, which means they cannot be used to push, and are safe to use with pull requests, for example. Pushing to a registry still requires setting credentials for the appropriate plugin. - -Example configuration using a private image: - -```diff - steps: - build: -+ image: gcr.io/custom/golang - commands: - - go build - - go test -``` - -Woodpecker matches the registry hostname to each image in your YAML. If the hostnames match, the registry credentials are used to authenticate to your registry and pull the image. Note that registry credentials are used by the Woodpecker agent and are never exposed to your build containers. - -Example registry hostnames: - -- Image `gcr.io/foo/bar` has hostname `gcr.io` -- Image `foo/bar` has hostname `docker.io` -- Image `qux.com:8000/foo/bar` has hostname `qux.com:8000` - -Example registry hostname matching logic: - -- Hostname `gcr.io` matches image `gcr.io/foo/bar` -- Hostname `docker.io` matches `golang` -- Hostname `docker.io` matches `library/golang` -- Hostname `docker.io` matches `bradyrydzewski/golang` -- Hostname `docker.io` matches `bradyrydzewski/golang:latest` - -## Global registry support - -To make a private registry globally available, check the [server configuration docs](../30-administration/10-server-config.md#global-registry-setting). - -## GCR registry support - -For specific details on configuring access to Google Container Registry, please view the docs [here](https://cloud.google.com/container-registry/docs/advanced-authentication#using_a_json_key_file). - -## Local Images - -:::warning -For this, privileged rights are needed only available to admins. In addition, this only works when using a single agent. -::: - -It's possible to build a local image by mounting the docker socket as a volume. - -With a `Dockerfile` at the root of the project: - -```diff -steps: - build-image: - image: docker - commands: - - docker build --rm -t local/project-image . - volumes: - - /var/run/docker.sock:/var/run/docker.sock - - build-project: - image: local/project-image - commands: - - ./build.sh -``` diff --git a/docs/versioned_docs/version-2.0/20-usage/45-cron.md b/docs/versioned_docs/version-2.0/20-usage/45-cron.md deleted file mode 100644 index f90c77c1ad..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/45-cron.md +++ /dev/null @@ -1,34 +0,0 @@ -# Cron - -To configure cron jobs you need at least push access to the repository. - -## Add a new cron job - -1. To create a new cron job adjust your pipeline config(s) and add the event filter to all steps you would like to run by the cron job: - - ```diff - steps: - sync_locales: - image: weblate_sync - settings: - url: example.com - token: - from_secret: weblate_token - + when: - + event: cron - + cron: "name of the cron job" # if you only want to execute this step by a specific cron job - ``` - -1. Create a new cron job in the repository settings: - - ![cron settings](./cron-settings.png) - - The supported schedule syntax can be found at . If you need general understanding of the cron syntax is a good place to start and experiment. - - Examples: `@every 5m`, `@daily`, `0 30 * * * *` ... - - :::info - Woodpeckers cron syntax starts with seconds instead of minutes as used by most linux cron schedulers. - - Example: "At minute 30 every hour" would be `0 30 * * * *` instead of `30 * * * *` - ::: diff --git a/docs/versioned_docs/version-2.0/20-usage/50-environment.md b/docs/versioned_docs/version-2.0/20-usage/50-environment.md deleted file mode 100644 index fb1fe3d7cd..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/50-environment.md +++ /dev/null @@ -1,224 +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: - 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: - build: - image: golang -- environment: -- - PATH=$PATH:/go - commands: -+ - export PATH=$PATH:/go - - go build - - go test -``` - -> Please be warned that `${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: - 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 | -| -------------------------------- | -------------------------------------------------------------------------------------------- | -| `CI` | CI environment name (value: `woodpecker`) | -| | **Repository** | -| `CI_REPO` | repository full name `/` | -| `CI_REPO_OWNER` | repository owner | -| `CI_REPO_NAME` | repository name | -| `CI_REPO_REMOTE_ID` | repository remote ID, is the UID it has in the forge | -| `CI_REPO_SCM` | repository SCM (git) | -| `CI_REPO_URL` | repository web URL | -| `CI_REPO_CLONE_URL` | repository clone URL | -| `CI_REPO_CLONE_SSH_URL` | repository SSH clone URL | -| `CI_REPO_DEFAULT_BRANCH` | repository default branch (main) | -| `CI_REPO_PRIVATE` | repository is private | -| `CI_REPO_TRUSTED` | repository is trusted | -| | **Current Commit** | -| `CI_COMMIT_SHA` | commit SHA | -| `CI_COMMIT_REF` | commit ref | -| `CI_COMMIT_REFSPEC` | commit ref spec | -| `CI_COMMIT_BRANCH` | commit branch (equals target branch for pull requests) | -| `CI_COMMIT_SOURCE_BRANCH` | commit source branch (empty if event is not `pull_request`) | -| `CI_COMMIT_TARGET_BRANCH` | commit target branch (empty if event is not `pull_request`) | -| `CI_COMMIT_TAG` | commit tag name (empty if event is not `tag`) | -| `CI_COMMIT_PULL_REQUEST` | commit pull request number (empty if event is not `pull_request`) | -| `CI_COMMIT_PULL_REQUEST_LABELS` | labels assigned to pull request (empty if event is not `pull_request`) | -| `CI_COMMIT_MESSAGE` | commit message | -| `CI_COMMIT_AUTHOR` | commit author username | -| `CI_COMMIT_AUTHOR_EMAIL` | commit author email address | -| `CI_COMMIT_AUTHOR_AVATAR` | commit author avatar | -| | **Current pipeline** | -| `CI_PIPELINE_NUMBER` | pipeline number | -| `CI_PIPELINE_PARENT` | number of parent pipeline | -| `CI_PIPELINE_EVENT` | pipeline event (push, pull_request, tag, deployment, cron, manual) | -| `CI_PIPELINE_URL` | link to the web UI for the pipeline | -| `CI_PIPELINE_FORGE_URL` | link to the forge's web UI for the commit(s) or tag that triggered the pipeline | -| `CI_PIPELINE_DEPLOY_TARGET` | pipeline deploy target for `deployment` events (ie production) | -| `CI_PIPELINE_STATUS` | pipeline status (success, failure) | -| `CI_PIPELINE_CREATED` | pipeline created UNIX timestamp | -| `CI_PIPELINE_STARTED` | pipeline started UNIX timestamp | -| `CI_PIPELINE_FINISHED` | pipeline finished UNIX timestamp | -| | **Current workflow** | -| `CI_WORKFLOW_NAME` | workflow name | -| | **Current step** | -| `CI_STEP_NAME` | step name | -| `CI_STEP_NUMBER` | step number | -| `CI_STEP_STATUS` | step status (success, failure) | -| `CI_STEP_STARTED` | step started UNIX timestamp | -| `CI_STEP_FINISHED` | step finished UNIX timestamp | -| `CI_STEP_URL` | URL to step in UI | -| | **Previous commit** | -| `CI_PREV_COMMIT_SHA` | previous commit SHA | -| `CI_PREV_COMMIT_REF` | previous commit ref | -| `CI_PREV_COMMIT_REFSPEC` | previous commit ref spec | -| `CI_PREV_COMMIT_BRANCH` | previous commit branch | -| `CI_PREV_COMMIT_SOURCE_BRANCH` | previous commit source branch | -| `CI_PREV_COMMIT_TARGET_BRANCH` | previous commit target branch | -| `CI_PREV_COMMIT_URL` | previous commit link in forge | -| `CI_PREV_COMMIT_MESSAGE` | previous commit message | -| `CI_PREV_COMMIT_AUTHOR` | previous commit author username | -| `CI_PREV_COMMIT_AUTHOR_EMAIL` | previous commit author email address | -| `CI_PREV_COMMIT_AUTHOR_AVATAR` | previous commit author avatar | -| | **Previous pipeline** | -| `CI_PREV_PIPELINE_NUMBER` | previous pipeline number | -| `CI_PREV_PIPELINE_PARENT` | previous pipeline number of parent pipeline | -| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (push, pull_request, tag, deployment) | -| `CI_PREV_PIPELINE_URL` | previous pipeline link in CI | -| `CI_PREV_PIPELINE_FORGE_URL` | previous pipeline link to event in forge | -| `CI_PREV_PIPELINE_DEPLOY_TARGET` | previous pipeline deploy target for `deployment` events (ie production) | -| `CI_PREV_PIPELINE_STATUS` | previous pipeline status (success, failure) | -| `CI_PREV_PIPELINE_CREATED` | previous pipeline created UNIX timestamp | -| `CI_PREV_PIPELINE_STARTED` | previous pipeline started UNIX timestamp | -| `CI_PREV_PIPELINE_FINISHED` | previous pipeline finished UNIX timestamp | -| |   | -| `CI_WORKSPACE` | Path of the workspace where source code gets cloned to | -| | **System** | -| `CI_SYSTEM_NAME` | name of the CI system: `woodpecker` | -| `CI_SYSTEM_URL` | link to CI system | -| `CI_SYSTEM_HOST` | hostname of CI server | -| `CI_SYSTEM_VERSION` | version of the server | -| | **Forge** | -| `CI_FORGE_TYPE` | name of forge (gitea, github, ...) | -| `CI_FORGE_URL` | root URL of configured forge | -| | **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. - -```diff -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2 -``` - -These can be used, for example, to manage the image tag used by multiple projects. - -```diff -steps: - build: -- image: golang:1.18 -+ image: golang:${GOLANG_VERSION} - commands: - - [...] - environment: - - [...] -+ - WOODPECKER_ENVIRONMENT=GOLANG_VERSION:1.18 -``` - -## 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: - docker: - image: plugins/docker - settings: -+ tags: ${CI_COMMIT_SHA} -``` - -Example tag substitution: - -```diff -steps: - docker: - image: plugins/docker - settings: -+ tags: ${CI_COMMIT_TAG} -``` - -## String Operations - -Woodpecker also emulates bash string operations. This gives us the ability to manipulate the strings prior to substitution. Example use cases might include substring and stripping prefix or suffix values. - -| OPERATION | DESCRIPTION | -| ------------------ | ------------------------------------------------ | -| `${param}` | parameter substitution | -| `${param,}` | parameter substitution with lowercase first char | -| `${param,,}` | parameter substitution with lowercase | -| `${param^}` | parameter substitution with uppercase first char | -| `${param^^}` | parameter substitution with uppercase | -| `${param:pos}` | parameter substitution with substring | -| `${param:pos:len}` | parameter substitution with substring and length | -| `${param=default}` | parameter substitution with default | -| `${param##prefix}` | parameter substitution with prefix removal | -| `${param%%suffix}` | parameter substitution with suffix removal | -| `${param/old/new}` | parameter substitution with find and replace | - -Example variable substitution with substring: - -```diff -steps: - docker: - image: plugins/docker - settings: -+ tags: ${CI_COMMIT_SHA:0:8} -``` - -Example variable substitution strips `v` prefix from `v.1.0.0`: - -```diff -steps: - docker: - image: plugins/docker - settings: -+ tags: ${CI_COMMIT_TAG##v} -``` diff --git a/docs/versioned_docs/version-2.0/20-usage/51-plugins/10-plugins.md b/docs/versioned_docs/version-2.0/20-usage/51-plugins/10-plugins.md deleted file mode 100644 index 48977c9a84..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/51-plugins/10-plugins.md +++ /dev/null @@ -1,49 +0,0 @@ -# Plugins - -Plugins are pipeline steps that perform pre-defined tasks and are configured as steps in your pipeline. Plugins can be used to deploy code, publish artifacts, send notification, and more. - -They are automatically pulled from the default container registry the agent's have configured. - -Example pipeline using the Docker and Slack plugins: - -```yaml -steps: - build: - image: golang - commands: - - go build - - go test - - publish: - image: plugins/docker - settings: - repo: foo/bar - tags: latest - - notify: - image: plugins/slack - settings: - channel: dev -``` - -## Plugin Isolation - -Plugins are just pipeline steps. They share the build workspace, mounted as a volume, and therefore have access to your source tree. - -## Finding Plugins - -For official plugins, you can use the Woodpecker plugin index: - -- [Official Woodpecker Plugins](https://woodpecker-ci.org/plugins) - -:::tip -There are also other plugin lists with additional plugins. Keep in mind that [Drone](https://www.drone.io/) plugins are generally supported, but could need some adjustments and tweaking. - -- [Drone Plugins](http://plugins.drone.io) -- [Geeklab Woodpecker Plugins](https://woodpecker-plugins.geekdocs.de/) - -::: - -## Creating a plugin - -See a [detailed plugin example](./20-sample-plugin.md). diff --git a/docs/versioned_docs/version-2.0/20-usage/51-plugins/20-sample-plugin.md b/docs/versioned_docs/version-2.0/20-usage/51-plugins/20-sample-plugin.md deleted file mode 100644 index 317303e76c..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/51-plugins/20-sample-plugin.md +++ /dev/null @@ -1,60 +0,0 @@ -# Example plugin - -This provides a brief tutorial for creating a Woodpecker webhook plugin, using simple shell scripting, to make an http requests during the build pipeline. - -## What end users will see - -The below example demonstrates how we might configure a webhook plugin in the YAML file: - -```yaml -steps: - webhook: - image: foo/webhook - settings: - url: http://example.com - method: post - body: | - hello world -``` - -## Write the logic - -Create a simple shell script that invokes curl using the YAML configuration parameters, which are passed to the script as environment variables in uppercase and prefixed with `PLUGIN_`. - -```bash -#!/bin/sh - -curl \ - -X ${PLUGIN_METHOD} \ - -d ${PLUGIN_BODY} \ - ${PLUGIN_URL} -``` - -## Package it - -Create a Dockerfile that adds your shell script to the image, and configures the image to execute your shell script as the main entrypoint. - -```dockerfile -FROM alpine -ADD script.sh /bin/ -RUN chmod +x /bin/script.sh -RUN apk -Uuv add curl ca-certificates -ENTRYPOINT /bin/script.sh -``` - -Build and publish your plugin to the Docker registry. Once published your plugin can be shared with the broader Woodpecker community. - -```nohighlight -docker build -t foo/webhook . -docker push foo/webhook -``` - -Execute your plugin locally from the command line to verify it is working: - -```nohighlight -docker run --rm \ - -e PLUGIN_METHOD=post \ - -e PLUGIN_URL=http://example.com \ - -e PLUGIN_BODY="hello world" \ - foo/webhook -``` diff --git a/docs/versioned_docs/version-2.0/20-usage/51-plugins/_category_.yaml b/docs/versioned_docs/version-2.0/20-usage/51-plugins/_category_.yaml deleted file mode 100644 index 7dd7a3cc85..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/51-plugins/_category_.yaml +++ /dev/null @@ -1,4 +0,0 @@ -label: 'Plugins' -# position: 2 -collapsible: true -collapsed: true diff --git a/docs/versioned_docs/version-2.0/20-usage/60-services.md b/docs/versioned_docs/version-2.0/20-usage/60-services.md deleted file mode 100644 index f2f157e075..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/60-services.md +++ /dev/null @@ -1,99 +0,0 @@ -# Services - -Woodpecker provides a services section in the YAML file used for defining service containers. -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`. - -```yaml -steps: - build: - image: golang - commands: - - go build - - go test - -services: - database: - image: mysql - - cache: - image: redis -``` - -## Configuration - -Service containers generally expose environment variables to customize service startup such as default usernames, passwords and ports. Please see the official image documentation to learn more. - -```diff -services: - database: - image: mysql -+ environment: -+ - MYSQL_DATABASE=test -+ - MYSQL_ALLOW_EMPTY_PASSWORD=yes - - cache: - image: redis -``` - -## Detachment - -Service and long running containers can also be included in the pipeline section of the configuration using the detach parameter without blocking other steps. This should be used when explicit control over startup order is required. - -```diff -steps: - build: - image: golang - commands: - - go build - - go test - - database: - image: redis -+ detach: true - - test: - image: golang - commands: - - go test -``` - -Containers from detached steps will terminate when the pipeline ends. - -## Initialization - -Service containers require time to initialize and begin to accept connections. If you are unable to connect to a service you may need to wait a few seconds or implement a backoff. - -```diff -steps: - test: - image: golang - commands: -+ - sleep 15 - - go get - - go test - -services: - database: - image: mysql -``` - -## Complete Pipeline Example - -```yaml -services: - database: - image: mysql - environment: - - MYSQL_DATABASE=test - - MYSQL_ROOT_PASSWORD=example -steps: - get-version: - image: ubuntu - commands: - - ( apt update && apt dist-upgrade -y && apt install -y mysql-client 2>&1 )> /dev/null - - sleep 30s # need to wait for mysql-server init - - echo 'SHOW VARIABLES LIKE "version"' | mysql -uroot -hdatabase test -pexample -``` diff --git a/docs/versioned_docs/version-2.0/20-usage/70-volumes.md b/docs/versioned_docs/version-2.0/20-usage/70-volumes.md deleted file mode 100644 index 297f14ec07..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/70-volumes.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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. - -:::note -Volumes are only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./71-project-settings.md#trusted) to enable trusted mode. -::: - -```diff -steps: - build: - image: docker - commands: - - docker build --rm -t octocat/hello-world . - - docker run --rm octocat/hello-world --test - - docker push octocat/hello-world - - docker rmi octocat/hello-world - volumes: -+ - /var/run/docker.sock:/var/run/docker.sock -``` - -Please note that Woodpecker mounts volumes on the host machine. This means you must use absolute paths when you configure volumes. Attempting to use relative paths will result in an error. - -```diff -- volumes: [ ./certs:/etc/ssl/certs ] -+ volumes: [ /etc/ssl/certs:/etc/ssl/certs ] -``` diff --git a/docs/versioned_docs/version-2.0/20-usage/71-project-settings.md b/docs/versioned_docs/version-2.0/20-usage/71-project-settings.md deleted file mode 100644 index 319a07e610..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/71-project-settings.md +++ /dev/null @@ -1,54 +0,0 @@ -# Project settings - -As the owner of a project in Woodpecker you can change project related settings via the web interface. - -![project settings](./project-settings.png) - -## Pipeline path - -The path to the pipeline config file or folder. By default it is left empty which will use the following configuration resolution `.woodpecker/*.yml` -> `.woodpecker/*.yaml` -> `.woodpecker.yml` -> `.woodpecker.yaml`. If you set a custom path Woodpecker tries to load your configuration or fails if no configuration could be found at the specified location. To use a [multiple workflows](./25-workflows.md) with a custom path you have to change it to a folder path ending with a `/` like `.woodpecker/`. - -## Repository hooks - -Your Version-Control-System will notify Woodpecker about events via webhooks. If you want your pipeline to only run on specific webhooks, you can check them with this setting. - -## Project settings - -### Allow pull requests - -Enables handling webhook's pull request event. If disabled, then pipeline won't run for pull requests. - -### Protected - -Every pipeline initiated by an webhook event needs to be approved by a project members with push permissions before being executed. -The protected option can be used as an additional review process before running potentially harmful pipelines. Especially if pipelines can be executed by third-parties through pull-requests. - -### Trusted - -If you set your project to trusted, a pipeline step and by this the underlying containers gets access to escalated capabilities like mounting volumes. - -:::note - -Only server admins can set this option. If you are not a server admin this option won't be shown in your project settings. - -::: - -### Only inject netrc credentials into trusted containers - -Cloning pipeline step may need git credentials. They are injected via netrc. By default, they're only injected if this option is enabled, the repo is trusted ([see above](#trusted)) or the image is a trusted clone image. If you uncheck the option, git credentials will be injected into any container in clone step. - -## Project visibility - -You can change the visibility of your project by this setting. If a user has access to a project he can see all builds and their logs and artifacts. Settings, Secrets and Registries can only be accessed by owners. - -- `Public` Every user can see your project without being logged in. -- `Internal` Only authenticated users of the Woodpecker instance can see this project. -- `Private` Only you and other owners of the repository can see this project. - -## Timeout - -After this timeout a pipeline has to finish or will be treated as timed out. - -## Cancel previous pipelines - -By enabling this option for a pipeline event previous pipelines of the same event and context will be canceled before starting the newly triggered one. diff --git a/docs/versioned_docs/version-2.0/20-usage/80-badges.md b/docs/versioned_docs/version-2.0/20-usage/80-badges.md deleted file mode 100644 index 1edfcfd495..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/80-badges.md +++ /dev/null @@ -1,18 +0,0 @@ -# Status Badges - -Woodpecker has integrated support for repository status badges. These badges can be added to your website or project readme file to display the status of your code. - -## Badge endpoint - -```text -:///api/badges//status.svg -``` - -The status badge displays the status for the latest build to your default branch (e.g. main). You can customize the branch by adding the `branch` query parameter. - -```diff --:///api/badges//status.svg -+:///api/badges//status.svg?branch= -``` - -Please note status badges do not include pull request results, since the status of a pull request does not provide an accurate representation of your repository state. diff --git a/docs/versioned_docs/version-2.0/20-usage/90-advanced-usage.md b/docs/versioned_docs/version-2.0/20-usage/90-advanced-usage.md deleted file mode 100644 index 56b1a153d9..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/90-advanced-usage.md +++ /dev/null @@ -1,134 +0,0 @@ -# Advanced usage - -## Advanced YAML syntax - -YAML has some advanced syntax features that can be used like variables to reduce duplication in your pipeline config: - -### Anchors & aliases - -You can use [YAML anchors & aliases](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) as variables in your pipeline config. - -To convert this: - -```yaml -steps: - test: - image: golang:1.18 - commands: go test ./... - build: - image: golang:1.18 - commands: build -``` - -Just add a new section called **variables** like this: - -```diff -+variables: -+ - &golang_image 'golang:1.18' - - steps: - test: -- image: golang:1.18 -+ image: *golang_image - commands: go test ./... - build: -- image: golang:1.18 -+ image: *golang_image - commands: build -``` - -### Map merges and overwrites - -```yaml -variables: - - &base-plugin-settings - target: dist - recursive: false - try: true - - &special-setting - special: true - - &some-plugin codeberg.org/6543/docker-images/print_env - -steps: - develop: - image: *some-plugin - settings: - <<: [*base-plugin-settings, *special-setting] # merge two maps into an empty map - when: - branch: develop - - main: - image: *some-plugin - settings: - <<: *base-plugin-settings # merge one map and ... - try: false # ... overwrite original value - ongoing: false # ... adding a new value - when: - branch: main -``` - -### Sequence merges - -```yaml -variables: - pre_cmds: &pre_cmds - - echo start - - whoami - post_cmds: &post_cmds - - echo stop - hello_cmd: &hello_cmd - - echo hello - -steps: - step1: - image: debian - commands: - - <<: *pre_cmds # prepend a sequence - - echo exec step now do dedicated things - - <<: *post_cmds # append a sequence - step2: - image: debian - commands: - - <<: [*pre_cmds, *hello_cmd] # prepend two sequences - - echo echo from second step - - <<: *post_cmds -``` - -### References - -- [Official YAML specification](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) -- [YAML Cheatsheet](https://learnxinyminutes.com/docs/yaml) - -## Persisting environment data between steps - -One can create a file containing environment variables, and then source it in each step that needs them. - -```yaml -steps: - init: - image: bash - commands: - - echo "FOO=hello" >> envvars - - echo "BAR=world" >> envvars - - debug: - image: bash - commands: - - source envvars - - echo $FOO -``` - -## Declaring global variables in `docker-compose.yml` - -As described in [Global environment variables](./50-environment.md#global-environment-variables), one can define global variables: - -```yaml -services: - woodpecker-server: - # ... - environment: - - WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2 - # ... -``` - -Note that this tightly couples the server and app configurations (where the app is a completely separate application). But this is a good option for truly global variables which should apply to all steps in all pipelines for all apps. diff --git a/docs/versioned_docs/version-2.0/20-usage/_category_.yaml b/docs/versioned_docs/version-2.0/20-usage/_category_.yaml deleted file mode 100644 index ba9f729ed0..0000000000 --- a/docs/versioned_docs/version-2.0/20-usage/_category_.yaml +++ /dev/null @@ -1,4 +0,0 @@ -label: 'Usage' -# position: 2 -collapsible: true -collapsed: false diff --git a/docs/versioned_docs/version-2.0/20-usage/cron-settings.png b/docs/versioned_docs/version-2.0/20-usage/cron-settings.png deleted file mode 100644 index d11c507afc..0000000000 Binary files a/docs/versioned_docs/version-2.0/20-usage/cron-settings.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.0/20-usage/project-settings.png b/docs/versioned_docs/version-2.0/20-usage/project-settings.png deleted file mode 100644 index fc29daac84..0000000000 Binary files a/docs/versioned_docs/version-2.0/20-usage/project-settings.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.0/20-usage/repo-list.png b/docs/versioned_docs/version-2.0/20-usage/repo-list.png deleted file mode 100644 index b473800876..0000000000 Binary files a/docs/versioned_docs/version-2.0/20-usage/repo-list.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.0/30-administration/00-deployment/00-overview.md b/docs/versioned_docs/version-2.0/30-administration/00-deployment/00-overview.md deleted file mode 100644 index 1e952c102b..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/00-deployment/00-overview.md +++ /dev/null @@ -1,72 +0,0 @@ -# Overview - -A Woodpecker deployment consists of two parts: - -- A server which is the heart of Woodpecker and ships the web interface. -- Next to one server you can deploy any number of agents which will run the pipelines. - -Each agent is able to process one pipeline step by default. -If you have 4 agents installed and connected to the Woodpecker server, your system will process 4 workflows in parallel. - -:::tip -You can add more agents to increase the number of parallel workflows or set the agent's `WOODPECKER_MAX_WORKFLOWS=1` environment variable to increase the number of parallel workflows for that agent. -::: - -## Which version of Woodpecker should I use? - -Woodpecker is having two different kinds of releases: **stable** and **next**. - -## Hardware Requirements - -Below are minimal resources requirements for Woodpecker components itself: - -| Component | Memory | CPU | -| --------- | ------ | --- | -| Server | 200 MB | 1 | -| Agent | 32 MB | 1 | - -Note, that those values do not include the operating system or workload (pipelines execution) resources consumption. - -In addition you need at least some kind of database which requires additional resources depending on the selected database system. - -## Installation - -You can install Woodpecker on multiple ways: - -- Using [docker-compose](./10-docker-compose.md) with the official [container images](./10-docker-compose.md#docker-images) -- Using [Kubernetes](./20-kubernetes.md) via the Woodpecker Helm chart -- Using binaries, DEBs or RPMs you can download from [latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest) - -## Authentication - -Authentication is done using OAuth and is delegated to your forge which is configured using environment variables. - -See the complete reference for all supported forges [here](../11-forges/10-overview.md). - -## Database - -By default Woodpecker uses a SQLite database which requires zero installation or configuration. See the [database settings](../30-database.md) page to further configure it or use MySQL or Postgres. - -## SSL - -Woodpecker supports SSL configuration by using Let's encrypt or by using own certificates. See the [SSL guide](../60-ssl.md). You can also put it behind a [reverse proxy](#behind-a-proxy) - -## Metrics - -A [Prometheus endpoint](../90-prometheus.md) is exposed. - -## Behind a proxy - -See the [proxy guide](../70-proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok. - -In the case you need to use Woodpecker with a URL path prefix (like: ), you can use the option [`WOODPECKER_ROOT_PATH`](../10-server-config.md#woodpecker_root_path). - -## Third-party installation methods - -:::info -These installation methods are not officially supported. If you experience issues with them, please open issues in the specific repositories. -::: - -- Using [NixOS](./30-nixos.md) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker) -- [Using YunoHost](https://apps.yunohost.org/app/woodpecker) -- [On Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html) diff --git a/docs/versioned_docs/version-2.0/30-administration/00-deployment/10-docker-compose.md b/docs/versioned_docs/version-2.0/30-administration/00-deployment/10-docker-compose.md deleted file mode 100644 index e649301f2a..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/00-deployment/10-docker-compose.md +++ /dev/null @@ -1,154 +0,0 @@ -# docker-compose - -The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start a Woodpecker server with a single agent. - -It relies on a number of environment variables that you must set before running `docker-compose up`. The variables are described below. - -```yaml -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - image: woodpeckerci/woodpecker-server:latest - ports: - - 8000:8000 - volumes: - - woodpecker-server-data:/var/lib/woodpecker/ - environment: - - WOODPECKER_OPEN=true - - WOODPECKER_HOST=${WOODPECKER_HOST} - - WOODPECKER_GITHUB=true - - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT} - - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET} - - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} - - woodpecker-agent: - image: woodpeckerci/woodpecker-agent:latest - command: agent - restart: always - depends_on: - - woodpecker-server - volumes: - - woodpecker-agent-config:/etc/woodpecker - - /var/run/docker.sock:/var/run/docker.sock - environment: - - WOODPECKER_SERVER=woodpecker-server:9000 - - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} - -volumes: - woodpecker-server-data: - woodpecker-agent-config: -``` - -Woodpecker needs to know its own address. You must therefore provide the public address of it in `://` format. Please omit trailing slashes: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_HOST=${WOODPECKER_HOST} -``` - -Woodpecker can also have its port's configured. It uses a separate port for gRPC and for HTTP. The agent performs gRPC calls and connects to the gRPC port. -They can be configured with ADDR variables: - -```diff -# docker-compose.yml -version: '3' -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR} -+ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR} -``` - -Reverse proxying can also be [configured for gRPC](../proxy#caddy). If the agents are connecting over the internet, it should also be SSL encrypted. The agent then needs to be configured to be secure: - -```diff -# docker-compose.yml -version: '3' -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_GRPC_SECURE=true # defaults to false -+ - WOODPECKER_GRPC_VERIFY=true # default -``` - -As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon: - -```diff -# docker-compose.yml -version: '3' - -services: - [...] - woodpecker-agent: - [...] -+ volumes: -+ - /var/run/docker.sock:/var/run/docker.sock -``` - -Agents require the server address for agent-to-server communication. The agent connects to the server's gRPC port: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-agent: - [...] - environment: -+ - WOODPECKER_SERVER=woodpecker-server:9000 -``` - -The server and agents use a shared secret to authenticate communication. This should be a random string of your choosing and should be kept private. You can generate such string with `openssl rand -hex 32`: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} - woodpecker-agent: - [...] - environment: - - [...] -+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} -``` - -## Docker images - -Image variants: - -- The `latest` image is the latest stable release -- The `vX.X.X` images are stable releases -- The `vX.X` images are based on the current release branch (e.g. `release/v1.0`) and can be used to get bugfixes asap -- The `next` images are based on the current `main` branch and should not be used for production environments - -```bash -# server -docker pull woodpeckerci/woodpecker-server:latest -docker pull woodpeckerci/woodpecker-server:latest-alpine - -# agent -docker pull woodpeckerci/woodpecker-agent:latest -docker pull woodpeckerci/woodpecker-agent:latest-alpine - -# cli -docker pull woodpeckerci/woodpecker-cli:latest -docker pull woodpeckerci/woodpecker-cli:latest-alpine -``` diff --git a/docs/versioned_docs/version-2.0/30-administration/00-deployment/20-kubernetes.md b/docs/versioned_docs/version-2.0/30-administration/00-deployment/20-kubernetes.md deleted file mode 100644 index f931c3e785..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/00-deployment/20-kubernetes.md +++ /dev/null @@ -1,9 +0,0 @@ -# Kubernetes - -We recommended to deploy Woodpecker using the [Woodpecker helm chart](https://github.com/woodpecker-ci/helm). -Have a look at the [`values.yaml`](https://github.com/woodpecker-ci/helm/blob/main/charts/woodpecker/values.yaml) config files for all available settings. - -The chart contains two subcharts, `server` and `agent` which are automatically configured as needed. -The chart started off with two independent charts but was merged into one to simplify the deployment at start of 2023. - -A couple of backend-specific config env vars exists which are described in the [kubernetes backend docs](../22-backends/40-kubernetes.md). diff --git a/docs/versioned_docs/version-2.0/30-administration/00-deployment/30-nixos.md b/docs/versioned_docs/version-2.0/30-administration/00-deployment/30-nixos.md deleted file mode 100644 index 148fbd581d..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/00-deployment/30-nixos.md +++ /dev/null @@ -1,88 +0,0 @@ -# NixOS - -:::info -Note that this module is not maintained by the woodpecker-developers. -If you experience issues please open a bug report in the [nixpkgs repo](https://github.com/NixOS/nixpkgs/issues/new/choose) where the module is maintained. -::: - -The NixOS install is in theory quite similar to the binary install and supports multiple backends. -In practice, the settings are specified declaratively in the NixOS configuration and no manual steps need to be taken. - -## General Configuration - -```nix -{ config -, ... -}: -let - domain = "woodpecker.example.org"; -in -{ - # This automatically sets up certificates via let's encrypt - security.acme.defaults.email = "acme@example.com"; - security.acme.acceptTerms = true; - security.acme.certs."${domain}" = { }; - - # Setting up a nginx proxy that handles tls for us - networking.firewall.allowedTCPPorts = [ 80 443 ]; - services.nginx = { - enable = true; - recommendedTlsSettings = true; - recommendedOptimisation = true; - recommendedProxySettings = true; - virtualHosts."${domain}" = { - enableACME = true; - forceSSL = true; - locations."/" = { - proxyPass = "http://localhost:3007"; - }; - }; - }; - - services.woodpecker-server = { - enable = true; - environment = { - WOODPECKER_HOST = "https://${domain}"; - WOODPECKER_SERVER_ADDR = ":3007"; - WOODPECKER_OPEN = "true"; - }; - # You can pass a file with env vars to the system it could look like: - # WOODPECKER_AGENT_SECRET=XXXXXXXXXXXXXXXXXXXXXX - environmentFile = "/path/to/my/secrets/file"; - }; - - # This sets up a woodpecker agent - services.woodpecker-agents.agents."docker" = { - enable = true; - # We need this to talk to the podman socket - extraGroups = [ "podman" ]; - environment = { - WOODPECKER_SERVER = "localhost:9000"; - WOODPECKER_MAX_WORKFLOWS = "4"; - DOCKER_HOST = "unix:///run/podman/podman.sock"; - WOODPECKER_BACKEND = "docker"; - }; - # Same as with woodpecker-server - environmentFile = [ "/var/lib/secrets/woodpecker.env" ]; - }; - - # Here we setup podman and enable dns - virtualisation.podman = { - enable = true; - defaultNetwork.settings = { - dns_enabled = true; - }; - }; - # This is needed for podman to be able to talk over dns - networking.firewall.interfaces."podman0" = { - allowedUDPPorts = [ 53 ]; - allowedTCPPorts = [ 53 ]; - }; -} -``` - -All configuration options can be found via [NixOS Search](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker) - -## Tips and tricks - -There are some resources on how to utilize Woodpecker more effectively with NixOS on the [Awesome Woodpecker](../../92-awesome.md) page, like using the runners nix-store in the pipeline diff --git a/docs/versioned_docs/version-2.0/30-administration/00-deployment/_category_.yaml b/docs/versioned_docs/version-2.0/30-administration/00-deployment/_category_.yaml deleted file mode 100644 index af150d5719..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/00-deployment/_category_.yaml +++ /dev/null @@ -1,3 +0,0 @@ -label: 'Deployment' -collapsible: true -collapsed: true diff --git a/docs/versioned_docs/version-2.0/30-administration/10-server-config.md b/docs/versioned_docs/version-2.0/30-administration/10-server-config.md deleted file mode 100644 index c5f883be1e..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/10-server-config.md +++ /dev/null @@ -1,620 +0,0 @@ -# Server configuration - -## User registration - -Woodpecker does not have its own user registry; users are provided from your [forge](./11-forges/10-overview.md) (using OAuth2). - -Registration is closed by default (`WOODPECKER_OPEN=false`). If registration is open (`WOODPECKER_OPEN=true`) then every user with an account at the configured forge can login to Woodpecker. - -To open registration: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_OPEN=true -``` - -You can **also restrict** registration, by keep registration closed and ...\ -... **adding** new **users manually** via the CLI: `woodpecker-cli user add`, or\ -... allowing specific **admin users** via the `WOODPECKER_ADMIN` setting, or\ -by open registration and **filter by organization** membership through the `WOODPECKER_ORGS` setting. - -### To close registration, but allow specific admin users - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_OPEN=false -+ - WOODPECKER_ADMIN=johnsmith,janedoe -``` - -### To only allow registration of users, who are members of approved organizations - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_OPEN=true -+ - WOODPECKER_ORGS=dolores,dogpatch -``` - -## Administrators - -Administrators should also be enumerated in your configuration. - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_ADMIN=johnsmith,janedoe -``` - -## Filtering repositories - -Woodpecker operates with the user's OAuth permission. Due to the coarse permission handling of GitHub, you may end up syncing more repos into Woodpecker than preferred. - -Use the `WOODPECKER_REPO_OWNERS` variable to filter which GitHub user's repos should be synced only. You typically want to put here your company's GitHub name. - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_REPO_OWNERS=mycompany,mycompanyossgithubuser -``` - -## Global registry setting - -If you want to make available a specific private registry to all pipelines, use the `WOODPECKER_DOCKER_CONFIG` server configuration. -Point it to your server's docker config. - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - volumes: - - [...] -+ - /home/user/.docker/config.json:/root/.docker/config.json:ro - environment: - - [...] -+ - WOODPECKER_DOCKER_CONFIG=/root/.docker/config.json -``` - -## Handling sensitive data in docker-compose and docker-swarm - -To handle sensitive data in docker-compose or docker-swarm configurations there are several options: - -For docker-compose you can use a .env file next to your compose configuration to store the secrets outside of the compose file. While this separates configuration from secrets it is still not very secure. - -Alternatively use docker-secrets. As it may be difficult to use docker secrets for environment variables woodpecker allows to read sensible data from files by providing a `*_FILE` option of all sensible configuration variables. Woodpecker will try to read the value directly from this file. Keep in mind that when the original environment variable gets specified at the same time it will override the value read from the file. - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_AGENT_SECRET_FILE=/run/secrets/woodpecker-agent-secret -+ secrets: -+ - woodpecker-agent-secret -+ -+secrets: -+ woodpecker-agent-secret: -+ external: true -``` - -Store a value to a docker secret like this: -`echo "my_agent_secret_key" | docker secret create woodpecker-agent-secret -` - -or generate a random one like this: - -`openssl rand -hex 32 | docker secret create woodpecker-agent-secret -` - -## Custom Javascript and CSS Styling (a.k.a. white-labeling) - -Woodpecker supports custom styling of the Web UI by providing custom JS and CSS files. -These files must be present in the server's filesystem. -They can be backed in a Docker image or mounted from a ConfigMap inside a Kubernetes environment. -The configuration variables are independent of each other, which means it can be just one file present, or both. - -```text -WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.css -WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.js -``` - -The examples below show how to place a banner message in the top navigation bar of Woodpecker. - -### woodpecker.css - -```css -.banner-message { - position: absolute; - width: 280px; - height: 40px; - margin-left: 240px; - margin-top: 5px; - padding-top: 5px; - font-weight: bold; - background: red no-repeat; - text-align: center; -} -``` - -### woodpecker.js - -```javascript -// place/copy a minified version of jQuery or ZeptoJS here ... -!(function () { - 'use strict'; - function e() {} /*...*/ -})(); - -$().ready(function () { - $('.app nav img').first().htmlAfter(""); -}); -``` - -## All server configuration options - -The following list describes all available server configuration options. - -### `WOODPECKER_LOG_LEVEL` - -> Default: empty - -Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty. - -### `WOODPECKER_LOG_FILE` - -> Default: `stderr` - -Output destination for logs. -'stdout' and 'stderr' can be used as special keywords. - -### `WOODPECKER_LOG_XORM` - -> Default: `false` - -Enable XORM logs. - -### `WOODPECKER_LOG_XORM_SQL` - -> Default: `false` - -Enable XORM SQL command logs. - -### `WOODPECKER_DEBUG_PRETTY` - -> Default: `false` - -Enable pretty-printed debug output. - -### `WOODPECKER_DEBUG_NOCOLOR` - -> Default: `true` - -Disable colored debug output. - -### `WOODPECKER_HOST` - -> Default: empty - -Server fully qualified URL of the user-facing hostname and path prefix. - -Example: `WOODPECKER_HOST=http://woodpecker.example.org` or `WOODPECKER_HOST=http://example.org/woodpecker` - -### `WOODPECKER_WEBHOOK_HOST` - -> Default: value from `WOODPECKER_HOST` config env - -Server fully qualified URL of the Webhook-facing hostname and path prefix. - -Example: `WOODPECKER_WEBHOOK_HOST=http://woodpecker-server.cicd.svc.cluster.local:8000` - -### `WOODPECKER_SERVER_ADDR` - -> Default: `:8000` - -Configures the HTTP listener port. - -### `WOODPECKER_SERVER_ADDR_TLS` - -> Default: `:443` - -Configures the HTTPS listener port when SSL is enabled. - -### `WOODPECKER_SERVER_CERT` - -> Default: empty - -Path to an SSL certificate used by the server to accept HTTPS requests. - -Example: `WOODPECKER_SERVER_CERT=/path/to/cert.pem` - -### `WOODPECKER_SERVER_KEY` - -> Default: empty - -Path to an SSL certificate key used by the server to accept HTTPS requests. - -Example: `WOODPECKER_SERVER_KEY=/path/to/key.pem` - -### `WOODPECKER_CUSTOM_CSS_FILE` - -> Default: empty - -File path for the server to serve a custom .CSS file, used for customizing the UI. -Can be used for showing banner messages, logos, or environment-specific hints (a.k.a. white-labeling). -The file must be UTF-8 encoded, to ensure all special characters are preserved. - -Example: `WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.css` - -### `WOODPECKER_CUSTOM_JS_FILE` - -> Default: empty - -File path for the server to serve a custom .JS file, used for customizing the UI. -Can be used for showing banner messages, logos, or environment-specific hints (a.k.a. white-labeling). -The file must be UTF-8 encoded, to ensure all special characters are preserved. - -Example: `WOODPECKER_CUSTOM_JS_FILE=/usr/local/www/woodpecker.js` - -### `WOODPECKER_LETS_ENCRYPT` - -> Default: `false` - -Automatically generates an SSL certificate using Let's Encrypt, and configures the server to accept HTTPS requests. - -### `WOODPECKER_GRPC_ADDR` - -> Default: `:9000` - -Configures the gRPC listener port. - -### `WOODPECKER_GRPC_SECRET` - -> Default: `secret` - -Configures the gRPC JWT secret. - -### `WOODPECKER_GRPC_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GRPC_SECRET` from the specified filepath. - -### `WOODPECKER_METRICS_SERVER_ADDR` - -> Default: empty - -Configures an unprotected metrics endpoint. An empty value disables the metrics endpoint completely. - -Example: `:9001` - -### `WOODPECKER_ADMIN` - -> Default: empty - -Comma-separated list of admin accounts. - -Example: `WOODPECKER_ADMIN=user1,user2` - -### `WOODPECKER_ORGS` - -> Default: empty - -Comma-separated list of approved organizations. - -Example: `org1,org2` - -### `WOODPECKER_REPO_OWNERS` - -> Default: empty - -Comma-separated list of syncable repo owners. ??? - -Example: `user1,user2` - -### `WOODPECKER_OPEN` - -> Default: `false` - -Enable to allow user registration. - -### `WOODPECKER_AUTHENTICATE_PUBLIC_REPOS` - -> Default: `false` - -Always use authentication to clone repositories even if they are public. Needed if the forge requires to always authenticate as used by many companies. - -### `WOODPECKER_DEFAULT_CANCEL_PREVIOUS_PIPELINE_EVENTS` - -> Default: `pull_request, push` - -List of event names that will be canceled when a new pipeline for the same context (tag, branch) is created. - -### `WOODPECKER_DEFAULT_CLONE_IMAGE` - -> Default is defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go) - -The default docker image to be used when cloning the repo - -### `WOODPECKER_DEFAULT_PIPELINE_TIMEOUT` - -> 60 (minutes) - -The default time for a repo in minutes before a pipeline gets killed - -### `WOODPECKER_MAX_PIPELINE_TIMEOUT` - -> 120 (minutes) - -The maximum time in minutes you can set in the repo settings before a pipeline gets killed - -### `WOODPECKER_SESSION_EXPIRES` - -> Default: `72h` - -Configures the session expiration time. -Context: when someone does log into Woodpecker, a temporary session token is created. -As long as the session is valid (until it expires or log-out), -a user can log into Woodpecker, without re-authentication. - -### `WOODPECKER_ESCALATE` - -> Defaults are defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go) - -Docker images to run in privileged mode. Only change if you are sure what you do! - - - -### `WOODPECKER_DOCKER_CONFIG` - -> Default: empty - -Configures a specific private registry config for all pipelines. - -Example: `WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json` - - - -### `WOODPECKER_AGENT_SECRET` - -> Default: empty - -A shared secret used by server and agents to authenticate communication. A secret can be generated by `openssl rand -hex 32`. - -### `WOODPECKER_AGENT_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_AGENT_SECRET` from the specified filepath - -### `WOODPECKER_KEEPALIVE_MIN_TIME` - -> Default: empty - -Server-side enforcement policy on the minimum amount of time a client should wait before sending a keepalive ping. - -Example: `WOODPECKER_KEEPALIVE_MIN_TIME=10s` - -### `WOODPECKER_DATABASE_DRIVER` - -> Default: `sqlite3` - -The database driver name. Possible values are `sqlite3`, `mysql` or `postgres`. - -### `WOODPECKER_DATABASE_DATASOURCE` - -> Default: `woodpecker.sqlite` - -The database connection string. The default value is the path of the embedded SQLite database file. - -Example: - -```bash -# MySQL -# https://github.com/go-sql-driver/mysql#dsn-data-source-name -WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true - -# PostgreSQL -# https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING -WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker?sslmode=disable -``` - -### `WOODPECKER_DATABASE_DATASOURCE_FILE` - -> Default: empty - -Read the value for `WOODPECKER_DATABASE_DATASOURCE` from the specified filepath - -### `WOODPECKER_ENCRYPTION_KEY` - -> Default: empty - -Encryption key used to encrypt secrets in DB. See [secrets encryption](./40-encryption.md) - -### `WOODPECKER_ENCRYPTION_KEY_FILE` - -> Default: empty - -Read the value for `WOODPECKER_ENCRYPTION_KEY` from the specified filepath - -### `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE` - -> Default: empty - -Filepath to encryption keyset used to encrypt secrets in DB. See [secrets encryption](./40-encryption.md) - -### `WOODPECKER_ENCRYPTION_DISABLE` - -> Default: empty - -Boolean flag to decrypt secrets in DB and disable server encryption. See [secrets encryption](./40-encryption.md) - -### `WOODPECKER_PROMETHEUS_AUTH_TOKEN` - -> Default: empty - -Token to secure the Prometheus metrics endpoint. -Must be set to enable the endpoint. - -### `WOODPECKER_PROMETHEUS_AUTH_TOKEN_FILE` - -> Default: empty - -Read the value for `WOODPECKER_PROMETHEUS_AUTH_TOKEN` from the specified filepath - -### `WOODPECKER_STATUS_CONTEXT` - -> Default: `ci/woodpecker` - -Context prefix Woodpecker will use to publish status messages to SCM. You probably will only need to change it if you run multiple Woodpecker instances for a single repository. - -### `WOODPECKER_STATUS_CONTEXT_FORMAT` - -> Default: `{{ .context }}/{{ .event }}/{{ .workflow }}{{if not (eq .axis_id 0)}}/{{.axis_id}}{{end}}` - -Template for the status messages published to forges, uses [Go templates](https://pkg.go.dev/text/template) as template language. -Supported variables: - -- `context`: Woodpecker's context (see `WOODPECKER_STATUS_CONTEXT`) -- `event`: the event which started the pipeline -- `workflow`: the workflow's name -- `owner`: the repo's owner -- `repo`: the repo's name - ---- - -### `WOODPECKER_LIMIT_MEM_SWAP` - -> Default: `0` - -The maximum amount of memory a single pipeline container is allowed to swap to disk, configured in bytes. There is no limit if `0`. - -### `WOODPECKER_LIMIT_MEM` - -> Default: `0` - -The maximum amount of memory a single pipeline container can use, configured in bytes. There is no limit if `0`. - -### `WOODPECKER_LIMIT_SHM_SIZE` - -> Default: `0` - -The maximum amount of memory of `/dev/shm` allowed in bytes. There is no limit if `0`. - -### `WOODPECKER_LIMIT_CPU_QUOTA` - -> Default: `0` - -The number of microseconds per CPU period that the container is limited to before throttled. There is no limit if `0`. - -### `WOODPECKER_LIMIT_CPU_SHARES` - -> Default: `0` - -The relative weight vs. other containers. - -### `WOODPECKER_LIMIT_CPU_SET` - -> Default: empty - -Comma-separated list to limit the specific CPUs or cores a pipeline container can use. - -Example: `WOODPECKER_LIMIT_CPU_SET=1,2` - -### `WOODPECKER_CONFIG_SERVICE_ENDPOINT` - -> Default: `` - -Specify a configuration service endpoint, see [Configuration Extension](./100-external-configuration-api.md) - -### `WOODPECKER_FORGE_TIMEOUT` - -> Default: 3sec - -Specify how many seconds before timeout when fetching the Woodpecker configuration from a Forge - -### `WOODPECKER_ROOT_PATH` - -> Default: extracted from `WOODPECKER_HOST` - -Server URL path prefix (used for statics loading when having a url path prefix), should start with `/` - -Example: `WOODPECKER_ROOT_PATH=/woodpecker` - -### `WOODPECKER_ENABLE_SWAGGER` - -> Default: true - -Enable the Swagger UI for API documentation. - ---- - -### `WOODPECKER_GITHUB_...` - -See [GitHub configuration](forges/github/#all-github-configuration-options) - -### `WOODPECKER_GITEA_...` - -See [Gitea configuration](forges/gitea/#configuration) - -### `WOODPECKER_BITBUCKET_...` - -See [Bitbucket configuration](forges/bitbucket/#configuration) - -### `WOODPECKER_GITLAB_...` - -See [Gitlab configuration](forges/gitlab/#configuration) diff --git a/docs/versioned_docs/version-2.0/30-administration/100-external-configuration-api.md b/docs/versioned_docs/version-2.0/30-administration/100-external-configuration-api.md deleted file mode 100644 index 47e6277acb..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/100-external-configuration-api.md +++ /dev/null @@ -1,106 +0,0 @@ -# External Configuration API - -To provide additional management and preprocessing capabilities for pipeline configurations Woodpecker supports an HTTP API which can be enabled to call an external config service. -Before the run or restart of any pipeline Woodpecker will make a POST request to an external HTTP API sending the current repository, build information and all current config files retrieved from the repository. The external API can then send back new pipeline configurations that will be used immediately or respond with `HTTP 204` to tell the system to use the existing configuration. - -Every request sent by Woodpecker is signed using a [http-signature](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures) by a private key (ed25519) generated on the first start of the Woodpecker server. You can get the public key for the verification of the http-signature from `http(s)://your-woodpecker-server/api/signature/public-key`. - -A simplistic example configuration service can be found here: [https://github.com/woodpecker-ci/example-config-service](https://github.com/woodpecker-ci/example-config-service) - -:::warning -You need to trust the external config service as it is getting secret information about the repository and pipeline and has the ability to change pipeline configs that could run malicious tasks. -::: - -## Config - -```bash -# Server -# ... -WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig -``` - -### Example request made by Woodpecker - -```json -{ - "repo": { - "id": 100, - "uid": "", - "user_id": 0, - "namespace": "", - "name": "woodpecker-testpipe", - "slug": "", - "scm": "git", - "git_http_url": "", - "git_ssh_url": "", - "link": "", - "default_branch": "", - "private": true, - "visibility": "private", - "active": true, - "config": "", - "trusted": false, - "protected": false, - "ignore_forks": false, - "ignore_pulls": false, - "cancel_pulls": false, - "timeout": 60, - "counter": 0, - "synced": 0, - "created": 0, - "updated": 0, - "version": 0 - }, - "pipeline": { - "author": "myUser", - "author_avatar": "https://myforge.com/avatars/d6b3f7787a685fcdf2a44e2c685c7e03", - "author_email": "my@email.com", - "branch": "main", - "changed_files": ["somefilename.txt"], - "commit": "2fff90f8d288a4640e90f05049fe30e61a14fd50", - "created_at": 0, - "deploy_to": "", - "enqueued_at": 0, - "error": "", - "event": "push", - "finished_at": 0, - "id": 0, - "link_url": "https://myforge.com/myUser/woodpecker-testpipe/commit/2fff90f8d288a4640e90f05049fe30e61a14fd50", - "message": "test old config\n", - "number": 0, - "parent": 0, - "ref": "refs/heads/main", - "refspec": "", - "clone_url": "", - "reviewed_at": 0, - "reviewed_by": "", - "sender": "myUser", - "signed": false, - "started_at": 0, - "status": "", - "timestamp": 1645962783, - "title": "", - "updated_at": 0, - "verified": false - }, - "configs": [ - { - "name": ".woodpecker.yml", - "data": "steps:\n backend:\n image: alpine\n commands:\n - echo \"Hello there from Repo (.woodpecker.yml)\"\n" - } - ] -} -``` - -### Example response structure - -```json -{ - "configs": [ - { - "name": "central-override", - "data": "steps:\n backend:\n image: alpine\n commands:\n - echo \"Hello there from ConfigAPI\"\n" - } - ] -} -``` diff --git a/docs/versioned_docs/version-2.0/30-administration/11-forges/10-overview.md b/docs/versioned_docs/version-2.0/30-administration/11-forges/10-overview.md deleted file mode 100644 index 3087ec059f..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/11-forges/10-overview.md +++ /dev/null @@ -1,12 +0,0 @@ -# Overview - -## Supported features - -| Feature | [GitHub](github/) | [Gitea / Forgejo](gitea/) | [Gitlab](gitlab/) | [Bitbucket](bitbucket/) | -| ------------------------------------------------------------- | :----------------: | :-----------------------: | :----------------: | :---------------------: | -| Event: Push | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| Event: Tag | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| Event: Pull-Request | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| Event: Deploy | :white_check_mark: | :x: | :x: | :x: | -| [Multiple workflows](../../20-usage/25-workflows.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| [when.path filter](../../20-usage/20-workflow-syntax.md#path) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | diff --git a/docs/versioned_docs/version-2.0/30-administration/11-forges/20-github.md b/docs/versioned_docs/version-2.0/30-administration/11-forges/20-github.md deleted file mode 100644 index 5a248c4940..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/11-forges/20-github.md +++ /dev/null @@ -1,49 +0,0 @@ -# GitHub - -Woodpecker comes with built-in support for GitHub and GitHub Enterprise. -To use Woodpecker with GitHub the following environment variables should be set for the server component: - -```bash -WOODPECKER_GITHUB=true -WOODPECKER_GITHUB_CLIENT=YOUR_GITHUB_CLIENT_ID -WOODPECKER_GITHUB_SECRET=YOUR_GITHUB_CLIENT_SECRET -``` - -You will get these values from GitHub when you register your OAuth application. -To do so, go to Settings -> Developer Settings -> GitHub Apps -> New Oauth2 App. - -:::warning -Do not use a "GitHub App" instead of an Oauth2 app as the former will not work correctly with Woodpecker right now (because user access tokens are not being refreshed automatically) -::: - -## App Settings - -- Name: An arbitrary name for your App -- Homepage URL: The URL of your Woodpecker instance -- Callback URL: `https:///authorize` -- (optional) Upload the Woodpecker Logo: - -## Client Secret Creation - -After your App has been created, you can generate a client secret. -Use this one for the `WOODPECKER_GITHUB_SECRET` environment variable. - -## All GitHub Configuration Options - -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. - -- `WOODPECKER_GITHUB` - Enables the GitHub driver (Default: `false`) - -- `WOODPECKER_GITHUB_URL` - Configures the GitHub server address (Default: `https://github.com`) - -- `WOODPECKER_GITHUB_CLIENT` - Configures the GitHub OAuth client id to authorize access (Default: empty) - -- `WOODPECKER_GITHUB_CLIENT_FILE` - Read the value for `WOODPECKER_GITHUB_CLIENT` from the specified filepath (Default: empty) - -- `WOODPECKER_GITHUB_SECRET` - Configures the GitHub OAuth client secret. This is used to authorize access. (Default: empty) - -- `WOODPECKER_GITHUB_SECRET_FILE` - Read the value for `WOODPECKER_GITHUB_SECRET` from the specified filepath (Default: empty) - - `WOODPECKER_GITHUB_MERGE_REF` - (Default: `true`) - -- `WOODPECKER_GITHUB_SKIP_VERIFY` - Configure if SSL verification should be skipped (Default: `false`) diff --git a/docs/versioned_docs/version-2.0/30-administration/11-forges/30-gitea.md b/docs/versioned_docs/version-2.0/30-administration/11-forges/30-gitea.md deleted file mode 100644 index b4d7f4e033..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/11-forges/30-gitea.md +++ /dev/null @@ -1,104 +0,0 @@ -# Gitea / Forgejo - -Woodpecker comes with built-in support for Gitea and the "soft" fork Forgejo. To enable Gitea you should configure the Woodpecker container using the following environment variables: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_GITEA=true -+ - WOODPECKER_GITEA_URL=${WOODPECKER_GITEA_URL} -+ - WOODPECKER_GITEA_CLIENT=${WOODPECKER_GITEA_CLIENT} -+ - WOODPECKER_GITEA_SECRET=${WOODPECKER_GITEA_SECRET} - - woodpecker-agent: - [...] -``` - -## Gitea on the same host - -If you have Gitea also running on the same host within a container, make sure the agent does have access to it. -The agent tries to clone using the URL which Gitea reports through its API. For simplified connectivity, you should add the woodpecker agent to the same docker network as Gitea is in. -Otherwise, the communication should go via the `docker0` gateway (usually 172.17.0.1). - -To configure the Docker network if the network's name is `gitea`, configure it like this: - -```diff -# docker-compose.yml -version: '3' - -services: - [...] - woodpecker-agent: - [...] - environment: - - [...] -+ - WOODPECKER_BACKEND_DOCKER_NETWORK=gitea -``` - -## Registration - -Register your application with Gitea to create your client id and secret. You can find the OAuth applications settings of Gitea at `https://gitea./user/settings/`. It is very import the authorization callback URL matches your http(s) scheme and hostname exactly with `https:///authorize` as the path. - -If you run the Woodpecker CI server on the same host as the Gitea instance, you might also need to allow local connections in Gitea, since version `v1.16`. Otherwise webhooks will fail. Add the following lines to your Gitea configuration (usually at `/etc/gitea/conf/app.ini`). - -```ini -... -[webhook] -ALLOWED_HOST_LIST=external,loopback -``` - -For reference see [Configuration Cheat Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/#webhook-webhook). - -![gitea oauth setup](gitea_oauth.gif) - -## 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. - -### `WOODPECKER_GITEA` - -> Default: `false` - -Enables the Gitea driver. - -### `WOODPECKER_GITEA_URL` - -> Default: `https://try.gitea.io` - -Configures the Gitea server address. - -### `WOODPECKER_GITEA_CLIENT` - -> Default: empty - -Configures the Gitea OAuth client id. This is used to authorize access. - -### `WOODPECKER_GITEA_CLIENT_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITEA_CLIENT` from the specified filepath - -### `WOODPECKER_GITEA_SECRET` - -> Default: empty - -Configures the Gitea OAuth client secret. This is used to authorize access. - -### `WOODPECKER_GITEA_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITEA_SECRET` from the specified filepath - -### `WOODPECKER_GITEA_SKIP_VERIFY` - -> Default: `false` - -Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-2.0/30-administration/11-forges/40-gitlab.md b/docs/versioned_docs/version-2.0/30-administration/11-forges/40-gitlab.md deleted file mode 100644 index bda58699df..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/11-forges/40-gitlab.md +++ /dev/null @@ -1,74 +0,0 @@ -# GitLab - -Woodpecker comes with built-in support for the GitLab version 8.2 and higher. To enable GitLab you should configure the Woodpecker container using the following environment variables: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: -+ - WOODPECKER_GITLAB=true -+ - WOODPECKER_GITLAB_URL=http://gitlab.mycompany.com -+ - WOODPECKER_GITLAB_CLIENT=95c0282573633eb25e82 -+ - WOODPECKER_GITLAB_SECRET=30f5064039e6b359e075 - - woodpecker-agent: - [...] -``` - -## Registration - -You must register your application with GitLab in order to generate a Client and Secret. Navigate to your account settings and choose Applications from the menu, and click New Application. - -Please use `http://woodpecker.mycompany.com/authorize` as the Authorization callback URL. Grant `api` scope to the application. - -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`. - -## 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. - -### `WOODPECKER_GITLAB` - -> Default: `false` - -Enables the GitLab driver. - -### `WOODPECKER_GITLAB_URL` - -> Default: `https://gitlab.com` - -Configures the GitLab server address. - -### `WOODPECKER_GITLAB_CLIENT` - -> Default: empty - -Configures the GitLab OAuth client id. This is used to authorize access. - -### `WOODPECKER_GITLAB_CLIENT_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITLAB_CLIENT` from the specified filepath - -### `WOODPECKER_GITLAB_SECRET` - -> Default: empty - -Configures the GitLab OAuth client secret. This is used to authorize access. - -### `WOODPECKER_GITLAB_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITLAB_SECRET` from the specified filepath - -### `WOODPECKER_GITLAB_SKIP_VERIFY` - -> Default: `false` - -Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-2.0/30-administration/11-forges/50-bitbucket.md b/docs/versioned_docs/version-2.0/30-administration/11-forges/50-bitbucket.md deleted file mode 100644 index 157d74acd0..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/11-forges/50-bitbucket.md +++ /dev/null @@ -1,84 +0,0 @@ -# Bitbucket - -Woodpecker comes with built-in support for Bitbucket Cloud. To enable Bitbucket Cloud you should configure the Woodpecker container using the following environment variables: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_BITBUCKET=true -+ - WOODPECKER_BITBUCKET_CLIENT=... # called "Key" in Bitbucket -+ - WOODPECKER_BITBUCKET_SECRET=... - - woodpecker-agent: - [...] -``` - -## Registration - -You must register an OAuth application at Bitbucket in order to get a key and secret combination for woodpecker. Navigate to your workspace settings and choose `OAuth consumers` from the menu, and finally click `Add Consumer` (the url should be like: `https://bitbucket.org/[your-project-name]/workspace/settings/api`). - -Please set a name and set the `Callback URL` like this: - -```nohighlight -https:///authorize -``` - -![bitbucket oauth setup](bitbucket_oauth.png) - -Please also be sure to check the following permissions: - -```nohighlight -Account: Email, Read -Workspace membership: Read -Projects: Read -Repositories: Read -Pull requests: Read -Webhooks: Read and Write -``` - -![bitbucket permissions](bitbucket_permissions.png) - -## 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. - -### `WOODPECKER_BITBUCKET` - -> Default: `false` - -Enables the Bitbucket driver. - -### `WOODPECKER_BITBUCKET_CLIENT` - -> Default: empty - -Configures the Bitbucket OAuth client key. This is used to authorize access. - -### `WOODPECKER_BITBUCKET_CLIENT_FILE` - -> Default: empty - -Read the value for `WOODPECKER_BITBUCKET_CLIENT` from the specified filepath - -### `WOODPECKER_BITBUCKET_SECRET` - -> Default: empty - -Configures the Bitbucket OAuth client secret. This is used to authorize access. - -### `WOODPECKER_BITBUCKET_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_BITBUCKET_SECRET` from the specified filepath - -## Missing Features - -Merge requests are not currently supported. We are interested in patches to include this functionality. -If you are interested in contributing to Woodpecker and submitting a patch please **contact us** via [Discord](https://discord.gg/fcMQqSMXJy) or [Matrix](https://matrix.to/#/#WoodpeckerCI-Develop:obermui.de). diff --git a/docs/versioned_docs/version-2.0/30-administration/11-forges/_category_.yaml b/docs/versioned_docs/version-2.0/30-administration/11-forges/_category_.yaml deleted file mode 100644 index 01e4025a5a..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/11-forges/_category_.yaml +++ /dev/null @@ -1,3 +0,0 @@ -label: 'Forges' -collapsible: true -collapsed: true diff --git a/docs/versioned_docs/version-2.0/30-administration/11-forges/bitbucket_oauth.png b/docs/versioned_docs/version-2.0/30-administration/11-forges/bitbucket_oauth.png deleted file mode 100644 index 17ecf38ab9..0000000000 Binary files a/docs/versioned_docs/version-2.0/30-administration/11-forges/bitbucket_oauth.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.0/30-administration/11-forges/bitbucket_permissions.png b/docs/versioned_docs/version-2.0/30-administration/11-forges/bitbucket_permissions.png deleted file mode 100644 index 0269f98b0b..0000000000 Binary files a/docs/versioned_docs/version-2.0/30-administration/11-forges/bitbucket_permissions.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.0/30-administration/11-forges/gitea_oauth.gif b/docs/versioned_docs/version-2.0/30-administration/11-forges/gitea_oauth.gif deleted file mode 100644 index 7478f93856..0000000000 Binary files a/docs/versioned_docs/version-2.0/30-administration/11-forges/gitea_oauth.gif and /dev/null differ diff --git a/docs/versioned_docs/version-2.0/30-administration/11-forges/github_oauth.png b/docs/versioned_docs/version-2.0/30-administration/11-forges/github_oauth.png deleted file mode 100644 index 6b0edef0ff..0000000000 Binary files a/docs/versioned_docs/version-2.0/30-administration/11-forges/github_oauth.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.0/30-administration/15-agent-config.md b/docs/versioned_docs/version-2.0/30-administration/15-agent-config.md deleted file mode 100644 index 6054affa22..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/15-agent-config.md +++ /dev/null @@ -1,211 +0,0 @@ -# Agent configuration - -Agents are configured by the command line or environment variables. At the minimum you need the following information: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-agent: - [...] - volumes: - - woodpecker-agent-config:/etc/woodpecker - environment: -+ - WOODPECKER_SERVER=localhost:9000 -+ - WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here" -``` - -The following are automatically set and can be overridden: - -- WOODPECKER_HOSTNAME if not set, becomes the OS' hostname -- WOODPECKER_MAX_WORKFLOWS if not set, defaults to 1 - -## Workflows per agent - -By default, the maximum workflows that are executed in parallel on an agent is 1. If required, you can add `WOODPECKER_MAX_WORKFLOWS` to increase your parallel processing for an agent. - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-agent: - [...] - environment: - - WOODPECKER_SERVER=localhost:9000 - - WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here" -+ - WOODPECKER_MAX_WORKFLOWS=4 -``` - -## Agent registration - -When the agent starts it connects to the server using the token from `WOODPECKER_AGENT_SECRET`. The server identifies the agent and registers the agent in its database if it wasn't connected before. - -There are two types of tokens to connect an agent to the server: - -### Using system token - -A _system token_ is a token that is used system-wide, e.g. when you set the same token in `WOODPECKER_AGENT_SECRET` on both the server and the agents. - -In that case registration process would be as following: - -1. The first time the agent communicates with the server, it is using the system token -1. The server registers the agent in its database if not done before and generates a unique ID which is then sent back to the agent -1. The agent stores the received ID in a file (configured by `WOODPECKER_AGENT_CONFIG_FILE`) -1. At the following startups, the agent uses the system token **and** its received ID to identify itself to the server - -### Using agent token - -An _agent token_ is a token that is used by only one particular agent. This unique token is applied to the agent by `WOODPECKER_AGENT_SECRET`. - -To get an _agent token_ you have to register the agent manually in the server using the UI: - -1. The administrator registers a new agent manually at `Settings -> Agents -> Add agent` - ![Agent creation](./new-agent-registration.png) - ![Agent created](./new-agent-created.png) -1. The generated token from the previous step has to be provided to the agent using `WOODPECKER_AGENT_SECRET` -1. The agent will connect to the server using the provided token and will update its status in the UI: - ![Agent connected](./new-agent-connected.png) - -## All agent configuration options - -Here is the full list of configuration options and their default variables. - -### `WOODPECKER_SERVER` - -> Default: `localhost:9000` - -Configures gRPC address of the server. - -### `WOODPECKER_USERNAME` - -> Default: `x-oauth-basic` - -The gRPC username. - -### `WOODPECKER_AGENT_SECRET` - -> Default: empty - -A shared secret used by server and agents to authenticate communication. A secret can be generated by `openssl rand -hex 32`. - -### `WOODPECKER_AGENT_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_AGENT_SECRET` from the specified filepath, e.g. `/etc/woodpecker/agent-secret.conf` - -### `WOODPECKER_LOG_LEVEL` - -> Default: empty - -Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty. - -### `WOODPECKER_DEBUG_PRETTY` - -> Default: `false` - -Enable pretty-printed debug output. - -### `WOODPECKER_DEBUG_NOCOLOR` - -> Default: `true` - -Disable colored debug output. - -### `WOODPECKER_HOSTNAME` - -> Default: empty - -Configures the agent hostname. - -### `WOODPECKER_AGENT_CONFIG_FILE` - -> Default: `/etc/woodpecker/agent.conf` - -Configures the path of the agent config file. - -### `WOODPECKER_MAX_WORKFLOWS` - -> Default: `1` - -Configures the number of parallel workflows. - -### `WOODPECKER_FILTER_LABELS` - -> Default: empty - -Configures labels to filter pipeline pick up. Use a list of key-value pairs like `key=value,second-key=*`. `*` can be used as a wildcard. By default, agents provide three additional labels `platform=os/arch`, `hostname=my-agent` and `repo=*` which can be overwritten if needed. To learn how labels work, check out the [pipeline syntax page](../20-usage/20-workflow-syntax.md#labels). - -### `WOODPECKER_HEALTHCHECK` - -> Default: `true` - -Enable healthcheck endpoint. - -### `WOODPECKER_HEALTHCHECK_ADDR` - -> Default: `:3000` - -Configures healthcheck endpoint address. - -### `WOODPECKER_KEEPALIVE_TIME` - -> Default: empty - -After a duration of this time of no activity, the agent pings the server to check if the transport is still alive. - -### `WOODPECKER_KEEPALIVE_TIMEOUT` - -> Default: `20s` - -After pinging for a keepalive check, the agent waits for a duration of this time before closing the connection if no activity. - -### `WOODPECKER_GRPC_SECURE` - -> Default: `false` - -Configures if the connection to `WOODPECKER_SERVER` should be made using a secure transport. - -### `WOODPECKER_GRPC_VERIFY` - -> Default: `true` - -Configures if the gRPC server certificate should be verified, only valid when `WOODPECKER_GRPC_SECURE` is `true`. - -### `WOODPECKER_BACKEND` - -> Default: `auto-detect` - -Configures the backend engine to run pipelines on. Possible values are `auto-detect`, `docker`, `local` or `kubernetes`. - -### `WOODPECKER_BACKEND_DOCKER_*` - -See [Docker backend configuration](./22-backends/10-docker.md#configuration) - -### `WOODPECKER_BACKEND_K8S_*` - -See [Kubernetes backend configuration](./22-backends/40-kubernetes.md#general-configuration) - -### `WOODPECKER_BACKEND_LOCAL_*` - -See [Local backend configuration](./22-backends/20-local.md#further-configuration) - -## Advanced Settings - -:::warning -Only change these If you know what you do. -::: - -### `WOODPECKER_CONNECT_RETRY_COUNT` - -> Default: `5` - -Configures number of times agent retries to connect to the server. - -### `WOODPECKER_CONNECT_RETRY_DELAY` - -> Default: `2s` - -Configures delay between agent connection retries to the server. diff --git a/docs/versioned_docs/version-2.0/30-administration/22-backends/10-docker.md b/docs/versioned_docs/version-2.0/30-administration/22-backends/10-docker.md deleted file mode 100644 index 57fe7bb919..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/22-backends/10-docker.md +++ /dev/null @@ -1,62 +0,0 @@ -# Docker backend - -This is the original backend used with Woodpecker. The docker backend executes each step inside a separate container started on the agent. - -## Configuration - -### `WOODPECKER_BACKEND_DOCKER_NETWORK` - -> Default: empty - -Set to the name of an existing network which will be attached to all your pipeline containers (steps). Please be careful as this allows the containers of different pipelines to access each other! - -### `WOODPECKER_BACKEND_DOCKER_ENABLE_IPV6` - -> Default: `false` - -Enable IPv6 for the networks used by pipeline containers (steps). Make sure you configured your docker daemon to support IPv6. - -### `WOODPECKER_BACKEND_DOCKER_VOLUMES` - -> Default: empty - -List of default volumes separated by comma to be mounted to all pipeline containers (steps). For example to use custom CA -certificates installed on host and host timezone use `/etc/ssl/certs:/etc/ssl/certs:ro,/etc/timezone:/etc/timezone`. - -## Docker credentials - -Woodpecker supports [Docker credentials](https://github.com/docker/docker-credential-helpers) to securely store registry credentials. Install your corresponding credential helper and configure it in your Docker config file passed via [`WOODPECKER_DOCKER_CONFIG`](../10-server-config.md#woodpecker_docker_config). - -To add your credential helper to the Woodpecker server container you could use the following code to build a custom image: - -```dockerfile -FROM woodpeckerci/woodpecker-server:latest-alpine - -RUN apk add -U --no-cache docker-credential-ecr-login -``` - -## Podman support - -While the agent was developed with Docker/Moby, Podman can also be used by setting the environment variable `DOCKER_HOST` to point to the Podman socket. In order to work without workarounds, Podman 4.0 (or above) is required. - -## Image Cleanup - -The agent **will not** automatically remove images from the host. This task should be managed by the host system. For example, you can use a cron job to periodically do clean-up tasks for the CI runner. - -:::danger - -The following commands **are destructive** and **irreversible** it is highly recommended that you test these commands on your system before running them in production via a cron job or other automation. - -::: - -### Remove all unused images - -```bash -docker image rm $(docker images --filter "dangling=true" -q --no-trunc) -``` - -### Remove Woodpecker Volumes - -```bash -docker volume rm $(docker volume ls --filter name=^wp_* --filter dangling=true -q) -``` diff --git a/docs/versioned_docs/version-2.0/30-administration/22-backends/20-local.md b/docs/versioned_docs/version-2.0/30-administration/22-backends/20-local.md deleted file mode 100644 index 3db1d6f70b..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/22-backends/20-local.md +++ /dev/null @@ -1,133 +0,0 @@ -# Local backend - -:::danger -The local backend will execute the pipelines on the local system without any isolation of any kind. -::: - -:::note -This backend is still pretty new and cannot be treated as stable. Its -implementation and configuration can change at any time. -::: - -Since the code runs directly in the same context as the agent (same user, same -filesystem), a malicious pipeline could be used to access the agent -configuration especially the `WOODPECKER_AGENT_SECRET` variable. - -It is recommended to use this backend only for private setup where the code and -pipeline can be trusted. You shouldn't use it for a public facing CI where -anyone can submit code or add new repositories. You shouldn't execute the agent -as a privileged user (root). - -The local backend will use a random directory in $TMPDIR to store the cloned -code and execute commands. - -In order to use this backend, you need to download (or build) the -[binary](https://github.com/woodpecker-ci/woodpecker/releases/latest) of the -agent, configure it and run it on the host machine. - -## Configuration - -### Server - -Enable connection to the server from the outside of the docker environment by -exposing the port 9000: - -```yaml -# docker-compose.yml for the server -version: '3' - -services: - woodpecker-server: - [...] - ports: - - 9000:9000 - [...] - environment: - - [...] -``` - -### Agent - -You can use the `.env` file to store environmental variables for configuration. -At the minimum you need the following information: - -```ini -# .env for the agent -WOODPECKER_AGENT_SECRET=replace_with_your_server_secret -WOODPECKER_SERVER=replace_with_your_server_address:9000 -``` - -## Running the agent - -Start the agent from the directory with the `.env` file: - -`woodpecker-agent` - -:::note -When using the `local` backend, the -[plugin-git](https://github.com/woodpecker-ci/plugin-git) binary must be in -your `$PATH` for the default clone step to work. If not, you can still write a -manual clone step. -::: - -## Further configuration - -### Specify the shell to be used for a pipeline step - -The `image` entry is used to specify the shell, such as Bash or Fish, that is -used to run the commands. - -```yaml -# .woodpecker.yml - -steps: - build: - image: bash - commands: [...] -``` - -### Plugins as Executable Binaries - -```yaml -steps: - build: - image: /usr/bin/tree -``` - -If no commands are provided, we treat them as plugins in the usual manner. -In the context of the local backend, plugins are simply executable binaries, which can be located using their name if they are listed in `$PATH`, or through an absolute path. - -### Using labels to filter tasks - -You can use the [agent configuration options](../15-agent-config.md#woodpecker_filter_labels) -and the [pipeline syntax](../../20-usage/20-workflow-syntax.md#labels) to only run certain -pipelines on certain agents. Example: - -Define a `label` `type` with value `exec` for a particular agent: - -```ini -# .env for the agent - -WOODPECKER_FILTER_LABELS=type=exec -``` - -Then, use this `label` `type` with value `exec` in the pipeline definition, to -only run on this agent: - -```yaml -# .woodpecker.yml - -labels: - type: exec - -steps: [...] -``` - -### Change temp directory - -We use the default temp directory to create folders for workflows. -This directory can be changed by: - -```env -WOODPECKER_BACKEND_LOCAL_TEMP_DIR=/some/other/dir -``` diff --git a/docs/versioned_docs/version-2.0/30-administration/22-backends/40-kubernetes.md b/docs/versioned_docs/version-2.0/30-administration/22-backends/40-kubernetes.md deleted file mode 100644 index 2fc80dba2b..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/22-backends/40-kubernetes.md +++ /dev/null @@ -1,168 +0,0 @@ -# Kubernetes backend - -The kubernetes backend executes steps inside standalone pods. A temporary PVC is created for the lifetime of the pipeline to transfer files between steps. - -## General Configuration - -These env vars can be set in the `env:` sections of both `server` and `agent`. -They do not need to be set for both but only for the part to which it is relevant to. - -```yaml -server: - env: - WOODPECKER_SESSION_EXPIRES: "300h" - [...] - -agent: - env: - [...] -``` - -- `WOODPECKER_BACKEND_K8S_NAMESPACE` (default: `woodpecker`) - - The namespace to create worker pods in. - -- `WOODPECKER_BACKEND_K8S_VOLUME_SIZE` (default: `10G`) - - The volume size of the pipeline volume. - -- `WOODPECKER_BACKEND_K8S_STORAGE_CLASS` (default: empty) - - The storage class to use for the pipeline volume. - -- `WOODPECKER_BACKEND_K8S_STORAGE_RWX` (default: `true`) - - Determines if `RWX` should be used for the pipeline volume's [access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes). If false, `RWO` is used instead. - -- `WOODPECKER_BACKEND_K8S_POD_LABELS` (default: empty) - - Additional labels to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-label":"test-value"}`. - -- `WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS` (default: empty) - - Additional annotations to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-annotation":"test-value"}`. - -## Job specific configuration - -### Resources - -The kubernetes backend also allows for specifying requests and limits on a per-step basic, most commonly for CPU and memory. -We recommend to add a `resources` definition to all steps to ensure efficient scheduling. - -Here is an example definition with an arbitrary `resources` definition below the `backend_options` section: - -```yaml -steps: - 'My kubernetes step': - image: alpine - commands: - - echo "Hello world" - backend_options: - kubernetes: - resources: - requests: - memory: 200Mi - cpu: 100m - limits: - memory: 400Mi - cpu: 1000m -``` - -### serviceAccountName - -Specify the name of the ServiceAccount which the build pod will mount. This serviceAccount must be created externally. -See the [kubernetes documentation](https://kubernetes.io/docs/concepts/security/service-accounts/) for more information on using serviceAccounts. - -### nodeSelector - -Specifies the label which is used to select the node on which the job will be executed. - -Labels defined here will be appended to a list which already contains `"kubernetes.io/arch"`. -By default `"kubernetes.io/arch"` is inferred from the agents' platform. One can override it by setting that label in the `nodeSelector` section of the `backend_options`. -Without a manual overwrite, builds will be randomly assigned to the runners and inherit their respective architectures. - -To overwrite this, one needs to set the label in the `nodeSelector` section of the `backend_options`. -A practical example for this is when running a matrix-build and delegating specific elements of the matrix to run on a specific architecture. -In this case, one must define an arbitrary key in the matrix section of the respective matrix element: - -```yaml -matrix: - include: - - NAME: runner1 - ARCH: arm64 -``` - -And then overwrite the `nodeSelector` in the `backend_options` section of the step(s) using the name of the respective env var: - -```yaml -[...] - backend_options: - kubernetes: - nodeSelector: - kubernetes.io/arch: "${ARCH}" -``` - -### 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. -See the [kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for more information on using tolerations. - -Example pipeline configuration: - -```yaml -steps: - build: - image: golang - commands: - - go get - - go build - - go test - backend_options: - kubernetes: - serviceAccountName: 'my-service-account' - resources: - requests: - memory: 128Mi - cpu: 1000m - limits: - memory: 256Mi - nodeSelector: - beta.kubernetes.io/instance-type: p3.8xlarge - tolerations: - - key: 'key1' - operator: 'Equal' - value: 'value1' - effect: 'NoSchedule' - tolerationSeconds: 3600 -``` - -### Volumes - -To mount volumes a persistent volume (PV) and persistent volume claim (PVC) are needed on the cluster which can be referenced in steps via the `volume:` option. -Assuming a PVC named "woodpecker-cache" exists, it can be referenced as follows in a step: - -```yaml -steps: - "Restore Cache": - image: meltwater/drone-cache - volumes: - - woodpecker-cache:/woodpecker/src/cache - settings: - mount: - - "woodpecker-cache" - [...] -``` - -## Tips and tricks - -### CRI-O - -CRI-O users currently need to configure the workspace for all workflows in order for them to run correctly. Add the following at the beginning of your configuration: - -```yaml -workspace: - base: '/woodpecker' - path: '/' -``` - -See [this issue](https://github.com/woodpecker-ci/woodpecker/issues/2510) for more details. diff --git a/docs/versioned_docs/version-2.0/30-administration/22-backends/_category_.yaml b/docs/versioned_docs/version-2.0/30-administration/22-backends/_category_.yaml deleted file mode 100644 index 556444f02f..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/22-backends/_category_.yaml +++ /dev/null @@ -1,4 +0,0 @@ -label: 'Backends' -# position: 3 -collapsible: true -collapsed: true diff --git a/docs/versioned_docs/version-2.0/30-administration/30-database.md b/docs/versioned_docs/version-2.0/30-administration/30-database.md deleted file mode 100644 index 775e5a1b0b..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/30-database.md +++ /dev/null @@ -1,68 +0,0 @@ -# Databases - -The default database engine of Woodpecker is an embedded SQLite database which requires zero installation or configuration. But you can replace it with a MySQL/MariaDB or Postgres database. - -## Configure SQLite - -By default Woodpecker uses a SQLite database stored under `/var/lib/woodpecker/`. You can mount a [data volume](https://docs.docker.com/storage/volumes/#create-and-manage-volumes) to persist the SQLite database. - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] -+ volumes: -+ - woodpecker-server-data:/var/lib/woodpecker/ -``` - -## Configure MySQL/MariaDB - -The below example demonstrates MySQL database configuration. See the official driver [documentation](https://github.com/go-sql-driver/mysql#dsn-data-source-name) for configuration options and examples. -The minimum version of MySQL/MariaDB required is determined by the `go-sql-driver/mysql` - see [it's README](https://github.com/go-sql-driver/mysql#requirements) for more information. - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: -+ - WOODPECKER_DATABASE_DRIVER=mysql -+ - WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true -``` - -## Configure Postgres - -The below example demonstrates Postgres database configuration. See the official driver [documentation](https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING) for configuration options and examples. -Please use Postgres versions equal or higher than **11**. - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: -+ - WOODPECKER_DATABASE_DRIVER=postgres -+ - WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/postgres?sslmode=disable -``` - -## Database Creation - -Woodpecker does not create your database automatically. If you are using the MySQL or Postgres driver you will need to manually create your database using `CREATE DATABASE` - -## Database Migration - -Woodpecker automatically handles database migration, including the initial creation of tables and indexes. New versions of Woodpecker will automatically upgrade the database unless otherwise specified in the release notes. - -## Database Backups - -Woodpecker does not perform database backups. This should be handled by separate third party tools provided by your database vendor of choice. - -## Database Archiving - -Woodpecker does not perform data archival; it considered out-of-scope for the project. Woodpecker is rather conservative with the amount of data it stores, however, you should expect the database logs to grow the size of your database considerably. diff --git a/docs/versioned_docs/version-2.0/30-administration/40-encryption.md b/docs/versioned_docs/version-2.0/30-administration/40-encryption.md deleted file mode 100644 index f630711d85..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/40-encryption.md +++ /dev/null @@ -1,83 +0,0 @@ -# Secrets encryption - -:::danger -Secrets encryption is currently broken and therefore disabled by default. It will be fixed in an upcoming release. - -Check: - -- and -- - -::: - -By default, Woodpecker does not encrypt secrets in its database. You can enable encryption -using simple AES key or more advanced [Google TINK](https://developers.google.com/tink) encryption. - -## Common - -### Enabling secrets encryption - -To enable secrets encryption and encrypt all existing secrets in database set -`WOODPECKER_ENCRYPTION_KEY`, `WOODPECKER_ENCRYPTION_KEY_FILE` or `WOODPECKER_ENCRYPTION_TINK_KEYSET_PATH` environment -variable depending on encryption method of your choice. - -After encryption is enabled you will be unable to start Woodpecker server without providing valid encryption key! - -### Disabling encryption and decrypting all secrets - -To disable secrets encryption and decrypt database you need to start server with valid -`WOODPECKER_ENCRYPTION_KEY` or `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE` environment variable set depending on -enabled encryption method, and `WOODPECKER_ENCRYPTION_DISABLE` set to true. - -After secrets was decrypted server will proceed working in unencrypted mode. You will not need to use "disable encryption" -variable or encryption keys to start server anymore. - -## AES - -Simple AES encryption. - -### Configuration - -You can manage encryption on server using these environment variables: - -- `WOODPECKER_ENCRYPTION_KEY` - encryption key -- `WOODPECKER_ENCRYPTION_KEY_FILE` - file to read encryption key from -- `WOODPECKER_ENCRYPTION_DISABLE` - disable encryption flag used to decrypt all data on server - -## TINK - -TINK uses AEAD encryption instead of simple AES and supports key rotation. - -### Configuration - -You can manage encryption on server using these two environment variables: - -- `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE` - keyset filepath -- `WOODPECKER_ENCRYPTION_DISABLE` - disable encryption flag used to decrypt all data on server - -### Encryption keys - -You will need plaintext AEAD-compatible Google TINK keyset to encrypt your data. - -To generate it and then rotate keys if needed, install `tinkey`([installation guide](https://developers.google.com/tink/install-tinkey)) - -Keyset contains one or more keys, used to encrypt or decrypt your data, and primary key ID, used to determine which key -to use while encrypting new data. - -Keyset generation example: - -```bash -tinkey create-keyset --key-template AES256_GCM --out-format json --out keyset.json -``` - -### Key rotation - -Use `tinkey` to rotate encryption keys in your existing keyset: - -```bash -tinkey rotate-keyset --in keyset_v1.json --out keyset_v2.json --key-template AES256_GCM -``` - -Then you just need to replace server keyset file with the new one. At the moment server detects new encryption -keyset it will re-encrypt all existing secrets with the new key, so you will be unable to start server with previous -keyset anymore. diff --git a/docs/versioned_docs/version-2.0/30-administration/60-ssl.md b/docs/versioned_docs/version-2.0/30-administration/60-ssl.md deleted file mode 100644 index 7174d6e412..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/60-ssl.md +++ /dev/null @@ -1,129 +0,0 @@ -# SSL - -Woodpecker supports two ways of enabling SSL communication. You can either use Let's Encrypt to get automated SSL support with -renewal or provide your own SSL certificates. - -## Let's Encrypt - -Woodpecker supports automated SSL configuration and updates using Let's Encrypt. - -You can enable Let's Encrypt by making the following modifications to your server configuration: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - ports: -+ - 80:80 -+ - 443:443 - - 9000:9000 - environment: - - [...] -+ - WOODPECKER_LETS_ENCRYPT=true -+ - WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld -``` - -Note that Woodpecker uses the hostname from the `WOODPECKER_HOST` environment variable when requesting certificates. For example, if `WOODPECKER_HOST=https://example.com` is set the certificate is requested for `example.com`. To receive emails before certificates expire Let's Encrypt requires an email address. You can set it with `WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld`. - -The SSL certificates are stored in `$HOME/.local/share/certmagic` for binary versions of Woodpecker and in `/var/lib/woodpecker` for the Container versions of it. You can set a custom path by setting `XDG_DATA_HOME` if required. - -> Once enabled you can visit the Woodpecker UI with http and the HTTPS address. HTTP will be redirected to HTTPS. - -### Certificate Cache - -Woodpecker writes the certificates to `/var/lib/woodpecker/certmagic/`. - -### Certificate Updates - -Woodpecker uses the official Go acme library which will handle certificate upgrades. There should be no addition configuration or management required. - -## SSL with own certificates - -Woodpecker supports SSL configuration by mounting certificates into your container. - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - ports: -+ - 80:80 -+ - 443:443 - - 9000:9000 - volumes: -+ - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt -+ - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key - environment: - - [...] -+ - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt -+ - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key -``` - -Update your configuration to expose the following ports: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - ports: -+ - 80:80 -+ - 443:443 - - 9000:9000 -``` - -Update your configuration to mount your certificate and key: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - ports: - - 80:80 - - 443:443 - - 9000:9000 - volumes: -+ - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt -+ - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key -``` - -Update your configuration to provide the paths of your certificate and key: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - ports: - - 80:80 - - 443:443 - - 9000:9000 - volumes: - - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt - - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key - environment: -+ - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt -+ - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key -``` - -### Certificate Chain - -The most common problem encountered is providing a certificate file without the intermediate chain. - -> LoadX509KeyPair reads and parses a public/private key pair from a pair of files. The files must contain PEM encoded data. The certificate file may contain intermediate certificates following the leaf certificate to form a certificate chain. - -### Certificate Errors - -SSL support is provided using the [ListenAndServeTLS](https://golang.org/pkg/net/http/#ListenAndServeTLS) function from the Go standard library. If you receive certificate errors or warnings please examine your configuration more closely. diff --git a/docs/versioned_docs/version-2.0/30-administration/70-proxy.md b/docs/versioned_docs/version-2.0/30-administration/70-proxy.md deleted file mode 100644 index 0d9455b908..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/70-proxy.md +++ /dev/null @@ -1,179 +0,0 @@ -# Proxy - -## Apache - -This guide provides a brief overview for installing Woodpecker server behind the Apache2 web-server. This is an example configuration: - -```apacheconf -ProxyPreserveHost On - -RequestHeader set X-Forwarded-Proto "https" - -ProxyPass / http://127.0.0.1:8000/ -ProxyPassReverse / http://127.0.0.1:8000/ -``` - -You must have the below Apache modules installed. - -```nohighlight -a2enmod proxy -a2enmod proxy_http -``` - -You must configure Apache to set `X-Forwarded-Proto` when using https. - -```diff -ProxyPreserveHost On - -+RequestHeader set X-Forwarded-Proto "https" - -ProxyPass / http://127.0.0.1:8000/ -ProxyPassReverse / http://127.0.0.1:8000/ -``` - -## Nginx - -This guide provides a basic overview for installing Woodpecker server behind the Nginx web-server. For more advanced configuration options please consult the official Nginx [documentation](https://www.nginx.com/resources/admin-guide/). - -Example configuration: - -```nginx -server { - listen 80; - server_name woodpecker.example.com; - - location / { - proxy_set_header X-Forwarded-For $remote_addr; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header Host $http_host; - - proxy_pass http://127.0.0.1:8000; - proxy_redirect off; - proxy_http_version 1.1; - proxy_buffering off; - - chunked_transfer_encoding off; - } -} -``` - -You must configure the proxy to set `X-Forwarded` proxy headers: - -```diff -server { - listen 80; - server_name woodpecker.example.com; - - location / { -+ proxy_set_header X-Forwarded-For $remote_addr; -+ proxy_set_header X-Forwarded-Proto $scheme; - - proxy_pass http://127.0.0.1:8000; - proxy_redirect off; - proxy_http_version 1.1; - proxy_buffering off; - - chunked_transfer_encoding off; - } -} -``` - -## Caddy - -This guide provides a brief overview for installing Woodpecker server behind the [Caddy web-server](https://caddyserver.com/). This is an example caddyfile proxy configuration: - -```caddy -# expose WebUI and API -woodpecker.example.com { - reverse_proxy woodpecker-server:8000 -} - -# expose gRPC -woodpeckeragent.example.com { - reverse_proxy h2c://woodpecker-server:9000 -} -``` - -:::note -Above configuration shows how to create reverse-proxies for web and agent communication. If your agent uses SSL do not forget to enable [WOODPECKER_GRPC_SECURE](./15-agent-config.md#woodpecker_grpc_secure). -::: - -## Ngrok - -After installing [ngrok](https://ngrok.com/), open a new console and run: - -```bash -ngrok http 8000 -``` - -Set `WOODPECKER_HOST` (for example in `docker-compose.yml`) to the ngrok URL (usually xxx.ngrok.io) and start the server. - -## Traefik - -To install the Woodpecker server behind a [Traefik](https://traefik.io/) load balancer, you must expose both the `http` and the `gRPC` ports. Here is a comprehensive example, considering you are running Traefik with docker swarm and want to do TLS termination and automatic redirection from http to https. - -```yaml -version: '3.8' - -services: - server: - image: woodpeckerci/woodpecker-server:latest - environment: - - WOODPECKER_OPEN=true - - WOODPECKER_ADMIN=your_admin_user - # other settings ... - - networks: - - dmz # externally defined network, so that traefik can connect to the server - volumes: - - woodpecker-server-data:/var/lib/woodpecker/ - - deploy: - labels: - - traefik.enable=true - - # web server - - traefik.http.services.woodpecker-service.loadbalancer.server.port=8000 - - - traefik.http.routers.woodpecker-secure.rule=Host(`cd.yourdomain.com`) - - traefik.http.routers.woodpecker-secure.tls=true - - traefik.http.routers.woodpecker-secure.tls.certresolver=letsencrypt - - traefik.http.routers.woodpecker-secure.entrypoints=websecure - - traefik.http.routers.woodpecker-secure.service=woodpecker-service - - - traefik.http.routers.woodpecker.rule=Host(`cd.yourdomain.com`) - - traefik.http.routers.woodpecker.entrypoints=web - - traefik.http.routers.woodpecker.service=woodpecker-service - - - traefik.http.middlewares.woodpecker-redirect.redirectscheme.scheme=https - - traefik.http.middlewares.woodpecker-redirect.redirectscheme.permanent=true - - traefik.http.routers.woodpecker.middlewares=woodpecker-redirect@docker - - # gRPC service - - traefik.http.services.woodpecker-grpc.loadbalancer.server.port=9000 - - traefik.http.services.woodpecker-grpc.loadbalancer.server.scheme=h2c - - - traefik.http.routers.woodpecker-grpc-secure.rule=Host(`woodpecker-grpc.yourdomain.com`) - - traefik.http.routers.woodpecker-grpc-secure.tls=true - - traefik.http.routers.woodpecker-grpc-secure.tls.certresolver=letsencrypt - - traefik.http.routers.woodpecker-grpc-secure.entrypoints=websecure - - traefik.http.routers.woodpecker-grpc-secure.service=woodpecker-grpc - - - traefik.http.routers.woodpecker-grpc.rule=Host(`woodpecker-grpc.yourdomain.com`) - - traefik.http.routers.woodpecker-grpc.entrypoints=web - - traefik.http.routers.woodpecker-grpc.service=woodpecker-grpc - - - traefik.http.middlewares.woodpecker-grpc-redirect.redirectscheme.scheme=https - - traefik.http.middlewares.woodpecker-grpc-redirect.redirectscheme.permanent=true - - traefik.http.routers.woodpecker-grpc.middlewares=woodpecker-grpc-redirect@docker - -volumes: - woodpecker-server-data: - driver: local - -networks: - dmz: - external: true -``` - -You should pass `WOODPECKER_GRPC_SECURE=true` and `WOODPECKER_GRPC_VERIFY=true` to your agent when using this configuration. diff --git a/docs/versioned_docs/version-2.0/30-administration/80-autoscaler.md b/docs/versioned_docs/version-2.0/30-administration/80-autoscaler.md deleted file mode 100644 index 86e92d1a24..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/80-autoscaler.md +++ /dev/null @@ -1,37 +0,0 @@ -# Autoscaler - -If your would like dynamically scale your agents with the load, you can use [our autoscaler](https://github.com/woodpecker-ci/autoscaler). - -Please note that the autoscaler is not feature-complete yet. You can follow the progress [here](https://github.com/woodpecker-ci/autoscaler#roadmap). - -## Setup - -### docker-compose - -If you are using docker-compose you can add the following to your docker-compose.yml file: - -```yaml -version: '3' - -services: - woodpecker-server: - image: woodpeckerci/woodpecker-server:next - [...] - - woodpecker-autoscaler: - image: woodpeckerci/autoscaler:next - restart: always - depends_on: - - woodpecker-server - environment: - - WOODPECKER_SERVER=https://your-woodpecker-server.tld # the url of your woodpecker server / could also be a public url - - WOODPECKER_TOKEN=${WOODPECKER_TOKEN} # the api token you can get from the UI https://your-woodpecker-server.tld/user - - WOODPECKER_MIN_AGENTS=0 - - WOODPECKER_MAX_AGENTS=3 - - WOODPECKER_WORKFLOWS_PER_AGENT=2 # the number of workflows each agent can run at the same time - - WOODEPCKER_GRPC_ADDR=https://grpc.your-woodpecker-server.tld # the grpc address of your woodpecker server, publicly accessible from the agents - - WOODEPCKER_GRPC_SECURE=true - - WOODPECKER_AGENT_ENV= # optional environment variables to pass to the agents - - WOODPECKER_PROVIDER=hetznercloud # set the provider, you can find all the available ones down below - - WOODPECKER_HETZNERCLOUD_API_TOKEN=${WOODPECKER_HETZNERCLOUD_API_TOKEN} # your api token for the Hetzner cloud -``` diff --git a/docs/versioned_docs/version-2.0/30-administration/90-prometheus.md b/docs/versioned_docs/version-2.0/30-administration/90-prometheus.md deleted file mode 100644 index 9be5770b0c..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/90-prometheus.md +++ /dev/null @@ -1,85 +0,0 @@ -# Prometheus - -Woodpecker is compatible with Prometheus and exposes a `/metrics` endpoint if the environment variable `WOODPECKER_PROMETHEUS_AUTH_TOKEN` is set. Please note that access to the metrics endpoint is restricted and requires the authorization token from the environment variable mentioned above. - -```yaml -global: - scrape_interval: 60s - -scrape_configs: - - job_name: 'woodpecker' - bearer_token: dummyToken... - - static_configs: - - targets: ['woodpecker.domain.com'] -``` - -## Authorization - -An administrator will need to generate a user API token and configure in the Prometheus configuration file as a bearer token. Please see the following example: - -```diff -global: - scrape_interval: 60s - -scrape_configs: - - job_name: 'woodpecker' -+ bearer_token: dummyToken... - - static_configs: - - targets: ['woodpecker.domain.com'] -``` - -As an alternative, the token can also be read from a file: - -```diff -global: - scrape_interval: 60s - -scrape_configs: - - job_name: 'woodpecker' -+ bearer_token_file: /etc/secrets/woodpecker-monitoring-token - - static_configs: - - targets: ['woodpecker.domain.com'] -``` - -## Unauthenticated Access - -Alternatively, the unprotected `/metrics` endpoint might be exposed on the internal port (Port is configurable via the `WOODPECKER_METRICS_SERVER_ADDR` environment variable, e.g. `:9001`). - -## Metric Reference - -List of Prometheus metrics specific to Woodpecker: - -```yaml -# HELP woodpecker_pipeline_count Pipeline count. -# TYPE woodpecker_pipeline_count counter -woodpecker_build_count{branch="main",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3 -woodpecker_build_count{branch="mkdocs",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3 -# HELP woodpecker_pipeline_time Build time. -# TYPE woodpecker_pipeline_time gauge -woodpecker_build_time{branch="main",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 116 -woodpecker_build_time{branch="mkdocs",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 155 -# HELP woodpecker_pipeline_total_count Total number of builds. -# TYPE woodpecker_pipeline_total_count gauge -woodpecker_build_total_count 1025 -# HELP woodpecker_pending_steps Total number of pending pipeline steps. -# TYPE woodpecker_pending_steps gauge -woodpecker_pending_steps 0 -# HELP woodpecker_repo_count Total number of repos. -# TYPE woodpecker_repo_count gauge -woodpecker_repo_count 9 -# HELP woodpecker_running_steps Total number of running pipeline steps. -# TYPE woodpecker_running_steps gauge -woodpecker_running_steps 0 -# HELP woodpecker_user_count Total number of users. -# TYPE woodpecker_user_count gauge -woodpecker_user_count 1 -# HELP woodpecker_waiting_steps Total number of pipeline waiting on deps. -# TYPE woodpecker_waiting_steps gauge -woodpecker_waiting_steps 0 -# HELP woodpecker_worker_count Total number of workers. -# TYPE woodpecker_worker_count gauge -woodpecker_worker_count 4 -``` diff --git a/docs/versioned_docs/version-2.0/30-administration/_category_.yaml b/docs/versioned_docs/version-2.0/30-administration/_category_.yaml deleted file mode 100644 index 4f31383598..0000000000 --- a/docs/versioned_docs/version-2.0/30-administration/_category_.yaml +++ /dev/null @@ -1,4 +0,0 @@ -label: 'Administration' -# position: 3 -collapsible: true -collapsed: true diff --git a/docs/versioned_docs/version-2.0/30-administration/new-agent-connected.png b/docs/versioned_docs/version-2.0/30-administration/new-agent-connected.png deleted file mode 100644 index 9d19153d9d..0000000000 Binary files a/docs/versioned_docs/version-2.0/30-administration/new-agent-connected.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.0/30-administration/new-agent-created.png b/docs/versioned_docs/version-2.0/30-administration/new-agent-created.png deleted file mode 100644 index dc561d8873..0000000000 Binary files a/docs/versioned_docs/version-2.0/30-administration/new-agent-created.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.0/30-administration/new-agent-registration.png b/docs/versioned_docs/version-2.0/30-administration/new-agent-registration.png deleted file mode 100644 index 71117771d6..0000000000 Binary files a/docs/versioned_docs/version-2.0/30-administration/new-agent-registration.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.0/40-cli.md b/docs/versioned_docs/version-2.0/40-cli.md deleted file mode 100644 index acfc7fd924..0000000000 --- a/docs/versioned_docs/version-2.0/40-cli.md +++ /dev/null @@ -1,1215 +0,0 @@ -# CLI - -# NAME - -woodpecker-cli - command line utility - -# SYNOPSIS - -woodpecker-cli - -``` -[--log-file]=[value] -[--log-level]=[value] -[--nocolor] -[--pretty] -[--server|-s]=[value] -[--token|-t]=[value] -``` - -**Usage**: - -``` -woodpecker-cli [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] -``` - -# GLOBAL OPTIONS - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - - -# COMMANDS - -## pipeline - -manage pipelines - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### ls - -show pipeline history - -**--branch**="": branch filter - -**--event**="": event filter - -**--format**="": format output (default: Pipeline #{{ .Number }}  -Status: {{ .Status }} -Event: {{ .Event }} -Commit: {{ .Commit }} -Branch: {{ .Branch }} -Ref: {{ .Ref }} -Author: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }} -Message: {{ .Message }} -) - -**--limit**="": limit the list size (default: 0) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--status**="": status filter - -**--token, -t**="": server auth token - -### last - -show latest pipeline details - -**--branch**="": branch name (default: main) - -**--format**="": format output (default: Number: {{ .Number }} -Status: {{ .Status }} -Event: {{ .Event }} -Commit: {{ .Commit }} -Branch: {{ .Branch }} -Ref: {{ .Ref }} -Message: {{ .Message }} -Author: {{ .Author }} -) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### logs - -show pipeline logs - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### info - -show pipeline details - -**--format**="": format output (default: {{ .Login }}) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### stop - -stop a pipeline - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### start - -start a pipeline - -**--format**="": format output (default: {{ .Login }}) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### approve - -approve a pipeline - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### decline - -decline a pipeline - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### queue - -show pipeline queue - -**--format**="": format output (default: {{ .Login }}) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### ps - -show pipeline steps - -**--format**="": format output (default: {{ .Login }}) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### create - -create new pipeline - -**--branch**="": branch to create pipeline from - -**--format**="": format output (default: Pipeline #{{ .Number }}  -Status: {{ .Status }} -Event: {{ .Event }} -Commit: {{ .Commit }} -Branch: {{ .Branch }} -Ref: {{ .Ref }} -Author: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }} -Message: {{ .Message }} -) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -**--var**="": key=value - -## log - -manage logs - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### purge - -purge a log - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -## deploy - -deploy code - -**--branch**="": branch filter (default: main) - -**--event**="": event filter (default: push) - -**--format**="": format output (default: Number: {{ .Number }} -Status: {{ .Status }} -Commit: {{ .Commit }} -Branch: {{ .Branch }} -Ref: {{ .Ref }} -Message: {{ .Message }} -Author: {{ .Author }} -Target: {{ .Deploy }} -) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--status**="": status filter (default: success) - -**--token, -t**="": server auth token - -## exec - -execute a local pipeline - -**--backend-docker-api-version**="": the version of the API to reach, leave empty for latest. - -**--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 - -**--backend-docker-ipv6**: backend docker enable IPV6 - -**--backend-docker-network**="": backend docker network - -**--backend-docker-tls-verify**: enable or disable TLS verification for connecting to docker server - -**--backend-docker-volumes**="": backend docker volumes (comma separated) - -**--backend-engine**="": backend engine to run pipelines on (default: auto-detect) - -**--backend-http-proxy**="": if set, pass the environment variable down as "HTTP_PROXY" to steps - -**--backend-https-proxy**="": if set, pass the environment variable down as "HTTPS_PROXY" to steps - -**--backend-k8s-namespace**="": backend k8s namespace (default: woodpecker) - -**--backend-k8s-pod-annotations**="": backend k8s additional worker pod annotations - -**--backend-k8s-pod-labels**="": backend k8s additional worker pod labels - -**--backend-k8s-storage-class**="": backend k8s storage class - -**--backend-k8s-storage-rwx**: backend k8s storage access mode, should ReadWriteMany (RWX) instead of ReadWriteOnce (RWO) be used? (default: true) - -**--backend-k8s-volume-size**="": backend k8s volume size (default 10G) (default: 10G) - -**--backend-local-temp-dir**="": set a different temp dir to clone workflows into (default: /tmp) - -**--backend-no-proxy**="": if set, pass the environment variable down as "NO_PROXY" to steps - -**--commit-author-avatar**="": - -**--commit-author-email**="": - -**--commit-author-name**="": - -**--commit-branch**="": - -**--commit-message**="": - -**--commit-ref**="": - -**--commit-refspec**="": - -**--commit-sha**="": - -**--connect-retry-count**="": number of times to retry connecting to the server (default: 0) - -**--connect-retry-delay**="": duration to wait before retrying to connect to the server (default: 0s) - -**--env**="": - -**--forge-type**="": - -**--forge-url**="": - -**--local**: run from local directory - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--netrc-machine**="": - -**--netrc-password**="": - -**--netrc-username**="": - -**--network**="": external networks - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pipeline-created**="": (default: 0) - -**--pipeline-event**="": (default: manual) - -**--pipeline-finished**="": (default: 0) - -**--pipeline-number**="": (default: 0) - -**--pipeline-parent**="": (default: 0) - -**--pipeline-started**="": (default: 0) - -**--pipeline-status**="": - -**--pipeline-target**="": - -**--pipeline-url**="": - -**--pretty**: enable pretty-printed debug output - -**--prev-commit-author-avatar**="": - -**--prev-commit-author-email**="": - -**--prev-commit-author-name**="": - -**--prev-commit-branch**="": - -**--prev-commit-message**="": - -**--prev-commit-ref**="": - -**--prev-commit-refspec**="": - -**--prev-commit-sha**="": - -**--prev-pipeline-created**="": (default: 0) - -**--prev-pipeline-event**="": - -**--prev-pipeline-finished**="": (default: 0) - -**--prev-pipeline-number**="": (default: 0) - -**--prev-pipeline-started**="": (default: 0) - -**--prev-pipeline-status**="": - -**--prev-pipeline-url**="": - -**--privileged**="": privileged plugins (default: "plugins/docker", "plugins/gcr", "plugins/ecr", "woodpeckerci/plugin-docker-buildx", "codeberg.org/woodpecker-plugins/docker-buildx") - -**--repo**="": full repo name - -**--repo-clone-ssh-url**="": - -**--repo-clone-url**="": - -**--repo-private**="": - -**--repo-remote-id**="": - -**--repo-trusted**: - -**--repo-url**="": - -**--server, -s**="": server address - -**--step-name**="": (default: 0) - -**--system-name**="": (default: woodpecker) - -**--system-platform**="": - -**--system-url**="": (default: https://github.com/woodpecker-ci/woodpecker) - -**--timeout**="": pipeline timeout (default: 0s) - -**--token, -t**="": server auth token - -**--volumes**="": pipeline volumes - -**--workflow-name**="": (default: 0) - -**--workflow-number**="": (default: 0) - -**--workspace-base**="": (default: /woodpecker) - -**--workspace-path**="": (default: src) - -## info - -show information about the current user - -**--format**="": format output (default: {{ .Login }}) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -## registry - -manage registries - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### add - -adds a registry - -**--hostname**="": registry hostname (default: docker.io) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--password**="": registry password - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -**--username**="": registry username - -### rm - -remove a registry - -**--hostname**="": registry hostname (default: docker.io) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### update - -update a registry - -**--hostname**="": registry hostname (default: docker.io) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--password**="": registry password - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -**--username**="": registry username - -### info - -display registry info - -**--hostname**="": registry hostname (default: docker.io) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### ls - -list registries - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -## secret - -manage secrets - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### add - -adds a secret - -**--event**="": secret limited to these events - -**--global**: global secret - -**--image**="": secret limited to these images - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--name**="": secret name - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -**--value**="": secret value - -### rm - -remove a secret - -**--global**: global secret - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--name**="": secret name - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### update - -update a secret - -**--event**="": secret limited to these events - -**--global**: global secret - -**--image**="": secret limited to these images - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--name**="": secret name - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -**--value**="": secret value - -### info - -display secret info - -**--global**: global secret - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--name**="": secret name - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### ls - -list secrets - -**--global**: global secret - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -## repo - -manage repositories - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### ls - -list all repos - -**--format**="": format output (default: {{ .FullName }} (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }})) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--org**="": filter by organization - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### info - -show repository details - -**--format**="": format output (default: {{ .Login }}) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### add - -add a repository - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### update - -update a repository - -**--config**="": repository configuration path (e.g. .woodpecker.yml) - -**--gated**: repository is gated - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pipeline-counter**="": repository starting pipeline number (default: 0) - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--timeout**="": repository timeout (default: 0s) - -**--token, -t**="": server auth token - -**--trusted**: repository is trusted - -**--unsafe**: validate updating the pipeline-counter is unsafe - -**--visibility**="": repository visibility - -### rm - -remove a repository - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### repair - -repair repository webhooks - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### chown - -assume ownership of a repository - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### sync - -synchronize the repository list - -**--format**="": format output (default: {{ .Login }}) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -## user - -manage users - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### ls - -list all users - -**--format**="": format output (default: {{ .Login }}) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### info - -show user details - -**--format**="": format output (default: {{ .Login }}) - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### add - -adds a user - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### rm - -remove a user - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -## lint - -lint a pipeline configuration file - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -## log-level - -get the logging level of the server, or set it with [level] - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -## cron - -manage cron jobs - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### add - -add a cron job - -**--branch**="": cron branch - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--name**="": cron name - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--schedule**="": cron schedule - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### rm - -remove a cron job - -**--id**="": cron id - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### update - -update a cron job - -**--branch**="": cron branch - -**--id**="": cron id - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--name**="": cron name - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--schedule**="": cron schedule - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### info - -display info about a cron job - -**--id**="": cron id - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--server, -s**="": server address - -**--token, -t**="": server auth token - -### ls - -list cron jobs - -**--log-file**="": where logs are written to. 'stdout' and 'stderr' can be used as special keywords (default: stderr) - -**--log-level**="": set logging level (default: info) - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--server, -s**="": server address - -**--token, -t**="": server auth token diff --git a/docs/versioned_docs/version-2.0/91-migrations.md b/docs/versioned_docs/version-2.0/91-migrations.md deleted file mode 100644 index 4d8cb85b85..0000000000 --- a/docs/versioned_docs/version-2.0/91-migrations.md +++ /dev/null @@ -1,140 +0,0 @@ -# Migrations - -Some versions need some changes to the server configuration or the pipeline configuration files. - -## next (2.0.0) - -- Dropped deprecated `CI_BUILD_*`, `CI_PREV_BUILD_*`, `CI_JOB_*`, `*_LINK`, `CI_SYSTEM_ARCH`, `CI_REPO_REMOTE` built-in environment variables -- Deprecated `platform:` filter in favor of `labels:`, [read more](./20-usage/20-workflow-syntax.md#filter-by-platform) -- Secrets `event` property was renamed to `events` and `image` to `images` as both are lists. The new property `events` / `images` has to be used in the api. The old properties `event` and `image` were removed. -- The secrets `plugin_only` option was removed. Secrets with images are now always only available for plugins using listed by the `images` property. Existing secrets with a list of `images` will now only be available to the listed images if they are used as a plugin. -- Removed `build` alias for `pipeline` command in CLI -- Removed `ssh` backend. Use an agent directly on the SSH machine using the `local` backend. -- Removed `/hook` and `/stream` API paths in favor of `/api/(hook|stream)`. You may need to use the "Repair repository" button in the repo settings or "Repair all" in the admin settings to recreate the forge hook. -- Removed `WOODPECKER_DOCS` config variable -- Renamed `link` to `url` (including all API fields) -- Deprecated `CI_COMMIT_URL` env var, use `CI_PIPELINE_FORGE_URL` - -## 1.0.0 - -- The signature used to verify extension calls (like those used for the [config-extension](./30-administration/100-external-configuration-api.md)) done by the Woodpecker server switched from using a shared-secret HMac to an ed25519 key-pair. Read more about it at the [config-extensions](./30-administration/100-external-configuration-api.md) documentation. -- Refactored support for old agent filter labels and expressions. Learn how to use the new [filter](./20-usage/20-workflow-syntax.md#labels) -- Renamed step environment variable `CI_SYSTEM_ARCH` to `CI_SYSTEM_PLATFORM`. Same applies for the cli exec variable. -- Renamed environment variables `CI_BUILD_*` and `CI_PREV_BUILD_*` to `CI_PIPELINE_*` and `CI_PREV_PIPELINE_*`, old ones are still available but deprecated -- Renamed environment variables `CI_JOB_*` to `CI_STEP_*`, old ones are still available but deprecated -- Renamed environment variable `CI_REPO_REMOTE` to `CI_REPO_CLONE_URL`, old is still available but deprecated -- Renamed environment variable `*_LINK` to `*_URL`, old ones are still available but deprecated -- Renamed API endpoints for pipelines (`//builds/` -> `//pipelines/`), old ones are still available but deprecated -- Updated Prometheus gauge `build_*` to `pipeline_*` -- Updated Prometheus gauge `*_job_*` to `*_step_*` -- Renamed config env `WOODPECKER_MAX_PROCS` to `WOODPECKER_MAX_WORKFLOWS` (still available as fallback) -- The pipelines are now also read from `.yaml` files, the new default order is `.woodpecker/*.yml` and `.woodpecker/*.yaml` (without any prioritization) -> `.woodpecker.yml` -> `.woodpecker.yaml` -- Dropped support for [Coding](https://coding.net/), [Gogs](https://gogs.io) and Bitbucket Server (Stash). -- `/api/queue/resume` & `/api/queue/pause` endpoint methods were changed from `GET` to `POST` -- rename `pipeline:` key in your workflow config to `steps:` -- If you want to migrate old logs to the new format, watch the error messages on start. If there are none we are good to go, else you have to plan a migration that can take hours. Set `WOODPECKER_MIGRATIONS_ALLOW_LONG` to true and let it run. -- Using `repo-id` in favor of `owner/repo` combination - - :warning: The api endpoints `/api/repos/{owner}/{repo}/...` were replaced by new endpoints using the repos id `/api/repos/{repo-id}` - - To find the id of a repo use the `/api/repos/lookup/{repo-full-name-with-slashes}` endpoint. - - The existing badge endpoint `/api/badges/{owner}/{repo}` will still work, but whenever possible try to use the new endpoint using the `repo-id`: `/api/badges/{repo-id}`. - - The UI urls for a repository changed from `/repos/{owner}/{repo}/...` to `/repos/{repo-id}/...`. You will be redirected automatically when using the old url. - - The woodpecker-go api-client is now using the `repo-id` instead of `owner/repo` for all functions -- Using `org-id` in favour of `owner` name - - :warning: The api endpoints `/api/orgs/{owner}/...` were replaced by new endpoints using the orgs id `/api/repos/{org-id}` - - To find the id of orgs use the `/api/orgs/lookup/{org_full_name}` endpoint. - - The UI urls for a organization changed from `/org/{owner}/...` to `/orgs/{org-id}/...`. You will be redirected automatically when using the old url. - - The woodpecker-go api-client is now using the `org-id` instead of `org name` for all functions -- The `command:` field has been removed from steps. If you were using it, please check if the entrypoint of the image you used is a shell. - - If it is a shell, simply rename `command:` to `commands:`. - - If it's not, you need to prepend the entrypoint before and also rename it (e.g., `commands: `). - -## 0.15.0 - -- Default value for custom pipeline path is now empty / un-set which results in following resolution: - - `.woodpecker/*.yml` -> `.woodpecker.yml` -> `.drone.yml` - - Only projects created after updating will have an empty value by default. Existing projects will stick to the current pipeline path which is `.drone.yml` in most cases. - - Read more about it at the [Project Settings](./20-usage/71-project-settings.md#pipeline-path) - -- From version `0.15.0` ongoing there will be three types of docker images: `latest`, `next` and `x.x.x` with an alpine variant for each type like `latest-alpine`. - If you used `latest` before to try pre-release features you should switch to `next` after this release. - -- Dropped support for `DRONE_*` environment variables. The according `WOODPECKER_*` variables must be used instead. - Additionally some alternative namings have been removed to simplify maintenance: - - - `WOODPECKER_AGENT_SECRET` replaces `WOODPECKER_SECRET`, `DRONE_SECRET`, `WOODPECKER_PASSWORD`, `DRONE_PASSWORD` and `DRONE_AGENT_SECRET`. - - `WOODPECKER_HOST` replaces `DRONE_HOST` and `DRONE_SERVER_HOST`. - - `WOODPECKER_DATABASE_DRIVER` replaces `DRONE_DATABASE_DRIVER` and `DATABASE_DRIVER`. - - `WOODPECKER_DATABASE_DATASOURCE` replaces `DRONE_DATABASE_DATASOURCE` and `DATABASE_CONFIG`. - -- Dropped support for `DRONE_*` environment variables in pipeline steps. Pipeline meta-data can be accessed with `CI_*` variables. - - - `CI_*` prefix replaces `DRONE_*` - - `CI` value is now `woodpecker` - - `DRONE=true` has been removed - - Some variables got deprecated and will be removed in future versions. Please migrate to the new names. Same applies for `DRONE_` of them. - - CI_ARCH => use CI_SYSTEM_ARCH - - CI_COMMIT => CI_COMMIT_SHA - - CI_TAG => CI_COMMIT_TAG - - CI_PULL_REQUEST => CI_COMMIT_PULL_REQUEST - - CI_REMOTE_URL => use CI_REPO_REMOTE - - CI_REPO_BRANCH => use CI_REPO_DEFAULT_BRANCH - - CI_PARENT_BUILD_NUMBER => use CI_BUILD_PARENT - - CI_BUILD_TARGET => use CI_BUILD_DEPLOY_TARGET - - CI_DEPLOY_TO => use CI_BUILD_DEPLOY_TARGET - - CI_COMMIT_AUTHOR_NAME => use CI_COMMIT_AUTHOR - - CI_PREV_COMMIT_AUTHOR_NAME => use CI_PREV_COMMIT_AUTHOR - - CI_SYSTEM => use CI_SYSTEM_NAME - - CI_BRANCH => use CI_COMMIT_BRANCH - - CI_SOURCE_BRANCH => use CI_COMMIT_SOURCE_BRANCH - - CI_TARGET_BRANCH => use CI_COMMIT_TARGET_BRANCH - - For all available variables and their descriptions have a look at [built-in-environment-variables](./20-usage/50-environment.md#built-in-environment-variables). - -- Prometheus metrics have been changed from `drone_*` to `woodpecker_*` - -- Base path has moved from `/var/lib/drone` to `/var/lib/woodpecker` - -- Default workspace base path has moved from `/drone` to `/woodpecker` - -- Default SQLite database location has changed: - - - `/var/lib/drone/drone.sqlite` -> `/var/lib/woodpecker/woodpecker.sqlite` - - `drone.sqlite` -> `woodpecker.sqlite` - -- Plugin Settings moved into `settings` section: - - ```diff - steps: - something: - image: my/plugin - - setting1: foo - - setting2: bar - + settings: - + setting1: foo - + setting2: bar - ``` - -- `WOODPECKER_DEBUG` option for server and agent got removed in favor of `WOODPECKER_LOG_LEVEL=debug` - -- Remove unused server flags which can safely be removed from your server config: `WOODPECKER_QUIC`, `WOODPECKER_GITHUB_SCOPE`, `WOODPECKER_GITHUB_GIT_USERNAME`, `WOODPECKER_GITHUB_GIT_PASSWORD`, `WOODPECKER_GITHUB_PRIVATE_MODE`, `WOODPECKER_GITEA_GIT_USERNAME`, `WOODPECKER_GITEA_GIT_PASSWORD`, `WOODPECKER_GITEA_PRIVATE_MODE`, `WOODPECKER_GITLAB_GIT_USERNAME`, `WOODPECKER_GITLAB_GIT_PASSWORD`, `WOODPECKER_GITLAB_PRIVATE_MODE` - -- Dropped support for manually setting the agents platform with `WOODPECKER_PLATFORM`. The platform is now automatically detected. - -- Use `WOODPECKER_STATUS_CONTEXT` instead of the deprecated options `WOODPECKER_GITHUB_CONTEXT` and `WOODPECKER_GITEA_CONTEXT`. - -## 0.14.0 - -No breaking changes - -## From Drone - -:::warning -Migration from Drone is only possible if you were running Drone <= v0.8. -::: - -1. Make sure you are already running Drone v0.8 -2. Upgrade to Woodpecker v0.14.4, migration will be done during startup -3. Upgrade to the latest Woodpecker version. Pay attention to the breaking changes listed above. diff --git a/docs/versioned_docs/version-2.0/92-awesome.md b/docs/versioned_docs/version-2.0/92-awesome.md deleted file mode 100644 index d440f031ad..0000000000 --- a/docs/versioned_docs/version-2.0/92-awesome.md +++ /dev/null @@ -1,61 +0,0 @@ -# Awesome Woodpecker - -A curated list of awesome things related to Woodpecker-CI. - -If you have some missing resources, please feel free to [open a pull-request](https://github.com/woodpecker-ci/woodpecker/edit/main/docs/docs/92-awesome.md) and add them. - -## Official Resources - -- [Woodpecker CI pipeline configs](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) - Complex setup containing different kind of pipelines - - [Golang tests](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/test.yml) - - [Typescript, eslint & Vue](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/web.yml) - - [Docusaurus & publishing to GitHub Pages](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docs.yml) - - [Docker container building](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docker.yml) - - [Helm chart linting & releasing](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/helm.yml) - -## Projects using Woodpecker - -- [Woodpecker-CI](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) itself -- [All official plugins](https://github.com/woodpecker-ci?q=plugin&type=all) -- [dessalines/thumb-key](https://github.com/dessalines/thumb-key/blob/main/.woodpecker.yml) - Android Jetpack compose linting and building -- [Vieter](https://git.rustybever.be/vieter-v/vieter) - Archlinux/Pacman repository server & automated package build system - - [Rieter](https://git.rustybever.be/Chewing_Bever/rieter) - Rewrite of the Vieter project in Rust -- [Alex](https://git.rustybever.be/Chewing_Bever/alex) - Minecraft server wrapper designed to automate backups & complement Docker installations - -## Tools - -- [Convert Drone CI pipelines to Woodpecker CI](https://codeberg.org/lafriks/woodpecker-pipeline-transform) -- [Ansible NAS](https://github.com/davestephens/ansible-nas/) - a homelab Ansible playbook that can set up Woodpecker-CI and Gitea -- [picus](https://github.com/windsource/picus) - Picus connects to a Woodpecker CI server and creates an agent in the cloud when there are pending workflows. -- [Hetzner cloud](https://www.hetzner.com/cloud) based [Woodpecker compatible autoscaler](https://git.ljoonal.xyz/ljoonal/hetzner-ci-autoscaler) - Creates and destroys VPS instances based on the count of pending & running jobs. -- [woodpecker-lint](https://git.schmidl.dev/schtobia/woodpecker-lint) - A repository for linting a woodpecker config file via pre-commit hook -- [Grafana Dashboard](https://github.com/Janik-Haag/woodpecker-grafana-dashboard) - A dashboard visualizing information exposed by the woodpecker prometheus endpoint. - -## Configuration Services - -- [Dynamic Pipelines for Nix Flakes](https://github.com/pinpox/woodpecker-flake-pipeliner) - Define pipelines as Nix Flake outputs - -## Pipelines - -- [Collection of pipeline examples](https://codeberg.org/Codeberg-CI/examples) - -## Posts & tutorials - -- [Setup Gitea with Woodpecker CI](https://containers.fan/posts/setup-gitea-with-woodpecker-ci/) -- [Step-by-step guide to modern, secure and Open-source CI setup](https://devforth.io/blog/step-by-step-guide-to-modern-secure-ci-setup/) -- [Using Woodpecker CI for my static sites](https://jan.wildeboer.net/2022/07/Woodpecker-CI-Jekyll/) -- [Woodpecker CI @ Codeberg](https://www.sarkasti.eu/articles/post/woodpecker/) -- [Deploy Docker/Compose using Woodpecker CI](https://hinty.io/vverenko/deploy-docker-compose-using-woodpecker-ci/) -- [Installing Woodpecker CI in your personal homelab](https://pwa.io/articles/installing-woodpecker-in-your-homelab/) -- [Locally Cached Nix CI with Woodpecker](https://blog.kotatsu.dev/posts/2023-04-21-woodpecker-nix-caching/) -- [How to run Cypress auto-tests on Woodpecker CI and report results to Slack](https://devforth.io/blog/how-to-run-cypress-auto-tests-on-woodpecker-ci-and-report-results-to-slack/) - -## Videos - -- [Replace Ansible Semaphore with Woodpecker CI](https://www.youtube.com/watch?v=d610YPvCB0E) -- ["unexpected EOF" error when trying to pair Woodpecker CI served through the Caddy with Gitea](https://www.youtube.com/watch?v=n7Hyvt71Np0) -- [CICD Environment in Docker Swarm behind Caddy Server - Part 2 Woodpeckerci](https://www.youtube.com/watch?v=rkbw_k7JvS0) - -## Plugins - -We have a separate [index](/plugins) for plugins. diff --git a/docs/versioned_docs/version-2.0/92-development/01-getting-started.md b/docs/versioned_docs/version-2.0/92-development/01-getting-started.md deleted file mode 100644 index 06bfe0ec2f..0000000000 --- a/docs/versioned_docs/version-2.0/92-development/01-getting-started.md +++ /dev/null @@ -1,147 +0,0 @@ -# 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 preconfigured 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 preconfigured [Gitea](https://github.com/go-gitea/gitea) instance as forge -- A preconfigured Woodpecker server -- A single preconfigured Woodpecker agent node -- Our docs preview server - -Simply start Woodpecker in Gitpod by clicking on the following badge. You can login 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 Golang (>=1.20) as described by [this guide](https://go.dev/doc/install). - -### 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 (). - -Install make on: - -- Ubuntu: `apt install make` - [Docs](https://wiki.ubuntuusers.de/Makefile/) -- [Windows](https://stackoverflow.com/a/32127632/8461267) -- Mac OS: `brew install make` - -### Install Node.js & pnpm - -Install [Node.js (>=14)](https://nodejs.org/en/download/) if you want to build Woodpeckers UI or documentation. - -For dependencies installation (node_modules) for the UI and documentation of Woodpecker the package-manager pnpm is used. The installation of pnpm is described by [this guide](https://pnpm.io/installation). - -### 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` in the root of the Woodpecker project and add any need config to it. - -A common config for debugging would look like this: - -```ini -WOODPECKER_OPEN=true -WOODPECKER_ADMIN=your-username - -# if you want to test webhooks with an online forge like GitHub this address needs to be accessible from public server -WOODPECKER_HOST=http://your-dev-address.com - -# github (sample for a forge config - see /docs/administration/forge/overview for other forges) -WOODPECKER_GITHUB=true -WOODPECKER_GITHUB_CLIENT= -WOODPECKER_GITHUB_SECRET= - -# agent -WOODPECKER_SERVER=localhost:9000 -WOODPECKER_AGENT_SECRET=a-long-and-secure-password-used-for-the-local-development-system -WOODPECKER_MAX_WORKFLOWS=1 - -# enable if you want to develop the UI -# WOODPECKER_DEV_WWW_PROXY=http://localhost:8010 - -# used so you can login without using a public address -WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000 - -# disable health-checks while debugging (normally not needed while developing) -WOODPECKER_HEALTHCHECK=false - -# WOODPECKER_LOG_LEVEL=debug -# WOODPECKER_LOG_LEVEL=trace -``` - -### Setup O-Auth - -Create an O-Auth app for your forge as describe in the [forges documentation](../30-administration/11-forges/10-overview.md). If you set `WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000` you can use that address with the path as explained for the specific forge to login without the need for a public address. For example for GitHub you would use `http://localhost:8000/authorize` as authorization callback URL. - -## Developing with VS-Code - -You can use different methods for debugging the Woodpecker applications. One of the currently recommended ways to debug and test the Woodpecker application is using [VS-Code](https://code.visualstudio.com/) or [VS-Codium](https://vscodium.com/) (Open-Source binaries of VS-Code) as most maintainers are using it and Woodpecker already includes the needed debug configurations for it. - -To launch all needed services for local development you can use "Woodpecker CI" debugging configuration that will launch UI, server and agent in debugging mode. Then open `http://localhost:8000` to access it. - -As a starting guide for programming Go with VS-Code you can use this video guide: -[![Getting started with Go in VS-Code](https://img.youtube.com/vi/1MXIGYrMk80/0.jpg)](https://www.youtube.com/watch?v=1MXIGYrMk80) - -### Debugging Woodpecker - -The Woodpecker source code already includes launch configurations for the Woodpecker server and agent. To start debugging you can click on the debug icon in the navigation bar of VS-Code (ctrl-shift-d). On that page you will see the existing launch jobs at the top. Simply select the agent or server and click on the play button. You can set breakpoints in the source files to stop at specific points. - -![Woodpecker debugging with VS-Code](./vscode-debug.png) - -## Testing & linting code - -To test or lint parts of Woodpecker you can run one of the following commands: - -```bash -# test server code -make test-server - -# test agent code -make test-agent - -# test cli code -make test-cli - -# test datastore / database related code like migrations of the server -make test-server-datastore - -# lint go code -make lint - -# lint UI code -make lint-frontend - -# test UI code -make test-frontend -``` - -If you want to test a specific go file you can also use: - -```bash -go test -race -timeout 30s go.woodpecker-ci.org/woodpecker/v2/ -``` - -Or you can open the test-file inside [VS-Code](#developing-with-vs-code) and run or debug the test by clicking on the inline commands: - -![Run test via VS-Code](./vscode-run-test.png) - -## Run applications from terminal - -If you want to run a Woodpecker applications from your terminal you can use one of the following commands from the base of the Woodpecker project. They will execute Woodpecker in a similar way as described in [debugging Woodpecker](#debugging-woodpecker) without the ability to really debug it in your editor. - -```bash title="start server" -go run ./cmd/server -``` - -```bash title="start agent" -go run ./cmd/agent -``` - -```bash title="execute cli command" -go run ./cmd/cli [command] -``` diff --git a/docs/versioned_docs/version-2.0/92-development/03-ui.md b/docs/versioned_docs/version-2.0/92-development/03-ui.md deleted file mode 100644 index e8999b0be8..0000000000 --- a/docs/versioned_docs/version-2.0/92-development/03-ui.md +++ /dev/null @@ -1,39 +0,0 @@ -# UI Development - -To develop the UI you need to install [Node.js and pnpm](./01-getting-started.md#install-nodejs--pnpm). In addition it is recommended to use VS-Code with the recommended plugin selection to get features like auto-formatting, linting and typechecking. The UI is written with [Vue 3](https://v3.vuejs.org/) as Single-Page-Application accessing the Woodpecker REST api. - -## Setup - -The UI code is placed in `web/`. Change to that folder in your terminal with `cd web/` and install all dependencies by running `pnpm install`. For production builds the generated UI code is integrated into the Woodpecker server by using [go-embed](https://pkg.go.dev/embed). - -Testing UI changes would require us to rebuild the UI after each adjustment to the code by running `pnpm build` and restarting the Woodpecker server. To avoid this you can make use of the dev-proxy integrated into the Woodpecker server. This integrated dev-proxy will forward all none api request to a separate http-server which will only serve the UI files. - -![UI Proxy architecture](./ui-proxy.svg) - -Start the UI server locally with [hot-reloading](https://stackoverflow.com/a/41429055/8461267) by running: `pnpm start`. To enable the forwarding of requests to the UI server you have to enable the dev-proxy inside the Woodpecker server by adding `WOODPECKER_DEV_WWW_PROXY=http://localhost:8010` to your `.env` file. -After starting the Woodpecker server as explained in the [debugging](./01-getting-started.md#debugging-woodpecker) section, you should now be able to access the UI under [http://localhost:8000](http://localhost:8000). - -## Tools and frameworks - -The following list contains some tools and frameworks used by the Woodpecker UI. For some points we added some guidelines / hints to help you developing. - -- [Vue 3](https://v3.vuejs.org/) - - use `setup` and composition api - - place (re-usable) components in `web/src/components/` - - views should have a route in `web/src/router.ts` and are located in `web/src/views/` -- [Windicss](https://windicss.org/) (similar to Tailwind) - - use Windicss classes where possible - - if needed extend the Windicss config to use new classes -- [Vite](https://vitejs.dev/) (similar to Webpack) -- [Typescript](https://www.typescriptlang.org/) - - avoid using `any` and `unknown` (the linter will prevent you from doing so anyways :wink:) -- [eslint](https://eslint.org/) -- [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) - -## 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. -You must not provide translations except English in PRs, otherwise weblate could put git into conflicts (when someone has translated in that language file and changes are not into main branch yet) - -For more information about translations see [Translations](./07-translations.md). diff --git a/docs/versioned_docs/version-2.0/92-development/04-docs.md b/docs/versioned_docs/version-2.0/92-development/04-docs.md deleted file mode 100644 index 55ccb5b7d9..0000000000 --- a/docs/versioned_docs/version-2.0/92-development/04-docs.md +++ /dev/null @@ -1,20 +0,0 @@ -# Documentation - -The documentation is using docusaurus as framework. You can learn more about it from its [official documentation](https://docusaurus.io/docs/). - -If you only want to change some text it probably is enough if you just search for the corresponding [Markdown](https://www.markdownguide.org/basic-syntax/) file inside the `docs/docs/` folder and adjust it. If you want to change larger parts and test the rendered documentation you can run docusaurus locally. Similarly to the UI you need to install [Node.js and pnpm](./01-getting-started.md#install-nodejs--pnpm). After that you can run and build docusaurus locally by using the following commands: - -```bash -cd docs/ - -pnpm install - -# build plugins used by the docs -pnpm build:woodpecker-plugins - -# start docs with hot-reloading, so you can change the docs and directly see the changes in the browser without reloading it manually -pnpm start - -# or build the docs to deploy it to some static page hosting -pnpm build -``` diff --git a/docs/versioned_docs/version-2.0/92-development/05-architecture.md b/docs/versioned_docs/version-2.0/92-development/05-architecture.md deleted file mode 100644 index 466ab2171e..0000000000 --- a/docs/versioned_docs/version-2.0/92-development/05-architecture.md +++ /dev/null @@ -1,48 +0,0 @@ -# Architecture - -## Package architecture - -![Woodpecker architecture](./woodpecker-architecture.png) - -## System architecture - -### main package hierarchy - -| package | meaning | imports | -| ------------------ | -------------------------------------------------------------- | ------------------------------------- | -| `cmd/**` | parse command-line args & environment to stat server/cli/agent | all other | -| `agent/**` | code only agent (remote worker) will need | `pipeline`, `shared` | -| `cli/**` | code only cli tool does need | `pipeline`, `shared`, `woodpecker-go` | -| `server/**` | code only server will need | `pipeline`, `shared` | -| `shared/**` | code shared for all three main tools (go help utils) | only std and external libs | -| `woodpecker-go/**` | go client for server rest api | std | - -### Server - -| package | meaning | imports | -| -------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `server/api/**` | handle web requests from `server/router` | `pipeline`, `../badges`, `../ccmenue`, `../logging`, `../model`, `../pubsub`, `../queue`, `../forge`, `../shared`, `../store`, `shared`, (TODO: mv `server/router/middleware/session`) | -| `server/badges/**` | generate svg badges for pipelines | `../model` | -| `server/ccmenu/**` | generate xml ccmenu for pipelines | `../model` | -| `server/grpc/**` | gRPC server agents can connect to | `pipeline/rpc/**`, `../logging`, `../model`, `../pubsub`, `../queue`, `../forge`, `../pipeline`, `../store` | -| `server/logging/**` | logging lib for gPRC server to stream logs while running | std | -| `server/model/**` | structs for store (db) and api (json) | std | -| `server/plugins/**` | plugins for server | `../model`, `../forge` | -| `server/pipeline/**` | orchestrate pipelines | `pipeline`, `../model`, `../pubsub`, `../queue`, `../forge`, `../store`, `../plugins` | -| `server/pubsub/**` | pubsub lib for server to push changes to the WebUI | std | -| `server/queue/**` | queue lib for server where agents pull new pipelines from via gRPC | `server/model` | -| `server/forge/**` | forge lib for server to connect and handle forge specific stuff | `shared`, `server/model` | -| `server/router/**` | handle requests to REST API (and all middleware) and serve UI and WebUI config | `shared`, `../api`, `../model`, `../forge`, `../store`, `../web` | -| `server/store/**` | handle database | `server/model` | -| `server/shared/**` | TODO: move and split [#974](https://github.com/woodpecker-ci/woodpecker/issues/974) | -| `server/web/**` | server SPA | - -- `../` = `server/` - -### Agent - -TODO - -### CLI - -TODO diff --git a/docs/versioned_docs/version-2.0/92-development/06-guides.md b/docs/versioned_docs/version-2.0/92-development/06-guides.md deleted file mode 100644 index d78e4f3224..0000000000 --- a/docs/versioned_docs/version-2.0/92-development/06-guides.md +++ /dev/null @@ -1,39 +0,0 @@ -# Guides - -## ORM - -Woodpecker uses [Xorm](https://xorm.io/) as ORM for the database connection. -You can find its documentation at [gobook.io/read/gitea.com/xorm](https://gobook.io/read/gitea.com/xorm/manual-en-US/). - -## Add a new migration - -Woodpecker uses migrations to change the database schema if a database model has been changed. If for example a developer removes a property `Counter` from the model `Repo` in `server/model/` they would need to add a new migration task like the following example to a file like `server/store/datastore/migration/004_repos_drop_repo_counter.go`: - -```go -package migration - -import ( - "xorm.io/xorm" -) - -var alterTableReposDropCounter = task{ - name: "alter-table-drop-counter", - fn: func(sess *xorm.Session) error { - return dropTableColumns(sess, "repos", "repo_counter") - }, -} -``` - -:::info -Adding new properties to models will be handled automatically by the underlying [ORM](#orm) based on the [struct field tags](https://stackoverflow.com/questions/10858787/what-are-the-uses-for-tags-in-go) of the model. If you add a completely new model, you have to add it to the `allBeans` variable at `server/store/datastore/migration/migration.go` to get a new table created. -::: - -:::warning -You should not use `sess.Begin()`, `sess.Commit()` or `sess.Close()` inside a migration. Session / transaction handling will be done by the underlying migration manager. -::: - -To automatically execute the migration after the start of the server, the new migration needs to be added to the end of `migrationTasks` in `server/store/datastore/migration/migration.go`. After a successful execution of that transaction the server will automatically add the migration to a list, so it won't be executed again on the next start. - -## Constants of official images - -All official default images, are saved in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go) and must be pinned by an exact tag. diff --git a/docs/versioned_docs/version-2.0/92-development/07-translations.md b/docs/versioned_docs/version-2.0/92-development/07-translations.md deleted file mode 100644 index 6ddd9f1eb4..0000000000 --- a/docs/versioned_docs/version-2.0/92-development/07-translations.md +++ /dev/null @@ -1,9 +0,0 @@ -# Translations - -To translate the web UI into your language, we have [our own Weblate instance](https://translate.woodpecker-ci.org/). Please register there and translate Woodpecker into your language. **We won't accept PRs changing any language except English.** - - - Translation status - - -Woodpecker uses [Vue I18n](https://vue-i18n.intlify.dev/) as translation library. diff --git a/docs/versioned_docs/version-2.0/92-development/08-swagger.md b/docs/versioned_docs/version-2.0/92-development/08-swagger.md deleted file mode 100644 index 69cc97aab3..0000000000 --- a/docs/versioned_docs/version-2.0/92-development/08-swagger.md +++ /dev/null @@ -1,81 +0,0 @@ -# Swagger, API Spec and Code Generation - -Woodpecker uses [gin-swagger](https://github.com/swaggo/gin-swagger) middleware to automatically -generate Swagger v2 API specifications and a nice looking Web UI from the source code. -Also, the generated spec will be transformed into Markdown, using [go-swagger](https://github.com/go-swagger/go-swagger) -and then being using on the community's website documentation. - -It's paramount important to keep the gin handler function's godoc documentation up-to-date, -to always have accurate API documentation. -Whenever you change, add or enhance an API endpoint, please update the godocs. - -You don't require any extra tools on your machine, all Swagger tooling is automatically fetched by standard Go tools. - -## Gin-Handler API documentation guideline - -Here's a typical example of how annotations for Swagger documentation look like... - -```text ---- server/api/user.go --- -// @Summary Get a user -// @Description Returns a user with the specified login name. Requires admin rights. -// @Router /users/{login} [get] -// @Produce json -// @Success 200 {object} User -// @Tags Users -// @Param Authorization header string true "Insert your personal access token" default(Bearer ) -// @Param login path string true "the user's login name" -// @Param foobar query string false "optional foobar parameter" -// @Param page query int false "for response pagination, page offset number" default(1) -// @Param perPage query int false "for response pagination, max items per page" default(50) -``` - -```text ---- server/model/user.go --- -type User struct { - ID int64 `json:"id" xorm:"pk autoincr 'user_id'"` -// ... -} // @name User -``` - -These guidelines aim to have consistent wording in the swagger doc: - -- first word after `@Summary` and `@Summary` are always uppercase -- `@Summary` has no . (dot) at the end of the line -- model structs shall use custom short names, to ease life for API consumers, using `@name` -- `@Success` object or array declarations shall be short, this means the actual `model.User` struct must have a `@name` annotation, so that the model can be renderend in Swagger -- when pagination is used, `@Parame page` and `@Parame perPage` must be added manually -- `@Param Authorization` is almost always present, there are just a few un-protected endpoints - -There are many examples in the server/api package, which you can use a blueprint. -More enhanced information you can find here - -### Manual code generation - -#### generate the server's Go code containing the Swagger - -```bash -make generate-swagger -``` - -##### update the Markdown in the ./docs folder - -```bash -make docs -``` - -##### auto-format swagger related godoc - -```bash -go run github.com/swaggo/swag/cmd/swag@latest fmt -g server/api/z.go -``` - - - -**WARNING, known issue**: using swag v1.18.12 , there's a bug when running the `fmt` command, -which makes the swagger generator failing, because it can't find the models/structs/types anymore. -To fix it, please replace `// @name\tModelName` with `// @name ModelName`, -which means, replace the tab (`\t`) with a space (` `). -See == once this is merged and released, the mentioned issue is obsolete. - - diff --git a/docs/versioned_docs/version-2.0/92-development/09-security.md b/docs/versioned_docs/version-2.0/92-development/09-security.md deleted file mode 100644 index 2491fe0cc4..0000000000 --- a/docs/versioned_docs/version-2.0/92-development/09-security.md +++ /dev/null @@ -1,10 +0,0 @@ -# Security - -We take security seriously. -If you discover a security issue, please bring it to their attention right away! - -## Reporting a Vulnerability - -Please **DO NOT** file a public issue, instead send your report privately to [`security @ woodpecker-ci.org`](mailto:security@woodpecker-ci.org). - -Security reports are greatly appreciated, and we will publicly thank you for it. If you choose to remain anonymous, we will respect your request and keep your name confidential. diff --git a/docs/versioned_docs/version-2.0/92-development/_category_.yaml b/docs/versioned_docs/version-2.0/92-development/_category_.yaml deleted file mode 100644 index 02d70e09b5..0000000000 --- a/docs/versioned_docs/version-2.0/92-development/_category_.yaml +++ /dev/null @@ -1,4 +0,0 @@ -label: 'Development' -# position: 3 -collapsible: true -collapsed: true diff --git a/docs/versioned_docs/version-2.0/92-development/ui-proxy.svg b/docs/versioned_docs/version-2.0/92-development/ui-proxy.svg deleted file mode 100644 index 79809ffa19..0000000000 --- a/docs/versioned_docs/version-2.0/92-development/ui-proxy.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - - - - forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler) diff --git a/docs/versioned_docs/version-2.0/92-development/vscode-debug.png b/docs/versioned_docs/version-2.0/92-development/vscode-debug.png deleted file mode 100644 index 58861dbde1..0000000000 Binary files a/docs/versioned_docs/version-2.0/92-development/vscode-debug.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.0/92-development/vscode-run-test.png b/docs/versioned_docs/version-2.0/92-development/vscode-run-test.png deleted file mode 100644 index 6d163f8b8c..0000000000 Binary files a/docs/versioned_docs/version-2.0/92-development/vscode-run-test.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.0/92-development/woodpecker-architecture.png b/docs/versioned_docs/version-2.0/92-development/woodpecker-architecture.png deleted file mode 100644 index 22f6a054ae..0000000000 Binary files a/docs/versioned_docs/version-2.0/92-development/woodpecker-architecture.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.0/woodpecker.png b/docs/versioned_docs/version-2.0/woodpecker.png deleted file mode 100644 index b92f3589f5..0000000000 Binary files a/docs/versioned_docs/version-2.0/woodpecker.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/10-intro.md b/docs/versioned_docs/version-2.1/10-intro.md deleted file mode 100644 index 5a36deb657..0000000000 --- a/docs/versioned_docs/version-2.1/10-intro.md +++ /dev/null @@ -1,89 +0,0 @@ -# Welcome to Woodpecker - -Woodpecker is a simple yet powerful CI/CD engine with great extensibility. It focuses on executing pipelines inside [containers](https://opencontainers.org/). -If you are already using containers in your daily workflow, you'll for sure love Woodpecker. - -![woodpecker](woodpecker.png) - -## .woodpecker.yml - -- Place your pipeline in a file named `.woodpecker.yml` in your repository -- Pipeline steps can be named as you like -- Run any command in the commands section - -```yaml title=".woodpecker.yml" -steps: - build: - image: debian - commands: - - echo "This is the build step" - a-test-step: - image: debian - commands: - - echo "Testing.." -``` - -### Steps are containers - -- Define any container image as context - - either use your own and install the needed tools in a custom image - - or search for available images that are already tailored for your needs in image registries like [Docker Hub](https://hub.docker.com/search?type=image) -- List the commands that should be executed in the container - -```diff -steps: - build: -- image: debian -+ image: mycompany/image-with-awscli - commands: - - aws help -``` - -### File changes are incremental - -- Woodpecker clones the source code in the beginning -- File changes are persisted throughout individual steps as the same volume is being mounted in all steps - -```yaml title=".woodpecker.yml" -steps: - build: - image: debian - commands: - - touch myfile - a-test-step: - image: debian - commands: - - cat myfile -``` - -## Plugins are straightforward - -- If you copy the same shell script from project to project -- Pack it into a plugin instead -- And make the yaml declarative -- Plugins are Docker images with your script as an entrypoint - -```dockerfile title="Dockerfile" -FROM laszlocloud/kubectl -COPY deploy /usr/local/deploy -ENTRYPOINT ["/usr/local/deploy"] -``` - -```bash title="deploy" -kubectl apply -f $PLUGIN_TEMPLATE -``` - -```yaml title=".woodpecker.yml" -steps: - deploy-to-k8s: - image: laszlocloud/my-k8s-plugin - settings: - template: config/k8s/service.yml -``` - -See [plugin docs](./20-usage/51-plugins/10-plugins.md). - -## Continue reading - -- [Create a Woodpecker pipeline for your repository](./20-usage/10-intro.md) -- [Setup your own Woodpecker instance](./30-administration/00-deployment/00-overview.md) diff --git a/docs/versioned_docs/version-2.1/20-usage/10-intro.md b/docs/versioned_docs/version-2.1/20-usage/10-intro.md deleted file mode 100644 index 7893696683..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/10-intro.md +++ /dev/null @@ -1,72 +0,0 @@ -# Getting started - -## Repository Activation - -To activate your project navigate to your account settings. You will see a list of repositories which can be activated with a simple toggle. When you activate your repository, Woodpecker automatically adds webhooks to your forge (e.g. GitHub, Gitea, ...). - -Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your forge will automatically send a webhook to Woodpecker which will in turn trigger the pipeline execution. - -![repository list](repo-list.png) - -## Required Permissions - -The user who enables a repo in Woodpecker must have `Admin` rights on that repo, so that Woodpecker can add the webhook. - -:::note -Note that manually creating webhooks yourself is not possible. -This is because webhooks are signed using a per-repository secret key which is not exposed to end users. -::: - -## Configuration - -To configure your pipeline you must create a `.woodpecker.yml` file in the root of your repository. The `.woodpecker.yml` file is used to define your pipeline steps. - -:::note -We support most of YAML 1.2, but preserve some behavior from 1.1 for backward compatibility. -Read more at: [https://github.com/go-yaml/yaml](https://github.com/go-yaml/yaml/tree/v3) -::: - -Example pipeline configuration: - -```yaml -steps: - build: - image: golang - commands: - - go get - - go build - - go test - -services: - postgres: - image: postgres:9.4.5 - environment: - - POSTGRES_USER=myapp -``` - -Example pipeline configuration with multiple, serial steps: - -```yaml -steps: - backend: - image: golang - commands: - - go get - - go build - - go test - - frontend: - image: node:6 - commands: - - npm install - - npm test - - notify: - image: plugins/slack - channel: developers - username: woodpecker -``` - -## Execution - -To trigger your first pipeline execution you can push code to your repository, open a pull request, or push a tag. Any of these events triggers a webhook from your forge and execute your pipeline. diff --git a/docs/versioned_docs/version-2.1/20-usage/15-terminiology/architecture.excalidraw b/docs/versioned_docs/version-2.1/20-usage/15-terminiology/architecture.excalidraw deleted file mode 100644 index b3eba1aab3..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/15-terminiology/architecture.excalidraw +++ /dev/null @@ -1,1549 +0,0 @@ -{ - "type": "excalidraw", - "version": 2, - "source": "https://excalidraw.com", - "elements": [ - { - "type": "rectangle", - "version": 226, - "versionNonce": 1002880859, - "isDeleted": false, - "id": "UczUX5VuNnCB1rVvUJVfm", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 487.098092529257, - "y": 320.8758615860986, - "strokeColor": "#1971c2", - "backgroundColor": "#e7f5ff", - "width": 472.8823858375721, - "height": 183.19688715994928, - "seed": 917720693, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "Kqbwk_qfkALJfhtCIr2eS", - "type": "arrow" - } - ], - "updated": 1697530113380, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 161, - "versionNonce": 286006267, - "isDeleted": false, - "id": "sKPZmBSWUdAYfBs4ByItH", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 539.5451038202509, - "y": 345.2419383247636, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "width": 82.46875, - "height": 32.199999999999996, - "seed": 1485551573, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113380, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Server", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Server", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "rectangle", - "version": 333, - "versionNonce": 448586907, - "isDeleted": false, - "id": "_A8uznhnpXuQBYzjP-iVx", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 649.8080506852966, - "y": 427.60908869342575, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 136, - "height": 60, - "seed": 1783625013, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "r90dckf8trHemYzEwCgCW" - }, - { - "id": "XxfJWnHonmvNOJzMFSlie", - "type": "arrow" - } - ], - "updated": 1697530113380, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 298, - "versionNonce": 1244067771, - "isDeleted": false, - "id": "r90dckf8trHemYzEwCgCW", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 703.8080506852966, - "y": 441.5090886934257, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 28, - "height": 32.199999999999996, - "seed": 660965013, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113383, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "UI", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "_A8uznhnpXuQBYzjP-iVx", - "originalText": "UI", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "rectangle", - "version": 105, - "versionNonce": 265992667, - "isDeleted": false, - "id": "v2eEwSOSRQBZ79O6wyzGf", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 800.9240766836483, - "y": 421.4987043996123, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 135.3671503686619, - "height": 62.2689029398432, - "seed": 1115810805, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "svsVhxCbatcLj7lQLch0P" - }, - { - "id": "TvtonmlV0W8__pnTG-wVZ", - "type": "arrow" - }, - { - "id": "5tl702dfcvJDLz9aIFU0P", - "type": "arrow" - } - ], - "updated": 1697530113380, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 83, - "versionNonce": 1706870395, - "isDeleted": false, - "id": "svsVhxCbatcLj7lQLch0P", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 828.1594096804793, - "y": 436.53315586953386, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 80.896484375, - "height": 32.199999999999996, - "seed": 2074781013, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113380, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "GRPC", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "v2eEwSOSRQBZ79O6wyzGf", - "originalText": "GRPC", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "rectangle", - "version": 270, - "versionNonce": 418660123, - "isDeleted": false, - "id": "hSrrwwnm9y7R-_CnJtaK1", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1065.567103519039, - "y": 556.4146894573112, - "strokeColor": "#2f9e44", - "backgroundColor": "#ebfbee", - "width": 601.932705468054, - "height": 175.07489600604117, - "seed": 1983197877, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "TvtonmlV0W8__pnTG-wVZ", - "type": "arrow" - } - ], - "updated": 1697530113380, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 154, - "versionNonce": 871605179, - "isDeleted": false, - "id": "8tsYgVssKnBd_Zw1QuqNz", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1298.4367898442752, - "y": 566.567242947784, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 96.5234375, - "height": 32.199999999999996, - "seed": 1321669653, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Agent 1", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Agent 1", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "text", - "version": 182, - "versionNonce": 1323136091, - "isDeleted": false, - "id": "eeugZg73_yD_6uLBBgmcX", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 404.5001910129067, - "y": 707.1233710221009, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 210.068359375, - "height": 32.199999999999996, - "seed": 1901447541, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "User => Browser", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "User => Browser", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "ellipse", - "version": 106, - "versionNonce": 1501835515, - "isDeleted": false, - "id": "mlDhl4OOc-H1tNgh77AAW", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 482.5857164810477, - "y": 602.4394551739279, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 46.024748503793035, - "height": 44.21988070606176, - "seed": 791073493, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "line", - "version": 166, - "versionNonce": 627726747, - "isDeleted": false, - "id": "ADEXzdYAhvj-_wVRftTIg", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 459.12202200277807, - "y": 697.1964604319912, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 80.31792517362464, - "height": 31.585599568061298, - "seed": 349155381, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": null, - "endBinding": null, - "lastCommittedPoint": null, - "startArrowhead": null, - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 42.415150610916044, - -28.87829787146393 - ], - [ - 80.31792517362464, - 2.7073016965973693 - ] - ] - }, - { - "type": "rectangle", - "version": 231, - "versionNonce": 801271355, - "isDeleted": false, - "id": "xmz4J-rxLIjfUQ4q19PjD", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 516.8788931508789, - "y": 870.4664542146543, - "strokeColor": "#f08c00", - "backgroundColor": "#fff4e6", - "width": 385.34512717560705, - "height": 60.464035142111264, - "seed": 3531157, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "05EJzh4NLXxemaKAmdi5n", - "type": "arrow" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 93, - "versionNonce": 728690395, - "isDeleted": false, - "id": "gSbpry_947XArfI7b6AAL", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 636.1468430141358, - "y": 878.5884970070326, - "strokeColor": "#f08c00", - "backgroundColor": "transparent", - "width": 132.2890625, - "height": 32.199999999999996, - "seed": 1989076725, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Autoscaler", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Autoscaler", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "text", - "version": 118, - "versionNonce": 1258445691, - "isDeleted": false, - "id": "WVy0mdTGbUx08RuxdQUH8", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 523.3741602213286, - "y": 907.372811672524, - "strokeColor": "#f08c00", - "backgroundColor": "transparent", - "width": 369.1484375, - "height": 18.4, - "seed": 979386453, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "Starts agents based on amount of pending pipelines", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Starts agents based on amount of pending pipelines", - "lineHeight": 1.15, - "baseline": 14 - }, - { - "type": "text", - "version": 373, - "versionNonce": 1254044699, - "isDeleted": false, - "id": "0Y1RcqzVFBFqh-wy-APMI", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1232.1955835481922, - "y": 605.8737363119278, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 292.6171875, - "height": 18.4, - "seed": 561999285, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "Executes pending workflows of a pipeline", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Executes pending workflows of a pipeline", - "lineHeight": 1.15, - "baseline": 14 - }, - { - "type": "text", - "version": 630, - "versionNonce": 983038139, - "isDeleted": false, - "id": "lGumbhMs3xx1vU2632hli", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 505.62283787078286, - "y": 383.42044095379515, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "width": 158.015625, - "height": 36.8, - "seed": 722595605, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "Central unit of a \nWoodpecker instance ", - "textAlign": "center", - "verticalAlign": "top", - "containerId": null, - "originalText": "Central unit of a \nWoodpecker instance ", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "rectangle", - "version": 131, - "versionNonce": 137308507, - "isDeleted": false, - "id": "PbSQXehWVLYcQGXYFpd-B", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 971.7123256059622, - "y": 171.06951064323448, - "strokeColor": "#be4bdb", - "backgroundColor": "#f8f0fc", - "width": 274.3443117379593, - "height": 74.90311522655017, - "seed": 1435321461, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "Kqbwk_qfkALJfhtCIr2eS", - "type": "arrow" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 96, - "versionNonce": 1222067707, - "isDeleted": false, - "id": "2P2tz29C_2sUzVNSpaG17", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1065.5206131439782, - "y": 183.12082907329545, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 73.14453125, - "height": 32.199999999999996, - "seed": 884403669, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Forge", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Forge", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "text", - "version": 141, - "versionNonce": 1133694619, - "isDeleted": false, - "id": "0eYhFYPuRanZ7wkR2OlHO", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 986.864582863368, - "y": 225.1223531590797, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 247.234375, - "height": 18.4, - "seed": 1201957685, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "HK1jmIcPmM6Us6Jrynobb", - "type": "arrow" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "Github, Gitea, Github, Bitbucket, ...", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Github, Gitea, Github, Bitbucket, ...", - "lineHeight": 1.15, - "baseline": 14 - }, - { - "type": "rectangle", - "version": 55, - "versionNonce": 991183675, - "isDeleted": false, - "id": "dihpRzuIc-UoRSsOI33SZ", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 820.419424341303, - "y": 340.29123237109366, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 117, - "height": 60, - "seed": 247151765, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "bcUL-u4zkLA9CLG2YdaeN" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 38, - "versionNonce": 2008949723, - "isDeleted": false, - "id": "bcUL-u4zkLA9CLG2YdaeN", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 831.853994653803, - "y": 358.79123237109366, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 94.130859375, - "height": 23, - "seed": 1638982133, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Webhooks", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "dihpRzuIc-UoRSsOI33SZ", - "originalText": "Webhooks", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 93, - "versionNonce": 295891067, - "isDeleted": false, - "id": "Bphhue86mMXHN4klGamM3", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 697.3018309300141, - "y": 339.607928999312, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 117, - "height": 60, - "seed": 92986197, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "0YxY2hEPyDWFqR8_-f6bn" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 87, - "versionNonce": 2055547163, - "isDeleted": false, - "id": "0YxY2hEPyDWFqR8_-f6bn", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 727.4522215550141, - "y": 358.107928999312, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 56.69921875, - "height": 23, - "seed": 43952309, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "OAuth", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "Bphhue86mMXHN4klGamM3", - "originalText": "OAuth", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "arrow", - "version": 284, - "versionNonce": 1205292475, - "isDeleted": false, - "id": "HK1jmIcPmM6Us6Jrynobb", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1205.6453201409104, - "y": 250.4849674923464, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 272.1094712799886, - "height": 94.31865813977868, - "seed": 982632981, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "uDIWJ5K5mEBL9QaiNk3cS" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": { - "elementId": "0eYhFYPuRanZ7wkR2OlHO", - "focus": -0.8418551162334328, - "gap": 6.962614333266799 - }, - "endBinding": null, - "lastCommittedPoint": null, - "startArrowhead": null, - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - -69.68740859223726, - 65.87860410965993 - ], - [ - -272.1094712799886, - 94.31865813977868 - ] - ] - }, - { - "type": "text", - "version": 53, - "versionNonce": 1803962459, - "isDeleted": false, - "id": "uDIWJ5K5mEBL9QaiNk3cS", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1050.575099048673, - "y": 297.96357160200637, - "strokeColor": "#be4bdb", - "backgroundColor": "#b2f2bb", - "width": 170.765625, - "height": 36.8, - "seed": 1046069109, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113385, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "sends events like push, \ntag, ...", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "HK1jmIcPmM6Us6Jrynobb", - "originalText": "sends events like push, tag, ...", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "arrow", - "version": 487, - "versionNonce": 335895291, - "isDeleted": false, - "id": "Kqbwk_qfkALJfhtCIr2eS", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 792.0835609101814, - "y": 316.38601649373913, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 176.92139414789008, - "height": 122.73778943055902, - "seed": 1681656021, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "yvJTQ64RU50N6-hxEQlkl" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": { - "elementId": "UczUX5VuNnCB1rVvUJVfm", - "focus": -0.03867359238356983, - "gap": 4.489845092359474 - }, - "endBinding": { - "elementId": "PbSQXehWVLYcQGXYFpd-B", - "focus": 0.7798878042817562, - "gap": 2.707370547890605 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 60.422360349016344, - -71.97786730696657 - ], - [ - 176.92139414789008, - -122.73778943055902 - ] - ] - }, - { - "type": "text", - "version": 62, - "versionNonce": 301106427, - "isDeleted": false, - "id": "yvJTQ64RU50N6-hxEQlkl", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 773.7910775091977, - "y": 226.00814918677256, - "strokeColor": "#be4bdb", - "backgroundColor": "#b2f2bb", - "width": 157.4296875, - "height": 36.8, - "seed": 500049461, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113385, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "allows users to login \nusing existing account", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "Kqbwk_qfkALJfhtCIr2eS", - "originalText": "allows users to login using existing account", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "arrow", - "version": 393, - "versionNonce": 598459861, - "isDeleted": false, - "id": "TvtonmlV0W8__pnTG-wVZ", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 936.9267543177084, - "y": 458.95033086418084, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 215.17788326846676, - "height": 93.99151368376693, - "seed": 234198933, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "rFf6NIofw6UBOyAFwg0Kn" - } - ], - "updated": 1697530127259, - "link": null, - "locked": false, - "startBinding": { - "elementId": "v2eEwSOSRQBZ79O6wyzGf", - "focus": -0.30339107267010673, - "gap": 1 - }, - "endBinding": { - "elementId": "hSrrwwnm9y7R-_CnJtaK1", - "focus": -0.14057158065513534, - "gap": 3.4728449093634026 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 130.0760301643047, - 42.90930518030268 - ], - [ - 215.17788326846676, - 93.99151368376693 - ] - ] - }, - { - "type": "text", - "version": 8, - "versionNonce": 1693330843, - "isDeleted": false, - "id": "rFf6NIofw6UBOyAFwg0Kn", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 997.4942845557462, - "y": 473.9409015069133, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 161.4140625, - "height": 36.8, - "seed": 1592253685, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113386, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "receives workflows & \nreturns logs + statuses", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "TvtonmlV0W8__pnTG-wVZ", - "originalText": "receives workflows & returns logs + statuses", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "arrow", - "version": 270, - "versionNonce": 1855882619, - "isDeleted": false, - "id": "5tl702dfcvJDLz9aIFU0P", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 886.0581619083632, - "y": 485.67004123832135, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 174.09447592006472, - "height": 326.4905563076211, - "seed": 1479177813, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "apyMCAv2GIN_yzHXwX4tY" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": { - "elementId": "v2eEwSOSRQBZ79O6wyzGf", - "focus": -0.1341191028023529, - "gap": 1.9024338988657519 - }, - "endBinding": { - "elementId": "pxF49EKDNO6IZq_34i7bY", - "focus": -0.7088661407505865, - "gap": 4.060573862784622 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 44.14165353942735, - 196.18483635907205 - ], - [ - 174.09447592006472, - 326.4905563076211 - ] - ] - }, - { - "type": "text", - "version": 66, - "versionNonce": 2007745083, - "isDeleted": false, - "id": "apyMCAv2GIN_yzHXwX4tY", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 849.4927841977906, - "y": 663.4548775973934, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 161.4140625, - "height": 36.8, - "seed": 882041781, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113386, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "receives workflows & \nreturns logs + statuses", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "5tl702dfcvJDLz9aIFU0P", - "originalText": "receives workflows & returns logs + statuses", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "arrow", - "version": 347, - "versionNonce": 1353818811, - "isDeleted": false, - "id": "XxfJWnHonmvNOJzMFSlie", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 534.9278465333664, - "y": 595.2199151317081, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 113.88020415193023, - "height": 119.81968366814112, - "seed": 944153877, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": null, - "endBinding": { - "elementId": "_A8uznhnpXuQBYzjP-iVx", - "focus": 0.5397285671082249, - "gap": 1 - }, - "lastCommittedPoint": null, - "startArrowhead": null, - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 113.88020415193023, - -119.81968366814112 - ] - ] - }, - { - "type": "rectangle", - "version": 61, - "versionNonce": 1099141979, - "isDeleted": false, - "id": "j56ZKRwmXk72nHrZzLz_1", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1081.8110514012087, - "y": 652.5253283508498, - "strokeColor": "#2f9e44", - "backgroundColor": "#ebfbee", - "width": 566.7373014532342, - "height": 68.58600908319681, - "seed": 112933493, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 82, - "versionNonce": 1879994363, - "isDeleted": false, - "id": "cAVYXfBRnfuGAv7QTQVow", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1300.6584159706863, - "y": 658.8425033454967, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 77.83203125, - "height": 23, - "seed": 951460821, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Backend", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Backend", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "text", - "version": 376,- add some images explaining the architecture & terminology with -pipeline -> workflow -> step -- combine advanced config usage -- rename pipeline syntax to workflow syntax (and most references to -pipeline steps etc as well) -- update agent registration part -- add bug note to secrets encryption setting -- remove usage from readme to point to up-to-date docs page -- typos -- closes #1408 - ---------- - "angle": 0, - "x": 1094.1972977313717, - "y": 681.8988272758752, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 530.9453125, - "height": 55.199999999999996, - "seed": 843899189, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "The backend is the environment (exp. Docker / Kubernetes / local) used to \nexecute workflows in.\n", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "The backend is the environment (exp. Docker / Kubernetes / local) used to \nexecute workflows in.\n", - "lineHeight": 1.15, - "baseline": 50 - }, - { - "type": "rectangle", - "version": 384, - "versionNonce": 1778969915, - "isDeleted": false, - "id": "pxF49EKDNO6IZq_34i7bY", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1064.2132116912126, - "y": 754.5018564383092, - "strokeColor": "#2f9e44", - "backgroundColor": "#ebfbee", - "width": 601.932705468054, - "height": 175.07489600604117, - "seed": 954528405, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "05EJzh4NLXxemaKAmdi5n", - "type": "arrow" - }, - { - "id": "5tl702dfcvJDLz9aIFU0P", - "type": "arrow" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "arrow", - "version": 154, - "versionNonce": 1988988379, - "isDeleted": false, - "id": "05EJzh4NLXxemaKAmdi5n", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 904.0288881242177, - "y": 882.4966027880746, - "strokeColor": "#f08c00", - "backgroundColor": "transparent", - "width": 158.83070714434325, - "height": 32.735025983189644, - "seed": 1228134389, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "yNxAOEPZu_Jl7mnI01OXs" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": { - "elementId": "xmz4J-rxLIjfUQ4q19PjD", - "gap": 1.8048677977312764, - "focus": 0.31250963573550006 - }, - "endBinding": { - "elementId": "pxF49EKDNO6IZq_34i7bY", - "gap": 1.353616422651612, - "focus": 0.36496042109885213 - }, - "lastCommittedPoint": null, - "startArrowhead": null, - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 158.83070714434325, - -32.735025983189644 - ] - ] - }, - { - "type": "text", - "version": 25, - "versionNonce": 1393410779, - "isDeleted": false, - "id": "yNxAOEPZu_Jl7mnI01OXs", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 963.8856479463893, - "y": 856.9290897964797, - "strokeColor": "#f08c00", - "backgroundColor": "#b2f2bb", - "width": 39.1171875, - "height": 18.4, - "seed": 759107925, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113387, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "starts", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "05EJzh4NLXxemaKAmdi5n", - "originalText": "starts", - "lineHeight": 1.15, - "baseline": 14 - }, - { - "type": "text", - "version": 187, - "versionNonce": 671224603, - "isDeleted": false, - "id": "sSj4Pda-fo-BBYM_dzml6", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1296.0854928322988, - "y": 776.6118140041631, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 104.2890625, - "height": 32.199999999999996, - "seed": 1381768885, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Agent ...", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Agent ...", - "lineHeight": 1.15, - "baseline": 25 - } - ], - "appState": { - "gridSize": null, - "viewBackgroundColor": "#ffffff" - }, - "files": {} -} diff --git a/docs/versioned_docs/version-2.1/20-usage/15-terminiology/architecture.svg b/docs/versioned_docs/version-2.1/20-usage/15-terminiology/architecture.svg deleted file mode 100644 index b34e96fdd8..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/15-terminiology/architecture.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - - - - - ServerUIGRPCAgent 1User => BrowserAutoscalerStarts agents based on amount of pending pipelinesExecutes pending workflows of a pipelineCentral unit of a Woodpecker instance ForgeGithub, Gitea, Github, Bitbucket, ...WebhooksOAuthsends events like push, tag, ...allows users to login using existing accountreceives workflows & returns logs + statusesreceives workflows & returns logs + statusesBackendThe backend is the environment (exp. Docker / Kubernetes / local) used to execute workflows in.startsAgent ... diff --git a/docs/versioned_docs/version-2.1/20-usage/15-terminiology/index.md b/docs/versioned_docs/version-2.1/20-usage/15-terminiology/index.md deleted file mode 100644 index 18e015d14d..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/15-terminiology/index.md +++ /dev/null @@ -1,61 +0,0 @@ -# Terminology - -## Woodpecker architecture - -![Woodpecker architecture](architecture.svg) - -## Pipeline, workflow & step - -![Relation between pipelines, workflows and steps](pipeline-workflow-step.svg) - -## Glossary - -- **Woodpecker CI**: The project name around Woodpecker. -- **Woodpecker**: An open-source tool that executes [pipelines][Pipeline] on your code. -- **Server**: The component of Woodpecker that handles webhooks from forges, orchestrates agents, and sends status back. It also serves the API and web UI for administration and configuration. -- **Agent**: A component of Woodpecker that executes [pipelines][Pipeline] (specifically one or more [workflows][Workflow]) with a specific backend (e.g. [Docker][], Kubernetes, [local][Local]). It connects to the server via GRPC. -- **CLI**: The Woodpecker command-line interface (CLI) is a terminal tool used to administer the server, to execute pipelines locally for debugging / testing purposes, and to perform tasks like linting pipelines. -- **Pipeline**: A sequence of [workflows][Workflow] that are executed on the code. [Pipelines][Pipeline] are triggered by events. -- **Workflow**: A sequence of steps and services that are executed as part of a [pipeline][Pipeline]. Workflows are represented by YAML files. Each [workflow][Workflow] has its own isolated [workspace][Workspace], and often additional resources like a shared network (docker). -- **Steps**: Individual commands, actions or tasks within a [workflow][Workflow]. -- **Code**: Refers to the files tracked by the version control system used by the [forge][Forge]. -- **Repos**: Short for repositories, these are storage locations where code is stored. -- **Forge**: The hosting platform or service where the repositories are hosted. -- **Workspace**: A folder shared between all steps of a [workflow][Workflow] containing the repository and all the generated data from previous steps. -- **Event**: Triggers the execution of a [pipeline][Pipeline], such as a [forge][Forge] event like `push`, or `manual` triggered manually from the UI. -- **Commit**: A defined state of the code, usually associated with a version control system like Git. -- **Matrix**: A configuration option that allows the execution of [workflows][Workflow] for each value in the [matrix][Matrix]. -- **Service**: A service is a step that is executed from the start of a [workflow][Workflow] until its end. It can be accessed by name via the network from other steps within the same [workflow][Workflow]. -- **Plugins**: [Plugins][Plugin] are extensions that provide pre-defined actions or commands for a step in a [workflow][Workflow]. They can be configured via settings. -- **Container**: A lightweight and isolated environment where commands are executed. -- **YAML File**: A file format used to define and configure [workflows][Workflow]. -- **Dependency**: [Workflows][Workflow] can depend on each other, and if possible, they are executed in parallel. -- **Status**: Status refers to the outcome of a step or [workflow][Workflow] after it has been executed, determined by the internal command exit code. At the end of a [workflow][Workflow], its status is sent to the [forge][Forge]. - -## Pipeline events - -- `push`: A push event is triggered when a commit is pushed to a branch. -- `pull_request`: A pull request event is triggered when a pull request is opened or a new commit is pushed to it. -- `pull_request_closed`: A pull request closed event is triggered when a pull request is closed or merged. -- `tag`: A tag event is triggered when a tag is pushed. -- `manual`: A manual event is triggered when a user manually triggers a pipeline. -- `cron`: A cron event is triggered when a cron job is executed. - -## Conventions - -Sometimes there are multiple terms that can be used to describe something. This section lists the preferred terms to use in Woodpecker: - -- Environment variables `*_LINK` should be called `*_URL`. In the code use `URL()` instead of `Link()` -- Use the term **pipelines** instead of the previous **builds** -- Use the term **steps** instead of the previous **jobs** - - - -[Pipeline]: ../20-workflow-syntax.md -[Workflow]: ../25-workflows.md -[Forge]: ../../30-administration/11-forges/10-overview.md -[Plugin]: ../51-plugins/10-plugins.md -[Workspace]: ../20-workflow-syntax.md#workspace -[Matrix]: ../30-matrix-workflows.md -[Docker]: ../../30-administration/22-backends/10-docker.md -[Local]: ../../30-administration/22-backends/20-local.md diff --git a/docs/versioned_docs/version-2.1/20-usage/15-terminiology/pipeline-workflow-step.excalidraw b/docs/versioned_docs/version-2.1/20-usage/15-terminiology/pipeline-workflow-step.excalidraw deleted file mode 100644 index 28704cff54..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/15-terminiology/pipeline-workflow-step.excalidraw +++ /dev/null @@ -1,1077 +0,0 @@ -{ - "type": "excalidraw", - "version": 2, - "source": "https://excalidraw.com", - "elements": [ - { - "type": "rectangle", - "version": 97, - "versionNonce": 257762037, - "isDeleted": false, - "id": "Y3hYdpX9r1qWfyHWs7AXT", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 393.622323134362, - "y": 336.02197155458475, - "strokeColor": "#1971c2", - "backgroundColor": "#e7f5ff", - "width": 366.3936710429598, - "height": 499.95605689083004, - "seed": 875444373, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 67, - "versionNonce": 369556565, - "isDeleted": false, - "id": "g1Eb010Kx_KFryVqNYWBQ", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 520.0116988873679, - "y": 363.32095846456355, - "strokeColor": "#1971c2", - "backgroundColor": "#b2f2bb", - "width": 99.626953125, - "height": 32.199999999999996, - "seed": 1466195445, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "9laL3864YWOna6NQlVDqq", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Pipeline", - "textAlign": "center", - "verticalAlign": "top", - "containerId": null, - "originalText": "Pipeline", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "rectangle", - "version": 314, - "versionNonce": 1983028731, - "isDeleted": false, - "id": "9o-DNP0YdlIGVz1kEm_hW", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 407.1590381712276, - "y": 410.9252244837219, - "strokeColor": "#be4bdb", - "backgroundColor": "#f8f0fc", - "width": 340.12211164367193, - "height": 199, - "seed": 1869535061, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "FU4jk6Tz6duLaaZE0Z55A", - "type": "arrow" - }, - { - "id": "9laL3864YWOna6NQlVDqq", - "type": "arrow" - } - ], - "updated": 1697530083624, - "link": null, - "locked": false - }, - { - "type": "rectangle", - "version": 156, - "versionNonce": 1495247317, - "isDeleted": false, - "id": "q4TKpiq2KAwPaz19GdhtK", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 490.3194993196821, - "y": 473.52959018719525, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 111355061, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "ya0JzDo-4oscHIq87TZ_D" - }, - { - "id": "1ZbDRqbETCkEx62nCmnpJ", - "type": "arrow" - }, - { - "id": "FU4jk6Tz6duLaaZE0Z55A", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 156, - "versionNonce": 1469425461, - "isDeleted": false, - "id": "ya0JzDo-4oscHIq87TZ_D", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 566.0118821321821, - "y": 478.52959018719525, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 95.615234375, - "height": 23, - "seed": 1084671509, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Clone step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "q4TKpiq2KAwPaz19GdhtK", - "originalText": "Clone step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 236, - "versionNonce": 1535319541, - "isDeleted": false, - "id": "AOJLQFldoHd2vxVtB2jrS", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 491.2218643672577, - "y": 519.7800332298218, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 812596085, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "FRby8A9aUiKvHpM5mCdDN" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 231, - "versionNonce": 28677973, - "isDeleted": false, - "id": "FRby8A9aUiKvHpM5mCdDN", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 583.0324112422577, - "y": 524.7800332298218, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 63.37890625, - "height": 23, - "seed": 1849820373, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "1. Step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "AOJLQFldoHd2vxVtB2jrS", - "originalText": "1. Step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 291, - "versionNonce": 571598005, - "isDeleted": false, - "id": "2WwuMWX7YawqK0i1rDPJo", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 489.6426911083554, - "y": 567.609787233933, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 1840554549, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "UOwxmKIS0W62CFt_ffEy4" - }, - { - "id": "379hO6Dc5rygB38JgDbVo", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 289, - "versionNonce": 4032021, - "isDeleted": false, - "id": "UOwxmKIS0W62CFt_ffEy4", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 581.4532379833554, - "y": 572.609787233933, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 63.37890625, - "height": 23, - "seed": 330077077, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "2. Step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "2WwuMWX7YawqK0i1rDPJo", - "originalText": "2. Step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "arrow", - "version": 296, - "versionNonce": 1539516059, - "isDeleted": false, - "id": "9laL3864YWOna6NQlVDqq", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 630.0635849044402, - "y": 383.14314287821776, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "width": 294.3024370154917, - "height": 36.656016722015465, - "seed": 207575285, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": { - "elementId": "9o-DNP0YdlIGVz1kEm_hW", - "focus": -1.000156025347643, - "gap": 27.782081605504118 - }, - "endBinding": { - "elementId": "vS2PNUbmeBe3EPxl-dID8", - "focus": 0.7761987167055517, - "gap": 8.978940924346716 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 294.3024370154917, - -36.656016722015465 - ] - ] - }, - { - "type": "text", - "version": 249, - "versionNonce": 2076402229, - "isDeleted": false, - "id": "vS2PNUbmeBe3EPxl-dID8", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 933.3449628442786, - "y": 336.02200598023114, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "width": 301.298828125, - "height": 46, - "seed": 1632793173, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "9laL3864YWOna6NQlVDqq", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "A pipeline is triggered by an event\nlike a push, tag, manual", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "A pipeline is triggered by an event\nlike a push, tag, manual", - "lineHeight": 1.15, - "baseline": 41 - }, - { - "type": "arrow", - "version": 751, - "versionNonce": 1371044827, - "isDeleted": false, - "id": "FU4jk6Tz6duLaaZE0Z55A", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 751.1619011845514, - "y": 440.8355079324799, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 160.46519124360202, - "height": 2.2452348338335923, - "seed": 1331388341, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": { - "elementId": "9o-DNP0YdlIGVz1kEm_hW", - "focus": -0.6591700594229558, - "gap": 3.8807513696519322 - }, - "endBinding": { - "elementId": "wfFvnFZuh0npL9hh0ez7o", - "focus": 0.7652411053273549, - "gap": 20.75618622779257 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 160.46519124360202, - -2.2452348338335923 - ] - ] - }, - { - "type": "rectangle", - "version": 440, - "versionNonce": 819540565, - "isDeleted": false, - "id": "TbejdIYo_qNDw15yLP2IB", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 406.0812257713851, - "y": 626.8305540252475, - "strokeColor": "#be4bdb", - "backgroundColor": "#f8f0fc", - "width": 340.12211164367193, - "height": 199, - "seed": 1553965333, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 466, - "versionNonce": 663477, - "isDeleted": false, - "id": "wfFvnFZuh0npL9hh0ez7o", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 932.383278655946, - "y": 424.0107569968011, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 481.2890625, - "height": 115, - "seed": 781497973, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "FU4jk6Tz6duLaaZE0Z55A", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Every pipeline consists of multiple workflows.\nEach defined by a separate YAML file and is named \nafter the filename.\nEach workflow has its own workspace (folder) which is\nused by all steps of that workflow.", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "Every pipeline consists of multiple workflows.\nEach defined by a separate YAML file and is named \nafter the filename.\nEach workflow has its own workspace (folder) which is\nused by all steps of that workflow.", - "lineHeight": 1.15, - "baseline": 110 - }, - { - "type": "arrow", - "version": 464, - "versionNonce": 734626075, - "isDeleted": false, - "id": "1ZbDRqbETCkEx62nCmnpJ", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 741.0645380446722, - "y": 492.31283255558515, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 178.4459423531871, - "height": 83.08707392565111, - "seed": 536879061, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": { - "elementId": "q4TKpiq2KAwPaz19GdhtK", - "focus": -0.7697471991854113, - "gap": 3.7450387249900814 - }, - "endBinding": { - "elementId": "Vu0JJ6ZWuEhEyCfxeHPtc", - "focus": -0.7822252364700005, - "gap": 8.360835317635974 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 178.4459423531871, - 83.08707392565111 - ] - ] - }, - { - "type": "text", - "version": 327, - "versionNonce": 371646421, - "isDeleted": false, - "id": "Vu0JJ6ZWuEhEyCfxeHPtc", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 927.8713157154953, - "y": 563.2132686484658, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 491.357421875, - "height": 46, - "seed": 385310005, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "1ZbDRqbETCkEx62nCmnpJ", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "The default first step of each workflow is the clone step.\nIts fetches the specific code version for a pipeline.", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "The default first step of each workflow is the clone step.\nIts fetches the specific code version for a pipeline.", - "lineHeight": 1.15, - "baseline": 41 - }, - { - "type": "text", - "version": 91, - "versionNonce": 1180085909, - "isDeleted": false, - "id": "0tGx2VdJLNf7W6HD76dtO", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 427.6895298601876, - "y": 432.3583566254258, - "strokeColor": "#9c36b5", - "backgroundColor": "#a5d8ff", - "width": 143.876953125, - "height": 23, - "seed": 450883221, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Workflow \"build\"", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "Workflow \"build\"", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 338, - "versionNonce": 957223925, - "isDeleted": false, - "id": "LQ2h2aO9uzDWyLG6OLn70", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 487.7251825950889, - "y": 685.3516128043414, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 711939061, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "8EqaPnZX2CgLaF08UNZZg" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 340, - "versionNonce": 510774613, - "isDeleted": false, - "id": "8EqaPnZX2CgLaF08UNZZg", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 563.4175654075889, - "y": 690.3516128043414, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 95.615234375, - "height": 23, - "seed": 1370164565, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Clone step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "LQ2h2aO9uzDWyLG6OLn70", - "originalText": "Clone step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 421, - "versionNonce": 97999541, - "isDeleted": false, - "id": "St9t4nwHuXXVlmjDqfn_Z", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 488.62754764266447, - "y": 731.6020558469675, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 2145950389, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "DX10t075MMDu7BLtuUaij" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 417, - "versionNonce": 2011446293, - "isDeleted": false, - "id": "DX10t075MMDu7BLtuUaij", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 580.4380945176645, - "y": 736.6020558469675, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 63.37890625, - "height": 23, - "seed": 500005909, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "1. Step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "St9t4nwHuXXVlmjDqfn_Z", - "originalText": "1. Step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 475, - "versionNonce": 1284370805, - "isDeleted": false, - "id": "XVGBz_X5yN6xjWTosVH2n", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 487.04837438376217, - "y": 779.4318098510787, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 1666134389, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "-xogFSFcP-Vv5cuOSFm8T" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 476, - "versionNonce": 1092221653, - "isDeleted": false, - "id": "-xogFSFcP-Vv5cuOSFm8T", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 578.8589212587622, - "y": 784.4318098510787, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 63.37890625, - "height": 23, - "seed": 1840462549, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "2. Step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "XVGBz_X5yN6xjWTosVH2n", - "originalText": "2. Step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "text", - "version": 125, - "versionNonce": 1310578741, - "isDeleted": false, - "id": "N1a9yL7Pts16hUKY9-vhw", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 424.78852030984035, - "y": 646.2446482189896, - "strokeColor": "#be4bdb", - "backgroundColor": "#a5d8ff", - "width": 133.857421875, - "height": 23, - "seed": 361699381, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Workflow \"test\"", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "Workflow \"test\"", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "arrow", - "version": 184, - "versionNonce": 2127603131, - "isDeleted": false, - "id": "O-YmtRLb8uFNqCAz22EoG", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 737.454940151797, - "y": 535.9141784615474, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 190.41665096887027, - "height": 112.96427727851824, - "seed": 80234901, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": null, - "endBinding": { - "elementId": "0TjxOfERekC91N3yciQIq", - "focus": -0.8392895251910331, - "gap": 2.0300115262207328 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 190.41665096887027, - 112.96427727851824 - ] - ] - }, - { - "type": "arrow", - "version": 327, - "versionNonce": 780710651, - "isDeleted": false, - "id": "379hO6Dc5rygB38JgDbVo", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 738.8084877231549, - "y": 591.3526691276127, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 186.8066399682357, - "height": 57.68023784868956, - "seed": 211046133, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": { - "elementId": "2WwuMWX7YawqK0i1rDPJo", - "focus": -0.5776522830934517, - "gap": 2.1657966147995467 - }, - "endBinding": { - "elementId": "0TjxOfERekC91N3yciQIq", - "focus": -0.7269489945238884, - "gap": 4.286474955497397 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 186.8066399682357, - 57.68023784868956 - ] - ] - }, - { - "type": "text", - "version": 285, - "versionNonce": 1165977685, - "isDeleted": false, - "id": "0TjxOfERekC91N3yciQIq", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 929.901602646888, - "y": 632.4760859429873, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 518.076171875, - "height": 46, - "seed": 997763157, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "O-YmtRLb8uFNqCAz22EoG", - "type": "arrow" - }, - { - "id": "379hO6Dc5rygB38JgDbVo", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Additional steps are used to execute commands or plugins\nlike `make install` or release-to-github", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "Additional steps are used to execute commands or plugins\nlike `make install` or release-to-github", - "lineHeight": 1.15, - "baseline": 41 - } - ], - "appState": { - "gridSize": null, - "viewBackgroundColor": "#ffffff" - }, - "files": {} -} diff --git a/docs/versioned_docs/version-2.1/20-usage/15-terminiology/pipeline-workflow-step.svg b/docs/versioned_docs/version-2.1/20-usage/15-terminiology/pipeline-workflow-step.svg deleted file mode 100644 index 4ea3aab0ac..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/15-terminiology/pipeline-workflow-step.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - - - - - PipelineClone step1. Step2. StepA pipeline is triggered by an eventlike a push, tag, manualEvery pipeline consists of multiple workflows.Each defined by a separate YAML file and is named after the filename.Each workflow has its own workspace (folder) which isused by all steps of that workflow.The default first step of each workflow is the clone step.Its fetches the specific code version for a pipeline.Workflow "build"Clone step1. Step2. StepWorkflow "test"Additional steps are used to execute commands or pluginslike `make install` or release-to-github diff --git a/docs/versioned_docs/version-2.1/20-usage/20-workflow-syntax.md b/docs/versioned_docs/version-2.1/20-usage/20-workflow-syntax.md deleted file mode 100644 index 9efee6fbf2..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/20-workflow-syntax.md +++ /dev/null @@ -1,869 +0,0 @@ -# Workflow syntax - -The workflow section defines a list of steps to build, test and deploy your code. Steps are executed serially, in the order in which they are defined. If a step returns a non-zero exit code, the workflow and therefore all other workflows and the pipeline immediately aborts and returns a failure status. - -Example steps: - -```yaml -steps: - backend: - image: golang - commands: - - go build - - go test - frontend: - image: node - commands: - - npm install - - npm run test - - npm run build -``` - -In the above example we define two steps, `frontend` and `backend`. The names of these steps are completely arbitrary. - -Another way to name a step is by using the name keyword: - -```yaml -steps: - - name: backend - image: golang - commands: - - go build - - go test - - name: frontend - image: node - commands: - - npm install - - npm run test - - npm run build -``` - -Keep in mind the name is optional, if not added the steps will be numerated. - -## Skip Commits - -Woodpecker gives the ability to skip individual commits by adding `[SKIP CI]` or `[CI SKIP]` to the commit message. Note this is case-insensitive. - -```bash -git commit -m "updated README [CI SKIP]" -``` - -## Steps - -Every step of your workflow executes commands inside a specified container. The defined commands are executed serially. -The associated commit is checked out with git to a workspace which is mounted to every step of the workflow as the working directory. - -```diff - steps: - backend: - image: golang - commands: -+ - go build -+ - go test -``` - -### File changes are incremental - -- Woodpecker clones the source code in the beginning of the workflow -- Changes to files are persisted through steps as the same volume is mounted to all steps - -```yaml title=".woodpecker.yml" -steps: - build: - image: debian - commands: - - echo "test content" > myfile - a-test-step: - image: debian - commands: - - cat myfile -``` - -### `image` - -Woodpecker pulls the defined image and uses it as environment to execute the workflow step commands, for plugins and for service containers. - -When using the `local` backend, the `image` entry is used to specify the shell, such as Bash or Fish, that is used to run the commands. - -```diff - steps: - build: -+ image: golang:1.6 - commands: - - go build - - go test - - publish: -+ image: plugins/docker - repo: foo/bar - - services: - database: -+ image: mysql -``` - -Woodpecker supports any valid Docker image from any Docker registry: - -```text -image: golang -image: golang:1.7 -image: library/golang:1.7 -image: index.docker.io/library/golang -image: index.docker.io/library/golang:1.7 -``` - -Woodpecker does not automatically upgrade container images. Example configuration to always pull the latest image when updates are available: - -```diff - steps: - build: - image: golang:latest -+ pull: true -``` - -Learn more how you can use images from [different registries](./41-registries.md). - -### `commands` - -Commands of every step are executed serially as if you would enter them into your local shell. - -```diff - steps: - backend: - image: golang - commands: -+ - go build -+ - go test -``` - -There is no magic here. The above commands are converted to a simple shell script. The commands in the above example are roughly converted to the below script: - -```bash -#!/bin/sh -set -e - -go build -go test -``` - -The above shell script is then executed as the container entrypoint. The below docker command is an (incomplete) example of how the script is executed: - -```bash -docker run --entrypoint=build.sh golang -``` - -> Please note that only build steps can define commands. You cannot use commands with plugins or services. - -### `environment` - -Woodpecker provides the ability to pass environment variables to individual steps. - -For more details check the [environment docs](./50-environment.md). - -### `secrets` - -Woodpecker provides the ability to store named parameters external to the YAML configuration file, in a central secret store. These secrets can be passed to individual steps of the workflow at runtime. - -For more details check the [secrets docs](./40-secrets.md). - -### `failure` - -Some of the steps may be allowed to fail without causing the whole workflow and therefore pipeline to report a failure (e.g., a step executing a linting check). To enable this, add `failure: ignore` to your step. If Woodpecker encounters an error while executing the step, it will report it as failed but still executes the next steps of the workflow, if any, without affecting the status of the workflow. - -```diff - steps: - backend: - image: golang - commands: - - go build - - go test -+ failure: ignore -``` - -### `when` - Conditional Execution - -Woodpecker supports defining a list of conditions for a step by using a `when` block. If at least one of the conditions in the `when` block evaluate to true the step is executed, otherwise it is skipped. A condition can be a check like: - -```diff - steps: - slack: - image: plugins/slack - settings: - channel: dev -+ when: -+ - event: pull_request -+ repo: test/test -+ - event: push -+ branch: main -``` - -#### `repo` - -Example conditional execution by repository: - -```diff - steps: - slack: - image: plugins/slack - settings: - channel: dev -+ when: -+ - repo: test/test -``` - -#### `branch` - -:::note -Branch conditions are not applied to tags. -::: - -Example conditional execution by branch: - -```diff -steps: - slack: - image: plugins/slack - settings: - channel: dev -+ when: -+ - branch: main -``` - -> The step now triggers on main branch, but also if the target branch of a pull request is `main`. Add an event condition to limit it further to pushes on main only. - -Execute a step if the branch is `main` or `develop`: - -```yaml -when: - - branch: [main, develop] -``` - -Execute a step if the branch starts with `prefix/*`: - -```yaml -when: - - branch: prefix/* -``` - -The branch matching is done using [doublestar](https://github.com/bmatcuk/doublestar/#usage), note that a pattern starting with `*` should be put between quotes and a literal `/` needs to be escaped. A few examples: - -- `*\\/*` to match patterns with exactly 1 `/` -- `*\\/**` to match patters with at least 1 `/` -- `*` to match patterns without `/` -- `**` to match everything - -Execute a step using custom include and exclude logic: - -```yaml -when: - - branch: - include: [main, release/*] - exclude: [release/1.0.0, release/1.1.*] -``` - -#### `event` - -Available events: `push`, `pull_request`, `pull_request_closed`, `tag`, `deployment`, `cron`, `manual` - -Execute a step if the build event is a `tag`: - -```yaml -when: - - event: tag -``` - -Execute a step if the pipeline event is a `push` to a specified branch: - -```diff -when: - - event: push -+ branch: main -``` - -Execute a step for multiple events: - -```yaml -when: - - event: [push, tag, deployment] -``` - -#### `cron` - -This filter **only** applies to cron events and filters based on the name of a cron job. - -Make sure to have a `event: cron` condition in the `when`-filters as well. - -```yaml -when: - - event: cron - cron: sync_* # name of your cron job -``` - -[Read more about cron](./45-cron.md) - -#### `ref` - -The `ref` filter compares the git reference against which the workflow is executed. -This allows you to filter, for example, tags that must start with **v**: - -```yaml -when: - - event: tag - ref: refs/tags/v* -``` - -#### `status` - -There are use cases for executing steps on failure, such as sending notifications for failed workflow / pipeline. Use the status constraint to execute steps even when the workflow fails: - -```diff -steps: - slack: - image: plugins/slack - settings: - channel: dev -+ when: -+ - status: [ success, failure ] -``` - -#### `platform` - -:::note -This condition should be used in conjunction with a [matrix](./30-matrix-workflows.md#example-matrix-pipeline-using-multiple-platforms) workflow as a regular workflow will only be executed by a single agent which only has one arch. -::: - -Execute a step for a specific platform: - -```yaml -when: - - platform: linux/amd64 -``` - -Execute a step for a specific platform using wildcards: - -```yaml -when: - - platform: [linux/*, windows/amd64] -``` - -#### `environment` - -Execute a step for deployment events matching the target deployment environment: - -```yaml -when: - - environment: production - - event: deployment -``` - -#### `matrix` - -Execute a step for a single matrix permutation: - -```yaml -when: - - matrix: - GO_VERSION: 1.5 - REDIS_VERSION: 2.8 -``` - -#### `instance` - -Execute a step only on a certain Woodpecker instance matching the specified hostname: - -```yaml -when: - - instance: stage.woodpecker.company.com -``` - -#### `path` - -:::info -Path conditions are applied only to **push** and **pull_request** events. -It is currently **only available** for GitHub, GitLab and Gitea (version 1.18.0 and newer) -::: - -Execute a step only on a pipeline with certain files being changed: - -```yaml -when: - - path: 'src/*' -``` - -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`. - -```yaml -when: - - path: - include: ['.woodpecker/*.yml', '*.ini'] - exclude: ['*.md', 'docs/**'] - ignore_message: '[ALL]' -``` - -**Hint:** Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions. - -#### `evaluate` - -Execute a step only if the provided evaluate expression is equal to true. Both built-in [`CI_`](./50-environment.md#built-in-environment-variables) and custom variables can be used inside the expression. - -The expression syntax can be found in [the docs](https://github.com/expr-lang/expr/blob/master/docs/Language-Definition.md) of the underlying library. - -Run on pushes to the default branch for the repository `owner/repo`: - -```yaml -when: - - evaluate: 'CI_PIPELINE_EVENT == "push" && CI_REPO == "owner/repo" && CI_COMMIT_BRANCH == CI_REPO_DEFAULT_BRANCH' -``` - -Run on commits created by user `woodpecker-ci`: - -```yaml -when: - - evaluate: 'CI_COMMIT_AUTHOR == "woodpecker-ci"' -``` - -Skip all commits containing `please ignore me` in the commit message: - -```yaml -when: - - evaluate: 'not (CI_COMMIT_MESSAGE contains "please ignore me")' -``` - -Run on pull requests with the label `deploy`: - -```yaml -when: - - evaluate: 'CI_COMMIT_PULL_REQUEST_LABELS contains "deploy"' -``` - -Skip step only if `SKIP=true`, run otherwise or if undefined: - -```yaml -when: - - evaluate: 'SKIP != "true"' -``` - -### `depends_on` - -Normally steps of a workflow are executed serially in the order in which they are defined. As soon as you set `depends_on` for a step a [directed acyclic graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) will be used and all steps of the workflow will be executed in parallel besides the steps that have a dependency set to another step using `depends_on`: - -```diff - steps: - build: # build will be executed immediately - image: golang - commands: - - go build - - deploy: - image: plugins/docker - settings: - repo: foo/bar -+ depends_on: [build, test] # deploy will be executed after build and test finished - - test: # test will be executed immediately as no dependencies are set - image: golang - commands: - - go test -``` - -### `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. - -For more details check the [volumes docs](./70-volumes.md). - -### `detach` - -Woodpecker gives the ability to detach steps to run them in background until the workflow finishes. - -For more details check the [service docs](./60-services.md#detachment). - -### `directory` - -Using `directory`, you can set a subdirectory of your repository or an absolute path inside the Docker container in which your commands will run. - -## `services` - -Woodpecker can provide service containers. They can for example be used to run databases or cache containers during the execution of workflow. - -For more details check the [services docs](./60-services.md). - -## `workspace` - -The workspace defines the shared volume and working directory shared by all workflow steps. The default workspace matches the below pattern, based on your repository URL. - -```txt -/woodpecker/src/github.com/octocat/hello-world -``` - -The workspace can be customized using the workspace block in the YAML file: - -```diff -+workspace: -+ base: /go -+ path: src/github.com/octocat/hello-world - - steps: - build: - image: golang:latest - commands: - - go get - - go test -``` - -The base attribute defines a shared base volume available to all steps. This ensures your source code, dependencies and compiled binaries are persisted and shared between steps. - -```diff - workspace: -+ base: /go - path: src/github.com/octocat/hello-world - - steps: - deps: - image: golang:latest - commands: - - go get - - go test - build: - image: node:latest - commands: - - go build -``` - -This would be equivalent to the following docker commands: - -```bash -docker volume create my-named-volume - -docker run --volume=my-named-volume:/go golang:latest -docker run --volume=my-named-volume:/go node:latest -``` - -The path attribute defines the working directory of your build. This is where your code is cloned and will be the default working directory of every step in your build process. The path must be relative and is combined with your base path. - -```diff - workspace: - base: /go -+ path: src/github.com/octocat/hello-world -``` - -```text -git clone https://github.com/octocat/hello-world \ - /go/src/github.com/octocat/hello-world -``` - -## `matrix` - -Woodpecker has integrated support for matrix builds. Woodpecker executes a separate build task for each combination in the matrix, allowing you to build and test a single commit against multiple configurations. - -For more details check the [matrix build docs](./30-matrix-workflows.md). - -## `labels` - -You can set labels for your workflow to select an agent to execute the workflow on. An agent will pick up and run a workflow when **every** label assigned to it matches the agents labels. - -To set additional agent labels check the [agent configuration options](../30-administration/15-agent-config.md#woodpecker_filter_labels). Agents will have at least four default labels: `platform=agent-os/agent-arch`, `hostname=my-agent`, `backend=docker` (type of the agent backend) and `repo=*`. Agents can use a `*` as a wildcard for a label. For example `repo=*` will match every repo. - -Workflow labels with an empty value will be ignored. -By default each workflow has at least the `repo=your-user/your-repo-name` label. If you have set the [platform attribute](#platform) for your workflow it will have a label like `platform=your-os/your-arch` as well. - -You can add additional labels as a key value map: - -```diff -+labels: -+ location: europe # only agents with `location=europe` or `location=*` will be used -+ weather: sun -+ hostname: "" # this label will be ignored as it is empty - -steps: - build: - image: golang - commands: - - go build - - go test -``` - -### Filter by platform - -To configure your workflow to only be executed on an agent with a specific platform, you can use the `platform` key. -Have a look at the official [go docs](https://go.dev/doc/install/source) for the available platforms. The syntax of the platform is `GOOS/GOARCH` like `linux/arm64` or `linux/amd64`. - -Example: - -Assuming we have two agents, one `linux/arm` and one `linux/amd64`. Previously this workflow would have executed on **either agent**, as Woodpecker is not fussy about where it runs the workflows. By setting the following option it will only be executed on an agent with the platform `linux/arm64`. - -```diff -+labels: -+ platform: linux/arm64 - -steps: - [...] -``` - -## `variables` - -Woodpecker supports using [YAML anchors & aliases](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) as variables in the workflow configuration. - -For more details and examples check the [Advanced usage docs](./90-advanced-usage.md) - -## `clone` - -Woodpecker automatically configures a default clone step if not explicitly defined. When using the `local` backend, the [plugin-git](https://github.com/woodpecker-ci/plugin-git) binary must be on your `$PATH` for the default clone step to work. If not, you can still write a manual clone step. - -You can manually configure the clone step in your workflow for customization: - -```diff -+clone: -+ git: -+ image: woodpeckerci/plugin-git - - steps: - build: - image: golang - commands: - - go build - - go test -``` - -Example configuration to override depth: - -```diff - clone: - git: - image: woodpeckerci/plugin-git -+ settings: -+ partial: false -+ depth: 50 -``` - -Example configuration to use a custom clone plugin: - -```diff -clone: - git: -+ image: octocat/custom-git-plugin -``` - -Example configuration to clone Mercurial repository: - -```diff - clone: - hg: -+ image: plugins/hg -+ settings: -+ path: bitbucket.org/foo/bar -``` - -### Git Submodules - -To use the credentials that cloned the repository to clone it's submodules, update `.gitmodules` to use `https` instead of `git`: - -```diff - [submodule "my-module"] - path = my-module --url = git@github.com:octocat/my-module.git -+url = https://github.com/octocat/my-module.git -``` - -To use the ssh git url in `.gitmodules` for users cloning with ssh, and also use the https url in Woodpecker, add `submodule_override`: - -```diff - clone: - git: - image: woodpeckerci/plugin-git - settings: - recursive: true -+ submodule_override: -+ my-module: https://github.com/octocat/my-module.git - -steps: - ... -``` - -## `skip_clone` - -By default Woodpecker is automatically adding a clone step. This clone step can be configured by the [clone](#clone) property. If you do not need a `clone` step at all you can skip it using: - -```yaml -skip_clone: true -``` - -## `when` - Global workflow conditions - -Woodpecker gives the ability to skip whole workflows (not just steps #when---conditional-execution-1) based on certain conditions by a `when` block. If all conditions in the `when` block evaluate to true the workflow is executed, otherwise it is skipped, but treated as successful and other workflows depending on it will still continue. - -### `repo` - -Example conditional execution by repository: - -```diff -+when: -+ repo: test/test -+ - steps: - slack: - image: plugins/slack - settings: - channel: dev -``` - -### `branch` - -:::note -Branch conditions are not applied to tags. -::: - -Example conditional execution by branch: - -```diff -+when: -+ branch: main -+ - steps: - slack: - image: plugins/slack - settings: - channel: dev -``` - -> The step now triggers on main, but also if the target branch of a pull request is `main`. Add an event condition to limit it further to pushes on main only. - -Execute a step if the branch is `main` or `develop`: - -```diff -when: - branch: [main, develop] -``` - -Execute a step if the branch starts with `prefix/*`: - -```diff -when: - branch: prefix/* -``` - -Execute a step using custom include and exclude logic: - -```diff -when: - branch: - include: [ main, release/* ] - exclude: [ release/1.0.0, release/1.1.* ] -``` - -### `event` - -Execute a step if the build event is a `tag`: - -```diff -when: - event: tag -``` - -Execute a step if the pipeline event is a `push` to a specified branch: - -```diff -when: - event: push -+ branch: main -``` - -Execute a step for all non-pull request events: - -```diff -when: - event: [push, tag, deployment] -``` - -Execute a step for all build events: - -```diff -when: - event: [push, pull_request, tag, deployment] -``` - -### `ref` - -The `ref` filter compares the git reference against which the pipeline is executed. -This allows you to filter, for example, tags that must start with **v**: - -```yaml -when: - event: tag - ref: refs/tags/v* -``` - -### `environment` - -Execute a step for deployment events matching the target deployment environment: - -```diff -when: - environment: production - event: deployment -``` - -### `instance` - -Execute a step only on a certain Woodpecker instance matching the specified hostname: - -```diff -when: - instance: stage.woodpecker.company.com -``` - -### `path` - -:::info -Path conditions are applied only to **push** and **pull_request** events. -It is currently **only available** for GitHub, GitLab and Gitea (version 1.18.0 and newer) -::: - -Execute a step only on a pipeline with certain files being changed: - -```diff -when: - path: "src/*" -``` - -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`. - -```diff -when: - path: - include: [ '.woodpecker/*.yml', '*.ini' ] - exclude: [ '*.md', 'docs/**' ] - ignore_message: "[ALL]" -``` - -**Hint:** Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions. - -## `depends_on` - -Woodpecker supports to define multiple workflows for a repository. Those workflows will run independent from each other. To depend them on each other you can use the [`depends_on`](./25-workflows.md#flow-control) keyword. - -## `runs_on` - -Workflows that should run even on failure should set the `runs_on` tag. See [here](./25-workflows.md#flow-control) for an example. - -## Privileged mode - -Woodpecker gives the ability to configure privileged mode in the YAML. You can use this parameter to launch containers with escalated capabilities. - -> Privileged mode is only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./71-project-settings.md#trusted) to enable trusted mode. - -```diff - steps: - build: - image: docker - environment: - - DOCKER_HOST=tcp://docker:2375 - commands: - - docker --tls=false ps - - services: - docker: - image: docker:dind - commands: dockerd-entrypoint.sh --storage-driver=vfs --tls=false -+ privileged: true -``` diff --git a/docs/versioned_docs/version-2.1/20-usage/25-workflows.md b/docs/versioned_docs/version-2.1/20-usage/25-workflows.md deleted file mode 100644 index 76d33f429e..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/25-workflows.md +++ /dev/null @@ -1,122 +0,0 @@ -# Workflows - -:::info -This Feature is only available for GitHub, Gitea & GitLab repositories. Follow [this](https://github.com/woodpecker-ci/woodpecker/issues/1138) issue to support further development. -::: - -A pipeline has at least one workflow. A workflow is a set of steps that are executed in sequence using the same workspace which is a shared folder containing the repository and all the generated data from previous steps. - -Incase there is a single configuration in `.woodpecker.yml` Woodpecker will create a pipeline with a single workflow. - -By placing the configurations in a folder which is by default named `.woodpecker/` Woodpecker will create a pipeline with multiple workflows each named by the file they are defined in. Only `.yml` and `.yaml` files will be used and files in any subfolders like `.woodpecker/sub-folder/test.yml` will be ignored. - -You can also set some custom path like `.my-ci/pipelines/` instead of `.woodpecker/` in the [project settings](./71-project-settings.md). - -## Benefits of using workflows - -- faster lint/test feedback, the workflow doesn't have to run fully to have a lint status pushed to the remote -- better organization of a pipeline along various concerns using one workflow for: testing, linting, building and deploying -- utilizing more agents to speed up the execution of the whole pipeline - -## Example workflow definition - -:::warning -Please note that files are only shared between steps of the same workflow (see [File changes are incremental](./20-workflow-syntax.md#file-changes-are-incremental)). That means you cannot access artifacts e.g. from the `build` workflow in the `deploy` workflow. -If you still need to pass artifacts between the workflows you need use some storage [plugin](./51-plugins/10-plugins.md) (e.g. one which stores files in an Amazon S3 bucket). -::: - -```bash -.woodpecker/ -├── .build.yml -├── .deploy.yml -├── .lint.yml -└── .test.yml -``` - -```yaml title=".woodpecker/.build.yml" -steps: - build: - image: debian:stable-slim - commands: - - echo building - - sleep 5 -``` - -```yaml title=".woodpecker/.deploy.yml" -steps: - deploy: - image: debian:stable-slim - commands: - - echo deploying - -depends_on: - - lint - - build - - test -``` - -```yaml title=".woodpecker/.test.yml" -steps: - test: - image: debian:stable-slim - commands: - - echo testing - - sleep 5 - -depends_on: - - build -``` - -```yaml title=".woodpecker/.lint.yml" -steps: - lint: - image: debian:stable-slim - commands: - - echo linting - - sleep 5 -``` - -## Status lines - -Each workflow will report its own status back to your forge. - -## Flow control - -The workflows run in parallel on separate agents and share nothing. - -Dependencies between workflows can be set with the `depends_on` element. A workflow doesn't execute until all of its dependencies finished successfully. - -The name for a `depends_on` entry is the filename without the path, leading dots and without the file extension `.yml` or `.yaml`. If the project config for example uses `.woodpecker/` as path for CI files with a file named `.woodpecker/.lint.yml` the corresponding `depends_on` entry would be `lint`. - -```diff -steps: - deploy: - image: debian:stable-slim - commands: - - echo deploying - -+depends_on: -+ - lint -+ - build -+ - test -``` - -Workflows that need to run even on failures should set the `runs_on` tag. - -```diff -steps: - notify: - image: debian:stable-slim - commands: - - echo notifying - -depends_on: - - deploy - -+runs_on: [ success, failure ] -``` - -:::info -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) -::: diff --git a/docs/versioned_docs/version-2.1/20-usage/30-matrix-workflows.md b/docs/versioned_docs/version-2.1/20-usage/30-matrix-workflows.md deleted file mode 100644 index 1abe0bcc58..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/30-matrix-workflows.md +++ /dev/null @@ -1,143 +0,0 @@ -# Matrix workflows - -Woodpecker has integrated support for matrix workflows. Woodpecker executes a separate workflow for each combination in the matrix, allowing you to build and test against multiple configurations. - -Example matrix definition: - -```yaml -matrix: - GO_VERSION: - - 1.4 - - 1.3 - REDIS_VERSION: - - 2.6 - - 2.8 - - 3.0 -``` - -Example matrix definition containing only specific combinations: - -```yaml -matrix: - include: - - GO_VERSION: 1.4 - REDIS_VERSION: 2.8 - - GO_VERSION: 1.5 - REDIS_VERSION: 2.8 - - GO_VERSION: 1.6 - REDIS_VERSION: 3.0 -``` - -## Interpolation - -Matrix variables are interpolated in the YAML using the `${VARIABLE}` syntax, before the YAML is parsed. This is an example YAML file before interpolating matrix parameters: - -```yaml -matrix: - GO_VERSION: - - 1.4 - - 1.3 - DATABASE: - - mysql:8 - - mysql:5 - - mariadb:10.1 - -steps: - build: - image: golang:${GO_VERSION} - commands: - - go get - - go build - - go test - -services: - database: - image: ${DATABASE} -``` - -Example YAML file after injecting the matrix parameters: - -```diff -steps: - build: -- image: golang:${GO_VERSION} -+ image: golang:1.4 - commands: - - go get - - go build - - go test -+ environment: -+ - GO_VERSION=1.4 -+ - DATABASE=mysql:8 - -services: - database: -- image: ${DATABASE} -+ image: mysql:8 -``` - -## Examples - -### Example matrix pipeline based on Docker image tag - -```yaml -matrix: - TAG: - - 1.7 - - 1.8 - - latest - -steps: - build: - image: golang:${TAG} - commands: - - go build - - go test -``` - -### Example matrix pipeline based on container image - -```yaml -matrix: - IMAGE: - - golang:1.7 - - golang:1.8 - - golang:latest - -steps: - build: - image: ${IMAGE} - commands: - - go build - - go test -``` - -### Example matrix pipeline using multiple platforms - -```yaml -matrix: - platform: - - linux/amd64 - - linux/arm64 - -labels: - platform: ${platform} - -steps: - test: - image: alpine - commands: - - echo "I am running on ${platform}" - - test-arm-only: - image: alpine - commands: - - echo "I am running on ${platform}" - - echo "Arm is cool!" - when: - platform: linux/arm* -``` - -:::note -If you want to control the architecture of a pipeline on a Kubernetes runner, see [the nodeSelector documentation of the Kubernetes backend](../30-administration/22-backends/40-kubernetes.md#nodeselector). -::: diff --git a/docs/versioned_docs/version-2.1/20-usage/40-secrets.md b/docs/versioned_docs/version-2.1/20-usage/40-secrets.md deleted file mode 100644 index 4f2a3ae54b..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/40-secrets.md +++ /dev/null @@ -1,142 +0,0 @@ -# Secrets - -Woodpecker provides the ability to store named parameters external to the YAML configuration file, in a central secret store. These secrets can be passed to individual steps of the pipeline at runtime. - -Woodpecker provides three different levels to add secrets to your pipeline. The following list shows the priority of the different levels. If a secret is defined in multiple levels, will be used following this priorities: Repository secrets > Organization secrets > Global secrets. - -1. **Repository secrets**: They are available to all pipelines of an repository. -2. **Organization secrets**: They are available to all pipelines of an organization. -3. **Global secrets**: Can be configured by an instance admin. - They are available to all pipelines of the **whole** Woodpecker instance and should therefore **only** be used for secrets that are allowed to be read by **all** users. - -## Usage - -### Use secrets in commands - -Secrets are exposed to your pipeline steps and plugins as uppercase environment variables and can therefore be referenced in the commands section of your pipeline, -once their usage is declared in the `secrets` section: - -```diff -steps: - docker: - image: docker - commands: -+ - echo $DOCKER_USERNAME -+ - echo $DOCKER_PASSWORD -+ secrets: [ docker_username, docker_password ] -``` - -### Use secrets in settings - -Alternatively, you can get a `setting` from secrets using the `from_secret` syntax. -In this example, the secret named `secret_token` would be passed to the setting named `token`, which will be available in the plugin as environment variable named `PLUGIN_TOKEN`. See [Plugins](./plugins/sample-plugin#write-the-logic) for details. - -**NOTE:** the `from_secret` syntax only works with the newer `settings` block. - -```diff -steps: - docker: - image: my-plugin - settings: -+ token: -+ from_secret: secret_token -``` - -### Note about parameter pre-processing - -Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped. - -```diff -steps: - docker: - image: docker - commands: -- - echo ${DOCKER_USERNAME} -- - echo ${DOCKER_PASSWORD} -+ - echo $${DOCKER_USERNAME} -+ - echo $${DOCKER_PASSWORD} - secrets: [ docker_username, docker_password ] -``` - -### Alternate Names - -There may be scenarios where you are required to store secrets using alternate names. You can map the alternate secret name to the expected name using the below syntax: - -```diff -steps: - docker: - image: plugins/docker - repo: octocat/hello-world - tags: latest -+ secrets: -+ - source: docker_prod_password -+ target: docker_password -``` - -### Use in Pull Requests events - -Secrets are not exposed to pull requests by default. You can override this behavior by creating the secret and enabling the `pull_request` event type, either in UI or by CLI, see below. - -**NOTE:** Please be careful when exposing secrets to pull requests. If your repository is open source and accepts pull requests your secrets are not safe. A bad actor can submit a malicious pull request that exposes your secrets. - -## Image filter - -To prevent abusing your secrets from malicious usage, you can limit a secret to a list of images. If enabled they are not available to any other plugin (steps without user-defined commands). If you or an attacker defines explicit commands, the secrets will not be available to the container to prevent leaking them. - -## Adding Secrets - -Secrets are added to the Woodpecker in the UI or with the CLI. - -### CLI Examples - -Create the secret using default settings. The secret will be available to all images in your pipeline, and will be available to all push, tag, and deployment events (not pull request events). - -```diff -woodpecker-cli secret add \ - -repository octocat/hello-world \ - -name aws_access_key_id \ - -value -``` - -Create the secret and limit to a single image: - -```diff -woodpecker-cli secret add \ - -repository octocat/hello-world \ -+ -image plugins/s3 \ - -name aws_access_key_id \ - -value -``` - -Create the secrets and limit to a set of images: - -```diff -woodpecker-cli secret add \ - -repository octocat/hello-world \ -+ -image plugins/s3 \ -+ -image peloton/woodpecker-ecs \ - -name aws_access_key_id \ - -value -``` - -Create the secret and enable for multiple hook events: - -```diff -woodpecker-cli secret add \ - -repository octocat/hello-world \ - -image plugins/s3 \ -+ -event pull_request \ -+ -event push \ -+ -event tag \ - -name aws_access_key_id \ - -value -``` - -Loading secrets from file using curl `@` syntax. This is the recommended approach for loading secrets from file to preserve newlines: - -```diff -woodpecker-cli secret add \ - -repository octocat/hello-world \ - -name ssh_key \ -+ -value @/root/ssh/id_rsa -``` diff --git a/docs/versioned_docs/version-2.1/20-usage/41-registries.md b/docs/versioned_docs/version-2.1/20-usage/41-registries.md deleted file mode 100644 index f0a69d6b66..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/41-registries.md +++ /dev/null @@ -1,69 +0,0 @@ -# Registries - -Woodpecker provides the ability to add container registries in the settings of your repository. Adding a registry allows you to authenticate and pull private images from a container registry when using these images as a step inside your pipeline. Using registry credentials can also help you avoid rate limiting when pulling images from public registries. - -## Images from private registries - -You must provide registry credentials in the UI in order to pull private container images defined in your YAML configuration file. - -These credentials are never exposed to your steps, which means they cannot be used to push, and are safe to use with pull requests, for example. Pushing to a registry still requires setting credentials for the appropriate plugin. - -Example configuration using a private image: - -```diff - steps: - build: -+ image: gcr.io/custom/golang - commands: - - go build - - go test -``` - -Woodpecker matches the registry hostname to each image in your YAML. If the hostnames match, the registry credentials are used to authenticate to your registry and pull the image. Note that registry credentials are used by the Woodpecker agent and are never exposed to your build containers. - -Example registry hostnames: - -- Image `gcr.io/foo/bar` has hostname `gcr.io` -- Image `foo/bar` has hostname `docker.io` -- Image `qux.com:8000/foo/bar` has hostname `qux.com:8000` - -Example registry hostname matching logic: - -- Hostname `gcr.io` matches image `gcr.io/foo/bar` -- Hostname `docker.io` matches `golang` -- Hostname `docker.io` matches `library/golang` -- Hostname `docker.io` matches `bradyrydzewski/golang` -- Hostname `docker.io` matches `bradyrydzewski/golang:latest` - -## Global registry support - -To make a private registry globally available, check the [server configuration docs](../30-administration/10-server-config.md#global-registry-setting). - -## GCR registry support - -For specific details on configuring access to Google Container Registry, please view the docs [here](https://cloud.google.com/container-registry/docs/advanced-authentication#using_a_json_key_file). - -## Local Images - -:::warning -For this, privileged rights are needed only available to admins. In addition, this only works when using a single agent. -::: - -It's possible to build a local image by mounting the docker socket as a volume. - -With a `Dockerfile` at the root of the project: - -```diff -steps: - build-image: - image: docker - commands: - - docker build --rm -t local/project-image . - volumes: - - /var/run/docker.sock:/var/run/docker.sock - - build-project: - image: local/project-image - commands: - - ./build.sh -``` diff --git a/docs/versioned_docs/version-2.1/20-usage/45-cron.md b/docs/versioned_docs/version-2.1/20-usage/45-cron.md deleted file mode 100644 index f90c77c1ad..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/45-cron.md +++ /dev/null @@ -1,34 +0,0 @@ -# Cron - -To configure cron jobs you need at least push access to the repository. - -## Add a new cron job - -1. To create a new cron job adjust your pipeline config(s) and add the event filter to all steps you would like to run by the cron job: - - ```diff - steps: - sync_locales: - image: weblate_sync - settings: - url: example.com - token: - from_secret: weblate_token - + when: - + event: cron - + cron: "name of the cron job" # if you only want to execute this step by a specific cron job - ``` - -1. Create a new cron job in the repository settings: - - ![cron settings](./cron-settings.png) - - The supported schedule syntax can be found at . If you need general understanding of the cron syntax is a good place to start and experiment. - - Examples: `@every 5m`, `@daily`, `0 30 * * * *` ... - - :::info - Woodpeckers cron syntax starts with seconds instead of minutes as used by most linux cron schedulers. - - Example: "At minute 30 every hour" would be `0 30 * * * *` instead of `30 * * * *` - ::: diff --git a/docs/versioned_docs/version-2.1/20-usage/50-environment.md b/docs/versioned_docs/version-2.1/20-usage/50-environment.md deleted file mode 100644 index cf33527915..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/50-environment.md +++ /dev/null @@ -1,225 +0,0 @@ -# Environment variables - -Woodpecker provides the ability to pass environment variables to individual pipeline steps. Note that these can't overwrite any existing, built-in variables. Example pipeline step with custom environment variables: - -```diff -steps: - 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: - build: - image: golang -- environment: -- - PATH=$PATH:/go - commands: -+ - export PATH=$PATH:/go - - go build - - go test -``` - -> Please be warned that `${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: - 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 | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -| `CI` | CI environment name (value: `woodpecker`) | -| | **Repository** | -| `CI_REPO` | repository full name `/` | -| `CI_REPO_OWNER` | repository owner | -| `CI_REPO_NAME` | repository name | -| `CI_REPO_REMOTE_ID` | repository remote ID, is the UID it has in the forge | -| `CI_REPO_SCM` | repository SCM (git) | -| `CI_REPO_URL` | repository web URL | -| `CI_REPO_CLONE_URL` | repository clone URL | -| `CI_REPO_CLONE_SSH_URL` | repository SSH clone URL | -| `CI_REPO_DEFAULT_BRANCH` | repository default branch (main) | -| `CI_REPO_PRIVATE` | repository is private | -| `CI_REPO_TRUSTED` | repository is trusted | -| | **Current Commit** | -| `CI_COMMIT_SHA` | commit SHA | -| `CI_COMMIT_REF` | commit ref | -| `CI_COMMIT_REFSPEC` | commit ref spec | -| `CI_COMMIT_BRANCH` | commit branch (equals target branch for pull requests) | -| `CI_COMMIT_SOURCE_BRANCH` | commit source branch (empty if event is not `pull_request` or `pull_request_closed`) | -| `CI_COMMIT_TARGET_BRANCH` | commit target branch (empty if event is not `pull_request` or `pull_request_closed`) | -| `CI_COMMIT_TAG` | commit tag name (empty if event is not `tag`) | -| `CI_COMMIT_PULL_REQUEST` | commit pull request number (empty if event is not `pull_request` or `pull_request_closed`) | -| `CI_COMMIT_PULL_REQUEST_LABELS` | labels assigned to pull request (empty if event is not `pull_request` or `pull_request_closed`) | -| `CI_COMMIT_MESSAGE` | commit message | -| `CI_COMMIT_AUTHOR` | commit author username | -| `CI_COMMIT_AUTHOR_EMAIL` | commit author email address | -| `CI_COMMIT_AUTHOR_AVATAR` | commit author avatar | -| | **Current pipeline** | -| `CI_PIPELINE_NUMBER` | pipeline number | -| `CI_PIPELINE_PARENT` | number of parent pipeline | -| `CI_PIPELINE_EVENT` | pipeline event (see [pipeline events](../20-usage/15-terminiology/index.md#pipeline-events)) | -| `CI_PIPELINE_URL` | link to the web UI for the pipeline | -| `CI_PIPELINE_FORGE_URL` | link to the forge's web UI for the commit(s) or tag that triggered the pipeline | -| `CI_PIPELINE_DEPLOY_TARGET` | pipeline deploy target for `deployment` events (i.e. production) | -| `CI_PIPELINE_STATUS` | pipeline status (success, failure) | -| `CI_PIPELINE_CREATED` | pipeline created UNIX timestamp | -| `CI_PIPELINE_STARTED` | pipeline started UNIX timestamp | -| `CI_PIPELINE_FINISHED` | pipeline finished UNIX timestamp | -| `CI_PIPELINE_FILES` | changed files (empty if event is not `push` or `pull_request`), it is undefined if more than 500 files are touched | -| | **Current workflow** | -| `CI_WORKFLOW_NAME` | workflow name | -| | **Current step** | -| `CI_STEP_NAME` | step name | -| `CI_STEP_NUMBER` | step number | -| `CI_STEP_STATUS` | step status (success, failure) | -| `CI_STEP_STARTED` | step started UNIX timestamp | -| `CI_STEP_FINISHED` | step finished UNIX timestamp | -| `CI_STEP_URL` | URL to step in UI | -| | **Previous commit** | -| `CI_PREV_COMMIT_SHA` | previous commit SHA | -| `CI_PREV_COMMIT_REF` | previous commit ref | -| `CI_PREV_COMMIT_REFSPEC` | previous commit ref spec | -| `CI_PREV_COMMIT_BRANCH` | previous commit branch | -| `CI_PREV_COMMIT_SOURCE_BRANCH` | previous commit source branch | -| `CI_PREV_COMMIT_TARGET_BRANCH` | previous commit target branch | -| `CI_PREV_COMMIT_URL` | previous commit link in forge | -| `CI_PREV_COMMIT_MESSAGE` | previous commit message | -| `CI_PREV_COMMIT_AUTHOR` | previous commit author username | -| `CI_PREV_COMMIT_AUTHOR_EMAIL` | previous commit author email address | -| `CI_PREV_COMMIT_AUTHOR_AVATAR` | previous commit author avatar | -| | **Previous pipeline** | -| `CI_PREV_PIPELINE_NUMBER` | previous pipeline number | -| `CI_PREV_PIPELINE_PARENT` | previous pipeline number of parent pipeline | -| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (see [pipeline events](../20-usage/15-terminiology/index.md#pipeline-events)) | -| `CI_PREV_PIPELINE_URL` | previous pipeline link in CI | -| `CI_PREV_PIPELINE_FORGE_URL` | previous pipeline link to event in forge | -| `CI_PREV_PIPELINE_DEPLOY_TARGET` | previous pipeline deploy target for `deployment` events (ie production) | -| `CI_PREV_PIPELINE_STATUS` | previous pipeline status (success, failure) | -| `CI_PREV_PIPELINE_CREATED` | previous pipeline created UNIX timestamp | -| `CI_PREV_PIPELINE_STARTED` | previous pipeline started UNIX timestamp | -| `CI_PREV_PIPELINE_FINISHED` | previous pipeline finished UNIX timestamp | -| |   | -| `CI_WORKSPACE` | Path of the workspace where source code gets cloned to | -| | **System** | -| `CI_SYSTEM_NAME` | name of the CI system: `woodpecker` | -| `CI_SYSTEM_URL` | link to CI system | -| `CI_SYSTEM_HOST` | hostname of CI server | -| `CI_SYSTEM_VERSION` | version of the server | -| | **Forge** | -| `CI_FORGE_TYPE` | name of forge (gitea, github, ...) | -| `CI_FORGE_URL` | root URL of configured forge | -| | **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. - -```diff -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2 -``` - -These can be used, for example, to manage the image tag used by multiple projects. - -```diff -steps: - build: -- image: golang:1.18 -+ image: golang:${GOLANG_VERSION} - commands: - - [...] - environment: - - [...] -+ - WOODPECKER_ENVIRONMENT=GOLANG_VERSION:1.18 -``` - -## 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: - docker: - image: plugins/docker - settings: -+ tags: ${CI_COMMIT_SHA} -``` - -Example tag substitution: - -```diff -steps: - docker: - image: plugins/docker - settings: -+ tags: ${CI_COMMIT_TAG} -``` - -## String Operations - -Woodpecker also emulates bash string operations. This gives us the ability to manipulate the strings prior to substitution. Example use cases might include substring and stripping prefix or suffix values. - -| OPERATION | DESCRIPTION | -| ------------------ | ------------------------------------------------ | -| `${param}` | parameter substitution | -| `${param,}` | parameter substitution with lowercase first char | -| `${param,,}` | parameter substitution with lowercase | -| `${param^}` | parameter substitution with uppercase first char | -| `${param^^}` | parameter substitution with uppercase | -| `${param:pos}` | parameter substitution with substring | -| `${param:pos:len}` | parameter substitution with substring and length | -| `${param=default}` | parameter substitution with default | -| `${param##prefix}` | parameter substitution with prefix removal | -| `${param%%suffix}` | parameter substitution with suffix removal | -| `${param/old/new}` | parameter substitution with find and replace | - -Example variable substitution with substring: - -```diff -steps: - docker: - image: plugins/docker - settings: -+ tags: ${CI_COMMIT_SHA:0:8} -``` - -Example variable substitution strips `v` prefix from `v.1.0.0`: - -```diff -steps: - docker: - image: plugins/docker - settings: -+ tags: ${CI_COMMIT_TAG##v} -``` diff --git a/docs/versioned_docs/version-2.1/20-usage/51-plugins/10-plugins.md b/docs/versioned_docs/version-2.1/20-usage/51-plugins/10-plugins.md deleted file mode 100644 index 48977c9a84..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/51-plugins/10-plugins.md +++ /dev/null @@ -1,49 +0,0 @@ -# Plugins - -Plugins are pipeline steps that perform pre-defined tasks and are configured as steps in your pipeline. Plugins can be used to deploy code, publish artifacts, send notification, and more. - -They are automatically pulled from the default container registry the agent's have configured. - -Example pipeline using the Docker and Slack plugins: - -```yaml -steps: - build: - image: golang - commands: - - go build - - go test - - publish: - image: plugins/docker - settings: - repo: foo/bar - tags: latest - - notify: - image: plugins/slack - settings: - channel: dev -``` - -## Plugin Isolation - -Plugins are just pipeline steps. They share the build workspace, mounted as a volume, and therefore have access to your source tree. - -## Finding Plugins - -For official plugins, you can use the Woodpecker plugin index: - -- [Official Woodpecker Plugins](https://woodpecker-ci.org/plugins) - -:::tip -There are also other plugin lists with additional plugins. Keep in mind that [Drone](https://www.drone.io/) plugins are generally supported, but could need some adjustments and tweaking. - -- [Drone Plugins](http://plugins.drone.io) -- [Geeklab Woodpecker Plugins](https://woodpecker-plugins.geekdocs.de/) - -::: - -## Creating a plugin - -See a [detailed plugin example](./20-sample-plugin.md). diff --git a/docs/versioned_docs/version-2.1/20-usage/51-plugins/20-sample-plugin.md b/docs/versioned_docs/version-2.1/20-usage/51-plugins/20-sample-plugin.md deleted file mode 100644 index 317303e76c..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/51-plugins/20-sample-plugin.md +++ /dev/null @@ -1,60 +0,0 @@ -# Example plugin - -This provides a brief tutorial for creating a Woodpecker webhook plugin, using simple shell scripting, to make an http requests during the build pipeline. - -## What end users will see - -The below example demonstrates how we might configure a webhook plugin in the YAML file: - -```yaml -steps: - webhook: - image: foo/webhook - settings: - url: http://example.com - method: post - body: | - hello world -``` - -## Write the logic - -Create a simple shell script that invokes curl using the YAML configuration parameters, which are passed to the script as environment variables in uppercase and prefixed with `PLUGIN_`. - -```bash -#!/bin/sh - -curl \ - -X ${PLUGIN_METHOD} \ - -d ${PLUGIN_BODY} \ - ${PLUGIN_URL} -``` - -## Package it - -Create a Dockerfile that adds your shell script to the image, and configures the image to execute your shell script as the main entrypoint. - -```dockerfile -FROM alpine -ADD script.sh /bin/ -RUN chmod +x /bin/script.sh -RUN apk -Uuv add curl ca-certificates -ENTRYPOINT /bin/script.sh -``` - -Build and publish your plugin to the Docker registry. Once published your plugin can be shared with the broader Woodpecker community. - -```nohighlight -docker build -t foo/webhook . -docker push foo/webhook -``` - -Execute your plugin locally from the command line to verify it is working: - -```nohighlight -docker run --rm \ - -e PLUGIN_METHOD=post \ - -e PLUGIN_URL=http://example.com \ - -e PLUGIN_BODY="hello world" \ - foo/webhook -``` diff --git a/docs/versioned_docs/version-2.1/20-usage/51-plugins/_category_.yaml b/docs/versioned_docs/version-2.1/20-usage/51-plugins/_category_.yaml deleted file mode 100644 index e24478e856..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/51-plugins/_category_.yaml +++ /dev/null @@ -1,7 +0,0 @@ -label: 'Plugins' -# position: 2 -collapsible: true -collapsed: true -link: - type: 'doc' - id: 'plugins' diff --git a/docs/versioned_docs/version-2.1/20-usage/60-services.md b/docs/versioned_docs/version-2.1/20-usage/60-services.md deleted file mode 100644 index f2f157e075..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/60-services.md +++ /dev/null @@ -1,99 +0,0 @@ -# Services - -Woodpecker provides a services section in the YAML file used for defining service containers. -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`. - -```yaml -steps: - build: - image: golang - commands: - - go build - - go test - -services: - database: - image: mysql - - cache: - image: redis -``` - -## Configuration - -Service containers generally expose environment variables to customize service startup such as default usernames, passwords and ports. Please see the official image documentation to learn more. - -```diff -services: - database: - image: mysql -+ environment: -+ - MYSQL_DATABASE=test -+ - MYSQL_ALLOW_EMPTY_PASSWORD=yes - - cache: - image: redis -``` - -## Detachment - -Service and long running containers can also be included in the pipeline section of the configuration using the detach parameter without blocking other steps. This should be used when explicit control over startup order is required. - -```diff -steps: - build: - image: golang - commands: - - go build - - go test - - database: - image: redis -+ detach: true - - test: - image: golang - commands: - - go test -``` - -Containers from detached steps will terminate when the pipeline ends. - -## Initialization - -Service containers require time to initialize and begin to accept connections. If you are unable to connect to a service you may need to wait a few seconds or implement a backoff. - -```diff -steps: - test: - image: golang - commands: -+ - sleep 15 - - go get - - go test - -services: - database: - image: mysql -``` - -## Complete Pipeline Example - -```yaml -services: - database: - image: mysql - environment: - - MYSQL_DATABASE=test - - MYSQL_ROOT_PASSWORD=example -steps: - get-version: - image: ubuntu - commands: - - ( apt update && apt dist-upgrade -y && apt install -y mysql-client 2>&1 )> /dev/null - - sleep 30s # need to wait for mysql-server init - - echo 'SHOW VARIABLES LIKE "version"' | mysql -uroot -hdatabase test -pexample -``` diff --git a/docs/versioned_docs/version-2.1/20-usage/70-volumes.md b/docs/versioned_docs/version-2.1/20-usage/70-volumes.md deleted file mode 100644 index 297f14ec07..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/70-volumes.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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. - -:::note -Volumes are only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./71-project-settings.md#trusted) to enable trusted mode. -::: - -```diff -steps: - build: - image: docker - commands: - - docker build --rm -t octocat/hello-world . - - docker run --rm octocat/hello-world --test - - docker push octocat/hello-world - - docker rmi octocat/hello-world - volumes: -+ - /var/run/docker.sock:/var/run/docker.sock -``` - -Please note that Woodpecker mounts volumes on the host machine. This means you must use absolute paths when you configure volumes. Attempting to use relative paths will result in an error. - -```diff -- volumes: [ ./certs:/etc/ssl/certs ] -+ volumes: [ /etc/ssl/certs:/etc/ssl/certs ] -``` diff --git a/docs/versioned_docs/version-2.1/20-usage/71-project-settings.md b/docs/versioned_docs/version-2.1/20-usage/71-project-settings.md deleted file mode 100644 index 41bab0dd59..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/71-project-settings.md +++ /dev/null @@ -1,54 +0,0 @@ -# Project settings - -As the owner of a project in Woodpecker you can change project related settings via the web interface. - -![project settings](./project-settings.png) - -## Pipeline path - -The path to the pipeline config file or folder. By default it is left empty which will use the following configuration resolution `.woodpecker/*.yml` -> `.woodpecker/*.yaml` -> `.woodpecker.yml` -> `.woodpecker.yaml`. If you set a custom path Woodpecker tries to load your configuration or fails if no configuration could be found at the specified location. To use a [multiple workflows](./25-workflows.md) with a custom path you have to change it to a folder path ending with a `/` like `.woodpecker/`. - -## Repository hooks - -Your Version-Control-System will notify Woodpecker about events via webhooks. If you want your pipeline to only run on specific webhooks, you can check them with this setting. - -## Project settings - -### Allow pull requests - -Enables handling webhook's pull request event. If disabled, then pipeline won't run for pull requests. - -### Protected - -Every pipeline initiated by an webhook event needs to be approved by a project members with push permissions before being executed. -The protected option can be used as an additional review process before running potentially harmful pipelines. Especially if pipelines can be executed by third-parties through pull-requests. - -### Trusted - -If you set your project to trusted, a pipeline step and by this the underlying containers gets access to escalated capabilities like mounting volumes. - -:::note - -Only server admins can set this option. If you are not a server admin this option won't be shown in your project settings. - -::: - -### Only inject netrc credentials into trusted containers - -Cloning pipeline step may need git credentials. They are injected via netrc. By default, they're only injected if this option is enabled, the repo is trusted ([see above](#trusted)) or the image is a trusted clone image. If you uncheck the option, git credentials will be injected into any container in clone step. - -## Project visibility - -You can change the visibility of your project by this setting. If a user has access to a project they can see all builds and their logs and artifacts. Settings, Secrets and Registries can only be accessed by owners. - -- `Public` Every user can see your project without being logged in. -- `Internal` Only authenticated users of the Woodpecker instance can see this project. -- `Private` Only you and other owners of the repository can see this project. - -## Timeout - -After this timeout a pipeline has to finish or will be treated as timed out. - -## Cancel previous pipelines - -By enabling this option for a pipeline event previous pipelines of the same event and context will be canceled before starting the newly triggered one. diff --git a/docs/versioned_docs/version-2.1/20-usage/80-badges.md b/docs/versioned_docs/version-2.1/20-usage/80-badges.md deleted file mode 100644 index 1edfcfd495..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/80-badges.md +++ /dev/null @@ -1,18 +0,0 @@ -# Status Badges - -Woodpecker has integrated support for repository status badges. These badges can be added to your website or project readme file to display the status of your code. - -## Badge endpoint - -```text -:///api/badges//status.svg -``` - -The status badge displays the status for the latest build to your default branch (e.g. main). You can customize the branch by adding the `branch` query parameter. - -```diff --:///api/badges//status.svg -+:///api/badges//status.svg?branch= -``` - -Please note status badges do not include pull request results, since the status of a pull request does not provide an accurate representation of your repository state. diff --git a/docs/versioned_docs/version-2.1/20-usage/90-advanced-usage.md b/docs/versioned_docs/version-2.1/20-usage/90-advanced-usage.md deleted file mode 100644 index 56b1a153d9..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/90-advanced-usage.md +++ /dev/null @@ -1,134 +0,0 @@ -# Advanced usage - -## Advanced YAML syntax - -YAML has some advanced syntax features that can be used like variables to reduce duplication in your pipeline config: - -### Anchors & aliases - -You can use [YAML anchors & aliases](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) as variables in your pipeline config. - -To convert this: - -```yaml -steps: - test: - image: golang:1.18 - commands: go test ./... - build: - image: golang:1.18 - commands: build -``` - -Just add a new section called **variables** like this: - -```diff -+variables: -+ - &golang_image 'golang:1.18' - - steps: - test: -- image: golang:1.18 -+ image: *golang_image - commands: go test ./... - build: -- image: golang:1.18 -+ image: *golang_image - commands: build -``` - -### Map merges and overwrites - -```yaml -variables: - - &base-plugin-settings - target: dist - recursive: false - try: true - - &special-setting - special: true - - &some-plugin codeberg.org/6543/docker-images/print_env - -steps: - develop: - image: *some-plugin - settings: - <<: [*base-plugin-settings, *special-setting] # merge two maps into an empty map - when: - branch: develop - - main: - image: *some-plugin - settings: - <<: *base-plugin-settings # merge one map and ... - try: false # ... overwrite original value - ongoing: false # ... adding a new value - when: - branch: main -``` - -### Sequence merges - -```yaml -variables: - pre_cmds: &pre_cmds - - echo start - - whoami - post_cmds: &post_cmds - - echo stop - hello_cmd: &hello_cmd - - echo hello - -steps: - step1: - image: debian - commands: - - <<: *pre_cmds # prepend a sequence - - echo exec step now do dedicated things - - <<: *post_cmds # append a sequence - step2: - image: debian - commands: - - <<: [*pre_cmds, *hello_cmd] # prepend two sequences - - echo echo from second step - - <<: *post_cmds -``` - -### References - -- [Official YAML specification](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) -- [YAML Cheatsheet](https://learnxinyminutes.com/docs/yaml) - -## Persisting environment data between steps - -One can create a file containing environment variables, and then source it in each step that needs them. - -```yaml -steps: - init: - image: bash - commands: - - echo "FOO=hello" >> envvars - - echo "BAR=world" >> envvars - - debug: - image: bash - commands: - - source envvars - - echo $FOO -``` - -## Declaring global variables in `docker-compose.yml` - -As described in [Global environment variables](./50-environment.md#global-environment-variables), one can define global variables: - -```yaml -services: - woodpecker-server: - # ... - environment: - - WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2 - # ... -``` - -Note that this tightly couples the server and app configurations (where the app is a completely separate application). But this is a good option for truly global variables which should apply to all steps in all pipelines for all apps. diff --git a/docs/versioned_docs/version-2.1/20-usage/_category_.yaml b/docs/versioned_docs/version-2.1/20-usage/_category_.yaml deleted file mode 100644 index ba9f729ed0..0000000000 --- a/docs/versioned_docs/version-2.1/20-usage/_category_.yaml +++ /dev/null @@ -1,4 +0,0 @@ -label: 'Usage' -# position: 2 -collapsible: true -collapsed: false diff --git a/docs/versioned_docs/version-2.1/20-usage/cron-settings.png b/docs/versioned_docs/version-2.1/20-usage/cron-settings.png deleted file mode 100644 index d11c507afc..0000000000 Binary files a/docs/versioned_docs/version-2.1/20-usage/cron-settings.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/20-usage/project-settings.png b/docs/versioned_docs/version-2.1/20-usage/project-settings.png deleted file mode 100644 index fc29daac84..0000000000 Binary files a/docs/versioned_docs/version-2.1/20-usage/project-settings.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/20-usage/repo-list.png b/docs/versioned_docs/version-2.1/20-usage/repo-list.png deleted file mode 100644 index b473800876..0000000000 Binary files a/docs/versioned_docs/version-2.1/20-usage/repo-list.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/30-administration/00-deployment/00-overview.md b/docs/versioned_docs/version-2.1/30-administration/00-deployment/00-overview.md deleted file mode 100644 index cd34fcf421..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/00-deployment/00-overview.md +++ /dev/null @@ -1,72 +0,0 @@ -# Deployment - -A Woodpecker deployment consists of two parts: - -- A server which is the heart of Woodpecker and ships the web interface. -- Next to one server, you can deploy any number of agents which will run the pipelines. - -Each agent is able to process one pipeline step by default. -If you have four agents installed and connected to the Woodpecker server, your system will process four workflows in parallel. - -:::tip -You can add more agents to increase the number of parallel workflows or set the agent's `WOODPECKER_MAX_WORKFLOWS=1` environment variable to increase the number of parallel workflows for that agent. -::: - -## Which version of Woodpecker should I use? - -Woodpecker is having two different kinds of releases: **stable** and **next**. - -## Hardware Requirements - -Below are minimal resources requirements for Woodpecker components itself: - -| Component | Memory | CPU | -| --------- | ------ | --- | -| Server | 200 MB | 1 | -| Agent | 32 MB | 1 | - -Note, that those values do not include the operating system or workload (pipelines execution) resources consumption. - -In addition you need at least some kind of database which requires additional resources depending on the selected database system. - -## Installation - -You can install Woodpecker on multiple ways: - -- Using [docker-compose](./10-docker-compose.md) with the official [container images](./10-docker-compose.md#docker-images) -- Using [Kubernetes](./20-kubernetes.md) via the Woodpecker Helm chart -- Using binaries, DEBs or RPMs you can download from [latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest) - -## Authentication - -Authentication is done using OAuth and is delegated to your forge which is configured using environment variables. - -See the complete reference for all supported forges [here](../11-forges/10-overview.md). - -## Database - -By default Woodpecker uses a SQLite database which requires zero installation or configuration. See the [database settings](../30-database.md) page to further configure it or use MySQL or Postgres. - -## SSL - -Woodpecker supports SSL configuration by using Let's encrypt or by using own certificates. See the [SSL guide](../60-ssl.md). You can also put it behind a [reverse proxy](#behind-a-proxy) - -## Metrics - -A [Prometheus endpoint](../90-prometheus.md) is exposed. - -## Behind a proxy - -See the [proxy guide](../70-proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok. - -In the case you need to use Woodpecker with a URL path prefix (like: ), add the root path to [`WOODPECKER_HOST`](../10-server-config.md#woodpecker_host). - -## Third-party installation methods - -:::info -These installation methods are not officially supported. If you experience issues with them, please open issues in the specific repositories. -::: - -- Using [NixOS](./30-nixos.md) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker) -- [Using YunoHost](https://apps.yunohost.org/app/woodpecker) -- [On Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html) diff --git a/docs/versioned_docs/version-2.1/30-administration/00-deployment/10-docker-compose.md b/docs/versioned_docs/version-2.1/30-administration/00-deployment/10-docker-compose.md deleted file mode 100644 index ea78f1ca11..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/00-deployment/10-docker-compose.md +++ /dev/null @@ -1,147 +0,0 @@ -# docker-compose - -The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start a Woodpecker server with a single agent. - -It relies on a number of environment variables that you must set before running `docker-compose up`. The variables are described below. - -```yaml title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - image: woodpeckerci/woodpecker-server:latest - ports: - - 8000:8000 - volumes: - - woodpecker-server-data:/var/lib/woodpecker/ - environment: - - WOODPECKER_OPEN=true - - WOODPECKER_HOST=${WOODPECKER_HOST} - - WOODPECKER_GITHUB=true - - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT} - - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET} - - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} - - woodpecker-agent: - image: woodpeckerci/woodpecker-agent:latest - command: agent - restart: always - depends_on: - - woodpecker-server - volumes: - - woodpecker-agent-config:/etc/woodpecker - - /var/run/docker.sock:/var/run/docker.sock - environment: - - WOODPECKER_SERVER=woodpecker-server:9000 - - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} - -volumes: - woodpecker-server-data: - woodpecker-agent-config: -``` - -Woodpecker needs to know its own address. You must therefore provide the public address of it in `://` format. Please omit trailing slashes: - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_HOST=${WOODPECKER_HOST} -``` - -Woodpecker can also have its port's configured. It uses a separate port for gRPC and for HTTP. The agent performs gRPC calls and connects to the gRPC port. -They can be configured with ADDR variables: - -```diff title="docker-compose.yml" -version: '3' -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR} -+ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR} -``` - -Reverse proxying can also be [configured for gRPC](../proxy#caddy). If the agents are connecting over the internet, it should also be SSL encrypted. The agent then needs to be configured to be secure: - -```diff title="docker-compose.yml" -version: '3' -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_GRPC_SECURE=true # defaults to false -+ - WOODPECKER_GRPC_VERIFY=true # default -``` - -As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon: - -```diff title="docker-compose.yml" -version: '3' - -services: - [...] - woodpecker-agent: - [...] -+ volumes: -+ - /var/run/docker.sock:/var/run/docker.sock -``` - -Agents require the server address for agent-to-server communication. The agent connects to the server's gRPC port: - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-agent: - [...] - environment: -+ - WOODPECKER_SERVER=woodpecker-server:9000 -``` - -The server and agents use a shared secret to authenticate communication. This should be a random string of your choosing and should be kept private. You can generate such string with `openssl rand -hex 32`: - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} - woodpecker-agent: - [...] - environment: - - [...] -+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} -``` - -## Docker images - -Image variants: - -- The `latest` image is the latest stable release -- The `vX.X.X` images are stable releases -- The `vX.X` images are based on the current release branch (e.g. `release/v1.0`) and can be used to get bugfixes asap -- The `next` images are based on the current `main` branch and should not be used for production environments - -```bash -# server -docker pull woodpeckerci/woodpecker-server:latest -docker pull woodpeckerci/woodpecker-server:latest-alpine - -# agent -docker pull woodpeckerci/woodpecker-agent:latest -docker pull woodpeckerci/woodpecker-agent:latest-alpine - -# cli -docker pull woodpeckerci/woodpecker-cli:latest -docker pull woodpeckerci/woodpecker-cli:latest-alpine -``` diff --git a/docs/versioned_docs/version-2.1/30-administration/00-deployment/20-kubernetes.md b/docs/versioned_docs/version-2.1/30-administration/00-deployment/20-kubernetes.md deleted file mode 100644 index f931c3e785..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/00-deployment/20-kubernetes.md +++ /dev/null @@ -1,9 +0,0 @@ -# Kubernetes - -We recommended to deploy Woodpecker using the [Woodpecker helm chart](https://github.com/woodpecker-ci/helm). -Have a look at the [`values.yaml`](https://github.com/woodpecker-ci/helm/blob/main/charts/woodpecker/values.yaml) config files for all available settings. - -The chart contains two subcharts, `server` and `agent` which are automatically configured as needed. -The chart started off with two independent charts but was merged into one to simplify the deployment at start of 2023. - -A couple of backend-specific config env vars exists which are described in the [kubernetes backend docs](../22-backends/40-kubernetes.md). diff --git a/docs/versioned_docs/version-2.1/30-administration/00-deployment/30-nixos.md b/docs/versioned_docs/version-2.1/30-administration/00-deployment/30-nixos.md deleted file mode 100644 index 148fbd581d..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/00-deployment/30-nixos.md +++ /dev/null @@ -1,88 +0,0 @@ -# NixOS - -:::info -Note that this module is not maintained by the woodpecker-developers. -If you experience issues please open a bug report in the [nixpkgs repo](https://github.com/NixOS/nixpkgs/issues/new/choose) where the module is maintained. -::: - -The NixOS install is in theory quite similar to the binary install and supports multiple backends. -In practice, the settings are specified declaratively in the NixOS configuration and no manual steps need to be taken. - -## General Configuration - -```nix -{ config -, ... -}: -let - domain = "woodpecker.example.org"; -in -{ - # This automatically sets up certificates via let's encrypt - security.acme.defaults.email = "acme@example.com"; - security.acme.acceptTerms = true; - security.acme.certs."${domain}" = { }; - - # Setting up a nginx proxy that handles tls for us - networking.firewall.allowedTCPPorts = [ 80 443 ]; - services.nginx = { - enable = true; - recommendedTlsSettings = true; - recommendedOptimisation = true; - recommendedProxySettings = true; - virtualHosts."${domain}" = { - enableACME = true; - forceSSL = true; - locations."/" = { - proxyPass = "http://localhost:3007"; - }; - }; - }; - - services.woodpecker-server = { - enable = true; - environment = { - WOODPECKER_HOST = "https://${domain}"; - WOODPECKER_SERVER_ADDR = ":3007"; - WOODPECKER_OPEN = "true"; - }; - # You can pass a file with env vars to the system it could look like: - # WOODPECKER_AGENT_SECRET=XXXXXXXXXXXXXXXXXXXXXX - environmentFile = "/path/to/my/secrets/file"; - }; - - # This sets up a woodpecker agent - services.woodpecker-agents.agents."docker" = { - enable = true; - # We need this to talk to the podman socket - extraGroups = [ "podman" ]; - environment = { - WOODPECKER_SERVER = "localhost:9000"; - WOODPECKER_MAX_WORKFLOWS = "4"; - DOCKER_HOST = "unix:///run/podman/podman.sock"; - WOODPECKER_BACKEND = "docker"; - }; - # Same as with woodpecker-server - environmentFile = [ "/var/lib/secrets/woodpecker.env" ]; - }; - - # Here we setup podman and enable dns - virtualisation.podman = { - enable = true; - defaultNetwork.settings = { - dns_enabled = true; - }; - }; - # This is needed for podman to be able to talk over dns - networking.firewall.interfaces."podman0" = { - allowedUDPPorts = [ 53 ]; - allowedTCPPorts = [ 53 ]; - }; -} -``` - -All configuration options can be found via [NixOS Search](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker) - -## Tips and tricks - -There are some resources on how to utilize Woodpecker more effectively with NixOS on the [Awesome Woodpecker](../../92-awesome.md) page, like using the runners nix-store in the pipeline diff --git a/docs/versioned_docs/version-2.1/30-administration/00-deployment/_category_.yaml b/docs/versioned_docs/version-2.1/30-administration/00-deployment/_category_.yaml deleted file mode 100644 index 7284349698..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/00-deployment/_category_.yaml +++ /dev/null @@ -1,6 +0,0 @@ -label: 'Deployment' -collapsible: true -collapsed: true -link: - type: 'doc' - id: 'overview' diff --git a/docs/versioned_docs/version-2.1/30-administration/10-server-config.md b/docs/versioned_docs/version-2.1/30-administration/10-server-config.md deleted file mode 100644 index fd6b55d59e..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/10-server-config.md +++ /dev/null @@ -1,611 +0,0 @@ -# Server configuration - -## User registration - -Woodpecker does not have its own user registry; users are provided from your [forge](./11-forges/10-overview.md) (using OAuth2). - -Registration is closed by default (`WOODPECKER_OPEN=false`). If registration is open (`WOODPECKER_OPEN=true`) then every user with an account at the configured forge can login to Woodpecker. - -To open registration: - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_OPEN=true -``` - -You can **also restrict** registration, by keep registration closed and ...\ -... **adding** new **users manually** via the CLI: `woodpecker-cli user add`, or\ -... allowing specific **admin users** via the `WOODPECKER_ADMIN` setting, or\ -by open registration and **filter by organization** membership through the `WOODPECKER_ORGS` setting. - -### To close registration, but allow specific admin users - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_OPEN=false -+ - WOODPECKER_ADMIN=johnsmith,janedoe -``` - -### To only allow registration of users, who are members of approved organizations - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_OPEN=true -+ - WOODPECKER_ORGS=dolores,dogpatch -``` - -## Administrators - -Administrators should also be enumerated in your configuration. - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_ADMIN=johnsmith,janedoe -``` - -## Filtering repositories - -Woodpecker operates with the user's OAuth permission. Due to the coarse permission handling of GitHub, you may end up syncing more repos into Woodpecker than preferred. - -Use the `WOODPECKER_REPO_OWNERS` variable to filter which GitHub user's repos should be synced only. You typically want to put here your company's GitHub name. - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_REPO_OWNERS=mycompany,mycompanyossgithubuser -``` - -## Global registry setting - -If you want to make available a specific private registry to all pipelines, use the `WOODPECKER_DOCKER_CONFIG` server configuration. -Point it to your server's docker config. - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - volumes: - - [...] -+ - /home/user/.docker/config.json:/root/.docker/config.json:ro - environment: - - [...] -+ - WOODPECKER_DOCKER_CONFIG=/root/.docker/config.json -``` - -## Handling sensitive data in docker-compose and docker-swarm - -To handle sensitive data in docker-compose or docker-swarm configurations there are several options: - -For docker-compose you can use a .env file next to your compose configuration to store the secrets outside of the compose file. While this separates configuration from secrets it is still not very secure. - -Alternatively use docker-secrets. As it may be difficult to use docker secrets for environment variables woodpecker allows to read sensible data from files by providing a `*_FILE` option of all sensible configuration variables. Woodpecker will try to read the value directly from this file. Keep in mind that when the original environment variable gets specified at the same time it will override the value read from the file. - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_AGENT_SECRET_FILE=/run/secrets/woodpecker-agent-secret -+ secrets: -+ - woodpecker-agent-secret -+ -+secrets: -+ woodpecker-agent-secret: -+ external: true -``` - -Store a value to a docker secret like this: -`echo "my_agent_secret_key" | docker secret create woodpecker-agent-secret -` - -or generate a random one like this: - -`openssl rand -hex 32 | docker secret create woodpecker-agent-secret -` - -## Custom Javascript and CSS Styling (a.k.a. white-labeling) - -Woodpecker supports custom styling of the Web UI by providing custom JS and CSS files. -These files must be present in the server's filesystem. -They can be backed in a Docker image or mounted from a ConfigMap inside a Kubernetes environment. -The configuration variables are independent of each other, which means it can be just one file present, or both. - -```text -WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.css -WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.js -``` - -The examples below show how to place a banner message in the top navigation bar of Woodpecker. - -### woodpecker.css - -```css -.banner-message { - position: absolute; - width: 280px; - height: 40px; - margin-left: 240px; - margin-top: 5px; - padding-top: 5px; - font-weight: bold; - background: red no-repeat; - text-align: center; -} -``` - -### woodpecker.js - -```javascript -// place/copy a minified version of jQuery or ZeptoJS here ... -!(function () { - 'use strict'; - function e() {} /*...*/ -})(); - -$().ready(function () { - $('.app nav img').first().htmlAfter(""); -}); -``` - -## All server configuration options - -The following list describes all available server configuration options. - -### `WOODPECKER_LOG_LEVEL` - -> Default: empty - -Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty. - -### `WOODPECKER_LOG_FILE` - -> Default: `stderr` - -Output destination for logs. -'stdout' and 'stderr' can be used as special keywords. - -### `WOODPECKER_LOG_XORM` - -> Default: `false` - -Enable XORM logs. - -### `WOODPECKER_LOG_XORM_SQL` - -> Default: `false` - -Enable XORM SQL command logs. - -### `WOODPECKER_DEBUG_PRETTY` - -> Default: `false` - -Enable pretty-printed debug output. - -### `WOODPECKER_DEBUG_NOCOLOR` - -> Default: `true` - -Disable colored debug output. - -### `WOODPECKER_HOST` - -> Default: empty - -Server fully qualified URL of the user-facing hostname and path prefix. - -Example: `WOODPECKER_HOST=http://woodpecker.example.org` or `WOODPECKER_HOST=http://example.org/woodpecker` - -### `WOODPECKER_WEBHOOK_HOST` - -> Default: value from `WOODPECKER_HOST` config env - -Server fully qualified URL of the Webhook-facing hostname and path prefix. - -Example: `WOODPECKER_WEBHOOK_HOST=http://woodpecker-server.cicd.svc.cluster.local:8000` - -### `WOODPECKER_SERVER_ADDR` - -> Default: `:8000` - -Configures the HTTP listener port. - -### `WOODPECKER_SERVER_ADDR_TLS` - -> Default: `:443` - -Configures the HTTPS listener port when SSL is enabled. - -### `WOODPECKER_SERVER_CERT` - -> Default: empty - -Path to an SSL certificate used by the server to accept HTTPS requests. - -Example: `WOODPECKER_SERVER_CERT=/path/to/cert.pem` - -### `WOODPECKER_SERVER_KEY` - -> Default: empty - -Path to an SSL certificate key used by the server to accept HTTPS requests. - -Example: `WOODPECKER_SERVER_KEY=/path/to/key.pem` - -### `WOODPECKER_CUSTOM_CSS_FILE` - -> Default: empty - -File path for the server to serve a custom .CSS file, used for customizing the UI. -Can be used for showing banner messages, logos, or environment-specific hints (a.k.a. white-labeling). -The file must be UTF-8 encoded, to ensure all special characters are preserved. - -Example: `WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.css` - -### `WOODPECKER_CUSTOM_JS_FILE` - -> Default: empty - -File path for the server to serve a custom .JS file, used for customizing the UI. -Can be used for showing banner messages, logos, or environment-specific hints (a.k.a. white-labeling). -The file must be UTF-8 encoded, to ensure all special characters are preserved. - -Example: `WOODPECKER_CUSTOM_JS_FILE=/usr/local/www/woodpecker.js` - -### `WOODPECKER_LETS_ENCRYPT` - -> Default: `false` - -Automatically generates an SSL certificate using Let's Encrypt, and configures the server to accept HTTPS requests. - -### `WOODPECKER_GRPC_ADDR` - -> Default: `:9000` - -Configures the gRPC listener port. - -### `WOODPECKER_GRPC_SECRET` - -> Default: `secret` - -Configures the gRPC JWT secret. - -### `WOODPECKER_GRPC_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GRPC_SECRET` from the specified filepath. - -### `WOODPECKER_METRICS_SERVER_ADDR` - -> Default: empty - -Configures an unprotected metrics endpoint. An empty value disables the metrics endpoint completely. - -Example: `:9001` - -### `WOODPECKER_ADMIN` - -> Default: empty - -Comma-separated list of admin accounts. - -Example: `WOODPECKER_ADMIN=user1,user2` - -### `WOODPECKER_ORGS` - -> Default: empty - -Comma-separated list of approved organizations. - -Example: `org1,org2` - -### `WOODPECKER_REPO_OWNERS` - -> Default: empty - -Comma-separated list of syncable repo owners. ??? - -Example: `user1,user2` - -### `WOODPECKER_OPEN` - -> Default: `false` - -Enable to allow user registration. - -### `WOODPECKER_AUTHENTICATE_PUBLIC_REPOS` - -> Default: `false` - -Always use authentication to clone repositories even if they are public. Needed if the forge requires to always authenticate as used by many companies. - -### `WOODPECKER_DEFAULT_CANCEL_PREVIOUS_PIPELINE_EVENTS` - -> Default: `pull_request, push` - -List of event names that will be canceled when a new pipeline for the same context (tag, branch) is created. - -### `WOODPECKER_DEFAULT_CLONE_IMAGE` - -> Default is defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go) - -The default docker image to be used when cloning the repo - -### `WOODPECKER_DEFAULT_PIPELINE_TIMEOUT` - -> 60 (minutes) - -The default time for a repo in minutes before a pipeline gets killed - -### `WOODPECKER_MAX_PIPELINE_TIMEOUT` - -> 120 (minutes) - -The maximum time in minutes you can set in the repo settings before a pipeline gets killed - -### `WOODPECKER_SESSION_EXPIRES` - -> Default: `72h` - -Configures the session expiration time. -Context: when someone does log into Woodpecker, a temporary session token is created. -As long as the session is valid (until it expires or log-out), -a user can log into Woodpecker, without re-authentication. - -### `WOODPECKER_ESCALATE` - -> Defaults are defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go) - -Docker images to run in privileged mode. Only change if you are sure what you do! - - - -### `WOODPECKER_DOCKER_CONFIG` - -> Default: empty - -Configures a specific private registry config for all pipelines. - -Example: `WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json` - - - -### `WOODPECKER_AGENT_SECRET` - -> Default: empty - -A shared secret used by server and agents to authenticate communication. A secret can be generated by `openssl rand -hex 32`. - -### `WOODPECKER_AGENT_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_AGENT_SECRET` from the specified filepath - -### `WOODPECKER_KEEPALIVE_MIN_TIME` - -> Default: empty - -Server-side enforcement policy on the minimum amount of time a client should wait before sending a keepalive ping. - -Example: `WOODPECKER_KEEPALIVE_MIN_TIME=10s` - -### `WOODPECKER_DATABASE_DRIVER` - -> Default: `sqlite3` - -The database driver name. Possible values are `sqlite3`, `mysql` or `postgres`. - -### `WOODPECKER_DATABASE_DATASOURCE` - -> Default: `woodpecker.sqlite` - -The database connection string. The default value is the path of the embedded SQLite database file. - -Example: - -```bash -# MySQL -# https://github.com/go-sql-driver/mysql#dsn-data-source-name -WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true - -# PostgreSQL -# https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING -WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker?sslmode=disable -``` - -### `WOODPECKER_DATABASE_DATASOURCE_FILE` - -> Default: empty - -Read the value for `WOODPECKER_DATABASE_DATASOURCE` from the specified filepath - -### `WOODPECKER_ENCRYPTION_KEY` - -> Default: empty - -Encryption key used to encrypt secrets in DB. See [secrets encryption](./40-encryption.md) - -### `WOODPECKER_ENCRYPTION_KEY_FILE` - -> Default: empty - -Read the value for `WOODPECKER_ENCRYPTION_KEY` from the specified filepath - -### `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE` - -> Default: empty - -Filepath to encryption keyset used to encrypt secrets in DB. See [secrets encryption](./40-encryption.md) - -### `WOODPECKER_ENCRYPTION_DISABLE` - -> Default: empty - -Boolean flag to decrypt secrets in DB and disable server encryption. See [secrets encryption](./40-encryption.md) - -### `WOODPECKER_PROMETHEUS_AUTH_TOKEN` - -> Default: empty - -Token to secure the Prometheus metrics endpoint. -Must be set to enable the endpoint. - -### `WOODPECKER_PROMETHEUS_AUTH_TOKEN_FILE` - -> Default: empty - -Read the value for `WOODPECKER_PROMETHEUS_AUTH_TOKEN` from the specified filepath - -### `WOODPECKER_STATUS_CONTEXT` - -> Default: `ci/woodpecker` - -Context prefix Woodpecker will use to publish status messages to SCM. You probably will only need to change it if you run multiple Woodpecker instances for a single repository. - -### `WOODPECKER_STATUS_CONTEXT_FORMAT` - -> Default: `{{ .context }}/{{ .event }}/{{ .workflow }}{{if not (eq .axis_id 0)}}/{{.axis_id}}{{end}}` - -Template for the status messages published to forges, uses [Go templates](https://pkg.go.dev/text/template) as template language. -Supported variables: - -- `context`: Woodpecker's context (see `WOODPECKER_STATUS_CONTEXT`) -- `event`: the event which started the pipeline -- `workflow`: the workflow's name -- `owner`: the repo's owner -- `repo`: the repo's name - -### WOODPECKER_ADDONS - -> Default: empty - -List of addon files. See [addons](./75-addons/00-overview.md). - ---- - -### `WOODPECKER_LIMIT_MEM_SWAP` - -> Default: `0` - -The maximum amount of memory a single pipeline container is allowed to swap to disk, configured in bytes. There is no limit if `0`. - -### `WOODPECKER_LIMIT_MEM` - -> Default: `0` - -The maximum amount of memory a single pipeline container can use, configured in bytes. There is no limit if `0`. - -### `WOODPECKER_LIMIT_SHM_SIZE` - -> Default: `0` - -The maximum amount of memory of `/dev/shm` allowed in bytes. There is no limit if `0`. - -### `WOODPECKER_LIMIT_CPU_QUOTA` - -> Default: `0` - -The number of microseconds per CPU period that the container is limited to before throttled. There is no limit if `0`. - -### `WOODPECKER_LIMIT_CPU_SHARES` - -> Default: `0` - -The relative weight vs. other containers. - -### `WOODPECKER_LIMIT_CPU_SET` - -> Default: empty - -Comma-separated list to limit the specific CPUs or cores a pipeline container can use. - -Example: `WOODPECKER_LIMIT_CPU_SET=1,2` - -### `WOODPECKER_CONFIG_SERVICE_ENDPOINT` - -> Default: empty - -Specify a configuration service endpoint, see [Configuration Extension](./100-external-configuration-api.md) - -### `WOODPECKER_FORGE_TIMEOUT` - -> Default: 3sec - -Specify how many seconds before timeout when fetching the Woodpecker configuration from a Forge - -### `WOODPECKER_ENABLE_SWAGGER` - -> Default: true - -Enable the Swagger UI for API documentation. - ---- - -### `WOODPECKER_GITHUB_...` - -See [GitHub configuration](forges/github/#configuration) - -### `WOODPECKER_GITEA_...` - -See [Gitea configuration](forges/gitea/#configuration) - -### `WOODPECKER_BITBUCKET_...` - -See [Bitbucket configuration](forges/bitbucket/#configuration) - -### `WOODPECKER_GITLAB_...` - -See [Gitlab configuration](forges/gitlab/#configuration) diff --git a/docs/versioned_docs/version-2.1/30-administration/100-external-configuration-api.md b/docs/versioned_docs/version-2.1/30-administration/100-external-configuration-api.md deleted file mode 100644 index 47e6277acb..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/100-external-configuration-api.md +++ /dev/null @@ -1,106 +0,0 @@ -# External Configuration API - -To provide additional management and preprocessing capabilities for pipeline configurations Woodpecker supports an HTTP API which can be enabled to call an external config service. -Before the run or restart of any pipeline Woodpecker will make a POST request to an external HTTP API sending the current repository, build information and all current config files retrieved from the repository. The external API can then send back new pipeline configurations that will be used immediately or respond with `HTTP 204` to tell the system to use the existing configuration. - -Every request sent by Woodpecker is signed using a [http-signature](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures) by a private key (ed25519) generated on the first start of the Woodpecker server. You can get the public key for the verification of the http-signature from `http(s)://your-woodpecker-server/api/signature/public-key`. - -A simplistic example configuration service can be found here: [https://github.com/woodpecker-ci/example-config-service](https://github.com/woodpecker-ci/example-config-service) - -:::warning -You need to trust the external config service as it is getting secret information about the repository and pipeline and has the ability to change pipeline configs that could run malicious tasks. -::: - -## Config - -```bash -# Server -# ... -WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig -``` - -### Example request made by Woodpecker - -```json -{ - "repo": { - "id": 100, - "uid": "", - "user_id": 0, - "namespace": "", - "name": "woodpecker-testpipe", - "slug": "", - "scm": "git", - "git_http_url": "", - "git_ssh_url": "", - "link": "", - "default_branch": "", - "private": true, - "visibility": "private", - "active": true, - "config": "", - "trusted": false, - "protected": false, - "ignore_forks": false, - "ignore_pulls": false, - "cancel_pulls": false, - "timeout": 60, - "counter": 0, - "synced": 0, - "created": 0, - "updated": 0, - "version": 0 - }, - "pipeline": { - "author": "myUser", - "author_avatar": "https://myforge.com/avatars/d6b3f7787a685fcdf2a44e2c685c7e03", - "author_email": "my@email.com", - "branch": "main", - "changed_files": ["somefilename.txt"], - "commit": "2fff90f8d288a4640e90f05049fe30e61a14fd50", - "created_at": 0, - "deploy_to": "", - "enqueued_at": 0, - "error": "", - "event": "push", - "finished_at": 0, - "id": 0, - "link_url": "https://myforge.com/myUser/woodpecker-testpipe/commit/2fff90f8d288a4640e90f05049fe30e61a14fd50", - "message": "test old config\n", - "number": 0, - "parent": 0, - "ref": "refs/heads/main", - "refspec": "", - "clone_url": "", - "reviewed_at": 0, - "reviewed_by": "", - "sender": "myUser", - "signed": false, - "started_at": 0, - "status": "", - "timestamp": 1645962783, - "title": "", - "updated_at": 0, - "verified": false - }, - "configs": [ - { - "name": ".woodpecker.yml", - "data": "steps:\n backend:\n image: alpine\n commands:\n - echo \"Hello there from Repo (.woodpecker.yml)\"\n" - } - ] -} -``` - -### Example response structure - -```json -{ - "configs": [ - { - "name": "central-override", - "data": "steps:\n backend:\n image: alpine\n commands:\n - echo \"Hello there from ConfigAPI\"\n" - } - ] -} -``` diff --git a/docs/versioned_docs/version-2.1/30-administration/11-forges/10-overview.md b/docs/versioned_docs/version-2.1/30-administration/11-forges/10-overview.md deleted file mode 100644 index 897d3d8972..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/11-forges/10-overview.md +++ /dev/null @@ -1,12 +0,0 @@ -# Forges - -## Supported features - -| Feature | [GitHub](github/) | [Gitea / Forgejo](gitea/) | [Gitlab](gitlab/) | [Bitbucket](bitbucket/) | -| ------------------------------------------------------------- | :----------------: | :-----------------------: | :----------------: | :---------------------: | -| Event: Push | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| Event: Tag | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| Event: Pull-Request | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| Event: Deploy | :white_check_mark: | :x: | :x: | :x: | -| [Multiple workflows](../../20-usage/25-workflows.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| [when.path filter](../../20-usage/20-workflow-syntax.md#path) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | diff --git a/docs/versioned_docs/version-2.1/30-administration/11-forges/20-github.md b/docs/versioned_docs/version-2.1/30-administration/11-forges/20-github.md deleted file mode 100644 index f2c474ce37..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/11-forges/20-github.md +++ /dev/null @@ -1,79 +0,0 @@ -# GitHub - -Woodpecker comes with built-in support for GitHub and GitHub Enterprise. -To use Woodpecker with GitHub the following environment variables should be set for the server component: - -```bash -WOODPECKER_GITHUB=true -WOODPECKER_GITHUB_CLIENT=YOUR_GITHUB_CLIENT_ID -WOODPECKER_GITHUB_SECRET=YOUR_GITHUB_CLIENT_SECRET -``` - -You will get these values from GitHub when you register your OAuth application. -To do so, go to Settings -> Developer Settings -> GitHub Apps -> New Oauth2 App. - -:::warning -Do not use a "GitHub App" instead of an Oauth2 app as the former will not work correctly with Woodpecker right now (because user access tokens are not being refreshed automatically) -::: - -## App Settings - -- Name: An arbitrary name for your App -- Homepage URL: The URL of your Woodpecker instance -- Callback URL: `https:///authorize` -- (optional) Upload the Woodpecker Logo: - -## Client Secret Creation - -After your App has been created, you can generate a client secret. -Use this one for the `WOODPECKER_GITHUB_SECRET` environment variable. - -## 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. - -### `WOODPECKER_GITHUB` - -> Default: `false` - -Enables the GitHub driver. - -### `WOODPECKER_GITHUB_URL` - -> Default: `https://github.com` - -Configures the GitHub server address. - -### `WOODPECKER_GITHUB_CLIENT` - -> Default: empty - -Configures the GitHub OAuth client id to authorize access. - -### `WOODPECKER_GITHUB_CLIENT_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITHUB_CLIENT` from the specified filepath. - -### `WOODPECKER_GITHUB_SECRET` - -> Default: empty - -Configures the GitHub OAuth client secret. This is used to authorize access. - -### `WOODPECKER_GITHUB_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITHUB_SECRET` from the specified filepath. - -### `WOODPECKER_GITHUB_MERGE_REF` - -> Default: `true` - -### `WOODPECKER_GITHUB_SKIP_VERIFY` - -> Default: `false` - -Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-2.1/30-administration/11-forges/30-gitea.md b/docs/versioned_docs/version-2.1/30-administration/11-forges/30-gitea.md deleted file mode 100644 index a9b91838d5..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/11-forges/30-gitea.md +++ /dev/null @@ -1,102 +0,0 @@ -# Gitea / Forgejo - -Woodpecker comes with built-in support for Gitea and the "soft" fork Forgejo. To enable Gitea you should configure the Woodpecker container using the following environment variables: - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_GITEA=true -+ - WOODPECKER_GITEA_URL=${WOODPECKER_GITEA_URL} -+ - WOODPECKER_GITEA_CLIENT=${WOODPECKER_GITEA_CLIENT} -+ - WOODPECKER_GITEA_SECRET=${WOODPECKER_GITEA_SECRET} - - woodpecker-agent: - [...] -``` - -## Gitea on the same host - -If you have Gitea also running on the same host within a container, make sure the agent does have access to it. -The agent tries to clone using the URL which Gitea reports through its API. For simplified connectivity, you should add the woodpecker agent to the same docker network as Gitea is in. -Otherwise, the communication should go via the `docker0` gateway (usually 172.17.0.1). - -To configure the Docker network if the network's name is `gitea`, configure it like this: - -```diff title="docker-compose.yml" -version: '3' - -services: - [...] - woodpecker-agent: - [...] - environment: - - [...] -+ - WOODPECKER_BACKEND_DOCKER_NETWORK=gitea -``` - -## Registration - -Register your application with Gitea to create your client id and secret. You can find the OAuth applications settings of Gitea at `https://gitea./user/settings/`. It is very import the authorization callback URL matches your http(s) scheme and hostname exactly with `https:///authorize` as the path. - -If you run the Woodpecker CI server on the same host as the Gitea instance, you might also need to allow local connections in Gitea, since version `v1.16`. Otherwise webhooks will fail. Add the following lines to your Gitea configuration (usually at `/etc/gitea/conf/app.ini`). - -```ini -... -[webhook] -ALLOWED_HOST_LIST=external,loopback -``` - -For reference see [Configuration Cheat Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/#webhook-webhook). - -![gitea oauth setup](gitea_oauth.gif) - -## 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. - -### `WOODPECKER_GITEA` - -> Default: `false` - -Enables the Gitea driver. - -### `WOODPECKER_GITEA_URL` - -> Default: `https://try.gitea.io` - -Configures the Gitea server address. - -### `WOODPECKER_GITEA_CLIENT` - -> Default: empty - -Configures the Gitea OAuth client id. This is used to authorize access. - -### `WOODPECKER_GITEA_CLIENT_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITEA_CLIENT` from the specified filepath - -### `WOODPECKER_GITEA_SECRET` - -> Default: empty - -Configures the Gitea OAuth client secret. This is used to authorize access. - -### `WOODPECKER_GITEA_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITEA_SECRET` from the specified filepath - -### `WOODPECKER_GITEA_SKIP_VERIFY` - -> Default: `false` - -Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-2.1/30-administration/11-forges/40-gitlab.md b/docs/versioned_docs/version-2.1/30-administration/11-forges/40-gitlab.md deleted file mode 100644 index a3934489da..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/11-forges/40-gitlab.md +++ /dev/null @@ -1,73 +0,0 @@ -# GitLab - -Woodpecker comes with built-in support for the GitLab version 8.2 and higher. To enable GitLab you should configure the Woodpecker container using the following environment variables: - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - environment: -+ - WOODPECKER_GITLAB=true -+ - WOODPECKER_GITLAB_URL=http://gitlab.mycompany.com -+ - WOODPECKER_GITLAB_CLIENT=95c0282573633eb25e82 -+ - WOODPECKER_GITLAB_SECRET=30f5064039e6b359e075 - - woodpecker-agent: - [...] -``` - -## Registration - -You must register your application with GitLab in order to generate a Client and Secret. Navigate to your account settings and choose Applications from the menu, and click New Application. - -Please use `http://woodpecker.mycompany.com/authorize` as the Authorization callback URL. Grant `api` scope to the application. - -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`. - -## 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. - -### `WOODPECKER_GITLAB` - -> Default: `false` - -Enables the GitLab driver. - -### `WOODPECKER_GITLAB_URL` - -> Default: `https://gitlab.com` - -Configures the GitLab server address. - -### `WOODPECKER_GITLAB_CLIENT` - -> Default: empty - -Configures the GitLab OAuth client id. This is used to authorize access. - -### `WOODPECKER_GITLAB_CLIENT_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITLAB_CLIENT` from the specified filepath - -### `WOODPECKER_GITLAB_SECRET` - -> Default: empty - -Configures the GitLab OAuth client secret. This is used to authorize access. - -### `WOODPECKER_GITLAB_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITLAB_SECRET` from the specified filepath - -### `WOODPECKER_GITLAB_SKIP_VERIFY` - -> Default: `false` - -Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-2.1/30-administration/11-forges/50-bitbucket.md b/docs/versioned_docs/version-2.1/30-administration/11-forges/50-bitbucket.md deleted file mode 100644 index 05912c1ce5..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/11-forges/50-bitbucket.md +++ /dev/null @@ -1,83 +0,0 @@ -# Bitbucket - -Woodpecker comes with built-in support for Bitbucket Cloud. To enable Bitbucket Cloud you should configure the Woodpecker container using the following environment variables: - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_BITBUCKET=true -+ - WOODPECKER_BITBUCKET_CLIENT=... # called "Key" in Bitbucket -+ - WOODPECKER_BITBUCKET_SECRET=... - - woodpecker-agent: - [...] -``` - -## Registration - -You must register an OAuth application at Bitbucket in order to get a key and secret combination for woodpecker. Navigate to your workspace settings and choose `OAuth consumers` from the menu, and finally click `Add Consumer` (the url should be like: `https://bitbucket.org/[your-project-name]/workspace/settings/api`). - -Please set a name and set the `Callback URL` like this: - -```nohighlight -https:///authorize -``` - -![bitbucket oauth setup](bitbucket_oauth.png) - -Please also be sure to check the following permissions: - -```nohighlight -Account: Email, Read -Workspace membership: Read -Projects: Read -Repositories: Read -Pull requests: Read -Webhooks: Read and Write -``` - -![bitbucket permissions](bitbucket_permissions.png) - -## 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. - -### `WOODPECKER_BITBUCKET` - -> Default: `false` - -Enables the Bitbucket driver. - -### `WOODPECKER_BITBUCKET_CLIENT` - -> Default: empty - -Configures the Bitbucket OAuth client key. This is used to authorize access. - -### `WOODPECKER_BITBUCKET_CLIENT_FILE` - -> Default: empty - -Read the value for `WOODPECKER_BITBUCKET_CLIENT` from the specified filepath - -### `WOODPECKER_BITBUCKET_SECRET` - -> Default: empty - -Configures the Bitbucket OAuth client secret. This is used to authorize access. - -### `WOODPECKER_BITBUCKET_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_BITBUCKET_SECRET` from the specified filepath - -## Missing Features - -Merge requests are not currently supported. We are interested in patches to include this functionality. -If you are interested in contributing to Woodpecker and submitting a patch please **contact us** via [Discord](https://discord.gg/fcMQqSMXJy) or [Matrix](https://matrix.to/#/#WoodpeckerCI-Develop:obermui.de). diff --git a/docs/versioned_docs/version-2.1/30-administration/11-forges/_category_.yaml b/docs/versioned_docs/version-2.1/30-administration/11-forges/_category_.yaml deleted file mode 100644 index e240bfc513..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/11-forges/_category_.yaml +++ /dev/null @@ -1,6 +0,0 @@ -label: 'Forges' -collapsible: true -collapsed: true -link: - type: 'doc' - id: 'overview' diff --git a/docs/versioned_docs/version-2.1/30-administration/11-forges/bitbucket_oauth.png b/docs/versioned_docs/version-2.1/30-administration/11-forges/bitbucket_oauth.png deleted file mode 100644 index 17ecf38ab9..0000000000 Binary files a/docs/versioned_docs/version-2.1/30-administration/11-forges/bitbucket_oauth.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/30-administration/11-forges/bitbucket_permissions.png b/docs/versioned_docs/version-2.1/30-administration/11-forges/bitbucket_permissions.png deleted file mode 100644 index 0269f98b0b..0000000000 Binary files a/docs/versioned_docs/version-2.1/30-administration/11-forges/bitbucket_permissions.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/30-administration/11-forges/gitea_oauth.gif b/docs/versioned_docs/version-2.1/30-administration/11-forges/gitea_oauth.gif deleted file mode 100644 index 7478f93856..0000000000 Binary files a/docs/versioned_docs/version-2.1/30-administration/11-forges/gitea_oauth.gif and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/30-administration/11-forges/github_oauth.png b/docs/versioned_docs/version-2.1/30-administration/11-forges/github_oauth.png deleted file mode 100644 index 6b0edef0ff..0000000000 Binary files a/docs/versioned_docs/version-2.1/30-administration/11-forges/github_oauth.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/30-administration/15-agent-config.md b/docs/versioned_docs/version-2.1/30-administration/15-agent-config.md deleted file mode 100644 index ab91a588f5..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/15-agent-config.md +++ /dev/null @@ -1,215 +0,0 @@ -# Agent configuration - -Agents are configured by the command line or environment variables. At the minimum you need the following information: - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-agent: - [...] - volumes: - - woodpecker-agent-config:/etc/woodpecker - environment: -+ - WOODPECKER_SERVER=localhost:9000 -+ - WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here" -``` - -The following are automatically set and can be overridden: - -- WOODPECKER_HOSTNAME if not set, becomes the OS' hostname -- WOODPECKER_MAX_WORKFLOWS if not set, defaults to 1 - -## Workflows per agent - -By default, the maximum workflows that are executed in parallel on an agent is 1. If required, you can add `WOODPECKER_MAX_WORKFLOWS` to increase your parallel processing for an agent. - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-agent: - [...] - environment: - - WOODPECKER_SERVER=localhost:9000 - - WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here" -+ - WOODPECKER_MAX_WORKFLOWS=4 -``` - -## Agent registration - -When the agent starts it connects to the server using the token from `WOODPECKER_AGENT_SECRET`. The server identifies the agent and registers the agent in its database if it wasn't connected before. - -There are two types of tokens to connect an agent to the server: - -### Using system token - -A _system token_ is a token that is used system-wide, e.g. when you set the same token in `WOODPECKER_AGENT_SECRET` on both the server and the agents. - -In that case registration process would be as following: - -1. The first time the agent communicates with the server, it is using the system token -1. The server registers the agent in its database if not done before and generates a unique ID which is then sent back to the agent -1. The agent stores the received ID in a file (configured by `WOODPECKER_AGENT_CONFIG_FILE`) -1. At the following startups, the agent uses the system token **and** its received ID to identify itself to the server - -### Using agent token - -An _agent token_ is a token that is used by only one particular agent. This unique token is applied to the agent by `WOODPECKER_AGENT_SECRET`. - -To get an _agent token_ you have to register the agent manually in the server using the UI: - -1. The administrator registers a new agent manually at `Settings -> Agents -> Add agent` - ![Agent creation](./new-agent-registration.png) - ![Agent created](./new-agent-created.png) -1. The generated token from the previous step has to be provided to the agent using `WOODPECKER_AGENT_SECRET` -1. The agent will connect to the server using the provided token and will update its status in the UI: - ![Agent connected](./new-agent-connected.png) - -## All agent configuration options - -Here is the full list of configuration options and their default variables. - -### `WOODPECKER_SERVER` - -> Default: `localhost:9000` - -Configures gRPC address of the server. - -### `WOODPECKER_USERNAME` - -> Default: `x-oauth-basic` - -The gRPC username. - -### `WOODPECKER_AGENT_SECRET` - -> Default: empty - -A shared secret used by server and agents to authenticate communication. A secret can be generated by `openssl rand -hex 32`. - -### `WOODPECKER_AGENT_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_AGENT_SECRET` from the specified filepath, e.g. `/etc/woodpecker/agent-secret.conf` - -### `WOODPECKER_LOG_LEVEL` - -> Default: empty - -Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty. - -### `WOODPECKER_DEBUG_PRETTY` - -> Default: `false` - -Enable pretty-printed debug output. - -### `WOODPECKER_DEBUG_NOCOLOR` - -> Default: `true` - -Disable colored debug output. - -### `WOODPECKER_HOSTNAME` - -> Default: empty - -Configures the agent hostname. - -### `WOODPECKER_AGENT_CONFIG_FILE` - -> Default: `/etc/woodpecker/agent.conf` - -Configures the path of the agent config file. - -### `WOODPECKER_MAX_WORKFLOWS` - -> Default: `1` - -Configures the number of parallel workflows. - -### `WOODPECKER_FILTER_LABELS` - -> Default: empty - -Configures labels to filter pipeline pick up. Use a list of key-value pairs like `key=value,second-key=*`. `*` can be used as a wildcard. By default, agents provide three additional labels `platform=os/arch`, `hostname=my-agent` and `repo=*` which can be overwritten if needed. To learn how labels work, check out the [pipeline syntax page](../20-usage/20-workflow-syntax.md#labels). - -### `WOODPECKER_HEALTHCHECK` - -> Default: `true` - -Enable healthcheck endpoint. - -### `WOODPECKER_HEALTHCHECK_ADDR` - -> Default: `:3000` - -Configures healthcheck endpoint address. - -### `WOODPECKER_KEEPALIVE_TIME` - -> Default: empty - -After a duration of this time of no activity, the agent pings the server to check if the transport is still alive. - -### `WOODPECKER_KEEPALIVE_TIMEOUT` - -> Default: `20s` - -After pinging for a keepalive check, the agent waits for a duration of this time before closing the connection if no activity. - -### `WOODPECKER_GRPC_SECURE` - -> Default: `false` - -Configures if the connection to `WOODPECKER_SERVER` should be made using a secure transport. - -### `WOODPECKER_GRPC_VERIFY` - -> Default: `true` - -Configures if the gRPC server certificate should be verified, only valid when `WOODPECKER_GRPC_SECURE` is `true`. - -### `WOODPECKER_BACKEND` - -> Default: `auto-detect` - -Configures the backend engine to run pipelines on. Possible values are `auto-detect`, `docker`, `local` or `kubernetes`. - -### WOODPECKER_ADDONS - -> Default: empty - -List of addon files. See [addons](./75-addons/00-overview.md). - -### `WOODPECKER_BACKEND_DOCKER_*` - -See [Docker backend configuration](./22-backends/10-docker.md#configuration) - -### `WOODPECKER_BACKEND_K8S_*` - -See [Kubernetes backend configuration](./22-backends/40-kubernetes.md#general-configuration) - -### `WOODPECKER_BACKEND_LOCAL_*` - -See [Local backend configuration](./22-backends/20-local.md#further-configuration) - -## Advanced Settings - -:::warning -Only change these If you know what you do. -::: - -### `WOODPECKER_CONNECT_RETRY_COUNT` - -> Default: `5` - -Configures number of times agent retries to connect to the server. - -### `WOODPECKER_CONNECT_RETRY_DELAY` - -> Default: `2s` - -Configures delay between agent connection retries to the server. diff --git a/docs/versioned_docs/version-2.1/30-administration/22-backends/10-docker.md b/docs/versioned_docs/version-2.1/30-administration/22-backends/10-docker.md deleted file mode 100644 index 57fe7bb919..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/22-backends/10-docker.md +++ /dev/null @@ -1,62 +0,0 @@ -# Docker backend - -This is the original backend used with Woodpecker. The docker backend executes each step inside a separate container started on the agent. - -## Configuration - -### `WOODPECKER_BACKEND_DOCKER_NETWORK` - -> Default: empty - -Set to the name of an existing network which will be attached to all your pipeline containers (steps). Please be careful as this allows the containers of different pipelines to access each other! - -### `WOODPECKER_BACKEND_DOCKER_ENABLE_IPV6` - -> Default: `false` - -Enable IPv6 for the networks used by pipeline containers (steps). Make sure you configured your docker daemon to support IPv6. - -### `WOODPECKER_BACKEND_DOCKER_VOLUMES` - -> Default: empty - -List of default volumes separated by comma to be mounted to all pipeline containers (steps). For example to use custom CA -certificates installed on host and host timezone use `/etc/ssl/certs:/etc/ssl/certs:ro,/etc/timezone:/etc/timezone`. - -## Docker credentials - -Woodpecker supports [Docker credentials](https://github.com/docker/docker-credential-helpers) to securely store registry credentials. Install your corresponding credential helper and configure it in your Docker config file passed via [`WOODPECKER_DOCKER_CONFIG`](../10-server-config.md#woodpecker_docker_config). - -To add your credential helper to the Woodpecker server container you could use the following code to build a custom image: - -```dockerfile -FROM woodpeckerci/woodpecker-server:latest-alpine - -RUN apk add -U --no-cache docker-credential-ecr-login -``` - -## Podman support - -While the agent was developed with Docker/Moby, Podman can also be used by setting the environment variable `DOCKER_HOST` to point to the Podman socket. In order to work without workarounds, Podman 4.0 (or above) is required. - -## Image Cleanup - -The agent **will not** automatically remove images from the host. This task should be managed by the host system. For example, you can use a cron job to periodically do clean-up tasks for the CI runner. - -:::danger - -The following commands **are destructive** and **irreversible** it is highly recommended that you test these commands on your system before running them in production via a cron job or other automation. - -::: - -### Remove all unused images - -```bash -docker image rm $(docker images --filter "dangling=true" -q --no-trunc) -``` - -### Remove Woodpecker Volumes - -```bash -docker volume rm $(docker volume ls --filter name=^wp_* --filter dangling=true -q) -``` diff --git a/docs/versioned_docs/version-2.1/30-administration/22-backends/20-local.md b/docs/versioned_docs/version-2.1/30-administration/22-backends/20-local.md deleted file mode 100644 index fb1f5f1633..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/22-backends/20-local.md +++ /dev/null @@ -1,128 +0,0 @@ -# Local backend - -:::danger -The local backend will execute the pipelines on the local system without any isolation of any kind. -::: - -:::note -This backend is still pretty new and cannot be treated as stable. Its -implementation and configuration can change at any time. -::: - -Since the code runs directly in the same context as the agent (same user, same -filesystem), a malicious pipeline could be used to access the agent -configuration especially the `WOODPECKER_AGENT_SECRET` variable. - -It is recommended to use this backend only for private setup where the code and -pipeline can be trusted. You shouldn't use it for a public facing CI where -anyone can submit code or add new repositories. You shouldn't execute the agent -as a privileged user (root). - -The local backend will use a random directory in $TMPDIR to store the cloned -code and execute commands. - -In order to use this backend, you need to download (or build) the -[binary](https://github.com/woodpecker-ci/woodpecker/releases/latest) of the -agent, configure it and run it on the host machine. - -## Configuration - -### Server - -Enable connection to the server from the outside of the docker environment by -exposing the port 9000: - -```yaml title="docker-compose.yml" for the server -version: '3' - -services: - woodpecker-server: - [...] - ports: - - 9000:9000 - [...] - environment: - - [...] -``` - -### Agent - -You can use the `.env` file to store environmental variables for configuration. -At the minimum you need the following information: - -```ini -# .env for the agent -WOODPECKER_AGENT_SECRET=replace_with_your_server_secret -WOODPECKER_SERVER=replace_with_your_server_address:9000 -``` - -## Running the agent - -Start the agent from the directory with the `.env` file: - -`woodpecker-agent` - -:::note -When using the `local` backend, the -[plugin-git](https://github.com/woodpecker-ci/plugin-git) binary must be in -your `$PATH` for the default clone step to work. If not, you can still write a -manual clone step. -::: - -## Further configuration - -### Specify the shell to be used for a pipeline step - -The `image` entry is used to specify the shell, such as Bash or Fish, that is -used to run the commands. - -```yaml title=".woodpecker.yml" -steps: - build: - image: bash - commands: [...] -``` - -### Plugins as Executable Binaries - -```yaml -steps: - build: - image: /usr/bin/tree -``` - -If no commands are provided, we treat them as plugins in the usual manner. -In the context of the local backend, plugins are simply executable binaries, which can be located using their name if they are listed in `$PATH`, or through an absolute path. - -### Using labels to filter tasks - -You can use the [agent configuration options](../15-agent-config.md#woodpecker_filter_labels) -and the [pipeline syntax](../../20-usage/20-workflow-syntax.md#labels) to only run certain -pipelines on certain agents. Example: - -Define a `label` `type` with value `exec` for a particular agent: - -```ini -# .env for the agent - -WOODPECKER_FILTER_LABELS=type=exec -``` - -Then, use this `label` `type` with value `exec` in the pipeline definition, to -only run on this agent: - -```yaml title=".woodpecker.yml" -labels: - type: exec - -steps: [...] -``` - -### Change temp directory - -We use the default temp directory to create folders for workflows. -This directory can be changed by: - -```env -WOODPECKER_BACKEND_LOCAL_TEMP_DIR=/some/other/dir -``` diff --git a/docs/versioned_docs/version-2.1/30-administration/22-backends/40-kubernetes.md b/docs/versioned_docs/version-2.1/30-administration/22-backends/40-kubernetes.md deleted file mode 100644 index 7efb478c84..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/22-backends/40-kubernetes.md +++ /dev/null @@ -1,215 +0,0 @@ -# Kubernetes backend - -The kubernetes backend executes steps inside standalone pods. A temporary PVC is created for the lifetime of the pipeline to transfer files between steps. - -## General Configuration - -These env vars can be set in the `env:` sections of both `server` and `agent`. -They do not need to be set for both but only for the part to which it is relevant to. - -```yaml -server: - env: - WOODPECKER_SESSION_EXPIRES: "300h" - [...] - -agent: - env: - [...] -``` - -- `WOODPECKER_BACKEND_K8S_NAMESPACE` (default: `woodpecker`) - - The namespace to create worker pods in. - -- `WOODPECKER_BACKEND_K8S_VOLUME_SIZE` (default: `10G`) - - The volume size of the pipeline volume. - -- `WOODPECKER_BACKEND_K8S_STORAGE_CLASS` (default: empty) - - The storage class to use for the pipeline volume. - -- `WOODPECKER_BACKEND_K8S_STORAGE_RWX` (default: `true`) - - Determines if `RWX` should be used for the pipeline volume's [access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes). If false, `RWO` is used instead. - -- `WOODPECKER_BACKEND_K8S_POD_LABELS` (default: empty) - - Additional labels to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-label":"test-value"}`. - -- `WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS` (default: empty) - - Additional annotations to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-annotation":"test-value"}`. - -- `WOODPECKER_BACKEND_K8S_SECCTX_NONROOT` (default: `false`) - - Determines if containers must be required to run as non-root users. - -- `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES` (default: empty) - - Secret names to pull images from private repositories. - -## Job specific configuration - -### Resources - -The kubernetes backend also allows for specifying requests and limits on a per-step basic, most commonly for CPU and memory. -We recommend to add a `resources` definition to all steps to ensure efficient scheduling. - -Here is an example definition with an arbitrary `resources` definition below the `backend_options` section: - -```yaml -steps: - 'My kubernetes step': - image: alpine - commands: - - echo "Hello world" - backend_options: - kubernetes: - resources: - requests: - memory: 200Mi - cpu: 100m - limits: - memory: 400Mi - cpu: 1000m -``` - -### serviceAccountName - -Specify the name of the ServiceAccount which the build pod will mount. This serviceAccount must be created externally. -See the [kubernetes documentation](https://kubernetes.io/docs/concepts/security/service-accounts/) for more information on using serviceAccounts. - -### nodeSelector - -Specifies the label which is used to select the node on which the job will be executed. - -Labels defined here will be appended to a list which already contains `"kubernetes.io/arch"`. -By default `"kubernetes.io/arch"` is inferred from the agents' platform. One can override it by setting that label in the `nodeSelector` section of the `backend_options`. -Without a manual overwrite, builds will be randomly assigned to the runners and inherit their respective architectures. - -To overwrite this, one needs to set the label in the `nodeSelector` section of the `backend_options`. -A practical example for this is when running a matrix-build and delegating specific elements of the matrix to run on a specific architecture. -In this case, one must define an arbitrary key in the matrix section of the respective matrix element: - -```yaml -matrix: - include: - - NAME: runner1 - ARCH: arm64 -``` - -And then overwrite the `nodeSelector` in the `backend_options` section of the step(s) using the name of the respective env var: - -```yaml -[...] - backend_options: - kubernetes: - nodeSelector: - kubernetes.io/arch: "${ARCH}" -``` - -### 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. -See the [kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for more information on using tolerations. - -Example pipeline configuration: - -```yaml -steps: - build: - image: golang - commands: - - go get - - go build - - go test - backend_options: - kubernetes: - serviceAccountName: 'my-service-account' - resources: - requests: - memory: 128Mi - cpu: 1000m - limits: - memory: 256Mi - nodeSelector: - beta.kubernetes.io/instance-type: p3.8xlarge - tolerations: - - key: 'key1' - operator: 'Equal' - value: 'value1' - effect: 'NoSchedule' - tolerationSeconds: 3600 -``` - -### Volumes - -To mount volumes a persistent volume (PV) and persistent volume claim (PVC) are needed on the cluster which can be referenced in steps via the `volume:` option. -Assuming a PVC named "woodpecker-cache" exists, it can be referenced as follows in a step: - -```yaml -steps: - "Restore Cache": - image: meltwater/drone-cache - volumes: - - woodpecker-cache:/woodpecker/src/cache - settings: - mount: - - "woodpecker-cache" - [...] -``` - -### `securityContext` - -Use the following configuration to set the `securityContext` for the pod/container running a given pipeline step: - -```yaml -steps: - test: - image: alpine - commands: - - echo Hello world - backend_options: - kubernetes: - securityContext: - runAsUser: 999 - runAsGroup: 999 - privileged: true - [...] -``` - -Note that the `backend_options.kubernetes.securityContext` object allows you to set both pod and container level security context options in one object. -By default, the properties will be set at the pod level. Properties that are only supported on the container level will be set there instead. So, the -configuration shown above will result in something like the following pod spec: - -```yaml -kind: Pod -spec: - securityContext: - runAsUser: 999 - runAsGroup: 999 - containers: - - name: wp-01hcd83q7be5ymh89k5accn3k6-0-step-0 - image: alpine - securityContext: - privileged: true - [...] -``` - -See the [kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for more information on using `securityContext`. - -## Tips and tricks - -### CRI-O - -CRI-O users currently need to configure the workspace for all workflows in order for them to run correctly. Add the following at the beginning of your configuration: - -```yaml -workspace: - base: '/woodpecker' - path: '/' -``` - -See [this issue](https://github.com/woodpecker-ci/woodpecker/issues/2510) for more details. diff --git a/docs/versioned_docs/version-2.1/30-administration/22-backends/_category_.yaml b/docs/versioned_docs/version-2.1/30-administration/22-backends/_category_.yaml deleted file mode 100644 index 556444f02f..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/22-backends/_category_.yaml +++ /dev/null @@ -1,4 +0,0 @@ -label: 'Backends' -# position: 3 -collapsible: true -collapsed: true diff --git a/docs/versioned_docs/version-2.1/30-administration/30-database.md b/docs/versioned_docs/version-2.1/30-administration/30-database.md deleted file mode 100644 index 1da4bc1854..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/30-database.md +++ /dev/null @@ -1,65 +0,0 @@ -# Databases - -The default database engine of Woodpecker is an embedded SQLite database which requires zero installation or configuration. But you can replace it with a MySQL/MariaDB or Postgres database. - -## Configure SQLite - -By default Woodpecker uses a SQLite database stored under `/var/lib/woodpecker/`. You can mount a [data volume](https://docs.docker.com/storage/volumes/#create-and-manage-volumes) to persist the SQLite database. - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] -+ volumes: -+ - woodpecker-server-data:/var/lib/woodpecker/ -``` - -## Configure MySQL/MariaDB - -The below example demonstrates MySQL database configuration. See the official driver [documentation](https://github.com/go-sql-driver/mysql#dsn-data-source-name) for configuration options and examples. -The minimum version of MySQL/MariaDB required is determined by the `go-sql-driver/mysql` - see [it's README](https://github.com/go-sql-driver/mysql#requirements) for more information. - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - environment: -+ - WOODPECKER_DATABASE_DRIVER=mysql -+ - WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true -``` - -## Configure Postgres - -The below example demonstrates Postgres database configuration. See the official driver [documentation](https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING) for configuration options and examples. -Please use Postgres versions equal or higher than **11**. - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - environment: -+ - WOODPECKER_DATABASE_DRIVER=postgres -+ - WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/postgres?sslmode=disable -``` - -## Database Creation - -Woodpecker does not create your database automatically. If you are using the MySQL or Postgres driver you will need to manually create your database using `CREATE DATABASE` - -## Database Migration - -Woodpecker automatically handles database migration, including the initial creation of tables and indexes. New versions of Woodpecker will automatically upgrade the database unless otherwise specified in the release notes. - -## Database Backups - -Woodpecker does not perform database backups. This should be handled by separate third party tools provided by your database vendor of choice. - -## Database Archiving - -Woodpecker does not perform data archival; it considered out-of-scope for the project. Woodpecker is rather conservative with the amount of data it stores, however, you should expect the database logs to grow the size of your database considerably. diff --git a/docs/versioned_docs/version-2.1/30-administration/40-encryption.md b/docs/versioned_docs/version-2.1/30-administration/40-encryption.md deleted file mode 100644 index f630711d85..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/40-encryption.md +++ /dev/null @@ -1,83 +0,0 @@ -# Secrets encryption - -:::danger -Secrets encryption is currently broken and therefore disabled by default. It will be fixed in an upcoming release. - -Check: - -- and -- - -::: - -By default, Woodpecker does not encrypt secrets in its database. You can enable encryption -using simple AES key or more advanced [Google TINK](https://developers.google.com/tink) encryption. - -## Common - -### Enabling secrets encryption - -To enable secrets encryption and encrypt all existing secrets in database set -`WOODPECKER_ENCRYPTION_KEY`, `WOODPECKER_ENCRYPTION_KEY_FILE` or `WOODPECKER_ENCRYPTION_TINK_KEYSET_PATH` environment -variable depending on encryption method of your choice. - -After encryption is enabled you will be unable to start Woodpecker server without providing valid encryption key! - -### Disabling encryption and decrypting all secrets - -To disable secrets encryption and decrypt database you need to start server with valid -`WOODPECKER_ENCRYPTION_KEY` or `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE` environment variable set depending on -enabled encryption method, and `WOODPECKER_ENCRYPTION_DISABLE` set to true. - -After secrets was decrypted server will proceed working in unencrypted mode. You will not need to use "disable encryption" -variable or encryption keys to start server anymore. - -## AES - -Simple AES encryption. - -### Configuration - -You can manage encryption on server using these environment variables: - -- `WOODPECKER_ENCRYPTION_KEY` - encryption key -- `WOODPECKER_ENCRYPTION_KEY_FILE` - file to read encryption key from -- `WOODPECKER_ENCRYPTION_DISABLE` - disable encryption flag used to decrypt all data on server - -## TINK - -TINK uses AEAD encryption instead of simple AES and supports key rotation. - -### Configuration - -You can manage encryption on server using these two environment variables: - -- `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE` - keyset filepath -- `WOODPECKER_ENCRYPTION_DISABLE` - disable encryption flag used to decrypt all data on server - -### Encryption keys - -You will need plaintext AEAD-compatible Google TINK keyset to encrypt your data. - -To generate it and then rotate keys if needed, install `tinkey`([installation guide](https://developers.google.com/tink/install-tinkey)) - -Keyset contains one or more keys, used to encrypt or decrypt your data, and primary key ID, used to determine which key -to use while encrypting new data. - -Keyset generation example: - -```bash -tinkey create-keyset --key-template AES256_GCM --out-format json --out keyset.json -``` - -### Key rotation - -Use `tinkey` to rotate encryption keys in your existing keyset: - -```bash -tinkey rotate-keyset --in keyset_v1.json --out keyset_v2.json --key-template AES256_GCM -``` - -Then you just need to replace server keyset file with the new one. At the moment server detects new encryption -keyset it will re-encrypt all existing secrets with the new key, so you will be unable to start server with previous -keyset anymore. diff --git a/docs/versioned_docs/version-2.1/30-administration/60-ssl.md b/docs/versioned_docs/version-2.1/30-administration/60-ssl.md deleted file mode 100644 index 8b6a3315e3..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/60-ssl.md +++ /dev/null @@ -1,124 +0,0 @@ -# SSL - -Woodpecker supports two ways of enabling SSL communication. You can either use Let's Encrypt to get automated SSL support with -renewal or provide your own SSL certificates. - -## Let's Encrypt - -Woodpecker supports automated SSL configuration and updates using Let's Encrypt. - -You can enable Let's Encrypt by making the following modifications to your server configuration: - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - ports: -+ - 80:80 -+ - 443:443 - - 9000:9000 - environment: - - [...] -+ - WOODPECKER_LETS_ENCRYPT=true -+ - WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld -``` - -Note that Woodpecker uses the hostname from the `WOODPECKER_HOST` environment variable when requesting certificates. For example, if `WOODPECKER_HOST=https://example.com` is set the certificate is requested for `example.com`. To receive emails before certificates expire Let's Encrypt requires an email address. You can set it with `WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld`. - -The SSL certificates are stored in `$HOME/.local/share/certmagic` for binary versions of Woodpecker and in `/var/lib/woodpecker` for the Container versions of it. You can set a custom path by setting `XDG_DATA_HOME` if required. - -> Once enabled you can visit the Woodpecker UI with http and the HTTPS address. HTTP will be redirected to HTTPS. - -### Certificate Cache - -Woodpecker writes the certificates to `/var/lib/woodpecker/certmagic/`. - -### Certificate Updates - -Woodpecker uses the official Go acme library which will handle certificate upgrades. There should be no addition configuration or management required. - -## SSL with own certificates - -Woodpecker supports SSL configuration by mounting certificates into your container. - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - ports: -+ - 80:80 -+ - 443:443 - - 9000:9000 - volumes: -+ - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt -+ - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key - environment: - - [...] -+ - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt -+ - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key -``` - -Update your configuration to expose the following ports: - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - ports: -+ - 80:80 -+ - 443:443 - - 9000:9000 -``` - -Update your configuration to mount your certificate and key: - -```diff title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - ports: - - 80:80 - - 443:443 - - 9000:9000 - volumes: -+ - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt -+ - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key -``` - -Update your configuration to provide the paths of your certificate and key: - -```yaml title="docker-compose.yml" -version: '3' - -services: - woodpecker-server: - [...] - ports: - - 80:80 - - 443:443 - - 9000:9000 - volumes: - - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt - - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key - environment: -+ - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt -+ - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key -``` - -### Certificate Chain - -The most common problem encountered is providing a certificate file without the intermediate chain. - -> LoadX509KeyPair reads and parses a public/private key pair from a pair of files. The files must contain PEM encoded data. The certificate file may contain intermediate certificates following the leaf certificate to form a certificate chain. - -### Certificate Errors - -SSL support is provided using the [ListenAndServeTLS](https://golang.org/pkg/net/http/#ListenAndServeTLS) function from the Go standard library. If you receive certificate errors or warnings please examine your configuration more closely. diff --git a/docs/versioned_docs/version-2.1/30-administration/70-proxy.md b/docs/versioned_docs/version-2.1/30-administration/70-proxy.md deleted file mode 100644 index b39b87a982..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/70-proxy.md +++ /dev/null @@ -1,201 +0,0 @@ -# Proxy - -## Apache - -This guide provides a brief overview for installing Woodpecker server behind the Apache2 web-server. This is an example configuration: - -```apacheconf -ProxyPreserveHost On - -RequestHeader set X-Forwarded-Proto "https" - -ProxyPass / http://127.0.0.1:8000/ -ProxyPassReverse / http://127.0.0.1:8000/ -``` - -You must have the below Apache modules installed. - -```nohighlight -a2enmod proxy -a2enmod proxy_http -``` - -You must configure Apache to set `X-Forwarded-Proto` when using https. - -```diff -ProxyPreserveHost On - -+RequestHeader set X-Forwarded-Proto "https" - -ProxyPass / http://127.0.0.1:8000/ -ProxyPassReverse / http://127.0.0.1:8000/ -``` - -## Nginx - -This guide provides a basic overview for installing Woodpecker server behind the Nginx web-server. For more advanced configuration options please consult the official Nginx [documentation](https://www.nginx.com/resources/admin-guide/). - -Example configuration: - -```nginx -server { - listen 80; - server_name woodpecker.example.com; - - location / { - proxy_set_header X-Forwarded-For $remote_addr; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header Host $http_host; - - proxy_pass http://127.0.0.1:8000; - proxy_redirect off; - proxy_http_version 1.1; - proxy_buffering off; - - chunked_transfer_encoding off; - } -} -``` - -You must configure the proxy to set `X-Forwarded` proxy headers: - -```diff -server { - listen 80; - server_name woodpecker.example.com; - - location / { -+ proxy_set_header X-Forwarded-For $remote_addr; -+ proxy_set_header X-Forwarded-Proto $scheme; - - proxy_pass http://127.0.0.1:8000; - proxy_redirect off; - proxy_http_version 1.1; - proxy_buffering off; - - chunked_transfer_encoding off; - } -} -``` - -## Caddy - -This guide provides a brief overview for installing Woodpecker server behind the [Caddy web-server](https://caddyserver.com/). This is an example caddyfile proxy configuration: - -```caddy -# expose WebUI and API -woodpecker.example.com { - reverse_proxy woodpecker-server:8000 -} - -# expose gRPC -woodpeckeragent.example.com { - reverse_proxy h2c://woodpecker-server:9000 -} -``` - -:::note -Above configuration shows how to create reverse-proxies for web and agent communication. If your agent uses SSL do not forget to enable [WOODPECKER_GRPC_SECURE](./15-agent-config.md#woodpecker_grpc_secure). -::: - -## Tunnelmole - -[Tunnelmole](https://github.com/robbie-cahill/tunnelmole-client) is an open source tunneling tool. - -Start by [installing tunnelmole](https://github.com/robbie-cahill/tunnelmole-client#installation). - -After the installation, run the following command to start tunnelmole: - -```bash -tmole 8000 -``` - -It will start a tunnel and will give a response like this: - -```bash -âžœ ~ tmole 8000 -http://bvdo5f-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:8000 -https://bvdo5f-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:8000 -``` - -Set `WOODPECKER_HOST` (for example in `docker-compose.yml`) to the Tunnelmole URL (`xxx.tunnelmole.net`) and start the server. - -## Ngrok - -[Ngrok](https://ngrok.com/) is a popular closed source tunnelling tool. After installing ngrok, open a new console and run the following command: - -```bash -ngrok http 8000 -``` - -Set `WOODPECKER_HOST` (for example in `docker-compose.yml`) to the ngrok URL (usually xxx.ngrok.io) and start the server. - -## Traefik - -To install the Woodpecker server behind a [Traefik](https://traefik.io/) load balancer, you must expose both the `http` and the `gRPC` ports. Here is a comprehensive example, considering you are running Traefik with docker swarm and want to do TLS termination and automatic redirection from http to https. - -```yaml -version: '3.8' - -services: - server: - image: woodpeckerci/woodpecker-server:latest - environment: - - WOODPECKER_OPEN=true - - WOODPECKER_ADMIN=your_admin_user - # other settings ... - - networks: - - dmz # externally defined network, so that traefik can connect to the server - volumes: - - woodpecker-server-data:/var/lib/woodpecker/ - - deploy: - labels: - - traefik.enable=true - - # web server - - traefik.http.services.woodpecker-service.loadbalancer.server.port=8000 - - - traefik.http.routers.woodpecker-secure.rule=Host(`cd.yourdomain.com`) - - traefik.http.routers.woodpecker-secure.tls=true - - traefik.http.routers.woodpecker-secure.tls.certresolver=letsencrypt - - traefik.http.routers.woodpecker-secure.entrypoints=websecure - - traefik.http.routers.woodpecker-secure.service=woodpecker-service - - - traefik.http.routers.woodpecker.rule=Host(`cd.yourdomain.com`) - - traefik.http.routers.woodpecker.entrypoints=web - - traefik.http.routers.woodpecker.service=woodpecker-service - - - traefik.http.middlewares.woodpecker-redirect.redirectscheme.scheme=https - - traefik.http.middlewares.woodpecker-redirect.redirectscheme.permanent=true - - traefik.http.routers.woodpecker.middlewares=woodpecker-redirect@docker - - # gRPC service - - traefik.http.services.woodpecker-grpc.loadbalancer.server.port=9000 - - traefik.http.services.woodpecker-grpc.loadbalancer.server.scheme=h2c - - - traefik.http.routers.woodpecker-grpc-secure.rule=Host(`woodpecker-grpc.yourdomain.com`) - - traefik.http.routers.woodpecker-grpc-secure.tls=true - - traefik.http.routers.woodpecker-grpc-secure.tls.certresolver=letsencrypt - - traefik.http.routers.woodpecker-grpc-secure.entrypoints=websecure - - traefik.http.routers.woodpecker-grpc-secure.service=woodpecker-grpc - - - traefik.http.routers.woodpecker-grpc.rule=Host(`woodpecker-grpc.yourdomain.com`) - - traefik.http.routers.woodpecker-grpc.entrypoints=web - - traefik.http.routers.woodpecker-grpc.service=woodpecker-grpc - - - traefik.http.middlewares.woodpecker-grpc-redirect.redirectscheme.scheme=https - - traefik.http.middlewares.woodpecker-grpc-redirect.redirectscheme.permanent=true - - traefik.http.routers.woodpecker-grpc.middlewares=woodpecker-grpc-redirect@docker - -volumes: - woodpecker-server-data: - driver: local - -networks: - dmz: - external: true -``` - -You should pass `WOODPECKER_GRPC_SECURE=true` and `WOODPECKER_GRPC_VERIFY=true` to your agent when using this configuration. diff --git a/docs/versioned_docs/version-2.1/30-administration/75-addons/00-overview.md b/docs/versioned_docs/version-2.1/30-administration/75-addons/00-overview.md deleted file mode 100644 index 615d116cae..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/75-addons/00-overview.md +++ /dev/null @@ -1,52 +0,0 @@ -# Addons - -:::warning -Addons are still experimental. Their implementation can change and break at any time. -::: - -:::danger -You need to trust the author of the addons you use. Depending on their type, addons can access forge authentication codes, your secrets or other sensitive information. -::: - -To adapt Woodpecker to your needs beyond the [configuration](../10-server-config.md), Woodpecker has its own **addon** system, built ontop of [Go's internal plugin system](https://go.dev/pkg/plugin). - -Addons can be used for: - -- Forges -- Agent backends -- Config services -- Secret services -- Environment services -- Registry services - -## Restrictions - -Addons are restricted by how Go plugins work. This includes the following restrictions: - -- only supported on Linux, FreeBSD and macOS -- addons must have been built for the correct Woodpecker version. If an addon is not provided specifically for this version, you likely won't be able to use it. - -## Usage - -To use an addon, download the addon version built for your Woodpecker version. Then, you can add the following to your configuration: - -```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: -+ - WOODPECKER_ADDONS=/path/to/your/addon/file.so -``` - -In case you run Woodpecker as container, you probably want to mount the addon binaries to `/opt/addons/`. - -You can list multiple addons, Woodpecker will automatically determine their type. If you specify multiple addons with the same type, only the first one will be used. - -Using an addon always overwrites Woodpecker's internal setup. This means, that a forge addon will be used if specified, no matter what's configured for the forges natively supported by Woodpecker. - -### Bug reports - -If you experience bugs, please check which component has the issue. If it's the addon, **do not raise an issue in the main repository**, but rather use the separate addon repositories. To check which component is responsible for the bug, look at the logs. Logs from addons are marked with a special field `addon` containing their addon file name. diff --git a/docs/versioned_docs/version-2.1/30-administration/75-addons/20-creating-addons.md b/docs/versioned_docs/version-2.1/30-administration/75-addons/20-creating-addons.md deleted file mode 100644 index 702443fee5..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/75-addons/20-creating-addons.md +++ /dev/null @@ -1,92 +0,0 @@ -# Creating addons - -Addons are written in Go. - -## Writing your code - -An addon consists of two variables/functions in Go. - -1. The `Type` variable. Specifies the type of the addon and must be directly accessed from `shared/addons/types/types.go`. -2. The `Addon` function which is the main point of your addon. - This function takes two arguments: - - 1. The zerolog logger you should use to log errors, warnings etc. - 2. A slice of strings with the environment variables used as configuration. - - It returns two values: - - 1. The actual addon. For type reference see [table below](#return-types). - 2. An error. If this error is not `nil`, Woodpecker exits. - -Directly import Woodpecker's Go package (`go.woodpecker-ci.org/woodpecker/woodpecker/v2`) and use the interfaces and types defined there. - -### Return types - -| Addon type | Return type | -| -------------------- | -------------------------------------------------------------------------------- | -| `Forge` | `"go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/forge".Forge` | -| `Backend` | `"go.woodpecker-ci.org/woodpecker/woodpecker/v2/pipeline/backend/types".Backend` | -| `ConfigService` | `"go.woodpecker-ci.org/woodpecker/v2/server/plugins/config".ConfigService` | -| `SecretService` | `"go.woodpecker-ci.org/woodpecker/v2/server/model".SecretService` | -| `EnvironmentService` | `"go.woodpecker-ci.org/woodpecker/v2/server/model".EnvironmentService` | -| `RegistryService` | `"go.woodpecker-ci.org/woodpecker/v2/server/model".RegistryService` | - -## Compiling - -After you write your addon code, compile your addon: - -```sh -go build -buildmode plugin -``` - -The output file is your addon which is now ready to be used. - -## Restrictions - -Addons must directly depend on Woodpecker's core (`go.woodpecker-ci.org/woodpecker/woodpecker/v2`). -The addon must have been built with **excatly the same code** as the Woodpecker instance you'd like to use it on. This means: If you build your addon with a specific commit from Woodpecker `next`, you can likely only use it with the Woodpecker version compiled from this commit. -Also, if you change something inside of Woodpecker without committing, it might fail because you need to recompile your addon with this code first. - -In addition to this, addons are only supported on Linux, FreeBSD and macOS. - -:::info -It is recommended to at least support the latest released version of Woodpecker. -::: - -### Compile for different versions - -As long as there are no changes to Woodpecker's interfaces or they are backwards-compatible, you can easily compile the addon for multiple version by changing the version of `go.woodpecker-ci.org/woodpecker/woodpecker/v2` using `go get` before compiling. - -## Logging - -The entrypoint receives a `zerolog.Logger` as input. **Do not use any other logging solution.** This logger follows the configuration of the Woodpecker instance and adds a special field `addon` to the log entries which allows users to find out which component is writing the log messages. - -## Example structure - -```go -package main - -import ( - "context" - "net/http" - - "github.com/rs/zerolog" - "go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/forge" - forge_types "go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/forge/types" - "go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/model" - addon_types "go.woodpecker-ci.org/woodpecker/woodpecker/v2/shared/addon/types" -) - -var Type = addon_types.TypeForge - -func Addon(logger zerolog.Logger, env []string) (forge.Forge, error) { - logger.Info().Msg("hello world from addon") - return &config{l: logger}, nil -} - -type config struct { - l zerolog.Logger -} - -// ... in this case, `config` must implement `forge.Forge`. You must directly use Woodpecker's packages - see imports above. -``` diff --git a/docs/versioned_docs/version-2.1/30-administration/75-addons/_category_.yaml b/docs/versioned_docs/version-2.1/30-administration/75-addons/_category_.yaml deleted file mode 100644 index 4cd7380c57..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/75-addons/_category_.yaml +++ /dev/null @@ -1,6 +0,0 @@ -label: 'Addons' -collapsible: true -collapsed: true -link: - type: 'doc' - id: 'overview' diff --git a/docs/versioned_docs/version-2.1/30-administration/80-autoscaler.md b/docs/versioned_docs/version-2.1/30-administration/80-autoscaler.md deleted file mode 100644 index 86e92d1a24..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/80-autoscaler.md +++ /dev/null @@ -1,37 +0,0 @@ -# Autoscaler - -If your would like dynamically scale your agents with the load, you can use [our autoscaler](https://github.com/woodpecker-ci/autoscaler). - -Please note that the autoscaler is not feature-complete yet. You can follow the progress [here](https://github.com/woodpecker-ci/autoscaler#roadmap). - -## Setup - -### docker-compose - -If you are using docker-compose you can add the following to your docker-compose.yml file: - -```yaml -version: '3' - -services: - woodpecker-server: - image: woodpeckerci/woodpecker-server:next - [...] - - woodpecker-autoscaler: - image: woodpeckerci/autoscaler:next - restart: always - depends_on: - - woodpecker-server - environment: - - WOODPECKER_SERVER=https://your-woodpecker-server.tld # the url of your woodpecker server / could also be a public url - - WOODPECKER_TOKEN=${WOODPECKER_TOKEN} # the api token you can get from the UI https://your-woodpecker-server.tld/user - - WOODPECKER_MIN_AGENTS=0 - - WOODPECKER_MAX_AGENTS=3 - - WOODPECKER_WORKFLOWS_PER_AGENT=2 # the number of workflows each agent can run at the same time - - WOODEPCKER_GRPC_ADDR=https://grpc.your-woodpecker-server.tld # the grpc address of your woodpecker server, publicly accessible from the agents - - WOODEPCKER_GRPC_SECURE=true - - WOODPECKER_AGENT_ENV= # optional environment variables to pass to the agents - - WOODPECKER_PROVIDER=hetznercloud # set the provider, you can find all the available ones down below - - WOODPECKER_HETZNERCLOUD_API_TOKEN=${WOODPECKER_HETZNERCLOUD_API_TOKEN} # your api token for the Hetzner cloud -``` diff --git a/docs/versioned_docs/version-2.1/30-administration/90-prometheus.md b/docs/versioned_docs/version-2.1/30-administration/90-prometheus.md deleted file mode 100644 index d3cfc3b376..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/90-prometheus.md +++ /dev/null @@ -1,85 +0,0 @@ -# Prometheus - -Woodpecker is compatible with Prometheus and exposes a `/metrics` endpoint if the environment variable `WOODPECKER_PROMETHEUS_AUTH_TOKEN` is set. Please note that access to the metrics endpoint is restricted and requires the authorization token from the environment variable mentioned above. - -```yaml -global: - scrape_interval: 60s - -scrape_configs: - - job_name: 'woodpecker' - bearer_token: dummyToken... - - static_configs: - - targets: ['woodpecker.domain.com'] -``` - -## Authorization - -An administrator will need to generate a user API token and configure in the Prometheus configuration file as a bearer token. Please see the following example: - -```diff -global: - scrape_interval: 60s - -scrape_configs: - - job_name: 'woodpecker' -+ bearer_token: dummyToken... - - static_configs: - - targets: ['woodpecker.domain.com'] -``` - -As an alternative, the token can also be read from a file: - -```diff -global: - scrape_interval: 60s - -scrape_configs: - - job_name: 'woodpecker' -+ bearer_token_file: /etc/secrets/woodpecker-monitoring-token - - static_configs: - - targets: ['woodpecker.domain.com'] -``` - -## Unauthenticated Access - -Alternatively, the unprotected `/metrics` endpoint might be exposed on the internal port (Port is configurable via the `WOODPECKER_METRICS_SERVER_ADDR` environment variable, e.g. `:9001`). - -## Metric Reference - -List of Prometheus metrics specific to Woodpecker: - -```yaml -# HELP woodpecker_pipeline_count Pipeline count. -# TYPE woodpecker_pipeline_count counter -woodpecker_pipeline_count{branch="main",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3 -woodpecker_pipeline_count{branch="mkdocs",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3 -# HELP woodpecker_pipeline_time Build time. -# TYPE woodpecker_pipeline_time gauge -woodpecker_pipeline_time{branch="main",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 116 -woodpecker_pipeline_time{branch="mkdocs",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 155 -# HELP woodpecker_pipeline_total_count Total number of builds. -# TYPE woodpecker_pipeline_total_count gauge -woodpecker_pipeline_total_count 1025 -# HELP woodpecker_pending_steps Total number of pending pipeline steps. -# TYPE woodpecker_pending_steps gauge -woodpecker_pending_steps 0 -# HELP woodpecker_repo_count Total number of repos. -# TYPE woodpecker_repo_count gauge -woodpecker_repo_count 9 -# HELP woodpecker_running_steps Total number of running pipeline steps. -# TYPE woodpecker_running_steps gauge -woodpecker_running_steps 0 -# HELP woodpecker_user_count Total number of users. -# TYPE woodpecker_user_count gauge -woodpecker_user_count 1 -# HELP woodpecker_waiting_steps Total number of pipeline waiting on deps. -# TYPE woodpecker_waiting_steps gauge -woodpecker_waiting_steps 0 -# HELP woodpecker_worker_count Total number of workers. -# TYPE woodpecker_worker_count gauge -woodpecker_worker_count 4 -``` diff --git a/docs/versioned_docs/version-2.1/30-administration/_category_.yaml b/docs/versioned_docs/version-2.1/30-administration/_category_.yaml deleted file mode 100644 index 4f31383598..0000000000 --- a/docs/versioned_docs/version-2.1/30-administration/_category_.yaml +++ /dev/null @@ -1,4 +0,0 @@ -label: 'Administration' -# position: 3 -collapsible: true -collapsed: true diff --git a/docs/versioned_docs/version-2.1/30-administration/new-agent-connected.png b/docs/versioned_docs/version-2.1/30-administration/new-agent-connected.png deleted file mode 100644 index 9d19153d9d..0000000000 Binary files a/docs/versioned_docs/version-2.1/30-administration/new-agent-connected.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/30-administration/new-agent-created.png b/docs/versioned_docs/version-2.1/30-administration/new-agent-created.png deleted file mode 100644 index dc561d8873..0000000000 Binary files a/docs/versioned_docs/version-2.1/30-administration/new-agent-created.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/30-administration/new-agent-registration.png b/docs/versioned_docs/version-2.1/30-administration/new-agent-registration.png deleted file mode 100644 index 71117771d6..0000000000 Binary files a/docs/versioned_docs/version-2.1/30-administration/new-agent-registration.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/40-cli.md b/docs/versioned_docs/version-2.1/40-cli.md deleted file mode 100644 index 6200bab712..0000000000 --- a/docs/versioned_docs/version-2.1/40-cli.md +++ /dev/null @@ -1,571 +0,0 @@ -# CLI - -# NAME - -woodpecker-cli - command line utility - -# SYNOPSIS - -woodpecker-cli - -``` -[--log-file]=[value] -[--log-level]=[value] -[--nocolor] -[--pretty] -[--server|-s]=[value] -[--token|-t]=[value] -``` - -**Usage**: - -``` -woodpecker-cli [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] -``` - -# GLOBAL OPTIONS - -**--log-file**="": Output destination for logs. 'stdout' and 'stderr' can be used as special keywords. (default: "stderr") - -**--log-level**="": set logging level (default: "info") - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - - -# COMMANDS - -## pipeline - -manage pipelines - -### ls - -show pipeline history - -**--branch**="": branch filter - -**--event**="": event filter - -**--format**="": format output (default: "\x1b[33mPipeline #{{ .Number }} \x1b[0m\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nAuthor: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}\nMessage: {{ .Message }}\n") - -**--limit**="": limit the list size (default: 25) - -**--status**="": status filter - -### last - -show latest pipeline details - -**--branch**="": branch name (default: "main") - -**--format**="": format output (default: "Number: {{ .Number }}\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\n") - -### logs - -show pipeline logs - -### info - -show pipeline details - -**--format**="": format output (default: "Number: {{ .Number }}\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\n") - -### stop - -stop a pipeline - -### start - -start a pipeline - -**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value - -### approve - -approve a pipeline - -### decline - -decline a pipeline - -### queue - -show pipeline queue - -**--format**="": format output (default: "\x1b[33m{{ .FullName }} #{{ .Number }} \x1b[0m\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nAuthor: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}\nMessage: {{ .Message }}\n") - -### ps - -show pipeline steps - -**--format**="": format output (default: "\x1b[33mStep #{{ .PID }} \x1b[0m\nStep: {{ .Name }}\nState: {{ .State }}\n") - -### create - -create new pipeline - -**--branch**="": branch to create pipeline from - -**--format**="": format output (default: "\x1b[33mPipeline #{{ .Number }} \x1b[0m\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nAuthor: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}\nMessage: {{ .Message }}\n") - -**--var**="": key=value - -## log - -manage logs - -### purge - -purge a log - -## deploy - -deploy code - -**--branch**="": branch filter (default: "main") - -**--event**="": event filter (default: "push") - -**--format**="": format output (default: "Number: {{ .Number }}\nStatus: {{ .Status }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\nTarget: {{ .Deploy }}\n") - -**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value - -**--status**="": status filter (default: "success") - -## exec - -execute a local pipeline - -**--backend-docker-api-version**="": the version of the API to reach, leave empty for latest. - -**--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 - -**--backend-docker-ipv6**: backend docker enable IPV6 - -**--backend-docker-network**="": backend docker network - -**--backend-docker-tls-verify**: enable or disable TLS verification for connecting to docker server - -**--backend-docker-volumes**="": backend docker volumes (comma separated) - -**--backend-engine**="": backend engine to run pipelines on (default: "auto-detect") - -**--backend-http-proxy**="": if set, pass the environment variable down as "HTTP_PROXY" to steps - -**--backend-https-proxy**="": if set, pass the environment variable down as "HTTPS_PROXY" to steps - -**--backend-k8s-namespace**="": backend k8s namespace (default: "woodpecker") - -**--backend-k8s-pod-annotations**="": backend k8s additional worker pod annotations - -**--backend-k8s-pod-labels**="": backend k8s additional worker pod labels - -**--backend-k8s-secctx-nonroot**: `run as non root` Kubernetes security context option - -**--backend-k8s-storage-class**="": backend k8s storage class - -**--backend-k8s-storage-rwx**: backend k8s storage access mode, should ReadWriteMany (RWX) instead of ReadWriteOnce (RWO) be used? (default: true) - -**--backend-k8s-volume-size**="": backend k8s volume size (default 10G) (default: "10G") - -**--backend-local-temp-dir**="": set a different temp dir to clone workflows into (default: "/tmp") - -**--backend-no-proxy**="": if set, pass the environment variable down as "NO_PROXY" to steps - -**--commit-author-avatar**="": - -**--commit-author-email**="": - -**--commit-author-name**="": - -**--commit-branch**="": - -**--commit-message**="": - -**--commit-ref**="": - -**--commit-refspec**="": - -**--commit-sha**="": - -**--connect-retry-count**="": number of times to retry connecting to the server (default: 5) - -**--connect-retry-delay**="": duration to wait before retrying to connect to the server (default: 2s) - -**--env**="": - -**--forge-type**="": - -**--forge-url**="": - -**--local**: run from local directory - -**--netrc-machine**="": - -**--netrc-password**="": - -**--netrc-username**="": - -**--network**="": external networks - -**--pipeline-created**="": (default: 0) - -**--pipeline-event**="": (default: "manual") - -**--pipeline-finished**="": (default: 0) - -**--pipeline-number**="": (default: 0) - -**--pipeline-parent**="": (default: 0) - -**--pipeline-started**="": (default: 0) - -**--pipeline-status**="": - -**--pipeline-target**="": - -**--pipeline-url**="": - -**--prev-commit-author-avatar**="": - -**--prev-commit-author-email**="": - -**--prev-commit-author-name**="": - -**--prev-commit-branch**="": - -**--prev-commit-message**="": - -**--prev-commit-ref**="": - -**--prev-commit-refspec**="": - -**--prev-commit-sha**="": - -**--prev-pipeline-created**="": (default: 0) - -**--prev-pipeline-event**="": - -**--prev-pipeline-finished**="": (default: 0) - -**--prev-pipeline-number**="": (default: 0) - -**--prev-pipeline-started**="": (default: 0) - -**--prev-pipeline-status**="": - -**--prev-pipeline-url**="": - -**--privileged**="": privileged plugins (default: "plugins/docker", "plugins/gcr", "plugins/ecr", "woodpeckerci/plugin-docker-buildx", "codeberg.org/woodpecker-plugins/docker-buildx") - -**--repo**="": full repo name - -**--repo-clone-ssh-url**="": - -**--repo-clone-url**="": - -**--repo-private**="": - -**--repo-remote-id**="": - -**--repo-trusted**: - -**--repo-url**="": - -**--step-name**="": (default: 0) - -**--system-name**="": (default: "woodpecker") - -**--system-platform**="": - -**--system-url**="": (default: "https://github.com/woodpecker-ci/woodpecker") - -**--timeout**="": pipeline timeout (default: 1h0m0s) - -**--volumes**="": pipeline volumes - -**--workflow-name**="": (default: 0) - -**--workflow-number**="": (default: 0) - -**--workspace-base**="": (default: "/woodpecker") - -**--workspace-path**="": (default: "src") - -## info - -show information about the current user - -## registry - -manage registries - -### add - -adds a registry - -**--hostname**="": registry hostname (default: "docker.io") - -**--password**="": registry password - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--username**="": registry username - -### rm - -remove a registry - -**--hostname**="": registry hostname (default: "docker.io") - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -### update - -update a registry - -**--hostname**="": registry hostname (default: "docker.io") - -**--password**="": registry password - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--username**="": registry username - -### info - -display registry info - -**--hostname**="": registry hostname (default: "docker.io") - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -### ls - -list registries - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -## secret - -manage secrets - -### add - -adds a secret - -**--event**="": secret limited to these events - -**--global**: global secret - -**--image**="": secret limited to these images - -**--name**="": secret name - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--value**="": secret value - -### rm - -remove a secret - -**--global**: global secret - -**--name**="": secret name - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -### update - -update a secret - -**--event**="": secret limited to these events - -**--global**: global secret - -**--image**="": secret limited to these images - -**--name**="": secret name - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--value**="": secret value - -### info - -display secret info - -**--global**: global secret - -**--name**="": secret name - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -### ls - -list secrets - -**--global**: global secret - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -## repo - -manage repositories - -### ls - -list all repos - -**--format**="": format output (default: "\x1b[33m{{ .FullName }}\x1b[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }})") - -**--org**="": filter by organization - -### info - -show repository details - -**--format**="": format output (default: "Owner: {{ .Owner }}\nRepo: {{ .Name }}\nURL: {{ .ForgeURL }}\nConfig path: {{ .Config }}\nVisibility: {{ .Visibility }}\nPrivate: {{ .IsSCMPrivate }}\nTrusted: {{ .IsTrusted }}\nGated: {{ .IsGated }}\nClone url: {{ .Clone }}\nAllow pull-requests: {{ .AllowPullRequests }}\n") - -### add - -add a repository - -### update - -update a repository - -**--config**="": repository configuration path (e.g. .woodpecker.yml) - -**--gated**: repository is gated - -**--pipeline-counter**="": repository starting pipeline number (default: 0) - -**--timeout**="": repository timeout (default: 0s) - -**--trusted**: repository is trusted - -**--unsafe**: validate updating the pipeline-counter is unsafe - -**--visibility**="": repository visibility - -### rm - -remove a repository - -### repair - -repair repository webhooks - -### chown - -assume ownership of a repository - -### sync - -synchronize the repository list - -**--format**="": format output (default: "\x1b[33m{{ .FullName }}\x1b[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }})") - -## user - -manage users - -### ls - -list all users - -**--format**="": format output (default: "{{ .Login }}") - -### info - -show user details - -**--format**="": format output (default: "User: {{ .Login }}\nEmail: {{ .Email }}") - -### add - -adds a user - -### rm - -remove a user - -## lint - -lint a pipeline configuration file - -## log-level - -get the logging level of the server, or set it with [level] - -## cron - -manage cron jobs - -### add - -add a cron job - -**--branch**="": cron branch - -**--name**="": cron name - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--schedule**="": cron schedule - -### rm - -remove a cron job - -**--id**="": cron id - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -### update - -update a cron job - -**--branch**="": cron branch - -**--id**="": cron id - -**--name**="": cron name - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--schedule**="": cron schedule - -### info - -display info about a cron job - -**--id**="": cron id - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -### ls - -list cron jobs - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) diff --git a/docs/versioned_docs/version-2.1/91-migrations.md b/docs/versioned_docs/version-2.1/91-migrations.md deleted file mode 100644 index 921580e022..0000000000 --- a/docs/versioned_docs/version-2.1/91-migrations.md +++ /dev/null @@ -1,147 +0,0 @@ -# Migrations - -Some versions need some changes to the server configuration or the pipeline configuration files. - -## `next` - -- Deprecated `steps.[name].group` in favor of `steps.[name].depends_on` (see [workflow syntax](./20-usage/20-workflow-syntax.md#depends_on) to learn how to set dependencies) -- Removed `WOODPECKER_ROOT_PATH` and `WOODPECKER_ROOT_URL` config variables. Use `WOODPECKER_HOST` with a path instead -- Pipelines without a config file will now be skipped instead of failing -- Deprecated implicitly defined `regcred` image pull secret. Set it explicitly via `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES`. - -## 2.0.0 - -- Dropped deprecated `CI_BUILD_*`, `CI_PREV_BUILD_*`, `CI_JOB_*`, `*_LINK`, `CI_SYSTEM_ARCH`, `CI_REPO_REMOTE` built-in environment variables -- Deprecated `platform:` filter in favor of `labels:`, [read more](./20-usage/20-workflow-syntax.md#filter-by-platform) -- Secrets `event` property was renamed to `events` and `image` to `images` as both are lists. The new property `events` / `images` has to be used in the api. The old properties `event` and `image` were removed. -- The secrets `plugin_only` option was removed. Secrets with images are now always only available for plugins using listed by the `images` property. Existing secrets with a list of `images` will now only be available to the listed images if they are used as a plugin. -- Removed `build` alias for `pipeline` command in CLI -- Removed `ssh` backend. Use an agent directly on the SSH machine using the `local` backend. -- Removed `/hook` and `/stream` API paths in favor of `/api/(hook|stream)`. You may need to use the "Repair repository" button in the repo settings or "Repair all" in the admin settings to recreate the forge hook. -- Removed `WOODPECKER_DOCS` config variable -- Renamed `link` to `url` (including all API fields) -- Deprecated `CI_COMMIT_URL` env var, use `CI_PIPELINE_FORGE_URL` - -## 1.0.0 - -- The signature used to verify extension calls (like those used for the [config-extension](./30-administration/100-external-configuration-api.md)) done by the Woodpecker server switched from using a shared-secret HMac to an ed25519 key-pair. Read more about it at the [config-extensions](./30-administration/100-external-configuration-api.md) documentation. -- Refactored support for old agent filter labels and expressions. Learn how to use the new [filter](./20-usage/20-workflow-syntax.md#labels) -- Renamed step environment variable `CI_SYSTEM_ARCH` to `CI_SYSTEM_PLATFORM`. Same applies for the cli exec variable. -- Renamed environment variables `CI_BUILD_*` and `CI_PREV_BUILD_*` to `CI_PIPELINE_*` and `CI_PREV_PIPELINE_*`, old ones are still available but deprecated -- Renamed environment variables `CI_JOB_*` to `CI_STEP_*`, old ones are still available but deprecated -- Renamed environment variable `CI_REPO_REMOTE` to `CI_REPO_CLONE_URL`, old is still available but deprecated -- Renamed environment variable `*_LINK` to `*_URL`, old ones are still available but deprecated -- Renamed API endpoints for pipelines (`//builds/` -> `//pipelines/`), old ones are still available but deprecated -- Updated Prometheus gauge `build_*` to `pipeline_*` -- Updated Prometheus gauge `*_job_*` to `*_step_*` -- Renamed config env `WOODPECKER_MAX_PROCS` to `WOODPECKER_MAX_WORKFLOWS` (still available as fallback) -- The pipelines are now also read from `.yaml` files, the new default order is `.woodpecker/*.yml` and `.woodpecker/*.yaml` (without any prioritization) -> `.woodpecker.yml` -> `.woodpecker.yaml` -- Dropped support for [Coding](https://coding.net/), [Gogs](https://gogs.io) and Bitbucket Server (Stash). -- `/api/queue/resume` & `/api/queue/pause` endpoint methods were changed from `GET` to `POST` -- rename `pipeline:` key in your workflow config to `steps:` -- If you want to migrate old logs to the new format, watch the error messages on start. If there are none we are good to go, else you have to plan a migration that can take hours. Set `WOODPECKER_MIGRATIONS_ALLOW_LONG` to true and let it run. -- Using `repo-id` in favor of `owner/repo` combination - - :warning: The api endpoints `/api/repos/{owner}/{repo}/...` were replaced by new endpoints using the repos id `/api/repos/{repo-id}` - - To find the id of a repo use the `/api/repos/lookup/{repo-full-name-with-slashes}` endpoint. - - The existing badge endpoint `/api/badges/{owner}/{repo}` will still work, but whenever possible try to use the new endpoint using the `repo-id`: `/api/badges/{repo-id}`. - - The UI urls for a repository changed from `/repos/{owner}/{repo}/...` to `/repos/{repo-id}/...`. You will be redirected automatically when using the old url. - - The woodpecker-go api-client is now using the `repo-id` instead of `owner/repo` for all functions -- Using `org-id` in favour of `owner` name - - :warning: The api endpoints `/api/orgs/{owner}/...` were replaced by new endpoints using the orgs id `/api/repos/{org-id}` - - To find the id of orgs use the `/api/orgs/lookup/{org_full_name}` endpoint. - - The UI urls for a organization changed from `/org/{owner}/...` to `/orgs/{org-id}/...`. You will be redirected automatically when using the old url. - - The woodpecker-go api-client is now using the `org-id` instead of `org name` for all functions -- The `command:` field has been removed from steps. If you were using it, please check if the entrypoint of the image you used is a shell. - - If it is a shell, simply rename `command:` to `commands:`. - - If it's not, you need to prepend the entrypoint before and also rename it (e.g., `commands: `). - -## 0.15.0 - -- Default value for custom pipeline path is now empty / un-set which results in following resolution: - - `.woodpecker/*.yml` -> `.woodpecker.yml` -> `.drone.yml` - - Only projects created after updating will have an empty value by default. Existing projects will stick to the current pipeline path which is `.drone.yml` in most cases. - - Read more about it at the [Project Settings](./20-usage/71-project-settings.md#pipeline-path) - -- From version `0.15.0` ongoing there will be three types of docker images: `latest`, `next` and `x.x.x` with an alpine variant for each type like `latest-alpine`. - If you used `latest` before to try pre-release features you should switch to `next` after this release. - -- Dropped support for `DRONE_*` environment variables. The according `WOODPECKER_*` variables must be used instead. - Additionally some alternative namings have been removed to simplify maintenance: - - - `WOODPECKER_AGENT_SECRET` replaces `WOODPECKER_SECRET`, `DRONE_SECRET`, `WOODPECKER_PASSWORD`, `DRONE_PASSWORD` and `DRONE_AGENT_SECRET`. - - `WOODPECKER_HOST` replaces `DRONE_HOST` and `DRONE_SERVER_HOST`. - - `WOODPECKER_DATABASE_DRIVER` replaces `DRONE_DATABASE_DRIVER` and `DATABASE_DRIVER`. - - `WOODPECKER_DATABASE_DATASOURCE` replaces `DRONE_DATABASE_DATASOURCE` and `DATABASE_CONFIG`. - -- Dropped support for `DRONE_*` environment variables in pipeline steps. Pipeline meta-data can be accessed with `CI_*` variables. - - - `CI_*` prefix replaces `DRONE_*` - - `CI` value is now `woodpecker` - - `DRONE=true` has been removed - - Some variables got deprecated and will be removed in future versions. Please migrate to the new names. Same applies for `DRONE_` of them. - - CI_ARCH => use CI_SYSTEM_ARCH - - CI_COMMIT => CI_COMMIT_SHA - - CI_TAG => CI_COMMIT_TAG - - CI_PULL_REQUEST => CI_COMMIT_PULL_REQUEST - - CI_REMOTE_URL => use CI_REPO_REMOTE - - CI_REPO_BRANCH => use CI_REPO_DEFAULT_BRANCH - - CI_PARENT_BUILD_NUMBER => use CI_BUILD_PARENT - - CI_BUILD_TARGET => use CI_BUILD_DEPLOY_TARGET - - CI_DEPLOY_TO => use CI_BUILD_DEPLOY_TARGET - - CI_COMMIT_AUTHOR_NAME => use CI_COMMIT_AUTHOR - - CI_PREV_COMMIT_AUTHOR_NAME => use CI_PREV_COMMIT_AUTHOR - - CI_SYSTEM => use CI_SYSTEM_NAME - - CI_BRANCH => use CI_COMMIT_BRANCH - - CI_SOURCE_BRANCH => use CI_COMMIT_SOURCE_BRANCH - - CI_TARGET_BRANCH => use CI_COMMIT_TARGET_BRANCH - - For all available variables and their descriptions have a look at [built-in-environment-variables](./20-usage/50-environment.md#built-in-environment-variables). - -- Prometheus metrics have been changed from `drone_*` to `woodpecker_*` - -- Base path has moved from `/var/lib/drone` to `/var/lib/woodpecker` - -- Default workspace base path has moved from `/drone` to `/woodpecker` - -- Default SQLite database location has changed: - - - `/var/lib/drone/drone.sqlite` -> `/var/lib/woodpecker/woodpecker.sqlite` - - `drone.sqlite` -> `woodpecker.sqlite` - -- Plugin Settings moved into `settings` section: - - ```diff - steps: - something: - image: my/plugin - - setting1: foo - - setting2: bar - + settings: - + setting1: foo - + setting2: bar - ``` - -- `WOODPECKER_DEBUG` option for server and agent got removed in favor of `WOODPECKER_LOG_LEVEL=debug` - -- Remove unused server flags which can safely be removed from your server config: `WOODPECKER_QUIC`, `WOODPECKER_GITHUB_SCOPE`, `WOODPECKER_GITHUB_GIT_USERNAME`, `WOODPECKER_GITHUB_GIT_PASSWORD`, `WOODPECKER_GITHUB_PRIVATE_MODE`, `WOODPECKER_GITEA_GIT_USERNAME`, `WOODPECKER_GITEA_GIT_PASSWORD`, `WOODPECKER_GITEA_PRIVATE_MODE`, `WOODPECKER_GITLAB_GIT_USERNAME`, `WOODPECKER_GITLAB_GIT_PASSWORD`, `WOODPECKER_GITLAB_PRIVATE_MODE` - -- Dropped support for manually setting the agents platform with `WOODPECKER_PLATFORM`. The platform is now automatically detected. - -- Use `WOODPECKER_STATUS_CONTEXT` instead of the deprecated options `WOODPECKER_GITHUB_CONTEXT` and `WOODPECKER_GITEA_CONTEXT`. - -## 0.14.0 - -No breaking changes - -## From Drone - -:::warning -Migration from Drone is only possible if you were running Drone <= v0.8. -::: - -1. Make sure you are already running Drone v0.8 -2. Upgrade to Woodpecker v0.14.4, migration will be done during startup -3. Upgrade to the latest Woodpecker version. Pay attention to the breaking changes listed above. diff --git a/docs/versioned_docs/version-2.1/92-awesome.md b/docs/versioned_docs/version-2.1/92-awesome.md deleted file mode 100644 index 4eaf81edee..0000000000 --- a/docs/versioned_docs/version-2.1/92-awesome.md +++ /dev/null @@ -1,63 +0,0 @@ -# Awesome Woodpecker - -A curated list of awesome things related to Woodpecker-CI. - -If you have some missing resources, please feel free to [open a pull-request](https://github.com/woodpecker-ci/woodpecker/edit/main/docs/docs/92-awesome.md) and add them. - -## Official Resources - -- [Woodpecker CI pipeline configs](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) - Complex setup containing different kind of pipelines - - [Golang tests](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/test.yml) - - [Typescript, eslint & Vue](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/web.yml) - - [Docusaurus & publishing to GitHub Pages](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docs.yml) - - [Docker container building](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docker.yml) - - [Helm chart linting & releasing](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/helm.yml) - -## Projects using Woodpecker - -- [Woodpecker-CI](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) itself -- [All official plugins](https://github.com/woodpecker-ci?q=plugin&type=all) -- [dessalines/thumb-key](https://github.com/dessalines/thumb-key/blob/main/.woodpecker.yml) - Android Jetpack compose linting and building -- [Vieter](https://git.rustybever.be/vieter-v/vieter) - Archlinux/Pacman repository server & automated package build system - - [Rieter](https://git.rustybever.be/Chewing_Bever/rieter) - Rewrite of the Vieter project in Rust -- [Alex](https://git.rustybever.be/Chewing_Bever/alex) - Minecraft server wrapper designed to automate backups & complement Docker installations - -## Tools - -- [Convert Drone CI pipelines to Woodpecker CI](https://codeberg.org/lafriks/woodpecker-pipeline-transform) -- [Ansible NAS](https://github.com/davestephens/ansible-nas/) - a homelab Ansible playbook that can set up Woodpecker-CI and Gitea -- [picus](https://github.com/windsource/picus) - Picus connects to a Woodpecker CI server and creates an agent in the cloud when there are pending workflows. -- [Hetzner cloud](https://www.hetzner.com/cloud) based [Woodpecker compatible autoscaler](https://git.ljoonal.xyz/ljoonal/hetzner-ci-autoscaler) - Creates and destroys VPS instances based on the count of pending & running jobs. -- [woodpecker-lint](https://git.schmidl.dev/schtobia/woodpecker-lint) - A repository for linting a woodpecker config file via pre-commit hook -- [Grafana Dashboard](https://github.com/Janik-Haag/woodpecker-grafana-dashboard) - A dashboard visualizing information exposed by the woodpecker prometheus endpoint. -- [woodpecker-autoscaler](https://github.com/Lerentis/woodpecker-autoscaler) - Yet another woodpecker autoscaler currently targeting [Hetzner cloud](https://www.hetzner.com/cloud) that works in parallel to other autoscaler implementations. - -## Configuration Services - -- [Dynamic Pipelines for Nix Flakes](https://github.com/pinpox/woodpecker-flake-pipeliner) - Define pipelines as Nix Flake outputs - -## Pipelines - -- [Collection of pipeline examples](https://codeberg.org/Codeberg-CI/examples) - -## Posts & tutorials - -- [Setup Gitea with Woodpecker CI](https://containers.fan/posts/setup-gitea-with-woodpecker-ci/) -- [Step-by-step guide to modern, secure and Open-source CI setup](https://devforth.io/blog/step-by-step-guide-to-modern-secure-ci-setup/) -- [Using Woodpecker CI for my static sites](https://jan.wildeboer.net/2022/07/Woodpecker-CI-Jekyll/) -- [Woodpecker CI @ Codeberg](https://www.sarkasti.eu/articles/post/woodpecker/) -- [Deploy Docker/Compose using Woodpecker CI](https://hinty.io/vverenko/deploy-docker-compose-using-woodpecker-ci/) -- [Installing Woodpecker CI in your personal homelab](https://pwa.io/articles/installing-woodpecker-in-your-homelab/) -- [Locally Cached Nix CI with Woodpecker](https://blog.kotatsu.dev/posts/2023-04-21-woodpecker-nix-caching/) -- [How to run Cypress auto-tests on Woodpecker CI and report results to Slack](https://devforth.io/blog/how-to-run-cypress-auto-tests-on-woodpecker-ci-and-report-results-to-slack/) -- [Quest For CICD - WoodpeckerCI](https://omaramin.me/posts/woodpecker/) - -## Videos - -- [Replace Ansible Semaphore with Woodpecker CI](https://www.youtube.com/watch?v=d610YPvCB0E) -- ["unexpected EOF" error when trying to pair Woodpecker CI served through the Caddy with Gitea](https://www.youtube.com/watch?v=n7Hyvt71Np0) -- [CICD Environment in Docker Swarm behind Caddy Server - Part 2 Woodpeckerci](https://www.youtube.com/watch?v=rkbw_k7JvS0) - -## Plugins - -We have a separate [index](/plugins) for plugins. diff --git a/docs/versioned_docs/version-2.1/92-development/01-getting-started.md b/docs/versioned_docs/version-2.1/92-development/01-getting-started.md deleted file mode 100644 index 06bfe0ec2f..0000000000 --- a/docs/versioned_docs/version-2.1/92-development/01-getting-started.md +++ /dev/null @@ -1,147 +0,0 @@ -# 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 preconfigured 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 preconfigured [Gitea](https://github.com/go-gitea/gitea) instance as forge -- A preconfigured Woodpecker server -- A single preconfigured Woodpecker agent node -- Our docs preview server - -Simply start Woodpecker in Gitpod by clicking on the following badge. You can login 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 Golang (>=1.20) as described by [this guide](https://go.dev/doc/install). - -### 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 (). - -Install make on: - -- Ubuntu: `apt install make` - [Docs](https://wiki.ubuntuusers.de/Makefile/) -- [Windows](https://stackoverflow.com/a/32127632/8461267) -- Mac OS: `brew install make` - -### Install Node.js & pnpm - -Install [Node.js (>=14)](https://nodejs.org/en/download/) if you want to build Woodpeckers UI or documentation. - -For dependencies installation (node_modules) for the UI and documentation of Woodpecker the package-manager pnpm is used. The installation of pnpm is described by [this guide](https://pnpm.io/installation). - -### 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` in the root of the Woodpecker project and add any need config to it. - -A common config for debugging would look like this: - -```ini -WOODPECKER_OPEN=true -WOODPECKER_ADMIN=your-username - -# if you want to test webhooks with an online forge like GitHub this address needs to be accessible from public server -WOODPECKER_HOST=http://your-dev-address.com - -# github (sample for a forge config - see /docs/administration/forge/overview for other forges) -WOODPECKER_GITHUB=true -WOODPECKER_GITHUB_CLIENT= -WOODPECKER_GITHUB_SECRET= - -# agent -WOODPECKER_SERVER=localhost:9000 -WOODPECKER_AGENT_SECRET=a-long-and-secure-password-used-for-the-local-development-system -WOODPECKER_MAX_WORKFLOWS=1 - -# enable if you want to develop the UI -# WOODPECKER_DEV_WWW_PROXY=http://localhost:8010 - -# used so you can login without using a public address -WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000 - -# disable health-checks while debugging (normally not needed while developing) -WOODPECKER_HEALTHCHECK=false - -# WOODPECKER_LOG_LEVEL=debug -# WOODPECKER_LOG_LEVEL=trace -``` - -### Setup O-Auth - -Create an O-Auth app for your forge as describe in the [forges documentation](../30-administration/11-forges/10-overview.md). If you set `WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000` you can use that address with the path as explained for the specific forge to login without the need for a public address. For example for GitHub you would use `http://localhost:8000/authorize` as authorization callback URL. - -## Developing with VS-Code - -You can use different methods for debugging the Woodpecker applications. One of the currently recommended ways to debug and test the Woodpecker application is using [VS-Code](https://code.visualstudio.com/) or [VS-Codium](https://vscodium.com/) (Open-Source binaries of VS-Code) as most maintainers are using it and Woodpecker already includes the needed debug configurations for it. - -To launch all needed services for local development you can use "Woodpecker CI" debugging configuration that will launch UI, server and agent in debugging mode. Then open `http://localhost:8000` to access it. - -As a starting guide for programming Go with VS-Code you can use this video guide: -[![Getting started with Go in VS-Code](https://img.youtube.com/vi/1MXIGYrMk80/0.jpg)](https://www.youtube.com/watch?v=1MXIGYrMk80) - -### Debugging Woodpecker - -The Woodpecker source code already includes launch configurations for the Woodpecker server and agent. To start debugging you can click on the debug icon in the navigation bar of VS-Code (ctrl-shift-d). On that page you will see the existing launch jobs at the top. Simply select the agent or server and click on the play button. You can set breakpoints in the source files to stop at specific points. - -![Woodpecker debugging with VS-Code](./vscode-debug.png) - -## Testing & linting code - -To test or lint parts of Woodpecker you can run one of the following commands: - -```bash -# test server code -make test-server - -# test agent code -make test-agent - -# test cli code -make test-cli - -# test datastore / database related code like migrations of the server -make test-server-datastore - -# lint go code -make lint - -# lint UI code -make lint-frontend - -# test UI code -make test-frontend -``` - -If you want to test a specific go file you can also use: - -```bash -go test -race -timeout 30s go.woodpecker-ci.org/woodpecker/v2/ -``` - -Or you can open the test-file inside [VS-Code](#developing-with-vs-code) and run or debug the test by clicking on the inline commands: - -![Run test via VS-Code](./vscode-run-test.png) - -## Run applications from terminal - -If you want to run a Woodpecker applications from your terminal you can use one of the following commands from the base of the Woodpecker project. They will execute Woodpecker in a similar way as described in [debugging Woodpecker](#debugging-woodpecker) without the ability to really debug it in your editor. - -```bash title="start server" -go run ./cmd/server -``` - -```bash title="start agent" -go run ./cmd/agent -``` - -```bash title="execute cli command" -go run ./cmd/cli [command] -``` diff --git a/docs/versioned_docs/version-2.1/92-development/03-ui.md b/docs/versioned_docs/version-2.1/92-development/03-ui.md deleted file mode 100644 index e8999b0be8..0000000000 --- a/docs/versioned_docs/version-2.1/92-development/03-ui.md +++ /dev/null @@ -1,39 +0,0 @@ -# UI Development - -To develop the UI you need to install [Node.js and pnpm](./01-getting-started.md#install-nodejs--pnpm). In addition it is recommended to use VS-Code with the recommended plugin selection to get features like auto-formatting, linting and typechecking. The UI is written with [Vue 3](https://v3.vuejs.org/) as Single-Page-Application accessing the Woodpecker REST api. - -## Setup - -The UI code is placed in `web/`. Change to that folder in your terminal with `cd web/` and install all dependencies by running `pnpm install`. For production builds the generated UI code is integrated into the Woodpecker server by using [go-embed](https://pkg.go.dev/embed). - -Testing UI changes would require us to rebuild the UI after each adjustment to the code by running `pnpm build` and restarting the Woodpecker server. To avoid this you can make use of the dev-proxy integrated into the Woodpecker server. This integrated dev-proxy will forward all none api request to a separate http-server which will only serve the UI files. - -![UI Proxy architecture](./ui-proxy.svg) - -Start the UI server locally with [hot-reloading](https://stackoverflow.com/a/41429055/8461267) by running: `pnpm start`. To enable the forwarding of requests to the UI server you have to enable the dev-proxy inside the Woodpecker server by adding `WOODPECKER_DEV_WWW_PROXY=http://localhost:8010` to your `.env` file. -After starting the Woodpecker server as explained in the [debugging](./01-getting-started.md#debugging-woodpecker) section, you should now be able to access the UI under [http://localhost:8000](http://localhost:8000). - -## Tools and frameworks - -The following list contains some tools and frameworks used by the Woodpecker UI. For some points we added some guidelines / hints to help you developing. - -- [Vue 3](https://v3.vuejs.org/) - - use `setup` and composition api - - place (re-usable) components in `web/src/components/` - - views should have a route in `web/src/router.ts` and are located in `web/src/views/` -- [Windicss](https://windicss.org/) (similar to Tailwind) - - use Windicss classes where possible - - if needed extend the Windicss config to use new classes -- [Vite](https://vitejs.dev/) (similar to Webpack) -- [Typescript](https://www.typescriptlang.org/) - - avoid using `any` and `unknown` (the linter will prevent you from doing so anyways :wink:) -- [eslint](https://eslint.org/) -- [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) - -## 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. -You must not provide translations except English in PRs, otherwise weblate could put git into conflicts (when someone has translated in that language file and changes are not into main branch yet) - -For more information about translations see [Translations](./07-translations.md). diff --git a/docs/versioned_docs/version-2.1/92-development/04-docs.md b/docs/versioned_docs/version-2.1/92-development/04-docs.md deleted file mode 100644 index 55ccb5b7d9..0000000000 --- a/docs/versioned_docs/version-2.1/92-development/04-docs.md +++ /dev/null @@ -1,20 +0,0 @@ -# Documentation - -The documentation is using docusaurus as framework. You can learn more about it from its [official documentation](https://docusaurus.io/docs/). - -If you only want to change some text it probably is enough if you just search for the corresponding [Markdown](https://www.markdownguide.org/basic-syntax/) file inside the `docs/docs/` folder and adjust it. If you want to change larger parts and test the rendered documentation you can run docusaurus locally. Similarly to the UI you need to install [Node.js and pnpm](./01-getting-started.md#install-nodejs--pnpm). After that you can run and build docusaurus locally by using the following commands: - -```bash -cd docs/ - -pnpm install - -# build plugins used by the docs -pnpm build:woodpecker-plugins - -# start docs with hot-reloading, so you can change the docs and directly see the changes in the browser without reloading it manually -pnpm start - -# or build the docs to deploy it to some static page hosting -pnpm build -``` diff --git a/docs/versioned_docs/version-2.1/92-development/05-architecture.md b/docs/versioned_docs/version-2.1/92-development/05-architecture.md deleted file mode 100644 index 466ab2171e..0000000000 --- a/docs/versioned_docs/version-2.1/92-development/05-architecture.md +++ /dev/null @@ -1,48 +0,0 @@ -# Architecture - -## Package architecture - -![Woodpecker architecture](./woodpecker-architecture.png) - -## System architecture - -### main package hierarchy - -| package | meaning | imports | -| ------------------ | -------------------------------------------------------------- | ------------------------------------- | -| `cmd/**` | parse command-line args & environment to stat server/cli/agent | all other | -| `agent/**` | code only agent (remote worker) will need | `pipeline`, `shared` | -| `cli/**` | code only cli tool does need | `pipeline`, `shared`, `woodpecker-go` | -| `server/**` | code only server will need | `pipeline`, `shared` | -| `shared/**` | code shared for all three main tools (go help utils) | only std and external libs | -| `woodpecker-go/**` | go client for server rest api | std | - -### Server - -| package | meaning | imports | -| -------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `server/api/**` | handle web requests from `server/router` | `pipeline`, `../badges`, `../ccmenue`, `../logging`, `../model`, `../pubsub`, `../queue`, `../forge`, `../shared`, `../store`, `shared`, (TODO: mv `server/router/middleware/session`) | -| `server/badges/**` | generate svg badges for pipelines | `../model` | -| `server/ccmenu/**` | generate xml ccmenu for pipelines | `../model` | -| `server/grpc/**` | gRPC server agents can connect to | `pipeline/rpc/**`, `../logging`, `../model`, `../pubsub`, `../queue`, `../forge`, `../pipeline`, `../store` | -| `server/logging/**` | logging lib for gPRC server to stream logs while running | std | -| `server/model/**` | structs for store (db) and api (json) | std | -| `server/plugins/**` | plugins for server | `../model`, `../forge` | -| `server/pipeline/**` | orchestrate pipelines | `pipeline`, `../model`, `../pubsub`, `../queue`, `../forge`, `../store`, `../plugins` | -| `server/pubsub/**` | pubsub lib for server to push changes to the WebUI | std | -| `server/queue/**` | queue lib for server where agents pull new pipelines from via gRPC | `server/model` | -| `server/forge/**` | forge lib for server to connect and handle forge specific stuff | `shared`, `server/model` | -| `server/router/**` | handle requests to REST API (and all middleware) and serve UI and WebUI config | `shared`, `../api`, `../model`, `../forge`, `../store`, `../web` | -| `server/store/**` | handle database | `server/model` | -| `server/shared/**` | TODO: move and split [#974](https://github.com/woodpecker-ci/woodpecker/issues/974) | -| `server/web/**` | server SPA | - -- `../` = `server/` - -### Agent - -TODO - -### CLI - -TODO diff --git a/docs/versioned_docs/version-2.1/92-development/06-guides.md b/docs/versioned_docs/version-2.1/92-development/06-guides.md deleted file mode 100644 index e8db28a537..0000000000 --- a/docs/versioned_docs/version-2.1/92-development/06-guides.md +++ /dev/null @@ -1,24 +0,0 @@ -# Guides - -## ORM - -Woodpecker uses [Xorm](https://xorm.io/) as ORM for the database connection. -You can find its documentation at [gobook.io/read/gitea.com/xorm](https://gobook.io/read/gitea.com/xorm/manual-en-US/). - -## Add a new migration - -Woodpecker uses migrations to change the database schema if a database model has been changed. Add the new migration task into `server/store/datastore/migration/`. - -:::info -Adding new properties to models will be handled automatically by the underlying [ORM](#orm) based on the [struct field tags](https://stackoverflow.com/questions/10858787/what-are-the-uses-for-tags-in-go) of the model. If you add a completely new model, you have to add it to the `allBeans` variable at `server/store/datastore/migration/migration.go` to get a new table created. -::: - -:::warning -You should not use `sess.Begin()`, `sess.Commit()` or `sess.Close()` inside a migration. Session / transaction handling will be done by the underlying migration manager. -::: - -To automatically execute the migration after the start of the server, the new migration needs to be added to the end of `migrationTasks` in `server/store/datastore/migration/migration.go`. After a successful execution of that transaction the server will automatically add the migration to a list, so it won't be executed again on the next start. - -## Constants of official images - -All official default images, are saved in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go) and must be pinned by an exact tag. diff --git a/docs/versioned_docs/version-2.1/92-development/07-translations.md b/docs/versioned_docs/version-2.1/92-development/07-translations.md deleted file mode 100644 index 6ddd9f1eb4..0000000000 --- a/docs/versioned_docs/version-2.1/92-development/07-translations.md +++ /dev/null @@ -1,9 +0,0 @@ -# Translations - -To translate the web UI into your language, we have [our own Weblate instance](https://translate.woodpecker-ci.org/). Please register there and translate Woodpecker into your language. **We won't accept PRs changing any language except English.** - - - Translation status - - -Woodpecker uses [Vue I18n](https://vue-i18n.intlify.dev/) as translation library. diff --git a/docs/versioned_docs/version-2.1/92-development/08-swagger.md b/docs/versioned_docs/version-2.1/92-development/08-swagger.md deleted file mode 100644 index 92505a8fcc..0000000000 --- a/docs/versioned_docs/version-2.1/92-development/08-swagger.md +++ /dev/null @@ -1,63 +0,0 @@ -# Swagger, API Spec and Code Generation - -Woodpecker uses [gin-swagger](https://github.com/swaggo/gin-swagger) middleware to automatically -generate Swagger v2 API specifications and a nice looking Web UI from the source code. -Also, the generated spec will be transformed into Markdown, using [go-swagger](https://github.com/go-swagger/go-swagger) -and then being using on the community's website documentation. - -It's paramount important to keep the gin handler function's godoc documentation up-to-date, -to always have accurate API documentation. -Whenever you change, add or enhance an API endpoint, please update the godocs. - -You don't require any extra tools on your machine, all Swagger tooling is automatically fetched by standard Go tools. - -## Gin-Handler API documentation guideline - -Here's a typical example of how annotations for Swagger documentation look like... - -```go title="server/api/user.go" -// @Summary Get a user -// @Description Returns a user with the specified login name. Requires admin rights. -// @Router /users/{login} [get] -// @Produce json -// @Success 200 {object} User -// @Tags Users -// @Param Authorization header string true "Insert your personal access token" default(Bearer ) -// @Param login path string true "the user's login name" -// @Param foobar query string false "optional foobar parameter" -// @Param page query int false "for response pagination, page offset number" default(1) -// @Param perPage query int false "for response pagination, max items per page" default(50) -``` - -```go title="server/model/user.go" -type User struct { - ID int64 `json:"id" xorm:"pk autoincr 'user_id'"` -// ... -} // @name User -``` - -These guidelines aim to have consistent wording in the swagger doc: - -- first word after `@Summary` and `@Summary` are always uppercase -- `@Summary` has no `.` (dot) at the end of the line -- model structs shall use custom short names, to ease life for API consumers, using `@name` -- `@Success` object or array declarations shall be short, this means the actual `model.User` struct must have a `@name` annotation, so that the model can be renderend in Swagger -- when pagination is used, `@Parame page` and `@Parame perPage` must be added manually -- `@Param Authorization` is almost always present, there are just a few un-protected endpoints - -There are many examples in the `server/api` package, which you can use a blueprint. -More enhanced information you can find here - -### Manual code generation - -```bash title="generate the server's Go code containing the Swagger" -make generate-swagger -``` - -```bash title="update the Markdown in the ./docs folder" -make docs -``` - -```bash title="auto-format swagger related godoc" -go run github.com/swaggo/swag/cmd/swag@latest fmt -g server/api/z.go -``` diff --git a/docs/versioned_docs/version-2.1/92-development/09-security.md b/docs/versioned_docs/version-2.1/92-development/09-security.md deleted file mode 100644 index 24517c8432..0000000000 --- a/docs/versioned_docs/version-2.1/92-development/09-security.md +++ /dev/null @@ -1,10 +0,0 @@ -# Security - -We take security seriously. -If you discover a security issue, please bring it to our attention right away! - -## Reporting a Vulnerability - -Please **DO NOT** file a public issue, instead send your report privately to [`security @ woodpecker-ci.org`](mailto:security@woodpecker-ci.org). - -Security reports are greatly appreciated, and we will publicly thank you for it. If you choose to remain anonymous, we will respect your request and keep your name confidential. diff --git a/docs/versioned_docs/version-2.1/92-development/_category_.yaml b/docs/versioned_docs/version-2.1/92-development/_category_.yaml deleted file mode 100644 index 02d70e09b5..0000000000 --- a/docs/versioned_docs/version-2.1/92-development/_category_.yaml +++ /dev/null @@ -1,4 +0,0 @@ -label: 'Development' -# position: 3 -collapsible: true -collapsed: true diff --git a/docs/versioned_docs/version-2.1/92-development/ui-proxy.svg b/docs/versioned_docs/version-2.1/92-development/ui-proxy.svg deleted file mode 100644 index 79809ffa19..0000000000 --- a/docs/versioned_docs/version-2.1/92-development/ui-proxy.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - - - - forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler) diff --git a/docs/versioned_docs/version-2.1/92-development/vscode-debug.png b/docs/versioned_docs/version-2.1/92-development/vscode-debug.png deleted file mode 100644 index 58861dbde1..0000000000 Binary files a/docs/versioned_docs/version-2.1/92-development/vscode-debug.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/92-development/vscode-run-test.png b/docs/versioned_docs/version-2.1/92-development/vscode-run-test.png deleted file mode 100644 index 6d163f8b8c..0000000000 Binary files a/docs/versioned_docs/version-2.1/92-development/vscode-run-test.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/92-development/woodpecker-architecture.png b/docs/versioned_docs/version-2.1/92-development/woodpecker-architecture.png deleted file mode 100644 index 22f6a054ae..0000000000 Binary files a/docs/versioned_docs/version-2.1/92-development/woodpecker-architecture.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.1/woodpecker.png b/docs/versioned_docs/version-2.1/woodpecker.png deleted file mode 100644 index b92f3589f5..0000000000 Binary files a/docs/versioned_docs/version-2.1/woodpecker.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/10-intro.md b/docs/versioned_docs/version-2.2/10-intro.md deleted file mode 100644 index 087fbe7ffb..0000000000 --- a/docs/versioned_docs/version-2.2/10-intro.md +++ /dev/null @@ -1,89 +0,0 @@ -# Welcome to Woodpecker - -Woodpecker is a simple yet powerful CI/CD engine with great extensibility. It focuses on executing pipelines inside [containers](https://opencontainers.org/). -If you are already using containers in your daily workflow, you'll for sure love Woodpecker. - -![woodpecker](woodpecker.png) - -## `.woodpecker.yaml` - -- Place your pipeline in a file named `.woodpecker.yaml` in your repository -- Pipeline steps can be named as you like -- Run any command in the commands section - -```yaml title=".woodpecker.yaml" -steps: - build: - image: debian - commands: - - echo "This is the build step" - a-test-step: - image: debian - commands: - - echo "Testing.." -``` - -### Steps are containers - -- Define any container image as context - - either use your own and install the needed tools in a custom image - - or search for available images that are already tailored for your needs in image registries like [Docker Hub](https://hub.docker.com/search?type=image) -- List the commands that should be executed in the container - -```diff - steps: - build: -- image: debian -+ image: mycompany/image-with-awscli - commands: - - aws help -``` - -### File changes are incremental - -- Woodpecker clones the source code in the beginning -- File changes are persisted throughout individual steps as the same volume is being mounted in all steps - -```yaml title=".woodpecker.yaml" -steps: - build: - image: debian - commands: - - touch myfile - a-test-step: - image: debian - commands: - - cat myfile -``` - -## Plugins are straightforward - -- If you copy the same shell script from project to project -- Pack it into a plugin instead -- And make the yaml declarative -- Plugins are Docker images with your script as an entrypoint - -```dockerfile title="Dockerfile" -FROM laszlocloud/kubectl -COPY deploy /usr/local/deploy -ENTRYPOINT ["/usr/local/deploy"] -``` - -```bash title="deploy" -kubectl apply -f $PLUGIN_TEMPLATE -``` - -```yaml title=".woodpecker.yaml" -steps: - deploy-to-k8s: - image: laszlocloud/my-k8s-plugin - settings: - template: config/k8s/service.yaml -``` - -See [plugin docs](./20-usage/51-plugins/10-overview.md). - -## Continue reading - -- [Create a Woodpecker pipeline for your repository](./20-usage/10-intro.md) -- [Setup your own Woodpecker instance](./30-administration/00-deployment/00-overview.md) diff --git a/docs/versioned_docs/version-2.2/20-usage/10-intro.md b/docs/versioned_docs/version-2.2/20-usage/10-intro.md deleted file mode 100644 index d5eaeed894..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/10-intro.md +++ /dev/null @@ -1,72 +0,0 @@ -# Getting started - -## Repository Activation - -To activate your project navigate to your account settings. You will see a list of repositories which can be activated with a simple toggle. When you activate your repository, Woodpecker automatically adds webhooks to your forge (e.g. GitHub, Gitea, ...). - -Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your forge will automatically send a webhook to Woodpecker which will in turn trigger the pipeline execution. - -![repository list](repo-list.png) - -## Required Permissions - -The user who enables a repo in Woodpecker must have `Admin` rights on that repo, so that Woodpecker can add the webhook. - -:::note -Note that manually creating webhooks yourself is not possible. -This is because webhooks are signed using a per-repository secret key which is not exposed to end users. -::: - -## Configuration - -To configure your pipeline you must create a `.woodpecker.yaml` file in the root of your repository. The `.woodpecker.yaml` file is used to define your pipeline steps. - -:::note -We support most of YAML 1.2, but preserve some behavior from 1.1 for backward compatibility. -Read more at: [https://github.com/go-yaml/yaml](https://github.com/go-yaml/yaml/tree/v3) -::: - -Example pipeline configuration: - -```yaml -steps: - build: - image: golang - commands: - - go get - - go build - - go test - -services: - postgres: - image: postgres:9.4.5 - environment: - - POSTGRES_USER=myapp -``` - -Example pipeline configuration with multiple, serial steps: - -```yaml -steps: - backend: - image: golang - commands: - - go get - - go build - - go test - - frontend: - image: node:6 - commands: - - npm install - - npm test - - notify: - image: plugins/slack - channel: developers - username: woodpecker -``` - -## Execution - -To trigger your first pipeline execution you can push code to your repository, open a pull request, or push a tag. Any of these events triggers a webhook from your forge and execute your pipeline. diff --git a/docs/versioned_docs/version-2.2/20-usage/15-terminiology/architecture.excalidraw b/docs/versioned_docs/version-2.2/20-usage/15-terminiology/architecture.excalidraw deleted file mode 100644 index b3eba1aab3..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/15-terminiology/architecture.excalidraw +++ /dev/null @@ -1,1549 +0,0 @@ -{ - "type": "excalidraw", - "version": 2, - "source": "https://excalidraw.com", - "elements": [ - { - "type": "rectangle", - "version": 226, - "versionNonce": 1002880859, - "isDeleted": false, - "id": "UczUX5VuNnCB1rVvUJVfm", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 487.098092529257, - "y": 320.8758615860986, - "strokeColor": "#1971c2", - "backgroundColor": "#e7f5ff", - "width": 472.8823858375721, - "height": 183.19688715994928, - "seed": 917720693, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "Kqbwk_qfkALJfhtCIr2eS", - "type": "arrow" - } - ], - "updated": 1697530113380, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 161, - "versionNonce": 286006267, - "isDeleted": false, - "id": "sKPZmBSWUdAYfBs4ByItH", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 539.5451038202509, - "y": 345.2419383247636, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "width": 82.46875, - "height": 32.199999999999996, - "seed": 1485551573, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113380, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Server", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Server", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "rectangle", - "version": 333, - "versionNonce": 448586907, - "isDeleted": false, - "id": "_A8uznhnpXuQBYzjP-iVx", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 649.8080506852966, - "y": 427.60908869342575, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 136, - "height": 60, - "seed": 1783625013, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "r90dckf8trHemYzEwCgCW" - }, - { - "id": "XxfJWnHonmvNOJzMFSlie", - "type": "arrow" - } - ], - "updated": 1697530113380, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 298, - "versionNonce": 1244067771, - "isDeleted": false, - "id": "r90dckf8trHemYzEwCgCW", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 703.8080506852966, - "y": 441.5090886934257, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 28, - "height": 32.199999999999996, - "seed": 660965013, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113383, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "UI", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "_A8uznhnpXuQBYzjP-iVx", - "originalText": "UI", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "rectangle", - "version": 105, - "versionNonce": 265992667, - "isDeleted": false, - "id": "v2eEwSOSRQBZ79O6wyzGf", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 800.9240766836483, - "y": 421.4987043996123, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 135.3671503686619, - "height": 62.2689029398432, - "seed": 1115810805, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "svsVhxCbatcLj7lQLch0P" - }, - { - "id": "TvtonmlV0W8__pnTG-wVZ", - "type": "arrow" - }, - { - "id": "5tl702dfcvJDLz9aIFU0P", - "type": "arrow" - } - ], - "updated": 1697530113380, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 83, - "versionNonce": 1706870395, - "isDeleted": false, - "id": "svsVhxCbatcLj7lQLch0P", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 828.1594096804793, - "y": 436.53315586953386, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 80.896484375, - "height": 32.199999999999996, - "seed": 2074781013, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113380, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "GRPC", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "v2eEwSOSRQBZ79O6wyzGf", - "originalText": "GRPC", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "rectangle", - "version": 270, - "versionNonce": 418660123, - "isDeleted": false, - "id": "hSrrwwnm9y7R-_CnJtaK1", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1065.567103519039, - "y": 556.4146894573112, - "strokeColor": "#2f9e44", - "backgroundColor": "#ebfbee", - "width": 601.932705468054, - "height": 175.07489600604117, - "seed": 1983197877, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "TvtonmlV0W8__pnTG-wVZ", - "type": "arrow" - } - ], - "updated": 1697530113380, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 154, - "versionNonce": 871605179, - "isDeleted": false, - "id": "8tsYgVssKnBd_Zw1QuqNz", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1298.4367898442752, - "y": 566.567242947784, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 96.5234375, - "height": 32.199999999999996, - "seed": 1321669653, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Agent 1", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Agent 1", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "text", - "version": 182, - "versionNonce": 1323136091, - "isDeleted": false, - "id": "eeugZg73_yD_6uLBBgmcX", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 404.5001910129067, - "y": 707.1233710221009, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 210.068359375, - "height": 32.199999999999996, - "seed": 1901447541, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "User => Browser", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "User => Browser", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "ellipse", - "version": 106, - "versionNonce": 1501835515, - "isDeleted": false, - "id": "mlDhl4OOc-H1tNgh77AAW", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 482.5857164810477, - "y": 602.4394551739279, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 46.024748503793035, - "height": 44.21988070606176, - "seed": 791073493, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "line", - "version": 166, - "versionNonce": 627726747, - "isDeleted": false, - "id": "ADEXzdYAhvj-_wVRftTIg", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 459.12202200277807, - "y": 697.1964604319912, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 80.31792517362464, - "height": 31.585599568061298, - "seed": 349155381, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": null, - "endBinding": null, - "lastCommittedPoint": null, - "startArrowhead": null, - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 42.415150610916044, - -28.87829787146393 - ], - [ - 80.31792517362464, - 2.7073016965973693 - ] - ] - }, - { - "type": "rectangle", - "version": 231, - "versionNonce": 801271355, - "isDeleted": false, - "id": "xmz4J-rxLIjfUQ4q19PjD", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 516.8788931508789, - "y": 870.4664542146543, - "strokeColor": "#f08c00", - "backgroundColor": "#fff4e6", - "width": 385.34512717560705, - "height": 60.464035142111264, - "seed": 3531157, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "05EJzh4NLXxemaKAmdi5n", - "type": "arrow" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 93, - "versionNonce": 728690395, - "isDeleted": false, - "id": "gSbpry_947XArfI7b6AAL", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 636.1468430141358, - "y": 878.5884970070326, - "strokeColor": "#f08c00", - "backgroundColor": "transparent", - "width": 132.2890625, - "height": 32.199999999999996, - "seed": 1989076725, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Autoscaler", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Autoscaler", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "text", - "version": 118, - "versionNonce": 1258445691, - "isDeleted": false, - "id": "WVy0mdTGbUx08RuxdQUH8", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 523.3741602213286, - "y": 907.372811672524, - "strokeColor": "#f08c00", - "backgroundColor": "transparent", - "width": 369.1484375, - "height": 18.4, - "seed": 979386453, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "Starts agents based on amount of pending pipelines", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Starts agents based on amount of pending pipelines", - "lineHeight": 1.15, - "baseline": 14 - }, - { - "type": "text", - "version": 373, - "versionNonce": 1254044699, - "isDeleted": false, - "id": "0Y1RcqzVFBFqh-wy-APMI", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1232.1955835481922, - "y": 605.8737363119278, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 292.6171875, - "height": 18.4, - "seed": 561999285, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "Executes pending workflows of a pipeline", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Executes pending workflows of a pipeline", - "lineHeight": 1.15, - "baseline": 14 - }, - { - "type": "text", - "version": 630, - "versionNonce": 983038139, - "isDeleted": false, - "id": "lGumbhMs3xx1vU2632hli", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 505.62283787078286, - "y": 383.42044095379515, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "width": 158.015625, - "height": 36.8, - "seed": 722595605, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "Central unit of a \nWoodpecker instance ", - "textAlign": "center", - "verticalAlign": "top", - "containerId": null, - "originalText": "Central unit of a \nWoodpecker instance ", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "rectangle", - "version": 131, - "versionNonce": 137308507, - "isDeleted": false, - "id": "PbSQXehWVLYcQGXYFpd-B", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 971.7123256059622, - "y": 171.06951064323448, - "strokeColor": "#be4bdb", - "backgroundColor": "#f8f0fc", - "width": 274.3443117379593, - "height": 74.90311522655017, - "seed": 1435321461, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "Kqbwk_qfkALJfhtCIr2eS", - "type": "arrow" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 96, - "versionNonce": 1222067707, - "isDeleted": false, - "id": "2P2tz29C_2sUzVNSpaG17", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1065.5206131439782, - "y": 183.12082907329545, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 73.14453125, - "height": 32.199999999999996, - "seed": 884403669, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Forge", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Forge", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "text", - "version": 141, - "versionNonce": 1133694619, - "isDeleted": false, - "id": "0eYhFYPuRanZ7wkR2OlHO", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 986.864582863368, - "y": 225.1223531590797, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 247.234375, - "height": 18.4, - "seed": 1201957685, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "HK1jmIcPmM6Us6Jrynobb", - "type": "arrow" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "Github, Gitea, Github, Bitbucket, ...", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Github, Gitea, Github, Bitbucket, ...", - "lineHeight": 1.15, - "baseline": 14 - }, - { - "type": "rectangle", - "version": 55, - "versionNonce": 991183675, - "isDeleted": false, - "id": "dihpRzuIc-UoRSsOI33SZ", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 820.419424341303, - "y": 340.29123237109366, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 117, - "height": 60, - "seed": 247151765, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "bcUL-u4zkLA9CLG2YdaeN" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 38, - "versionNonce": 2008949723, - "isDeleted": false, - "id": "bcUL-u4zkLA9CLG2YdaeN", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 831.853994653803, - "y": 358.79123237109366, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 94.130859375, - "height": 23, - "seed": 1638982133, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Webhooks", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "dihpRzuIc-UoRSsOI33SZ", - "originalText": "Webhooks", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 93, - "versionNonce": 295891067, - "isDeleted": false, - "id": "Bphhue86mMXHN4klGamM3", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 697.3018309300141, - "y": 339.607928999312, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 117, - "height": 60, - "seed": 92986197, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "0YxY2hEPyDWFqR8_-f6bn" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 87, - "versionNonce": 2055547163, - "isDeleted": false, - "id": "0YxY2hEPyDWFqR8_-f6bn", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 727.4522215550141, - "y": 358.107928999312, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 56.69921875, - "height": 23, - "seed": 43952309, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "OAuth", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "Bphhue86mMXHN4klGamM3", - "originalText": "OAuth", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "arrow", - "version": 284, - "versionNonce": 1205292475, - "isDeleted": false, - "id": "HK1jmIcPmM6Us6Jrynobb", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1205.6453201409104, - "y": 250.4849674923464, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 272.1094712799886, - "height": 94.31865813977868, - "seed": 982632981, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "uDIWJ5K5mEBL9QaiNk3cS" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": { - "elementId": "0eYhFYPuRanZ7wkR2OlHO", - "focus": -0.8418551162334328, - "gap": 6.962614333266799 - }, - "endBinding": null, - "lastCommittedPoint": null, - "startArrowhead": null, - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - -69.68740859223726, - 65.87860410965993 - ], - [ - -272.1094712799886, - 94.31865813977868 - ] - ] - }, - { - "type": "text", - "version": 53, - "versionNonce": 1803962459, - "isDeleted": false, - "id": "uDIWJ5K5mEBL9QaiNk3cS", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1050.575099048673, - "y": 297.96357160200637, - "strokeColor": "#be4bdb", - "backgroundColor": "#b2f2bb", - "width": 170.765625, - "height": 36.8, - "seed": 1046069109, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113385, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "sends events like push, \ntag, ...", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "HK1jmIcPmM6Us6Jrynobb", - "originalText": "sends events like push, tag, ...", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "arrow", - "version": 487, - "versionNonce": 335895291, - "isDeleted": false, - "id": "Kqbwk_qfkALJfhtCIr2eS", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 792.0835609101814, - "y": 316.38601649373913, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 176.92139414789008, - "height": 122.73778943055902, - "seed": 1681656021, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "yvJTQ64RU50N6-hxEQlkl" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": { - "elementId": "UczUX5VuNnCB1rVvUJVfm", - "focus": -0.03867359238356983, - "gap": 4.489845092359474 - }, - "endBinding": { - "elementId": "PbSQXehWVLYcQGXYFpd-B", - "focus": 0.7798878042817562, - "gap": 2.707370547890605 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 60.422360349016344, - -71.97786730696657 - ], - [ - 176.92139414789008, - -122.73778943055902 - ] - ] - }, - { - "type": "text", - "version": 62, - "versionNonce": 301106427, - "isDeleted": false, - "id": "yvJTQ64RU50N6-hxEQlkl", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 773.7910775091977, - "y": 226.00814918677256, - "strokeColor": "#be4bdb", - "backgroundColor": "#b2f2bb", - "width": 157.4296875, - "height": 36.8, - "seed": 500049461, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113385, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "allows users to login \nusing existing account", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "Kqbwk_qfkALJfhtCIr2eS", - "originalText": "allows users to login using existing account", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "arrow", - "version": 393, - "versionNonce": 598459861, - "isDeleted": false, - "id": "TvtonmlV0W8__pnTG-wVZ", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 936.9267543177084, - "y": 458.95033086418084, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 215.17788326846676, - "height": 93.99151368376693, - "seed": 234198933, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "rFf6NIofw6UBOyAFwg0Kn" - } - ], - "updated": 1697530127259, - "link": null, - "locked": false, - "startBinding": { - "elementId": "v2eEwSOSRQBZ79O6wyzGf", - "focus": -0.30339107267010673, - "gap": 1 - }, - "endBinding": { - "elementId": "hSrrwwnm9y7R-_CnJtaK1", - "focus": -0.14057158065513534, - "gap": 3.4728449093634026 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 130.0760301643047, - 42.90930518030268 - ], - [ - 215.17788326846676, - 93.99151368376693 - ] - ] - }, - { - "type": "text", - "version": 8, - "versionNonce": 1693330843, - "isDeleted": false, - "id": "rFf6NIofw6UBOyAFwg0Kn", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 997.4942845557462, - "y": 473.9409015069133, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 161.4140625, - "height": 36.8, - "seed": 1592253685, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113386, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "receives workflows & \nreturns logs + statuses", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "TvtonmlV0W8__pnTG-wVZ", - "originalText": "receives workflows & returns logs + statuses", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "arrow", - "version": 270, - "versionNonce": 1855882619, - "isDeleted": false, - "id": "5tl702dfcvJDLz9aIFU0P", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 886.0581619083632, - "y": 485.67004123832135, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 174.09447592006472, - "height": 326.4905563076211, - "seed": 1479177813, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "apyMCAv2GIN_yzHXwX4tY" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": { - "elementId": "v2eEwSOSRQBZ79O6wyzGf", - "focus": -0.1341191028023529, - "gap": 1.9024338988657519 - }, - "endBinding": { - "elementId": "pxF49EKDNO6IZq_34i7bY", - "focus": -0.7088661407505865, - "gap": 4.060573862784622 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 44.14165353942735, - 196.18483635907205 - ], - [ - 174.09447592006472, - 326.4905563076211 - ] - ] - }, - { - "type": "text", - "version": 66, - "versionNonce": 2007745083, - "isDeleted": false, - "id": "apyMCAv2GIN_yzHXwX4tY", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 849.4927841977906, - "y": 663.4548775973934, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 161.4140625, - "height": 36.8, - "seed": 882041781, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113386, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "receives workflows & \nreturns logs + statuses", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "5tl702dfcvJDLz9aIFU0P", - "originalText": "receives workflows & returns logs + statuses", - "lineHeight": 1.15, - "baseline": 32 - }, - { - "type": "arrow", - "version": 347, - "versionNonce": 1353818811, - "isDeleted": false, - "id": "XxfJWnHonmvNOJzMFSlie", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 534.9278465333664, - "y": 595.2199151317081, - "strokeColor": "#c2255c", - "backgroundColor": "transparent", - "width": 113.88020415193023, - "height": 119.81968366814112, - "seed": 944153877, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": null, - "endBinding": { - "elementId": "_A8uznhnpXuQBYzjP-iVx", - "focus": 0.5397285671082249, - "gap": 1 - }, - "lastCommittedPoint": null, - "startArrowhead": null, - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 113.88020415193023, - -119.81968366814112 - ] - ] - }, - { - "type": "rectangle", - "version": 61, - "versionNonce": 1099141979, - "isDeleted": false, - "id": "j56ZKRwmXk72nHrZzLz_1", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1081.8110514012087, - "y": 652.5253283508498, - "strokeColor": "#2f9e44", - "backgroundColor": "#ebfbee", - "width": 566.7373014532342, - "height": 68.58600908319681, - "seed": 112933493, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 82, - "versionNonce": 1879994363, - "isDeleted": false, - "id": "cAVYXfBRnfuGAv7QTQVow", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1300.6584159706863, - "y": 658.8425033454967, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 77.83203125, - "height": 23, - "seed": 951460821, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Backend", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Backend", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "text", - "version": 376,- add some images explaining the architecture & terminology with -pipeline -> workflow -> step -- combine advanced config usage -- rename pipeline syntax to workflow syntax (and most references to -pipeline steps etc as well) -- update agent registration part -- add bug note to secrets encryption setting -- remove usage from readme to point to up-to-date docs page -- typos -- closes #1408 - ---------- - "angle": 0, - "x": 1094.1972977313717, - "y": 681.8988272758752, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 530.9453125, - "height": 55.199999999999996, - "seed": 843899189, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "The backend is the environment (exp. Docker / Kubernetes / local) used to \nexecute workflows in.\n", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "The backend is the environment (exp. Docker / Kubernetes / local) used to \nexecute workflows in.\n", - "lineHeight": 1.15, - "baseline": 50 - }, - { - "type": "rectangle", - "version": 384, - "versionNonce": 1778969915, - "isDeleted": false, - "id": "pxF49EKDNO6IZq_34i7bY", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1064.2132116912126, - "y": 754.5018564383092, - "strokeColor": "#2f9e44", - "backgroundColor": "#ebfbee", - "width": 601.932705468054, - "height": 175.07489600604117, - "seed": 954528405, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "05EJzh4NLXxemaKAmdi5n", - "type": "arrow" - }, - { - "id": "5tl702dfcvJDLz9aIFU0P", - "type": "arrow" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false - }, - { - "type": "arrow", - "version": 154, - "versionNonce": 1988988379, - "isDeleted": false, - "id": "05EJzh4NLXxemaKAmdi5n", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 904.0288881242177, - "y": 882.4966027880746, - "strokeColor": "#f08c00", - "backgroundColor": "transparent", - "width": 158.83070714434325, - "height": 32.735025983189644, - "seed": 1228134389, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [ - { - "type": "text", - "id": "yNxAOEPZu_Jl7mnI01OXs" - } - ], - "updated": 1697530113381, - "link": null, - "locked": false, - "startBinding": { - "elementId": "xmz4J-rxLIjfUQ4q19PjD", - "gap": 1.8048677977312764, - "focus": 0.31250963573550006 - }, - "endBinding": { - "elementId": "pxF49EKDNO6IZq_34i7bY", - "gap": 1.353616422651612, - "focus": 0.36496042109885213 - }, - "lastCommittedPoint": null, - "startArrowhead": null, - "endArrowhead": "triangle", - "points": [ - [ - 0, - 0 - ], - [ - 158.83070714434325, - -32.735025983189644 - ] - ] - }, - { - "type": "text", - "version": 25, - "versionNonce": 1393410779, - "isDeleted": false, - "id": "yNxAOEPZu_Jl7mnI01OXs", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 963.8856479463893, - "y": 856.9290897964797, - "strokeColor": "#f08c00", - "backgroundColor": "#b2f2bb", - "width": 39.1171875, - "height": 18.4, - "seed": 759107925, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113387, - "link": null, - "locked": false, - "fontSize": 16, - "fontFamily": 2, - "text": "starts", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "05EJzh4NLXxemaKAmdi5n", - "originalText": "starts", - "lineHeight": 1.15, - "baseline": 14 - }, - { - "type": "text", - "version": 187, - "versionNonce": 671224603, - "isDeleted": false, - "id": "sSj4Pda-fo-BBYM_dzml6", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 1296.0854928322988, - "y": 776.6118140041631, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 104.2890625, - "height": 32.199999999999996, - "seed": 1381768885, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530113381, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Agent ...", - "textAlign": "right", - "verticalAlign": "top", - "containerId": null, - "originalText": "Agent ...", - "lineHeight": 1.15, - "baseline": 25 - } - ], - "appState": { - "gridSize": null, - "viewBackgroundColor": "#ffffff" - }, - "files": {} -} diff --git a/docs/versioned_docs/version-2.2/20-usage/15-terminiology/architecture.svg b/docs/versioned_docs/version-2.2/20-usage/15-terminiology/architecture.svg deleted file mode 100644 index b34e96fdd8..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/15-terminiology/architecture.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - - - - - ServerUIGRPCAgent 1User => BrowserAutoscalerStarts agents based on amount of pending pipelinesExecutes pending workflows of a pipelineCentral unit of a Woodpecker instance ForgeGithub, Gitea, Github, Bitbucket, ...WebhooksOAuthsends events like push, tag, ...allows users to login using existing accountreceives workflows & returns logs + statusesreceives workflows & returns logs + statusesBackendThe backend is the environment (exp. Docker / Kubernetes / local) used to execute workflows in.startsAgent ... diff --git a/docs/versioned_docs/version-2.2/20-usage/15-terminiology/index.md b/docs/versioned_docs/version-2.2/20-usage/15-terminiology/index.md deleted file mode 100644 index 9f24e46173..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/15-terminiology/index.md +++ /dev/null @@ -1,61 +0,0 @@ -# Terminology - -## Woodpecker architecture - -![Woodpecker architecture](architecture.svg) - -## Pipeline, workflow & step - -![Relation between pipelines, workflows and steps](pipeline-workflow-step.svg) - -## Glossary - -- **Woodpecker CI**: The project name around Woodpecker. -- **Woodpecker**: An open-source tool that executes [pipelines][Pipeline] on your code. -- **Server**: The component of Woodpecker that handles webhooks from forges, orchestrates agents, and sends status back. It also serves the API and web UI for administration and configuration. -- **Agent**: A component of Woodpecker that executes [pipelines][Pipeline] (specifically one or more [workflows][Workflow]) with a specific backend (e.g. [Docker][], Kubernetes, [local][Local]). It connects to the server via GRPC. -- **CLI**: The Woodpecker command-line interface (CLI) is a terminal tool used to administer the server, to execute pipelines locally for debugging / testing purposes, and to perform tasks like linting pipelines. -- **Pipeline**: A sequence of [workflows][Workflow] that are executed on the code. [Pipelines][Pipeline] are triggered by events. -- **Workflow**: A sequence of steps and services that are executed as part of a [pipeline][Pipeline]. Workflows are represented by YAML files. Each [workflow][Workflow] has its own isolated [workspace][Workspace], and often additional resources like a shared network (docker). -- **Steps**: Individual commands, actions or tasks within a [workflow][Workflow]. -- **Code**: Refers to the files tracked by the version control system used by the [forge][Forge]. -- **Repos**: Short for repositories, these are storage locations where code is stored. -- **Forge**: The hosting platform or service where the repositories are hosted. -- **Workspace**: A folder shared between all steps of a [workflow][Workflow] containing the repository and all the generated data from previous steps. -- **Event**: Triggers the execution of a [pipeline][Pipeline], such as a [forge][Forge] event like `push`, or `manual` triggered manually from the UI. -- **Commit**: A defined state of the code, usually associated with a version control system like Git. -- **Matrix**: A configuration option that allows the execution of [workflows][Workflow] for each value in the [matrix][Matrix]. -- **Service**: A service is a step that is executed from the start of a [workflow][Workflow] until its end. It can be accessed by name via the network from other steps within the same [workflow][Workflow]. -- **Plugins**: [Plugins][Plugin] are extensions that provide pre-defined actions or commands for a step in a [workflow][Workflow]. They can be configured via settings. -- **Container**: A lightweight and isolated environment where commands are executed. -- **YAML File**: A file format used to define and configure [workflows][Workflow]. -- **Dependency**: [Workflows][Workflow] can depend on each other, and if possible, they are executed in parallel. -- **Status**: Status refers to the outcome of a step or [workflow][Workflow] after it has been executed, determined by the internal command exit code. At the end of a [workflow][Workflow], its status is sent to the [forge][Forge]. - -## Pipeline events - -- `push`: A push event is triggered when a commit is pushed to a branch. -- `pull_request`: A pull request event is triggered when a pull request is opened or a new commit is pushed to it. -- `pull_request_closed`: A pull request closed event is triggered when a pull request is closed or merged. -- `tag`: A tag event is triggered when a tag is pushed. -- `manual`: A manual event is triggered when a user manually triggers a pipeline. -- `cron`: A cron event is triggered when a cron job is executed. - -## Conventions - -Sometimes there are multiple terms that can be used to describe something. This section lists the preferred terms to use in Woodpecker: - -- Environment variables `*_LINK` should be called `*_URL`. In the code use `URL()` instead of `Link()` -- Use the term **pipelines** instead of the previous **builds** -- Use the term **steps** instead of the previous **jobs** - - - -[Pipeline]: ../20-workflow-syntax.md -[Workflow]: ../25-workflows.md -[Forge]: ../../30-administration/11-forges/10-overview.md -[Plugin]: ../51-plugins/10-overview.md -[Workspace]: ../20-workflow-syntax.md#workspace -[Matrix]: ../30-matrix-workflows.md -[Docker]: ../../30-administration/22-backends/10-docker.md -[Local]: ../../30-administration/22-backends/20-local.md diff --git a/docs/versioned_docs/version-2.2/20-usage/15-terminiology/pipeline-workflow-step.excalidraw b/docs/versioned_docs/version-2.2/20-usage/15-terminiology/pipeline-workflow-step.excalidraw deleted file mode 100644 index 28704cff54..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/15-terminiology/pipeline-workflow-step.excalidraw +++ /dev/null @@ -1,1077 +0,0 @@ -{ - "type": "excalidraw", - "version": 2, - "source": "https://excalidraw.com", - "elements": [ - { - "type": "rectangle", - "version": 97, - "versionNonce": 257762037, - "isDeleted": false, - "id": "Y3hYdpX9r1qWfyHWs7AXT", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 393.622323134362, - "y": 336.02197155458475, - "strokeColor": "#1971c2", - "backgroundColor": "#e7f5ff", - "width": 366.3936710429598, - "height": 499.95605689083004, - "seed": 875444373, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 67, - "versionNonce": 369556565, - "isDeleted": false, - "id": "g1Eb010Kx_KFryVqNYWBQ", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 520.0116988873679, - "y": 363.32095846456355, - "strokeColor": "#1971c2", - "backgroundColor": "#b2f2bb", - "width": 99.626953125, - "height": 32.199999999999996, - "seed": 1466195445, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "9laL3864YWOna6NQlVDqq", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 28, - "fontFamily": 2, - "text": "Pipeline", - "textAlign": "center", - "verticalAlign": "top", - "containerId": null, - "originalText": "Pipeline", - "lineHeight": 1.15, - "baseline": 25 - }, - { - "type": "rectangle", - "version": 314, - "versionNonce": 1983028731, - "isDeleted": false, - "id": "9o-DNP0YdlIGVz1kEm_hW", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 407.1590381712276, - "y": 410.9252244837219, - "strokeColor": "#be4bdb", - "backgroundColor": "#f8f0fc", - "width": 340.12211164367193, - "height": 199, - "seed": 1869535061, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "id": "FU4jk6Tz6duLaaZE0Z55A", - "type": "arrow" - }, - { - "id": "9laL3864YWOna6NQlVDqq", - "type": "arrow" - } - ], - "updated": 1697530083624, - "link": null, - "locked": false - }, - { - "type": "rectangle", - "version": 156, - "versionNonce": 1495247317, - "isDeleted": false, - "id": "q4TKpiq2KAwPaz19GdhtK", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 490.3194993196821, - "y": 473.52959018719525, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 111355061, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "ya0JzDo-4oscHIq87TZ_D" - }, - { - "id": "1ZbDRqbETCkEx62nCmnpJ", - "type": "arrow" - }, - { - "id": "FU4jk6Tz6duLaaZE0Z55A", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 156, - "versionNonce": 1469425461, - "isDeleted": false, - "id": "ya0JzDo-4oscHIq87TZ_D", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 566.0118821321821, - "y": 478.52959018719525, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 95.615234375, - "height": 23, - "seed": 1084671509, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Clone step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "q4TKpiq2KAwPaz19GdhtK", - "originalText": "Clone step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 236, - "versionNonce": 1535319541, - "isDeleted": false, - "id": "AOJLQFldoHd2vxVtB2jrS", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 491.2218643672577, - "y": 519.7800332298218, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 812596085, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "FRby8A9aUiKvHpM5mCdDN" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 231, - "versionNonce": 28677973, - "isDeleted": false, - "id": "FRby8A9aUiKvHpM5mCdDN", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 583.0324112422577, - "y": 524.7800332298218, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 63.37890625, - "height": 23, - "seed": 1849820373, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "1. Step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "AOJLQFldoHd2vxVtB2jrS", - "originalText": "1. Step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 291, - "versionNonce": 571598005, - "isDeleted": false, - "id": "2WwuMWX7YawqK0i1rDPJo", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 489.6426911083554, - "y": 567.609787233933, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 1840554549, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "UOwxmKIS0W62CFt_ffEy4" - }, - { - "id": "379hO6Dc5rygB38JgDbVo", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 289, - "versionNonce": 4032021, - "isDeleted": false, - "id": "UOwxmKIS0W62CFt_ffEy4", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 581.4532379833554, - "y": 572.609787233933, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 63.37890625, - "height": 23, - "seed": 330077077, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "2. Step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "2WwuMWX7YawqK0i1rDPJo", - "originalText": "2. Step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "arrow", - "version": 296, - "versionNonce": 1539516059, - "isDeleted": false, - "id": "9laL3864YWOna6NQlVDqq", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 630.0635849044402, - "y": 383.14314287821776, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "width": 294.3024370154917, - "height": 36.656016722015465, - "seed": 207575285, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": { - "elementId": "9o-DNP0YdlIGVz1kEm_hW", - "focus": -1.000156025347643, - "gap": 27.782081605504118 - }, - "endBinding": { - "elementId": "vS2PNUbmeBe3EPxl-dID8", - "focus": 0.7761987167055517, - "gap": 8.978940924346716 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 294.3024370154917, - -36.656016722015465 - ] - ] - }, - { - "type": "text", - "version": 249, - "versionNonce": 2076402229, - "isDeleted": false, - "id": "vS2PNUbmeBe3EPxl-dID8", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 933.3449628442786, - "y": 336.02200598023114, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "width": 301.298828125, - "height": 46, - "seed": 1632793173, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "9laL3864YWOna6NQlVDqq", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "A pipeline is triggered by an event\nlike a push, tag, manual", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "A pipeline is triggered by an event\nlike a push, tag, manual", - "lineHeight": 1.15, - "baseline": 41 - }, - { - "type": "arrow", - "version": 751, - "versionNonce": 1371044827, - "isDeleted": false, - "id": "FU4jk6Tz6duLaaZE0Z55A", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 751.1619011845514, - "y": 440.8355079324799, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 160.46519124360202, - "height": 2.2452348338335923, - "seed": 1331388341, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": { - "elementId": "9o-DNP0YdlIGVz1kEm_hW", - "focus": -0.6591700594229558, - "gap": 3.8807513696519322 - }, - "endBinding": { - "elementId": "wfFvnFZuh0npL9hh0ez7o", - "focus": 0.7652411053273549, - "gap": 20.75618622779257 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 160.46519124360202, - -2.2452348338335923 - ] - ] - }, - { - "type": "rectangle", - "version": 440, - "versionNonce": 819540565, - "isDeleted": false, - "id": "TbejdIYo_qNDw15yLP2IB", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 406.0812257713851, - "y": 626.8305540252475, - "strokeColor": "#be4bdb", - "backgroundColor": "#f8f0fc", - "width": 340.12211164367193, - "height": 199, - "seed": 1553965333, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 466, - "versionNonce": 663477, - "isDeleted": false, - "id": "wfFvnFZuh0npL9hh0ez7o", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 932.383278655946, - "y": 424.0107569968011, - "strokeColor": "#be4bdb", - "backgroundColor": "transparent", - "width": 481.2890625, - "height": 115, - "seed": 781497973, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "FU4jk6Tz6duLaaZE0Z55A", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Every pipeline consists of multiple workflows.\nEach defined by a separate YAML file and is named \nafter the filename.\nEach workflow has its own workspace (folder) which is\nused by all steps of that workflow.", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "Every pipeline consists of multiple workflows.\nEach defined by a separate YAML file and is named \nafter the filename.\nEach workflow has its own workspace (folder) which is\nused by all steps of that workflow.", - "lineHeight": 1.15, - "baseline": 110 - }, - { - "type": "arrow", - "version": 464, - "versionNonce": 734626075, - "isDeleted": false, - "id": "1ZbDRqbETCkEx62nCmnpJ", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 741.0645380446722, - "y": 492.31283255558515, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 178.4459423531871, - "height": 83.08707392565111, - "seed": 536879061, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": { - "elementId": "q4TKpiq2KAwPaz19GdhtK", - "focus": -0.7697471991854113, - "gap": 3.7450387249900814 - }, - "endBinding": { - "elementId": "Vu0JJ6ZWuEhEyCfxeHPtc", - "focus": -0.7822252364700005, - "gap": 8.360835317635974 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 178.4459423531871, - 83.08707392565111 - ] - ] - }, - { - "type": "text", - "version": 327, - "versionNonce": 371646421, - "isDeleted": false, - "id": "Vu0JJ6ZWuEhEyCfxeHPtc", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 927.8713157154953, - "y": 563.2132686484658, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "width": 491.357421875, - "height": 46, - "seed": 385310005, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "1ZbDRqbETCkEx62nCmnpJ", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "The default first step of each workflow is the clone step.\nIts fetches the specific code version for a pipeline.", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "The default first step of each workflow is the clone step.\nIts fetches the specific code version for a pipeline.", - "lineHeight": 1.15, - "baseline": 41 - }, - { - "type": "text", - "version": 91, - "versionNonce": 1180085909, - "isDeleted": false, - "id": "0tGx2VdJLNf7W6HD76dtO", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 427.6895298601876, - "y": 432.3583566254258, - "strokeColor": "#9c36b5", - "backgroundColor": "#a5d8ff", - "width": 143.876953125, - "height": 23, - "seed": 450883221, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Workflow \"build\"", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "Workflow \"build\"", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 338, - "versionNonce": 957223925, - "isDeleted": false, - "id": "LQ2h2aO9uzDWyLG6OLn70", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 487.7251825950889, - "y": 685.3516128043414, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 711939061, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "8EqaPnZX2CgLaF08UNZZg" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 340, - "versionNonce": 510774613, - "isDeleted": false, - "id": "8EqaPnZX2CgLaF08UNZZg", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 563.4175654075889, - "y": 690.3516128043414, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 95.615234375, - "height": 23, - "seed": 1370164565, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Clone step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "LQ2h2aO9uzDWyLG6OLn70", - "originalText": "Clone step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 421, - "versionNonce": 97999541, - "isDeleted": false, - "id": "St9t4nwHuXXVlmjDqfn_Z", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 488.62754764266447, - "y": 731.6020558469675, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 2145950389, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "DX10t075MMDu7BLtuUaij" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 417, - "versionNonce": 2011446293, - "isDeleted": false, - "id": "DX10t075MMDu7BLtuUaij", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 580.4380945176645, - "y": 736.6020558469675, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 63.37890625, - "height": 23, - "seed": 500005909, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "1. Step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "St9t4nwHuXXVlmjDqfn_Z", - "originalText": "1. Step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "rectangle", - "version": 475, - "versionNonce": 1284370805, - "isDeleted": false, - "id": "XVGBz_X5yN6xjWTosVH2n", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 487.04837438376217, - "y": 779.4318098510787, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 247, - "height": 33, - "seed": 1666134389, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "boundElements": [ - { - "type": "text", - "id": "-xogFSFcP-Vv5cuOSFm8T" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false - }, - { - "type": "text", - "version": 476, - "versionNonce": 1092221653, - "isDeleted": false, - "id": "-xogFSFcP-Vv5cuOSFm8T", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 578.8589212587622, - "y": 784.4318098510787, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 63.37890625, - "height": 23, - "seed": 1840462549, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "2. Step", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "XVGBz_X5yN6xjWTosVH2n", - "originalText": "2. Step", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "text", - "version": 125, - "versionNonce": 1310578741, - "isDeleted": false, - "id": "N1a9yL7Pts16hUKY9-vhw", - "fillStyle": "hachure", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 424.78852030984035, - "y": 646.2446482189896, - "strokeColor": "#be4bdb", - "backgroundColor": "#a5d8ff", - "width": 133.857421875, - "height": 23, - "seed": 361699381, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Workflow \"test\"", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "Workflow \"test\"", - "lineHeight": 1.15, - "baseline": 18 - }, - { - "type": "arrow", - "version": 184, - "versionNonce": 2127603131, - "isDeleted": false, - "id": "O-YmtRLb8uFNqCAz22EoG", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 737.454940151797, - "y": 535.9141784615474, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 190.41665096887027, - "height": 112.96427727851824, - "seed": 80234901, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": null, - "endBinding": { - "elementId": "0TjxOfERekC91N3yciQIq", - "focus": -0.8392895251910331, - "gap": 2.0300115262207328 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 190.41665096887027, - 112.96427727851824 - ] - ] - }, - { - "type": "arrow", - "version": 327, - "versionNonce": 780710651, - "isDeleted": false, - "id": "379hO6Dc5rygB38JgDbVo", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 738.8084877231549, - "y": 591.3526691276127, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 186.8066399682357, - "height": 57.68023784868956, - "seed": 211046133, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 2 - }, - "boundElements": [], - "updated": 1697530083624, - "link": null, - "locked": false, - "startBinding": { - "elementId": "2WwuMWX7YawqK0i1rDPJo", - "focus": -0.5776522830934517, - "gap": 2.1657966147995467 - }, - "endBinding": { - "elementId": "0TjxOfERekC91N3yciQIq", - "focus": -0.7269489945238884, - "gap": 4.286474955497397 - }, - "lastCommittedPoint": null, - "startArrowhead": "triangle", - "endArrowhead": null, - "points": [ - [ - 0, - 0 - ], - [ - 186.8066399682357, - 57.68023784868956 - ] - ] - }, - { - "type": "text", - "version": 285, - "versionNonce": 1165977685, - "isDeleted": false, - "id": "0TjxOfERekC91N3yciQIq", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "x": 929.901602646888, - "y": 632.4760859429873, - "strokeColor": "#2f9e44", - "backgroundColor": "#b2f2bb", - "width": 518.076171875, - "height": 46, - "seed": 997763157, - "groupIds": [], - "frameId": null, - "roundness": null, - "boundElements": [ - { - "id": "O-YmtRLb8uFNqCAz22EoG", - "type": "arrow" - }, - { - "id": "379hO6Dc5rygB38JgDbVo", - "type": "arrow" - } - ], - "updated": 1697530083427, - "link": null, - "locked": false, - "fontSize": 20, - "fontFamily": 2, - "text": "Additional steps are used to execute commands or plugins\nlike `make install` or release-to-github", - "textAlign": "left", - "verticalAlign": "top", - "containerId": null, - "originalText": "Additional steps are used to execute commands or plugins\nlike `make install` or release-to-github", - "lineHeight": 1.15, - "baseline": 41 - } - ], - "appState": { - "gridSize": null, - "viewBackgroundColor": "#ffffff" - }, - "files": {} -} diff --git a/docs/versioned_docs/version-2.2/20-usage/15-terminiology/pipeline-workflow-step.svg b/docs/versioned_docs/version-2.2/20-usage/15-terminiology/pipeline-workflow-step.svg deleted file mode 100644 index 4ea3aab0ac..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/15-terminiology/pipeline-workflow-step.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - - - - - PipelineClone step1. Step2. StepA pipeline is triggered by an eventlike a push, tag, manualEvery pipeline consists of multiple workflows.Each defined by a separate YAML file and is named after the filename.Each workflow has its own workspace (folder) which isused by all steps of that workflow.The default first step of each workflow is the clone step.Its fetches the specific code version for a pipeline.Workflow "build"Clone step1. Step2. StepWorkflow "test"Additional steps are used to execute commands or pluginslike `make install` or release-to-github diff --git a/docs/versioned_docs/version-2.2/20-usage/20-workflow-syntax.md b/docs/versioned_docs/version-2.2/20-usage/20-workflow-syntax.md deleted file mode 100644 index d79ec6a392..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/20-workflow-syntax.md +++ /dev/null @@ -1,877 +0,0 @@ -# Workflow syntax - -The workflow section defines a list of steps to build, test and deploy your code. Steps are executed serially, in the order in which they are defined. If a step returns a non-zero exit code, the workflow and therefore all other workflows and the pipeline immediately aborts and returns a failure status. - -Example steps: - -```yaml -steps: - backend: - image: golang - commands: - - go build - - go test - frontend: - image: node - commands: - - npm install - - npm run test - - npm run build -``` - -In the above example we define two steps, `frontend` and `backend`. The names of these steps are completely arbitrary. - -Another way to name a step is by using the name keyword: - -```yaml -steps: - - name: backend - image: golang - commands: - - go build - - go test - - name: frontend - image: node - commands: - - npm install - - npm run test - - npm run build -``` - -Keep in mind the name is optional, if not added the steps will be numerated. - -## Skip Commits - -Woodpecker gives the ability to skip individual commits by adding `[SKIP CI]` or `[CI SKIP]` to the commit message. Note this is case-insensitive. - -```bash -git commit -m "updated README [CI SKIP]" -``` - -## Steps - -Every step of your workflow executes commands inside a specified container. The defined commands are executed serially. -The associated commit is checked out with git to a workspace which is mounted to every step of the workflow as the working directory. - -```diff - steps: - backend: - image: golang - commands: -+ - go build -+ - go test -``` - -### File changes are incremental - -- Woodpecker clones the source code in the beginning of the workflow -- Changes to files are persisted through steps as the same volume is mounted to all steps - -```yaml title=".woodpecker.yaml" -steps: - build: - image: debian - commands: - - echo "test content" > myfile - a-test-step: - image: debian - commands: - - cat myfile -``` - -### `image` - -Woodpecker pulls the defined image and uses it as environment to execute the workflow step commands, for plugins and for service containers. - -When using the `local` backend, the `image` entry is used to specify the shell, such as Bash or Fish, that is used to run the commands. - -```diff - steps: - build: -+ image: golang:1.6 - commands: - - go build - - go test - - publish: -+ image: plugins/docker - repo: foo/bar - - services: - database: -+ image: mysql -``` - -Woodpecker supports any valid Docker image from any Docker registry: - -```yaml -image: golang -image: golang:1.7 -image: library/golang:1.7 -image: index.docker.io/library/golang -image: index.docker.io/library/golang:1.7 -``` - -Woodpecker does not automatically upgrade container images. Example configuration to always pull the latest image when updates are available: - -```diff - steps: - build: - image: golang:latest -+ pull: true -``` - -Learn more how you can use images from [different registries](./41-registries.md). - -### `commands` - -Commands of every step are executed serially as if you would enter them into your local shell. - -```diff - steps: - backend: - image: golang - commands: -+ - go build -+ - go test -``` - -There is no magic here. The above commands are converted to a simple shell script. The commands in the above example are roughly converted to the below script: - -```bash -#!/bin/sh -set -e - -go build -go test -``` - -The above shell script is then executed as the container entrypoint. The below docker command is an (incomplete) example of how the script is executed: - -```bash -docker run --entrypoint=build.sh golang -``` - -:::note -Only build steps can define commands. You cannot use commands with plugins or services. -::: - -### `entrypoint` - -Allows you to specify the entrypoint for containers. Note that this must be a list of the command and its arguments (e.g. `["/bin/sh", "-c"]`). - -### `environment` - -Woodpecker provides the ability to pass environment variables to individual steps. - -For more details check the [environment docs](./50-environment.md). - -### `secrets` - -Woodpecker provides the ability to store named parameters external to the YAML configuration file, in a central secret store. These secrets can be passed to individual steps of the workflow at runtime. - -For more details check the [secrets docs](./40-secrets.md). - -### `failure` - -Some of the steps may be allowed to fail without causing the whole workflow and therefore pipeline to report a failure (e.g., a step executing a linting check). To enable this, add `failure: ignore` to your step. If Woodpecker encounters an error while executing the step, it will report it as failed but still executes the next steps of the workflow, if any, without affecting the status of the workflow. - -```diff - steps: - backend: - image: golang - commands: - - go build - - go test -+ failure: ignore -``` - -### `when` - Conditional Execution - -Woodpecker supports defining a list of conditions for a step by using a `when` block. If at least one of the conditions in the `when` block evaluate to true the step is executed, otherwise it is skipped. A condition can be a check like: - -```diff - steps: - slack: - image: plugins/slack - settings: - channel: dev -+ when: -+ - event: pull_request -+ repo: test/test -+ - event: push -+ branch: main -``` - -#### `repo` - -Example conditional execution by repository: - -```diff - steps: - slack: - image: plugins/slack - settings: - channel: dev -+ when: -+ - repo: test/test -``` - -#### `branch` - -:::note -Branch conditions are not applied to tags. -::: - -Example conditional execution by branch: - -```diff - steps: - slack: - image: plugins/slack - settings: - channel: dev -+ when: -+ - branch: main -``` - -> The step now triggers on main branch, but also if the target branch of a pull request is `main`. Add an event condition to limit it further to pushes on main only. - -Execute a step if the branch is `main` or `develop`: - -```yaml -when: - - branch: [main, develop] -``` - -Execute a step if the branch starts with `prefix/*`: - -```yaml -when: - - branch: prefix/* -``` - -The branch matching is done using [doublestar](https://github.com/bmatcuk/doublestar/#usage), note that a pattern starting with `*` should be put between quotes and a literal `/` needs to be escaped. A few examples: - -- `*\\/*` to match patterns with exactly 1 `/` -- `*\\/**` to match patters with at least 1 `/` -- `*` to match patterns without `/` -- `**` to match everything - -Execute a step using custom include and exclude logic: - -```yaml -when: - - branch: - include: [main, release/*] - exclude: [release/1.0.0, release/1.1.*] -``` - -#### `event` - -Available events: `push`, `pull_request`, `pull_request_closed`, `tag`, `deployment`, `cron`, `manual` - -Execute a step if the build event is a `tag`: - -```yaml -when: - - event: tag -``` - -Execute a step if the pipeline event is a `push` to a specified branch: - -```diff -when: - - event: push -+ branch: main -``` - -Execute a step for multiple events: - -```yaml -when: - - event: [push, tag, deployment] -``` - -#### `cron` - -This filter **only** applies to cron events and filters based on the name of a cron job. - -Make sure to have a `event: cron` condition in the `when`-filters as well. - -```yaml -when: - - event: cron - cron: sync_* # name of your cron job -``` - -[Read more about cron](./45-cron.md) - -#### `ref` - -The `ref` filter compares the git reference against which the workflow is executed. -This allows you to filter, for example, tags that must start with **v**: - -```yaml -when: - - event: tag - ref: refs/tags/v* -``` - -#### `status` - -There are use cases for executing steps on failure, such as sending notifications for failed workflow / pipeline. Use the status constraint to execute steps even when the workflow fails: - -```diff - steps: - slack: - image: plugins/slack - settings: - channel: dev -+ when: -+ - status: [ success, failure ] -``` - -#### `platform` - -:::note -This condition should be used in conjunction with a [matrix](./30-matrix-workflows.md#example-matrix-pipeline-using-multiple-platforms) workflow as a regular workflow will only be executed by a single agent which only has one arch. -::: - -Execute a step for a specific platform: - -```yaml -when: - - platform: linux/amd64 -``` - -Execute a step for a specific platform using wildcards: - -```yaml -when: - - platform: [linux/*, windows/amd64] -``` - -#### `environment` - -Execute a step for deployment events matching the target deployment environment: - -```yaml -when: - - environment: production - - event: deployment -``` - -#### `matrix` - -Execute a step for a single matrix permutation: - -```yaml -when: - - matrix: - GO_VERSION: 1.5 - REDIS_VERSION: 2.8 -``` - -#### `instance` - -Execute a step only on a certain Woodpecker instance matching the specified hostname: - -```yaml -when: - - instance: stage.woodpecker.company.com -``` - -#### `path` - -:::info -Path conditions are applied only to **push** and **pull_request** events. -It is currently **only available** for GitHub, GitLab and Gitea (version 1.18.0 and newer) -::: - -Execute a step only on a pipeline with certain files being changed: - -```yaml -when: - - path: 'src/*' -``` - -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`. - -```yaml -when: - - path: - include: ['.woodpecker/*.yaml', '*.ini'] - exclude: ['*.md', 'docs/**'] - ignore_message: '[ALL]' -``` - -:::info -Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions. -::: - -#### `evaluate` - -Execute a step only if the provided evaluate expression is equal to true. Both built-in [`CI_`](./50-environment.md#built-in-environment-variables) and custom variables can be used inside the expression. - -The expression syntax can be found in [the docs](https://github.com/expr-lang/expr/blob/master/docs/language-definition.md) of the underlying library. - -Run on pushes to the default branch for the repository `owner/repo`: - -```yaml -when: - - evaluate: 'CI_PIPELINE_EVENT == "push" && CI_REPO == "owner/repo" && CI_COMMIT_BRANCH == CI_REPO_DEFAULT_BRANCH' -``` - -Run on commits created by user `woodpecker-ci`: - -```yaml -when: - - evaluate: 'CI_COMMIT_AUTHOR == "woodpecker-ci"' -``` - -Skip all commits containing `please ignore me` in the commit message: - -```yaml -when: - - evaluate: 'not (CI_COMMIT_MESSAGE contains "please ignore me")' -``` - -Run on pull requests with the label `deploy`: - -```yaml -when: - - evaluate: 'CI_COMMIT_PULL_REQUEST_LABELS contains "deploy"' -``` - -Skip step only if `SKIP=true`, run otherwise or if undefined: - -```yaml -when: - - evaluate: 'SKIP != "true"' -``` - -### `depends_on` - -Normally steps of a workflow are executed serially in the order in which they are defined. As soon as you set `depends_on` for a step a [directed acyclic graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) will be used and all steps of the workflow will be executed in parallel besides the steps that have a dependency set to another step using `depends_on`: - -```diff - steps: - build: # build will be executed immediately - image: golang - commands: - - go build - - deploy: - image: plugins/docker - settings: - repo: foo/bar -+ depends_on: [build, test] # deploy will be executed after build and test finished - - test: # test will be executed immediately as no dependencies are set - image: golang - commands: - - go test -``` - -### `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. - -For more details check the [volumes docs](./70-volumes.md). - -### `detach` - -Woodpecker gives the ability to detach steps to run them in background until the workflow finishes. - -For more details check the [service docs](./60-services.md#detachment). - -### `directory` - -Using `directory`, you can set a subdirectory of your repository or an absolute path inside the Docker container in which your commands will run. - -## `services` - -Woodpecker can provide service containers. They can for example be used to run databases or cache containers during the execution of workflow. - -For more details check the [services docs](./60-services.md). - -## `workspace` - -The workspace defines the shared volume and working directory shared by all workflow steps. The default workspace matches the pattern `/woodpecker/src/github.com/octocat/hello-world`, based on your repository URL. - -The workspace can be customized using the workspace block in the YAML file: - -```diff -+workspace: -+ base: /go -+ path: src/github.com/octocat/hello-world - - steps: - build: - image: golang:latest - commands: - - go get - - go test -``` - -The base attribute defines a shared base volume available to all steps. This ensures your source code, dependencies and compiled binaries are persisted and shared between steps. - -```diff - workspace: -+ base: /go - path: src/github.com/octocat/hello-world - - steps: - deps: - image: golang:latest - commands: - - go get - - go test - build: - image: node:latest - commands: - - go build -``` - -This would be equivalent to the following docker commands: - -```bash -docker volume create my-named-volume - -docker run --volume=my-named-volume:/go golang:latest -docker run --volume=my-named-volume:/go node:latest -``` - -The path attribute defines the working directory of your build. This is where your code is cloned and will be the default working directory of every step in your build process. The path must be relative and is combined with your base path. - -```diff - workspace: - base: /go -+ path: src/github.com/octocat/hello-world -``` - -```bash -git clone https://github.com/octocat/hello-world \ - /go/src/github.com/octocat/hello-world -``` - -## `matrix` - -Woodpecker has integrated support for matrix builds. Woodpecker executes a separate build task for each combination in the matrix, allowing you to build and test a single commit against multiple configurations. - -For more details check the [matrix build docs](./30-matrix-workflows.md). - -## `labels` - -You can set labels for your workflow to select an agent to execute the workflow on. An agent will pick up and run a workflow when **every** label assigned to it matches the agents labels. - -To set additional agent labels check the [agent configuration options](../30-administration/15-agent-config.md#woodpecker_filter_labels). Agents will have at least four default labels: `platform=agent-os/agent-arch`, `hostname=my-agent`, `backend=docker` (type of the agent backend) and `repo=*`. Agents can use a `*` as a wildcard for a label. For example `repo=*` will match every repo. - -Workflow labels with an empty value will be ignored. -By default each workflow has at least the `repo=your-user/your-repo-name` label. If you have set the [platform attribute](#platform) for your workflow it will have a label like `platform=your-os/your-arch` as well. - -You can add additional labels as a key value map: - -```diff -+labels: -+ location: europe # only agents with `location=europe` or `location=*` will be used -+ weather: sun -+ hostname: "" # this label will be ignored as it is empty - - steps: - build: - image: golang - commands: - - go build - - go test -``` - -### Filter by platform - -To configure your workflow to only be executed on an agent with a specific platform, you can use the `platform` key. -Have a look at the official [go docs](https://go.dev/doc/install/source) for the available platforms. The syntax of the platform is `GOOS/GOARCH` like `linux/arm64` or `linux/amd64`. - -Example: - -Assuming we have two agents, one `linux/arm` and one `linux/amd64`. Previously this workflow would have executed on **either agent**, as Woodpecker is not fussy about where it runs the workflows. By setting the following option it will only be executed on an agent with the platform `linux/arm64`. - -```diff -+labels: -+ platform: linux/arm64 - - steps: - [...] -``` - -## `variables` - -Woodpecker supports using [YAML anchors & aliases](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) as variables in the workflow configuration. - -For more details and examples check the [Advanced usage docs](./90-advanced-usage.md) - -## `clone` - -Woodpecker automatically configures a default clone step if not explicitly defined. When using the `local` backend, the [plugin-git](https://github.com/woodpecker-ci/plugin-git) binary must be on your `$PATH` for the default clone step to work. If not, you can still write a manual clone step. - -You can manually configure the clone step in your workflow for customization: - -```diff -+clone: -+ git: -+ image: woodpeckerci/plugin-git - - steps: - build: - image: golang - commands: - - go build - - go test -``` - -Example configuration to override depth: - -```diff - clone: - git: - image: woodpeckerci/plugin-git -+ settings: -+ partial: false -+ depth: 50 -``` - -Example configuration to use a custom clone plugin: - -```diff - clone: - git: -+ image: octocat/custom-git-plugin -``` - -Example configuration to clone Mercurial repository: - -```diff - clone: - hg: -+ image: plugins/hg -+ settings: -+ path: bitbucket.org/foo/bar -``` - -### Git Submodules - -To use the credentials that cloned the repository to clone it's submodules, update `.gitmodules` to use `https` instead of `git`: - -```diff - [submodule "my-module"] - path = my-module --url = git@github.com:octocat/my-module.git -+url = https://github.com/octocat/my-module.git -``` - -To use the ssh git url in `.gitmodules` for users cloning with ssh, and also use the https url in Woodpecker, add `submodule_override`: - -```diff - clone: - git: - image: woodpeckerci/plugin-git - settings: - recursive: true -+ submodule_override: -+ my-module: https://github.com/octocat/my-module.git - -steps: - ... -``` - -## `skip_clone` - -By default Woodpecker is automatically adding a clone step. This clone step can be configured by the [clone](#clone) property. If you do not need a `clone` step at all you can skip it using: - -```yaml -skip_clone: true -``` - -## `when` - Global workflow conditions - -Woodpecker gives the ability to skip whole workflows (not just steps #when---conditional-execution-1) based on certain conditions by a `when` block. If all conditions in the `when` block evaluate to true the workflow is executed, otherwise it is skipped, but treated as successful and other workflows depending on it will still continue. - -### `repo` - -Example conditional execution by repository: - -```diff -+when: -+ repo: test/test -+ - steps: - slack: - image: plugins/slack - settings: - channel: dev -``` - -### `branch` - -:::note -Branch conditions are not applied to tags. -::: - -Example conditional execution by branch: - -```diff -+when: -+ branch: main -+ - steps: - slack: - image: plugins/slack - settings: - channel: dev -``` - -The step now triggers on `main`, but also if the target branch of a pull request is `main`. Add an event condition to limit it further to pushes on main only. - -Execute a step if the branch is `main` or `develop`: - -```yaml -when: - branch: [main, develop] -``` - -Execute a step if the branch starts with `prefix/*`: - -```yaml -when: - branch: prefix/* -``` - -Execute a step using custom include and exclude logic: - -```yaml -when: - branch: - include: [main, release/*] - exclude: [release/1.0.0, release/1.1.*] -``` - -### `event` - -Execute a step if the build event is a `tag`: - -```yaml -when: - event: tag -``` - -Execute a step if the pipeline event is a `push` to a specified branch: - -```diff - when: - event: push -+ branch: main -``` - -Execute a step for all non-pull request events: - -```yaml -when: - event: [push, tag, deployment] -``` - -Execute a step for all build events: - -```yaml -when: - event: [push, pull_request, tag, deployment] -``` - -### `ref` - -The `ref` filter compares the git reference against which the pipeline is executed. -This allows you to filter, for example, tags that must start with **v**: - -```yaml -when: - event: tag - ref: refs/tags/v* -``` - -### `environment` - -Execute a step for deployment events matching the target deployment environment: - -```yaml -when: - environment: production - event: deployment -``` - -### `instance` - -Execute a step only on a certain Woodpecker instance matching the specified hostname: - -```yaml -when: - instance: stage.woodpecker.company.com -``` - -### `path` - -:::info -Path conditions are applied only to **push** and **pull_request** events. -It is currently **only available** for GitHub, GitLab and Gitea (version 1.18.0 and newer) -::: - -Execute a step only on a pipeline with certain files being changed: - -```yaml -when: - path: 'src/*' -``` - -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`. - -```yaml -when: - path: - include: ['.woodpecker/*.yaml', '*.ini'] - exclude: ['*.md', 'docs/**'] - ignore_message: '[ALL]' -``` - -:::info -Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions. -::: - -## `depends_on` - -Woodpecker supports to define multiple workflows for a repository. Those workflows will run independent from each other. To depend them on each other you can use the [`depends_on`](./25-workflows.md#flow-control) keyword. - -## `runs_on` - -Workflows that should run even on failure should set the `runs_on` tag. See [here](./25-workflows.md#flow-control) for an example. - -## Privileged mode - -Woodpecker gives the ability to configure privileged mode in the YAML. You can use this parameter to launch containers with escalated capabilities. - -:::info -Privileged mode is only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./71-project-settings.md#trusted) to enable trusted mode. -::: - -```diff - steps: - build: - image: docker - environment: - - DOCKER_HOST=tcp://docker:2375 - commands: - - docker --tls=false ps - - services: - docker: - image: docker:dind - commands: dockerd-entrypoint.sh --storage-driver=vfs --tls=false -+ privileged: true -``` diff --git a/docs/versioned_docs/version-2.2/20-usage/25-workflows.md b/docs/versioned_docs/version-2.2/20-usage/25-workflows.md deleted file mode 100644 index d1f8a0c446..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/25-workflows.md +++ /dev/null @@ -1,118 +0,0 @@ -# Workflows - -A pipeline has at least one workflow. A workflow is a set of steps that are executed in sequence using the same workspace which is a shared folder containing the repository and all the generated data from previous steps. - -In case there is a single configuration in `.woodpecker.yaml` Woodpecker will create a pipeline with a single workflow. - -By placing the configurations in a folder which is by default named `.woodpecker/` Woodpecker will create a pipeline with multiple workflows each named by the file they are defined in. Only `.yml` and `.yaml` files will be used and files in any subfolders like `.woodpecker/sub-folder/test.yaml` will be ignored. - -You can also set some custom path like `.my-ci/pipelines/` instead of `.woodpecker/` in the [project settings](./71-project-settings.md). - -## Benefits of using workflows - -- faster lint/test feedback, the workflow doesn't have to run fully to have a lint status pushed to the remote -- better organization of a pipeline along various concerns using one workflow for: testing, linting, building and deploying -- utilizing more agents to speed up the execution of the whole pipeline - -## Example workflow definition - -:::warning -Please note that files are only shared between steps of the same workflow (see [File changes are incremental](./20-workflow-syntax.md#file-changes-are-incremental)). That means you cannot access artifacts e.g. from the `build` workflow in the `deploy` workflow. -If you still need to pass artifacts between the workflows you need use some storage [plugin](./51-plugins/10-overview.md) (e.g. one which stores files in an Amazon S3 bucket). -::: - -```bash -.woodpecker/ -├── .build.yaml -├── .deploy.yaml -├── .lint.yaml -└── .test.yaml -``` - -```yaml title=".woodpecker/.build.yaml" -steps: - build: - image: debian:stable-slim - commands: - - echo building - - sleep 5 -``` - -```yaml title=".woodpecker/.deploy.yaml" -steps: - deploy: - image: debian:stable-slim - commands: - - echo deploying - -depends_on: - - lint - - build - - test -``` - -```yaml title=".woodpecker/.test.yaml" -steps: - test: - image: debian:stable-slim - commands: - - echo testing - - sleep 5 - -depends_on: - - build -``` - -```yaml title=".woodpecker/.lint.yaml" -steps: - lint: - image: debian:stable-slim - commands: - - echo linting - - sleep 5 -``` - -## Status lines - -Each workflow will report its own status back to your forge. - -## Flow control - -The workflows run in parallel on separate agents and share nothing. - -Dependencies between workflows can be set with the `depends_on` element. A workflow doesn't execute until all of its dependencies finished successfully. - -The name for a `depends_on` entry is the filename without the path, leading dots and without the file extension `.yml` or `.yaml`. If the project config for example uses `.woodpecker/` as path for CI files with a file named `.woodpecker/.lint.yaml` the corresponding `depends_on` entry would be `lint`. - -```diff - steps: - deploy: - image: debian:stable-slim - commands: - - echo deploying - -+depends_on: -+ - lint -+ - build -+ - test -``` - -Workflows that need to run even on failures should set the `runs_on` tag. - -```diff - steps: - notify: - image: debian:stable-slim - commands: - - echo notifying - - depends_on: - - deploy - -+runs_on: [ success, failure ] -``` - -:::info -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) -::: diff --git a/docs/versioned_docs/version-2.2/20-usage/30-matrix-workflows.md b/docs/versioned_docs/version-2.2/20-usage/30-matrix-workflows.md deleted file mode 100644 index 8fd1e3f8b5..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/30-matrix-workflows.md +++ /dev/null @@ -1,143 +0,0 @@ -# Matrix workflows - -Woodpecker has integrated support for matrix workflows. Woodpecker executes a separate workflow for each combination in the matrix, allowing you to build and test against multiple configurations. - -Example matrix definition: - -```yaml -matrix: - GO_VERSION: - - 1.4 - - 1.3 - REDIS_VERSION: - - 2.6 - - 2.8 - - 3.0 -``` - -Example matrix definition containing only specific combinations: - -```yaml -matrix: - include: - - GO_VERSION: 1.4 - REDIS_VERSION: 2.8 - - GO_VERSION: 1.5 - REDIS_VERSION: 2.8 - - GO_VERSION: 1.6 - REDIS_VERSION: 3.0 -``` - -## Interpolation - -Matrix variables are interpolated in the YAML using the `${VARIABLE}` syntax, before the YAML is parsed. This is an example YAML file before interpolating matrix parameters: - -```yaml -matrix: - GO_VERSION: - - 1.4 - - 1.3 - DATABASE: - - mysql:8 - - mysql:5 - - mariadb:10.1 - -steps: - build: - image: golang:${GO_VERSION} - commands: - - go get - - go build - - go test - -services: - database: - image: ${DATABASE} -``` - -Example YAML file after injecting the matrix parameters: - -```diff - steps: - build: -- image: golang:${GO_VERSION} -+ image: golang:1.4 - commands: - - go get - - go build - - go test -+ environment: -+ - GO_VERSION=1.4 -+ - DATABASE=mysql:8 - - services: - database: -- image: ${DATABASE} -+ image: mysql:8 -``` - -## Examples - -### Example matrix pipeline based on Docker image tag - -```yaml -matrix: - TAG: - - 1.7 - - 1.8 - - latest - -steps: - build: - image: golang:${TAG} - commands: - - go build - - go test -``` - -### Example matrix pipeline based on container image - -```yaml -matrix: - IMAGE: - - golang:1.7 - - golang:1.8 - - golang:latest - -steps: - build: - image: ${IMAGE} - commands: - - go build - - go test -``` - -### Example matrix pipeline using multiple platforms - -```yaml -matrix: - platform: - - linux/amd64 - - linux/arm64 - -labels: - platform: ${platform} - -steps: - test: - image: alpine - commands: - - echo "I am running on ${platform}" - - test-arm-only: - image: alpine - commands: - - echo "I am running on ${platform}" - - echo "Arm is cool!" - when: - platform: linux/arm* -``` - -:::note -If you want to control the architecture of a pipeline on a Kubernetes runner, see [the nodeSelector documentation of the Kubernetes backend](../30-administration/22-backends/40-kubernetes.md#nodeselector). -::: diff --git a/docs/versioned_docs/version-2.2/20-usage/40-secrets.md b/docs/versioned_docs/version-2.2/20-usage/40-secrets.md deleted file mode 100644 index 6c8465a58b..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/40-secrets.md +++ /dev/null @@ -1,142 +0,0 @@ -# Secrets - -Woodpecker provides the ability to store named parameters external to the YAML configuration file, in a central secret store. These secrets can be passed to individual steps of the pipeline at runtime. - -Woodpecker provides three different levels to add secrets to your pipeline. The following list shows the priority of the different levels. If a secret is defined in multiple levels, will be used following this priorities: Repository secrets > Organization secrets > Global secrets. - -1. **Repository secrets**: They are available to all pipelines of an repository. -2. **Organization secrets**: They are available to all pipelines of an organization. -3. **Global secrets**: Can be configured by an instance admin. - They are available to all pipelines of the **whole** Woodpecker instance and should therefore **only** be used for secrets that are allowed to be read by **all** users. - -## Usage - -### Use secrets in commands - -Secrets are exposed to your pipeline steps and plugins as uppercase environment variables and can therefore be referenced in the commands section of your pipeline, -once their usage is declared in the `secrets` section: - -```diff - steps: - docker: - image: docker - commands: -+ - echo $DOCKER_USERNAME -+ - echo $DOCKER_PASSWORD -+ secrets: [ docker_username, docker_password ] -``` - -### Use secrets in settings - -Alternatively, you can get a `setting` from secrets using the `from_secret` syntax. -In this example, the secret named `secret_token` would be passed to the setting named `token`, which will be available in the plugin as environment variable named `PLUGIN_TOKEN`. See [Plugins](./51-plugins/20-creating-plugins.md#settings) for details. - -**NOTE:** the `from_secret` syntax only works with the newer `settings` block. - -```diff - steps: - docker: - image: my-plugin - settings: -+ token: -+ from_secret: secret_token -``` - -### Note about parameter pre-processing - -Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped. - -```diff - steps: - docker: - image: docker - commands: -- - echo ${DOCKER_USERNAME} -- - echo ${DOCKER_PASSWORD} -+ - echo $${DOCKER_USERNAME} -+ - echo $${DOCKER_PASSWORD} - secrets: [ docker_username, docker_password ] -``` - -### Alternate Names - -There may be scenarios where you are required to store secrets using alternate names. You can map the alternate secret name to the expected name using the below syntax: - -```diff - steps: - docker: - image: plugins/docker - repo: octocat/hello-world - tags: latest -+ secrets: -+ - source: docker_prod_password -+ target: docker_password -``` - -### Use in Pull Requests events - -Secrets are not exposed to pull requests by default. You can override this behavior by creating the secret and enabling the `pull_request` event type, either in UI or by CLI, see below. - -**NOTE:** Please be careful when exposing secrets to pull requests. If your repository is open source and accepts pull requests your secrets are not safe. A bad actor can submit a malicious pull request that exposes your secrets. - -## Image filter - -To prevent abusing your secrets from malicious usage, you can limit a secret to a list of images. If enabled they are not available to any other plugin (steps without user-defined commands). If you or an attacker defines explicit commands, the secrets will not be available to the container to prevent leaking them. - -## Adding Secrets - -Secrets are added to the Woodpecker in the UI or with the CLI. - -### CLI Examples - -Create the secret using default settings. The secret will be available to all images in your pipeline, and will be available to all push, tag, and deployment events (not pull request events). - -```bash -woodpecker-cli secret add \ - -repository octocat/hello-world \ - -name aws_access_key_id \ - -value -``` - -Create the secret and limit to a single image: - -```diff - woodpecker-cli secret add \ - -repository octocat/hello-world \ -+ -image plugins/s3 \ - -name aws_access_key_id \ - -value -``` - -Create the secrets and limit to a set of images: - -```diff - woodpecker-cli secret add \ - -repository octocat/hello-world \ -+ -image plugins/s3 \ -+ -image peloton/woodpecker-ecs \ - -name aws_access_key_id \ - -value -``` - -Create the secret and enable for multiple hook events: - -```diff - woodpecker-cli secret add \ - -repository octocat/hello-world \ - -image plugins/s3 \ -+ -event pull_request \ -+ -event push \ -+ -event tag \ - -name aws_access_key_id \ - -value -``` - -Loading secrets from file using curl `@` syntax. This is the recommended approach for loading secrets from file to preserve newlines: - -```diff - woodpecker-cli secret add \ - -repository octocat/hello-world \ - -name ssh_key \ -+ -value @/root/ssh/id_rsa -``` diff --git a/docs/versioned_docs/version-2.2/20-usage/41-registries.md b/docs/versioned_docs/version-2.2/20-usage/41-registries.md deleted file mode 100644 index 9711c3519d..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/41-registries.md +++ /dev/null @@ -1,69 +0,0 @@ -# Registries - -Woodpecker provides the ability to add container registries in the settings of your repository. Adding a registry allows you to authenticate and pull private images from a container registry when using these images as a step inside your pipeline. Using registry credentials can also help you avoid rate limiting when pulling images from public registries. - -## Images from private registries - -You must provide registry credentials in the UI in order to pull private container images defined in your YAML configuration file. - -These credentials are never exposed to your steps, which means they cannot be used to push, and are safe to use with pull requests, for example. Pushing to a registry still requires setting credentials for the appropriate plugin. - -Example configuration using a private image: - -```diff - steps: - build: -+ image: gcr.io/custom/golang - commands: - - go build - - go test -``` - -Woodpecker matches the registry hostname to each image in your YAML. If the hostnames match, the registry credentials are used to authenticate to your registry and pull the image. Note that registry credentials are used by the Woodpecker agent and are never exposed to your build containers. - -Example registry hostnames: - -- Image `gcr.io/foo/bar` has hostname `gcr.io` -- Image `foo/bar` has hostname `docker.io` -- Image `qux.com:8000/foo/bar` has hostname `qux.com:8000` - -Example registry hostname matching logic: - -- Hostname `gcr.io` matches image `gcr.io/foo/bar` -- Hostname `docker.io` matches `golang` -- Hostname `docker.io` matches `library/golang` -- Hostname `docker.io` matches `bradyrydzewski/golang` -- Hostname `docker.io` matches `bradyrydzewski/golang:latest` - -## Global registry support - -To make a private registry globally available, check the [server configuration docs](../30-administration/10-server-config.md#global-registry-setting). - -## GCR registry support - -For specific details on configuring access to Google Container Registry, please view the docs [here](https://cloud.google.com/container-registry/docs/advanced-authentication#using_a_json_key_file). - -## Local Images - -:::warning -For this, privileged rights are needed only available to admins. In addition, this only works when using a single agent. -::: - -It's possible to build a local image by mounting the docker socket as a volume. - -With a `Dockerfile` at the root of the project: - -```yaml -steps: - build-image: - image: docker - commands: - - docker build --rm -t local/project-image . - volumes: - - /var/run/docker.sock:/var/run/docker.sock - - build-project: - image: local/project-image - commands: - - ./build.sh -``` diff --git a/docs/versioned_docs/version-2.2/20-usage/45-cron.md b/docs/versioned_docs/version-2.2/20-usage/45-cron.md deleted file mode 100644 index f90c77c1ad..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/45-cron.md +++ /dev/null @@ -1,34 +0,0 @@ -# Cron - -To configure cron jobs you need at least push access to the repository. - -## Add a new cron job - -1. To create a new cron job adjust your pipeline config(s) and add the event filter to all steps you would like to run by the cron job: - - ```diff - steps: - sync_locales: - image: weblate_sync - settings: - url: example.com - token: - from_secret: weblate_token - + when: - + event: cron - + cron: "name of the cron job" # if you only want to execute this step by a specific cron job - ``` - -1. Create a new cron job in the repository settings: - - ![cron settings](./cron-settings.png) - - The supported schedule syntax can be found at . If you need general understanding of the cron syntax is a good place to start and experiment. - - Examples: `@every 5m`, `@daily`, `0 30 * * * *` ... - - :::info - Woodpeckers cron syntax starts with seconds instead of minutes as used by most linux cron schedulers. - - Example: "At minute 30 every hour" would be `0 30 * * * *` instead of `30 * * * *` - ::: diff --git a/docs/versioned_docs/version-2.2/20-usage/50-environment.md b/docs/versioned_docs/version-2.2/20-usage/50-environment.md deleted file mode 100644 index 32096c5da3..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/50-environment.md +++ /dev/null @@ -1,223 +0,0 @@ -# Environment variables - -Woodpecker provides the ability to pass environment variables to individual pipeline steps. Note that these can't overwrite any existing, built-in variables. Example pipeline step with custom environment variables: - -```diff - steps: - 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: - 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: - 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 | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -| `CI` | CI environment name (value: `woodpecker`) | -| | **Repository** | -| `CI_REPO` | repository full name `/` | -| `CI_REPO_OWNER` | repository owner | -| `CI_REPO_NAME` | repository name | -| `CI_REPO_REMOTE_ID` | repository remote ID, is the UID it has in the forge | -| `CI_REPO_SCM` | repository SCM (git) | -| `CI_REPO_URL` | repository web URL | -| `CI_REPO_CLONE_URL` | repository clone URL | -| `CI_REPO_CLONE_SSH_URL` | repository SSH clone URL | -| `CI_REPO_DEFAULT_BRANCH` | repository default branch (main) | -| `CI_REPO_PRIVATE` | repository is private | -| `CI_REPO_TRUSTED` | repository is trusted | -| | **Current Commit** | -| `CI_COMMIT_SHA` | commit SHA | -| `CI_COMMIT_REF` | commit ref | -| `CI_COMMIT_REFSPEC` | commit ref spec | -| `CI_COMMIT_BRANCH` | commit branch (equals target branch for pull requests) | -| `CI_COMMIT_SOURCE_BRANCH` | commit source branch (empty if event is not `pull_request` or `pull_request_closed`) | -| `CI_COMMIT_TARGET_BRANCH` | commit target branch (empty if event is not `pull_request` or `pull_request_closed`) | -| `CI_COMMIT_TAG` | commit tag name (empty if event is not `tag`) | -| `CI_COMMIT_PULL_REQUEST` | commit pull request number (empty if event is not `pull_request` or `pull_request_closed`) | -| `CI_COMMIT_PULL_REQUEST_LABELS` | labels assigned to pull request (empty if event is not `pull_request` or `pull_request_closed`) | -| `CI_COMMIT_MESSAGE` | commit message | -| `CI_COMMIT_AUTHOR` | commit author username | -| `CI_COMMIT_AUTHOR_EMAIL` | commit author email address | -| `CI_COMMIT_AUTHOR_AVATAR` | commit author avatar | -| | **Current pipeline** | -| `CI_PIPELINE_NUMBER` | pipeline number | -| `CI_PIPELINE_PARENT` | number of parent pipeline | -| `CI_PIPELINE_EVENT` | pipeline event (see [pipeline events](../20-usage/15-terminiology/index.md#pipeline-events)) | -| `CI_PIPELINE_URL` | link to the web UI for the pipeline | -| `CI_PIPELINE_FORGE_URL` | link to the forge's web UI for the commit(s) or tag that triggered the pipeline | -| `CI_PIPELINE_DEPLOY_TARGET` | pipeline deploy target for `deployment` events (i.e. production) | -| `CI_PIPELINE_STATUS` | pipeline status (success, failure) | -| `CI_PIPELINE_CREATED` | pipeline created UNIX timestamp | -| `CI_PIPELINE_STARTED` | pipeline started UNIX timestamp | -| `CI_PIPELINE_FINISHED` | pipeline finished UNIX timestamp | -| `CI_PIPELINE_FILES` | changed files (empty if event is not `push` or `pull_request`), it is undefined if more than 500 files are touched | -| | **Current workflow** | -| `CI_WORKFLOW_NAME` | workflow name | -| | **Current step** | -| `CI_STEP_NAME` | step name | -| `CI_STEP_NUMBER` | step number | -| `CI_STEP_STATUS` | step status (success, failure) | -| `CI_STEP_STARTED` | step started UNIX timestamp | -| `CI_STEP_FINISHED` | step finished UNIX timestamp | -| `CI_STEP_URL` | URL to step in UI | -| | **Previous commit** | -| `CI_PREV_COMMIT_SHA` | previous commit SHA | -| `CI_PREV_COMMIT_REF` | previous commit ref | -| `CI_PREV_COMMIT_REFSPEC` | previous commit ref spec | -| `CI_PREV_COMMIT_BRANCH` | previous commit branch | -| `CI_PREV_COMMIT_SOURCE_BRANCH` | previous commit source branch | -| `CI_PREV_COMMIT_TARGET_BRANCH` | previous commit target branch | -| `CI_PREV_COMMIT_URL` | previous commit link in forge | -| `CI_PREV_COMMIT_MESSAGE` | previous commit message | -| `CI_PREV_COMMIT_AUTHOR` | previous commit author username | -| `CI_PREV_COMMIT_AUTHOR_EMAIL` | previous commit author email address | -| `CI_PREV_COMMIT_AUTHOR_AVATAR` | previous commit author avatar | -| | **Previous pipeline** | -| `CI_PREV_PIPELINE_NUMBER` | previous pipeline number | -| `CI_PREV_PIPELINE_PARENT` | previous pipeline number of parent pipeline | -| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (see [pipeline events](../20-usage/15-terminiology/index.md#pipeline-events)) | -| `CI_PREV_PIPELINE_URL` | previous pipeline link in CI | -| `CI_PREV_PIPELINE_FORGE_URL` | previous pipeline link to event in forge | -| `CI_PREV_PIPELINE_DEPLOY_TARGET` | previous pipeline deploy target for `deployment` events (ie production) | -| `CI_PREV_PIPELINE_STATUS` | previous pipeline status (success, failure) | -| `CI_PREV_PIPELINE_CREATED` | previous pipeline created UNIX timestamp | -| `CI_PREV_PIPELINE_STARTED` | previous pipeline started UNIX timestamp | -| `CI_PREV_PIPELINE_FINISHED` | previous pipeline finished UNIX timestamp | -| |   | -| `CI_WORKSPACE` | Path of the workspace where source code gets cloned to | -| | **System** | -| `CI_SYSTEM_NAME` | name of the CI system: `woodpecker` | -| `CI_SYSTEM_URL` | link to CI system | -| `CI_SYSTEM_HOST` | hostname of CI server | -| `CI_SYSTEM_VERSION` | version of the server | -| | **Forge** | -| `CI_FORGE_TYPE` | name of forge (gitea, github, ...) | -| `CI_FORGE_URL` | root URL of configured forge | -| | **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: - 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: - docker: - image: plugins/docker - settings: -+ tags: ${CI_COMMIT_SHA} -``` - -Example tag substitution: - -```diff - steps: - docker: - image: plugins/docker - settings: -+ tags: ${CI_COMMIT_TAG} -``` - -## String Operations - -Woodpecker also emulates bash string operations. This gives us the ability to manipulate the strings prior to substitution. Example use cases might include substring and stripping prefix or suffix values. - -| OPERATION | DESCRIPTION | -| ------------------ | ------------------------------------------------ | -| `${param}` | parameter substitution | -| `${param,}` | parameter substitution with lowercase first char | -| `${param,,}` | parameter substitution with lowercase | -| `${param^}` | parameter substitution with uppercase first char | -| `${param^^}` | parameter substitution with uppercase | -| `${param:pos}` | parameter substitution with substring | -| `${param:pos:len}` | parameter substitution with substring and length | -| `${param=default}` | parameter substitution with default | -| `${param##prefix}` | parameter substitution with prefix removal | -| `${param%%suffix}` | parameter substitution with suffix removal | -| `${param/old/new}` | parameter substitution with find and replace | - -Example variable substitution with substring: - -```diff - steps: - docker: - image: plugins/docker - settings: -+ tags: ${CI_COMMIT_SHA:0:8} -``` - -Example variable substitution strips `v` prefix from `v.1.0.0`: - -```diff - steps: - docker: - image: plugins/docker - settings: -+ tags: ${CI_COMMIT_TAG##v} -``` diff --git a/docs/versioned_docs/version-2.2/20-usage/51-plugins/10-overview.md b/docs/versioned_docs/version-2.2/20-usage/51-plugins/10-overview.md deleted file mode 100644 index d37c969f55..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/51-plugins/10-overview.md +++ /dev/null @@ -1,45 +0,0 @@ -# Plugins - -Plugins are pipeline steps that perform pre-defined tasks and are configured as steps in your pipeline. Plugins can be used to deploy code, publish artifacts, send notification, and more. - -They are automatically pulled from the default container registry the agent's have configured. - -Example pipeline using the Docker and Slack plugins: - -```yaml -steps: - build: - image: golang - commands: - - go build - - go test - - publish: - image: plugins/docker - settings: - repo: foo/bar - tags: latest - - notify: - image: plugins/slack - settings: - channel: dev -``` - -## Plugin Isolation - -Plugins are just pipeline steps. They share the build workspace, mounted as a volume, and therefore have access to your source tree. - -## Finding Plugins - -For official plugins, you can use the Woodpecker plugin index: - -- [Official Woodpecker Plugins](https://woodpecker-ci.org/plugins) - -:::tip -There are also other plugin lists with additional plugins. Keep in mind that [Drone](https://www.drone.io/) plugins are generally supported, but could need some adjustments and tweaking. - -- [Drone Plugins](http://plugins.drone.io) -- [Geeklab Woodpecker Plugins](https://woodpecker-plugins.geekdocs.de/) - -::: diff --git a/docs/versioned_docs/version-2.2/20-usage/51-plugins/20-creating-plugins.md b/docs/versioned_docs/version-2.2/20-usage/51-plugins/20-creating-plugins.md deleted file mode 100644 index 893010ad2a..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/51-plugins/20-creating-plugins.md +++ /dev/null @@ -1,122 +0,0 @@ -# Creating plugins - -Creating a new plugin is simple: Build a Docker container which uses your plugin logic as the ENTRYPOINT. - -## Settings - -To allow users to configure the behavior of your plugin, you should use `settings:`. - -These are passed to your plugin as uppercase env vars with a `PLUGIN_` prefix. -Using a setting like `url` results in an env var named `PLUGIN_URL`. - -Characters like `-` are converted to an underscore (`_`). `some_String` gets `PLUGIN_SOME_STRING`. -CamelCase is not respected, `anInt` get `PLUGIN_ANINT`. - -### Basic settings - -Using any basic YAML type (scalar) will be converted into a string: - -| Setting | Environment value | -| -------------------- | ---------------------------- | -| `some-bool: false` | `PLUGIN_SOME_BOOL="false"` | -| `some_String: hello` | `PLUGIN_SOME_STRING="hello"` | -| `anInt: 3` | `PLUGIN_ANINT="3"` | - -### Complex settings - -It's also possible to use complex settings like this: - -```yaml -steps: - plugin: - image: foo/plugin - settings: - complex: - abc: 2 - list: - - 2 - - 3 -``` - -Values like this are converted to JSON and then passed to your plugin. In the example above, the environment variable `PLUGIN_COMPLEX` would contain `{"abc": "2", "list": [ "2", "3" ]}`. - -### Secrets - -Secrets should be passed as settings too. Therefore, users should use [`from_secret`](../40-secrets.md#use-secrets-in-settings). - -## Plugin library - -For Go, we provide a plugin library you can use to get easy access to internal env vars and your settings. See . - -## Example plugin - -This provides a brief tutorial for creating a Woodpecker webhook plugin, using simple shell scripting, to make HTTP requests during the build pipeline. - -### What end users will see - -The below example demonstrates how we might configure a webhook plugin in the YAML file: - -```yaml -steps: - webhook: - image: foo/webhook - settings: - url: https://example.com - method: post - body: | - hello world -``` - -### Write the logic - -Create a simple shell script that invokes curl using the YAML configuration parameters, which are passed to the script as environment variables in uppercase and prefixed with `PLUGIN_`. - -```bash -#!/bin/sh - -curl \ - -X ${PLUGIN_METHOD} \ - -d ${PLUGIN_BODY} \ - ${PLUGIN_URL} -``` - -### Package it - -Create a Dockerfile that adds your shell script to the image, and configures the image to execute your shell script as the main entrypoint. - -```dockerfile -# please pin the version, e.g. alpine:3.19 -FROM alpine -ADD script.sh /bin/ -RUN chmod +x /bin/script.sh -RUN apk -Uuv add curl ca-certificates -ENTRYPOINT /bin/script.sh -``` - -Build and publish your plugin to the Docker registry. Once published, your plugin can be shared with the broader Woodpecker community. - -```shell -docker build -t foo/webhook . -docker push foo/webhook -``` - -Execute your plugin locally from the command line to verify it is working: - -```shell -docker run --rm \ - -e PLUGIN_METHOD=post \ - -e PLUGIN_URL=https://example.com \ - -e PLUGIN_BODY="hello world" \ - foo/webhook -``` - -## Best practices - -- Build your plugin for different architectures to allow many users to use them. - At least, you should support `amd64` and `arm64`. -- Provide binaries for users using the `local` backend. - These should also be built for different OS/architectures. -- Use [built-in env vars](../50-environment.md#built-in-environment-variables) where possible. -- Do not use any configuration except settings (and internal env vars). This means: Don't require using [`environment`](../50-environment.md) and don't require specific secret names. -- Add a `docs.md` file, listing all your settings and plugin metadata ([example](https://codeberg.org/woodpecker-plugins/plugin-docker-buildx/src/branch/main/docs.md)). -- Add your plugin to the [plugin index](/plugins) using your `docs.md` ([the example above in the index](https://woodpecker-ci.org/plugins/Docker%20Buildx)). diff --git a/docs/versioned_docs/version-2.2/20-usage/51-plugins/_category_.yaml b/docs/versioned_docs/version-2.2/20-usage/51-plugins/_category_.yaml deleted file mode 100644 index ecdc198db6..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/51-plugins/_category_.yaml +++ /dev/null @@ -1,7 +0,0 @@ -label: 'Plugins' -# position: 2 -collapsible: true -collapsed: true -link: - type: 'doc' - id: 'overview' diff --git a/docs/versioned_docs/version-2.2/20-usage/60-services.md b/docs/versioned_docs/version-2.2/20-usage/60-services.md deleted file mode 100644 index 6d6a0b594f..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/60-services.md +++ /dev/null @@ -1,114 +0,0 @@ -# Services - -Woodpecker provides a services section in the YAML file used for defining service containers. -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`. - -```yaml -steps: - build: - image: golang - commands: - - go build - - go test - -services: - database: - image: mysql - - cache: - image: redis -``` - -You can define a port and a protocol explicitly: - -```yaml -services: - database: - image: mysql - ports: - - 3306 - - wireguard: - image: wg - ports: - - 51820/udp -``` - -## Configuration - -Service containers generally expose environment variables to customize service startup such as default usernames, passwords and ports. Please see the official image documentation to learn more. - -```diff - services: - database: - image: mysql -+ environment: -+ - MYSQL_DATABASE=test -+ - MYSQL_ALLOW_EMPTY_PASSWORD=yes - - cache: - image: redis -``` - -## Detachment - -Service and long running containers can also be included in the pipeline section of the configuration using the detach parameter without blocking other steps. This should be used when explicit control over startup order is required. - -```diff - steps: - build: - image: golang - commands: - - go build - - go test - - database: - image: redis -+ detach: true - - test: - image: golang - commands: - - go test -``` - -Containers from detached steps will terminate when the pipeline ends. - -## Initialization - -Service containers require time to initialize and begin to accept connections. If you are unable to connect to a service you may need to wait a few seconds or implement a backoff. - -```diff - steps: - test: - image: golang - commands: -+ - sleep 15 - - go get - - go test - - services: - database: - image: mysql -``` - -## Complete Pipeline Example - -```yaml -services: - database: - image: mysql - environment: - - MYSQL_DATABASE=test - - MYSQL_ROOT_PASSWORD=example -steps: - get-version: - image: ubuntu - commands: - - ( apt update && apt dist-upgrade -y && apt install -y mysql-client 2>&1 )> /dev/null - - sleep 30s # need to wait for mysql-server init - - echo 'SHOW VARIABLES LIKE "version"' | mysql -uroot -hdatabase test -pexample -``` diff --git a/docs/versioned_docs/version-2.2/20-usage/70-volumes.md b/docs/versioned_docs/version-2.2/20-usage/70-volumes.md deleted file mode 100644 index 989f416e1b..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/70-volumes.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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. - -:::note -Volumes are only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](./71-project-settings.md#trusted) to enable trusted mode. -::: - -```diff - steps: - build: - image: docker - commands: - - docker build --rm -t octocat/hello-world . - - docker run --rm octocat/hello-world --test - - docker push octocat/hello-world - - docker rmi octocat/hello-world - volumes: -+ - /var/run/docker.sock:/var/run/docker.sock -``` - -Please note that Woodpecker mounts volumes on the host machine. This means you must use absolute paths when you configure volumes. Attempting to use relative paths will result in an error. - -```diff --volumes: [ ./certs:/etc/ssl/certs ] -+volumes: [ /etc/ssl/certs:/etc/ssl/certs ] -``` diff --git a/docs/versioned_docs/version-2.2/20-usage/71-project-settings.md b/docs/versioned_docs/version-2.2/20-usage/71-project-settings.md deleted file mode 100644 index f09402b61d..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/71-project-settings.md +++ /dev/null @@ -1,54 +0,0 @@ -# Project settings - -As the owner of a project in Woodpecker you can change project related settings via the web interface. - -![project settings](./project-settings.png) - -## Pipeline path - -The path to the pipeline config file or folder. By default it is left empty which will use the following configuration resolution `.woodpecker/*.{yaml,yml}` -> `.woodpecker.yaml` -> `.woodpecker.yml`. If you set a custom path Woodpecker tries to load your configuration or fails if no configuration could be found at the specified location. To use a [multiple workflows](./25-workflows.md) with a custom path you have to change it to a folder path ending with a `/` like `.woodpecker/`. - -## Repository hooks - -Your Version-Control-System will notify Woodpecker about events via webhooks. If you want your pipeline to only run on specific webhooks, you can check them with this setting. - -## Project settings - -### Allow pull requests - -Enables handling webhook's pull request event. If disabled, then pipeline won't run for pull requests. - -### Protected - -Every pipeline initiated by an webhook event needs to be approved by a project members with push permissions before being executed. -The protected option can be used as an additional review process before running potentially harmful pipelines. Especially if pipelines can be executed by third-parties through pull-requests. - -### Trusted - -If you set your project to trusted, a pipeline step and by this the underlying containers gets access to escalated capabilities like mounting volumes. - -:::note - -Only server admins can set this option. If you are not a server admin this option won't be shown in your project settings. - -::: - -### Only inject netrc credentials into trusted containers - -Cloning pipeline step may need git credentials. They are injected via netrc. By default, they're only injected if this option is enabled, the repo is trusted ([see above](#trusted)) or the image is a trusted clone image. If you uncheck the option, git credentials will be injected into any container in clone step. - -## Project visibility - -You can change the visibility of your project by this setting. If a user has access to a project they can see all builds and their logs and artifacts. Settings, Secrets and Registries can only be accessed by owners. - -- `Public` Every user can see your project without being logged in. -- `Internal` Only authenticated users of the Woodpecker instance can see this project. -- `Private` Only you and other owners of the repository can see this project. - -## Timeout - -After this timeout a pipeline has to finish or will be treated as timed out. - -## Cancel previous pipelines - -By enabling this option for a pipeline event previous pipelines of the same event and context will be canceled before starting the newly triggered one. diff --git a/docs/versioned_docs/version-2.2/20-usage/80-badges.md b/docs/versioned_docs/version-2.2/20-usage/80-badges.md deleted file mode 100644 index 1bee62a582..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/80-badges.md +++ /dev/null @@ -1,18 +0,0 @@ -# Status Badges - -Woodpecker has integrated support for repository status badges. These badges can be added to your website or project readme file to display the status of your code. - -## Badge endpoint - -```uri -:///api/badges//status.svg -``` - -The status badge displays the status for the latest build to your default branch (e.g. main). You can customize the branch by adding the `branch` query parameter. - -```diff --:///api/badges//status.svg -+:///api/badges//status.svg?branch= -``` - -Please note status badges do not include pull request results, since the status of a pull request does not provide an accurate representation of your repository state. diff --git a/docs/versioned_docs/version-2.2/20-usage/90-advanced-usage.md b/docs/versioned_docs/version-2.2/20-usage/90-advanced-usage.md deleted file mode 100644 index 8855e4430e..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/90-advanced-usage.md +++ /dev/null @@ -1,129 +0,0 @@ -# Advanced usage - -## Advanced YAML syntax - -YAML has some advanced syntax features that can be used like variables to reduce duplication in your pipeline config: - -### Anchors & aliases - -You can use [YAML anchors & aliases](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) as variables in your pipeline config. - -To convert this: - -```yaml -steps: - test: - image: golang:1.18 - commands: go test ./... - build: - image: golang:1.18 - commands: build -``` - -Just add a new section called **variables** like this: - -```diff -+variables: -+ - &golang_image 'golang:1.18' - - steps: - test: -- image: golang:1.18 -+ image: *golang_image - commands: go test ./... - build: -- image: golang:1.18 -+ image: *golang_image - commands: build -``` - -### Map merges and overwrites - -```yaml -variables: - - &base-plugin-settings - target: dist - recursive: false - try: true - - &special-setting - special: true - - &some-plugin codeberg.org/6543/docker-images/print_env - -steps: - develop: - image: *some-plugin - settings: - <<: [*base-plugin-settings, *special-setting] # merge two maps into an empty map - when: - branch: develop - - main: - image: *some-plugin - settings: - <<: *base-plugin-settings # merge one map and ... - try: false # ... overwrite original value - ongoing: false # ... adding a new value - when: - branch: main -``` - -### Sequence merges - -```yaml -variables: - pre_cmds: &pre_cmds - - echo start - - whoami - post_cmds: &post_cmds - - echo stop - hello_cmd: &hello_cmd - - echo hello - -steps: - step1: - image: debian - commands: - - <<: *pre_cmds # prepend a sequence - - echo exec step now do dedicated things - - <<: *post_cmds # append a sequence - step2: - image: debian - commands: - - <<: [*pre_cmds, *hello_cmd] # prepend two sequences - - echo echo from second step - - <<: *post_cmds -``` - -### References - -- [Official YAML specification](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) -- [YAML Cheatsheet](https://learnxinyminutes.com/docs/yaml) - -## Persisting environment data between steps - -One can create a file containing environment variables, and then source it in each step that needs them. - -```yaml -steps: - init: - image: bash - commands: - - echo "FOO=hello" >> envvars - - echo "BAR=world" >> envvars - - debug: - image: bash - commands: - - source envvars - - echo $FOO -``` - -## Declaring global variables - -As described in [Global environment variables](./50-environment.md#global-environment-variables), you can define global variables: - -```ini -WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2 -``` - -Note that this tightly couples the server and app configurations (where the app is a completely separate application). But this is a good option for truly global variables which should apply to all steps in all pipelines for all apps. diff --git a/docs/versioned_docs/version-2.2/20-usage/_category_.yaml b/docs/versioned_docs/version-2.2/20-usage/_category_.yaml deleted file mode 100644 index ba9f729ed0..0000000000 --- a/docs/versioned_docs/version-2.2/20-usage/_category_.yaml +++ /dev/null @@ -1,4 +0,0 @@ -label: 'Usage' -# position: 2 -collapsible: true -collapsed: false diff --git a/docs/versioned_docs/version-2.2/20-usage/cron-settings.png b/docs/versioned_docs/version-2.2/20-usage/cron-settings.png deleted file mode 100644 index d11c507afc..0000000000 Binary files a/docs/versioned_docs/version-2.2/20-usage/cron-settings.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/20-usage/project-settings.png b/docs/versioned_docs/version-2.2/20-usage/project-settings.png deleted file mode 100644 index fc29daac84..0000000000 Binary files a/docs/versioned_docs/version-2.2/20-usage/project-settings.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/20-usage/repo-list.png b/docs/versioned_docs/version-2.2/20-usage/repo-list.png deleted file mode 100644 index b473800876..0000000000 Binary files a/docs/versioned_docs/version-2.2/20-usage/repo-list.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/30-administration/00-deployment/00-overview.md b/docs/versioned_docs/version-2.2/30-administration/00-deployment/00-overview.md deleted file mode 100644 index cd34fcf421..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/00-deployment/00-overview.md +++ /dev/null @@ -1,72 +0,0 @@ -# Deployment - -A Woodpecker deployment consists of two parts: - -- A server which is the heart of Woodpecker and ships the web interface. -- Next to one server, you can deploy any number of agents which will run the pipelines. - -Each agent is able to process one pipeline step by default. -If you have four agents installed and connected to the Woodpecker server, your system will process four workflows in parallel. - -:::tip -You can add more agents to increase the number of parallel workflows or set the agent's `WOODPECKER_MAX_WORKFLOWS=1` environment variable to increase the number of parallel workflows for that agent. -::: - -## Which version of Woodpecker should I use? - -Woodpecker is having two different kinds of releases: **stable** and **next**. - -## Hardware Requirements - -Below are minimal resources requirements for Woodpecker components itself: - -| Component | Memory | CPU | -| --------- | ------ | --- | -| Server | 200 MB | 1 | -| Agent | 32 MB | 1 | - -Note, that those values do not include the operating system or workload (pipelines execution) resources consumption. - -In addition you need at least some kind of database which requires additional resources depending on the selected database system. - -## Installation - -You can install Woodpecker on multiple ways: - -- Using [docker-compose](./10-docker-compose.md) with the official [container images](./10-docker-compose.md#docker-images) -- Using [Kubernetes](./20-kubernetes.md) via the Woodpecker Helm chart -- Using binaries, DEBs or RPMs you can download from [latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest) - -## Authentication - -Authentication is done using OAuth and is delegated to your forge which is configured using environment variables. - -See the complete reference for all supported forges [here](../11-forges/10-overview.md). - -## Database - -By default Woodpecker uses a SQLite database which requires zero installation or configuration. See the [database settings](../30-database.md) page to further configure it or use MySQL or Postgres. - -## SSL - -Woodpecker supports SSL configuration by using Let's encrypt or by using own certificates. See the [SSL guide](../60-ssl.md). You can also put it behind a [reverse proxy](#behind-a-proxy) - -## Metrics - -A [Prometheus endpoint](../90-prometheus.md) is exposed. - -## Behind a proxy - -See the [proxy guide](../70-proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok. - -In the case you need to use Woodpecker with a URL path prefix (like: ), add the root path to [`WOODPECKER_HOST`](../10-server-config.md#woodpecker_host). - -## Third-party installation methods - -:::info -These installation methods are not officially supported. If you experience issues with them, please open issues in the specific repositories. -::: - -- Using [NixOS](./30-nixos.md) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker) -- [Using YunoHost](https://apps.yunohost.org/app/woodpecker) -- [On Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html) diff --git a/docs/versioned_docs/version-2.2/30-administration/00-deployment/10-docker-compose.md b/docs/versioned_docs/version-2.2/30-administration/00-deployment/10-docker-compose.md deleted file mode 100644 index 2212f7b2fd..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/00-deployment/10-docker-compose.md +++ /dev/null @@ -1,147 +0,0 @@ -# docker-compose - -The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start a Woodpecker server with a single agent. - -It relies on a number of environment variables that you must set before running `docker-compose up`. The variables are described below. - -```yaml title="docker-compose.yaml" -version: '3' - -services: - woodpecker-server: - image: woodpeckerci/woodpecker-server:latest - ports: - - 8000:8000 - volumes: - - woodpecker-server-data:/var/lib/woodpecker/ - environment: - - WOODPECKER_OPEN=true - - WOODPECKER_HOST=${WOODPECKER_HOST} - - WOODPECKER_GITHUB=true - - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT} - - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET} - - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} - - woodpecker-agent: - image: woodpeckerci/woodpecker-agent:latest - command: agent - restart: always - depends_on: - - woodpecker-server - volumes: - - woodpecker-agent-config:/etc/woodpecker - - /var/run/docker.sock:/var/run/docker.sock - environment: - - WOODPECKER_SERVER=woodpecker-server:9000 - - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} - -volumes: - woodpecker-server-data: - woodpecker-agent-config: -``` - -Woodpecker needs to know its own address. You must therefore provide the public address of it in `://` format. Please omit trailing slashes: - -```diff title="docker-compose.yaml" - version: '3' - - services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_HOST=${WOODPECKER_HOST} -``` - -Woodpecker can also have its port's configured. It uses a separate port for gRPC and for HTTP. The agent performs gRPC calls and connects to the gRPC port. -They can be configured with `*_ADDR` variables: - -```diff title="docker-compose.yaml" - version: '3' - services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR} -+ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR} -``` - -Reverse proxying can also be [configured for gRPC](../proxy#caddy). If the agents are connecting over the internet, it should also be SSL encrypted. The agent then needs to be configured to be secure: - -```diff title="docker-compose.yaml" - version: '3' - services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_GRPC_SECURE=true # defaults to false -+ - WOODPECKER_GRPC_VERIFY=true # default -``` - -As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon: - -```diff title="docker-compose.yaml" - version: '3' - - services: - [...] - woodpecker-agent: - [...] -+ volumes: -+ - /var/run/docker.sock:/var/run/docker.sock -``` - -Agents require the server address for agent-to-server communication. The agent connects to the server's gRPC port: - -```diff title="docker-compose.yaml" - version: '3' - - services: - woodpecker-agent: - [...] - environment: -+ - WOODPECKER_SERVER=woodpecker-server:9000 -``` - -The server and agents use a shared secret to authenticate communication. This should be a random string of your choosing and should be kept private. You can generate such string with `openssl rand -hex 32`: - -```diff title="docker-compose.yaml" - version: '3' - - services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} - woodpecker-agent: - [...] - environment: - - [...] -+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET} -``` - -## Docker images - -Image variants: - -- The `latest` image is the latest stable release -- The `vX.X.X` images are stable releases -- The `vX.X` images are based on the current release branch (e.g. `release/v1.0`) and can be used to get bugfixes asap -- The `next` images are based on the current `main` branch - -```bash -# server -docker pull woodpeckerci/woodpecker-server:latest -docker pull woodpeckerci/woodpecker-server:latest-alpine - -# agent -docker pull woodpeckerci/woodpecker-agent:latest -docker pull woodpeckerci/woodpecker-agent:latest-alpine - -# cli -docker pull woodpeckerci/woodpecker-cli:latest -docker pull woodpeckerci/woodpecker-cli:latest-alpine -``` diff --git a/docs/versioned_docs/version-2.2/30-administration/00-deployment/20-kubernetes.md b/docs/versioned_docs/version-2.2/30-administration/00-deployment/20-kubernetes.md deleted file mode 100644 index f931c3e785..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/00-deployment/20-kubernetes.md +++ /dev/null @@ -1,9 +0,0 @@ -# Kubernetes - -We recommended to deploy Woodpecker using the [Woodpecker helm chart](https://github.com/woodpecker-ci/helm). -Have a look at the [`values.yaml`](https://github.com/woodpecker-ci/helm/blob/main/charts/woodpecker/values.yaml) config files for all available settings. - -The chart contains two subcharts, `server` and `agent` which are automatically configured as needed. -The chart started off with two independent charts but was merged into one to simplify the deployment at start of 2023. - -A couple of backend-specific config env vars exists which are described in the [kubernetes backend docs](../22-backends/40-kubernetes.md). diff --git a/docs/versioned_docs/version-2.2/30-administration/00-deployment/30-nixos.md b/docs/versioned_docs/version-2.2/30-administration/00-deployment/30-nixos.md deleted file mode 100644 index 148fbd581d..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/00-deployment/30-nixos.md +++ /dev/null @@ -1,88 +0,0 @@ -# NixOS - -:::info -Note that this module is not maintained by the woodpecker-developers. -If you experience issues please open a bug report in the [nixpkgs repo](https://github.com/NixOS/nixpkgs/issues/new/choose) where the module is maintained. -::: - -The NixOS install is in theory quite similar to the binary install and supports multiple backends. -In practice, the settings are specified declaratively in the NixOS configuration and no manual steps need to be taken. - -## General Configuration - -```nix -{ config -, ... -}: -let - domain = "woodpecker.example.org"; -in -{ - # This automatically sets up certificates via let's encrypt - security.acme.defaults.email = "acme@example.com"; - security.acme.acceptTerms = true; - security.acme.certs."${domain}" = { }; - - # Setting up a nginx proxy that handles tls for us - networking.firewall.allowedTCPPorts = [ 80 443 ]; - services.nginx = { - enable = true; - recommendedTlsSettings = true; - recommendedOptimisation = true; - recommendedProxySettings = true; - virtualHosts."${domain}" = { - enableACME = true; - forceSSL = true; - locations."/" = { - proxyPass = "http://localhost:3007"; - }; - }; - }; - - services.woodpecker-server = { - enable = true; - environment = { - WOODPECKER_HOST = "https://${domain}"; - WOODPECKER_SERVER_ADDR = ":3007"; - WOODPECKER_OPEN = "true"; - }; - # You can pass a file with env vars to the system it could look like: - # WOODPECKER_AGENT_SECRET=XXXXXXXXXXXXXXXXXXXXXX - environmentFile = "/path/to/my/secrets/file"; - }; - - # This sets up a woodpecker agent - services.woodpecker-agents.agents."docker" = { - enable = true; - # We need this to talk to the podman socket - extraGroups = [ "podman" ]; - environment = { - WOODPECKER_SERVER = "localhost:9000"; - WOODPECKER_MAX_WORKFLOWS = "4"; - DOCKER_HOST = "unix:///run/podman/podman.sock"; - WOODPECKER_BACKEND = "docker"; - }; - # Same as with woodpecker-server - environmentFile = [ "/var/lib/secrets/woodpecker.env" ]; - }; - - # Here we setup podman and enable dns - virtualisation.podman = { - enable = true; - defaultNetwork.settings = { - dns_enabled = true; - }; - }; - # This is needed for podman to be able to talk over dns - networking.firewall.interfaces."podman0" = { - allowedUDPPorts = [ 53 ]; - allowedTCPPorts = [ 53 ]; - }; -} -``` - -All configuration options can be found via [NixOS Search](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker) - -## Tips and tricks - -There are some resources on how to utilize Woodpecker more effectively with NixOS on the [Awesome Woodpecker](../../92-awesome.md) page, like using the runners nix-store in the pipeline diff --git a/docs/versioned_docs/version-2.2/30-administration/00-deployment/_category_.yaml b/docs/versioned_docs/version-2.2/30-administration/00-deployment/_category_.yaml deleted file mode 100644 index 7284349698..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/00-deployment/_category_.yaml +++ /dev/null @@ -1,6 +0,0 @@ -label: 'Deployment' -collapsible: true -collapsed: true -link: - type: 'doc' - id: 'overview' diff --git a/docs/versioned_docs/version-2.2/30-administration/10-server-config.md b/docs/versioned_docs/version-2.2/30-administration/10-server-config.md deleted file mode 100644 index be40ddb7d3..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/10-server-config.md +++ /dev/null @@ -1,582 +0,0 @@ ---- -toc_max_heading_level: 2 ---- - -# Server configuration - -## User registration - -Woodpecker does not have its own user registry; users are provided from your [forge](./11-forges/10-overview.md) (using OAuth2). - -Registration is closed by default (`WOODPECKER_OPEN=false`). If registration is open (`WOODPECKER_OPEN=true`) then every user with an account at the configured forge can login to Woodpecker. - -To open registration: - -```ini -WOODPECKER_OPEN=true -``` - -You can **also restrict** registration, by keep registration closed and: - -- **adding** new **users manually** via the CLI: `woodpecker-cli user add` -- allowing specific **admin users** via the `WOODPECKER_ADMIN` setting -- by open registration and **filter by organization** membership through the `WOODPECKER_ORGS` setting - -### Close registration, but allow specific admin users - -```ini -WOODPECKER_OPEN=false -WOODPECKER_ADMIN=johnsmith,janedoe -``` - -### Only allow registration of users, who are members of approved organizations - -```ini -WOODPECKER_OPEN=true -WOODPECKER_ORGS=dolores,dogpatch -``` - -## Administrators - -Administrators should also be enumerated in your configuration. - -```ini -WOODPECKER_ADMIN=johnsmith,janedoe -``` - -## Filtering repositories - -Woodpecker operates with the user's OAuth permission. Due to the coarse permission handling of GitHub, you may end up syncing more repos into Woodpecker than preferred. - -Use the `WOODPECKER_REPO_OWNERS` variable to filter which GitHub user's repos should be synced only. You typically want to put here your company's GitHub name. - -```ini -WOODPECKER_REPO_OWNERS=mycompany,mycompanyossgithubuser -``` - -## Global registry setting - -If you want to make available a specific private registry to all pipelines, use the `WOODPECKER_DOCKER_CONFIG` server configuration. -Point it to your server's docker config. - -```ini -WOODPECKER_DOCKER_CONFIG=/root/.docker/config.json -``` - -## Handling sensitive data in docker-compose and docker-swarm - -To handle sensitive data in docker-compose or docker-swarm configurations there are several options: - -For docker-compose you can use a `.env` file next to your compose configuration to store the secrets outside of the compose file. While this separates configuration from secrets it is still not very secure. - -Alternatively use docker-secrets. As it may be difficult to use docker secrets for environment variables woodpecker allows to read sensible data from files by providing a `*_FILE` option of all sensible configuration variables. Woodpecker will try to read the value directly from this file. Keep in mind that when the original environment variable gets specified at the same time it will override the value read from the file. - -```diff title="docker-compose.yaml" - version: '3' - - services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_AGENT_SECRET_FILE=/run/secrets/woodpecker-agent-secret -+ secrets: -+ - woodpecker-agent-secret -+ -+ secrets: -+ woodpecker-agent-secret: -+ external: true -``` - -Store a value to a docker secret like this: - -```bash -echo "my_agent_secret_key" | docker secret create woodpecker-agent-secret - -``` - -or generate a random one like this: - -```bash -openssl rand -hex 32 | docker secret create woodpecker-agent-secret - -``` - -## Custom JavaScript and CSS - -Woodpecker supports custom JS and CSS files. -These files must be present in the server's filesystem. -They can be backed in a Docker image or mounted from a ConfigMap inside a Kubernetes environment. -The configuration variables are independent of each other, which means it can be just one file present, or both. - -```ini -WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.css -WOODPECKER_CUSTOM_JS_FILE=/usr/local/www/woodpecker.js -``` - -The examples below show how to place a banner message in the top navigation bar of Woodpecker. - -### `woodpecker.css` - -```css -.banner-message { - position: absolute; - width: 280px; - height: 40px; - margin-left: 240px; - margin-top: 5px; - padding-top: 5px; - font-weight: bold; - background: red no-repeat; - text-align: center; -} -``` - -### `woodpecker.js` - -```javascript -// place/copy a minified version of jQuery or ZeptoJS here ... -!(function () { - 'use strict'; - function e() {} /*...*/ -})(); - -$().ready(function () { - $('.app nav img').first().htmlAfter(""); -}); -``` - -## All server configuration options - -The following list describes all available server configuration options. - -### `WOODPECKER_LOG_LEVEL` - -> Default: empty - -Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty. - -### `WOODPECKER_LOG_FILE` - -> Default: `stderr` - -Output destination for logs. -'stdout' and 'stderr' can be used as special keywords. - -### `WOODPECKER_LOG_XORM` - -> Default: `false` - -Enable XORM logs. - -### `WOODPECKER_LOG_XORM_SQL` - -> Default: `false` - -Enable XORM SQL command logs. - -### `WOODPECKER_DEBUG_PRETTY` - -> Default: `false` - -Enable pretty-printed debug output. - -### `WOODPECKER_DEBUG_NOCOLOR` - -> Default: `true` - -Disable colored debug output. - -### `WOODPECKER_HOST` - -> Default: empty - -Server fully qualified URL of the user-facing hostname and path prefix. - -Example: `WOODPECKER_HOST=http://woodpecker.example.org` or `WOODPECKER_HOST=http://example.org/woodpecker` - -### `WOODPECKER_WEBHOOK_HOST` - -> Default: value from `WOODPECKER_HOST` config env - -Server fully qualified URL of the Webhook-facing hostname and path prefix. - -Example: `WOODPECKER_WEBHOOK_HOST=http://woodpecker-server.cicd.svc.cluster.local:8000` - -### `WOODPECKER_SERVER_ADDR` - -> Default: `:8000` - -Configures the HTTP listener port. - -### `WOODPECKER_SERVER_ADDR_TLS` - -> Default: `:443` - -Configures the HTTPS listener port when SSL is enabled. - -### `WOODPECKER_SERVER_CERT` - -> Default: empty - -Path to an SSL certificate used by the server to accept HTTPS requests. - -Example: `WOODPECKER_SERVER_CERT=/path/to/cert.pem` - -### `WOODPECKER_SERVER_KEY` - -> Default: empty - -Path to an SSL certificate key used by the server to accept HTTPS requests. - -Example: `WOODPECKER_SERVER_KEY=/path/to/key.pem` - -### `WOODPECKER_CUSTOM_CSS_FILE` - -> Default: empty - -File path for the server to serve a custom .CSS file, used for customizing the UI. -Can be used for showing banner messages, logos, or environment-specific hints (a.k.a. white-labeling). -The file must be UTF-8 encoded, to ensure all special characters are preserved. - -Example: `WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.css` - -### `WOODPECKER_CUSTOM_JS_FILE` - -> Default: empty - -File path for the server to serve a custom .JS file, used for customizing the UI. -Can be used for showing banner messages, logos, or environment-specific hints (a.k.a. white-labeling). -The file must be UTF-8 encoded, to ensure all special characters are preserved. - -Example: `WOODPECKER_CUSTOM_JS_FILE=/usr/local/www/woodpecker.js` - -### `WOODPECKER_LETS_ENCRYPT` - -> Default: `false` - -Automatically generates an SSL certificate using Let's Encrypt, and configures the server to accept HTTPS requests. - -### `WOODPECKER_GRPC_ADDR` - -> Default: `:9000` - -Configures the gRPC listener port. - -### `WOODPECKER_GRPC_SECRET` - -> Default: `secret` - -Configures the gRPC JWT secret. - -### `WOODPECKER_GRPC_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GRPC_SECRET` from the specified filepath. - -### `WOODPECKER_METRICS_SERVER_ADDR` - -> Default: empty - -Configures an unprotected metrics endpoint. An empty value disables the metrics endpoint completely. - -Example: `:9001` - -### `WOODPECKER_ADMIN` - -> Default: empty - -Comma-separated list of admin accounts. - -Example: `WOODPECKER_ADMIN=user1,user2` - -### `WOODPECKER_ORGS` - -> Default: empty - -Comma-separated list of approved organizations. - -Example: `org1,org2` - -### `WOODPECKER_REPO_OWNERS` - -> Default: empty - -Comma-separated list of syncable repo owners. ??? - -Example: `user1,user2` - -### `WOODPECKER_OPEN` - -> Default: `false` - -Enable to allow user registration. - -### `WOODPECKER_AUTHENTICATE_PUBLIC_REPOS` - -> Default: `false` - -Always use authentication to clone repositories even if they are public. Needed if the forge requires to always authenticate as used by many companies. - -### `WOODPECKER_DEFAULT_CANCEL_PREVIOUS_PIPELINE_EVENTS` - -> Default: `pull_request, push` - -List of event names that will be canceled when a new pipeline for the same context (tag, branch) is created. - -### `WOODPECKER_DEFAULT_CLONE_IMAGE` - -> Default is defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go) - -The default docker image to be used when cloning the repo - -### `WOODPECKER_DEFAULT_PIPELINE_TIMEOUT` - -> 60 (minutes) - -The default time for a repo in minutes before a pipeline gets killed - -### `WOODPECKER_MAX_PIPELINE_TIMEOUT` - -> 120 (minutes) - -The maximum time in minutes you can set in the repo settings before a pipeline gets killed - -### `WOODPECKER_SESSION_EXPIRES` - -> Default: `72h` - -Configures the session expiration time. -Context: when someone does log into Woodpecker, a temporary session token is created. -As long as the session is valid (until it expires or log-out), -a user can log into Woodpecker, without re-authentication. - -### `WOODPECKER_ESCALATE` - -> Defaults are defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go) - -Docker images to run in privileged mode. Only change if you are sure what you do! - - - -### `WOODPECKER_DOCKER_CONFIG` - -> Default: empty - -Configures a specific private registry config for all pipelines. - -Example: `WOODPECKER_DOCKER_CONFIG=/home/user/.docker/config.json` - - - -### `WOODPECKER_AGENT_SECRET` - -> Default: empty - -A shared secret used by server and agents to authenticate communication. A secret can be generated by `openssl rand -hex 32`. - -### `WOODPECKER_AGENT_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_AGENT_SECRET` from the specified filepath - -### `WOODPECKER_KEEPALIVE_MIN_TIME` - -> Default: empty - -Server-side enforcement policy on the minimum amount of time a client should wait before sending a keepalive ping. - -Example: `WOODPECKER_KEEPALIVE_MIN_TIME=10s` - -### `WOODPECKER_DATABASE_DRIVER` - -> Default: `sqlite3` - -The database driver name. Possible values are `sqlite3`, `mysql` or `postgres`. - -### `WOODPECKER_DATABASE_DATASOURCE` - -> Default: `woodpecker.sqlite` - -The database connection string. The default value is the path of the embedded SQLite database file. - -Example: - -```bash -# MySQL -# https://github.com/go-sql-driver/mysql#dsn-data-source-name -WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true - -# PostgreSQL -# https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING -WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker?sslmode=disable -``` - -### `WOODPECKER_DATABASE_DATASOURCE_FILE` - -> Default: empty - -Read the value for `WOODPECKER_DATABASE_DATASOURCE` from the specified filepath - -### `WOODPECKER_ENCRYPTION_KEY` - -> Default: empty - -Encryption key used to encrypt secrets in DB. See [secrets encryption](./40-encryption.md) - -### `WOODPECKER_ENCRYPTION_KEY_FILE` - -> Default: empty - -Read the value for `WOODPECKER_ENCRYPTION_KEY` from the specified filepath - -### `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE` - -> Default: empty - -Filepath to encryption keyset used to encrypt secrets in DB. See [secrets encryption](./40-encryption.md) - -### `WOODPECKER_ENCRYPTION_DISABLE` - -> Default: empty - -Boolean flag to decrypt secrets in DB and disable server encryption. See [secrets encryption](./40-encryption.md) - -### `WOODPECKER_PROMETHEUS_AUTH_TOKEN` - -> Default: empty - -Token to secure the Prometheus metrics endpoint. -Must be set to enable the endpoint. - -### `WOODPECKER_PROMETHEUS_AUTH_TOKEN_FILE` - -> Default: empty - -Read the value for `WOODPECKER_PROMETHEUS_AUTH_TOKEN` from the specified filepath - -### `WOODPECKER_STATUS_CONTEXT` - -> Default: `ci/woodpecker` - -Context prefix Woodpecker will use to publish status messages to SCM. You probably will only need to change it if you run multiple Woodpecker instances for a single repository. - -### `WOODPECKER_STATUS_CONTEXT_FORMAT` - -> Default: `{{ .context }}/{{ .event }}/{{ .workflow }}{{if not (eq .axis_id 0)}}/{{.axis_id}}{{end}}` - -Template for the status messages published to forges, uses [Go templates](https://pkg.go.dev/text/template) as template language. -Supported variables: - -- `context`: Woodpecker's context (see `WOODPECKER_STATUS_CONTEXT`) -- `event`: the event which started the pipeline -- `workflow`: the workflow's name -- `owner`: the repo's owner -- `repo`: the repo's name - -### `WOODPECKER_ADDONS` - -> Default: empty - -List of addon files. See [addons](./75-addons/00-overview.md). - ---- - -### `WOODPECKER_LIMIT_MEM_SWAP` - -> Default: `0` - -The maximum amount of memory a single pipeline container is allowed to swap to disk, configured in bytes. There is no limit if `0`. - -### `WOODPECKER_LIMIT_MEM` - -> Default: `0` - -The maximum amount of memory a single pipeline container can use, configured in bytes. There is no limit if `0`. - -### `WOODPECKER_LIMIT_SHM_SIZE` - -> Default: `0` - -The maximum amount of memory of `/dev/shm` allowed in bytes. There is no limit if `0`. - -### `WOODPECKER_LIMIT_CPU_QUOTA` - -> Default: `0` - -The number of microseconds per CPU period that the container is limited to before throttled. There is no limit if `0`. - -### `WOODPECKER_LIMIT_CPU_SHARES` - -> Default: `0` - -The relative weight vs. other containers. - -### `WOODPECKER_LIMIT_CPU_SET` - -> Default: empty - -Comma-separated list to limit the specific CPUs or cores a pipeline container can use. - -Example: `WOODPECKER_LIMIT_CPU_SET=1,2` - -### `WOODPECKER_CONFIG_SERVICE_ENDPOINT` - -> Default: empty - -Specify a configuration service endpoint, see [Configuration Extension](./100-external-configuration-api.md) - -### `WOODPECKER_FORGE_TIMEOUT` - -> Default: 3s - -Specify timeout when fetching the Woodpecker configuration from forge. See for syntax reference. - -### `WOODPECKER_ENABLE_SWAGGER` - -> Default: true - -Enable the Swagger UI for API documentation. - -### `WOODPECKER_DISABLE_VERSION_CHECK` - -> Default: false - -Disable version check in admin web UI. - ---- - -### `WOODPECKER_GITHUB_...` - -See [GitHub configuration](forges/github/#configuration) - -### `WOODPECKER_GITEA_...` - -See [Gitea configuration](forges/gitea/#configuration) - -### `WOODPECKER_BITBUCKET_...` - -See [Bitbucket configuration](forges/bitbucket/#configuration) - -### `WOODPECKER_GITLAB_...` - -See [Gitlab configuration](forges/gitlab/#configuration) diff --git a/docs/versioned_docs/version-2.2/30-administration/100-external-configuration-api.md b/docs/versioned_docs/version-2.2/30-administration/100-external-configuration-api.md deleted file mode 100644 index a5e216159f..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/100-external-configuration-api.md +++ /dev/null @@ -1,104 +0,0 @@ -# External Configuration API - -To provide additional management and preprocessing capabilities for pipeline configurations Woodpecker supports an HTTP API which can be enabled to call an external config service. -Before the run or restart of any pipeline Woodpecker will make a POST request to an external HTTP API sending the current repository, build information and all current config files retrieved from the repository. The external API can then send back new pipeline configurations that will be used immediately or respond with `HTTP 204` to tell the system to use the existing configuration. - -Every request sent by Woodpecker is signed using a [http-signature](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures) by a private key (ed25519) generated on the first start of the Woodpecker server. You can get the public key for the verification of the http-signature from `http(s)://your-woodpecker-server/api/signature/public-key`. - -A simplistic example configuration service can be found here: [https://github.com/woodpecker-ci/example-config-service](https://github.com/woodpecker-ci/example-config-service) - -:::warning -You need to trust the external config service as it is getting secret information about the repository and pipeline and has the ability to change pipeline configs that could run malicious tasks. -::: - -## Config - -```ini title="Server" -WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig -``` - -### Example request made by Woodpecker - -```json -{ - "repo": { - "id": 100, - "uid": "", - "user_id": 0, - "namespace": "", - "name": "woodpecker-testpipe", - "slug": "", - "scm": "git", - "git_http_url": "", - "git_ssh_url": "", - "link": "", - "default_branch": "", - "private": true, - "visibility": "private", - "active": true, - "config": "", - "trusted": false, - "protected": false, - "ignore_forks": false, - "ignore_pulls": false, - "cancel_pulls": false, - "timeout": 60, - "counter": 0, - "synced": 0, - "created": 0, - "updated": 0, - "version": 0 - }, - "pipeline": { - "author": "myUser", - "author_avatar": "https://myforge.com/avatars/d6b3f7787a685fcdf2a44e2c685c7e03", - "author_email": "my@email.com", - "branch": "main", - "changed_files": ["somefilename.txt"], - "commit": "2fff90f8d288a4640e90f05049fe30e61a14fd50", - "created_at": 0, - "deploy_to": "", - "enqueued_at": 0, - "error": "", - "event": "push", - "finished_at": 0, - "id": 0, - "link_url": "https://myforge.com/myUser/woodpecker-testpipe/commit/2fff90f8d288a4640e90f05049fe30e61a14fd50", - "message": "test old config\n", - "number": 0, - "parent": 0, - "ref": "refs/heads/main", - "refspec": "", - "clone_url": "", - "reviewed_at": 0, - "reviewed_by": "", - "sender": "myUser", - "signed": false, - "started_at": 0, - "status": "", - "timestamp": 1645962783, - "title": "", - "updated_at": 0, - "verified": false - }, - "configs": [ - { - "name": ".woodpecker.yaml", - "data": "steps:\n backend:\n image: alpine\n commands:\n - echo \"Hello there from Repo (.woodpecker.yaml)\"\n" - } - ] -} -``` - -### Example response structure - -```json -{ - "configs": [ - { - "name": "central-override", - "data": "steps:\n backend:\n image: alpine\n commands:\n - echo \"Hello there from ConfigAPI\"\n" - } - ] -} -``` diff --git a/docs/versioned_docs/version-2.2/30-administration/11-forges/10-overview.md b/docs/versioned_docs/version-2.2/30-administration/11-forges/10-overview.md deleted file mode 100644 index 897d3d8972..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/11-forges/10-overview.md +++ /dev/null @@ -1,12 +0,0 @@ -# Forges - -## Supported features - -| Feature | [GitHub](github/) | [Gitea / Forgejo](gitea/) | [Gitlab](gitlab/) | [Bitbucket](bitbucket/) | -| ------------------------------------------------------------- | :----------------: | :-----------------------: | :----------------: | :---------------------: | -| Event: Push | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| Event: Tag | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| Event: Pull-Request | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| Event: Deploy | :white_check_mark: | :x: | :x: | :x: | -| [Multiple workflows](../../20-usage/25-workflows.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| [when.path filter](../../20-usage/20-workflow-syntax.md#path) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | diff --git a/docs/versioned_docs/version-2.2/30-administration/11-forges/20-github.md b/docs/versioned_docs/version-2.2/30-administration/11-forges/20-github.md deleted file mode 100644 index a3e4abdedb..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/11-forges/20-github.md +++ /dev/null @@ -1,79 +0,0 @@ -# GitHub - -Woodpecker comes with built-in support for GitHub and GitHub Enterprise. -To use Woodpecker with GitHub the following environment variables should be set for the server component: - -```ini -WOODPECKER_GITHUB=true -WOODPECKER_GITHUB_CLIENT=YOUR_GITHUB_CLIENT_ID -WOODPECKER_GITHUB_SECRET=YOUR_GITHUB_CLIENT_SECRET -``` - -You will get these values from GitHub when you register your OAuth application. -To do so, go to Settings -> Developer Settings -> GitHub Apps -> New Oauth2 App. - -:::warning -Do not use a "GitHub App" instead of an Oauth2 app as the former will not work correctly with Woodpecker right now (because user access tokens are not being refreshed automatically) -::: - -## App Settings - -- Name: An arbitrary name for your App -- Homepage URL: The URL of your Woodpecker instance -- Callback URL: `https:///authorize` -- (optional) Upload the Woodpecker Logo: - -## Client Secret Creation - -After your App has been created, you can generate a client secret. -Use this one for the `WOODPECKER_GITHUB_SECRET` environment variable. - -## 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. - -### `WOODPECKER_GITHUB` - -> Default: `false` - -Enables the GitHub driver. - -### `WOODPECKER_GITHUB_URL` - -> Default: `https://github.com` - -Configures the GitHub server address. - -### `WOODPECKER_GITHUB_CLIENT` - -> Default: empty - -Configures the GitHub OAuth client id to authorize access. - -### `WOODPECKER_GITHUB_CLIENT_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITHUB_CLIENT` from the specified filepath. - -### `WOODPECKER_GITHUB_SECRET` - -> Default: empty - -Configures the GitHub OAuth client secret. This is used to authorize access. - -### `WOODPECKER_GITHUB_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITHUB_SECRET` from the specified filepath. - -### `WOODPECKER_GITHUB_MERGE_REF` - -> Default: `true` - -### `WOODPECKER_GITHUB_SKIP_VERIFY` - -> Default: `false` - -Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-2.2/30-administration/11-forges/30-gitea.md b/docs/versioned_docs/version-2.2/30-administration/11-forges/30-gitea.md deleted file mode 100644 index 1bae1bd38d..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/11-forges/30-gitea.md +++ /dev/null @@ -1,91 +0,0 @@ -# Gitea / Forgejo - -Woodpecker comes with built-in support for Gitea and the "soft" fork Forgejo. To enable Gitea you should configure the Woodpecker container using the following environment variables: - -```ini -WOODPECKER_GITEA=true -WOODPECKER_GITEA_URL=YOUR_GITEA_URL -WOODPECKER_GITEA_CLIENT=YOUR_GITEA_CLIENT -WOODPECKER_GITEA_SECRET=YOUR_GITEA_CLIENT_SECRET -``` - -## Gitea on the same host with containers - -If you have Gitea also running on the same host within a container, make sure the agent does have access to it. -The agent tries to clone using the URL which Gitea reports through its API. For simplified connectivity, you should add the woodpecker agent to the same docker network as Gitea is in. -Otherwise, the communication should go via the `docker0` gateway (usually 172.17.0.1). - -To configure the Docker network if the network's name is `gitea`, configure it like this: - -```diff title="docker-compose.yaml" - version: '3' - - services: - [...] - woodpecker-agent: - [...] - environment: - - [...] -+ - WOODPECKER_BACKEND_DOCKER_NETWORK=gitea -``` - -## Registration - -Register your application with Gitea to create your client id and secret. You can find the OAuth applications settings of Gitea at `https://gitea./user/settings/`. It is very import the authorization callback URL matches your http(s) scheme and hostname exactly with `https:///authorize` as the path. - -If you run the Woodpecker CI server on the same host as the Gitea instance, you might also need to allow local connections in Gitea, since version `v1.16`. Otherwise webhooks will fail. Add the following lines to your Gitea configuration (usually at `/etc/gitea/conf/app.ini`). - -```ini -[webhook] -ALLOWED_HOST_LIST=external,loopback -``` - -For reference see [Configuration Cheat Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/#webhook-webhook). - -![gitea oauth setup](gitea_oauth.gif) - -## 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. - -### `WOODPECKER_GITEA` - -> Default: `false` - -Enables the Gitea driver. - -### `WOODPECKER_GITEA_URL` - -> Default: `https://try.gitea.io` - -Configures the Gitea server address. - -### `WOODPECKER_GITEA_CLIENT` - -> Default: empty - -Configures the Gitea OAuth client id. This is used to authorize access. - -### `WOODPECKER_GITEA_CLIENT_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITEA_CLIENT` from the specified filepath - -### `WOODPECKER_GITEA_SECRET` - -> Default: empty - -Configures the Gitea OAuth client secret. This is used to authorize access. - -### `WOODPECKER_GITEA_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITEA_SECRET` from the specified filepath - -### `WOODPECKER_GITEA_SKIP_VERIFY` - -> Default: `false` - -Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-2.2/30-administration/11-forges/40-gitlab.md b/docs/versioned_docs/version-2.2/30-administration/11-forges/40-gitlab.md deleted file mode 100644 index 7c55d62631..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/11-forges/40-gitlab.md +++ /dev/null @@ -1,64 +0,0 @@ -# GitLab - -Woodpecker comes with built-in support for the GitLab version 8.2 and higher. To enable GitLab you should configure the Woodpecker container using the following environment variables: - -```ini -WOODPECKER_GITLAB=true -WOODPECKER_GITLAB_URL=http://gitlab.mycompany.com -WOODPECKER_GITLAB_CLIENT=95c0282573633eb25e82 -WOODPECKER_GITLAB_SECRET=30f5064039e6b359e075 -``` - -## Registration - -You must register your application with GitLab in order to generate a Client and Secret. Navigate to your account settings and choose Applications from the menu, and click New Application. - -Please use `http://woodpecker.mycompany.com/authorize` as the Authorization callback URL. Grant `api` scope to the application. - -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`. - -## 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. - -### `WOODPECKER_GITLAB` - -> Default: `false` - -Enables the GitLab driver. - -### `WOODPECKER_GITLAB_URL` - -> Default: `https://gitlab.com` - -Configures the GitLab server address. - -### `WOODPECKER_GITLAB_CLIENT` - -> Default: empty - -Configures the GitLab OAuth client id. This is used to authorize access. - -### `WOODPECKER_GITLAB_CLIENT_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITLAB_CLIENT` from the specified filepath - -### `WOODPECKER_GITLAB_SECRET` - -> Default: empty - -Configures the GitLab OAuth client secret. This is used to authorize access. - -### `WOODPECKER_GITLAB_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_GITLAB_SECRET` from the specified filepath - -### `WOODPECKER_GITLAB_SKIP_VERIFY` - -> Default: `false` - -Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-2.2/30-administration/11-forges/50-bitbucket.md b/docs/versioned_docs/version-2.2/30-administration/11-forges/50-bitbucket.md deleted file mode 100644 index 8d153258a4..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/11-forges/50-bitbucket.md +++ /dev/null @@ -1,71 +0,0 @@ -# Bitbucket - -Woodpecker comes with built-in support for Bitbucket Cloud. To enable Bitbucket Cloud you should configure the Woodpecker container using the following environment variables: - -```ini -WOODPECKER_BITBUCKET=true -WOODPECKER_BITBUCKET_CLIENT=... # called "Key" in Bitbucket -WOODPECKER_BITBUCKET_SECRET=... -``` - -## Registration - -You must register an OAuth application at Bitbucket in order to get a key and secret combination for woodpecker. Navigate to your workspace settings and choose `OAuth consumers` from the menu, and finally click `Add Consumer` (the url should be like: `https://bitbucket.org/[your-project-name]/workspace/settings/api`). - -Please set a name and set the `Callback URL` like this: - -```uri -https:///authorize -``` - -![bitbucket oauth setup](bitbucket_oauth.png) - -Please also be sure to check the following permissions: - -- Account: Email, Read -- Workspace membership: Read -- Projects: Read -- Repositories: Read -- Pull requests: Read -- Webhooks: Read and Write - -![bitbucket permissions](bitbucket_permissions.png) - -## 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. - -### `WOODPECKER_BITBUCKET` - -> Default: `false` - -Enables the Bitbucket driver. - -### `WOODPECKER_BITBUCKET_CLIENT` - -> Default: empty - -Configures the Bitbucket OAuth client key. This is used to authorize access. - -### `WOODPECKER_BITBUCKET_CLIENT_FILE` - -> Default: empty - -Read the value for `WOODPECKER_BITBUCKET_CLIENT` from the specified filepath - -### `WOODPECKER_BITBUCKET_SECRET` - -> Default: empty - -Configures the Bitbucket OAuth client secret. This is used to authorize access. - -### `WOODPECKER_BITBUCKET_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_BITBUCKET_SECRET` from the specified filepath - -## Missing Features - -Path filters for pull requests are not supported. We are interested in patches to include this functionality. -If you are interested in contributing to Woodpecker and submitting a patch please **contact us** via [Discord](https://discord.gg/fcMQqSMXJy) or [Matrix](https://matrix.to/#/#WoodpeckerCI-Develop:obermui.de). diff --git a/docs/versioned_docs/version-2.2/30-administration/11-forges/_category_.yaml b/docs/versioned_docs/version-2.2/30-administration/11-forges/_category_.yaml deleted file mode 100644 index e240bfc513..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/11-forges/_category_.yaml +++ /dev/null @@ -1,6 +0,0 @@ -label: 'Forges' -collapsible: true -collapsed: true -link: - type: 'doc' - id: 'overview' diff --git a/docs/versioned_docs/version-2.2/30-administration/11-forges/bitbucket_oauth.png b/docs/versioned_docs/version-2.2/30-administration/11-forges/bitbucket_oauth.png deleted file mode 100644 index 17ecf38ab9..0000000000 Binary files a/docs/versioned_docs/version-2.2/30-administration/11-forges/bitbucket_oauth.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/30-administration/11-forges/bitbucket_permissions.png b/docs/versioned_docs/version-2.2/30-administration/11-forges/bitbucket_permissions.png deleted file mode 100644 index 0269f98b0b..0000000000 Binary files a/docs/versioned_docs/version-2.2/30-administration/11-forges/bitbucket_permissions.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/30-administration/11-forges/gitea_oauth.gif b/docs/versioned_docs/version-2.2/30-administration/11-forges/gitea_oauth.gif deleted file mode 100644 index 7478f93856..0000000000 Binary files a/docs/versioned_docs/version-2.2/30-administration/11-forges/gitea_oauth.gif and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/30-administration/11-forges/github_oauth.png b/docs/versioned_docs/version-2.2/30-administration/11-forges/github_oauth.png deleted file mode 100644 index 6b0edef0ff..0000000000 Binary files a/docs/versioned_docs/version-2.2/30-administration/11-forges/github_oauth.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/30-administration/15-agent-config.md b/docs/versioned_docs/version-2.2/30-administration/15-agent-config.md deleted file mode 100644 index 4a3a5e5e00..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/15-agent-config.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -toc_max_heading_level: 2 ---- - -# Agent configuration - -Agents are configured by the command line or environment variables. At the minimum you need the following information: - -```ini -WOODPECKER_SERVER=localhost:9000 -WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here" -``` - -The following are automatically set and can be overridden: - -- `WOODPECKER_HOSTNAME` if not set, becomes the OS' hostname -- `WOODPECKER_MAX_WORKFLOWS` if not set, defaults to 1 - -## Workflows per agent - -By default, the maximum workflows that are executed in parallel on an agent is 1. If required, you can add `WOODPECKER_MAX_WORKFLOWS` to increase your parallel processing for an agent. - -```ini -WOODPECKER_SERVER=localhost:9000 -WOODPECKER_AGENT_SECRET="your-shared-secret-goes-here" -WOODPECKER_MAX_WORKFLOWS=4 -``` - -## Agent registration - -When the agent starts it connects to the server using the token from `WOODPECKER_AGENT_SECRET`. The server identifies the agent and registers the agent in its database if it wasn't connected before. - -There are two types of tokens to connect an agent to the server: - -### Using system token - -A _system token_ is a token that is used system-wide, e.g. when you set the same token in `WOODPECKER_AGENT_SECRET` on both the server and the agents. - -In that case registration process would be as following: - -1. The first time the agent communicates with the server, it is using the system token -1. The server registers the agent in its database if not done before and generates a unique ID which is then sent back to the agent -1. The agent stores the received ID in a file (configured by `WOODPECKER_AGENT_CONFIG_FILE`) -1. At the following startups, the agent uses the system token **and** its received ID to identify itself to the server - -### Using agent token - -An _agent token_ is a token that is used by only one particular agent. This unique token is applied to the agent by `WOODPECKER_AGENT_SECRET`. - -To get an _agent token_ you have to register the agent manually in the server using the UI: - -1. The administrator registers a new agent manually at `Settings -> Agents -> Add agent` - ![Agent creation](./new-agent-registration.png) - ![Agent created](./new-agent-created.png) -1. The generated token from the previous step has to be provided to the agent using `WOODPECKER_AGENT_SECRET` -1. The agent will connect to the server using the provided token and will update its status in the UI: - ![Agent connected](./new-agent-connected.png) - -## All agent configuration options - -Here is the full list of configuration options and their default variables. - -### `WOODPECKER_SERVER` - -> Default: `localhost:9000` - -Configures gRPC address of the server. - -### `WOODPECKER_USERNAME` - -> Default: `x-oauth-basic` - -The gRPC username. - -### `WOODPECKER_AGENT_SECRET` - -> Default: empty - -A shared secret used by server and agents to authenticate communication. A secret can be generated by `openssl rand -hex 32`. - -### `WOODPECKER_AGENT_SECRET_FILE` - -> Default: empty - -Read the value for `WOODPECKER_AGENT_SECRET` from the specified filepath, e.g. `/etc/woodpecker/agent-secret.conf` - -### `WOODPECKER_LOG_LEVEL` - -> Default: empty - -Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty. - -### `WOODPECKER_DEBUG_PRETTY` - -> Default: `false` - -Enable pretty-printed debug output. - -### `WOODPECKER_DEBUG_NOCOLOR` - -> Default: `true` - -Disable colored debug output. - -### `WOODPECKER_HOSTNAME` - -> Default: empty - -Configures the agent hostname. - -### `WOODPECKER_AGENT_CONFIG_FILE` - -> Default: `/etc/woodpecker/agent.conf` - -Configures the path of the agent config file. - -### `WOODPECKER_MAX_WORKFLOWS` - -> Default: `1` - -Configures the number of parallel workflows. - -### `WOODPECKER_FILTER_LABELS` - -> Default: empty - -Configures labels to filter pipeline pick up. Use a list of key-value pairs like `key=value,second-key=*`. `*` can be used as a wildcard. By default, agents provide three additional labels `platform=os/arch`, `hostname=my-agent` and `repo=*` which can be overwritten if needed. To learn how labels work, check out the [pipeline syntax page](../20-usage/20-workflow-syntax.md#labels). - -### `WOODPECKER_HEALTHCHECK` - -> Default: `true` - -Enable healthcheck endpoint. - -### `WOODPECKER_HEALTHCHECK_ADDR` - -> Default: `:3000` - -Configures healthcheck endpoint address. - -### `WOODPECKER_KEEPALIVE_TIME` - -> Default: empty - -After a duration of this time of no activity, the agent pings the server to check if the transport is still alive. - -### `WOODPECKER_KEEPALIVE_TIMEOUT` - -> Default: `20s` - -After pinging for a keepalive check, the agent waits for a duration of this time before closing the connection if no activity. - -### `WOODPECKER_GRPC_SECURE` - -> Default: `false` - -Configures if the connection to `WOODPECKER_SERVER` should be made using a secure transport. - -### `WOODPECKER_GRPC_VERIFY` - -> Default: `true` - -Configures if the gRPC server certificate should be verified, only valid when `WOODPECKER_GRPC_SECURE` is `true`. - -### `WOODPECKER_BACKEND` - -> Default: `auto-detect` - -Configures the backend engine to run pipelines on. Possible values are `auto-detect`, `docker`, `local` or `kubernetes`. - -### `WOODPECKER_ADDONS` - -> Default: empty - -List of addon files. See [addons](./75-addons/00-overview.md). - -### `WOODPECKER_BACKEND_DOCKER_*` - -See [Docker backend configuration](./22-backends/10-docker.md#configuration) - -### `WOODPECKER_BACKEND_K8S_*` - -See [Kubernetes backend configuration](./22-backends/40-kubernetes.md#configuration) - -### `WOODPECKER_BACKEND_LOCAL_*` - -See [Local backend configuration](./22-backends/20-local.md#options) - -## Advanced Settings - -:::warning -Only change these If you know what you do. -::: - -### `WOODPECKER_CONNECT_RETRY_COUNT` - -> Default: `5` - -Configures number of times agent retries to connect to the server. - -### `WOODPECKER_CONNECT_RETRY_DELAY` - -> Default: `2s` - -Configures delay between agent connection retries to the server. diff --git a/docs/versioned_docs/version-2.2/30-administration/22-backends/10-docker.md b/docs/versioned_docs/version-2.2/30-administration/22-backends/10-docker.md deleted file mode 100644 index faa9e3d91d..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/22-backends/10-docker.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -toc_max_heading_level: 2 ---- - -# Docker backend - -This is the original backend used with Woodpecker. The docker backend executes each step inside a separate container started on the agent. - -## Docker credentials - -Woodpecker supports [Docker credentials](https://github.com/docker/docker-credential-helpers) to securely store registry credentials. Install your corresponding credential helper and configure it in your Docker config file passed via [`WOODPECKER_DOCKER_CONFIG`](../10-server-config.md#woodpecker_docker_config). - -To add your credential helper to the Woodpecker server container you could use the following code to build a custom image: - -```dockerfile -FROM woodpeckerci/woodpecker-server:latest-alpine - -RUN apk add -U --no-cache docker-credential-ecr-login -``` - -## Podman support - -While the agent was developed with Docker/Moby, Podman can also be used by setting the environment variable `DOCKER_HOST` to point to the Podman socket. In order to work without workarounds, Podman 4.0 (or above) is required. - -## Image cleanup - -The agent **will not** automatically remove images from the host. This task should be managed by the host system. For example, you can use a cron job to periodically do clean-up tasks for the CI runner. - -:::danger -The following commands **are destructive** and **irreversible** it is highly recommended that you test these commands on your system before running them in production via a cron job or other automation. -::: - -### Remove all unused images - -```bash -docker image rm $(docker images --filter "dangling=true" -q --no-trunc) -``` - -### Remove Woodpecker volumes - -```bash -docker volume rm $(docker volume ls --filter name=^wp_* --filter dangling=true -q) -``` - -## Configuration - -### `WOODPECKER_BACKEND_DOCKER_NETWORK` - -> Default: empty - -Set to the name of an existing network which will be attached to all your pipeline containers (steps). Please be careful as this allows the containers of different pipelines to access each other! - -### `WOODPECKER_BACKEND_DOCKER_ENABLE_IPV6` - -> Default: `false` - -Enable IPv6 for the networks used by pipeline containers (steps). Make sure you configured your docker daemon to support IPv6. - -### `WOODPECKER_BACKEND_DOCKER_VOLUMES` - -> Default: empty - -List of default volumes separated by comma to be mounted to all pipeline containers (steps). For example to use custom CA -certificates installed on host and host timezone use `/etc/ssl/certs:/etc/ssl/certs:ro,/etc/timezone:/etc/timezone`. diff --git a/docs/versioned_docs/version-2.2/30-administration/22-backends/20-local.md b/docs/versioned_docs/version-2.2/30-administration/22-backends/20-local.md deleted file mode 100644 index c2d229d57b..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/22-backends/20-local.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -toc_max_heading_level: 3 ---- - -# Local backend - -:::danger -The local backend will execute the pipelines on the local system without any isolation of any kind. -::: - -:::note -Currently we do not support services for this backend. -[Read more here](https://github.com/woodpecker-ci/woodpecker/issues/3095). -::: - -Since the code runs directly in the same context as the agent (same user, same -filesystem), a malicious pipeline could be used to access the agent -configuration especially the `WOODPECKER_AGENT_SECRET` variable. - -It is recommended to use this backend only for private setup where the code and -pipeline can be trusted. You shouldn't use it for a public facing CI where -anyone can submit code or add new repositories. You shouldn't execute the agent -as a privileged user (root). - -The local backend will use a random directory in $TMPDIR to store the cloned -code and execute commands. - -In order to use this backend, you need to download (or build) the -[binary](https://github.com/woodpecker-ci/woodpecker/releases/latest) of the -agent, configure it and run it on the host machine. - -## Usage - -To enable the local backend, add this to your configuration: - -```ini -WOODPECKER_BACKEND=local -``` - -### Shell - -The `image` entry is used to specify the shell, such as Bash or Fish, that is -used to run the commands. - -```yaml title=".woodpecker.yaml" -steps: - build: - image: bash - commands: [...] -``` - -### Plugins - -Plugins are just executable binaries: - -```yaml -steps: - build: - image: /usr/bin/tree -``` - -If no commands are provided, we treat them as plugins in the usual manner. -In the context of the local backend, plugins are simply executable binaries, which can be located using their name if they are listed in `$PATH`, or through an absolute path. - -### Options - -#### `WOODPECKER_BACKEND_LOCAL_TEMP_DIR` - -> Default: default temp directory - -Directory to create folders for workflows. diff --git a/docs/versioned_docs/version-2.2/30-administration/22-backends/40-kubernetes.md b/docs/versioned_docs/version-2.2/30-administration/22-backends/40-kubernetes.md deleted file mode 100644 index b4cba009a5..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/22-backends/40-kubernetes.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -toc_max_heading_level: 2 ---- - -# Kubernetes backend - -The kubernetes backend executes steps inside standalone pods. A temporary PVC is created for the lifetime of the pipeline to transfer files between steps. - -## Job specific configuration - -### Resources - -The kubernetes backend also allows for specifying requests and limits on a per-step basic, most commonly for CPU and memory. -We recommend to add a `resources` definition to all steps to ensure efficient scheduling. - -Here is an example definition with an arbitrary `resources` definition below the `backend_options` section: - -```yaml -steps: - 'My kubernetes step': - image: alpine - commands: - - echo "Hello world" - backend_options: - kubernetes: - resources: - requests: - memory: 200Mi - cpu: 100m - limits: - memory: 400Mi - cpu: 1000m -``` - -### `serviceAccountName` - -Specify the name of the ServiceAccount which the build pod will mount. This serviceAccount must be created externally. -See the [kubernetes documentation](https://kubernetes.io/docs/concepts/security/service-accounts/) for more information on using serviceAccounts. - -### `nodeSelector` - -Specifies the label which is used to select the node on which the job will be executed. - -Labels defined here will be appended to a list which already contains `"kubernetes.io/arch"`. -By default `"kubernetes.io/arch"` is inferred from the agents' platform. One can override it by setting that label in the `nodeSelector` section of the `backend_options`. -Without a manual overwrite, builds will be randomly assigned to the runners and inherit their respective architectures. - -To overwrite this, one needs to set the label in the `nodeSelector` section of the `backend_options`. -A practical example for this is when running a matrix-build and delegating specific elements of the matrix to run on a specific architecture. -In this case, one must define an arbitrary key in the matrix section of the respective matrix element: - -```yaml -matrix: - include: - - NAME: runner1 - ARCH: arm64 -``` - -And then overwrite the `nodeSelector` in the `backend_options` section of the step(s) using the name of the respective env var: - -```yaml -[...] - backend_options: - kubernetes: - nodeSelector: - kubernetes.io/arch: "${ARCH}" -``` - -### `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. -See the [kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for more information on using tolerations. - -Example pipeline configuration: - -```yaml -steps: - build: - image: golang - commands: - - go get - - go build - - go test - backend_options: - kubernetes: - serviceAccountName: 'my-service-account' - resources: - requests: - memory: 128Mi - cpu: 1000m - limits: - memory: 256Mi - nodeSelector: - beta.kubernetes.io/instance-type: p3.8xlarge - tolerations: - - key: 'key1' - operator: 'Equal' - value: 'value1' - effect: 'NoSchedule' - tolerationSeconds: 3600 -``` - -### Volumes - -To mount volumes a persistent volume (PV) and persistent volume claim (PVC) are needed on the cluster which can be referenced in steps via the `volume:` option. -Assuming a PVC named "woodpecker-cache" exists, it can be referenced as follows in a step: - -```yaml -steps: - "Restore Cache": - image: meltwater/drone-cache - volumes: - - woodpecker-cache:/woodpecker/src/cache - settings: - mount: - - "woodpecker-cache" - [...] -``` - -### `securityContext` - -Use the following configuration to set the `securityContext` for the pod/container running a given pipeline step: - -```yaml -steps: - test: - image: alpine - commands: - - echo Hello world - backend_options: - kubernetes: - securityContext: - runAsUser: 999 - runAsGroup: 999 - privileged: true - [...] -``` - -Note that the `backend_options.kubernetes.securityContext` object allows you to set both pod and container level security context options in one object. -By default, the properties will be set at the pod level. Properties that are only supported on the container level will be set there instead. So, the -configuration shown above will result in something like the following pod spec: - -```yaml -kind: Pod -spec: - securityContext: - runAsUser: 999 - runAsGroup: 999 - containers: - - name: wp-01hcd83q7be5ymh89k5accn3k6-0-step-0 - image: alpine - securityContext: - privileged: true - [...] -``` - -See the [kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for more information on using `securityContext`. - -## Tips and tricks - -### CRI-O - -CRI-O users currently need to configure the workspace for all workflows in order for them to run correctly. Add the following at the beginning of your configuration: - -```yaml -workspace: - base: '/woodpecker' - path: '/' -``` - -See [this issue](https://github.com/woodpecker-ci/woodpecker/issues/2510) for more details. - -## Configuration - -These env vars can be set in the `env:` sections of the agent. - -### `WOODPECKER_BACKEND_K8S_NAMESPACE` - -> Default: `woodpecker` - -The namespace to create worker pods in. - -### `WOODPECKER_BACKEND_K8S_VOLUME_SIZE` - -> Default: `10G` - -The volume size of the pipeline volume. - -### `WOODPECKER_BACKEND_K8S_STORAGE_CLASS` - -> Default: empty - -The storage class to use for the pipeline volume. - -### `WOODPECKER_BACKEND_K8S_STORAGE_RWX` - -> Default: `true` - -Determines if `RWX` should be used for the pipeline volume's [access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes). If false, `RWO` is used instead. - -### `WOODPECKER_BACKEND_K8S_POD_LABELS` - -> Default: empty - -Additional labels to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-label":"test-value"}`. - -### `WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS` - -> Default: empty - -Additional annotations to apply to worker pods. Must be a YAML object, e.g. `{"example.com/test-annotation":"test-value"}`. - -### `WOODPECKER_BACKEND_K8S_SECCTX_NONROOT` - -> Default: `false` - -Determines if containers must be required to run as non-root users. diff --git a/docs/versioned_docs/version-2.2/30-administration/22-backends/_category_.yaml b/docs/versioned_docs/version-2.2/30-administration/22-backends/_category_.yaml deleted file mode 100644 index 556444f02f..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/22-backends/_category_.yaml +++ /dev/null @@ -1,4 +0,0 @@ -label: 'Backends' -# position: 3 -collapsible: true -collapsed: true diff --git a/docs/versioned_docs/version-2.2/30-administration/30-database.md b/docs/versioned_docs/version-2.2/30-administration/30-database.md deleted file mode 100644 index e3e33ba7d1..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/30-database.md +++ /dev/null @@ -1,53 +0,0 @@ -# Databases - -The default database engine of Woodpecker is an embedded SQLite database which requires zero installation or configuration. But you can replace it with a MySQL/MariaDB or Postgres database. - -## Configure SQLite - -By default Woodpecker uses a SQLite database stored under `/var/lib/woodpecker/`. If using containers, you can mount a [data volume](https://docs.docker.com/storage/volumes/#create-and-manage-volumes) to persist the SQLite database. - -```diff title="docker-compose.yaml" - version: '3' - - services: - woodpecker-server: - [...] -+ volumes: -+ - woodpecker-server-data:/var/lib/woodpecker/ -``` - -## Configure MySQL/MariaDB - -The below example demonstrates MySQL database configuration. See the official driver [documentation](https://github.com/go-sql-driver/mysql#dsn-data-source-name) for configuration options and examples. -The minimum version of MySQL/MariaDB required is determined by the `go-sql-driver/mysql` - see [it's README](https://github.com/go-sql-driver/mysql#requirements) for more information. - -```ini -WOODPECKER_DATABASE_DRIVER=mysql -WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true -``` - -## Configure Postgres - -The below example demonstrates Postgres database configuration. See the official driver [documentation](https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING) for configuration options and examples. -Please use Postgres versions equal or higher than **11**. - -```ini -WOODPECKER_DATABASE_DRIVER=postgres -WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/postgres?sslmode=disable -``` - -## Database Creation - -Woodpecker does not create your database automatically. If you are using the MySQL or Postgres driver you will need to manually create your database using `CREATE DATABASE`. - -## Database Migration - -Woodpecker automatically handles database migration, including the initial creation of tables and indexes. New versions of Woodpecker will automatically upgrade the database unless otherwise specified in the release notes. - -## Database Backups - -Woodpecker does not perform database backups. This should be handled by separate third party tools provided by your database vendor of choice. - -## Database Archiving - -Woodpecker does not perform data archival; it considered out-of-scope for the project. Woodpecker is rather conservative with the amount of data it stores, however, you should expect the database logs to grow the size of your database considerably. diff --git a/docs/versioned_docs/version-2.2/30-administration/40-encryption.md b/docs/versioned_docs/version-2.2/30-administration/40-encryption.md deleted file mode 100644 index f630711d85..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/40-encryption.md +++ /dev/null @@ -1,83 +0,0 @@ -# Secrets encryption - -:::danger -Secrets encryption is currently broken and therefore disabled by default. It will be fixed in an upcoming release. - -Check: - -- and -- - -::: - -By default, Woodpecker does not encrypt secrets in its database. You can enable encryption -using simple AES key or more advanced [Google TINK](https://developers.google.com/tink) encryption. - -## Common - -### Enabling secrets encryption - -To enable secrets encryption and encrypt all existing secrets in database set -`WOODPECKER_ENCRYPTION_KEY`, `WOODPECKER_ENCRYPTION_KEY_FILE` or `WOODPECKER_ENCRYPTION_TINK_KEYSET_PATH` environment -variable depending on encryption method of your choice. - -After encryption is enabled you will be unable to start Woodpecker server without providing valid encryption key! - -### Disabling encryption and decrypting all secrets - -To disable secrets encryption and decrypt database you need to start server with valid -`WOODPECKER_ENCRYPTION_KEY` or `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE` environment variable set depending on -enabled encryption method, and `WOODPECKER_ENCRYPTION_DISABLE` set to true. - -After secrets was decrypted server will proceed working in unencrypted mode. You will not need to use "disable encryption" -variable or encryption keys to start server anymore. - -## AES - -Simple AES encryption. - -### Configuration - -You can manage encryption on server using these environment variables: - -- `WOODPECKER_ENCRYPTION_KEY` - encryption key -- `WOODPECKER_ENCRYPTION_KEY_FILE` - file to read encryption key from -- `WOODPECKER_ENCRYPTION_DISABLE` - disable encryption flag used to decrypt all data on server - -## TINK - -TINK uses AEAD encryption instead of simple AES and supports key rotation. - -### Configuration - -You can manage encryption on server using these two environment variables: - -- `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE` - keyset filepath -- `WOODPECKER_ENCRYPTION_DISABLE` - disable encryption flag used to decrypt all data on server - -### Encryption keys - -You will need plaintext AEAD-compatible Google TINK keyset to encrypt your data. - -To generate it and then rotate keys if needed, install `tinkey`([installation guide](https://developers.google.com/tink/install-tinkey)) - -Keyset contains one or more keys, used to encrypt or decrypt your data, and primary key ID, used to determine which key -to use while encrypting new data. - -Keyset generation example: - -```bash -tinkey create-keyset --key-template AES256_GCM --out-format json --out keyset.json -``` - -### Key rotation - -Use `tinkey` to rotate encryption keys in your existing keyset: - -```bash -tinkey rotate-keyset --in keyset_v1.json --out keyset_v2.json --key-template AES256_GCM -``` - -Then you just need to replace server keyset file with the new one. At the moment server detects new encryption -keyset it will re-encrypt all existing secrets with the new key, so you will be unable to start server with previous -keyset anymore. diff --git a/docs/versioned_docs/version-2.2/30-administration/60-ssl.md b/docs/versioned_docs/version-2.2/30-administration/60-ssl.md deleted file mode 100644 index 74de210230..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/60-ssl.md +++ /dev/null @@ -1,90 +0,0 @@ -# SSL - -Woodpecker supports two ways of enabling SSL communication. You can either use Let's Encrypt to get automated SSL support with -renewal or provide your own SSL certificates. - -## Let's Encrypt - -Woodpecker supports automated SSL configuration and updates using Let's Encrypt. - -You can enable Let's Encrypt by making the following modifications to your server configuration: - -```ini -WOODPECKER_LETS_ENCRYPT=true -WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld -``` - -Note that Woodpecker uses the hostname from the `WOODPECKER_HOST` environment variable when requesting certificates. For example, if `WOODPECKER_HOST=https://example.com` is set the certificate is requested for `example.com`. To receive emails before certificates expire Let's Encrypt requires an email address. You can set it with `WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld`. - -The SSL certificates are stored in `$HOME/.local/share/certmagic` for binary versions of Woodpecker and in `/var/lib/woodpecker` for the Container versions of it. You can set a custom path by setting `XDG_DATA_HOME` if required. - -> Once enabled you can visit the Woodpecker UI with http and the HTTPS address. HTTP will be redirected to HTTPS. - -### Certificate Cache - -Woodpecker writes the certificates to `/var/lib/woodpecker/certmagic/`. - -### Certificate Updates - -Woodpecker uses the official Go acme library which will handle certificate upgrades. There should be no addition configuration or management required. - -## SSL with own certificates - -Woodpecker supports SSL configuration by mounting certificates into your container. - -```ini -WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt -WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key -``` - -### Certificate Chain - -The most common problem encountered is providing a certificate file without the intermediate chain. - -> LoadX509KeyPair reads and parses a public/private key pair from a pair of files. The files must contain PEM encoded data. The certificate file may contain intermediate certificates following the leaf certificate to form a certificate chain. - -### Certificate Errors - -SSL support is provided using the [ListenAndServeTLS](https://golang.org/pkg/net/http/#ListenAndServeTLS) function from the Go standard library. If you receive certificate errors or warnings please examine your configuration more closely. - -### Running in containers - -Update your configuration to expose the following ports: - -```diff title="docker-compose.yaml" - version: '3' - - services: - woodpecker-server: - [...] - ports: -+ - 80:80 -+ - 443:443 - - 9000:9000 -``` - -Update your configuration to mount your certificate and key: - -```diff title="docker-compose.yaml" - version: '3' - - services: - woodpecker-server: - [...] - volumes: -+ - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt -+ - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key -``` - -Update your configuration to provide the paths of your certificate and key: - -```yaml title="docker-compose.yaml" - version: '3' - - services: - woodpecker-server: - [...] - environment: -+ - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt -+ - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key -``` diff --git a/docs/versioned_docs/version-2.2/30-administration/70-proxy.md b/docs/versioned_docs/version-2.2/30-administration/70-proxy.md deleted file mode 100644 index 4aae2fbe1d..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/70-proxy.md +++ /dev/null @@ -1,199 +0,0 @@ -# Proxy - -## Apache - -This guide provides a brief overview for installing Woodpecker server behind the Apache2 web-server. This is an example configuration: - -```apacheconf -ProxyPreserveHost On - -RequestHeader set X-Forwarded-Proto "https" - -ProxyPass / http://127.0.0.1:8000/ -ProxyPassReverse / http://127.0.0.1:8000/ -``` - -You must have these Apache modules installed: - -- `proxy` -- `proxy_http` - -You must configure Apache to set `X-Forwarded-Proto` when using https. - -```diff - ProxyPreserveHost On - -+RequestHeader set X-Forwarded-Proto "https" - - ProxyPass / http://127.0.0.1:8000/ - ProxyPassReverse / http://127.0.0.1:8000/ -``` - -## Nginx - -This guide provides a basic overview for installing Woodpecker server behind the Nginx web-server. For more advanced configuration options please consult the official Nginx [documentation](https://www.nginx.com/resources/admin-guide/). - -Example configuration: - -```nginx -server { - listen 80; - server_name woodpecker.example.com; - - location / { - proxy_set_header X-Forwarded-For $remote_addr; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header Host $http_host; - - proxy_pass http://127.0.0.1:8000; - proxy_redirect off; - proxy_http_version 1.1; - proxy_buffering off; - - chunked_transfer_encoding off; - } -} -``` - -You must configure the proxy to set `X-Forwarded` proxy headers: - -```diff - server { - listen 80; - server_name woodpecker.example.com; - - location / { -+ proxy_set_header X-Forwarded-For $remote_addr; -+ proxy_set_header X-Forwarded-Proto $scheme; - - proxy_pass http://127.0.0.1:8000; - proxy_redirect off; - proxy_http_version 1.1; - proxy_buffering off; - - chunked_transfer_encoding off; - } - } -``` - -## Caddy - -This guide provides a brief overview for installing Woodpecker server behind the [Caddy web-server](https://caddyserver.com/). This is an example caddyfile proxy configuration: - -```caddy -# expose WebUI and API -woodpecker.example.com { - reverse_proxy woodpecker-server:8000 -} - -# expose gRPC -woodpeckeragent.example.com { - reverse_proxy h2c://woodpecker-server:9000 -} -``` - -:::note -Above configuration shows how to create reverse-proxies for web and agent communication. If your agent uses SSL do not forget to enable [`WOODPECKER_GRPC_SECURE`](./15-agent-config.md#woodpecker_grpc_secure). -::: - -## Tunnelmole - -[Tunnelmole](https://github.com/robbie-cahill/tunnelmole-client) is an open source tunneling tool. - -Start by [installing tunnelmole](https://github.com/robbie-cahill/tunnelmole-client#installation). - -After the installation, run the following command to start tunnelmole: - -```bash -tmole 8000 -``` - -It will start a tunnel and will give a response like this: - -```bash -âžœ ~ tmole 8000 -http://bvdo5f-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:8000 -https://bvdo5f-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:8000 -``` - -Set `WOODPECKER_HOST` to the Tunnelmole URL (`xxx.tunnelmole.net`) and start the server. - -## Ngrok - -[Ngrok](https://ngrok.com/) is a popular closed source tunnelling tool. After installing ngrok, open a new console and run the following command: - -```bash -ngrok http 8000 -``` - -Set `WOODPECKER_HOST` to the ngrok URL (usually xxx.ngrok.io) and start the server. - -## Traefik - -To install the Woodpecker server behind a [Traefik](https://traefik.io/) load balancer, you must expose both the `http` and the `gRPC` ports. Here is a comprehensive example, considering you are running Traefik with docker swarm and want to do TLS termination and automatic redirection from http to https. - -```yaml -version: '3.8' - -services: - server: - image: woodpeckerci/woodpecker-server:latest - environment: - - WOODPECKER_OPEN=true - - WOODPECKER_ADMIN=your_admin_user - # other settings ... - - networks: - - dmz # externally defined network, so that traefik can connect to the server - volumes: - - woodpecker-server-data:/var/lib/woodpecker/ - - deploy: - labels: - - traefik.enable=true - - # web server - - traefik.http.services.woodpecker-service.loadbalancer.server.port=8000 - - - traefik.http.routers.woodpecker-secure.rule=Host(`cd.yourdomain.com`) - - traefik.http.routers.woodpecker-secure.tls=true - - traefik.http.routers.woodpecker-secure.tls.certresolver=letsencrypt - - traefik.http.routers.woodpecker-secure.entrypoints=websecure - - traefik.http.routers.woodpecker-secure.service=woodpecker-service - - - traefik.http.routers.woodpecker.rule=Host(`cd.yourdomain.com`) - - traefik.http.routers.woodpecker.entrypoints=web - - traefik.http.routers.woodpecker.service=woodpecker-service - - - traefik.http.middlewares.woodpecker-redirect.redirectscheme.scheme=https - - traefik.http.middlewares.woodpecker-redirect.redirectscheme.permanent=true - - traefik.http.routers.woodpecker.middlewares=woodpecker-redirect@docker - - # gRPC service - - traefik.http.services.woodpecker-grpc.loadbalancer.server.port=9000 - - traefik.http.services.woodpecker-grpc.loadbalancer.server.scheme=h2c - - - traefik.http.routers.woodpecker-grpc-secure.rule=Host(`woodpecker-grpc.yourdomain.com`) - - traefik.http.routers.woodpecker-grpc-secure.tls=true - - traefik.http.routers.woodpecker-grpc-secure.tls.certresolver=letsencrypt - - traefik.http.routers.woodpecker-grpc-secure.entrypoints=websecure - - traefik.http.routers.woodpecker-grpc-secure.service=woodpecker-grpc - - - traefik.http.routers.woodpecker-grpc.rule=Host(`woodpecker-grpc.yourdomain.com`) - - traefik.http.routers.woodpecker-grpc.entrypoints=web - - traefik.http.routers.woodpecker-grpc.service=woodpecker-grpc - - - traefik.http.middlewares.woodpecker-grpc-redirect.redirectscheme.scheme=https - - traefik.http.middlewares.woodpecker-grpc-redirect.redirectscheme.permanent=true - - traefik.http.routers.woodpecker-grpc.middlewares=woodpecker-grpc-redirect@docker - -volumes: - woodpecker-server-data: - driver: local - -networks: - dmz: - external: true -``` - -You should pass `WOODPECKER_GRPC_SECURE=true` and `WOODPECKER_GRPC_VERIFY=true` to your agent when using this configuration. diff --git a/docs/versioned_docs/version-2.2/30-administration/75-addons/00-overview.md b/docs/versioned_docs/version-2.2/30-administration/75-addons/00-overview.md deleted file mode 100644 index 485f9ce84e..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/75-addons/00-overview.md +++ /dev/null @@ -1,45 +0,0 @@ -# Addons - -:::warning -Addons are still experimental. Their implementation can change and break at any time. -::: - -:::danger -You need to trust the author of the addons you use. Depending on their type, addons can access forge authentication codes, your secrets or other sensitive information. -::: - -To adapt Woodpecker to your needs beyond the [configuration](../10-server-config.md), Woodpecker has its own **addon** system, built ontop of [Go's internal plugin system](https://go.dev/pkg/plugin). - -Addons can be used for: - -- Forges -- Agent backends -- Config services -- Secret services -- Environment services -- Registry services - -## Restrictions - -Addons are restricted by how Go plugins work. This includes the following restrictions: - -- only supported on Linux, FreeBSD, and macOS -- addons must have been built for the correct Woodpecker version. If an addon is not provided specifically for this version, you likely won't be able to use it. - -## Usage - -To use an addon, download the addon version built for your Woodpecker version. Then, you can add the following to your configuration: - -```ini -WOODPECKER_ADDONS=/path/to/your/addon/file.so -``` - -In case you run Woodpecker as container, you probably want to mount the addon binaries to `/opt/addons/`. - -You can list multiple addons, Woodpecker will automatically determine their type. If you specify multiple addons with the same type, only the first one will be used. - -Using an addon always overwrites Woodpecker's internal setup. This means, that a forge addon will be used if specified, no matter what's configured for the forges natively supported by Woodpecker. - -### Bug reports - -If you experience bugs, please check which component has the issue. If it's the addon, **do not raise an issue in the main repository**, but rather use the separate addon repositories. To check which component is responsible for the bug, look at the logs. Logs from addons are marked with a special field `addon` containing their addon file name. diff --git a/docs/versioned_docs/version-2.2/30-administration/75-addons/20-creating-addons.md b/docs/versioned_docs/version-2.2/30-administration/75-addons/20-creating-addons.md deleted file mode 100644 index 0fd6d2fe07..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/75-addons/20-creating-addons.md +++ /dev/null @@ -1,102 +0,0 @@ -# Creating addons - -Addons are written in Go. - -## Writing your code - -An addon consists of two variables/functions in Go. - -1. The `Type` variable. Specifies the type of the addon and must be directly accessed from `shared/addons/types/types.go`. -2. The `Addon` function which is the main point of your addon. - This function takes the `zerolog` logger you should use to log errors, warnings, etc. as argument. - - It returns two values: - - 1. The actual addon. For type reference see [table below](#return-types). - 2. An error. If this error is not `nil`, Woodpecker exits. - -Directly import Woodpecker's Go package (`go.woodpecker-ci.org/woodpecker/woodpecker/v2`) and use the interfaces and types defined there. - -### Return types - -| Addon type | Return type | -| -------------------- | -------------------------------------------------------------------------------- | -| `Forge` | `"go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/forge".Forge` | -| `Backend` | `"go.woodpecker-ci.org/woodpecker/woodpecker/v2/pipeline/backend/types".Backend` | -| `ConfigService` | `"go.woodpecker-ci.org/woodpecker/v2/server/plugins/config".Extension` | -| `SecretService` | `"go.woodpecker-ci.org/woodpecker/v2/server/model".SecretService` | -| `EnvironmentService` | `"go.woodpecker-ci.org/woodpecker/v2/server/model".EnvironmentService` | -| `RegistryService` | `"go.woodpecker-ci.org/woodpecker/v2/server/model".RegistryService` | - -### Using configurations - -If you write a plugin for the server (`Forge` and the services), you can access the server config. - -Therefore, use the `"go.woodpecker-ci.org/woodpecker/v2/server".Config` variable. - -:::warning -The config is not available when your addon is initialized, i.e., the `Addon` function is called. -Only use the config in the interface methods. -::: - -## Compiling - -After you write your addon code, compile your addon: - -```sh -go build -buildmode plugin -``` - -The output file is your addon that is now ready to be used. - -## Restrictions - -Addons must directly depend on Woodpecker's core (`go.woodpecker-ci.org/woodpecker/woodpecker/v2`). -The addon must have been built with **exactly the same code** as the Woodpecker instance you'd like to use it on. This means: If you build your addon with a specific commit from Woodpecker `next`, you can likely only use it with the Woodpecker version compiled from this commit. -Also, if you change something inside Woodpecker without committing, it might fail because you need to recompile your addon with this code first. - -In addition to this, addons are only supported on Linux, FreeBSD, and macOS. - -:::info -It is recommended to at least support the latest version of Woodpecker. -::: - -### Compile for different versions - -As long as there are no changes to Woodpecker's interfaces, -or they are backwards-compatible, you can compile the addon for multiple versions -by changing the version of `go.woodpecker-ci.org/woodpecker/woodpecker/v2` using `go get` before compiling. - -## Logging - -The entrypoint receives a `zerolog.Logger` as input. **Do not use any other logging solution.** This logger follows the configuration of the Woodpecker instance and adds a special field `addon` to the log entries which allows users to find out which component is writing the log messages. - -## Example structure - -```go -package main - -import ( - "context" - "net/http" - - "github.com/rs/zerolog" - "go.woodpecker-ci.org/woodpecker/v2/server/forge" - forge_types "go.woodpecker-ci.org/woodpecker/v2/server/forge/types" - "go.woodpecker-ci.org/woodpecker/v2/server/model" - addon_types "go.woodpecker-ci.org/woodpecker/v2/shared/addon/types" -) - -var Type = addon_types.TypeForge - -func Addon(logger zerolog.Logger) (forge.Forge, error) { - logger.Info().Msg("hello world from addon") - return &config{l: logger}, nil -} - -type config struct { - l zerolog.Logger -} - -// In this case, `config` must implement `forge.Forge`. You must directly use Woodpecker's packages - see imports above. -``` diff --git a/docs/versioned_docs/version-2.2/30-administration/75-addons/_category_.yaml b/docs/versioned_docs/version-2.2/30-administration/75-addons/_category_.yaml deleted file mode 100644 index 4cd7380c57..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/75-addons/_category_.yaml +++ /dev/null @@ -1,6 +0,0 @@ -label: 'Addons' -collapsible: true -collapsed: true -link: - type: 'doc' - id: 'overview' diff --git a/docs/versioned_docs/version-2.2/30-administration/80-autoscaler.md b/docs/versioned_docs/version-2.2/30-administration/80-autoscaler.md deleted file mode 100644 index 6ac581c2e7..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/80-autoscaler.md +++ /dev/null @@ -1,37 +0,0 @@ -# Autoscaler - -If your would like dynamically scale your agents with the load, you can use [our autoscaler](https://github.com/woodpecker-ci/autoscaler). - -Please note that the autoscaler is not feature-complete yet. You can follow the progress [here](https://github.com/woodpecker-ci/autoscaler#roadmap). - -## Setup - -### docker-compose - -If you are using docker-compose you can add the following to your `docker-compose.yaml` file: - -```yaml -version: '3' - -services: - woodpecker-server: - image: woodpeckerci/woodpecker-server:next - [...] - - woodpecker-autoscaler: - image: woodpeckerci/autoscaler:next - restart: always - depends_on: - - woodpecker-server - environment: - - WOODPECKER_SERVER=https://your-woodpecker-server.tld # the url of your woodpecker server / could also be a public url - - WOODPECKER_TOKEN=${WOODPECKER_TOKEN} # the api token you can get from the UI https://your-woodpecker-server.tld/user - - WOODPECKER_MIN_AGENTS=0 - - WOODPECKER_MAX_AGENTS=3 - - WOODPECKER_WORKFLOWS_PER_AGENT=2 # the number of workflows each agent can run at the same time - - WOODEPCKER_GRPC_ADDR=https://grpc.your-woodpecker-server.tld # the grpc address of your woodpecker server, publicly accessible from the agents - - WOODEPCKER_GRPC_SECURE=true - - WOODPECKER_AGENT_ENV= # optional environment variables to pass to the agents - - WOODPECKER_PROVIDER=hetznercloud # set the provider, you can find all the available ones down below - - WOODPECKER_HETZNERCLOUD_API_TOKEN=${WOODPECKER_HETZNERCLOUD_API_TOKEN} # your api token for the Hetzner cloud -``` diff --git a/docs/versioned_docs/version-2.2/30-administration/90-prometheus.md b/docs/versioned_docs/version-2.2/30-administration/90-prometheus.md deleted file mode 100644 index 2264f3b09c..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/90-prometheus.md +++ /dev/null @@ -1,81 +0,0 @@ -# Prometheus - -Woodpecker is compatible with Prometheus and exposes a `/metrics` endpoint if the environment variable `WOODPECKER_PROMETHEUS_AUTH_TOKEN` is set. Please note that access to the metrics endpoint is restricted and requires the authorization token from the environment variable mentioned above. - -```yaml -global: - scrape_interval: 60s - -scrape_configs: - - job_name: 'woodpecker' - bearer_token: dummyToken... - - static_configs: - - targets: ['woodpecker.domain.com'] -``` - -## Authorization - -An administrator will need to generate a user API token and configure in the Prometheus configuration file as a bearer token. Please see the following example: - -```diff - global: - scrape_interval: 60s - - scrape_configs: - - job_name: 'woodpecker' -+ bearer_token: dummyToken... - - static_configs: - - targets: ['woodpecker.domain.com'] -``` - -As an alternative, the token can also be read from a file: - -```diff - global: - scrape_interval: 60s - - scrape_configs: - - job_name: 'woodpecker' -+ bearer_token_file: /etc/secrets/woodpecker-monitoring-token - - static_configs: - - targets: ['woodpecker.domain.com'] -``` - -## Metric Reference - -List of Prometheus metrics specific to Woodpecker: - -```yaml -# HELP woodpecker_pipeline_count Pipeline count. -# TYPE woodpecker_pipeline_count counter -woodpecker_pipeline_count{branch="main",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3 -woodpecker_pipeline_count{branch="mkdocs",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3 -# HELP woodpecker_pipeline_time Build time. -# TYPE woodpecker_pipeline_time gauge -woodpecker_pipeline_time{branch="main",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 116 -woodpecker_pipeline_time{branch="mkdocs",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 155 -# HELP woodpecker_pipeline_total_count Total number of builds. -# TYPE woodpecker_pipeline_total_count gauge -woodpecker_pipeline_total_count 1025 -# HELP woodpecker_pending_steps Total number of pending pipeline steps. -# TYPE woodpecker_pending_steps gauge -woodpecker_pending_steps 0 -# HELP woodpecker_repo_count Total number of repos. -# TYPE woodpecker_repo_count gauge -woodpecker_repo_count 9 -# HELP woodpecker_running_steps Total number of running pipeline steps. -# TYPE woodpecker_running_steps gauge -woodpecker_running_steps 0 -# HELP woodpecker_user_count Total number of users. -# TYPE woodpecker_user_count gauge -woodpecker_user_count 1 -# HELP woodpecker_waiting_steps Total number of pipeline waiting on deps. -# TYPE woodpecker_waiting_steps gauge -woodpecker_waiting_steps 0 -# HELP woodpecker_worker_count Total number of workers. -# TYPE woodpecker_worker_count gauge -woodpecker_worker_count 4 -``` diff --git a/docs/versioned_docs/version-2.2/30-administration/_category_.yaml b/docs/versioned_docs/version-2.2/30-administration/_category_.yaml deleted file mode 100644 index 4f31383598..0000000000 --- a/docs/versioned_docs/version-2.2/30-administration/_category_.yaml +++ /dev/null @@ -1,4 +0,0 @@ -label: 'Administration' -# position: 3 -collapsible: true -collapsed: true diff --git a/docs/versioned_docs/version-2.2/30-administration/new-agent-connected.png b/docs/versioned_docs/version-2.2/30-administration/new-agent-connected.png deleted file mode 100644 index 9d19153d9d..0000000000 Binary files a/docs/versioned_docs/version-2.2/30-administration/new-agent-connected.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/30-administration/new-agent-created.png b/docs/versioned_docs/version-2.2/30-administration/new-agent-created.png deleted file mode 100644 index dc561d8873..0000000000 Binary files a/docs/versioned_docs/version-2.2/30-administration/new-agent-created.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/30-administration/new-agent-registration.png b/docs/versioned_docs/version-2.2/30-administration/new-agent-registration.png deleted file mode 100644 index 71117771d6..0000000000 Binary files a/docs/versioned_docs/version-2.2/30-administration/new-agent-registration.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/40-cli.md b/docs/versioned_docs/version-2.2/40-cli.md deleted file mode 100644 index 0cfb425eef..0000000000 --- a/docs/versioned_docs/version-2.2/40-cli.md +++ /dev/null @@ -1,573 +0,0 @@ -# CLI - -# NAME - -woodpecker-cli - command line utility - -# SYNOPSIS - -woodpecker-cli - -``` -[--log-file]=[value] -[--log-level]=[value] -[--nocolor] -[--pretty] -[--server|-s]=[value] -[--token|-t]=[value] -``` - -**Usage**: - -``` -woodpecker-cli [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] -``` - -# GLOBAL OPTIONS - -**--log-file**="": Output destination for logs. 'stdout' and 'stderr' can be used as special keywords. (default: "stderr") - -**--log-level**="": set logging level (default: "info") - -**--nocolor**: disable colored debug output, only has effect if pretty output is set too - -**--pretty**: enable pretty-printed debug output - -**--server, -s**="": server address - -**--token, -t**="": server auth token - - -# COMMANDS - -## pipeline - -manage pipelines - -### ls - -show pipeline history - -**--branch**="": branch filter - -**--event**="": event filter - -**--format**="": format output (default: "\x1b[33mPipeline #{{ .Number }} \x1b[0m\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nAuthor: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}\nMessage: {{ .Message }}\n") - -**--limit**="": limit the list size (default: 25) - -**--status**="": status filter - -### last - -show latest pipeline details - -**--branch**="": branch name (default: "main") - -**--format**="": format output (default: "Number: {{ .Number }}\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\n") - -### logs - -show pipeline logs - -### info - -show pipeline details - -**--format**="": format output (default: "Number: {{ .Number }}\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\n") - -### stop - -stop a pipeline - -### start - -start a pipeline - -**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value - -### approve - -approve a pipeline - -### decline - -decline a pipeline - -### queue - -show pipeline queue - -**--format**="": format output (default: "\x1b[33m{{ .FullName }} #{{ .Number }} \x1b[0m\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nAuthor: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}\nMessage: {{ .Message }}\n") - -### ps - -show pipeline steps - -**--format**="": format output (default: "\x1b[33mStep #{{ .PID }} \x1b[0m\nStep: {{ .Name }}\nState: {{ .State }}\n") - -### create - -create new pipeline - -**--branch**="": branch to create pipeline from - -**--format**="": format output (default: "\x1b[33mPipeline #{{ .Number }} \x1b[0m\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nAuthor: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}\nMessage: {{ .Message }}\n") - -**--var**="": key=value - -## log - -manage logs - -### purge - -purge a log - -## deploy - -deploy code - -**--branch**="": branch filter (default: "main") - -**--event**="": event filter (default: "push") - -**--format**="": format output (default: "Number: {{ .Number }}\nStatus: {{ .Status }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\nTarget: {{ .Deploy }}\n") - -**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value - -**--status**="": status filter (default: "success") - -## exec - -execute a local pipeline - -**--backend-docker-api-version**="": the version of the API to reach, leave empty for latest. - -**--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 - -**--backend-docker-ipv6**: backend docker enable IPV6 - -**--backend-docker-network**="": backend docker network - -**--backend-docker-tls-verify**: enable or disable TLS verification for connecting to docker server - -**--backend-docker-volumes**="": backend docker volumes (comma separated) - -**--backend-engine**="": backend engine to run pipelines on (default: "auto-detect") - -**--backend-http-proxy**="": if set, pass the environment variable down as "HTTP_PROXY" to steps - -**--backend-https-proxy**="": if set, pass the environment variable down as "HTTPS_PROXY" to steps - -**--backend-k8s-namespace**="": backend k8s namespace (default: "woodpecker") - -**--backend-k8s-pod-annotations**="": backend k8s additional worker pod annotations - -**--backend-k8s-pod-image-pull-secret-names**="": backend k8s pull secret names for private registries (default: "regcred") - -**--backend-k8s-pod-labels**="": backend k8s additional worker pod labels - -**--backend-k8s-secctx-nonroot**: `run as non root` Kubernetes security context option - -**--backend-k8s-storage-class**="": backend k8s storage class - -**--backend-k8s-storage-rwx**: backend k8s storage access mode, should ReadWriteMany (RWX) instead of ReadWriteOnce (RWO) be used? (default: true) - -**--backend-k8s-volume-size**="": backend k8s volume size (default 10G) (default: "10G") - -**--backend-local-temp-dir**="": set a different temp dir to clone workflows into (default: "/tmp") - -**--backend-no-proxy**="": if set, pass the environment variable down as "NO_PROXY" to steps - -**--commit-author-avatar**="": - -**--commit-author-email**="": - -**--commit-author-name**="": - -**--commit-branch**="": - -**--commit-message**="": - -**--commit-ref**="": - -**--commit-refspec**="": - -**--commit-sha**="": - -**--connect-retry-count**="": number of times to retry connecting to the server (default: 5) - -**--connect-retry-delay**="": duration to wait before retrying to connect to the server (default: 2s) - -**--env**="": - -**--forge-type**="": - -**--forge-url**="": - -**--local**: run from local directory - -**--netrc-machine**="": - -**--netrc-password**="": - -**--netrc-username**="": - -**--network**="": external networks - -**--pipeline-created**="": (default: 0) - -**--pipeline-event**="": (default: "manual") - -**--pipeline-finished**="": (default: 0) - -**--pipeline-number**="": (default: 0) - -**--pipeline-parent**="": (default: 0) - -**--pipeline-started**="": (default: 0) - -**--pipeline-status**="": - -**--pipeline-target**="": - -**--pipeline-url**="": - -**--prev-commit-author-avatar**="": - -**--prev-commit-author-email**="": - -**--prev-commit-author-name**="": - -**--prev-commit-branch**="": - -**--prev-commit-message**="": - -**--prev-commit-ref**="": - -**--prev-commit-refspec**="": - -**--prev-commit-sha**="": - -**--prev-pipeline-created**="": (default: 0) - -**--prev-pipeline-event**="": - -**--prev-pipeline-finished**="": (default: 0) - -**--prev-pipeline-number**="": (default: 0) - -**--prev-pipeline-started**="": (default: 0) - -**--prev-pipeline-status**="": - -**--prev-pipeline-url**="": - -**--privileged**="": privileged plugins (default: "plugins/docker", "plugins/gcr", "plugins/ecr", "woodpeckerci/plugin-docker-buildx", "codeberg.org/woodpecker-plugins/docker-buildx") - -**--repo**="": full repo name - -**--repo-clone-ssh-url**="": - -**--repo-clone-url**="": - -**--repo-private**="": - -**--repo-remote-id**="": - -**--repo-trusted**: - -**--repo-url**="": - -**--step-name**="": (default: 0) - -**--system-name**="": (default: "woodpecker") - -**--system-platform**="": - -**--system-url**="": (default: "https://github.com/woodpecker-ci/woodpecker") - -**--timeout**="": pipeline timeout (default: 1h0m0s) - -**--volumes**="": pipeline volumes - -**--workflow-name**="": (default: 0) - -**--workflow-number**="": (default: 0) - -**--workspace-base**="": (default: "/woodpecker") - -**--workspace-path**="": (default: "src") - -## info - -show information about the current user - -## registry - -manage registries - -### add - -adds a registry - -**--hostname**="": registry hostname (default: "docker.io") - -**--password**="": registry password - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--username**="": registry username - -### rm - -remove a registry - -**--hostname**="": registry hostname (default: "docker.io") - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -### update - -update a registry - -**--hostname**="": registry hostname (default: "docker.io") - -**--password**="": registry password - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--username**="": registry username - -### info - -display registry info - -**--hostname**="": registry hostname (default: "docker.io") - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -### ls - -list registries - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -## secret - -manage secrets - -### add - -adds a secret - -**--event**="": secret limited to these events - -**--global**: global secret - -**--image**="": secret limited to these images - -**--name**="": secret name - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--value**="": secret value - -### rm - -remove a secret - -**--global**: global secret - -**--name**="": secret name - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -### update - -update a secret - -**--event**="": secret limited to these events - -**--global**: global secret - -**--image**="": secret limited to these images - -**--name**="": secret name - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--value**="": secret value - -### info - -display secret info - -**--global**: global secret - -**--name**="": secret name - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -### ls - -list secrets - -**--global**: global secret - -**--organization, --org**="": organization id or full-name (e.g. 123 or octocat) - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -## repo - -manage repositories - -### ls - -list all repos - -**--format**="": format output (default: "\x1b[33m{{ .FullName }}\x1b[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }})") - -**--org**="": filter by organization - -### info - -show repository details - -**--format**="": format output (default: "Owner: {{ .Owner }}\nRepo: {{ .Name }}\nURL: {{ .ForgeURL }}\nConfig path: {{ .Config }}\nVisibility: {{ .Visibility }}\nPrivate: {{ .IsSCMPrivate }}\nTrusted: {{ .IsTrusted }}\nGated: {{ .IsGated }}\nClone url: {{ .Clone }}\nAllow pull-requests: {{ .AllowPullRequests }}\n") - -### add - -add a repository - -### update - -update a repository - -**--config**="": repository configuration path (e.g. .woodpecker.yml) - -**--gated**: repository is gated - -**--pipeline-counter**="": repository starting pipeline number (default: 0) - -**--timeout**="": repository timeout (default: 0s) - -**--trusted**: repository is trusted - -**--unsafe**: validate updating the pipeline-counter is unsafe - -**--visibility**="": repository visibility - -### rm - -remove a repository - -### repair - -repair repository webhooks - -### chown - -assume ownership of a repository - -### sync - -synchronize the repository list - -**--format**="": format output (default: "\x1b[33m{{ .FullName }}\x1b[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }})") - -## user - -manage users - -### ls - -list all users - -**--format**="": format output (default: "{{ .Login }}") - -### info - -show user details - -**--format**="": format output (default: "User: {{ .Login }}\nEmail: {{ .Email }}") - -### add - -adds a user - -### rm - -remove a user - -## lint - -lint a pipeline configuration file - -## log-level - -get the logging level of the server, or set it with [level] - -## cron - -manage cron jobs - -### add - -add a cron job - -**--branch**="": cron branch - -**--name**="": cron name - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--schedule**="": cron schedule - -### rm - -remove a cron job - -**--id**="": cron id - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -### update - -update a cron job - -**--branch**="": cron branch - -**--id**="": cron id - -**--name**="": cron name - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -**--schedule**="": cron schedule - -### info - -display info about a cron job - -**--id**="": cron id - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) - -### ls - -list cron jobs - -**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world) diff --git a/docs/versioned_docs/version-2.2/91-migrations.md b/docs/versioned_docs/version-2.2/91-migrations.md deleted file mode 100644 index 328d87a625..0000000000 --- a/docs/versioned_docs/version-2.2/91-migrations.md +++ /dev/null @@ -1,146 +0,0 @@ -# Migrations - -Some versions need some changes to the server configuration or the pipeline configuration files. - -## `next` - -- Deprecated `steps.[name].group` in favor of `steps.[name].depends_on` (see [workflow syntax](./20-usage/20-workflow-syntax.md#depends_on) to learn how to set dependencies) -- Removed `WOODPECKER_ROOT_PATH` and `WOODPECKER_ROOT_URL` config variables. Use `WOODPECKER_HOST` with a path instead -- Pipelines without a config file will now be skipped instead of failing - -## 2.0.0 - -- Dropped deprecated `CI_BUILD_*`, `CI_PREV_BUILD_*`, `CI_JOB_*`, `*_LINK`, `CI_SYSTEM_ARCH`, `CI_REPO_REMOTE` built-in environment variables -- Deprecated `platform:` filter in favor of `labels:`, [read more](./20-usage/20-workflow-syntax.md#filter-by-platform) -- Secrets `event` property was renamed to `events` and `image` to `images` as both are lists. The new property `events` / `images` has to be used in the api. The old properties `event` and `image` were removed. -- The secrets `plugin_only` option was removed. Secrets with images are now always only available for plugins using listed by the `images` property. Existing secrets with a list of `images` will now only be available to the listed images if they are used as a plugin. -- Removed `build` alias for `pipeline` command in CLI -- Removed `ssh` backend. Use an agent directly on the SSH machine using the `local` backend. -- Removed `/hook` and `/stream` API paths in favor of `/api/(hook|stream)`. You may need to use the "Repair repository" button in the repo settings or "Repair all" in the admin settings to recreate the forge hook. -- Removed `WOODPECKER_DOCS` config variable -- Renamed `link` to `url` (including all API fields) -- Deprecated `CI_COMMIT_URL` env var, use `CI_PIPELINE_FORGE_URL` - -## 1.0.0 - -- The signature used to verify extension calls (like those used for the [config-extension](./30-administration/100-external-configuration-api.md)) done by the Woodpecker server switched from using a shared-secret HMac to an ed25519 key-pair. Read more about it at the [config-extensions](./30-administration/100-external-configuration-api.md) documentation. -- Refactored support for old agent filter labels and expressions. Learn how to use the new [filter](./20-usage/20-workflow-syntax.md#labels) -- Renamed step environment variable `CI_SYSTEM_ARCH` to `CI_SYSTEM_PLATFORM`. Same applies for the cli exec variable. -- Renamed environment variables `CI_BUILD_*` and `CI_PREV_BUILD_*` to `CI_PIPELINE_*` and `CI_PREV_PIPELINE_*`, old ones are still available but deprecated -- Renamed environment variables `CI_JOB_*` to `CI_STEP_*`, old ones are still available but deprecated -- Renamed environment variable `CI_REPO_REMOTE` to `CI_REPO_CLONE_URL`, old is still available but deprecated -- Renamed environment variable `*_LINK` to `*_URL`, old ones are still available but deprecated -- Renamed API endpoints for pipelines (`//builds/` -> `//pipelines/`), old ones are still available but deprecated -- Updated Prometheus gauge `build_*` to `pipeline_*` -- Updated Prometheus gauge `*_job_*` to `*_step_*` -- Renamed config env `WOODPECKER_MAX_PROCS` to `WOODPECKER_MAX_WORKFLOWS` (still available as fallback) -- The pipelines are now also read from `.yaml` files, the new default order is `.woodpecker/*.yml` and `.woodpecker/*.yaml` (without any prioritization) -> `.woodpecker.yml` -> `.woodpecker.yaml` -- Dropped support for [Coding](https://coding.net/), [Gogs](https://gogs.io) and Bitbucket Server (Stash). -- `/api/queue/resume` & `/api/queue/pause` endpoint methods were changed from `GET` to `POST` -- rename `pipeline:` key in your workflow config to `steps:` -- If you want to migrate old logs to the new format, watch the error messages on start. If there are none we are good to go, else you have to plan a migration that can take hours. Set `WOODPECKER_MIGRATIONS_ALLOW_LONG` to true and let it run. -- Using `repo-id` in favor of `owner/repo` combination - - :warning: The api endpoints `/api/repos/{owner}/{repo}/...` were replaced by new endpoints using the repos id `/api/repos/{repo-id}` - - To find the id of a repo use the `/api/repos/lookup/{repo-full-name-with-slashes}` endpoint. - - The existing badge endpoint `/api/badges/{owner}/{repo}` will still work, but whenever possible try to use the new endpoint using the `repo-id`: `/api/badges/{repo-id}`. - - The UI urls for a repository changed from `/repos/{owner}/{repo}/...` to `/repos/{repo-id}/...`. You will be redirected automatically when using the old url. - - The woodpecker-go api-client is now using the `repo-id` instead of `owner/repo` for all functions -- Using `org-id` in favour of `owner` name - - :warning: The api endpoints `/api/orgs/{owner}/...` were replaced by new endpoints using the orgs id `/api/repos/{org-id}` - - To find the id of orgs use the `/api/orgs/lookup/{org_full_name}` endpoint. - - The UI urls for a organization changed from `/org/{owner}/...` to `/orgs/{org-id}/...`. You will be redirected automatically when using the old url. - - The woodpecker-go api-client is now using the `org-id` instead of `org name` for all functions -- The `command:` field has been removed from steps. If you were using it, please check if the entrypoint of the image you used is a shell. - - If it is a shell, simply rename `command:` to `commands:`. - - If it's not, you need to prepend the entrypoint before and also rename it (e.g., `commands: `). - -## 0.15.0 - -- Default value for custom pipeline path is now empty / un-set which results in following resolution: - - `.woodpecker/*.yml` -> `.woodpecker.yml` -> `.drone.yml` - - Only projects created after updating will have an empty value by default. Existing projects will stick to the current pipeline path which is `.drone.yml` in most cases. - - Read more about it at the [Project Settings](./20-usage/71-project-settings.md#pipeline-path) - -- From version `0.15.0` ongoing there will be three types of docker images: `latest`, `next` and `x.x.x` with an alpine variant for each type like `latest-alpine`. - If you used `latest` before to try pre-release features you should switch to `next` after this release. - -- Dropped support for `DRONE_*` environment variables. The according `WOODPECKER_*` variables must be used instead. - Additionally some alternative namings have been removed to simplify maintenance: - - - `WOODPECKER_AGENT_SECRET` replaces `WOODPECKER_SECRET`, `DRONE_SECRET`, `WOODPECKER_PASSWORD`, `DRONE_PASSWORD` and `DRONE_AGENT_SECRET`. - - `WOODPECKER_HOST` replaces `DRONE_HOST` and `DRONE_SERVER_HOST`. - - `WOODPECKER_DATABASE_DRIVER` replaces `DRONE_DATABASE_DRIVER` and `DATABASE_DRIVER`. - - `WOODPECKER_DATABASE_DATASOURCE` replaces `DRONE_DATABASE_DATASOURCE` and `DATABASE_CONFIG`. - -- Dropped support for `DRONE_*` environment variables in pipeline steps. Pipeline meta-data can be accessed with `CI_*` variables. - - - `CI_*` prefix replaces `DRONE_*` - - `CI` value is now `woodpecker` - - `DRONE=true` has been removed - - Some variables got deprecated and will be removed in future versions. Please migrate to the new names. Same applies for `DRONE_` of them. - - CI_ARCH => use CI_SYSTEM_ARCH - - CI_COMMIT => CI_COMMIT_SHA - - CI_TAG => CI_COMMIT_TAG - - CI_PULL_REQUEST => CI_COMMIT_PULL_REQUEST - - CI_REMOTE_URL => use CI_REPO_REMOTE - - CI_REPO_BRANCH => use CI_REPO_DEFAULT_BRANCH - - CI_PARENT_BUILD_NUMBER => use CI_BUILD_PARENT - - CI_BUILD_TARGET => use CI_BUILD_DEPLOY_TARGET - - CI_DEPLOY_TO => use CI_BUILD_DEPLOY_TARGET - - CI_COMMIT_AUTHOR_NAME => use CI_COMMIT_AUTHOR - - CI_PREV_COMMIT_AUTHOR_NAME => use CI_PREV_COMMIT_AUTHOR - - CI_SYSTEM => use CI_SYSTEM_NAME - - CI_BRANCH => use CI_COMMIT_BRANCH - - CI_SOURCE_BRANCH => use CI_COMMIT_SOURCE_BRANCH - - CI_TARGET_BRANCH => use CI_COMMIT_TARGET_BRANCH - - For all available variables and their descriptions have a look at [built-in-environment-variables](./20-usage/50-environment.md#built-in-environment-variables). - -- Prometheus metrics have been changed from `drone_*` to `woodpecker_*` - -- Base path has moved from `/var/lib/drone` to `/var/lib/woodpecker` - -- Default workspace base path has moved from `/drone` to `/woodpecker` - -- Default SQLite database location has changed: - - - `/var/lib/drone/drone.sqlite` -> `/var/lib/woodpecker/woodpecker.sqlite` - - `drone.sqlite` -> `woodpecker.sqlite` - -- Plugin Settings moved into `settings` section: - - ```diff - steps: - something: - image: my/plugin - - setting1: foo - - setting2: bar - + settings: - + setting1: foo - + setting2: bar - ``` - -- `WOODPECKER_DEBUG` option for server and agent got removed in favor of `WOODPECKER_LOG_LEVEL=debug` - -- Remove unused server flags which can safely be removed from your server config: `WOODPECKER_QUIC`, `WOODPECKER_GITHUB_SCOPE`, `WOODPECKER_GITHUB_GIT_USERNAME`, `WOODPECKER_GITHUB_GIT_PASSWORD`, `WOODPECKER_GITHUB_PRIVATE_MODE`, `WOODPECKER_GITEA_GIT_USERNAME`, `WOODPECKER_GITEA_GIT_PASSWORD`, `WOODPECKER_GITEA_PRIVATE_MODE`, `WOODPECKER_GITLAB_GIT_USERNAME`, `WOODPECKER_GITLAB_GIT_PASSWORD`, `WOODPECKER_GITLAB_PRIVATE_MODE` - -- Dropped support for manually setting the agents platform with `WOODPECKER_PLATFORM`. The platform is now automatically detected. - -- Use `WOODPECKER_STATUS_CONTEXT` instead of the deprecated options `WOODPECKER_GITHUB_CONTEXT` and `WOODPECKER_GITEA_CONTEXT`. - -## 0.14.0 - -No breaking changes - -## From Drone - -:::warning -Migration from Drone is only possible if you were running Drone <= v0.8. -::: - -1. Make sure you are already running Drone v0.8 -2. Upgrade to Woodpecker v0.14.4, migration will be done during startup -3. Upgrade to the latest Woodpecker version. Pay attention to the breaking changes listed above. diff --git a/docs/versioned_docs/version-2.2/92-awesome.md b/docs/versioned_docs/version-2.2/92-awesome.md deleted file mode 100644 index 18f36ce711..0000000000 --- a/docs/versioned_docs/version-2.2/92-awesome.md +++ /dev/null @@ -1,62 +0,0 @@ -# Awesome Woodpecker - -A curated list of awesome things related to Woodpecker-CI. - -If you have some missing resources, please feel free to [open a pull-request](https://github.com/woodpecker-ci/woodpecker/edit/main/docs/docs/92-awesome.md) and add them. - -## Official Resources - -- [Woodpecker CI pipeline configs](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) - Complex setup containing different kind of pipelines - - [Golang tests](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/test.yaml) - - [Typescript, eslint & Vue](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/web.yaml) - - [Docusaurus & publishing to GitHub Pages](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docs.yaml) - - [Docker container building](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docker.yaml) - -## Projects using Woodpecker - -- [Woodpecker-CI](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) itself -- [All official plugins](https://github.com/woodpecker-ci?q=plugin&type=all) -- [dessalines/thumb-key](https://github.com/dessalines/thumb-key/blob/main/.woodpecker.yml) - Android Jetpack compose linting and building -- [Vieter](https://git.rustybever.be/vieter-v/vieter) - Archlinux/Pacman repository server & automated package build system - - [Rieter](https://git.rustybever.be/Chewing_Bever/rieter) - Rewrite of the Vieter project in Rust -- [Alex](https://git.rustybever.be/Chewing_Bever/alex) - Minecraft server wrapper designed to automate backups & complement Docker installations - -## Tools - -- [Convert Drone CI pipelines to Woodpecker CI](https://codeberg.org/lafriks/woodpecker-pipeline-transform) -- [Ansible NAS](https://github.com/davestephens/ansible-nas/) - a homelab Ansible playbook that can set up Woodpecker-CI and Gitea -- [picus](https://github.com/windsource/picus) - Picus connects to a Woodpecker CI server and creates an agent in the cloud when there are pending workflows. -- [Hetzner cloud](https://www.hetzner.com/cloud) based [Woodpecker compatible autoscaler](https://git.ljoonal.xyz/ljoonal/hetzner-ci-autoscaler) - Creates and destroys VPS instances based on the count of pending & running jobs. -- [woodpecker-lint](https://git.schmidl.dev/schtobia/woodpecker-lint) - A repository for linting a woodpecker config file via pre-commit hook -- [Grafana Dashboard](https://github.com/Janik-Haag/woodpecker-grafana-dashboard) - A dashboard visualizing information exposed by the woodpecker prometheus endpoint. -- [woodpecker-autoscaler](https://github.com/Lerentis/woodpecker-autoscaler) - Yet another woodpecker autoscaler currently targeting [Hetzner cloud](https://www.hetzner.com/cloud) that works in parallel to other autoscaler implementations. - -## Configuration Services - -- [Dynamic Pipelines for Nix Flakes](https://github.com/pinpox/woodpecker-flake-pipeliner) - Define pipelines as Nix Flake outputs - -## Pipelines - -- [Collection of pipeline examples](https://codeberg.org/Codeberg-CI/examples) - -## Posts & tutorials - -- [Setup Gitea with Woodpecker CI](https://containers.fan/posts/setup-gitea-with-woodpecker-ci/) -- [Step-by-step guide to modern, secure and Open-source CI setup](https://devforth.io/blog/step-by-step-guide-to-modern-secure-ci-setup/) -- [Using Woodpecker CI for my static sites](https://jan.wildeboer.net/2022/07/Woodpecker-CI-Jekyll/) -- [Woodpecker CI @ Codeberg](https://www.sarkasti.eu/articles/post/woodpecker/) -- [Deploy Docker/Compose using Woodpecker CI](https://hinty.io/vverenko/deploy-docker-compose-using-woodpecker-ci/) -- [Installing Woodpecker CI in your personal homelab](https://pwa.io/articles/installing-woodpecker-in-your-homelab/) -- [Locally Cached Nix CI with Woodpecker](https://blog.kotatsu.dev/posts/2023-04-21-woodpecker-nix-caching/) -- [How to run Cypress auto-tests on Woodpecker CI and report results to Slack](https://devforth.io/blog/how-to-run-cypress-auto-tests-on-woodpecker-ci-and-report-results-to-slack/) -- [Quest For CICD - WoodpeckerCI](https://omaramin.me/posts/woodpecker/) - -## Videos - -- [Replace Ansible Semaphore with Woodpecker CI](https://www.youtube.com/watch?v=d610YPvCB0E) -- ["unexpected EOF" error when trying to pair Woodpecker CI served through the Caddy with Gitea](https://www.youtube.com/watch?v=n7Hyvt71Np0) -- [CICD Environment in Docker Swarm behind Caddy Server - Part 2 Woodpeckerci](https://www.youtube.com/watch?v=rkbw_k7JvS0) - -## Plugins - -We have a separate [index](/plugins) for plugins. diff --git a/docs/versioned_docs/version-2.2/92-development/01-getting-started.md b/docs/versioned_docs/version-2.2/92-development/01-getting-started.md deleted file mode 100644 index 367e582842..0000000000 --- a/docs/versioned_docs/version-2.2/92-development/01-getting-started.md +++ /dev/null @@ -1,160 +0,0 @@ -# Getting started - -## Core ideas - -- A (e.g. pipeline) configuration should never be [turing complete](https://en.wikipedia.org/wiki/Turing_completeness) (We have agents to exec things 🙂). -- If possible follow the [KISS principle](https://en.wikipedia.org/wiki/KISS_principle). -- What is used most should be default. -- Keep different topics separated, so you can write plugins, port new ideas ... more easily, see [Architecture](./05-architecture.md). - -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 preconfigured 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 preconfigured [Gitea](https://github.com/go-gitea/gitea) instance as forge -- A preconfigured Woodpecker server -- A single preconfigured 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 Golang (>=1.20) as described by [this guide](https://go.dev/doc/install). - -### 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 (). - -Install make on: - -- Ubuntu: `apt install make` - [Docs](https://wiki.ubuntuusers.de/Makefile/) -- [Windows](https://stackoverflow.com/a/32127632/8461267) -- Mac OS: `brew install make` - -### Install Node.js & `pnpm` - -Install [Node.js (>=14)](https://nodejs.org/en/download/) 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) - -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 - -Similar to the environment variables you can set for your production setup of Woodpecker, you can create a `.env` in the root of the Woodpecker project and add any need config to it. - -A common config for debugging would look like this: - -```ini -WOODPECKER_OPEN=true -WOODPECKER_ADMIN=your-username - -# if you want to test webhooks with an online forge like GitHub this address needs to be accessible from public server -WOODPECKER_HOST=http://your-dev-address.com - -# github (sample for a forge config - see /docs/administration/forge/overview for other forges) -WOODPECKER_GITHUB=true -WOODPECKER_GITHUB_CLIENT= -WOODPECKER_GITHUB_SECRET= - -# agent -WOODPECKER_SERVER=localhost:9000 -WOODPECKER_AGENT_SECRET=a-long-and-secure-password-used-for-the-local-development-system -WOODPECKER_MAX_WORKFLOWS=1 - -# enable if you want to develop the UI -# WOODPECKER_DEV_WWW_PROXY=http://localhost:8010 - -# used so you can login without using a public address -WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000 - -# disable health-checks while debugging (normally not needed while developing) -WOODPECKER_HEALTHCHECK=false - -# WOODPECKER_LOG_LEVEL=debug -# WOODPECKER_LOG_LEVEL=trace -``` - -### Setup OAuth - -Create an OAuth app for your forge as described in the [forges documentation](../30-administration/11-forges/10-overview.md). If you set `WOODPECKER_DEV_OAUTH_HOST=http://localhost:8000` you can use that address with the path as explained for the specific forge to login without the need for a public address. For example for GitHub you would use `http://localhost:8000/authorize` as authorization callback URL. - -## Developing with VS Code - -You can use different methods for debugging the Woodpecker applications. One of the currently recommended ways to debug and test the Woodpecker application is using [VS-Code](https://code.visualstudio.com/) or [VS-Codium](https://vscodium.com/) (Open-Source binaries of VS-Code) as most maintainers are using it and Woodpecker already includes the needed debug configurations for it. - -To launch all needed services for local development, you can use "Woodpecker CI" debugging configuration that will launch UI, server and agent in debugging mode. Then open `http://localhost:8000` to access it. - -As a starting guide for programming Go with VS Code, you can use this video guide: -[![Getting started with Go in VS Code](https://img.youtube.com/vi/1MXIGYrMk80/0.jpg)](https://www.youtube.com/watch?v=1MXIGYrMk80) - -### Debugging Woodpecker - -The Woodpecker source code already includes launch configurations for the Woodpecker server and agent. To start debugging you can click on the debug icon in the navigation bar of VS-Code (ctrl-shift-d). On that page you will see the existing launch jobs at the top. Simply select the agent or server and click on the play button. You can set breakpoints in the source files to stop at specific points. - -![Woodpecker debugging with VS Code](./vscode-debug.png) - -## Testing & linting code - -To test or lint parts of Woodpecker, you can run one of the following commands: - -```bash -# test server code -make test-server - -# test agent code -make test-agent - -# test cli code -make test-cli - -# test datastore / database related code like migrations of the server -make test-server-datastore - -# lint go code -make lint - -# lint UI code -make lint-frontend - -# test UI code -make test-frontend -``` - -If you want to test a specific Go file, you can also use: - -```bash -go test -race -timeout 30s go.woodpecker-ci.org/woodpecker/v2/ -``` - -Or you can open the test-file inside [VS-Code](#developing-with-vs-code) and run or debug the test by clicking on the inline commands: - -![Run test via VS-Code](./vscode-run-test.png) - -## Run applications from terminal - -If you want to run a Woodpecker applications from your terminal, you can use one of the following commands from the base of the Woodpecker project. They will execute Woodpecker in a similar way as described in [debugging Woodpecker](#debugging-woodpecker) without the ability to really debug it in your editor. - -```bash title="start server" -go run ./cmd/server -``` - -```bash title="start agent" -go run ./cmd/agent -``` - -```bash title="execute cli command" -go run ./cmd/cli [command] -``` diff --git a/docs/versioned_docs/version-2.2/92-development/03-ui.md b/docs/versioned_docs/version-2.2/92-development/03-ui.md deleted file mode 100644 index e8999b0be8..0000000000 --- a/docs/versioned_docs/version-2.2/92-development/03-ui.md +++ /dev/null @@ -1,39 +0,0 @@ -# UI Development - -To develop the UI you need to install [Node.js and pnpm](./01-getting-started.md#install-nodejs--pnpm). In addition it is recommended to use VS-Code with the recommended plugin selection to get features like auto-formatting, linting and typechecking. The UI is written with [Vue 3](https://v3.vuejs.org/) as Single-Page-Application accessing the Woodpecker REST api. - -## Setup - -The UI code is placed in `web/`. Change to that folder in your terminal with `cd web/` and install all dependencies by running `pnpm install`. For production builds the generated UI code is integrated into the Woodpecker server by using [go-embed](https://pkg.go.dev/embed). - -Testing UI changes would require us to rebuild the UI after each adjustment to the code by running `pnpm build` and restarting the Woodpecker server. To avoid this you can make use of the dev-proxy integrated into the Woodpecker server. This integrated dev-proxy will forward all none api request to a separate http-server which will only serve the UI files. - -![UI Proxy architecture](./ui-proxy.svg) - -Start the UI server locally with [hot-reloading](https://stackoverflow.com/a/41429055/8461267) by running: `pnpm start`. To enable the forwarding of requests to the UI server you have to enable the dev-proxy inside the Woodpecker server by adding `WOODPECKER_DEV_WWW_PROXY=http://localhost:8010` to your `.env` file. -After starting the Woodpecker server as explained in the [debugging](./01-getting-started.md#debugging-woodpecker) section, you should now be able to access the UI under [http://localhost:8000](http://localhost:8000). - -## Tools and frameworks - -The following list contains some tools and frameworks used by the Woodpecker UI. For some points we added some guidelines / hints to help you developing. - -- [Vue 3](https://v3.vuejs.org/) - - use `setup` and composition api - - place (re-usable) components in `web/src/components/` - - views should have a route in `web/src/router.ts` and are located in `web/src/views/` -- [Windicss](https://windicss.org/) (similar to Tailwind) - - use Windicss classes where possible - - if needed extend the Windicss config to use new classes -- [Vite](https://vitejs.dev/) (similar to Webpack) -- [Typescript](https://www.typescriptlang.org/) - - avoid using `any` and `unknown` (the linter will prevent you from doing so anyways :wink:) -- [eslint](https://eslint.org/) -- [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) - -## 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. -You must not provide translations except English in PRs, otherwise weblate could put git into conflicts (when someone has translated in that language file and changes are not into main branch yet) - -For more information about translations see [Translations](./07-translations.md). diff --git a/docs/versioned_docs/version-2.2/92-development/04-docs.md b/docs/versioned_docs/version-2.2/92-development/04-docs.md deleted file mode 100644 index 55ccb5b7d9..0000000000 --- a/docs/versioned_docs/version-2.2/92-development/04-docs.md +++ /dev/null @@ -1,20 +0,0 @@ -# Documentation - -The documentation is using docusaurus as framework. You can learn more about it from its [official documentation](https://docusaurus.io/docs/). - -If you only want to change some text it probably is enough if you just search for the corresponding [Markdown](https://www.markdownguide.org/basic-syntax/) file inside the `docs/docs/` folder and adjust it. If you want to change larger parts and test the rendered documentation you can run docusaurus locally. Similarly to the UI you need to install [Node.js and pnpm](./01-getting-started.md#install-nodejs--pnpm). After that you can run and build docusaurus locally by using the following commands: - -```bash -cd docs/ - -pnpm install - -# build plugins used by the docs -pnpm build:woodpecker-plugins - -# start docs with hot-reloading, so you can change the docs and directly see the changes in the browser without reloading it manually -pnpm start - -# or build the docs to deploy it to some static page hosting -pnpm build -``` diff --git a/docs/versioned_docs/version-2.2/92-development/05-architecture.md b/docs/versioned_docs/version-2.2/92-development/05-architecture.md deleted file mode 100644 index 466ab2171e..0000000000 --- a/docs/versioned_docs/version-2.2/92-development/05-architecture.md +++ /dev/null @@ -1,48 +0,0 @@ -# Architecture - -## Package architecture - -![Woodpecker architecture](./woodpecker-architecture.png) - -## System architecture - -### main package hierarchy - -| package | meaning | imports | -| ------------------ | -------------------------------------------------------------- | ------------------------------------- | -| `cmd/**` | parse command-line args & environment to stat server/cli/agent | all other | -| `agent/**` | code only agent (remote worker) will need | `pipeline`, `shared` | -| `cli/**` | code only cli tool does need | `pipeline`, `shared`, `woodpecker-go` | -| `server/**` | code only server will need | `pipeline`, `shared` | -| `shared/**` | code shared for all three main tools (go help utils) | only std and external libs | -| `woodpecker-go/**` | go client for server rest api | std | - -### Server - -| package | meaning | imports | -| -------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `server/api/**` | handle web requests from `server/router` | `pipeline`, `../badges`, `../ccmenue`, `../logging`, `../model`, `../pubsub`, `../queue`, `../forge`, `../shared`, `../store`, `shared`, (TODO: mv `server/router/middleware/session`) | -| `server/badges/**` | generate svg badges for pipelines | `../model` | -| `server/ccmenu/**` | generate xml ccmenu for pipelines | `../model` | -| `server/grpc/**` | gRPC server agents can connect to | `pipeline/rpc/**`, `../logging`, `../model`, `../pubsub`, `../queue`, `../forge`, `../pipeline`, `../store` | -| `server/logging/**` | logging lib for gPRC server to stream logs while running | std | -| `server/model/**` | structs for store (db) and api (json) | std | -| `server/plugins/**` | plugins for server | `../model`, `../forge` | -| `server/pipeline/**` | orchestrate pipelines | `pipeline`, `../model`, `../pubsub`, `../queue`, `../forge`, `../store`, `../plugins` | -| `server/pubsub/**` | pubsub lib for server to push changes to the WebUI | std | -| `server/queue/**` | queue lib for server where agents pull new pipelines from via gRPC | `server/model` | -| `server/forge/**` | forge lib for server to connect and handle forge specific stuff | `shared`, `server/model` | -| `server/router/**` | handle requests to REST API (and all middleware) and serve UI and WebUI config | `shared`, `../api`, `../model`, `../forge`, `../store`, `../web` | -| `server/store/**` | handle database | `server/model` | -| `server/shared/**` | TODO: move and split [#974](https://github.com/woodpecker-ci/woodpecker/issues/974) | -| `server/web/**` | server SPA | - -- `../` = `server/` - -### Agent - -TODO - -### CLI - -TODO diff --git a/docs/versioned_docs/version-2.2/92-development/06-guides.md b/docs/versioned_docs/version-2.2/92-development/06-guides.md deleted file mode 100644 index e8db28a537..0000000000 --- a/docs/versioned_docs/version-2.2/92-development/06-guides.md +++ /dev/null @@ -1,24 +0,0 @@ -# Guides - -## ORM - -Woodpecker uses [Xorm](https://xorm.io/) as ORM for the database connection. -You can find its documentation at [gobook.io/read/gitea.com/xorm](https://gobook.io/read/gitea.com/xorm/manual-en-US/). - -## Add a new migration - -Woodpecker uses migrations to change the database schema if a database model has been changed. Add the new migration task into `server/store/datastore/migration/`. - -:::info -Adding new properties to models will be handled automatically by the underlying [ORM](#orm) based on the [struct field tags](https://stackoverflow.com/questions/10858787/what-are-the-uses-for-tags-in-go) of the model. If you add a completely new model, you have to add it to the `allBeans` variable at `server/store/datastore/migration/migration.go` to get a new table created. -::: - -:::warning -You should not use `sess.Begin()`, `sess.Commit()` or `sess.Close()` inside a migration. Session / transaction handling will be done by the underlying migration manager. -::: - -To automatically execute the migration after the start of the server, the new migration needs to be added to the end of `migrationTasks` in `server/store/datastore/migration/migration.go`. After a successful execution of that transaction the server will automatically add the migration to a list, so it won't be executed again on the next start. - -## Constants of official images - -All official default images, are saved in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go) and must be pinned by an exact tag. diff --git a/docs/versioned_docs/version-2.2/92-development/07-translations.md b/docs/versioned_docs/version-2.2/92-development/07-translations.md deleted file mode 100644 index 6ddd9f1eb4..0000000000 --- a/docs/versioned_docs/version-2.2/92-development/07-translations.md +++ /dev/null @@ -1,9 +0,0 @@ -# Translations - -To translate the web UI into your language, we have [our own Weblate instance](https://translate.woodpecker-ci.org/). Please register there and translate Woodpecker into your language. **We won't accept PRs changing any language except English.** - - - Translation status - - -Woodpecker uses [Vue I18n](https://vue-i18n.intlify.dev/) as translation library. diff --git a/docs/versioned_docs/version-2.2/92-development/08-swagger.md b/docs/versioned_docs/version-2.2/92-development/08-swagger.md deleted file mode 100644 index 92505a8fcc..0000000000 --- a/docs/versioned_docs/version-2.2/92-development/08-swagger.md +++ /dev/null @@ -1,63 +0,0 @@ -# Swagger, API Spec and Code Generation - -Woodpecker uses [gin-swagger](https://github.com/swaggo/gin-swagger) middleware to automatically -generate Swagger v2 API specifications and a nice looking Web UI from the source code. -Also, the generated spec will be transformed into Markdown, using [go-swagger](https://github.com/go-swagger/go-swagger) -and then being using on the community's website documentation. - -It's paramount important to keep the gin handler function's godoc documentation up-to-date, -to always have accurate API documentation. -Whenever you change, add or enhance an API endpoint, please update the godocs. - -You don't require any extra tools on your machine, all Swagger tooling is automatically fetched by standard Go tools. - -## Gin-Handler API documentation guideline - -Here's a typical example of how annotations for Swagger documentation look like... - -```go title="server/api/user.go" -// @Summary Get a user -// @Description Returns a user with the specified login name. Requires admin rights. -// @Router /users/{login} [get] -// @Produce json -// @Success 200 {object} User -// @Tags Users -// @Param Authorization header string true "Insert your personal access token" default(Bearer ) -// @Param login path string true "the user's login name" -// @Param foobar query string false "optional foobar parameter" -// @Param page query int false "for response pagination, page offset number" default(1) -// @Param perPage query int false "for response pagination, max items per page" default(50) -``` - -```go title="server/model/user.go" -type User struct { - ID int64 `json:"id" xorm:"pk autoincr 'user_id'"` -// ... -} // @name User -``` - -These guidelines aim to have consistent wording in the swagger doc: - -- first word after `@Summary` and `@Summary` are always uppercase -- `@Summary` has no `.` (dot) at the end of the line -- model structs shall use custom short names, to ease life for API consumers, using `@name` -- `@Success` object or array declarations shall be short, this means the actual `model.User` struct must have a `@name` annotation, so that the model can be renderend in Swagger -- when pagination is used, `@Parame page` and `@Parame perPage` must be added manually -- `@Param Authorization` is almost always present, there are just a few un-protected endpoints - -There are many examples in the `server/api` package, which you can use a blueprint. -More enhanced information you can find here - -### Manual code generation - -```bash title="generate the server's Go code containing the Swagger" -make generate-swagger -``` - -```bash title="update the Markdown in the ./docs folder" -make docs -``` - -```bash title="auto-format swagger related godoc" -go run github.com/swaggo/swag/cmd/swag@latest fmt -g server/api/z.go -``` diff --git a/docs/versioned_docs/version-2.2/92-development/09-security.md b/docs/versioned_docs/version-2.2/92-development/09-security.md deleted file mode 100644 index 24517c8432..0000000000 --- a/docs/versioned_docs/version-2.2/92-development/09-security.md +++ /dev/null @@ -1,10 +0,0 @@ -# Security - -We take security seriously. -If you discover a security issue, please bring it to our attention right away! - -## Reporting a Vulnerability - -Please **DO NOT** file a public issue, instead send your report privately to [`security @ woodpecker-ci.org`](mailto:security@woodpecker-ci.org). - -Security reports are greatly appreciated, and we will publicly thank you for it. If you choose to remain anonymous, we will respect your request and keep your name confidential. diff --git a/docs/versioned_docs/version-2.2/92-development/_category_.yaml b/docs/versioned_docs/version-2.2/92-development/_category_.yaml deleted file mode 100644 index 02d70e09b5..0000000000 --- a/docs/versioned_docs/version-2.2/92-development/_category_.yaml +++ /dev/null @@ -1,4 +0,0 @@ -label: 'Development' -# position: 3 -collapsible: true -collapsed: true diff --git a/docs/versioned_docs/version-2.2/92-development/ui-proxy.svg b/docs/versioned_docs/version-2.2/92-development/ui-proxy.svg deleted file mode 100644 index 79809ffa19..0000000000 --- a/docs/versioned_docs/version-2.2/92-development/ui-proxy.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - - - - forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler) diff --git a/docs/versioned_docs/version-2.2/92-development/vscode-debug.png b/docs/versioned_docs/version-2.2/92-development/vscode-debug.png deleted file mode 100644 index 58861dbde1..0000000000 Binary files a/docs/versioned_docs/version-2.2/92-development/vscode-debug.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/92-development/vscode-run-test.png b/docs/versioned_docs/version-2.2/92-development/vscode-run-test.png deleted file mode 100644 index 6d163f8b8c..0000000000 Binary files a/docs/versioned_docs/version-2.2/92-development/vscode-run-test.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/92-development/woodpecker-architecture.png b/docs/versioned_docs/version-2.2/92-development/woodpecker-architecture.png deleted file mode 100644 index 22f6a054ae..0000000000 Binary files a/docs/versioned_docs/version-2.2/92-development/woodpecker-architecture.png and /dev/null differ diff --git a/docs/versioned_docs/version-2.2/woodpecker.png b/docs/versioned_docs/version-2.2/woodpecker.png deleted file mode 100644 index b92f3589f5..0000000000 Binary files a/docs/versioned_docs/version-2.2/woodpecker.png and /dev/null differ diff --git a/docs/versioned_sidebars/version-2.0-sidebars.json b/docs/versioned_sidebars/version-2.0-sidebars.json deleted file mode 100644 index caea0c03ba..0000000000 --- a/docs/versioned_sidebars/version-2.0-sidebars.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "tutorialSidebar": [ - { - "type": "autogenerated", - "dirName": "." - } - ] -} diff --git a/docs/versioned_sidebars/version-2.1-sidebars.json b/docs/versioned_sidebars/version-2.1-sidebars.json deleted file mode 100644 index caea0c03ba..0000000000 --- a/docs/versioned_sidebars/version-2.1-sidebars.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "tutorialSidebar": [ - { - "type": "autogenerated", - "dirName": "." - } - ] -} diff --git a/docs/versioned_sidebars/version-2.2-sidebars.json b/docs/versioned_sidebars/version-2.2-sidebars.json deleted file mode 100644 index caea0c03ba..0000000000 --- a/docs/versioned_sidebars/version-2.2-sidebars.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "tutorialSidebar": [ - { - "type": "autogenerated", - "dirName": "." - } - ] -} diff --git a/docs/versions.json b/docs/versions.json index 4a93430a06..ebc0244999 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1 +1 @@ -["2.5", "2.4", "2.3", "2.2", "2.1", "2.0", "1.0"] +["2.5", "2.4", "2.3", "1.0"]