From 71d16dae07a0a332e81d5bc9630351c934e03732 Mon Sep 17 00:00:00 2001 From: pat-s Date: Wed, 25 Oct 2023 14:47:34 +0200 Subject: [PATCH 01/22] add initial config --- .markdownlint.yaml | 143 ++++++++++++++++++++++++++++++++++++++++ .pre-commit-config.yaml | 28 ++++++++ CONTRIBUTING.md | 32 +++++---- hooks/pre-commit | 44 +++++++++++++ 4 files changed, 236 insertions(+), 11 deletions(-) create mode 100644 .markdownlint.yaml create mode 100644 .pre-commit-config.yaml create mode 100755 hooks/pre-commit diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 00000000000..11338dc2cca --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,143 @@ +# markdownlint YAML configuration +# https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml + +# Default state for all rules +default: true + +# Path to configuration file to extend +extends: null + +# MD003/heading-style/header-style - Heading style +MD003: + # Heading style + style: "atx" + +# MD004/ul-style - Unordered list style +MD004: + style: "dash" + +# MD007/ul-indent - Unordered list indentation +MD007: + # Spaces for indent + indent: 2 + # Whether to indent the first level of the list + start_indented: false + +# MD009/no-trailing-spaces - Trailing spaces +MD009: + # Spaces for line break + br_spaces: 2 + # Allow spaces for empty lines in list items + list_item_empty_lines: false + # Include unnecessary breaks + strict: false + +# MD010/no-hard-tabs - Hard tabs +MD010: + # Include code blocks + code_blocks: true + +# MD012/no-multiple-blanks - Multiple consecutive blank lines +MD012: + # Consecutive blank lines + maximum: 1 + +# MD013/line-length - Line length +MD013: + # Number of characters + line_length: 500 + # Number of characters for headings + heading_line_length: 100 + # Number of characters for code blocks + code_block_line_length: 80 + # Include code blocks + code_blocks: false + # Include tables + tables: false + # Include headings + headings: true + # Include headings + headers: true + # Strict length checking + strict: false + # Stern length checking + stern: false + +# MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines +MD022: + # Blank lines above heading + lines_above: 1 + # Blank lines below heading + lines_below: 1 + +# MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content +MD024: + # Only check sibling headings + allow_different_nesting: true + +# MD025/single-title/single-h1 - Multiple top-level headings in the same document +MD025: + # Heading level + level: 1 + # RegExp for matching title in front matter + front_matter_title: "^\\s*title\\s*[:=]" + +# MD026/no-trailing-punctuation - Trailing punctuation in heading +MD026: + # Punctuation characters + punctuation: ".,;:!。，；：！" + +# MD029/ol-prefix - Ordered list item prefix +MD029: + # List style + style: "one_or_ordered" + +# MD030/list-marker-space - Spaces after list markers +MD030: + # Spaces for single-line unordered list items + ul_single: 1 + # Spaces for single-line ordered list items + ol_single: 1 + # Spaces for multi-line unordered list items + ul_multi: 1 + # Spaces for multi-line ordered list items + ol_multi: 1 + +# MD033/no-inline-html - Inline HTML +MD033: + # Allowed elements + allowed_elements: [details, summary, img, a, br] + +# MD035/hr-style - Horizontal rule style +MD035: + # Horizontal rule style + style: "---" + +# MD036/no-emphasis-as-heading/no-emphasis-as-header - Emphasis used instead of a heading +MD036: + # Punctuation characters + punctuation: ".,;:!?。，；：！？" + +# MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading +MD041: + # Heading level + level: 1 + # RegExp for matching title in front matter + front_matter_title: "^\\s*title\\s*[:=]" + +# MD044/proper-names - Proper names should have the correct capitalization +MD044: + # List of proper names + # names: + # Include code blocks + code_blocks: false + +# MD046/code-block-style - Code block style +MD046: + # Block style + style: "fenced" + +# MD048/code-fence-style - Code fence style +MD048: + # Code fence syle + style: "backtick" diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000000..43369ae82f0 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,28 @@ +repos: + - repo: meta + hooks: + - id: check-hooks-apply + - id: check-useless-excludes + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v2.3.0 + hooks: + - id: check-yaml + exclude: 'pipeline/schema/.woodpecker/test-merge-map-and-sequence.yml' + - id: end-of-file-fixer + - id: trailing-whitespace + - repo: https://github.com/golangci/golangci-lint + rev: v1.55.1 + hooks: + - id: golangci-lint + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.37.0 + hooks: + - id: markdownlint-fix + - repo: https://github.com/mrtazz/checkmake + rev: 0.2.2 + hooks: + - id: checkmake + # - repo: https://github.com/hadolint/hadolint + # rev: v2.12.0 + # hooks: + # - id: hadolint diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6b1579455b9..bbf8bdbb68d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,8 +2,8 @@ ## Maintainers -To make sure every Pull Request (PR) is checked, we have **team maintainers**. -Every PR **MUST** be reviewed by at least **one** maintainer (or owner) before it can get merged. +To make sure every Pull Request (PR) is checked, we have **team maintainers**. +Every PR **MUST** be reviewed by at least **one** maintainer (or owner) before it can get merged. A maintainer should be a contributor and contributed at least 4 accepted PRs. A contributor should apply as a maintainer in the [Discord #develop](https://discord.gg/fcMQqSMXJy) or [Matrix Develop](https://matrix.to/#/#WoodpeckerCI-Develop:obermui.de) channel. The owners or the team maintainers may invite the contributor. @@ -14,30 +14,30 @@ team](https://github.com/orgs/woodpecker-ci/teams/advisors/members). Of course, if an advisor has time to code review, we will gladly welcome them back to the maintainers team. If a maintainer is inactive for more than 3 months and forgets to leave the maintainers team, the owners may move him or her from the maintainers team to the advisors team. -For security reasons, Maintainers must use 2FA for their accounts and if possible provide GPG signed commits. -https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/ -https://help.github.com/articles/signing-commits-with-gpg/ +For security reasons, Maintainers must use 2FA for their accounts and if possible provide GPG signed commits. + + ## Owners Since Woodpecker is a pure community organization without any company support, -to keep the development healthy we will elect two owners every year. -This can also happen when a owner propose a vote or the majority of the maintainers do so. -All maintainers may vote to elect up to two candidates. When the new owners have been elected, the old owners will give up ownership to the newly elected owners. +to keep the development healthy we will elect two owners every year. +This can also happen when a owner propose a vote or the majority of the maintainers do so. +All maintainers may vote to elect up to two candidates. When the new owners have been elected, the old owners will give up ownership to the newly elected owners. If an owner is unable to do so, the other owners will assist in ceding ownership to the newly elected owners. -For security reasons, Owners must use 2FA. +For security reasons, Owners must use 2FA. ([Docs: Securing your account with two-factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa)) To honor the past owners, here's the history of the owners and the time they served: -- 2023-01-01 ~ 2023-12-31 - https://github.com/woodpecker-ci/woodpecker/issues/1467 +- 2023-01-01 ~ 2023-12-31 - - [6543](https://github.com/6543) - [Anbraten](https://github.com/anbraten) -- 2021-09-28 ~ 2022-12-31 - https://github.com/woodpecker-ci/woodpecker/issues/633 +- 2021-09-28 ~ 2022-12-31 - - [6543](https://github.com/6543) - [Anbraten](https://github.com/anbraten) @@ -61,3 +61,13 @@ modifications). It is the maintainer team's responsibility from this point to ge 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. + +## Development + +[pre-commit](https://pre-commit.com/) is used in this repository. +To apply it during local development, first + +1. Install `pre-commit` via your favorite option +1. Enable it via `pre-commit install` in the repository root. +1. (Run it manually via `pre-commit run --all-files` in the repository root.) +1. Now `pre-commit` will exec on all modified files before every commit. diff --git a/hooks/pre-commit b/hooks/pre-commit new file mode 100755 index 00000000000..7c7d68e3fae --- /dev/null +++ b/hooks/pre-commit @@ -0,0 +1,44 @@ +#!/usr/bin/env python3 +# File generated by pre-commit: https://pre-commit.com +# ID: 138fd403232d2ddd5efb44317e38bf03 +import os +import sys + +# we try our best, but the shebang of this script is difficult to determine: +# - macos doesn't ship with python3 +# - windows executables are almost always `python.exe` +# therefore we continue to support python2 for this small script +if sys.version_info < (3, 3): + from distutils.spawn import find_executable as which +else: + from shutil import which + +# work around https://github.com/Homebrew/homebrew-core/issues/30445 +os.environ.pop('__PYVENV_LAUNCHER__', None) + +# start templated +INSTALL_PYTHON = '/opt/homebrew/opt/python@3.9/bin/python3.9' +ARGS = ['hook-impl', '--config=.pre-commit-config.yaml', '--hook-type=pre-commit', '--skip-on-missing-config'] +# end templated +ARGS.extend(('--hook-dir', os.path.realpath(os.path.dirname(__file__)))) +ARGS.append('--') +ARGS.extend(sys.argv[1:]) + +DNE = '`pre-commit` not found. Did you forget to activate your virtualenv?' +if os.access(INSTALL_PYTHON, os.X_OK): + CMD = [INSTALL_PYTHON, '-mpre_commit'] +elif which('pre-commit'): + CMD = ['pre-commit'] +else: + raise SystemExit(DNE) + +CMD.extend(ARGS) +if sys.platform == 'win32': # https://bugs.python.org/issue19124 + import subprocess + + if sys.version_info < (3, 7): # https://bugs.python.org/issue25942 + raise SystemExit(subprocess.Popen(CMD).wait()) + else: + raise SystemExit(subprocess.call(CMD)) +else: + os.execvp(CMD[0], CMD) From d21242d456a80fb7945819e92ef562aaa48a47b1 Mon Sep 17 00:00:00 2001 From: pat-s Date: Wed, 25 Oct 2023 14:55:37 +0200 Subject: [PATCH 02/22] add ci config --- .pre-commit-config.yaml | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 43369ae82f0..f5b5e7cd244 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -22,7 +22,19 @@ repos: rev: 0.2.2 hooks: - id: checkmake - # - repo: https://github.com/hadolint/hadolint - # rev: v2.12.0 - # hooks: - # - id: hadolint + - repo: https://github.com/hadolint/hadolint + rev: v2.12.0 + hooks: + - id: hadolint + +ci: + autofix_commit_msg: | + [pre-commit.ci] auto fixes from pre-commit.com hooks + + for more information, see https://pre-commit.ci + autofix_prs: true + autoupdate_branch: '' + autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate' + autoupdate_schedule: monthly + skip: [check-hooks-apply, check-useless-excludes] + submodules: false From 07da727d9dbe9dcb7dcdcee24007a56f04fa141c Mon Sep 17 00:00:00 2001 From: pat-s Date: Wed, 25 Oct 2023 14:58:21 +0200 Subject: [PATCH 03/22] delete local hook --- hooks/pre-commit | 44 -------------------------------------------- 1 file changed, 44 deletions(-) delete mode 100755 hooks/pre-commit diff --git a/hooks/pre-commit b/hooks/pre-commit deleted file mode 100755 index 7c7d68e3fae..00000000000 --- a/hooks/pre-commit +++ /dev/null @@ -1,44 +0,0 @@ -#!/usr/bin/env python3 -# File generated by pre-commit: https://pre-commit.com -# ID: 138fd403232d2ddd5efb44317e38bf03 -import os -import sys - -# we try our best, but the shebang of this script is difficult to determine: -# - macos doesn't ship with python3 -# - windows executables are almost always `python.exe` -# therefore we continue to support python2 for this small script -if sys.version_info < (3, 3): - from distutils.spawn import find_executable as which -else: - from shutil import which - -# work around https://github.com/Homebrew/homebrew-core/issues/30445 -os.environ.pop('__PYVENV_LAUNCHER__', None) - -# start templated -INSTALL_PYTHON = '/opt/homebrew/opt/python@3.9/bin/python3.9' -ARGS = ['hook-impl', '--config=.pre-commit-config.yaml', '--hook-type=pre-commit', '--skip-on-missing-config'] -# end templated -ARGS.extend(('--hook-dir', os.path.realpath(os.path.dirname(__file__)))) -ARGS.append('--') -ARGS.extend(sys.argv[1:]) - -DNE = '`pre-commit` not found. Did you forget to activate your virtualenv?' -if os.access(INSTALL_PYTHON, os.X_OK): - CMD = [INSTALL_PYTHON, '-mpre_commit'] -elif which('pre-commit'): - CMD = ['pre-commit'] -else: - raise SystemExit(DNE) - -CMD.extend(ARGS) -if sys.platform == 'win32': # https://bugs.python.org/issue19124 - import subprocess - - if sys.version_info < (3, 7): # https://bugs.python.org/issue25942 - raise SystemExit(subprocess.Popen(CMD).wait()) - else: - raise SystemExit(subprocess.call(CMD)) -else: - os.execvp(CMD[0], CMD) From c22127ec20aaf861f850abebf07e35b2882419bd Mon Sep 17 00:00:00 2001 From: pat-s Date: Wed, 25 Oct 2023 15:01:43 +0200 Subject: [PATCH 04/22] [CI SKIP] --- .pre-commit-config.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f5b5e7cd244..46f9dd196fb 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -14,6 +14,7 @@ repos: rev: v1.55.1 hooks: - id: golangci-lint + - id: golangci-lint-full - repo: https://github.com/igorshubovych/markdownlint-cli rev: v0.37.0 hooks: @@ -29,12 +30,12 @@ repos: ci: autofix_commit_msg: | - [pre-commit.ci] auto fixes from pre-commit.com hooks + [pre-commit.ci] auto fixes from pre-commit.com hooks [CI SKIP] for more information, see https://pre-commit.ci autofix_prs: true autoupdate_branch: '' autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate' autoupdate_schedule: monthly - skip: [check-hooks-apply, check-useless-excludes] + skip: [check-hooks-apply, check-useless-excludes, golangci-lint] submodules: false From 0732c5d36c101f3487eaffecef13e296363c978b Mon Sep 17 00:00:00 2001 From: pat-s Date: Thu, 26 Oct 2023 13:59:43 +0200 Subject: [PATCH 05/22] use `\` instead of trailing space --- CONTRIBUTING.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bbf8bdbb68d..1d681f945cb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,8 +2,8 @@ ## Maintainers -To make sure every Pull Request (PR) is checked, we have **team maintainers**. -Every PR **MUST** be reviewed by at least **one** maintainer (or owner) before it can get merged. +To make sure every Pull Request (PR) is checked, we have **team maintainers**.\ +Every PR **MUST** be reviewed by at least **one** maintainer (or owner) before it can get merged.\ A maintainer should be a contributor and contributed at least 4 accepted PRs. A contributor should apply as a maintainer in the [Discord #develop](https://discord.gg/fcMQqSMXJy) or [Matrix Develop](https://matrix.to/#/#WoodpeckerCI-Develop:obermui.de) channel. The owners or the team maintainers may invite the contributor. @@ -14,19 +14,18 @@ team](https://github.com/orgs/woodpecker-ci/teams/advisors/members). Of course, if an advisor has time to code review, we will gladly welcome them back to the maintainers team. If a maintainer is inactive for more than 3 months and forgets to leave the maintainers team, the owners may move him or her from the maintainers team to the advisors team. -For security reasons, Maintainers must use 2FA for their accounts and if possible provide GPG signed commits. +For security reasons, Maintainers must use 2FA for their accounts and if possible provide GPG signed commits.\ ## Owners -Since Woodpecker is a pure community organization without any company support, -to keep the development healthy we will elect two owners every year. -This can also happen when a owner propose a vote or the majority of the maintainers do so. +Since Woodpecker is a pure community organization without any company support, to keep the development healthy we will elect two owners every year.\ +This can also happen when a owner propose a vote or the majority of the maintainers do so.\ All maintainers may vote to elect up to two candidates. When the new owners have been elected, the old owners will give up ownership to the newly elected owners. If an owner is unable to do so, the other owners will assist in ceding ownership to the newly elected owners. -For security reasons, Owners must use 2FA. +For security reasons, Owners must use 2FA.\ ([Docs: Securing your account with two-factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa)) To honor the past owners, here's the history of the owners and the time From eae7652e1b87e11dbe12fd54be8d3c0e3eefc79b Mon Sep 17 00:00:00 2001 From: pat-s Date: Sat, 28 Oct 2023 21:35:29 +0200 Subject: [PATCH 06/22] add hadolint.yml --- .hadolint.yml | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 .hadolint.yml diff --git a/.hadolint.yml b/.hadolint.yml new file mode 100644 index 00000000000..85e8ce0f72b --- /dev/null +++ b/.hadolint.yml @@ -0,0 +1,2 @@ +ignored: + - DL3018 # pin versions in Dockerfile From c59bb3379936e1f27ba7976dbc499d484fafb484 Mon Sep 17 00:00:00 2001 From: pat-s Date: Sat, 28 Oct 2023 21:46:54 +0200 Subject: [PATCH 07/22] md lint --- .markdownlint.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 11338dc2cca..83be56f64d5 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -106,7 +106,7 @@ MD030: # MD033/no-inline-html - Inline HTML MD033: # Allowed elements - allowed_elements: [details, summary, img, a, br] + allowed_elements: [details, summary, img, a, br, p] # MD035/hr-style - Horizontal rule style MD035: From 66e7488c7355e782fbb91c55c957dc41729dcc31 Mon Sep 17 00:00:00 2001 From: pat-s Date: Sat, 28 Oct 2023 21:57:04 +0200 Subject: [PATCH 08/22] no fix --- .pre-commit-config.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 46f9dd196fb..289d4c5c6c8 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -14,11 +14,10 @@ repos: rev: v1.55.1 hooks: - id: golangci-lint - - id: golangci-lint-full - repo: https://github.com/igorshubovych/markdownlint-cli rev: v0.37.0 hooks: - - id: markdownlint-fix + - id: markdownlint - repo: https://github.com/mrtazz/checkmake rev: 0.2.2 hooks: @@ -37,5 +36,5 @@ ci: autoupdate_branch: '' autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate' autoupdate_schedule: monthly - skip: [check-hooks-apply, check-useless-excludes, golangci-lint] + skip: [check-hooks-apply, check-useless-excludes] submodules: false From 187b469315b521f87dfbd138a7e4fe0ba31855d6 Mon Sep 17 00:00:00 2001 From: pat-s Date: Sat, 28 Oct 2023 21:59:49 +0200 Subject: [PATCH 09/22] precommit fixes --- .woodpecker/securityscan.yml | 2 +- CHANGELOG.md | 1002 ++++++++--------- Makefile | 5 + README.md | 11 +- SECURITY.md | 4 +- cli/README.md | 2 +- docs/README.md | 8 +- docs/blog/2023-07-28-release-v1.0.0/index.md | 18 +- .../20-usage/15-terminiology/architecture.svg | 6 +- .../pipeline-workflow-step.svg | 6 +- docs/docs/20-usage/20-workflow-syntax.md | 2 +- .../00-deployment/00-overview.md | 2 +- .../30-administration/11-forges/20-github.md | 2 +- docs/docs/30-administration/40-encryption.md | 4 +- docs/docs/30-administration/90-prometheus.md | 2 +- .../docs/92-development/01-getting-started.md | 2 +- docs/docs/92-development/03-ui.md | 2 +- docs/docs/92-development/08-swagger.md | 32 +- docs/docs/92-development/09-security.md | 4 +- docs/docs/92-development/ui-proxy.svg | 4 +- .../20-usage/20-pipeline-syntax.md | 8 +- .../20-usage/22-conditional-execution.md | 4 +- .../version-0.15/20-usage/40-secrets.md | 3 +- .../20-usage/71-project-settings.md | 1 - .../30-administration/00-setup.md | 2 + .../30-administration/10-server-config.md | 33 +- .../30-administration/11-vcs/20-github.md | 6 + .../30-administration/11-vcs/30-gitea.md | 8 +- .../30-administration/11-vcs/40-gitlab.md | 5 + .../30-administration/11-vcs/50-bitbucket.md | 3 + .../11-vcs/60-bitbucket_server.md | 10 +- .../30-administration/11-vcs/70-gogs.md | 6 + .../30-administration/11-vcs/80-coding.md | 9 + .../30-administration/15-agent-config.md | 23 +- .../version-0.15/30-administration/60-ssl.md | 3 +- .../30-administration/70-proxy.md | 4 +- .../30-administration/80-kubernetes.md | 3 +- .../30-administration/90-prometheus.md | 2 +- docs/versioned_docs/version-0.15/40-cli.md | 1 + .../version-0.15/80-downloads.md | 9 +- .../version-0.15/91-migrations.md | 1 + .../92-development/01-getting-started.md | 9 +- .../version-0.15/92-development/03-ui.md | 1 + .../version-0.15/92-development/ui-proxy.svg | 4 +- .../20-usage/20-pipeline-syntax.md | 4 +- .../20-usage/35-advanced-yaml-syntax.md | 1 + .../version-1.0/20-usage/40-secrets.md | 1 - .../20-usage/71-project-settings.md | 2 +- .../version-1.0/30-administration/00-setup.md | 2 +- .../30-administration/10-server-config.md | 69 +- .../30-administration/11-forges/20-github.md | 8 + .../30-administration/11-forges/30-gitea.md | 10 +- .../30-administration/11-forges/40-gitlab.md | 7 + .../11-forges/50-bitbucket.md | 5 + .../30-administration/15-agent-config.md | 18 + .../22-backends/10-docker.md | 3 + .../30-administration/22-backends/20-local.md | 2 - .../30-administration/22-backends/30-ssh.md | 5 + .../22-backends/40-kubernetes.md | 7 + .../30-administration/40-encryption.md | 17 +- .../version-1.0/30-administration/70-proxy.md | 1 - .../30-administration/90-prometheus.md | 2 +- docs/versioned_docs/version-1.0/40-cli.md | 83 +- .../92-development/01-getting-started.md | 9 +- .../version-1.0/92-development/03-ui.md | 3 +- .../92-development/05-architecture.md | 2 +- .../version-1.0/92-development/08-swagger.md | 49 +- .../version-1.0/92-development/09-security.md | 4 +- .../version-1.0/92-development/ui-proxy.svg | 4 +- pipeline/samples/sample_1/README.md | 6 +- pipeline/samples/sample_10_windows/README.md | 6 +- .../samples/sample_8_network_mode/README.md | 8 +- web/public/favicons/favicon-dark-error.svg | 2 +- web/public/favicons/favicon-dark-pending.svg | 2 +- web/public/favicons/favicon-dark-success.svg | 2 +- web/public/favicons/favicon-light-default.svg | 2 +- web/public/favicons/favicon-light-error.svg | 2 +- web/public/favicons/favicon-light-pending.svg | 2 +- web/public/favicons/favicon-light-success.svg | 2 +- woodpecker-go/LICENSE | 1 - 80 files changed, 931 insertions(+), 700 deletions(-) diff --git a/.woodpecker/securityscan.yml b/.woodpecker/securityscan.yml index c81074f7339..6c5a95017f9 100644 --- a/.woodpecker/securityscan.yml +++ b/.woodpecker/securityscan.yml @@ -6,7 +6,7 @@ when: - release/* variables: - - &trivy_image aquasec/trivy:latest + - &trivy_image aquasec/trivy:0.46.1 - &trivy_plugin codeberg.org/woodpecker-plugins/trivy:1.0.1 steps: diff --git a/CHANGELOG.md b/CHANGELOG.md index 1eeced8c43a..04a016b69d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,564 +2,564 @@ ## [1.0.3](https://github.com/woodpecker-ci/woodpecker/releases/tag/v1.0.3) - 2023-10-14 -* SECURITY - * Update dependencies (#2587) - * Frontend: bump postcss to 8.4.31 (#2541) - * Check permissions on repo lookup (#2358) - * Change token logging to trace level (#2247) (#2248) -* BUGFIXES - * Fix gitlab hooks (#2537) (#2542) - * Trim last "/" from WOODPECKER_HOST config (#2538) (#2540) - * Fix(server/api/repo): Fix repair webhook host (#2372) (#2452) - * Show correct event in pipeline step list (#2448) - * Make WOODPECKER_MIGRATIONS_ALLOW_LONG have an actuall effect (#2251) (#2309) - * Docker build dont ignore ci env vars (#2238) (#2246) - * Handle parsed hooks that should be ignored (#2243) (#2244) - * Return 204 not 500 on filtered pipeline (#2230) - * Set correct version for release branch releases (#2227) (#2229) -* MISC - * Rebuild swagger with latest version (#2455) +- SECURITY + - Update dependencies (#2587) + - Frontend: bump postcss to 8.4.31 (#2541) + - Check permissions on repo lookup (#2358) + - Change token logging to trace level (#2247) (#2248) +- BUGFIXES + - Fix gitlab hooks (#2537) (#2542) + - Trim last "/" from WOODPECKER_HOST config (#2538) (#2540) + - Fix(server/api/repo): Fix repair webhook host (#2372) (#2452) + - Show correct event in pipeline step list (#2448) + - Make WOODPECKER_MIGRATIONS_ALLOW_LONG have an actuall effect (#2251) (#2309) + - Docker build dont ignore ci env vars (#2238) (#2246) + - Handle parsed hooks that should be ignored (#2243) (#2244) + - Return 204 not 500 on filtered pipeline (#2230) + - Set correct version for release branch releases (#2227) (#2229) +- MISC + - Rebuild swagger with latest version (#2455) ## [1.0.2](https://github.com/woodpecker-ci/woodpecker/releases/tag/v1.0.2) - 2023-08-16 -* SECURITY - * Validate webhook before change any data (#2221) (#2222) -* BUGFIXES - * Bump default git clone plugin (#2215) (#2220) - * Show all steps (#2190) (#2191) +- SECURITY + - Validate webhook before change any data (#2221) (#2222) +- BUGFIXES + - Bump default git clone plugin (#2215) (#2220) + - Show all steps (#2190) (#2191) ## [1.0.1](https://github.com/woodpecker-ci/woodpecker/releases/tag/v1.0.1) - 2023-08-08 -* SECURITY - * Fix WOODPECKER_GRPC_VERIFY being ignored (#2077) (#2082) -* BUGFIXES - * Fix 'add-orgs' migration (#2117) (#2145) - * Fix UI and backend paths with subpath (#1799) (#2133) - * Fix swagger response code (#2119) (#2121) - * Forge Github Org: Use `login` instead of `name` (#2104) (#2106) - * Client.go: Backport fix RepoPost path (#2100) - * Fix translation key (#2098) +- SECURITY + - Fix WOODPECKER_GRPC_VERIFY being ignored (#2077) (#2082) +- BUGFIXES + - Fix 'add-orgs' migration (#2117) (#2145) + - Fix UI and backend paths with subpath (#1799) (#2133) + - Fix swagger response code (#2119) (#2121) + - Forge Github Org: Use `login` instead of `name` (#2104) (#2106) + - Client.go: Backport fix RepoPost path (#2100) + - Fix translation key (#2098) ## [1.0.0](https://github.com/woodpecker-ci/woodpecker/releases/tag/v1.0.0) - 2023-07-29 -* BREAKING - * Use IDs to access organizations (#1873) - * Drop support for Bitbucket Server (#1994) - * Rename yaml `pipeline` to `steps` (#1833) - * Drop ".drone.yml" as default pipeline config (#1795) - * Build-in Env Vars, use _URL for all links/URLs (#1794) - * Resolve built-in variables for global when filtered too (#1790) - * Drop "Gogs" support (#1752) - * Access repos by their IDs (#1691) - * Drop "coding" support (#1644) - * Add queue details UI for admins (#1632) - * Remove `command:` from steps (#1032) - * Remove old `build` API routes (#1283) - * Let single line command be a single command (#1009) - * Drop deprecated environment vars (#920) - * Drop Var-Args in steps in favor of settings (#919) - * Fix branch condition on tags (#917) - * Use asymmetric key to sign webhooks (#916) - * Add agent tagging / filtering for pipelines (#902) - * Delete old fallback for "drone.sqlite" (#791) - * Migrate to certmagic (#360) -* FEATURES - * Implement YAML Map Merge, Overrides, and Sequence Merge Support (#1720) - * Add users UI for admins (#1634) - * Add agent no-schedule flag (#1567) - * Change locale in user settings (#1305) - * Add when evaluate filter (#1213) - * Store an agents list and add agent heartbeats (#1189) - * Add ability to trigger manual builds (#1156) - * Add default event filter (#1140) - * Add CLI support for global and organization secrets (#1113) - * Allow multiple when conditions (#1087) - * Add syntax highlighting for pipeline config (#1082) - * Add `logs` command to CLI & update forges features docs (#1064) - * Add method to check organization membership (#1037) - * Global and organization secrets (#1027) - * Add pipeline log output download (#1023) - * Provide global environment variables for pipeline substitution (#968) - * Add cron jobs (#934) - * Support localized web UI (#912) - * Add support to define a custom docker network and enable docker ipv6 (#893) - * Add SSH backend (#861) - * Add support for superseding runs (#831) - * Add support for steps to be a list (instead of dict) (#826) - * Add editing of secrets and registries (#823) - * Allow loading sensitive flags from files (#815) - * Add support for pipeline configuration service (#804) - * Support all backends for CLI exec (#801) - * Add support for pipeline root.when conditions (#770) - * Add support to run pipelines using a local backend (#709) - * Add initial version of Kubernetes backend (#552) -* SECURITY - * Fix ignoring server set pipeline max-timeout (#1875) - * Only grant privileged to plugins (#1646) - * Only inject netrc to trusted clone plugins (#1352) - * Support plugin-only secrets (#1344) - * Fix insecure /tmp usage in local backend (#872) -* BUGFIXES - * Handle case where there is no latest pipeline for GetBadge (#2042) (#2050) - * Fix repo gate protection (#1969) - * Make secrets with "/" in name editable / deletable (#1938) - * Fix Bitbucket implement missing features (#1887) (#1889) - * Fix nil pointer in repo repair (#1804) - * Do not use OAuth client without token (#1803) - * Correct label argument parsing in agent code (#1717) - * Fully support `.yaml` (#1713) - * Consistent status on delete (#1703) - * Fix Bitbucket Server branches (#1698) - * Set 'HOME' during local pipeline step (#1686) - * Pipeline compiler: handle nil entrys in settings list (#1626) - * Fix: backend auto-detection should be consistent (#1618) - * Return 404 on badge endpoint for inactive repos (#1600) - * Ensure the SharedInformerFactory closes eventually (#1585) - * Deduplicate step docker container volumes (#1571) - * Don't require secret value on secret edit (#1552) (#1553) - * Rework status constraint logic for successes (#1515) - * Don't panic on hook parsing (#1501) - * Hide not owned repos from sidebar and repo list (#1453) - * Fix cut of woodpecker animation (#1402) - * Fix approval on mobile (#1320) - * Unify buttons, links and improve focus styles (#1317) - * Fix pipeline manual trigger on web (#1307) - * Fix SCM visibility if user visibility is private (#1217) - * Hide log output container if step does not have logs (#1086) - * Fix to show build pipeline parse error (#1066) - * Pipeline compiler should not alter specified image (#1005) - * Gracefully handle non-zero exit code in local backend (#1002) - * Replace run_on references with runs_on (#965) - * Set default logging value of CLI to info (#871) - * Support conditional branch as an array to align with documentation (#836) - * Fix redirect after login (#824) -* ENHANCEMENTS - * Add BranchHead implementation for bitbucket forge (#2011) - * Use global logger for xorm logs and add options (#1997) - * Let HookParse func explicit ignore events (#1942) - * Link swagger in navbar (#1984) - * Add option to read grpc-secret from file (#1972) - * Let pipeline-compiler export step types (#1958) - * docker backend use uuid instead of name as identifier (#1967) - * Kubernetes do not set Pod's Image pull policy if not explicitly set (#1914) - * Fixed when:evaluate on non-standard (non-CI*) env vars (#1907) - * Add pull-request implementation for bitbucket forge (#1889) - * Store agent ID in config file (#1888) - * Fix bitbucket forge add repo (#1887) - * Added Woodpecker Host Config used for Webhooks (#1869) - * Drop old columns (#1838) - * Remove MSSQL specific code and cleanups (#1796) - * Remove unused file system API (#1791) - * Add Forge Metadata to built-in environment variables (#1789) - * Redirect to new pipeline (#1761) - * Add reset token button (#1755) - * Add agent functions to go-sdk (#1754) - * Always send a status back to forge (#1751) - * Allow to configure listener port for SSL (#1735) - * Identify users using their remote ID (#1732) - * Let agent retry to connecting to server (#1728) - * Stable sort order for DB lists (#1702) - * Add backend label to agents (#1692) - * Web: use i18n-t to avoid v-html directive (#1676) - * Various UI improvements (#1663) - * Do not store inactive repos without any resources (#1658) - * Implement visual display of queue statistics (#1657) - * Agent check gRPC version against server (#1653) - * Initiate Pagination Implementation for API and Infinite Scroll in UI (#1651) - * Add PR pipeline list (#1641) - * Save agent-id for tasks and add endpoint to get agent tasks (#1631) - * Return 404 if pipeline not exist and handle 404 errors in WebUI (#1627) - * UI should confirm secret deletion (#1604) - * Add collapsable support to panel elements (#1601) - * Add cancel button on secrets tab (#1599) - * Allow custom dnsConfig in agent deployment (#1569) - * Show platform, backend and capacity as badges in agent list (#1568) - * Define WOODPECKER_FORGE_TIMEOUT server config (#1558) - * Sort repos by org/name (#1548) - * Improve button and input contrast in dark mode (#1456) - * Consistent and more descriptive naming of parameters in index.ts (#1455) - * Add button in UI to trigger the deployment event (#1415) - * Use icons for step and workflow states (#1409) - * Match notification font size to rest of the UI (#1399) - * Support .yaml as file-ending for workflow config too (#1388) - * Show workflow state in UI and collapse completed workflows (#1383) - * Use pipeline wrapper and improve scaffold UI (#1368) - * Lazy load locales (#1362) - * Always use rounded quadrat user avatars (#1350) - * Fix display of long pipeline and job names (#1346) - * Support changed files for Gitea PRs (#1342) - * Allow to change directory for steps (#1329) - * UI use system font stack (#1326) - * Add pull request labels as environment variable (#1321) - * Make pipeline workflows collapsable (#1304) - * Make submit buttons green and add forms (#1302) - * Add pipeline build number into Pipeline list (#1301) - * Add title to docs links (#1298) - * Check if repo exists before creating pipeline (#1297) - * Use HTML buttons to allow keyboard navigation (#1242) - * Introduce and use Pagination helper func (#1236) - * Sort secret lists and events (#1223) - * Add support sub-settings and secrets in sub-settings (#1221) - * Add option to ignore failures on steps (#1219) - * Set a default value for `pipeline-event` flag of `cli exec` command (#1212) - * Add option for docker runtime to provide default volumes (#1203) - * Make healthcheck port configurable (#1197) - * Don't show "changed files" if event can't have them (#1191) - * Add dedicated DroneCI env compatibility layer (#1185) - * Only enable debug endpoints if log level is debug or below (#1160) - * Sort pipelines based on creation date (#1159) - * Add option to turn on and off log automatic scrolling (#1149) - * Checkout tags on tag pipeline (#1110) - * Use fixed version of git clone plugin (#1108) - * Fetch repositories with remote ID if possible (#1078) - * Support Docker credential helpers (#1075) - * Do not show pipeline name if it's a single file (#1069) - * Remove xterm and use ansi converter for logs (#1067) - * Update jsonschema and define "services" (#1036) - * Show forge icons in UI (#987) - * Make pipeline runtime log with description (#970) - * Improve UI colors to have more contrast (#943) - * Add branches support for BitBucket (#907) - * Auto cancel blocked pipelines (#905) - * Allow to change forge status messages (#900) - * Added support for step errors when executing backend (#817) - * Do not filter on linux/amd64 per default (#805) -* DOCUMENTATION - * Remove never implemented "tag"-filter and document "ref"-filter to do the same (#1820) - * Define Glossary (#1800) - * Add more documentation about branch matching (#1186) - * Use versioned docs (#1145) - * Add gitpod setup (#1020) -* MISC - * Drop tarball release (#1819) - * Move helm charts to own repo "helm" (#1589) - * Replace yarn with pnpm (#1240) - * Publish preview docker images of pulls (#1072) +- BREAKING + - Use IDs to access organizations (#1873) + - Drop support for Bitbucket Server (#1994) + - Rename yaml `pipeline` to `steps` (#1833) + - Drop ".drone.yml" as default pipeline config (#1795) + - Build-in Env Vars, use _URL for all links/URLs (#1794) + - Resolve built-in variables for global when filtered too (#1790) + - Drop "Gogs" support (#1752) + - Access repos by their IDs (#1691) + - Drop "coding" support (#1644) + - Add queue details UI for admins (#1632) + - Remove `command:` from steps (#1032) + - Remove old `build` API routes (#1283) + - Let single line command be a single command (#1009) + - Drop deprecated environment vars (#920) + - Drop Var-Args in steps in favor of settings (#919) + - Fix branch condition on tags (#917) + - Use asymmetric key to sign webhooks (#916) + - Add agent tagging / filtering for pipelines (#902) + - Delete old fallback for "drone.sqlite" (#791) + - Migrate to certmagic (#360) +- FEATURES + - Implement YAML Map Merge, Overrides, and Sequence Merge Support (#1720) + - Add users UI for admins (#1634) + - Add agent no-schedule flag (#1567) + - Change locale in user settings (#1305) + - Add when evaluate filter (#1213) + - Store an agents list and add agent heartbeats (#1189) + - Add ability to trigger manual builds (#1156) + - Add default event filter (#1140) + - Add CLI support for global and organization secrets (#1113) + - Allow multiple when conditions (#1087) + - Add syntax highlighting for pipeline config (#1082) + - Add `logs` command to CLI & update forges features docs (#1064) + - Add method to check organization membership (#1037) + - Global and organization secrets (#1027) + - Add pipeline log output download (#1023) + - Provide global environment variables for pipeline substitution (#968) + - Add cron jobs (#934) + - Support localized web UI (#912) + - Add support to define a custom docker network and enable docker ipv6 (#893) + - Add SSH backend (#861) + - Add support for superseding runs (#831) + - Add support for steps to be a list (instead of dict) (#826) + - Add editing of secrets and registries (#823) + - Allow loading sensitive flags from files (#815) + - Add support for pipeline configuration service (#804) + - Support all backends for CLI exec (#801) + - Add support for pipeline root.when conditions (#770) + - Add support to run pipelines using a local backend (#709) + - Add initial version of Kubernetes backend (#552) +- SECURITY + - Fix ignoring server set pipeline max-timeout (#1875) + - Only grant privileged to plugins (#1646) + - Only inject netrc to trusted clone plugins (#1352) + - Support plugin-only secrets (#1344) + - Fix insecure /tmp usage in local backend (#872) +- BUGFIXES + - Handle case where there is no latest pipeline for GetBadge (#2042) (#2050) + - Fix repo gate protection (#1969) + - Make secrets with "/" in name editable / deletable (#1938) + - Fix Bitbucket implement missing features (#1887) (#1889) + - Fix nil pointer in repo repair (#1804) + - Do not use OAuth client without token (#1803) + - Correct label argument parsing in agent code (#1717) + - Fully support `.yaml` (#1713) + - Consistent status on delete (#1703) + - Fix Bitbucket Server branches (#1698) + - Set 'HOME' during local pipeline step (#1686) + - Pipeline compiler: handle nil entrys in settings list (#1626) + - Fix: backend auto-detection should be consistent (#1618) + - Return 404 on badge endpoint for inactive repos (#1600) + - Ensure the SharedInformerFactory closes eventually (#1585) + - Deduplicate step docker container volumes (#1571) + - Don't require secret value on secret edit (#1552) (#1553) + - Rework status constraint logic for successes (#1515) + - Don't panic on hook parsing (#1501) + - Hide not owned repos from sidebar and repo list (#1453) + - Fix cut of woodpecker animation (#1402) + - Fix approval on mobile (#1320) + - Unify buttons, links and improve focus styles (#1317) + - Fix pipeline manual trigger on web (#1307) + - Fix SCM visibility if user visibility is private (#1217) + - Hide log output container if step does not have logs (#1086) + - Fix to show build pipeline parse error (#1066) + - Pipeline compiler should not alter specified image (#1005) + - Gracefully handle non-zero exit code in local backend (#1002) + - Replace run_on references with runs_on (#965) + - Set default logging value of CLI to info (#871) + - Support conditional branch as an array to align with documentation (#836) + - Fix redirect after login (#824) +- ENHANCEMENTS + - Add BranchHead implementation for bitbucket forge (#2011) + - Use global logger for xorm logs and add options (#1997) + - Let HookParse func explicit ignore events (#1942) + - Link swagger in navbar (#1984) + - Add option to read grpc-secret from file (#1972) + - Let pipeline-compiler export step types (#1958) + - docker backend use uuid instead of name as identifier (#1967) + - Kubernetes do not set Pod's Image pull policy if not explicitly set (#1914) + - Fixed when:evaluate on non-standard (non-CI*) env vars (#1907) + - Add pull-request implementation for bitbucket forge (#1889) + - Store agent ID in config file (#1888) + - Fix bitbucket forge add repo (#1887) + - Added Woodpecker Host Config used for Webhooks (#1869) + - Drop old columns (#1838) + - Remove MSSQL specific code and cleanups (#1796) + - Remove unused file system API (#1791) + - Add Forge Metadata to built-in environment variables (#1789) + - Redirect to new pipeline (#1761) + - Add reset token button (#1755) + - Add agent functions to go-sdk (#1754) + - Always send a status back to forge (#1751) + - Allow to configure listener port for SSL (#1735) + - Identify users using their remote ID (#1732) + - Let agent retry to connecting to server (#1728) + - Stable sort order for DB lists (#1702) + - Add backend label to agents (#1692) + - Web: use i18n-t to avoid v-html directive (#1676) + - Various UI improvements (#1663) + - Do not store inactive repos without any resources (#1658) + - Implement visual display of queue statistics (#1657) + - Agent check gRPC version against server (#1653) + - Initiate Pagination Implementation for API and Infinite Scroll in UI (#1651) + - Add PR pipeline list (#1641) + - Save agent-id for tasks and add endpoint to get agent tasks (#1631) + - Return 404 if pipeline not exist and handle 404 errors in WebUI (#1627) + - UI should confirm secret deletion (#1604) + - Add collapsable support to panel elements (#1601) + - Add cancel button on secrets tab (#1599) + - Allow custom dnsConfig in agent deployment (#1569) + - Show platform, backend and capacity as badges in agent list (#1568) + - Define WOODPECKER_FORGE_TIMEOUT server config (#1558) + - Sort repos by org/name (#1548) + - Improve button and input contrast in dark mode (#1456) + - Consistent and more descriptive naming of parameters in index.ts (#1455) + - Add button in UI to trigger the deployment event (#1415) + - Use icons for step and workflow states (#1409) + - Match notification font size to rest of the UI (#1399) + - Support .yaml as file-ending for workflow config too (#1388) + - Show workflow state in UI and collapse completed workflows (#1383) + - Use pipeline wrapper and improve scaffold UI (#1368) + - Lazy load locales (#1362) + - Always use rounded quadrat user avatars (#1350) + - Fix display of long pipeline and job names (#1346) + - Support changed files for Gitea PRs (#1342) + - Allow to change directory for steps (#1329) + - UI use system font stack (#1326) + - Add pull request labels as environment variable (#1321) + - Make pipeline workflows collapsable (#1304) + - Make submit buttons green and add forms (#1302) + - Add pipeline build number into Pipeline list (#1301) + - Add title to docs links (#1298) + - Check if repo exists before creating pipeline (#1297) + - Use HTML buttons to allow keyboard navigation (#1242) + - Introduce and use Pagination helper func (#1236) + - Sort secret lists and events (#1223) + - Add support sub-settings and secrets in sub-settings (#1221) + - Add option to ignore failures on steps (#1219) + - Set a default value for `pipeline-event` flag of `cli exec` command (#1212) + - Add option for docker runtime to provide default volumes (#1203) + - Make healthcheck port configurable (#1197) + - Don't show "changed files" if event can't have them (#1191) + - Add dedicated DroneCI env compatibility layer (#1185) + - Only enable debug endpoints if log level is debug or below (#1160) + - Sort pipelines based on creation date (#1159) + - Add option to turn on and off log automatic scrolling (#1149) + - Checkout tags on tag pipeline (#1110) + - Use fixed version of git clone plugin (#1108) + - Fetch repositories with remote ID if possible (#1078) + - Support Docker credential helpers (#1075) + - Do not show pipeline name if it's a single file (#1069) + - Remove xterm and use ansi converter for logs (#1067) + - Update jsonschema and define "services" (#1036) + - Show forge icons in UI (#987) + - Make pipeline runtime log with description (#970) + - Improve UI colors to have more contrast (#943) + - Add branches support for BitBucket (#907) + - Auto cancel blocked pipelines (#905) + - Allow to change forge status messages (#900) + - Added support for step errors when executing backend (#817) + - Do not filter on linux/amd64 per default (#805) +- DOCUMENTATION + - Remove never implemented "tag"-filter and document "ref"-filter to do the same (#1820) + - Define Glossary (#1800) + - Add more documentation about branch matching (#1186) + - Use versioned docs (#1145) + - Add gitpod setup (#1020) +- MISC + - Drop tarball release (#1819) + - Move helm charts to own repo "helm" (#1589) + - Replace yarn with pnpm (#1240) + - Publish preview docker images of pulls (#1072) ## [0.15.11](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.15.11) - 2023-07-12 -* SECURITY - * Update github.com/gin-gonic/gin to 1.9.1 (#1989) -* ENHANCEMENTS - * Allow gitea dev version (#914) (#1988) +- SECURITY + - Update github.com/gin-gonic/gin to 1.9.1 (#1989) +- ENHANCEMENTS + - Allow gitea dev version (#914) (#1988) ## [0.15.10](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.15.10) - 2023-07-09 -* SECURITY - * Fix agent auth (#1952) (#1953) - * Return after error (#1875) (#1876) - * Update github.com/docker/distribution (#1750) +- SECURITY + - Fix agent auth (#1952) (#1953) + - Return after error (#1875) (#1876) + - Update github.com/docker/distribution (#1750) ## [0.15.9](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.15.9) - 2023-05-11 -* SECURITY - * Backport securitycheck and bump deps where needed (#1745) +- SECURITY + - Backport securitycheck and bump deps where needed (#1745) ## [0.15.8](https://github.com/woodpecker-ci/woodpecker/releases/tag/0.15.8) - 2023-04-29 -* BUGFIXES - * Use codeberg.org/6543/go-yaml2json (#1719) - * Fix faulty hardlink in release tarball (#1669) (#1671) - * Persist `DepStatus` of tasks (#1610) (#1625) +- BUGFIXES + - Use codeberg.org/6543/go-yaml2json (#1719) + - Fix faulty hardlink in release tarball (#1669) (#1671) + - Persist `DepStatus` of tasks (#1610) (#1625) ## [0.15.7](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.15.7) - 2023-03-14 -* SECURITY - * Update dependencies golang/x libs (#1612) (#1621) -* BUGFIXES - * Docker backend should not close 'engine.Tail' result (#1616) (#1620) - * Force pure Go resolver onto server (#1502) (#1503) -* ENHANCEMENTS - * SanitizeParamKey "-" to "_" for plugin settings (#1511) -* MISC - * Bump xgo and go to v1.19.5 (#1538) (#1547) - * Pin official default clone image (#1526) (#1534) +- SECURITY + - Update dependencies golang/x libs (#1612) (#1621) +- BUGFIXES + - Docker backend should not close 'engine.Tail' result (#1616) (#1620) + - Force pure Go resolver onto server (#1502) (#1503) +- ENHANCEMENTS + - SanitizeParamKey "-" to "_" for plugin settings (#1511) +- MISC + - Bump xgo and go to v1.19.5 (#1538) (#1547) + - Pin official default clone image (#1526) (#1534) ## [0.15.6](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.15.6) - 2022-12-23 -* SECURITY - * Update golang.org/x/net (#1494) - * [**BREAKING**] Disable metrics access if no token is set (#1469) (#1470) - * Update dep moby (#1263) (#1264) -* BUGFIXES - * Update json schema for cli lint to cover valid cases (#1384) - * Add pipeline.step.when.branch string-array type to schema.json (#1380) - * Display system CA error only if there is an error (#870) (#1286) -* ENHANCEMENTS - * Bump Frontend Deps and remove unused (#1404) +- SECURITY + - Update golang.org/x/net (#1494) + - [**BREAKING**] Disable metrics access if no token is set (#1469) (#1470) + - Update dep moby (#1263) (#1264) +- BUGFIXES + - Update json schema for cli lint to cover valid cases (#1384) + - Add pipeline.step.when.branch string-array type to schema.json (#1380) + - Display system CA error only if there is an error (#870) (#1286) +- ENHANCEMENTS + - Bump Frontend Deps and remove unused (#1404) ## [0.15.5](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.15.5) - 2022-10-13 -* BUGFIXES - * Change build message column type to text (#1252) (#1253) -* ENHANCEMENTS - * Bump DefaultCloneImage version to v1.6.0 (#1254) - * On Repo update, keep old "Clone" if update would empty it (#1170) (#1195) +- BUGFIXES + - Change build message column type to text (#1252) (#1253) +- ENHANCEMENTS + - Bump DefaultCloneImage version to v1.6.0 (#1254) + - On Repo update, keep old "Clone" if update would empty it (#1170) (#1195) ## [0.15.4](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.15.4) - 2022-09-06 -* BUGFIXES - * Extract commit message from branch creation (#1150) (#1153) - * Respect WOODPECKER_GITEA_SKIP_VERIFY (#1152) (#1151) - * update golang.org/x/crypto (#1124) - * Implement Refresher for GitLab (#1031) (#1120) - * Make returned proc list to be returned always in correct order (#1060) (#1065) - * Update type of 'log_data' from blob to longblob (#1050) (#1052) - * Make ListItem component more accessible by using a button tag when clickable (#1044) (#1046) -* MISC - * Update base images (#1024) (#1025) +- BUGFIXES + - Extract commit message from branch creation (#1150) (#1153) + - Respect WOODPECKER_GITEA_SKIP_VERIFY (#1152) (#1151) + - update golang.org/x/crypto (#1124) + - Implement Refresher for GitLab (#1031) (#1120) + - Make returned proc list to be returned always in correct order (#1060) (#1065) + - Update type of 'log_data' from blob to longblob (#1050) (#1052) + - Make ListItem component more accessible by using a button tag when clickable (#1044) (#1046) +- MISC + - Update base images (#1024) (#1025) ## [0.15.3](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.15.3) - 2022-06-16 -* SECURITY - * Update github.com/containerd/containerd (#978) (#980) -* BUGFIXES - * Return to page after clicking login at navbar (#975) (#976) +- SECURITY + - Update github.com/containerd/containerd (#978) (#980) +- BUGFIXES + - Return to page after clicking login at navbar (#975) (#976) ## [0.15.2](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.15.2) - 2022-06-14 -* BUGFIXES - * Fix uppercase from_secrets (#842) (#925) - * Fix key/val format for dind env vars (#889) (#890) - * Update helm chart releasing (#882) (#888) -* DOCUMENTATION - * Fix run_on references with runs_on in docs (#965) +- BUGFIXES + - Fix uppercase from_secrets (#842) (#925) + - Fix key/val format for dind env vars (#889) (#890) + - Update helm chart releasing (#882) (#888) +- DOCUMENTATION + - Fix run_on references with runs_on in docs (#965) ## [0.15.1](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.15.1) - 2022-04-13 -* SECURITY - * Escape html / xml in log view (#879) (#880) -* FEATURES - * Build multiarch images for server (#821) (#822) -* BUGFIXES - * Branch list enhancements (#808) (#809) - * Get Netrc machine from clone url (#800) (#803) +- SECURITY + - Escape html / xml in log view (#879) (#880) +- FEATURES + - Build multiarch images for server (#821) (#822) +- BUGFIXES + - Branch list enhancements (#808) (#809) + - Get Netrc machine from clone url (#800) (#803) ## [v0.15.0](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.15.0) - 2022-02-24 -* BREAKING - * Change paths to use woodpecker instead of drone (#494) - * Move plugin config to root.pipeline.[step].settings (#464) - * Replace debug with log-level flag (#440) - * Change prometheus metrics from `drone_*` to `woodpecker_*` (#439) - * Replace DRONE_ with CI_ variables in pipeline steps (#427) - * Enable pull_request hook by default on repository activation (#420) - * Remote Gitea drop basic auth support (#365) - * Change pipeline config path resolution (#299) - * Remove push, tag and deployment webhook filters (#281) - * Clean up config environment variables for server and agent (#218) -* SECURITY - * Add linter bidichk to prevent malicious utf8 chars (#516) -* FEATURES - * Show changed files of pipeline in UI (#650) - * Show yml config of pipeline in UI (#649) - * Multiarch build for cli and agent docker images (#634), (#622) - * Get secrets in settings (#604) - * Add multi-pipeline support to exec & lint (#568) - * Add repo branches endpoint (#481) - * Add repo permission endpoint (#436) - * Add web-config endpoint (#433) - * Replace www-path with www-proxy option for development (#248) -* BUGFIXES - * Make gRPC error "too many keepalive pings" only show up in trace logs (#787) - * WOODPECKER_ENVIRONMENT: ignore items only containing a key and no value (#781) - * Fix pipeline timestamps (#730) - * Remove "panic()" as much as possible from code (#682) - * Send decline events back to UI (#680) - * Notice all changed files of all related commits for gitea push webhooks (#675) - * Use global branch filter only on events containing branch info (#659) - * API GetRepos() return empty list if no active repos exist (#658) - * Skip nested GitLab repositories during sync (#656), (#652) - * Build proc tree function should not depend on sorted procs list (#647) - * Fix sqlite migration on column drop of abnormal schemas (#629) - * Fix gRPC incompatibility in helm chart (#627) - * Fix new pipeline not published to UI if protected repo mode enabled (#619) - * Dont panic, report error back (#582) - * Improve status updates (#561) - * Let normal repo admins change timeout to lower values (#543) - * Fix registry delete (#532) - * Fix overflowing commit messages (#528) - * Fix passing of netrc credentials to clone step (#492) - * Fix various typos (#416) - * Append trailing slash to default GH API URL (#411) - * Fix filter pipeline config files (#279) -* ENHANCEMENTS - * Return better error if repo was deleted/renamed (#780) - * Add support to set default clone image via environment variable (#769) - * Add flag to always authenticate when cloning public repositories from locked down / private only forges (#760) - * UI: show date time on hover over time items (#756) - * Add repo-link to badge markdown in UI (#753) - * Allow specifying dind container in values (#750) - * Add page to view all projects of a user / group (#741) - * Let non required migration tasks fail and continue (#729) - * Improve pipeline compiler (#699) - * Support ChangedFiles for GitHub & Gitlab PRs and pushes and Gitea pushes (#697) - * Remove unused flags / options (#693) - * Automatically determine platform of agent (#690) - * Build ref link point to commit not compare if only one commit was pushed (#673) - * Hide multi line secrets from log (#671) - * Do not exclude repo owner from gated rule (#641) - * Add field for image list in Secrets Repo Settings (Web UI) (#638) - * Use Woodpecker theme colors on Safari Tab Bar / Header Bar (#632) - * Add "woodpeckerci/plugin-docker-buildx" to privileged plugins (#623) - * Use gitlab generic webhooks instead of drone-ci-service (#620) - * Calculate build number on creation (#615) - * Hide gin routes logging on non-debug starts (#603) - * Let remove be a remove (#593) - * Add flag to set oauth redirect host in dev mode (#586) - * Add log-level option to cli (#584) - * Improve favicons (#576) - * Show icon and index of a pull request in pipelines triggered by pull requests (#575) - * Improve secrets tab (#574) - * Use monospace font for build logs (#527) - * Show environ in every BuildProc (#526) - * Drop error only on purpose or else report back or log (#514) - * Migrate database backend to Xorm (#474) - * Add backend selection for agent (#463) - * Switch default git plugin (#449) - * Add log level API (#444) - * Move entirely to zerolog (#426) - * Pass context.Context down (#371) - * Extend Logging & Report to WebHook Caller back if pulls are disabled (#369) - * If config is no file assume its a folder (#354) - * Rename cmd agent and server folders and binaries (#330) - * Release Helm charts (#302) - * Add flag for specific grpc server addr (#295) - * Add option to charts, to pass in topology pod constraints (#262) - * Use server-host as source for public links and warn if it is set to localhost (#251) - * Rewrite of UI (#245) -* REFACTOR - * Remove github.com/kr/pretty in favor of assert.EqualValues() (#564) - * Simplify web router code (#541) - * Server obtain remote from glob config not from context (#540) - * Serve index.html directly without template (#539) - * Add linter revive, unused, ineffassign, varcheck, structcheck, staticcheck, whitespace, misspell (#550), (#551), (#554), (#538), (#537), (#535), (#531), (#530) - * Rename struct field and add new types into server/model's (#523) - * Update database in one transaction on syncing user repositories (#513) - * Format code with 'simplify' flag and check via CI (#509) - * Use Goblin Assert as intended (#501) - * Embedding libcompose types for yaml parsing (#495) - * Use std method to get SystemCertPool (#488) - * Upgrade urfave/cli to v2 (#483) - * Remove some wrapper and make code more readable (#478) - * More logging and refactor (#457) - * Simplify routes (#437) - * Move api-routes to separate file (#434) - * Rename drone-go to woodpecker-go (#390) - * Remove ghodss/yaml (#384) - * Move model/ to server/model/ (#366) - * Use moby definitions for docker pipeline backend (#364) - * Rewrite Gitlab Remote (#358) - * Update Generated Proto Code (#351) - * Remove legacy/unused code + misc cleanups (#331) - * CLI use version from version/version.go (#329) - * Move cli/drone/ to cli/ (#329) - * Cleanup Code (#348) - * Move cncd/pipeline/pipeline/ to pipeline/ (#347) - * Move cncd/{logging,pubsub,queue}/ to server/{logging,pubsub,queue}/ (#346) - * Move remote/ to server/remote/ (#344) - * Move plugins/ to server/plugins/ (#343) - * Move store/ to server/store/ (#341) - * Move router/ to server/router/ (#339) - * Create agent/ package for backend agnostic logic (#338) - * Reorganize into server/{api,grpc,shared} packages (#337) -* TESTING - * Add tests framework for storage migration (#630) - * Add more golangci-lint linters & sort them (#499) (#502) - * Compile on pull too (#287) -* DOCUMENTATION - * Add note about Gitlab & Gitea internal connections to docs (#711) - * Add registries docs (#679) - * Add documentation of all agent configuration options (#667) - * Add `repo` to `when` block (#642) - * Add development docs (#610) - * Clarify Docs on Docker for new users in intro (#606) - * Update Documentation (fix diffs and add settings) (#569) - * Add notice of supported YAML versions in docs (#556) - * Update Agent and Pipeline syntax documentation (#506) - * Update docs about selecting agent based on platform (#470) - * Add plugin marketplace (for official plugins) (#451) - * Add search to docs (#448) - * Add image migration docs (#406) - * Add security policy (#396) - * Explain open registration setting (#361) - * Add json schema and cli lint command (#342) - * Improve docs deployment (#333) - * Improve plugin docs (#313) - * Add Support section to README (#310) - * Community Guide (#296) - * Migrate docs framework to Docusaurus (#282) - * Use woodpecker env variable instead of drone in docker-compose (#264) -* MISC - * Add support for building in docker (#759) - * Compile for more platforms on release (#703) - * Build agent for multiple platforms (arm, arm64, amd64, linux, windows, darwin) (#408) - * Release deb, rpm bundles (#405) - * Release cli images (#404) - * Publish alpine container (#398) - * Migrate go-docker to docker/docker (#363) - * Use go's vendoring (#284) +- BREAKING + - Change paths to use woodpecker instead of drone (#494) + - Move plugin config to root.pipeline.[step].settings (#464) + - Replace debug with log-level flag (#440) + - Change prometheus metrics from `drone_*` to `woodpecker_*` (#439) + - Replace DRONE_with CI_ variables in pipeline steps (#427) + - Enable pull_request hook by default on repository activation (#420) + - Remote Gitea drop basic auth support (#365) + - Change pipeline config path resolution (#299) + - Remove push, tag and deployment webhook filters (#281) + - Clean up config environment variables for server and agent (#218) +- SECURITY + - Add linter bidichk to prevent malicious utf8 chars (#516) +- FEATURES + - Show changed files of pipeline in UI (#650) + - Show yml config of pipeline in UI (#649) + - Multiarch build for cli and agent docker images (#634), (#622) + - Get secrets in settings (#604) + - Add multi-pipeline support to exec & lint (#568) + - Add repo branches endpoint (#481) + - Add repo permission endpoint (#436) + - Add web-config endpoint (#433) + - Replace www-path with www-proxy option for development (#248) +- BUGFIXES + - Make gRPC error "too many keepalive pings" only show up in trace logs (#787) + - WOODPECKER_ENVIRONMENT: ignore items only containing a key and no value (#781) + - Fix pipeline timestamps (#730) + - Remove "panic()" as much as possible from code (#682) + - Send decline events back to UI (#680) + - Notice all changed files of all related commits for gitea push webhooks (#675) + - Use global branch filter only on events containing branch info (#659) + - API GetRepos() return empty list if no active repos exist (#658) + - Skip nested GitLab repositories during sync (#656), (#652) + - Build proc tree function should not depend on sorted procs list (#647) + - Fix sqlite migration on column drop of abnormal schemas (#629) + - Fix gRPC incompatibility in helm chart (#627) + - Fix new pipeline not published to UI if protected repo mode enabled (#619) + - Dont panic, report error back (#582) + - Improve status updates (#561) + - Let normal repo admins change timeout to lower values (#543) + - Fix registry delete (#532) + - Fix overflowing commit messages (#528) + - Fix passing of netrc credentials to clone step (#492) + - Fix various typos (#416) + - Append trailing slash to default GH API URL (#411) + - Fix filter pipeline config files (#279) +- ENHANCEMENTS + - Return better error if repo was deleted/renamed (#780) + - Add support to set default clone image via environment variable (#769) + - Add flag to always authenticate when cloning public repositories from locked down / private only forges (#760) + - UI: show date time on hover over time items (#756) + - Add repo-link to badge markdown in UI (#753) + - Allow specifying dind container in values (#750) + - Add page to view all projects of a user / group (#741) + - Let non required migration tasks fail and continue (#729) + - Improve pipeline compiler (#699) + - Support ChangedFiles for GitHub & Gitlab PRs and pushes and Gitea pushes (#697) + - Remove unused flags / options (#693) + - Automatically determine platform of agent (#690) + - Build ref link point to commit not compare if only one commit was pushed (#673) + - Hide multi line secrets from log (#671) + - Do not exclude repo owner from gated rule (#641) + - Add field for image list in Secrets Repo Settings (Web UI) (#638) + - Use Woodpecker theme colors on Safari Tab Bar / Header Bar (#632) + - Add "woodpeckerci/plugin-docker-buildx" to privileged plugins (#623) + - Use gitlab generic webhooks instead of drone-ci-service (#620) + - Calculate build number on creation (#615) + - Hide gin routes logging on non-debug starts (#603) + - Let remove be a remove (#593) + - Add flag to set oauth redirect host in dev mode (#586) + - Add log-level option to cli (#584) + - Improve favicons (#576) + - Show icon and index of a pull request in pipelines triggered by pull requests (#575) + - Improve secrets tab (#574) + - Use monospace font for build logs (#527) + - Show environ in every BuildProc (#526) + - Drop error only on purpose or else report back or log (#514) + - Migrate database backend to Xorm (#474) + - Add backend selection for agent (#463) + - Switch default git plugin (#449) + - Add log level API (#444) + - Move entirely to zerolog (#426) + - Pass context.Context down (#371) + - Extend Logging & Report to WebHook Caller back if pulls are disabled (#369) + - If config is no file assume its a folder (#354) + - Rename cmd agent and server folders and binaries (#330) + - Release Helm charts (#302) + - Add flag for specific grpc server addr (#295) + - Add option to charts, to pass in topology pod constraints (#262) + - Use server-host as source for public links and warn if it is set to localhost (#251) + - Rewrite of UI (#245) +- REFACTOR + - Remove github.com/kr/pretty in favor of assert.EqualValues() (#564) + - Simplify web router code (#541) + - Server obtain remote from glob config not from context (#540) + - Serve index.html directly without template (#539) + - Add linter revive, unused, ineffassign, varcheck, structcheck, staticcheck, whitespace, misspell (#550), (#551), (#554), (#538), (#537), (#535), (#531), (#530) + - Rename struct field and add new types into server/model's (#523) + - Update database in one transaction on syncing user repositories (#513) + - Format code with 'simplify' flag and check via CI (#509) + - Use Goblin Assert as intended (#501) + - Embedding libcompose types for yaml parsing (#495) + - Use std method to get SystemCertPool (#488) + - Upgrade urfave/cli to v2 (#483) + - Remove some wrapper and make code more readable (#478) + - More logging and refactor (#457) + - Simplify routes (#437) + - Move api-routes to separate file (#434) + - Rename drone-go to woodpecker-go (#390) + - Remove ghodss/yaml (#384) + - Move model/ to server/model/ (#366) + - Use moby definitions for docker pipeline backend (#364) + - Rewrite Gitlab Remote (#358) + - Update Generated Proto Code (#351) + - Remove legacy/unused code + misc cleanups (#331) + - CLI use version from version/version.go (#329) + - Move cli/drone/ to cli/ (#329) + - Cleanup Code (#348) + - Move cncd/pipeline/pipeline/ to pipeline/ (#347) + - Move cncd/{logging,pubsub,queue}/ to server/{logging,pubsub,queue}/ (#346) + - Move remote/ to server/remote/ (#344) + - Move plugins/ to server/plugins/ (#343) + - Move store/ to server/store/ (#341) + - Move router/ to server/router/ (#339) + - Create agent/ package for backend agnostic logic (#338) + - Reorganize into server/{api,grpc,shared} packages (#337) +- TESTING + - Add tests framework for storage migration (#630) + - Add more golangci-lint linters & sort them (#499) (#502) + - Compile on pull too (#287) +- DOCUMENTATION + - Add note about Gitlab & Gitea internal connections to docs (#711) + - Add registries docs (#679) + - Add documentation of all agent configuration options (#667) + - Add `repo` to `when` block (#642) + - Add development docs (#610) + - Clarify Docs on Docker for new users in intro (#606) + - Update Documentation (fix diffs and add settings) (#569) + - Add notice of supported YAML versions in docs (#556) + - Update Agent and Pipeline syntax documentation (#506) + - Update docs about selecting agent based on platform (#470) + - Add plugin marketplace (for official plugins) (#451) + - Add search to docs (#448) + - Add image migration docs (#406) + - Add security policy (#396) + - Explain open registration setting (#361) + - Add json schema and cli lint command (#342) + - Improve docs deployment (#333) + - Improve plugin docs (#313) + - Add Support section to README (#310) + - Community Guide (#296) + - Migrate docs framework to Docusaurus (#282) + - Use woodpecker env variable instead of drone in docker-compose (#264) +- MISC + - Add support for building in docker (#759) + - Compile for more platforms on release (#703) + - Build agent for multiple platforms (arm, arm64, amd64, linux, windows, darwin) (#408) + - Release deb, rpm bundles (#405) + - Release cli images (#404) + - Publish alpine container (#398) + - Migrate go-docker to docker/docker (#363) + - Use go's vendoring (#284) ## [v0.14.4](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.14.4) - 2022-01-31 -* BUGFIXES - * Docker Images use golang image for ca-certificates (#608) +- BUGFIXES + - Docker Images use golang image for ca-certificates (#608) ## [v0.14.3](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.14.3) - 2021-10-30 -* BUGFIXES - * Add flag for not fetching permissions (FlatPermissions) (#491) - * Gitea use default branch (#480) (#482) - * Fix repo access (#476) (#477) -* ENHANCEMENTS - * Use go embed for web files and remove httptreemux (#382) (#489) +- BUGFIXES + - Add flag for not fetching permissions (FlatPermissions) (#491) + - Gitea use default branch (#480) (#482) + - Fix repo access (#476) (#477) +- ENHANCEMENTS + - Use go embed for web files and remove httptreemux (#382) (#489) ## [v0.14.2](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.14.2) - 2021-10-19 -* BUGFIXES - * Fix sanitizePath (#326) (aa4fa9aab3) - * Fix json tag for `Pos` at struct `Line` (#422) (#424) - * Fix channel buffer used with signal.Notify (#421) (#423) -* ENHANCEMENTS - * Support recursive glob for path conditions (#327) (#412) -* TESTING - * Add TestPipelineName to procBuilder_test.go (#461) (#455) +- BUGFIXES + - Fix sanitizePath (#326) (aa4fa9aab3) + - Fix json tag for `Pos` at struct `Line` (#422) (#424) + - Fix channel buffer used with signal.Notify (#421) (#423) +- ENHANCEMENTS + - Support recursive glob for path conditions (#327) (#412) +- TESTING + - Add TestPipelineName to procBuilder_test.go (#461) (#455) ## [v0.14.1](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.14.1) - 2021-09-21 -* SECURITY - * Migrate jwt token lib (#332) -* BUGFIXES - * Increase allowed length for user token in db (#328) - * Fix cli matrix filter (#311) - * Fix ignore pushes to tags for gitea (#289) - * Fix use custom config path to sanitize build names (#280) +- SECURITY + - Migrate jwt token lib (#332) +- BUGFIXES + - Increase allowed length for user token in db (#328) + - Fix cli matrix filter (#311) + - Fix ignore pushes to tags for gitea (#289) + - Fix use custom config path to sanitize build names (#280) ## [v0.14.0](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.14.0) - 2021-08-01 -* FEATURES - * Add OAuth2 Support for Gitea Remote (#226) - * Add support for path-prefix condition (#174) -* BUGFIXES - * Allow multi pipeline file to be named .drone.yml (#250) - * Fix release-server make target by build server with correct option (#237) - * Fix Gitea unable to login on 0.12.0+ with error "cannot authenticate user. 403 Forbidden" (#221) -* ENHANCEMENTS - * Update / Remove drone dependencies (#236) - * Add support to gitea remote for path-prefix condition (#235) - * Enable go vet for ci (#230) - * Enforce code format (#228) - * Add multi-pipeline to Gitea (#225) - * Move flag definitions into extra files (#215) - * Remove unused code in server (#213) - * Docs URL configuration (#206) - * Filter main branch (#205) - * Fix multi pipeline bug when a pipeline depends on two other pipelines (#201) - * Using configured server URL instead of obtained from request (#175) -* DOCUMENTATION - * Switch in docs to new docker hub image repo (#227) - * Use WOODPECKER_ env vars in docs (#211) - * Also show WOODPECKER_HOST and WOODPECKER_SERVER_HOST environment variables in log messages (#208) - * Move woodpecker to dedicated organisation on github (#202) -* MISC - * Add chart for installing woodpecker server and agent (#199) +- FEATURES + - Add OAuth2 Support for Gitea Remote (#226) + - Add support for path-prefix condition (#174) +- BUGFIXES + - Allow multi pipeline file to be named .drone.yml (#250) + - Fix release-server make target by build server with correct option (#237) + - Fix Gitea unable to login on 0.12.0+ with error "cannot authenticate user. 403 Forbidden" (#221) +- ENHANCEMENTS + - Update / Remove drone dependencies (#236) + - Add support to gitea remote for path-prefix condition (#235) + - Enable go vet for ci (#230) + - Enforce code format (#228) + - Add multi-pipeline to Gitea (#225) + - Move flag definitions into extra files (#215) + - Remove unused code in server (#213) + - Docs URL configuration (#206) + - Filter main branch (#205) + - Fix multi pipeline bug when a pipeline depends on two other pipelines (#201) + - Using configured server URL instead of obtained from request (#175) +- DOCUMENTATION + - Switch in docs to new docker hub image repo (#227) + - Use WOODPECKER_ env vars in docs (#211) + - Also show WOODPECKER_HOST and WOODPECKER_SERVER_HOST environment variables in log messages (#208) + - Move woodpecker to dedicated organisation on github (#202) +- MISC + - Add chart for installing woodpecker server and agent (#199) diff --git a/Makefile b/Makefile index 40062a47971..50dfe39c25b 100644 --- a/Makefile +++ b/Makefile @@ -63,6 +63,7 @@ else ##@ General +.PHONY: all all: help .PHONY: version @@ -167,6 +168,7 @@ test-ui: ui-dependencies ## Test UI code test-lib: ## Test lib code go test -race -cover -coverprofile coverage.out -timeout 30s $(shell go list ./... | grep -v '/cmd\|/agent\|/cli\|/server') +.PHONY: test test: test-agent test-server test-server-datastore test-cli test-lib test-ui ## Run all tests ##@ Build @@ -183,6 +185,7 @@ build-agent: ## Build agent build-cli: ## Build cli CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -ldflags '${LDFLAGS}' -o dist/woodpecker-cli${BIN_SUFFIX} github.com/woodpecker-ci/woodpecker/cmd/cli +.PHONY: build build: build-agent build-server build-cli ## Build all binaries release-frontend: build-frontend ## Build frontend @@ -250,6 +253,7 @@ release-checksums: ## Create checksums for all release files # generate shas for tar files (cd dist/; sha256sum *.* > checksums.txt) +.PHONY: release release: release-frontend release-server release-agent release-cli ## Release all binaries bundle-prepare: ## Prepare the bundles @@ -267,6 +271,7 @@ bundle-cli: bundle-prepare ## Create bundles for cli VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-cli.yml --target ./dist --packager deb VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-cli.yml --target ./dist --packager rpm +.PHONY: bundle bundle: bundle-agent bundle-server bundle-cli ## Create all bundles ##@ Docs diff --git a/README.md b/README.md index acd37ea0e26..3d76ddba9ba 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +# Woodpecker +

Woodpecker @@ -41,12 +43,13 @@ + + +


-# Woodpecker - -> Woodpecker is a community fork of the Drone CI system. +Woodpecker is a community fork of the Drone CI system. ![woodpecker](docs/docs/woodpecker.png) @@ -58,7 +61,7 @@ Please consider to donate and become a backer. 🙏 [[Become a backer](https://o ## 📖 Documentation -https://woodpecker-ci.org/ + ## ✨ Contribute diff --git a/SECURITY.md b/SECURITY.md index e8b2d95f258..2491fe0cc40 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,9 +1,9 @@ # Security -We take security seriously. +We take security seriously. If you discover a security issue, please bring it to their attention right away! -### Reporting a Vulnerability +## 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). diff --git a/cli/README.md b/cli/README.md index 005e7412bfd..9e2c7861dea 100644 --- a/cli/README.md +++ b/cli/README.md @@ -2,4 +2,4 @@ Command line client for the Woodpecker continuous integration server. -Please see the official documentation at https://woodpecker-ci.org/docs/cli +Please see the official documentation at diff --git a/docs/README.md b/docs/README.md index 822be20193d..673bfe22c2a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,13 +2,13 @@ This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. -### Installation +## Installation ```bash pnpm install ``` -### Local Development +## Local Development ```bash pnpm start @@ -16,7 +16,7 @@ pnpm start This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. -### Build +## Build ```bash pnpm build @@ -24,7 +24,7 @@ pnpm build This command generates static content into the `build` directory and can be served using any static contents hosting service. -### Deployment +## Deployment Deployment happen via [CI](https://github.com/woodpecker-ci/woodpecker/blob/d59fdb4602bfdd0d00078716ba61b05c02cbd1af/.woodpecker/docs.yml#L8-L30) to [woodpecker-ci.org](https://woodpecker-ci.org). diff --git a/docs/blog/2023-07-28-release-v1.0.0/index.md b/docs/blog/2023-07-28-release-v1.0.0/index.md index b5db8ec39f4..3388419f54a 100644 --- a/docs/blog/2023-07-28-release-v1.0.0/index.md +++ b/docs/blog/2023-07-28-release-v1.0.0/index.md @@ -16,12 +16,12 @@ It took us quite some time, but now we are sure it's ready, and you should reall -We've refactored a lot of code, so contributing to the codebase should be much easier. -Furthermore, a ton of bugs where addressed and various enhancements introduced, along with some highly anticipated features. +We've refactored a lot of code, so contributing to the codebase should be much easier. +Furthermore, a ton of bugs where addressed and various enhancements introduced, along with some highly anticipated features. With Woodpecker v1.0.0, you can now substantially improve and streamline your code pipelines, empowering you to automate and optimize workflows like never before. -## Some picked highlights: +## Some picked highlights ### Add Support for Cron Jobs @@ -31,33 +31,33 @@ Schedule pipelines to run at specified intervals or times, optimizing repetitive ### YAML Map Merge, Overrides, and Sequence Merge Support -With enhanced YAML support, managing complex configurations becomes a breeze. +With enhanced YAML support, managing complex configurations becomes a breeze. Merge maps, apply overrides, and sequence merging—all within your YAML files. This is providing more flexibility and control over your pipelines. [Read more](/docs/usage/advanced-yaml-syntax) ### Web-UI for Admins -Simplify administration tasks with Woodpecker's new Admin UI. +Simplify administration tasks with Woodpecker's new Admin UI. Effortlessly manage user accounts, agents, and tasks, including adding new agents or pausing the task queue for maintenance. ![Image of admin queue view](./admin_queue_ui.png) ### Localize Web-UI -Embrace internationalization by changing your locale in the user settings. -Interact with Woodpecker in the language of your choice, tailored to your preferences. +Embrace internationalization by changing your locale in the user settings. +Interact with Woodpecker in the language of your choice, tailored to your preferences. If your language is not available or only partially translated, consider contributing to our [Weblate](https://translate.woodpecker-ci.org/engage/woodpecker-ci/). ### Add `evaluate` to `when` Filter Enhance pipeline flexibility with the new "when evaluate" filter, enabling or disabling steps based on custom conditions. -Customize your workflows to dynamically respond to specific triggers and events. +Customize your workflows to dynamically respond to specific triggers and events. [Read more](/docs/usage/pipeline-syntax#evaluate) ### Global- and Organization-Secrets -Save time and effort by declaring secrets for your entire instance or organization. +Save time and effort by declaring secrets for your entire instance or organization. Simplify your workflow and securely manage sensitive information across projects. ![Image of settings view of org secrets](./org_secrets.png) diff --git a/docs/docs/20-usage/15-terminiology/architecture.svg b/docs/docs/20-usage/15-terminiology/architecture.svg index 45967fc92e9..b34e96fdd8a 100644 --- a/docs/docs/20-usage/15-terminiology/architecture.svg +++ b/docs/docs/20-usage/15-terminiology/architecture.svg @@ -1,6 +1,6 @@ - + - + - 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 ... \ No newline at end of file + 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/docs/20-usage/15-terminiology/pipeline-workflow-step.svg b/docs/docs/20-usage/15-terminiology/pipeline-workflow-step.svg index 555347d6037..4ea3aab0ac2 100644 --- a/docs/docs/20-usage/15-terminiology/pipeline-workflow-step.svg +++ b/docs/docs/20-usage/15-terminiology/pipeline-workflow-step.svg @@ -1,6 +1,6 @@ - + - + - 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 \ No newline at end of file + 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/docs/20-usage/20-workflow-syntax.md b/docs/docs/20-usage/20-workflow-syntax.md index fad2711c160..58c6bd5efc7 100644 --- a/docs/docs/20-usage/20-workflow-syntax.md +++ b/docs/docs/20-usage/20-workflow-syntax.md @@ -40,7 +40,7 @@ steps: Keep in mind the name is optional, if not added the steps will be numerated. -### Skip Commits +## 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. diff --git a/docs/docs/30-administration/00-deployment/00-overview.md b/docs/docs/30-administration/00-deployment/00-overview.md index 9e48d9d6ac6..d360abf62d3 100644 --- a/docs/docs/30-administration/00-deployment/00-overview.md +++ b/docs/docs/30-administration/00-deployment/00-overview.md @@ -60,7 +60,7 @@ A [Prometheus endpoint](../90-prometheus.md) is exposed. 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: https://example.org/woodpecker/), you can use the option [`WOODPECKER_ROOT_PATH`](../10-server-config.md#woodpecker_root_path). +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 diff --git a/docs/docs/30-administration/11-forges/20-github.md b/docs/docs/30-administration/11-forges/20-github.md index 367e7882036..088a841e7a7 100644 --- a/docs/docs/30-administration/11-forges/20-github.md +++ b/docs/docs/30-administration/11-forges/20-github.md @@ -21,7 +21,7 @@ Do not use a "GitHub App" instead of an Oauth2 app as the former will not work c - Name: An arbitrary name for your App - Homepage URL: The URL of your Woodpecker instance - Callback URL: `https:///authorize` -- (optional) Upload the Woodpecker Logo: https://avatars.githubusercontent.com/u/84780935?s=200&v=4 +- (optional) Upload the Woodpecker Logo: ## Client Secret Creation diff --git a/docs/docs/30-administration/40-encryption.md b/docs/docs/30-administration/40-encryption.md index cef0be4ab7b..93d8e9ac974 100644 --- a/docs/docs/30-administration/40-encryption.md +++ b/docs/docs/30-administration/40-encryption.md @@ -5,8 +5,8 @@ Secrets encryption is currently broken and therefore disabled by default. It wil Check: -- https://github.com/woodpecker-ci/woodpecker/issues/1541 and -- https://github.com/woodpecker-ci/woodpecker/pull/2300 +- and +- ::: diff --git a/docs/docs/30-administration/90-prometheus.md b/docs/docs/30-administration/90-prometheus.md index cb05bf5671c..769a0c6025b 100644 --- a/docs/docs/30-administration/90-prometheus.md +++ b/docs/docs/30-administration/90-prometheus.md @@ -52,7 +52,7 @@ Alternatively, the unprotected `/metrics` endpoint might be exposed on the inter 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 diff --git a/docs/docs/92-development/01-getting-started.md b/docs/docs/92-development/01-getting-started.md index 3c700b2bc2b..3866d57634c 100644 --- a/docs/docs/92-development/01-getting-started.md +++ b/docs/docs/92-development/01-getting-started.md @@ -24,7 +24,7 @@ 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. (https://www.gnu.org/software/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: diff --git a/docs/docs/92-development/03-ui.md b/docs/docs/92-development/03-ui.md index 7bc13b1ee55..1fcf45ab469 100644 --- a/docs/docs/92-development/03-ui.md +++ b/docs/docs/92-development/03-ui.md @@ -33,7 +33,7 @@ The following list contains some tools and frameworks used by the Woodpecker UI. ## 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. +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/docs/92-development/08-swagger.md b/docs/docs/92-development/08-swagger.md index 32fd6e05904..28f4c23d0e6 100644 --- a/docs/docs/92-development/08-swagger.md +++ b/docs/docs/92-development/08-swagger.md @@ -11,23 +11,23 @@ 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 +## 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" +// @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) +// @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 @@ -35,7 +35,7 @@ Here's a typical example of how annotations for Swagger documentation look like. type User struct { ID int64 `json:"id" xorm:"pk autoincr 'user_id'"` // ... -} // @name User +} // @name User ``` These guidelines aim to have consistent wording in the swagger doc: @@ -48,11 +48,11 @@ These guidelines aim to have consistent wording in the swagger doc: - `@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 https://github.com/swaggo/swag/blob/main/README.md#declarative-comments-format +More enhanced information you can find here ### Manual code generation -##### generate the server's Go code containing the Swagger +#### generate the server's Go code containing the Swagger ```shell make generate-swagger @@ -73,5 +73,5 @@ 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 https://github.com/swaggo/swag/pull/1594 == once this is merged and released, the mentioned issue is obsolete. +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/docs/92-development/09-security.md b/docs/docs/92-development/09-security.md index e8b2d95f258..2491fe0cc40 100644 --- a/docs/docs/92-development/09-security.md +++ b/docs/docs/92-development/09-security.md @@ -1,9 +1,9 @@ # Security -We take security seriously. +We take security seriously. If you discover a security issue, please bring it to their attention right away! -### Reporting a Vulnerability +## 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). diff --git a/docs/docs/92-development/ui-proxy.svg b/docs/docs/92-development/ui-proxy.svg index 6ccb7445870..79809ffa197 100644 --- a/docs/docs/92-development/ui-proxy.svg +++ b/docs/docs/92-development/ui-proxy.svg @@ -1,6 +1,6 @@ - + - forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler) \ No newline at end of file + 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-0.15/20-usage/20-pipeline-syntax.md b/docs/versioned_docs/version-0.15/20-usage/20-pipeline-syntax.md index 17180da8cdd..a9d85a6437a 100644 --- a/docs/versioned_docs/version-0.15/20-usage/20-pipeline-syntax.md +++ b/docs/versioned_docs/version-0.15/20-usage/20-pipeline-syntax.md @@ -21,12 +21,12 @@ pipeline: In the above example we define two pipeline steps, `frontend` and `backend`. The names of these steps are completely arbitrary. - ## Global Pipeline Conditionals Woodpecker gives the ability to skip whole pipelines (not just steps) based on certain conditions. ### `branches` + Woodpecker can skip commits based on the target branch. If the branch matches the `branches:` block the pipeline is executed, otherwise it is skipped. Example skipping a commit when the target branch is not master: @@ -268,7 +268,7 @@ go test The above shell script is then executed as the docker entrypoint. The below docker command is an (incomplete) example of how the script is executed: -``` +```sh docker run --entrypoint=build.sh golang ``` @@ -338,7 +338,7 @@ For more details check the [service docs](./60-services.md#detachment). The workspace defines the shared volume and working directory shared by all pipeline steps. The default workspace matches the below pattern, based on your repository url. -``` +```sh /drone/src/github.com/octocat/hello-world ``` @@ -378,7 +378,7 @@ The base attribute defines a shared base volume available to all pipeline steps. This would be equivalent to the following docker commands: -``` +```sh docker volume create my-named-volume docker run --volume=my-named-volume:/go golang:latest diff --git a/docs/versioned_docs/version-0.15/20-usage/22-conditional-execution.md b/docs/versioned_docs/version-0.15/20-usage/22-conditional-execution.md index 81e5f009327..6703a09d61d 100644 --- a/docs/versioned_docs/version-0.15/20-usage/22-conditional-execution.md +++ b/docs/versioned_docs/version-0.15/20-usage/22-conditional-execution.md @@ -150,7 +150,7 @@ when: :::info This feature is currently only available for GitHub, GitLab and Gitea. -Pull requests aren't supported by gitea at the moment ([go-gitea/gitea#18228](https://github.com/go-gitea/gitea/pull/18228)). +Pull requests aren't supported by gitea at the moment ([go-gitea/gitea#18228](https://github.com/go-gitea/gitea/pull/18228)). Path conditions are ignored for tag events. ::: @@ -171,4 +171,4 @@ when: ignore_message: "[ALL]" ``` -** Hint: ** Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions. +**Hint:** Passing a defined ignore-message like `[ALL]` inside the commit message will ignore all path conditions. diff --git a/docs/versioned_docs/version-0.15/20-usage/40-secrets.md b/docs/versioned_docs/version-0.15/20-usage/40-secrets.md index 195f3999a49..5b1898c0948 100644 --- a/docs/versioned_docs/version-0.15/20-usage/40-secrets.md +++ b/docs/versioned_docs/version-0.15/20-usage/40-secrets.md @@ -14,7 +14,7 @@ pipeline: + secrets: [ docker_username, docker_password ] ``` -Alternatively, you can get a `setting` from secrets using the `from_secret` syntax. +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 pipeline as `PLUGIN_TOKEN`. **NOTE:** the `from_secret` syntax only works with the newer `settings` block. @@ -28,7 +28,6 @@ pipeline: + from_secret: secret_token ``` - Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped. ```diff diff --git a/docs/versioned_docs/version-0.15/20-usage/71-project-settings.md b/docs/versioned_docs/version-0.15/20-usage/71-project-settings.md index 5173ff78a0a..b2c6ec6bb6e 100644 --- a/docs/versioned_docs/version-0.15/20-usage/71-project-settings.md +++ b/docs/versioned_docs/version-0.15/20-usage/71-project-settings.md @@ -33,4 +33,3 @@ You can change the visibility of your project by this setting. If a user has acc ## Timeout After this timeout a pipeline has to finish or will be treated as timed out. - diff --git a/docs/versioned_docs/version-0.15/30-administration/00-setup.md b/docs/versioned_docs/version-0.15/30-administration/00-setup.md index f00fa7a9719..1240a6db13b 100644 --- a/docs/versioned_docs/version-0.15/30-administration/00-setup.md +++ b/docs/versioned_docs/version-0.15/30-administration/00-setup.md @@ -1,6 +1,7 @@ # Setup A Woodpecker deployment consists of two parts: + - A server which is the heart of Woodpecker and ships the webinterface. - Next to one server you can deploy any number of agents which will run the pipelines. @@ -19,6 +20,7 @@ To find out more about the differences between the two releases, please read the ## Installation You can install Woodpecker on multiple ways: + - Using [docker-compose](#docker-compose) with the official [docker images](../80-downloads.md#docker-images) - By deploying to a [Kubernetes](./80-kubernetes.md) with manifests or Woodpeckers official Helm charts - Using [binaries](../80-downloads.md) diff --git a/docs/versioned_docs/version-0.15/30-administration/10-server-config.md b/docs/versioned_docs/version-0.15/30-administration/10-server-config.md index f279a7e8d5d..2b5478601d6 100644 --- a/docs/versioned_docs/version-0.15/30-administration/10-server-config.md +++ b/docs/versioned_docs/version-0.15/30-administration/10-server-config.md @@ -77,21 +77,25 @@ services: 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_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. @@ -99,11 +103,13 @@ Server fully qualified url of the user-facing hostname. Example: `WOODPECKER_HOST=http://woodpecker.example.org` ### `WOODPECKER_SERVER_ADDR` +> > Default: `:8000` Configures the HTTP listener port. ### `WOODPECKER_SERVER_CERT` +> > Default: empty Path to an SSL certificate used by the server to accept HTTPS requests. @@ -111,6 +117,7 @@ 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. @@ -118,17 +125,19 @@ Path to an SSL certificate key used by the server to accept HTTPS requests. Example: `WOODPECKER_SERVER_KEY=/path/to/key.pem` ### `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_ADMIN` +> > Default: empty Comma-separated list of admin accounts. @@ -136,6 +145,7 @@ Comma-separated list of admin accounts. Example: `WOODPECKER_ADMIN=user1,user2` ### `WOODPECKER_ORGS` +> > Default: empty Comma-separated list of approved organizations. @@ -143,6 +153,7 @@ Comma-separated list of approved organizations. Example: `org1,org2` ### `WOODPECKER_REPO_OWNERS` +> > Default: empty Comma-separated list of syncable repo owners. ??? @@ -150,26 +161,31 @@ Comma-separated list of syncable repo owners. ??? Example: `user1,user2` ### `WOODPECKER_OPEN` +> > Default: `false` Enable to allow user registration. ### `WOODPECKER_DOCS` +> > Default: `https://woodpecker-ci.org/` Link to documentation in the UI. ### `WOODPECKER_AUTHENTICATE_PUBLIC_REPOS` +> > Default: `false` Always use authentication to clone repositories even if they are public. Needed if the SCM requires to always authenticate as used by many companies. ### `WOODPECKER_DEFAULT_CLONE_IMAGE` +> > Default is defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/release/v0.15/shared/constant/constant.go) The default docker image to be used when cloning the repo ### `WOODPECKER_SESSION_EXPIRES` +> > Default: `72h` Configures the session expiration time. @@ -178,6 +194,7 @@ As long as the session is valid (until it expires or log-out), a user can log into Woodpecker, without re-authentication. ### `WOODPECKER_ESCALATE` +> > Default: `plugins/docker,plugins/gcr,plugins/ecr,woodpeckerci/plugin-docker,woodpeckerci/plugin-docker-buildx` Docker images to run in privileged mode. Only change if you are sure what you do! @@ -192,6 +209,7 @@ Example: `WOODPECKER_VOLUME=/path/on/host:/path/in/container:rw`| --> ### `WOODPECKER_DOCKER_CONFIG` +> > Default: empty Configures a specific private registry config for all pipelines. @@ -213,11 +231,13 @@ Example: `WOODPECKER_NETWORK=network1,network2` --> ### `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_KEEPALIVE_MIN_TIME` +> > Default: empty Server-side enforcement policy on the minimum amount of time a client should wait before sending a keepalive ping. @@ -225,16 +245,19 @@ Server-side enforcement policy on the minimum amount of time a client should wai 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 @@ -246,11 +269,13 @@ WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker? ``` ### `WOODPECKER_PROMETHEUS_AUTH_TOKEN` +> > Default: empty Token to secure the Prometheus metrics endpoint. ### `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. @@ -258,31 +283,37 @@ Context prefix Woodpecker will use to publish status messages to SCM. You probab --- ### `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. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/20-github.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/20-github.md index 6f8d41e2e0c..5d01dab99cb 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/20-github.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/20-github.md @@ -32,31 +32,37 @@ Please use this screenshot for reference: 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. This is used to authorize access. ### `WOODPECKER_GITHUB_SECRET` +> > Default: empty Configures the GitHub OAuth client secret. This is used to authorize access. ### `WOODPECKER_GITHUB_MERGE_REF` +> > Default: `true` TODO ### `WOODPECKER_GITHUB_SKIP_VERIFY` +> > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/30-gitea.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/30-gitea.md index 6f564d8352e..495a33b7a29 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/30-gitea.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/30-gitea.md @@ -25,41 +25,47 @@ services: 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 important 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_SECRET` +> > Default: empty Configures the Gitea OAuth client secret. This is used to authorize access. ### `WOODPECKER_GITEA_SKIP_VERIFY` +> > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/40-gitlab.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/40-gitlab.md index 14a5d01cce7..5bb88b0262b 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/40-gitlab.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/40-gitlab.md @@ -32,26 +32,31 @@ If you run the Woodpecker CI server on the same host as the GitLab instance, you 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_SECRET` +> > Default: empty Configures the GitLab OAuth client secret. This is used to authorize access. ### `WOODPECKER_GITLAB_SKIP_VERIFY` +> > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/50-bitbucket.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/50-bitbucket.md index 5065e2e3122..38e1a793241 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/50-bitbucket.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/50-bitbucket.md @@ -44,16 +44,19 @@ Webhooks:Read and Write 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 id. This is used to authorize access. ### `WOODPECKER_BITBUCKET_SECRET` +> > Default: empty Configures the Bitbucket OAuth client secret. This is used to authorize access. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/60-bitbucket_server.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/60-bitbucket_server.md index 58b24307ef3..1ab776f4e62 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/60-bitbucket_server.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/60-bitbucket_server.md @@ -94,48 +94,56 @@ Woodpecker uses `git+https` to clone repositories, however, Bitbucket Server doe You must register your application with Bitbucket Server in order to generate a consumer key. Navigate to your account settings and choose Applications from the menu, and click Register new application. Now copy & paste the text value from `/etc/bitbucket/key.pub` into the `Public Key` in the incoming link part of the application registration. -Please use http://woodpecker.mycompany.com/authorize as the Authorization callback URL. +Please use as the Authorization callback URL. ## 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_STASH` +> > Default: `false` Enables the Bitbucket Server driver. ### `WOODPECKER_STASH_URL` +> > Default: empty Configures the Bitbucket Server address. ### `WOODPECKER_STASH_CONSUMER_KEY` +> > Default: empty Configures your Bitbucket Server consumer key. ### `WOODPECKER_STASH_CONSUMER_RSA` +> > Default: empty Configures the path to your Bitbucket Server private key file. ### `WOODPECKER_STASH_CONSUMER_RSA_STRING` +> > Default: empty Configures your Bitbucket Server private key. ### `WOODPECKER_STASH_GIT_USERNAME` +> > Default: empty This username is used to authenticate and clone all private repositories. ### `WOODPECKER_STASH_GIT_PASSWORD` +> > Default: empty The password is used to authenticate and clone all private repositories. ### `WOODPECKER_STASH_SKIP_VERIFY` +> > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/70-gogs.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/70-gogs.md index a165bea6dec..3b815ec806e 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/70-gogs.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/70-gogs.md @@ -5,31 +5,37 @@ 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_GOGS` +> > Default: `false` Enables the Gogs driver. ### `WOODPECKER_GOGS_URL` +> > Default: `https://github.com` Configures the Gogs server address. ### `WOODPECKER_GOGS_GIT_USERNAME` +> > Default: empty This username is used to authenticate and clone all private repositories. ### `WOODPECKER_GOGS_GIT_PASSWORD` +> > Default: empty The password is used to authenticate and clone all private repositories. ### `WOODPECKER_GOGS_PRIVATE_MODE` +> > Default: `false` TODO ### `WOODPECKER_GOGS_SKIP_VERIFY` +> > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/80-coding.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/80-coding.md index 751c090205d..1e1546a810f 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/80-coding.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/80-coding.md @@ -5,46 +5,55 @@ 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_CODING` +> > Default: `false` Enables the Coding driver. ### `WOODPECKER_CODING_URL` +> > Default: `https://coding.net` Configures the Coding server address. ### `WOODPECKER_CODING_CLIENT` +> > Default: empty Configures the Coding OAuth client id. This is used to authorize access. ### `WOODPECKER_CODING_SECRET` +> > Default: empty Configures the Coding OAuth client secret. This is used to authorize access. ### `WOODPECKER_CODING_SCOPE` +> > Default: `user, project, project:depot` Comma-separated list of OAuth scopes. ### `WOODPECKER_CODING_GIT_MACHINE` +> > Default: `git.coding.net` TODO ### `WOODPECKER_CODING_GIT_USERNAME` +> > Default: empty This username is used to authenticate and clone all private repositories. ### `WOODPECKER_CODING_GIT_PASSWORD` +> > Default: empty The password is used to authenticate and clone all private repositories. ### `WOODPECKER_CODING_SKIP_VERIFY` +> > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md b/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md index cf3afae54ef..9c2a6a4685b 100644 --- a/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md +++ b/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md @@ -41,7 +41,7 @@ services: When building your pipelines as long as you have set the platform or filter, builds can be made to only run code on certain agents. -``` +```yaml - WOODPECKER_HOSTNAME=mycompany-ci-01.example.com - WOODPECKER_FILTER= ``` @@ -75,81 +75,96 @@ pipeline: See [Conditionals Pipeline](../20-usage/20-pipeline-syntax.md#step-when---conditional-execution) syntax for more - ## All agent configuration options Here is the full list of configuration options and their default variables. -#### `DOCKER_HOST` -> Default: empty + +### `DOCKER_HOST` +> +> Default: empty Point to an alternate socket file or host. For example, "unix:////run/podman/podman.sock" ### `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_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_MAX_PROCS` +> > Default: `1` Configures the number of parallel builds. ### `WOODPECKER_HEALTHCHECK` +> > Default: `true` Enable healthcheck endpoint. ### `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` or `docker`. diff --git a/docs/versioned_docs/version-0.15/30-administration/60-ssl.md b/docs/versioned_docs/version-0.15/30-administration/60-ssl.md index 4357e0ca736..9a0e8c799b1 100644 --- a/docs/versioned_docs/version-0.15/30-administration/60-ssl.md +++ b/docs/versioned_docs/version-0.15/30-administration/60-ssl.md @@ -3,7 +3,6 @@ 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. @@ -34,7 +33,7 @@ Note that Woodpecker uses the hostname from the `WOODPECKER_HOST` environment va Woodpecker writes the certificates to the below directory: -``` +```sh /var/lib/woodpecker/golang-autocert ``` diff --git a/docs/versioned_docs/version-0.15/30-administration/70-proxy.md b/docs/versioned_docs/version-0.15/30-administration/70-proxy.md index cd6381bfa1f..a2b7096ba6b 100644 --- a/docs/versioned_docs/version-0.15/30-administration/70-proxy.md +++ b/docs/versioned_docs/version-0.15/30-administration/70-proxy.md @@ -1,6 +1,7 @@ # Proxy ## Apache + This guide provides a brief overview for installing Woodpecker server behind the Apache2 webserver. This is an example configuration: ```nohighlight @@ -88,9 +89,10 @@ woodpecker.example.com { ``` ## Ngrok + After installing [ngrok](https://ngrok.com/), open a new console and run: -``` +```sh ngrok http 8000 ``` diff --git a/docs/versioned_docs/version-0.15/30-administration/80-kubernetes.md b/docs/versioned_docs/version-0.15/30-administration/80-kubernetes.md index 6132a51897a..7a0bf50f40d 100644 --- a/docs/versioned_docs/version-0.15/30-administration/80-kubernetes.md +++ b/docs/versioned_docs/version-0.15/30-administration/80-kubernetes.md @@ -56,6 +56,7 @@ Build step containers are started up within the agent pod. Warning: this approach requires `privileged` access. Also DinD's reputation hasn't been too high in the early days of Docker - this changed somewhat over time, and there are organizations succeeding with this approach. server.yaml + ```yaml apiVersion: apps/v1 kind: Deployment @@ -153,6 +154,7 @@ spec: ``` agent.yaml + ```yaml apiVersion: apps/v1 kind: Deployment @@ -210,4 +212,3 @@ spec: - name: sock-dir emptyDir: {} ``` - diff --git a/docs/versioned_docs/version-0.15/30-administration/90-prometheus.md b/docs/versioned_docs/version-0.15/30-administration/90-prometheus.md index 75d1aa1f49f..24761f5a6a4 100644 --- a/docs/versioned_docs/version-0.15/30-administration/90-prometheus.md +++ b/docs/versioned_docs/version-0.15/30-administration/90-prometheus.md @@ -34,7 +34,7 @@ scrape_configs: List of prometheus metrics specific to Woodpecker: -``` +```yaml # HELP woodpecker_build_count Build count. # TYPE woodpecker_build_count counter woodpecker_build_count{branch="master",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3 diff --git a/docs/versioned_docs/version-0.15/40-cli.md b/docs/versioned_docs/version-0.15/40-cli.md index ca62a6bbc0a..d9477013367 100644 --- a/docs/versioned_docs/version-0.15/40-cli.md +++ b/docs/versioned_docs/version-0.15/40-cli.md @@ -1,6 +1,7 @@ # CLI ```docker run --rm woodpeckerci/woodpecker-cli:v0.15``` + ```bash NAME: woodpecker-cli - command line utility diff --git a/docs/versioned_docs/version-0.15/80-downloads.md b/docs/versioned_docs/version-0.15/80-downloads.md index 4c22844a5df..cfc5f409aa3 100644 --- a/docs/versioned_docs/version-0.15/80-downloads.md +++ b/docs/versioned_docs/version-0.15/80-downloads.md @@ -13,10 +13,11 @@ To find out more about the differences between the two releases, please read the ## 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 latest patch version of a specific minor release (see [Semver](https://semver.org/lang/)) -* The `next` images are based on the current master branch and should not be used for production environments + +- The `latest` image is the latest stable release +- The `vX.X.X` images are stable releases +- The `vX.X` images are based on the latest patch version of a specific minor release (see [Semver](https://semver.org/lang/)) +- The `next` images are based on the current master branch and should not be used for production environments ``` bash # server diff --git a/docs/versioned_docs/version-0.15/91-migrations.md b/docs/versioned_docs/version-0.15/91-migrations.md index 8c4ca17856d..76858ad4590 100644 --- a/docs/versioned_docs/version-0.15/91-migrations.md +++ b/docs/versioned_docs/version-0.15/91-migrations.md @@ -54,6 +54,7 @@ Some versions need some changes to the server configuration or the pipeline conf - `drone.sqlite` -> `woodpecker.sqlite` - Plugin Settings moved into `settings` section: + ```diff pipeline: something: diff --git a/docs/versioned_docs/version-0.15/92-development/01-getting-started.md b/docs/versioned_docs/version-0.15/92-development/01-getting-started.md index df18218976d..fd187801bea 100644 --- a/docs/versioned_docs/version-0.15/92-development/01-getting-started.md +++ b/docs/versioned_docs/version-0.15/92-development/01-getting-started.md @@ -8,12 +8,13 @@ Install Golang (>=1.16) 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. (https://www.gnu.org/software/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` + +- 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 & Yarn diff --git a/docs/versioned_docs/version-0.15/92-development/03-ui.md b/docs/versioned_docs/version-0.15/92-development/03-ui.md index 9491a7160a9..d48b4dff7eb 100644 --- a/docs/versioned_docs/version-0.15/92-development/03-ui.md +++ b/docs/versioned_docs/version-0.15/92-development/03-ui.md @@ -3,6 +3,7 @@ To develop the UI you need to install [Node.js and Yarn](./01-getting-started.md#nodejs--yarn). 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 `yarn 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 `yarn 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. diff --git a/docs/versioned_docs/version-0.15/92-development/ui-proxy.svg b/docs/versioned_docs/version-0.15/92-development/ui-proxy.svg index 6ccb7445870..79809ffa197 100644 --- a/docs/versioned_docs/version-0.15/92-development/ui-proxy.svg +++ b/docs/versioned_docs/version-0.15/92-development/ui-proxy.svg @@ -1,6 +1,6 @@ - + - forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler) \ No newline at end of file + 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-1.0/20-usage/20-pipeline-syntax.md b/docs/versioned_docs/version-1.0/20-usage/20-pipeline-syntax.md index dd8bc6f555b..56484b39e2f 100644 --- a/docs/versioned_docs/version-1.0/20-usage/20-pipeline-syntax.md +++ b/docs/versioned_docs/version-1.0/20-usage/20-pipeline-syntax.md @@ -40,7 +40,7 @@ steps: Keep in mind the name is optional, if not added the steps will be numerated. -### Skip Commits +## Skip Commits Woodpecker gives the ability to skip individual commits by adding `[CI SKIP]` to the commit message. Note this is case-insensitive. @@ -122,7 +122,7 @@ Woodpecker does not automatically upgrade container images. Example configuratio + pull: true ``` -##### Images from private registries +#### Images from private registries You must provide registry credentials on the UI in order to pull private pipeline images defined in your YAML configuration file. diff --git a/docs/versioned_docs/version-1.0/20-usage/35-advanced-yaml-syntax.md b/docs/versioned_docs/version-1.0/20-usage/35-advanced-yaml-syntax.md index b5ea914c97b..8272ddb425d 100644 --- a/docs/versioned_docs/version-1.0/20-usage/35-advanced-yaml-syntax.md +++ b/docs/versioned_docs/version-1.0/20-usage/35-advanced-yaml-syntax.md @@ -5,6 +5,7 @@ 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: + ```yml steps: test: diff --git a/docs/versioned_docs/version-1.0/20-usage/40-secrets.md b/docs/versioned_docs/version-1.0/20-usage/40-secrets.md index 613a03fdb1e..bd4ea95021b 100644 --- a/docs/versioned_docs/version-1.0/20-usage/40-secrets.md +++ b/docs/versioned_docs/version-1.0/20-usage/40-secrets.md @@ -28,7 +28,6 @@ steps: + from_secret: secret_token ``` - Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped. ```diff diff --git a/docs/versioned_docs/version-1.0/20-usage/71-project-settings.md b/docs/versioned_docs/version-1.0/20-usage/71-project-settings.md index d65552182e9..319a07e6101 100644 --- a/docs/versioned_docs/version-1.0/20-usage/71-project-settings.md +++ b/docs/versioned_docs/version-1.0/20-usage/71-project-settings.md @@ -21,7 +21,7 @@ Enables handling webhook's pull request event. If disabled, then pipeline won't ### 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. +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 diff --git a/docs/versioned_docs/version-1.0/30-administration/00-setup.md b/docs/versioned_docs/version-1.0/30-administration/00-setup.md index a5dbb1c8a1a..4e66ab52d6c 100644 --- a/docs/versioned_docs/version-1.0/30-administration/00-setup.md +++ b/docs/versioned_docs/version-1.0/30-administration/00-setup.md @@ -192,4 +192,4 @@ A [Prometheus endpoint](./90-prometheus.md) is exposed. 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: https://example.org/woodpecker/), you can use the option [`WOODPECKER_ROOT_URL`](./10-server-config.md#woodpecker_root_url). +In the case you need to use Woodpecker with a URL path prefix (like: ), you can use the option [`WOODPECKER_ROOT_URL`](./10-server-config.md#woodpecker_root_url). diff --git a/docs/versioned_docs/version-1.0/30-administration/10-server-config.md b/docs/versioned_docs/version-1.0/30-administration/10-server-config.md index 9f86cb1c0e8..0e0698cfc98 100644 --- a/docs/versioned_docs/version-1.0/30-administration/10-server-config.md +++ b/docs/versioned_docs/version-1.0/30-administration/10-server-config.md @@ -20,9 +20,9 @@ services: + - 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 +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 @@ -153,7 +153,8 @@ 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 +### woodpecker.css + ```css .banner-message { position: absolute; @@ -168,7 +169,7 @@ The examples below show how to place a banner message in the top navigation bar } ``` -##### woodpecker.js +### woodpecker.js ```javascript // place/copy a minified version of jQuery or ZeptoJS here ... @@ -179,37 +180,42 @@ $().ready(function(){ }); ``` - ## 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_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. @@ -217,6 +223,7 @@ Server fully qualified URL of the user-facing hostname. Example: `WOODPECKER_HOST=http://woodpecker.example.org` ### `WOODPECKER_WEBHOOK_HOST` +> > Default: value from `WOODPECKER_HOST` config env Server fully qualified URL of the Webhook-facing hostname. @@ -224,16 +231,19 @@ Server fully qualified URL of the Webhook-facing hostname. 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. @@ -241,6 +251,7 @@ 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. @@ -248,6 +259,7 @@ 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. @@ -257,6 +269,7 @@ 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. @@ -266,26 +279,31 @@ 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. @@ -293,6 +311,7 @@ Configures an unprotected metrics endpoint. An empty value disables the metrics Example: `:9001` ### `WOODPECKER_ADMIN` +> > Default: empty Comma-separated list of admin accounts. @@ -300,6 +319,7 @@ Comma-separated list of admin accounts. Example: `WOODPECKER_ADMIN=user1,user2` ### `WOODPECKER_ORGS` +> > Default: empty Comma-separated list of approved organizations. @@ -307,6 +327,7 @@ Comma-separated list of approved organizations. Example: `org1,org2` ### `WOODPECKER_REPO_OWNERS` +> > Default: empty Comma-separated list of syncable repo owners. ??? @@ -314,41 +335,49 @@ Comma-separated list of syncable repo owners. ??? Example: `user1,user2` ### `WOODPECKER_OPEN` +> > Default: `false` Enable to allow user registration. ### `WOODPECKER_DOCS` +> > Default: `https://woodpecker-ci.org/` Link to documentation in the UI. ### `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/master/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. @@ -357,6 +386,7 @@ 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/master/shared/constant/constant.go) Docker images to run in privileged mode. Only change if you are sure what you do! @@ -371,6 +401,7 @@ Example: `WOODPECKER_VOLUME=/path/on/host:/path/in/container:rw`| --> ### `WOODPECKER_DOCKER_CONFIG` +> > Default: empty Configures a specific private registry config for all pipelines. @@ -392,16 +423,19 @@ Example: `WOODPECKER_NETWORK=network1,network2` --> ### `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. @@ -409,16 +443,19 @@ Server-side enforcement policy on the minimum amount of time a client should wai 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 @@ -430,47 +467,56 @@ WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker? ``` ### `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 }}` Template for the status messages published to forges, uses [Go templates](https://pkg.go.dev/text/template) as template language. @@ -485,50 +531,57 @@ Supported variables: --- ### `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_URL` +> > Default: `` Server URL path prefix (used for statics loading when having a url path prefix), should start with `/` diff --git a/docs/versioned_docs/version-1.0/30-administration/11-forges/20-github.md b/docs/versioned_docs/version-1.0/30-administration/11-forges/20-github.md index 9ed47580d05..a5a239b22a5 100644 --- a/docs/versioned_docs/version-1.0/30-administration/11-forges/20-github.md +++ b/docs/versioned_docs/version-1.0/30-administration/11-forges/20-github.md @@ -32,41 +32,49 @@ Please use this screenshot for reference: 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. This is used 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` TODO ### `WOODPECKER_GITHUB_SKIP_VERIFY` +> > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-1.0/30-administration/11-forges/30-gitea.md b/docs/versioned_docs/version-1.0/30-administration/11-forges/30-gitea.md index 24a500d3b3e..2e7e5c9a330 100644 --- a/docs/versioned_docs/version-1.0/30-administration/11-forges/30-gitea.md +++ b/docs/versioned_docs/version-1.0/30-administration/11-forges/30-gitea.md @@ -25,51 +25,59 @@ services: 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-1.0/30-administration/11-forges/40-gitlab.md b/docs/versioned_docs/version-1.0/30-administration/11-forges/40-gitlab.md index 46b40a0f1a4..e63fd905f8d 100644 --- a/docs/versioned_docs/version-1.0/30-administration/11-forges/40-gitlab.md +++ b/docs/versioned_docs/version-1.0/30-administration/11-forges/40-gitlab.md @@ -32,36 +32,43 @@ If you run the Woodpecker CI server on the same host as the GitLab instance, you 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-1.0/30-administration/11-forges/50-bitbucket.md b/docs/versioned_docs/version-1.0/30-administration/11-forges/50-bitbucket.md index 909da4d693f..b5064fd88ce 100644 --- a/docs/versioned_docs/version-1.0/30-administration/11-forges/50-bitbucket.md +++ b/docs/versioned_docs/version-1.0/30-administration/11-forges/50-bitbucket.md @@ -44,26 +44,31 @@ Webhooks:Read and Write 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 id. 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 diff --git a/docs/versioned_docs/version-1.0/30-administration/15-agent-config.md b/docs/versioned_docs/version-1.0/30-administration/15-agent-config.md index 94fb03f674a..c69f7d6b61d 100644 --- a/docs/versioned_docs/version-1.0/30-administration/15-agent-config.md +++ b/docs/versioned_docs/version-1.0/30-administration/15-agent-config.md @@ -76,91 +76,109 @@ At following startups Agent uses own token only. 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-pipeline-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`, `ssh` or `kubernetes`. diff --git a/docs/versioned_docs/version-1.0/30-administration/22-backends/10-docker.md b/docs/versioned_docs/version-1.0/30-administration/22-backends/10-docker.md index 8651d2594ef..37a29fd9041 100644 --- a/docs/versioned_docs/version-1.0/30-administration/22-backends/10-docker.md +++ b/docs/versioned_docs/version-1.0/30-administration/22-backends/10-docker.md @@ -5,16 +5,19 @@ This is the original backend used with Woodpecker. The docker backend executes e ## 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 diff --git a/docs/versioned_docs/version-1.0/30-administration/22-backends/20-local.md b/docs/versioned_docs/version-1.0/30-administration/22-backends/20-local.md index c8c5dbc4eb6..0368a9ad4fe 100644 --- a/docs/versioned_docs/version-1.0/30-administration/22-backends/20-local.md +++ b/docs/versioned_docs/version-1.0/30-administration/22-backends/20-local.md @@ -77,7 +77,6 @@ manual clone 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 @@ -115,4 +114,3 @@ labels: steps: [...] ``` - diff --git a/docs/versioned_docs/version-1.0/30-administration/22-backends/30-ssh.md b/docs/versioned_docs/version-1.0/30-administration/22-backends/30-ssh.md index 79e8dc998b1..edf15eca462 100644 --- a/docs/versioned_docs/version-1.0/30-administration/22-backends/30-ssh.md +++ b/docs/versioned_docs/version-1.0/30-administration/22-backends/30-ssh.md @@ -16,26 +16,31 @@ The backend will use a random directory in $TMPDIR to store the clone code and e ## Configuration ### `WOODPECKER_BACKEND_SSH_ADDRESS` +> > Default: empty The SSH host to run steps with `ssh` backend. ### `WOODPECKER_BACKEND_SSH_USER` +> > Default: empty The SSH user to run steps with `ssh` backend. ### `WOODPECKER_BACKEND_SSH_KEY` +> > Default: empty Path to the private SSH key to run steps with `ssh` backend. ### `WOODPECKER_BACKEND_SSH_KEY_PASSWORD` +> > Default: empty The password for the private key to run steps with `ssh` backend. ### `WOODPECKER_BACKEND_SSH_PASSWORD` +> > Default empty The SSH password to run steps with `ssh` backend. diff --git a/docs/versioned_docs/version-1.0/30-administration/22-backends/40-kubernetes.md b/docs/versioned_docs/version-1.0/30-administration/22-backends/40-kubernetes.md index 9ab79b7e6f2..32f55a49007 100644 --- a/docs/versioned_docs/version-1.0/30-administration/22-backends/40-kubernetes.md +++ b/docs/versioned_docs/version-1.0/30-administration/22-backends/40-kubernetes.md @@ -11,31 +11,37 @@ The kubernetes backend executes each step inside a newly created pod. A PVC is a ## Configuration ### `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"}`. @@ -59,6 +65,7 @@ By default the pod will use "kubernetes.io/arch" inferred from top-level "platfo See the [kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for more information on using nodeSelector. Example pipeline configuration: + ```yaml steps: build: diff --git a/docs/versioned_docs/version-1.0/30-administration/40-encryption.md b/docs/versioned_docs/version-1.0/30-administration/40-encryption.md index 78aab913044..f9f3132f425 100644 --- a/docs/versioned_docs/version-1.0/30-administration/40-encryption.md +++ b/docs/versioned_docs/version-1.0/30-administration/40-encryption.md @@ -1,6 +1,6 @@ # Secrets encryption -By default, Woodpecker does not encrypt secrets in its database. You can enable encryption +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 @@ -8,7 +8,7 @@ using simple AES key or more advanced [Google TINK](https://developers.google.co ### 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 +`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! @@ -22,39 +22,48 @@ 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 +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: + ```shell 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: + ```shell tinkey rotate-keyset --in keyset_v1.json --out keyset_v2.json --key-template AES256_GCM ``` diff --git a/docs/versioned_docs/version-1.0/30-administration/70-proxy.md b/docs/versioned_docs/version-1.0/30-administration/70-proxy.md index b57b93442f9..8c6ac2733a8 100644 --- a/docs/versioned_docs/version-1.0/30-administration/70-proxy.md +++ b/docs/versioned_docs/version-1.0/30-administration/70-proxy.md @@ -108,7 +108,6 @@ 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. diff --git a/docs/versioned_docs/version-1.0/30-administration/90-prometheus.md b/docs/versioned_docs/version-1.0/30-administration/90-prometheus.md index 78e00935173..f2d339b99c6 100644 --- a/docs/versioned_docs/version-1.0/30-administration/90-prometheus.md +++ b/docs/versioned_docs/version-1.0/30-administration/90-prometheus.md @@ -38,7 +38,7 @@ Alternatively, the unprotected `/metrics` endpoint might be exposed on the inter List of Prometheus metrics specific to Woodpecker: -``` +```yaml # HELP woodpecker_pipeline_count Pipeline count. # TYPE woodpecker_pipeline_count counter woodpecker_build_count{branch="master",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3 diff --git a/docs/versioned_docs/version-1.0/40-cli.md b/docs/versioned_docs/version-1.0/40-cli.md index 3f4b46c1e0d..bd38de512cb 100644 --- a/docs/versioned_docs/version-1.0/40-cli.md +++ b/docs/versioned_docs/version-1.0/40-cli.md @@ -1,14 +1,14 @@ # CLI -# NAME +## NAME woodpecker-cli - command line utility -# SYNOPSIS +## SYNOPSIS woodpecker-cli -``` +```sh [--log-level]=[value] [--server|-s]=[value] [--token|-t]=[value] @@ -16,11 +16,11 @@ woodpecker-cli **Usage**: -``` +```sh woodpecker-cli [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] ``` -# GLOBAL OPTIONS +## GLOBAL OPTIONS **--log-level**="": set logging level (default: info) @@ -28,8 +28,7 @@ woodpecker-cli [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] **--token, -t**="": server auth token - -# COMMANDS +## COMMANDS ## pipeline, build @@ -304,37 +303,37 @@ execute a local pipeline **--backend-ssh-user**="": backend ssh user -**--commit-author-avatar**="": +**--commit-author-avatar**="": -**--commit-author-email**="": +**--commit-author-email**="": -**--commit-author-name**="": +**--commit-author-name**="": -**--commit-branch**="": +**--commit-branch**="": -**--commit-message**="": +**--commit-message**="": -**--commit-ref**="": +**--commit-ref**="": -**--commit-refspec**="": +**--commit-refspec**="": -**--commit-sha**="": +**--commit-sha**="": -**--env**="": +**--env**="": -**--forge-type**="": +**--forge-type**="": -**--forge-url**="": +**--forge-url**="": **--local**: run from local directory **--log-level**="": set logging level (default: info) -**--netrc-machine**="": +**--netrc-machine**="": -**--netrc-password**="": +**--netrc-password**="": -**--netrc-username**="": +**--netrc-username**="": **--network**="": external networks @@ -344,7 +343,7 @@ execute a local pipeline **--pipeline-finished**="": (default: 0) -**--pipeline-link**="": +**--pipeline-link**="": **--pipeline-number**="": (default: 0) @@ -352,63 +351,63 @@ execute a local pipeline **--pipeline-started**="": (default: 0) -**--pipeline-status**="": +**--pipeline-status**="": -**--pipeline-target**="": +**--pipeline-target**="": -**--prev-commit-author-avatar**="": +**--prev-commit-author-avatar**="": -**--prev-commit-author-email**="": +**--prev-commit-author-email**="": -**--prev-commit-author-name**="": +**--prev-commit-author-name**="": -**--prev-commit-branch**="": +**--prev-commit-branch**="": -**--prev-commit-message**="": +**--prev-commit-message**="": -**--prev-commit-ref**="": +**--prev-commit-ref**="": -**--prev-commit-refspec**="": +**--prev-commit-refspec**="": -**--prev-commit-sha**="": +**--prev-commit-sha**="": **--prev-pipeline-created**="": (default: 0) -**--prev-pipeline-event**="": +**--prev-pipeline-event**="": **--prev-pipeline-finished**="": (default: 0) -**--prev-pipeline-link**="": +**--prev-pipeline-link**="": **--prev-pipeline-number**="": (default: 0) **--prev-pipeline-started**="": (default: 0) -**--prev-pipeline-status**="": +**--prev-pipeline-status**="": **--privileged**="": privileged plugins (default: "plugins/docker", "plugins/gcr", "plugins/ecr", "woodpeckerci/plugin-docker-buildx") **--repo**="": full repo name -**--repo-clone-url**="": +**--repo-clone-url**="": -**--repo-link**="": +**--repo-link**="": -**--repo-private**="": +**--repo-private**="": -**--repo-remote-id**="": +**--repo-remote-id**="": -**--repo-trusted**: +**--repo-trusted**: **--server, -s**="": server address **--step-name**="": (default: 0) -**--system-link**="": (default: https://github.com/woodpecker-ci/woodpecker) +**--system-link**="": (default: ) **--system-name**="": (default: woodpecker) -**--system-platform**="": +**--system-platform**="": **--timeout**="": pipeline timeout (default: 0s) diff --git a/docs/versioned_docs/version-1.0/92-development/01-getting-started.md b/docs/versioned_docs/version-1.0/92-development/01-getting-started.md index d5f229ae035..3866d57634c 100644 --- a/docs/versioned_docs/version-1.0/92-development/01-getting-started.md +++ b/docs/versioned_docs/version-1.0/92-development/01-getting-started.md @@ -24,12 +24,13 @@ 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. (https://www.gnu.org/software/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` + +- 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 diff --git a/docs/versioned_docs/version-1.0/92-development/03-ui.md b/docs/versioned_docs/version-1.0/92-development/03-ui.md index b2a12484723..5affaed6100 100644 --- a/docs/versioned_docs/version-1.0/92-development/03-ui.md +++ b/docs/versioned_docs/version-1.0/92-development/03-ui.md @@ -3,6 +3,7 @@ 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. @@ -32,7 +33,7 @@ The following list contains some tools and frameworks used by the Woodpecker UI. ## 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. +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 master branch yet) For more information about translations see [Translations](./07-translations.md). diff --git a/docs/versioned_docs/version-1.0/92-development/05-architecture.md b/docs/versioned_docs/version-1.0/92-development/05-architecture.md index d0093e24a28..8f3c15ca769 100644 --- a/docs/versioned_docs/version-1.0/92-development/05-architecture.md +++ b/docs/versioned_docs/version-1.0/92-development/05-architecture.md @@ -37,7 +37,7 @@ | `server/shared/**` | TODO: move and split [#974](https://github.com/woodpecker-ci/woodpecker/issues/974) | | `server/web/**` | server SPA | -* `../` = `server/` +- `../` = `server/` ### Agent diff --git a/docs/versioned_docs/version-1.0/92-development/08-swagger.md b/docs/versioned_docs/version-1.0/92-development/08-swagger.md index 6d8d99f6fb5..2c8871b8ec0 100644 --- a/docs/versioned_docs/version-1.0/92-development/08-swagger.md +++ b/docs/versioned_docs/version-1.0/92-development/08-swagger.md @@ -11,23 +11,23 @@ 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 +## 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" +// @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) +// @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 @@ -35,35 +35,36 @@ Here's a typical example of how annotations for Swagger documentation look like. type User struct { ID int64 `json:"id" xorm:"pk autoincr 'user_id'"` // ... -} // @name User +} // @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 + +- 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 https://github.com/swaggo/swag/blob/master/README.md#declarative-comments-format +More enhanced information you can find here ### Manual code generation -##### generate the server's Go code containing the Swagger +#### generate the server's Go code containing the Swagger ```shell make generate-swagger ``` -##### update the Markdown in the ./docs folder +#### update the Markdown in the ./docs folder ```shell make docs ``` -##### auto-format swagger related godoc +#### auto-format swagger related godoc ```shell go run github.com/swaggo/swag/cmd/swag@latest fmt -g server/api/z.go @@ -72,5 +73,5 @@ 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 https://github.com/swaggo/swag/pull/1594 == once this is merged and released, the mentioned issue is obsolete. +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-1.0/92-development/09-security.md b/docs/versioned_docs/version-1.0/92-development/09-security.md index e8b2d95f258..2491fe0cc40 100644 --- a/docs/versioned_docs/version-1.0/92-development/09-security.md +++ b/docs/versioned_docs/version-1.0/92-development/09-security.md @@ -1,9 +1,9 @@ # Security -We take security seriously. +We take security seriously. If you discover a security issue, please bring it to their attention right away! -### Reporting a Vulnerability +## 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). diff --git a/docs/versioned_docs/version-1.0/92-development/ui-proxy.svg b/docs/versioned_docs/version-1.0/92-development/ui-proxy.svg index 6ccb7445870..79809ffa197 100644 --- a/docs/versioned_docs/version-1.0/92-development/ui-proxy.svg +++ b/docs/versioned_docs/version-1.0/92-development/ui-proxy.svg @@ -1,6 +1,6 @@ - + - forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler) \ No newline at end of file + forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler) diff --git a/pipeline/samples/sample_1/README.md b/pipeline/samples/sample_1/README.md index 02534cdfb5f..0cf3536c639 100644 --- a/pipeline/samples/sample_1/README.md +++ b/pipeline/samples/sample_1/README.md @@ -1,11 +1,13 @@ +# Example + Compile the yaml to the intermediate representation: -``` +```sh pipec compile ``` Execute the intermediate representation: -``` +```sh pipec exec ``` diff --git a/pipeline/samples/sample_10_windows/README.md b/pipeline/samples/sample_10_windows/README.md index 0564f06ab5b..7e5e872d8a3 100644 --- a/pipeline/samples/sample_10_windows/README.md +++ b/pipeline/samples/sample_10_windows/README.md @@ -1,11 +1,13 @@ +# Example + Compile the yaml to the intermediate representation: -``` +```sh pipec compile --system-arch windows/amd64 ``` Execute the intermediate representation: -``` +```sh pipec exec ``` diff --git a/pipeline/samples/sample_8_network_mode/README.md b/pipeline/samples/sample_8_network_mode/README.md index fe8ef97d8cf..47896db6c3a 100644 --- a/pipeline/samples/sample_8_network_mode/README.md +++ b/pipeline/samples/sample_8_network_mode/README.md @@ -1,12 +1,14 @@ +# Example + Compile the yaml to the intermediate representation: -``` +```sh pipec compile ``` Execute the intermediate representation: -``` +```sh pipec exec ``` @@ -15,4 +17,4 @@ by other container. This is useful for example to allow the CI to connect with s behind a VPN. Before to start you need to create a container that connects to the VPN (using one of -the openvpn client images like https://github.com/ekristen/docker-openvpn-client). +the openvpn client images like ). diff --git a/web/public/favicons/favicon-dark-error.svg b/web/public/favicons/favicon-dark-error.svg index 334808ae247..8ad3722c66d 100644 --- a/web/public/favicons/favicon-dark-error.svg +++ b/web/public/favicons/favicon-dark-error.svg @@ -1 +1 @@ - \ No newline at end of file + diff --git a/web/public/favicons/favicon-dark-pending.svg b/web/public/favicons/favicon-dark-pending.svg index efa389fa1b6..d6fb79becf6 100644 --- a/web/public/favicons/favicon-dark-pending.svg +++ b/web/public/favicons/favicon-dark-pending.svg @@ -1 +1 @@ - \ No newline at end of file + diff --git a/web/public/favicons/favicon-dark-success.svg b/web/public/favicons/favicon-dark-success.svg index 92b8b6a1d27..a587b985cac 100644 --- a/web/public/favicons/favicon-dark-success.svg +++ b/web/public/favicons/favicon-dark-success.svg @@ -1 +1 @@ - \ No newline at end of file + diff --git a/web/public/favicons/favicon-light-default.svg b/web/public/favicons/favicon-light-default.svg index 1f4eb14f740..43acef1176a 100644 --- a/web/public/favicons/favicon-light-default.svg +++ b/web/public/favicons/favicon-light-default.svg @@ -1 +1 @@ - \ No newline at end of file + diff --git a/web/public/favicons/favicon-light-error.svg b/web/public/favicons/favicon-light-error.svg index 6bedff96e74..7bd863ccde0 100644 --- a/web/public/favicons/favicon-light-error.svg +++ b/web/public/favicons/favicon-light-error.svg @@ -1 +1 @@ - \ No newline at end of file + diff --git a/web/public/favicons/favicon-light-pending.svg b/web/public/favicons/favicon-light-pending.svg index 5e2b99af6ae..d7e651d8e4d 100644 --- a/web/public/favicons/favicon-light-pending.svg +++ b/web/public/favicons/favicon-light-pending.svg @@ -1 +1 @@ - \ No newline at end of file + diff --git a/web/public/favicons/favicon-light-success.svg b/web/public/favicons/favicon-light-success.svg index e2932a2e0da..21adb619248 100644 --- a/web/public/favicons/favicon-light-success.svg +++ b/web/public/favicons/favicon-light-success.svg @@ -1 +1 @@ - \ No newline at end of file + diff --git a/woodpecker-go/LICENSE b/woodpecker-go/LICENSE index 8ca4ece9654..85a3fa9a1ff 100644 --- a/woodpecker-go/LICENSE +++ b/woodpecker-go/LICENSE @@ -199,4 +199,3 @@ Apache License WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - From ff963442f21dc3bd7c119c82bc56aea8012cdf75 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 29 Oct 2023 07:37:01 +0000 Subject: [PATCH 10/22] [pre-commit.ci] auto fixes from pre-commit.com hooks [CI SKIP] for more information, see https://pre-commit.ci --- docs/docs/30-administration/10-server-config.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/30-administration/10-server-config.md b/docs/docs/30-administration/10-server-config.md index e3740338e1d..ad6e9ca5160 100644 --- a/docs/docs/30-administration/10-server-config.md +++ b/docs/docs/30-administration/10-server-config.md @@ -20,9 +20,9 @@ services: + - 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 +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 From d893f3bade79f562a011994732ea9ee8b895f465 Mon Sep 17 00:00:00 2001 From: pat-s Date: Sun, 29 Oct 2023 08:44:25 +0100 Subject: [PATCH 11/22] use hadolint in docker --- .pre-commit-config.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 289d4c5c6c8..05293787c5d 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -25,7 +25,7 @@ repos: - repo: https://github.com/hadolint/hadolint rev: v2.12.0 hooks: - - id: hadolint + - id: hadolint-docker ci: autofix_commit_msg: | From bad5ef49ee9ca0b5d1ffcbda0990c33dc57c60c8 Mon Sep 17 00:00:00 2001 From: pat-s Date: Sun, 29 Oct 2023 08:44:33 +0100 Subject: [PATCH 12/22] md fixes --- docs/docs/30-administration/10-server-config.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/30-administration/10-server-config.md b/docs/docs/30-administration/10-server-config.md index ad6e9ca5160..9cf2a879ac6 100644 --- a/docs/docs/30-administration/10-server-config.md +++ b/docs/docs/30-administration/10-server-config.md @@ -20,9 +20,9 @@ services: + - 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 +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 @@ -156,7 +156,7 @@ 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 +### woodpecker.css ```css .banner-message { @@ -172,7 +172,7 @@ The examples below show how to place a banner message in the top navigation bar } ``` -##### woodpecker.js +### woodpecker.js ```javascript // place/copy a minified version of jQuery or ZeptoJS here ... From 94012647c808534d1569ada9038a5bca025ec216 Mon Sep 17 00:00:00 2001 From: pat-s Date: Sun, 29 Oct 2023 08:47:50 +0100 Subject: [PATCH 13/22] don't run hadolint in ci --- .pre-commit-config.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 05293787c5d..bba356cea09 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -22,10 +22,11 @@ repos: rev: 0.2.2 hooks: - id: checkmake + exclude: '^docker/Dockerfile.make$' # actually a Dockerfile and not a makefile - repo: https://github.com/hadolint/hadolint rev: v2.12.0 hooks: - - id: hadolint-docker + - id: hadolint ci: autofix_commit_msg: | @@ -36,5 +37,6 @@ ci: autoupdate_branch: '' autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate' autoupdate_schedule: monthly - skip: [check-hooks-apply, check-useless-excludes] + # NB: hadolint not included in pre-commit.ci + skip: [check-hooks-apply, check-useless-excludes, hadolint] submodules: false From 4cad2cdecccb7ac51c1fdbede0a9c4c7d1cedec8 Mon Sep 17 00:00:00 2001 From: pat-s Date: Sun, 29 Oct 2023 09:47:32 +0100 Subject: [PATCH 14/22] one-sentence-per-line --- .pre-commit-config.yaml | 3 + CONTRIBUTING.md | 19 ++- SECURITY.md | 3 +- docs/README.md | 3 +- docs/blog/2023-06-11-hello-blog/index.md | 8 +- docs/docs/10-intro.md | 3 +- docs/docs/20-usage/10-intro.md | 16 ++- docs/docs/20-usage/15-terminiology/index.md | 28 ++-- docs/docs/20-usage/20-workflow-syntax.md | 120 ++++++++++++------ docs/docs/20-usage/25-workflows.md | 18 ++- docs/docs/20-usage/30-matrix-workflows.md | 6 +- docs/docs/20-usage/40-secrets.md | 30 +++-- docs/docs/20-usage/41-registries.md | 14 +- docs/docs/20-usage/45-cron.md | 3 +- docs/docs/20-usage/50-environment.md | 25 ++-- docs/docs/20-usage/51-plugins/10-plugins.md | 9 +- .../20-usage/51-plugins/20-sample-plugin.md | 3 +- docs/docs/20-usage/60-services.md | 9 +- docs/docs/20-usage/70-volumes.md | 10 +- docs/docs/20-usage/71-project-settings.md | 26 +++- docs/docs/20-usage/80-badges.md | 6 +- docs/docs/20-usage/90-advanced-usage.md | 3 +- .../00-deployment/00-overview.md | 10 +- .../00-deployment/10-docker-compose.md | 22 +++- .../30-administration/10-server-config.md | 62 ++++++--- .../100-external-configuration-api.md | 6 +- .../30-administration/11-forges/20-github.md | 6 +- .../30-administration/11-forges/30-gitea.md | 20 ++- .../30-administration/11-forges/40-gitlab.md | 21 ++- .../11-forges/50-bitbucket.md | 18 ++- .../docs/30-administration/15-agent-config.md | 27 ++-- .../22-backends/10-docker.md | 23 ++-- .../30-administration/22-backends/20-local.md | 41 +++--- .../22-backends/40-kubernetes.md | 24 ++-- docs/docs/30-administration/30-database.md | 24 ++-- docs/docs/30-administration/40-encryption.md | 29 ++--- docs/docs/30-administration/60-ssl.md | 25 ++-- docs/docs/30-administration/70-proxy.md | 15 ++- docs/docs/30-administration/80-autoscaler.md | 3 +- docs/docs/30-administration/90-prometheus.md | 8 +- docs/docs/91-migrations.md | 59 ++++++--- .../docs/92-development/01-getting-started.md | 30 +++-- docs/docs/92-development/03-ui.md | 24 +++- docs/docs/92-development/04-docs.md | 8 +- docs/docs/92-development/06-guides.md | 12 +- docs/docs/92-development/07-translations.md | 3 +- docs/docs/92-development/09-security.md | 3 +- docs/src/pages/faq.md | 20 ++- .../20-usage/22-conditional-execution.md | 4 +- .../version-0.15/20-usage/40-secrets.md | 2 +- .../30-administration/40-encryption.md | 11 +- .../samples/sample_8_network_mode/README.md | 8 +- 52 files changed, 607 insertions(+), 326 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index bba356cea09..e9b02033b0a 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -18,6 +18,9 @@ repos: rev: v0.37.0 hooks: - id: markdownlint + args: [--rules, sentences-per-line] + additional_dependencies: [sentences-per-line] + exclude: '^docs/versioned_docs/.*$' - repo: https://github.com/mrtazz/checkmake rev: 0.2.2 hooks: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d681f945cb..94a2bb52cb7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,7 +22,8 @@ For security reasons, Maintainers must use 2FA for their accounts and if possibl Since Woodpecker is a pure community organization without any company support, to keep the development healthy we will elect two owners every year.\ This can also happen when a owner propose a vote or the majority of the maintainers do so.\ -All maintainers may vote to elect up to two candidates. When the new owners have been elected, the old owners will give up ownership to the newly elected owners. +All maintainers may vote to elect up to two candidates. +When the new owners have been elected, the old owners will give up ownership to the newly elected owners. If an owner is unable to do so, the other owners will assist in ceding ownership to the newly elected owners. For security reasons, Owners must use 2FA.\ @@ -46,20 +47,16 @@ they served: ## Code Review -Once code review starts on your PR, do not rebase nor squash your branch as it makes it -difficult to review the new changes. Only if there is a need, sync your branch by merging -the base branch into yours. Don't worry about merge commits messing up your tree as -the final merge process squashes all commits into one, with the visible commit message (first -line) being the PR title + PR index and description being the PR's first comment. +Once code review starts on your PR, do not rebase nor squash your branch as it makes it difficult to review the new changes. +Only if there is a need, sync your branch by merging the base branch into yours. +Don't worry about merge commits messing up your tree as the final merge process squashes all commits into one, with the visible commit message (first line) being the PR title + PR index and description being the PR's first comment. -Once your PR gets approved, don't worry about keeping it up-to-date or breaking -builds (unless there's a merge conflict or a request is made by a maintainer to make -modifications). It is the maintainer team's responsibility from this point to get it merged. +Once your PR gets approved, don't worry about keeping it up-to-date or breaking builds (unless there's a merge conflict or a request is made by a maintainer to make modifications). +It is the maintainer team's responsibility from this point to get it merged. ## 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. +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. ## Development diff --git a/SECURITY.md b/SECURITY.md index 2491fe0cc40..f9841655d0d 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -7,4 +7,5 @@ If you discover a security issue, please bring it to their attention right away! 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. +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/README.md b/docs/README.md index 673bfe22c2a..a67a886c59e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,7 +14,8 @@ pnpm install pnpm start ``` -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. +This command starts a local development server and opens up a browser window. +Most changes are reflected live without having to restart the server. ## Build diff --git a/docs/blog/2023-06-11-hello-blog/index.md b/docs/blog/2023-06-11-hello-blog/index.md index 44436794ef7..612da975e87 100644 --- a/docs/blog/2023-06-11-hello-blog/index.md +++ b/docs/blog/2023-06-11-hello-blog/index.md @@ -1,6 +1,6 @@ --- title: Welcome Woodpecker's blog -description: This our first post on Woodpecker. +description: This our first post on Woodpecker slug: hello-blog authors: - name: Anbraten @@ -11,12 +11,14 @@ tags: [hello, woodpecker] hide_table_of_contents: false --- -Welcome to this blog. This is our first post on this blog ... +Welcome to this blog. +This is our first post on this blog ... In the future we will post about our releases and other things like tutorials. -We are currently working on the `1.0.0` release of Woodpecker. This release will include a lot of new features and improvements which most of you probably already tested using the `next` tag. +We are currently working on the `1.0.0` release of Woodpecker. +This release will include a lot of new features and improvements which most of you probably already tested using the `next` tag. If you have any suggestions or ideas for posts, feel free to open an issue in the [GitHub repository](https://github.com/woodpecker-ci/woodpecker). diff --git a/docs/docs/10-intro.md b/docs/docs/10-intro.md index cc28b1f86d3..d1f88bf29bf 100644 --- a/docs/docs/10-intro.md +++ b/docs/docs/10-intro.md @@ -1,6 +1,7 @@ # Welcome to Woodpecker -Woodpecker is a simple CI engine with great extensibility. It focuses on executing pipelines inside [containers](https://opencontainers.org/). +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) diff --git a/docs/docs/20-usage/10-intro.md b/docs/docs/20-usage/10-intro.md index 8512ed62130..225335648fb 100644 --- a/docs/docs/20-usage/10-intro.md +++ b/docs/docs/20-usage/10-intro.md @@ -2,9 +2,12 @@ ## 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, ...). +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. +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) @@ -12,11 +15,13 @@ Webhooks are used to trigger pipeline executions. When you push code to your rep > > The user who enables a repo in Woodpecker must have `Admin` rights on that repo, so that Woodpecker can add the webhook. > -> 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. +> 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. +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. @@ -66,4 +71,5 @@ steps: ## 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. +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/docs/20-usage/15-terminiology/index.md b/docs/docs/20-usage/15-terminiology/index.md index 4640ede350d..cbf2d9d67ac 100644 --- a/docs/docs/20-usage/15-terminiology/index.md +++ b/docs/docs/20-usage/15-terminiology/index.md @@ -12,11 +12,16 @@ - **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. +- **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). +- **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. @@ -25,18 +30,23 @@ - **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. +- **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]. +- **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: +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()` +- 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** diff --git a/docs/docs/20-usage/20-workflow-syntax.md b/docs/docs/20-usage/20-workflow-syntax.md index 58c6bd5efc7..b1219fb6f0e 100644 --- a/docs/docs/20-usage/20-workflow-syntax.md +++ b/docs/docs/20-usage/20-workflow-syntax.md @@ -1,6 +1,8 @@ # 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. +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: @@ -19,7 +21,8 @@ steps: - npm run build ``` -In the above example we define two steps, `frontend` and `backend`. The names of these steps are completely arbitrary. +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: @@ -42,7 +45,8 @@ 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. +Woodpecker gives the ability to skip individual commits by adding `[SKIP CI]` or `[CI SKIP]` to the commit message. +Note this is case-insensitive. ```sh git commit -m "updated README [CI SKIP]" @@ -50,7 +54,8 @@ 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. +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 @@ -113,7 +118,8 @@ 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: +Woodpecker does not automatically upgrade container images. +Example configuration to always pull the latest image when updates are available: ```diff steps: @@ -137,7 +143,9 @@ Commands of every step are executed serially as if you would enter them into you + - 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: +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: ```sh #!/bin/sh @@ -147,13 +155,15 @@ 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: +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: ```sh docker run --entrypoint=build.sh golang ``` -> Please note that only build steps can define commands. You cannot use commands with plugins or services. +> Please note that only build steps can define commands. +> You cannot use commands with plugins or services. ### `environment` @@ -163,13 +173,16 @@ 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. +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. +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: @@ -183,7 +196,9 @@ Some of the steps may be allowed to fail without causing the whole workflow and ### `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: +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: @@ -230,7 +245,8 @@ steps: + - 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. +> 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`: @@ -246,7 +262,8 @@ 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: +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 `/` @@ -315,7 +332,8 @@ when: #### `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: +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: @@ -405,7 +423,8 @@ when: #### `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. +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. @@ -446,7 +465,9 @@ when: ### `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. +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: @@ -470,11 +491,13 @@ Example parallel configuration: 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. +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. +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). @@ -490,13 +513,15 @@ Using `directory`, you can set a subdirectory of your repository or an absolute ## `services` -Woodpecker can provide service containers. They can for example be used to run databases or cache containers during the execution of workflow. +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. +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 @@ -517,7 +542,8 @@ The workspace can be customized using the workspace block in the YAML file: - 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. +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: @@ -545,7 +571,9 @@ 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. +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: @@ -560,18 +588,24 @@ git clone https://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. +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. +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. +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. +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: @@ -592,11 +626,14 @@ steps: ### 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`. +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`. +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: @@ -614,7 +651,9 @@ For more details and examples check the [Advanced usage docs](./90-advanced-usag ## `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. +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: @@ -688,7 +727,9 @@ 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: +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 @@ -696,7 +737,8 @@ 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. +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` @@ -732,7 +774,8 @@ Example conditional execution by branch: 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. +> 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`: @@ -846,17 +889,22 @@ when: ## `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. +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. +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. +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. +> 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: diff --git a/docs/docs/20-usage/25-workflows.md b/docs/docs/20-usage/25-workflows.md index 0d1523109e5..3e35d1bac92 100644 --- a/docs/docs/20-usage/25-workflows.md +++ b/docs/docs/20-usage/25-workflows.md @@ -1,14 +1,17 @@ # 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. +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. +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. +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). @@ -21,7 +24,8 @@ You can also set some custom path like `.my-ci/pipelines/` instead of `.woodpeck ## 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. +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). ::: @@ -92,9 +96,11 @@ Each workflow will report its own status back to your forge. 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. +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`. +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: diff --git a/docs/docs/20-usage/30-matrix-workflows.md b/docs/docs/20-usage/30-matrix-workflows.md index 9ec8851848c..1f094076365 100644 --- a/docs/docs/20-usage/30-matrix-workflows.md +++ b/docs/docs/20-usage/30-matrix-workflows.md @@ -1,6 +1,7 @@ # 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. +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: @@ -30,7 +31,8 @@ matrix: ## 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: +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: diff --git a/docs/docs/20-usage/40-secrets.md b/docs/docs/20-usage/40-secrets.md index 83b9493131d..c0f8da4b818 100644 --- a/docs/docs/20-usage/40-secrets.md +++ b/docs/docs/20-usage/40-secrets.md @@ -1,10 +1,13 @@ # 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 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. 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. -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. +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. @@ -37,7 +40,8 @@ steps: + from_secret: secret_token ``` -Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped. +Please note parameter expressions are subject to pre-processing. +When using secrets in parameter expressions they should be escaped. ```diff steps: @@ -57,7 +61,8 @@ Secrets are added to the Woodpecker in the UI or with the CLI. ## 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: +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: @@ -72,7 +77,8 @@ steps: ## Pull Requests -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. +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. ```diff woodpecker-cli secret add \ @@ -85,15 +91,20 @@ woodpecker-cli secret add \ -value ``` -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. +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. +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. ## 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). +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 \ @@ -136,7 +147,8 @@ woodpecker-cli secret add \ -value ``` -Loading secrets from file using curl `@` syntax. This is the recommended approach for loading secrets from file to preserve newlines: +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 \ diff --git a/docs/docs/20-usage/41-registries.md b/docs/docs/20-usage/41-registries.md index f0a69d6b668..9970dd30f35 100644 --- a/docs/docs/20-usage/41-registries.md +++ b/docs/docs/20-usage/41-registries.md @@ -1,12 +1,15 @@ # 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. +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. +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: @@ -19,7 +22,9 @@ Example configuration using a private image: - 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. +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: @@ -46,7 +51,8 @@ For specific details on configuring access to Google Container Registry, please ## Local Images :::warning -For this, privileged rights are needed only available to admins. In addition, this only works when using a single agent. +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. diff --git a/docs/docs/20-usage/45-cron.md b/docs/docs/20-usage/45-cron.md index f90c77c1adb..3654a422533 100644 --- a/docs/docs/20-usage/45-cron.md +++ b/docs/docs/20-usage/45-cron.md @@ -23,7 +23,8 @@ To configure cron jobs you need at least push access to the repository. ![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. + 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 * * * *` ... diff --git a/docs/docs/20-usage/50-environment.md b/docs/docs/20-usage/50-environment.md index 3dd5d801d18..ee692d4deff 100644 --- a/docs/docs/20-usage/50-environment.md +++ b/docs/docs/20-usage/50-environment.md @@ -1,6 +1,8 @@ # 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: +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: @@ -15,7 +17,8 @@ steps: - 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. +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: @@ -29,7 +32,8 @@ steps: - 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: +> 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: @@ -44,7 +48,8 @@ steps: ## 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. +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 | | -------------------------------- | -------------------------------------------------------------------------------------------- | @@ -126,14 +131,15 @@ This is the reference list of all environment variables available to your pipeli | `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_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. +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: @@ -160,7 +166,8 @@ steps: ## 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. +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: @@ -184,7 +191,9 @@ steps: ## 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. +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 | | ------------------ | ------------------------------------------------ | diff --git a/docs/docs/20-usage/51-plugins/10-plugins.md b/docs/docs/20-usage/51-plugins/10-plugins.md index 48977c9a849..983640ee3a1 100644 --- a/docs/docs/20-usage/51-plugins/10-plugins.md +++ b/docs/docs/20-usage/51-plugins/10-plugins.md @@ -1,6 +1,7 @@ # 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. +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. @@ -28,7 +29,8 @@ steps: ## Plugin Isolation -Plugins are just pipeline steps. They share the build workspace, mounted as a volume, and therefore have access to your source tree. +Plugins are just pipeline steps. +They share the build workspace, mounted as a volume, and therefore have access to your source tree. ## Finding Plugins @@ -37,7 +39,8 @@ 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. +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/docs/20-usage/51-plugins/20-sample-plugin.md b/docs/docs/20-usage/51-plugins/20-sample-plugin.md index 317303e76c3..805d1d4cb0e 100644 --- a/docs/docs/20-usage/51-plugins/20-sample-plugin.md +++ b/docs/docs/20-usage/51-plugins/20-sample-plugin.md @@ -42,7 +42,8 @@ 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. +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 . diff --git a/docs/docs/20-usage/60-services.md b/docs/docs/20-usage/60-services.md index df2467200b7..1442c565efa 100644 --- a/docs/docs/20-usage/60-services.md +++ b/docs/docs/20-usage/60-services.md @@ -24,7 +24,8 @@ services: ## 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. +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: @@ -40,7 +41,8 @@ services: ## 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. +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: @@ -64,7 +66,8 @@ 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. +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: diff --git a/docs/docs/20-usage/70-volumes.md b/docs/docs/20-usage/70-volumes.md index 297f14ec07e..a5cc62ff2cc 100644 --- a/docs/docs/20-usage/70-volumes.md +++ b/docs/docs/20-usage/70-volumes.md @@ -1,9 +1,11 @@ # 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. +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. +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 @@ -19,7 +21,9 @@ steps: + - /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. +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 ] diff --git a/docs/docs/20-usage/71-project-settings.md b/docs/docs/20-usage/71-project-settings.md index 319a07e6101..66fba5c4a8d 100644 --- a/docs/docs/20-usage/71-project-settings.md +++ b/docs/docs/20-usage/71-project-settings.md @@ -6,22 +6,28 @@ As the owner of a project in Woodpecker you can change project related settings ## 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/`. +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. +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. +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. +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 @@ -29,17 +35,23 @@ If you set your project to trusted, a pipeline step and by this the underlying c :::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 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. +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. +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. diff --git a/docs/docs/20-usage/80-badges.md b/docs/docs/20-usage/80-badges.md index 1edfcfd4952..7d536f505c3 100644 --- a/docs/docs/20-usage/80-badges.md +++ b/docs/docs/20-usage/80-badges.md @@ -1,6 +1,7 @@ # 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. +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 @@ -8,7 +9,8 @@ Woodpecker has integrated support for repository status badges. These badges can :///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. +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 diff --git a/docs/docs/20-usage/90-advanced-usage.md b/docs/docs/20-usage/90-advanced-usage.md index 2edad5d2474..62881987f70 100644 --- a/docs/docs/20-usage/90-advanced-usage.md +++ b/docs/docs/20-usage/90-advanced-usage.md @@ -131,4 +131,5 @@ services: # ... ``` -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. +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/docs/30-administration/00-deployment/00-overview.md b/docs/docs/30-administration/00-deployment/00-overview.md index d360abf62d3..bf17ee10cba 100644 --- a/docs/docs/30-administration/00-deployment/00-overview.md +++ b/docs/docs/30-administration/00-deployment/00-overview.md @@ -46,11 +46,14 @@ See the complete reference for all supported forges [here](../11-forges/10-overv ## 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. +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) +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 @@ -65,7 +68,8 @@ In the case you need to use Woodpecker with a URL path prefix (like: ://` format. Please omit trailing slashes: +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 @@ -55,7 +58,9 @@ services: + - 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. +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 @@ -70,7 +75,9 @@ services: + - 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: +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 @@ -98,7 +105,8 @@ services: + - /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: +Agents require the server address for agent-to-server communication. +The agent connects to the server's gRPC port: ```diff # docker-compose.yml @@ -111,7 +119,9 @@ services: + - 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`: +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 diff --git a/docs/docs/30-administration/10-server-config.md b/docs/docs/30-administration/10-server-config.md index 9cf2a879ac6..65806b463c4 100644 --- a/docs/docs/30-administration/10-server-config.md +++ b/docs/docs/30-administration/10-server-config.md @@ -4,7 +4,8 @@ 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. +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: @@ -73,9 +74,11 @@ services: ## 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. +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. +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 @@ -113,9 +116,13 @@ services: 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. +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. +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 @@ -194,7 +201,8 @@ The following list describes all available server configuration options. > Default: empty -Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty. +Configures the logging level. +Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty. ### `WOODPECKER_LOG_XORM` @@ -312,7 +320,8 @@ Read the value for `WOODPECKER_GRPC_SECRET` from the specified filepath. > Default: empty -Configures an unprotected metrics endpoint. An empty value disables the metrics endpoint completely. +Configures an unprotected metrics endpoint. +An empty value disables the metrics endpoint completely. Example: `:9001` @@ -350,7 +359,8 @@ Enable to allow user registration. > 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. +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` @@ -389,7 +399,8 @@ a user can log into Woodpecker, without re-authentication. > 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! +Docker images to run in privileged mode. +Only change if you are sure what you do! + **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. + + From 0ca42d2226f9f3387cf39b8d2dbea36062f0c725 Mon Sep 17 00:00:00 2001 From: pat-s Date: Mon, 30 Oct 2023 19:36:22 +0100 Subject: [PATCH 17/22] fix duplicate quote character --- docs/docs/20-usage/10-intro.md | 4 +- .../00-deployment/00-overview.md | 4 +- .../version-0.15/20-usage/10-intro.md | 4 +- .../30-administration/00-setup.md | 4 +- .../30-administration/10-server-config.md | 62 +++++----- .../30-administration/11-vcs/20-github.md | 12 +- .../30-administration/11-vcs/30-gitea.md | 10 +- .../30-administration/11-vcs/40-gitlab.md | 10 +- .../30-administration/11-vcs/50-bitbucket.md | 6 +- .../11-vcs/60-bitbucket_server.md | 16 +-- .../30-administration/11-vcs/70-gogs.md | 12 +- .../30-administration/11-vcs/80-coding.md | 18 +-- .../30-administration/15-agent-config.md | 30 ++--- .../version-1.0/20-usage/10-intro.md | 4 +- .../version-1.0/30-administration/00-setup.md | 4 +- .../30-administration/10-server-config.md | 108 +++++++++--------- .../30-administration/11-forges/20-github.md | 16 +-- .../30-administration/11-forges/30-gitea.md | 14 +-- .../30-administration/11-forges/40-gitlab.md | 14 +-- .../11-forges/50-bitbucket.md | 10 +- .../30-administration/15-agent-config.md | 36 +++--- .../22-backends/10-docker.md | 6 +- .../30-administration/22-backends/30-ssh.md | 10 +- .../22-backends/40-kubernetes.md | 12 +- 24 files changed, 213 insertions(+), 213 deletions(-) diff --git a/docs/docs/20-usage/10-intro.md b/docs/docs/20-usage/10-intro.md index 225335648fb..21c3cdbda13 100644 --- a/docs/docs/20-usage/10-intro.md +++ b/docs/docs/20-usage/10-intro.md @@ -12,9 +12,9 @@ When you push code to your repository, open a pull request, or create a tag, you ![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 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. diff --git a/docs/docs/30-administration/00-deployment/00-overview.md b/docs/docs/30-administration/00-deployment/00-overview.md index bf17ee10cba..cbb988afee6 100644 --- a/docs/docs/30-administration/00-deployment/00-overview.md +++ b/docs/docs/30-administration/00-deployment/00-overview.md @@ -6,9 +6,9 @@ A Woodpecker deployment consists of two parts: - 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. -> + > 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? diff --git a/docs/versioned_docs/version-0.15/20-usage/10-intro.md b/docs/versioned_docs/version-0.15/20-usage/10-intro.md index 2673c751841..5898ef54368 100644 --- a/docs/versioned_docs/version-0.15/20-usage/10-intro.md +++ b/docs/versioned_docs/version-0.15/20-usage/10-intro.md @@ -9,9 +9,9 @@ Webhooks are used to trigger pipeline executions. When you push code to your rep ![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 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 diff --git a/docs/versioned_docs/version-0.15/30-administration/00-setup.md b/docs/versioned_docs/version-0.15/30-administration/00-setup.md index 1240a6db13b..83d695d34c6 100644 --- a/docs/versioned_docs/version-0.15/30-administration/00-setup.md +++ b/docs/versioned_docs/version-0.15/30-administration/00-setup.md @@ -6,9 +6,9 @@ A Woodpecker deployment consists of two parts: - 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 builds in parallel. -> + > You can add more agents to increase the number of parallel builds or set the agent's `WOODPECKER_MAX_PROCS=1` environment variable to increase the number of parallel builds for that agent. ## Which version of Woodpecker should I use? diff --git a/docs/versioned_docs/version-0.15/30-administration/10-server-config.md b/docs/versioned_docs/version-0.15/30-administration/10-server-config.md index 2b5478601d6..17ed28e5112 100644 --- a/docs/versioned_docs/version-0.15/30-administration/10-server-config.md +++ b/docs/versioned_docs/version-0.15/30-administration/10-server-config.md @@ -77,25 +77,25 @@ services: 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_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. @@ -103,13 +103,13 @@ Server fully qualified url of the user-facing hostname. Example: `WOODPECKER_HOST=http://woodpecker.example.org` ### `WOODPECKER_SERVER_ADDR` -> + > Default: `:8000` Configures the HTTP listener port. ### `WOODPECKER_SERVER_CERT` -> + > Default: empty Path to an SSL certificate used by the server to accept HTTPS requests. @@ -117,7 +117,7 @@ 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. @@ -125,19 +125,19 @@ Path to an SSL certificate key used by the server to accept HTTPS requests. Example: `WOODPECKER_SERVER_KEY=/path/to/key.pem` ### `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_ADMIN` -> + > Default: empty Comma-separated list of admin accounts. @@ -145,7 +145,7 @@ Comma-separated list of admin accounts. Example: `WOODPECKER_ADMIN=user1,user2` ### `WOODPECKER_ORGS` -> + > Default: empty Comma-separated list of approved organizations. @@ -153,7 +153,7 @@ Comma-separated list of approved organizations. Example: `org1,org2` ### `WOODPECKER_REPO_OWNERS` -> + > Default: empty Comma-separated list of syncable repo owners. ??? @@ -161,31 +161,31 @@ Comma-separated list of syncable repo owners. ??? Example: `user1,user2` ### `WOODPECKER_OPEN` -> + > Default: `false` Enable to allow user registration. ### `WOODPECKER_DOCS` -> + > Default: `https://woodpecker-ci.org/` Link to documentation in the UI. ### `WOODPECKER_AUTHENTICATE_PUBLIC_REPOS` -> + > Default: `false` Always use authentication to clone repositories even if they are public. Needed if the SCM requires to always authenticate as used by many companies. ### `WOODPECKER_DEFAULT_CLONE_IMAGE` -> + > Default is defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/release/v0.15/shared/constant/constant.go) The default docker image to be used when cloning the repo ### `WOODPECKER_SESSION_EXPIRES` -> + > Default: `72h` Configures the session expiration time. @@ -194,7 +194,7 @@ As long as the session is valid (until it expires or log-out), a user can log into Woodpecker, without re-authentication. ### `WOODPECKER_ESCALATE` -> + > Default: `plugins/docker,plugins/gcr,plugins/ecr,woodpeckerci/plugin-docker,woodpeckerci/plugin-docker-buildx` Docker images to run in privileged mode. Only change if you are sure what you do! @@ -209,7 +209,7 @@ Example: `WOODPECKER_VOLUME=/path/on/host:/path/in/container:rw`| --> ### `WOODPECKER_DOCKER_CONFIG` -> + > Default: empty Configures a specific private registry config for all pipelines. @@ -231,13 +231,13 @@ Example: `WOODPECKER_NETWORK=network1,network2` --> ### `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_KEEPALIVE_MIN_TIME` -> + > Default: empty Server-side enforcement policy on the minimum amount of time a client should wait before sending a keepalive ping. @@ -245,13 +245,13 @@ Server-side enforcement policy on the minimum amount of time a client should wai 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. @@ -269,13 +269,13 @@ WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker? ``` ### `WOODPECKER_PROMETHEUS_AUTH_TOKEN` -> + > Default: empty Token to secure the Prometheus metrics endpoint. ### `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. @@ -283,37 +283,37 @@ Context prefix Woodpecker will use to publish status messages to SCM. You probab --- ### `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. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/20-github.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/20-github.md index 5d01dab99cb..30d67fe9e67 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/20-github.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/20-github.md @@ -32,37 +32,37 @@ Please use this screenshot for reference: 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. This is used to authorize access. ### `WOODPECKER_GITHUB_SECRET` -> + > Default: empty Configures the GitHub OAuth client secret. This is used to authorize access. ### `WOODPECKER_GITHUB_MERGE_REF` -> + > Default: `true` TODO ### `WOODPECKER_GITHUB_SKIP_VERIFY` -> + > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/30-gitea.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/30-gitea.md index 495a33b7a29..82a89ad6c57 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/30-gitea.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/30-gitea.md @@ -41,31 +41,31 @@ For reference see [Configuration Cheat Sheet](https://docs.gitea.io/en-us/config 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_SECRET` -> + > Default: empty Configures the Gitea OAuth client secret. This is used to authorize access. ### `WOODPECKER_GITEA_SKIP_VERIFY` -> + > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/40-gitlab.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/40-gitlab.md index 5bb88b0262b..26874d2d057 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/40-gitlab.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/40-gitlab.md @@ -32,31 +32,31 @@ If you run the Woodpecker CI server on the same host as the GitLab instance, you 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_SECRET` -> + > Default: empty Configures the GitLab OAuth client secret. This is used to authorize access. ### `WOODPECKER_GITLAB_SKIP_VERIFY` -> + > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/50-bitbucket.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/50-bitbucket.md index 38e1a793241..8a61fa9fc6b 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/50-bitbucket.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/50-bitbucket.md @@ -44,19 +44,19 @@ Webhooks:Read and Write 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 id. This is used to authorize access. ### `WOODPECKER_BITBUCKET_SECRET` -> + > Default: empty Configures the Bitbucket OAuth client secret. This is used to authorize access. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/60-bitbucket_server.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/60-bitbucket_server.md index 1ab776f4e62..4e1ccc4931d 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/60-bitbucket_server.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/60-bitbucket_server.md @@ -101,49 +101,49 @@ Please use as the Authorization call 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_STASH` -> + > Default: `false` Enables the Bitbucket Server driver. ### `WOODPECKER_STASH_URL` -> + > Default: empty Configures the Bitbucket Server address. ### `WOODPECKER_STASH_CONSUMER_KEY` -> + > Default: empty Configures your Bitbucket Server consumer key. ### `WOODPECKER_STASH_CONSUMER_RSA` -> + > Default: empty Configures the path to your Bitbucket Server private key file. ### `WOODPECKER_STASH_CONSUMER_RSA_STRING` -> + > Default: empty Configures your Bitbucket Server private key. ### `WOODPECKER_STASH_GIT_USERNAME` -> + > Default: empty This username is used to authenticate and clone all private repositories. ### `WOODPECKER_STASH_GIT_PASSWORD` -> + > Default: empty The password is used to authenticate and clone all private repositories. ### `WOODPECKER_STASH_SKIP_VERIFY` -> + > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/70-gogs.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/70-gogs.md index 3b815ec806e..8eb33f493e7 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/70-gogs.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/70-gogs.md @@ -5,37 +5,37 @@ 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_GOGS` -> + > Default: `false` Enables the Gogs driver. ### `WOODPECKER_GOGS_URL` -> + > Default: `https://github.com` Configures the Gogs server address. ### `WOODPECKER_GOGS_GIT_USERNAME` -> + > Default: empty This username is used to authenticate and clone all private repositories. ### `WOODPECKER_GOGS_GIT_PASSWORD` -> + > Default: empty The password is used to authenticate and clone all private repositories. ### `WOODPECKER_GOGS_PRIVATE_MODE` -> + > Default: `false` TODO ### `WOODPECKER_GOGS_SKIP_VERIFY` -> + > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/80-coding.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/80-coding.md index 1e1546a810f..ac2cda97750 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/80-coding.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/80-coding.md @@ -5,55 +5,55 @@ 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_CODING` -> + > Default: `false` Enables the Coding driver. ### `WOODPECKER_CODING_URL` -> + > Default: `https://coding.net` Configures the Coding server address. ### `WOODPECKER_CODING_CLIENT` -> + > Default: empty Configures the Coding OAuth client id. This is used to authorize access. ### `WOODPECKER_CODING_SECRET` -> + > Default: empty Configures the Coding OAuth client secret. This is used to authorize access. ### `WOODPECKER_CODING_SCOPE` -> + > Default: `user, project, project:depot` Comma-separated list of OAuth scopes. ### `WOODPECKER_CODING_GIT_MACHINE` -> + > Default: `git.coding.net` TODO ### `WOODPECKER_CODING_GIT_USERNAME` -> + > Default: empty This username is used to authenticate and clone all private repositories. ### `WOODPECKER_CODING_GIT_PASSWORD` -> + > Default: empty The password is used to authenticate and clone all private repositories. ### `WOODPECKER_CODING_SKIP_VERIFY` -> + > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md b/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md index 9c2a6a4685b..ad3343cb3ad 100644 --- a/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md +++ b/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md @@ -80,91 +80,91 @@ See [Conditionals Pipeline](../20-usage/20-pipeline-syntax.md#step-when---condit Here is the full list of configuration options and their default variables. ### `DOCKER_HOST` -> + > Default: empty Point to an alternate socket file or host. For example, "unix:////run/podman/podman.sock" ### `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_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_MAX_PROCS` -> + > Default: `1` Configures the number of parallel builds. ### `WOODPECKER_HEALTHCHECK` -> + > Default: `true` Enable healthcheck endpoint. ### `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` or `docker`. diff --git a/docs/versioned_docs/version-1.0/20-usage/10-intro.md b/docs/versioned_docs/version-1.0/20-usage/10-intro.md index fcefb8195c5..dc4d4070e57 100644 --- a/docs/versioned_docs/version-1.0/20-usage/10-intro.md +++ b/docs/versioned_docs/version-1.0/20-usage/10-intro.md @@ -9,9 +9,9 @@ Webhooks are used to trigger pipeline executions. When you push code to your rep ![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 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 diff --git a/docs/versioned_docs/version-1.0/30-administration/00-setup.md b/docs/versioned_docs/version-1.0/30-administration/00-setup.md index 4e66ab52d6c..d98d9b70147 100644 --- a/docs/versioned_docs/version-1.0/30-administration/00-setup.md +++ b/docs/versioned_docs/version-1.0/30-administration/00-setup.md @@ -6,9 +6,9 @@ A Woodpecker deployment consists of two parts: - 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 builds in parallel. -> + > You can add more agents to increase the number of parallel steps 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? diff --git a/docs/versioned_docs/version-1.0/30-administration/10-server-config.md b/docs/versioned_docs/version-1.0/30-administration/10-server-config.md index 0e0698cfc98..391fa2ff4f5 100644 --- a/docs/versioned_docs/version-1.0/30-administration/10-server-config.md +++ b/docs/versioned_docs/version-1.0/30-administration/10-server-config.md @@ -185,37 +185,37 @@ $().ready(function(){ 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_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. @@ -223,7 +223,7 @@ Server fully qualified URL of the user-facing hostname. Example: `WOODPECKER_HOST=http://woodpecker.example.org` ### `WOODPECKER_WEBHOOK_HOST` -> + > Default: value from `WOODPECKER_HOST` config env Server fully qualified URL of the Webhook-facing hostname. @@ -231,19 +231,19 @@ Server fully qualified URL of the Webhook-facing hostname. 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. @@ -251,7 +251,7 @@ 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. @@ -259,7 +259,7 @@ 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. @@ -269,7 +269,7 @@ 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. @@ -279,31 +279,31 @@ 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. @@ -311,7 +311,7 @@ Configures an unprotected metrics endpoint. An empty value disables the metrics Example: `:9001` ### `WOODPECKER_ADMIN` -> + > Default: empty Comma-separated list of admin accounts. @@ -319,7 +319,7 @@ Comma-separated list of admin accounts. Example: `WOODPECKER_ADMIN=user1,user2` ### `WOODPECKER_ORGS` -> + > Default: empty Comma-separated list of approved organizations. @@ -327,7 +327,7 @@ Comma-separated list of approved organizations. Example: `org1,org2` ### `WOODPECKER_REPO_OWNERS` -> + > Default: empty Comma-separated list of syncable repo owners. ??? @@ -335,49 +335,49 @@ Comma-separated list of syncable repo owners. ??? Example: `user1,user2` ### `WOODPECKER_OPEN` -> + > Default: `false` Enable to allow user registration. ### `WOODPECKER_DOCS` -> + > Default: `https://woodpecker-ci.org/` Link to documentation in the UI. ### `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/master/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. @@ -386,7 +386,7 @@ 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/master/shared/constant/constant.go) Docker images to run in privileged mode. Only change if you are sure what you do! @@ -401,7 +401,7 @@ Example: `WOODPECKER_VOLUME=/path/on/host:/path/in/container:rw`| --> ### `WOODPECKER_DOCKER_CONFIG` -> + > Default: empty Configures a specific private registry config for all pipelines. @@ -423,19 +423,19 @@ Example: `WOODPECKER_NETWORK=network1,network2` --> ### `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. @@ -443,13 +443,13 @@ Server-side enforcement policy on the minimum amount of time a client should wai 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. @@ -467,56 +467,56 @@ WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker? ``` ### `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 }}` Template for the status messages published to forges, uses [Go templates](https://pkg.go.dev/text/template) as template language. @@ -531,37 +531,37 @@ Supported variables: --- ### `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. @@ -569,19 +569,19 @@ Comma-separated list to limit the specific CPUs or cores a pipeline container ca 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_URL` -> + > Default: `` Server URL path prefix (used for statics loading when having a url path prefix), should start with `/` diff --git a/docs/versioned_docs/version-1.0/30-administration/11-forges/20-github.md b/docs/versioned_docs/version-1.0/30-administration/11-forges/20-github.md index a5a239b22a5..f3203d3d1a5 100644 --- a/docs/versioned_docs/version-1.0/30-administration/11-forges/20-github.md +++ b/docs/versioned_docs/version-1.0/30-administration/11-forges/20-github.md @@ -32,49 +32,49 @@ Please use this screenshot for reference: 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. This is used 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` TODO ### `WOODPECKER_GITHUB_SKIP_VERIFY` -> + > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-1.0/30-administration/11-forges/30-gitea.md b/docs/versioned_docs/version-1.0/30-administration/11-forges/30-gitea.md index 2e7e5c9a330..54e94a65147 100644 --- a/docs/versioned_docs/version-1.0/30-administration/11-forges/30-gitea.md +++ b/docs/versioned_docs/version-1.0/30-administration/11-forges/30-gitea.md @@ -41,43 +41,43 @@ For reference see [Configuration Cheat Sheet](https://docs.gitea.io/en-us/config 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-1.0/30-administration/11-forges/40-gitlab.md b/docs/versioned_docs/version-1.0/30-administration/11-forges/40-gitlab.md index e63fd905f8d..6753bfafe45 100644 --- a/docs/versioned_docs/version-1.0/30-administration/11-forges/40-gitlab.md +++ b/docs/versioned_docs/version-1.0/30-administration/11-forges/40-gitlab.md @@ -32,43 +32,43 @@ If you run the Woodpecker CI server on the same host as the GitLab instance, you 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-1.0/30-administration/11-forges/50-bitbucket.md b/docs/versioned_docs/version-1.0/30-administration/11-forges/50-bitbucket.md index b5064fd88ce..81f71519b45 100644 --- a/docs/versioned_docs/version-1.0/30-administration/11-forges/50-bitbucket.md +++ b/docs/versioned_docs/version-1.0/30-administration/11-forges/50-bitbucket.md @@ -44,31 +44,31 @@ Webhooks:Read and Write 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 id. 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 diff --git a/docs/versioned_docs/version-1.0/30-administration/15-agent-config.md b/docs/versioned_docs/version-1.0/30-administration/15-agent-config.md index c69f7d6b61d..4055a561395 100644 --- a/docs/versioned_docs/version-1.0/30-administration/15-agent-config.md +++ b/docs/versioned_docs/version-1.0/30-administration/15-agent-config.md @@ -76,109 +76,109 @@ At following startups Agent uses own token only. 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-pipeline-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`, `ssh` or `kubernetes`. diff --git a/docs/versioned_docs/version-1.0/30-administration/22-backends/10-docker.md b/docs/versioned_docs/version-1.0/30-administration/22-backends/10-docker.md index 37a29fd9041..6eac9395c82 100644 --- a/docs/versioned_docs/version-1.0/30-administration/22-backends/10-docker.md +++ b/docs/versioned_docs/version-1.0/30-administration/22-backends/10-docker.md @@ -5,19 +5,19 @@ This is the original backend used with Woodpecker. The docker backend executes e ## 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 diff --git a/docs/versioned_docs/version-1.0/30-administration/22-backends/30-ssh.md b/docs/versioned_docs/version-1.0/30-administration/22-backends/30-ssh.md index edf15eca462..7d8d5414f5c 100644 --- a/docs/versioned_docs/version-1.0/30-administration/22-backends/30-ssh.md +++ b/docs/versioned_docs/version-1.0/30-administration/22-backends/30-ssh.md @@ -16,31 +16,31 @@ The backend will use a random directory in $TMPDIR to store the clone code and e ## Configuration ### `WOODPECKER_BACKEND_SSH_ADDRESS` -> + > Default: empty The SSH host to run steps with `ssh` backend. ### `WOODPECKER_BACKEND_SSH_USER` -> + > Default: empty The SSH user to run steps with `ssh` backend. ### `WOODPECKER_BACKEND_SSH_KEY` -> + > Default: empty Path to the private SSH key to run steps with `ssh` backend. ### `WOODPECKER_BACKEND_SSH_KEY_PASSWORD` -> + > Default: empty The password for the private key to run steps with `ssh` backend. ### `WOODPECKER_BACKEND_SSH_PASSWORD` -> + > Default empty The SSH password to run steps with `ssh` backend. diff --git a/docs/versioned_docs/version-1.0/30-administration/22-backends/40-kubernetes.md b/docs/versioned_docs/version-1.0/30-administration/22-backends/40-kubernetes.md index 32f55a49007..7c0bcd5f6a6 100644 --- a/docs/versioned_docs/version-1.0/30-administration/22-backends/40-kubernetes.md +++ b/docs/versioned_docs/version-1.0/30-administration/22-backends/40-kubernetes.md @@ -11,37 +11,37 @@ The kubernetes backend executes each step inside a newly created pod. A PVC is a ## Configuration ### `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"}`. From c7c385ebb9bd6b2530317a9d7687fd80cb7ed005 Mon Sep 17 00:00:00 2001 From: pat-s Date: Mon, 30 Oct 2023 19:41:57 +0100 Subject: [PATCH 18/22] more md fixes --- docs/docs/20-usage/10-intro.md | 6 ++++-- docs/docs/30-administration/00-deployment/00-overview.md | 9 +++++---- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/docs/20-usage/10-intro.md b/docs/docs/20-usage/10-intro.md index 21c3cdbda13..25e19163687 100644 --- a/docs/docs/20-usage/10-intro.md +++ b/docs/docs/20-usage/10-intro.md @@ -11,12 +11,14 @@ When you push code to your repository, open a pull request, or create a tag, you ![repository list](repo-list.png) -> Required Permissions +## Required Permissions -> The user who enables a repo in Woodpecker must have `Admin` rights on that repo, so that Woodpecker can add the webhook. +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 diff --git a/docs/docs/30-administration/00-deployment/00-overview.md b/docs/docs/30-administration/00-deployment/00-overview.md index cbb988afee6..4b2ed213ea7 100644 --- a/docs/docs/30-administration/00-deployment/00-overview.md +++ b/docs/docs/30-administration/00-deployment/00-overview.md @@ -5,11 +5,12 @@ 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. +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. -> If you have 4 agents installed and connected to the Woodpecker server, your system will process 4 workflows in parallel. - -> 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. +:::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? From 934683f0a3a4d0d9695546b2dd170c7d9f454e52 Mon Sep 17 00:00:00 2001 From: Anbraten Date: Tue, 31 Oct 2023 08:45:55 +0100 Subject: [PATCH 19/22] Revert "one-sentence-per-line" This reverts commit 4cad2cdecccb7ac51c1fdbede0a9c4c7d1cedec8. --- .pre-commit-config.yaml | 3 - CONTRIBUTING.md | 19 +-- SECURITY.md | 3 +- docs/README.md | 3 +- docs/blog/2023-06-11-hello-blog/index.md | 8 +- docs/docs/10-intro.md | 3 +- docs/docs/20-usage/10-intro.md | 17 +-- docs/docs/20-usage/15-terminiology/index.md | 28 ++-- docs/docs/20-usage/20-workflow-syntax.md | 120 ++++++------------ docs/docs/20-usage/25-workflows.md | 18 +-- docs/docs/20-usage/30-matrix-workflows.md | 6 +- docs/docs/20-usage/40-secrets.md | 30 ++--- docs/docs/20-usage/41-registries.md | 14 +- docs/docs/20-usage/45-cron.md | 3 +- docs/docs/20-usage/50-environment.md | 25 ++-- docs/docs/20-usage/51-plugins/10-plugins.md | 9 +- .../20-usage/51-plugins/20-sample-plugin.md | 3 +- docs/docs/20-usage/60-services.md | 9 +- docs/docs/20-usage/70-volumes.md | 10 +- docs/docs/20-usage/71-project-settings.md | 26 +--- docs/docs/20-usage/80-badges.md | 6 +- docs/docs/20-usage/90-advanced-usage.md | 3 +- .../00-deployment/00-overview.md | 10 +- .../00-deployment/10-docker-compose.md | 22 +--- .../30-administration/10-server-config.md | 62 +++------ .../100-external-configuration-api.md | 6 +- .../30-administration/11-forges/20-github.md | 6 +- .../30-administration/11-forges/30-gitea.md | 20 +-- .../30-administration/11-forges/40-gitlab.md | 21 +-- .../11-forges/50-bitbucket.md | 18 +-- .../docs/30-administration/15-agent-config.md | 27 ++-- .../22-backends/10-docker.md | 23 ++-- .../30-administration/22-backends/20-local.md | 41 +++--- .../22-backends/40-kubernetes.md | 24 ++-- docs/docs/30-administration/30-database.md | 24 ++-- docs/docs/30-administration/40-encryption.md | 29 +++-- docs/docs/30-administration/60-ssl.md | 25 ++-- docs/docs/30-administration/70-proxy.md | 15 +-- docs/docs/30-administration/80-autoscaler.md | 3 +- docs/docs/30-administration/90-prometheus.md | 8 +- docs/docs/91-migrations.md | 59 +++------ .../docs/92-development/01-getting-started.md | 30 ++--- docs/docs/92-development/03-ui.md | 24 +--- docs/docs/92-development/04-docs.md | 8 +- docs/docs/92-development/06-guides.md | 12 +- docs/docs/92-development/07-translations.md | 3 +- docs/docs/92-development/09-security.md | 3 +- docs/src/pages/faq.md | 20 +-- .../20-usage/22-conditional-execution.md | 4 +- .../version-0.15/20-usage/40-secrets.md | 2 +- .../30-administration/40-encryption.md | 11 +- .../samples/sample_8_network_mode/README.md | 8 +- 52 files changed, 327 insertions(+), 607 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index e9b02033b0a..bba356cea09 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -18,9 +18,6 @@ repos: rev: v0.37.0 hooks: - id: markdownlint - args: [--rules, sentences-per-line] - additional_dependencies: [sentences-per-line] - exclude: '^docs/versioned_docs/.*$' - repo: https://github.com/mrtazz/checkmake rev: 0.2.2 hooks: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94a2bb52cb7..1d681f945cb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,8 +22,7 @@ For security reasons, Maintainers must use 2FA for their accounts and if possibl Since Woodpecker is a pure community organization without any company support, to keep the development healthy we will elect two owners every year.\ This can also happen when a owner propose a vote or the majority of the maintainers do so.\ -All maintainers may vote to elect up to two candidates. -When the new owners have been elected, the old owners will give up ownership to the newly elected owners. +All maintainers may vote to elect up to two candidates. When the new owners have been elected, the old owners will give up ownership to the newly elected owners. If an owner is unable to do so, the other owners will assist in ceding ownership to the newly elected owners. For security reasons, Owners must use 2FA.\ @@ -47,16 +46,20 @@ they served: ## Code Review -Once code review starts on your PR, do not rebase nor squash your branch as it makes it difficult to review the new changes. -Only if there is a need, sync your branch by merging the base branch into yours. -Don't worry about merge commits messing up your tree as the final merge process squashes all commits into one, with the visible commit message (first line) being the PR title + PR index and description being the PR's first comment. +Once code review starts on your PR, do not rebase nor squash your branch as it makes it +difficult to review the new changes. Only if there is a need, sync your branch by merging +the base branch into yours. Don't worry about merge commits messing up your tree as +the final merge process squashes all commits into one, with the visible commit message (first +line) being the PR title + PR index and description being the PR's first comment. -Once your PR gets approved, don't worry about keeping it up-to-date or breaking builds (unless there's a merge conflict or a request is made by a maintainer to make modifications). -It is the maintainer team's responsibility from this point to get it merged. +Once your PR gets approved, don't worry about keeping it up-to-date or breaking +builds (unless there's a merge conflict or a request is made by a maintainer to make +modifications). It is the maintainer team's responsibility from this point to get it merged. ## 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. +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. ## Development diff --git a/SECURITY.md b/SECURITY.md index f9841655d0d..2491fe0cc40 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -7,5 +7,4 @@ If you discover a security issue, please bring it to their attention right away! 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. +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/README.md b/docs/README.md index a67a886c59e..673bfe22c2a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,8 +14,7 @@ pnpm install pnpm start ``` -This command starts a local development server and opens up a browser window. -Most changes are reflected live without having to restart the server. +This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. ## Build diff --git a/docs/blog/2023-06-11-hello-blog/index.md b/docs/blog/2023-06-11-hello-blog/index.md index 612da975e87..44436794ef7 100644 --- a/docs/blog/2023-06-11-hello-blog/index.md +++ b/docs/blog/2023-06-11-hello-blog/index.md @@ -1,6 +1,6 @@ --- title: Welcome Woodpecker's blog -description: This our first post on Woodpecker +description: This our first post on Woodpecker. slug: hello-blog authors: - name: Anbraten @@ -11,14 +11,12 @@ tags: [hello, woodpecker] hide_table_of_contents: false --- -Welcome to this blog. -This is our first post on this blog ... +Welcome to this blog. This is our first post on this blog ... In the future we will post about our releases and other things like tutorials. -We are currently working on the `1.0.0` release of Woodpecker. -This release will include a lot of new features and improvements which most of you probably already tested using the `next` tag. +We are currently working on the `1.0.0` release of Woodpecker. This release will include a lot of new features and improvements which most of you probably already tested using the `next` tag. If you have any suggestions or ideas for posts, feel free to open an issue in the [GitHub repository](https://github.com/woodpecker-ci/woodpecker). diff --git a/docs/docs/10-intro.md b/docs/docs/10-intro.md index d1f88bf29bf..cc28b1f86d3 100644 --- a/docs/docs/10-intro.md +++ b/docs/docs/10-intro.md @@ -1,7 +1,6 @@ # Welcome to Woodpecker -Woodpecker is a simple CI engine with great extensibility. -It focuses on executing pipelines inside [containers](https://opencontainers.org/). +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) diff --git a/docs/docs/20-usage/10-intro.md b/docs/docs/20-usage/10-intro.md index 25e19163687..7893696683d 100644 --- a/docs/docs/20-usage/10-intro.md +++ b/docs/docs/20-usage/10-intro.md @@ -2,12 +2,9 @@ ## 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, ...). +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. +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) @@ -16,14 +13,13 @@ When you push code to your repository, open a pull request, or create a tag, you 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. +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. +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. @@ -73,5 +69,4 @@ steps: ## 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. +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/docs/20-usage/15-terminiology/index.md b/docs/docs/20-usage/15-terminiology/index.md index cbf2d9d67ac..4640ede350d 100644 --- a/docs/docs/20-usage/15-terminiology/index.md +++ b/docs/docs/20-usage/15-terminiology/index.md @@ -12,16 +12,11 @@ - **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. +- **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). +- **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. @@ -30,23 +25,18 @@ - **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. +- **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]. +- **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: +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()` +- 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** diff --git a/docs/docs/20-usage/20-workflow-syntax.md b/docs/docs/20-usage/20-workflow-syntax.md index b1219fb6f0e..58c6bd5efc7 100644 --- a/docs/docs/20-usage/20-workflow-syntax.md +++ b/docs/docs/20-usage/20-workflow-syntax.md @@ -1,8 +1,6 @@ # 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. +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: @@ -21,8 +19,7 @@ steps: - npm run build ``` -In the above example we define two steps, `frontend` and `backend`. -The names of these steps are completely arbitrary. +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: @@ -45,8 +42,7 @@ 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. +Woodpecker gives the ability to skip individual commits by adding `[SKIP CI]` or `[CI SKIP]` to the commit message. Note this is case-insensitive. ```sh git commit -m "updated README [CI SKIP]" @@ -54,8 +50,7 @@ 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. +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 @@ -118,8 +113,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: +Woodpecker does not automatically upgrade container images. Example configuration to always pull the latest image when updates are available: ```diff steps: @@ -143,9 +137,7 @@ Commands of every step are executed serially as if you would enter them into you + - 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: +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: ```sh #!/bin/sh @@ -155,15 +147,13 @@ 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: +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: ```sh docker run --entrypoint=build.sh golang ``` -> Please note that only build steps can define commands. -> You cannot use commands with plugins or services. +> Please note that only build steps can define commands. You cannot use commands with plugins or services. ### `environment` @@ -173,16 +163,13 @@ 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. +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. +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: @@ -196,9 +183,7 @@ If Woodpecker encounters an error while executing the step, it will report it as ### `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: +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: @@ -245,8 +230,7 @@ steps: + - 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. +> 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`: @@ -262,8 +246,7 @@ 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: +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 `/` @@ -332,8 +315,7 @@ when: #### `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: +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: @@ -423,8 +405,7 @@ when: #### `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. +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. @@ -465,9 +446,7 @@ when: ### `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. +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: @@ -491,13 +470,11 @@ Example parallel configuration: 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. +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. +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). @@ -513,15 +490,13 @@ Using `directory`, you can set a subdirectory of your repository or an absolute ## `services` -Woodpecker can provide service containers. -They can for example be used to run databases or cache containers during the execution of workflow. +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. +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 @@ -542,8 +517,7 @@ The workspace can be customized using the workspace block in the YAML file: - 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. +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: @@ -571,9 +545,7 @@ 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. +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: @@ -588,24 +560,18 @@ git clone https://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. +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. +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. +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. +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: @@ -626,14 +592,11 @@ steps: ### 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`. +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`. +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: @@ -651,9 +614,7 @@ For more details and examples check the [Advanced usage docs](./90-advanced-usag ## `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. +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: @@ -727,9 +688,7 @@ 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: +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 @@ -737,8 +696,7 @@ 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. +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` @@ -774,8 +732,7 @@ Example conditional execution by branch: 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. +> 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`: @@ -889,22 +846,17 @@ when: ## `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. +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. +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. +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. +> 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: diff --git a/docs/docs/20-usage/25-workflows.md b/docs/docs/20-usage/25-workflows.md index 3e35d1bac92..0d1523109e5 100644 --- a/docs/docs/20-usage/25-workflows.md +++ b/docs/docs/20-usage/25-workflows.md @@ -1,17 +1,14 @@ # 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. +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. +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. +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). @@ -24,8 +21,7 @@ You can also set some custom path like `.my-ci/pipelines/` instead of `.woodpeck ## 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. +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). ::: @@ -96,11 +92,9 @@ Each workflow will report its own status back to your forge. 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. +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`. +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: diff --git a/docs/docs/20-usage/30-matrix-workflows.md b/docs/docs/20-usage/30-matrix-workflows.md index 1f094076365..9ec8851848c 100644 --- a/docs/docs/20-usage/30-matrix-workflows.md +++ b/docs/docs/20-usage/30-matrix-workflows.md @@ -1,7 +1,6 @@ # 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. +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: @@ -31,8 +30,7 @@ matrix: ## 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: +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: diff --git a/docs/docs/20-usage/40-secrets.md b/docs/docs/20-usage/40-secrets.md index c0f8da4b818..83b9493131d 100644 --- a/docs/docs/20-usage/40-secrets.md +++ b/docs/docs/20-usage/40-secrets.md @@ -1,13 +1,10 @@ # 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 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. 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. -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. +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. @@ -40,8 +37,7 @@ steps: + from_secret: secret_token ``` -Please note parameter expressions are subject to pre-processing. -When using secrets in parameter expressions they should be escaped. +Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped. ```diff steps: @@ -61,8 +57,7 @@ Secrets are added to the Woodpecker in the UI or with the CLI. ## 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: +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: @@ -77,8 +72,7 @@ steps: ## Pull Requests -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. +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. ```diff woodpecker-cli secret add \ @@ -91,20 +85,15 @@ woodpecker-cli secret add \ -value ``` -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. +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. +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. ## 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). +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 \ @@ -147,8 +136,7 @@ woodpecker-cli secret add \ -value ``` -Loading secrets from file using curl `@` syntax. -This is the recommended approach for loading secrets from file to preserve newlines: +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 \ diff --git a/docs/docs/20-usage/41-registries.md b/docs/docs/20-usage/41-registries.md index 9970dd30f35..f0a69d6b668 100644 --- a/docs/docs/20-usage/41-registries.md +++ b/docs/docs/20-usage/41-registries.md @@ -1,15 +1,12 @@ # 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. +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. +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: @@ -22,9 +19,7 @@ Example configuration using a private image: - 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. +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: @@ -51,8 +46,7 @@ For specific details on configuring access to Google Container Registry, please ## Local Images :::warning -For this, privileged rights are needed only available to admins. -In addition, this only works when using a single agent. +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. diff --git a/docs/docs/20-usage/45-cron.md b/docs/docs/20-usage/45-cron.md index 3654a422533..f90c77c1adb 100644 --- a/docs/docs/20-usage/45-cron.md +++ b/docs/docs/20-usage/45-cron.md @@ -23,8 +23,7 @@ To configure cron jobs you need at least push access to the repository. ![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. + 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 * * * *` ... diff --git a/docs/docs/20-usage/50-environment.md b/docs/docs/20-usage/50-environment.md index ee692d4deff..3dd5d801d18 100644 --- a/docs/docs/20-usage/50-environment.md +++ b/docs/docs/20-usage/50-environment.md @@ -1,8 +1,6 @@ # 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: +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: @@ -17,8 +15,7 @@ steps: - 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. +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: @@ -32,8 +29,7 @@ steps: - 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: +> 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: @@ -48,8 +44,7 @@ steps: ## 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. +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 | | -------------------------------- | -------------------------------------------------------------------------------------------- | @@ -131,15 +126,14 @@ These are injected into your pipeline step and plugins containers, at runtime. | `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_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. +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: @@ -166,8 +160,7 @@ steps: ## 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. +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: @@ -191,9 +184,7 @@ steps: ## 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. +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 | | ------------------ | ------------------------------------------------ | diff --git a/docs/docs/20-usage/51-plugins/10-plugins.md b/docs/docs/20-usage/51-plugins/10-plugins.md index 983640ee3a1..48977c9a849 100644 --- a/docs/docs/20-usage/51-plugins/10-plugins.md +++ b/docs/docs/20-usage/51-plugins/10-plugins.md @@ -1,7 +1,6 @@ # 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. +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. @@ -29,8 +28,7 @@ steps: ## Plugin Isolation -Plugins are just pipeline steps. -They share the build workspace, mounted as a volume, and therefore have access to your source tree. +Plugins are just pipeline steps. They share the build workspace, mounted as a volume, and therefore have access to your source tree. ## Finding Plugins @@ -39,8 +37,7 @@ 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. +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/docs/20-usage/51-plugins/20-sample-plugin.md b/docs/docs/20-usage/51-plugins/20-sample-plugin.md index 805d1d4cb0e..317303e76c3 100644 --- a/docs/docs/20-usage/51-plugins/20-sample-plugin.md +++ b/docs/docs/20-usage/51-plugins/20-sample-plugin.md @@ -42,8 +42,7 @@ 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. +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 . diff --git a/docs/docs/20-usage/60-services.md b/docs/docs/20-usage/60-services.md index 1442c565efa..df2467200b7 100644 --- a/docs/docs/20-usage/60-services.md +++ b/docs/docs/20-usage/60-services.md @@ -24,8 +24,7 @@ services: ## 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. +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: @@ -41,8 +40,7 @@ services: ## 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. +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: @@ -66,8 +64,7 @@ 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. +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: diff --git a/docs/docs/20-usage/70-volumes.md b/docs/docs/20-usage/70-volumes.md index a5cc62ff2cc..297f14ec07e 100644 --- a/docs/docs/20-usage/70-volumes.md +++ b/docs/docs/20-usage/70-volumes.md @@ -1,11 +1,9 @@ # 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. +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. +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 @@ -21,9 +19,7 @@ steps: + - /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. +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 ] diff --git a/docs/docs/20-usage/71-project-settings.md b/docs/docs/20-usage/71-project-settings.md index 66fba5c4a8d..319a07e6101 100644 --- a/docs/docs/20-usage/71-project-settings.md +++ b/docs/docs/20-usage/71-project-settings.md @@ -6,28 +6,22 @@ As the owner of a project in Woodpecker you can change project related settings ## 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/`. +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. +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. +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. +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 @@ -35,23 +29,17 @@ If you set your project to trusted, a pipeline step and by this the underlying c :::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 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. +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. +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. diff --git a/docs/docs/20-usage/80-badges.md b/docs/docs/20-usage/80-badges.md index 7d536f505c3..1edfcfd4952 100644 --- a/docs/docs/20-usage/80-badges.md +++ b/docs/docs/20-usage/80-badges.md @@ -1,7 +1,6 @@ # 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. +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 @@ -9,8 +8,7 @@ These badges can be added to your website or project readme file to display the :///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. +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 diff --git a/docs/docs/20-usage/90-advanced-usage.md b/docs/docs/20-usage/90-advanced-usage.md index 62881987f70..2edad5d2474 100644 --- a/docs/docs/20-usage/90-advanced-usage.md +++ b/docs/docs/20-usage/90-advanced-usage.md @@ -131,5 +131,4 @@ services: # ... ``` -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. +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/docs/30-administration/00-deployment/00-overview.md b/docs/docs/30-administration/00-deployment/00-overview.md index 4b2ed213ea7..762bfade903 100644 --- a/docs/docs/30-administration/00-deployment/00-overview.md +++ b/docs/docs/30-administration/00-deployment/00-overview.md @@ -47,14 +47,11 @@ See the complete reference for all supported forges [here](../11-forges/10-overv ## 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. +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) +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 @@ -69,8 +66,7 @@ In the case you need to use Woodpecker with a URL path prefix (like: ://` format. -Please omit trailing slashes: +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 @@ -58,9 +55,7 @@ services: + - 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. +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 @@ -75,9 +70,7 @@ services: + - 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: +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 @@ -105,8 +98,7 @@ services: + - /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: +Agents require the server address for agent-to-server communication. The agent connects to the server's gRPC port: ```diff # docker-compose.yml @@ -119,9 +111,7 @@ services: + - 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`: +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 diff --git a/docs/docs/30-administration/10-server-config.md b/docs/docs/30-administration/10-server-config.md index 65806b463c4..9cf2a879ac6 100644 --- a/docs/docs/30-administration/10-server-config.md +++ b/docs/docs/30-administration/10-server-config.md @@ -4,8 +4,7 @@ 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. +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: @@ -74,11 +73,9 @@ services: ## 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. +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. +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 @@ -116,13 +113,9 @@ services: 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. +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. +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 @@ -201,8 +194,7 @@ The following list describes all available server configuration options. > Default: empty -Configures the logging level. -Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty. +Configures the logging level. Possible values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, `disabled` and empty. ### `WOODPECKER_LOG_XORM` @@ -320,8 +312,7 @@ Read the value for `WOODPECKER_GRPC_SECRET` from the specified filepath. > Default: empty -Configures an unprotected metrics endpoint. -An empty value disables the metrics endpoint completely. +Configures an unprotected metrics endpoint. An empty value disables the metrics endpoint completely. Example: `:9001` @@ -359,8 +350,7 @@ Enable to allow user registration. > 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. +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` @@ -399,8 +389,7 @@ a user can log into Woodpecker, without re-authentication. > 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! +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. @@ -231,13 +213,11 @@ Example: `WOODPECKER_NETWORK=network1,network2` --> ### `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_KEEPALIVE_MIN_TIME` - > Default: empty Server-side enforcement policy on the minimum amount of time a client should wait before sending a keepalive ping. @@ -245,19 +225,16 @@ Server-side enforcement policy on the minimum amount of time a client should wai 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 @@ -269,13 +246,11 @@ WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker? ``` ### `WOODPECKER_PROMETHEUS_AUTH_TOKEN` - > Default: empty Token to secure the Prometheus metrics endpoint. ### `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. @@ -283,37 +258,31 @@ Context prefix Woodpecker will use to publish status messages to SCM. You probab --- ### `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. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/20-github.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/20-github.md index 30d67fe9e67..6f8d41e2e0c 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/20-github.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/20-github.md @@ -32,37 +32,31 @@ Please use this screenshot for reference: 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. This is used to authorize access. ### `WOODPECKER_GITHUB_SECRET` - > Default: empty Configures the GitHub OAuth client secret. This is used to authorize access. ### `WOODPECKER_GITHUB_MERGE_REF` - > Default: `true` TODO ### `WOODPECKER_GITHUB_SKIP_VERIFY` - > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/30-gitea.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/30-gitea.md index 82a89ad6c57..6f564d8352e 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/30-gitea.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/30-gitea.md @@ -25,47 +25,41 @@ services: 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 important 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_SECRET` - > Default: empty Configures the Gitea OAuth client secret. This is used to authorize access. ### `WOODPECKER_GITEA_SKIP_VERIFY` - > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/40-gitlab.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/40-gitlab.md index 26874d2d057..14a5d01cce7 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/40-gitlab.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/40-gitlab.md @@ -32,31 +32,26 @@ If you run the Woodpecker CI server on the same host as the GitLab instance, you 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_SECRET` - > Default: empty Configures the GitLab OAuth client secret. This is used to authorize access. ### `WOODPECKER_GITLAB_SKIP_VERIFY` - > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/50-bitbucket.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/50-bitbucket.md index 8a61fa9fc6b..5065e2e3122 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/50-bitbucket.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/50-bitbucket.md @@ -44,19 +44,16 @@ Webhooks:Read and Write 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 id. This is used to authorize access. ### `WOODPECKER_BITBUCKET_SECRET` - > Default: empty Configures the Bitbucket OAuth client secret. This is used to authorize access. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/60-bitbucket_server.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/60-bitbucket_server.md index 4e1ccc4931d..58b24307ef3 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/60-bitbucket_server.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/60-bitbucket_server.md @@ -94,56 +94,48 @@ Woodpecker uses `git+https` to clone repositories, however, Bitbucket Server doe You must register your application with Bitbucket Server in order to generate a consumer key. Navigate to your account settings and choose Applications from the menu, and click Register new application. Now copy & paste the text value from `/etc/bitbucket/key.pub` into the `Public Key` in the incoming link part of the application registration. -Please use as the Authorization callback URL. +Please use http://woodpecker.mycompany.com/authorize as the Authorization callback URL. ## 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_STASH` - > Default: `false` Enables the Bitbucket Server driver. ### `WOODPECKER_STASH_URL` - > Default: empty Configures the Bitbucket Server address. ### `WOODPECKER_STASH_CONSUMER_KEY` - > Default: empty Configures your Bitbucket Server consumer key. ### `WOODPECKER_STASH_CONSUMER_RSA` - > Default: empty Configures the path to your Bitbucket Server private key file. ### `WOODPECKER_STASH_CONSUMER_RSA_STRING` - > Default: empty Configures your Bitbucket Server private key. ### `WOODPECKER_STASH_GIT_USERNAME` - > Default: empty This username is used to authenticate and clone all private repositories. ### `WOODPECKER_STASH_GIT_PASSWORD` - > Default: empty The password is used to authenticate and clone all private repositories. ### `WOODPECKER_STASH_SKIP_VERIFY` - > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/70-gogs.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/70-gogs.md index 8eb33f493e7..a165bea6dec 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/70-gogs.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/70-gogs.md @@ -5,37 +5,31 @@ 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_GOGS` - > Default: `false` Enables the Gogs driver. ### `WOODPECKER_GOGS_URL` - > Default: `https://github.com` Configures the Gogs server address. ### `WOODPECKER_GOGS_GIT_USERNAME` - > Default: empty This username is used to authenticate and clone all private repositories. ### `WOODPECKER_GOGS_GIT_PASSWORD` - > Default: empty The password is used to authenticate and clone all private repositories. ### `WOODPECKER_GOGS_PRIVATE_MODE` - > Default: `false` TODO ### `WOODPECKER_GOGS_SKIP_VERIFY` - > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/11-vcs/80-coding.md b/docs/versioned_docs/version-0.15/30-administration/11-vcs/80-coding.md index ac2cda97750..751c090205d 100644 --- a/docs/versioned_docs/version-0.15/30-administration/11-vcs/80-coding.md +++ b/docs/versioned_docs/version-0.15/30-administration/11-vcs/80-coding.md @@ -5,55 +5,46 @@ 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_CODING` - > Default: `false` Enables the Coding driver. ### `WOODPECKER_CODING_URL` - > Default: `https://coding.net` Configures the Coding server address. ### `WOODPECKER_CODING_CLIENT` - > Default: empty Configures the Coding OAuth client id. This is used to authorize access. ### `WOODPECKER_CODING_SECRET` - > Default: empty Configures the Coding OAuth client secret. This is used to authorize access. ### `WOODPECKER_CODING_SCOPE` - > Default: `user, project, project:depot` Comma-separated list of OAuth scopes. ### `WOODPECKER_CODING_GIT_MACHINE` - > Default: `git.coding.net` TODO ### `WOODPECKER_CODING_GIT_USERNAME` - > Default: empty This username is used to authenticate and clone all private repositories. ### `WOODPECKER_CODING_GIT_PASSWORD` - > Default: empty The password is used to authenticate and clone all private repositories. ### `WOODPECKER_CODING_SKIP_VERIFY` - > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md b/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md index ad3343cb3ad..cf3afae54ef 100644 --- a/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md +++ b/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md @@ -41,7 +41,7 @@ services: When building your pipelines as long as you have set the platform or filter, builds can be made to only run code on certain agents. -```yaml +``` - WOODPECKER_HOSTNAME=mycompany-ci-01.example.com - WOODPECKER_FILTER= ``` @@ -75,96 +75,81 @@ pipeline: See [Conditionals Pipeline](../20-usage/20-pipeline-syntax.md#step-when---conditional-execution) syntax for more + ## All agent configuration options Here is the full list of configuration options and their default variables. - -### `DOCKER_HOST` - -> Default: empty +#### `DOCKER_HOST` +> Default: empty Point to an alternate socket file or host. For example, "unix:////run/podman/podman.sock" ### `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_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_MAX_PROCS` - > Default: `1` Configures the number of parallel builds. ### `WOODPECKER_HEALTHCHECK` - > Default: `true` Enable healthcheck endpoint. ### `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` or `docker`. diff --git a/docs/versioned_docs/version-0.15/30-administration/60-ssl.md b/docs/versioned_docs/version-0.15/30-administration/60-ssl.md index 9a0e8c799b1..4357e0ca736 100644 --- a/docs/versioned_docs/version-0.15/30-administration/60-ssl.md +++ b/docs/versioned_docs/version-0.15/30-administration/60-ssl.md @@ -3,6 +3,7 @@ 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. @@ -33,7 +34,7 @@ Note that Woodpecker uses the hostname from the `WOODPECKER_HOST` environment va Woodpecker writes the certificates to the below directory: -```sh +``` /var/lib/woodpecker/golang-autocert ``` diff --git a/docs/versioned_docs/version-0.15/30-administration/70-proxy.md b/docs/versioned_docs/version-0.15/30-administration/70-proxy.md index a2b7096ba6b..cd6381bfa1f 100644 --- a/docs/versioned_docs/version-0.15/30-administration/70-proxy.md +++ b/docs/versioned_docs/version-0.15/30-administration/70-proxy.md @@ -1,7 +1,6 @@ # Proxy ## Apache - This guide provides a brief overview for installing Woodpecker server behind the Apache2 webserver. This is an example configuration: ```nohighlight @@ -89,10 +88,9 @@ woodpecker.example.com { ``` ## Ngrok - After installing [ngrok](https://ngrok.com/), open a new console and run: -```sh +``` ngrok http 8000 ``` diff --git a/docs/versioned_docs/version-0.15/30-administration/80-kubernetes.md b/docs/versioned_docs/version-0.15/30-administration/80-kubernetes.md index 7a0bf50f40d..6132a51897a 100644 --- a/docs/versioned_docs/version-0.15/30-administration/80-kubernetes.md +++ b/docs/versioned_docs/version-0.15/30-administration/80-kubernetes.md @@ -56,7 +56,6 @@ Build step containers are started up within the agent pod. Warning: this approach requires `privileged` access. Also DinD's reputation hasn't been too high in the early days of Docker - this changed somewhat over time, and there are organizations succeeding with this approach. server.yaml - ```yaml apiVersion: apps/v1 kind: Deployment @@ -154,7 +153,6 @@ spec: ``` agent.yaml - ```yaml apiVersion: apps/v1 kind: Deployment @@ -212,3 +210,4 @@ spec: - name: sock-dir emptyDir: {} ``` + diff --git a/docs/versioned_docs/version-0.15/30-administration/90-prometheus.md b/docs/versioned_docs/version-0.15/30-administration/90-prometheus.md index 24761f5a6a4..75d1aa1f49f 100644 --- a/docs/versioned_docs/version-0.15/30-administration/90-prometheus.md +++ b/docs/versioned_docs/version-0.15/30-administration/90-prometheus.md @@ -34,7 +34,7 @@ scrape_configs: List of prometheus metrics specific to Woodpecker: -```yaml +``` # HELP woodpecker_build_count Build count. # TYPE woodpecker_build_count counter woodpecker_build_count{branch="master",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3 diff --git a/docs/versioned_docs/version-0.15/40-cli.md b/docs/versioned_docs/version-0.15/40-cli.md index d9477013367..ca62a6bbc0a 100644 --- a/docs/versioned_docs/version-0.15/40-cli.md +++ b/docs/versioned_docs/version-0.15/40-cli.md @@ -1,7 +1,6 @@ # CLI ```docker run --rm woodpeckerci/woodpecker-cli:v0.15``` - ```bash NAME: woodpecker-cli - command line utility diff --git a/docs/versioned_docs/version-0.15/80-downloads.md b/docs/versioned_docs/version-0.15/80-downloads.md index cfc5f409aa3..4c22844a5df 100644 --- a/docs/versioned_docs/version-0.15/80-downloads.md +++ b/docs/versioned_docs/version-0.15/80-downloads.md @@ -13,11 +13,10 @@ To find out more about the differences between the two releases, please read the ## 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 latest patch version of a specific minor release (see [Semver](https://semver.org/lang/)) -- The `next` images are based on the current master branch and should not be used for production environments +* The `latest` image is the latest stable release +* The `vX.X.X` images are stable releases +* The `vX.X` images are based on the latest patch version of a specific minor release (see [Semver](https://semver.org/lang/)) +* The `next` images are based on the current master branch and should not be used for production environments ``` bash # server diff --git a/docs/versioned_docs/version-0.15/91-migrations.md b/docs/versioned_docs/version-0.15/91-migrations.md index 76858ad4590..8c4ca17856d 100644 --- a/docs/versioned_docs/version-0.15/91-migrations.md +++ b/docs/versioned_docs/version-0.15/91-migrations.md @@ -54,7 +54,6 @@ Some versions need some changes to the server configuration or the pipeline conf - `drone.sqlite` -> `woodpecker.sqlite` - Plugin Settings moved into `settings` section: - ```diff pipeline: something: diff --git a/docs/versioned_docs/version-0.15/92-development/01-getting-started.md b/docs/versioned_docs/version-0.15/92-development/01-getting-started.md index fd187801bea..df18218976d 100644 --- a/docs/versioned_docs/version-0.15/92-development/01-getting-started.md +++ b/docs/versioned_docs/version-0.15/92-development/01-getting-started.md @@ -8,13 +8,12 @@ Install Golang (>=1.16) 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. () +> 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. (https://www.gnu.org/software/make/) 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` + - 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 & Yarn diff --git a/docs/versioned_docs/version-0.15/92-development/03-ui.md b/docs/versioned_docs/version-0.15/92-development/03-ui.md index d48b4dff7eb..9491a7160a9 100644 --- a/docs/versioned_docs/version-0.15/92-development/03-ui.md +++ b/docs/versioned_docs/version-0.15/92-development/03-ui.md @@ -3,7 +3,6 @@ To develop the UI you need to install [Node.js and Yarn](./01-getting-started.md#nodejs--yarn). 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 `yarn 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 `yarn 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. diff --git a/docs/versioned_docs/version-0.15/92-development/ui-proxy.svg b/docs/versioned_docs/version-0.15/92-development/ui-proxy.svg index 79809ffa197..6ccb7445870 100644 --- a/docs/versioned_docs/version-0.15/92-development/ui-proxy.svg +++ b/docs/versioned_docs/version-0.15/92-development/ui-proxy.svg @@ -1,6 +1,6 @@ - + - forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler) + forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler) \ No newline at end of file diff --git a/docs/versioned_docs/version-1.0/20-usage/10-intro.md b/docs/versioned_docs/version-1.0/20-usage/10-intro.md index dc4d4070e57..fcefb8195c5 100644 --- a/docs/versioned_docs/version-1.0/20-usage/10-intro.md +++ b/docs/versioned_docs/version-1.0/20-usage/10-intro.md @@ -9,9 +9,9 @@ Webhooks are used to trigger pipeline executions. When you push code to your rep ![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 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 diff --git a/docs/versioned_docs/version-1.0/20-usage/20-pipeline-syntax.md b/docs/versioned_docs/version-1.0/20-usage/20-pipeline-syntax.md index 56484b39e2f..dd8bc6f555b 100644 --- a/docs/versioned_docs/version-1.0/20-usage/20-pipeline-syntax.md +++ b/docs/versioned_docs/version-1.0/20-usage/20-pipeline-syntax.md @@ -40,7 +40,7 @@ steps: Keep in mind the name is optional, if not added the steps will be numerated. -## Skip Commits +### Skip Commits Woodpecker gives the ability to skip individual commits by adding `[CI SKIP]` to the commit message. Note this is case-insensitive. @@ -122,7 +122,7 @@ Woodpecker does not automatically upgrade container images. Example configuratio + pull: true ``` -#### Images from private registries +##### Images from private registries You must provide registry credentials on the UI in order to pull private pipeline images defined in your YAML configuration file. diff --git a/docs/versioned_docs/version-1.0/20-usage/35-advanced-yaml-syntax.md b/docs/versioned_docs/version-1.0/20-usage/35-advanced-yaml-syntax.md index 8272ddb425d..b5ea914c97b 100644 --- a/docs/versioned_docs/version-1.0/20-usage/35-advanced-yaml-syntax.md +++ b/docs/versioned_docs/version-1.0/20-usage/35-advanced-yaml-syntax.md @@ -5,7 +5,6 @@ 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: - ```yml steps: test: diff --git a/docs/versioned_docs/version-1.0/20-usage/40-secrets.md b/docs/versioned_docs/version-1.0/20-usage/40-secrets.md index bd4ea95021b..613a03fdb1e 100644 --- a/docs/versioned_docs/version-1.0/20-usage/40-secrets.md +++ b/docs/versioned_docs/version-1.0/20-usage/40-secrets.md @@ -28,6 +28,7 @@ steps: + from_secret: secret_token ``` + Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped. ```diff diff --git a/docs/versioned_docs/version-1.0/20-usage/71-project-settings.md b/docs/versioned_docs/version-1.0/20-usage/71-project-settings.md index 319a07e6101..d65552182e9 100644 --- a/docs/versioned_docs/version-1.0/20-usage/71-project-settings.md +++ b/docs/versioned_docs/version-1.0/20-usage/71-project-settings.md @@ -21,7 +21,7 @@ Enables handling webhook's pull request event. If disabled, then pipeline won't ### 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. +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 diff --git a/docs/versioned_docs/version-1.0/30-administration/00-setup.md b/docs/versioned_docs/version-1.0/30-administration/00-setup.md index d98d9b70147..a5dbb1c8a1a 100644 --- a/docs/versioned_docs/version-1.0/30-administration/00-setup.md +++ b/docs/versioned_docs/version-1.0/30-administration/00-setup.md @@ -6,9 +6,9 @@ A Woodpecker deployment consists of two parts: - 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 builds in parallel. - +> > You can add more agents to increase the number of parallel steps 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? @@ -192,4 +192,4 @@ A [Prometheus endpoint](./90-prometheus.md) is exposed. 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_URL`](./10-server-config.md#woodpecker_root_url). +In the case you need to use Woodpecker with a URL path prefix (like: https://example.org/woodpecker/), you can use the option [`WOODPECKER_ROOT_URL`](./10-server-config.md#woodpecker_root_url). diff --git a/docs/versioned_docs/version-1.0/30-administration/10-server-config.md b/docs/versioned_docs/version-1.0/30-administration/10-server-config.md index 391fa2ff4f5..9f86cb1c0e8 100644 --- a/docs/versioned_docs/version-1.0/30-administration/10-server-config.md +++ b/docs/versioned_docs/version-1.0/30-administration/10-server-config.md @@ -20,9 +20,9 @@ services: + - 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 +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 @@ -153,8 +153,7 @@ 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 - +##### woodpecker.css ```css .banner-message { position: absolute; @@ -169,7 +168,7 @@ The examples below show how to place a banner message in the top navigation bar } ``` -### woodpecker.js +##### woodpecker.js ```javascript // place/copy a minified version of jQuery or ZeptoJS here ... @@ -180,42 +179,37 @@ $().ready(function(){ }); ``` + ## 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_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. @@ -223,7 +217,6 @@ Server fully qualified URL of the user-facing hostname. Example: `WOODPECKER_HOST=http://woodpecker.example.org` ### `WOODPECKER_WEBHOOK_HOST` - > Default: value from `WOODPECKER_HOST` config env Server fully qualified URL of the Webhook-facing hostname. @@ -231,19 +224,16 @@ Server fully qualified URL of the Webhook-facing hostname. 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. @@ -251,7 +241,6 @@ 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. @@ -259,7 +248,6 @@ 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. @@ -269,7 +257,6 @@ 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. @@ -279,31 +266,26 @@ 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. @@ -311,7 +293,6 @@ Configures an unprotected metrics endpoint. An empty value disables the metrics Example: `:9001` ### `WOODPECKER_ADMIN` - > Default: empty Comma-separated list of admin accounts. @@ -319,7 +300,6 @@ Comma-separated list of admin accounts. Example: `WOODPECKER_ADMIN=user1,user2` ### `WOODPECKER_ORGS` - > Default: empty Comma-separated list of approved organizations. @@ -327,7 +307,6 @@ Comma-separated list of approved organizations. Example: `org1,org2` ### `WOODPECKER_REPO_OWNERS` - > Default: empty Comma-separated list of syncable repo owners. ??? @@ -335,49 +314,41 @@ Comma-separated list of syncable repo owners. ??? Example: `user1,user2` ### `WOODPECKER_OPEN` - > Default: `false` Enable to allow user registration. ### `WOODPECKER_DOCS` - > Default: `https://woodpecker-ci.org/` Link to documentation in the UI. ### `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/master/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. @@ -386,7 +357,6 @@ 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/master/shared/constant/constant.go) Docker images to run in privileged mode. Only change if you are sure what you do! @@ -401,7 +371,6 @@ Example: `WOODPECKER_VOLUME=/path/on/host:/path/in/container:rw`| --> ### `WOODPECKER_DOCKER_CONFIG` - > Default: empty Configures a specific private registry config for all pipelines. @@ -423,19 +392,16 @@ Example: `WOODPECKER_NETWORK=network1,network2` --> ### `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. @@ -443,19 +409,16 @@ Server-side enforcement policy on the minimum amount of time a client should wai 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 @@ -467,56 +430,47 @@ WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/woodpecker? ``` ### `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 }}` Template for the status messages published to forges, uses [Go templates](https://pkg.go.dev/text/template) as template language. @@ -531,57 +485,50 @@ Supported variables: --- ### `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` +### `WOODPECKER_CONFIG_SERVICE_ENDPOINT` > Default: `` Specify a configuration service endpoint, see [Configuration Extension](./100-external-configuration-api.md) -### `WOODPECKER_FORGE_TIMEOUT` +### `WOODPECKER_FORGE_TIMEOUT` > Default: 3sec Specify how many seconds before timeout when fetching the Woodpecker configuration from a Forge ### `WOODPECKER_ROOT_URL` - > Default: `` Server URL path prefix (used for statics loading when having a url path prefix), should start with `/` diff --git a/docs/versioned_docs/version-1.0/30-administration/11-forges/20-github.md b/docs/versioned_docs/version-1.0/30-administration/11-forges/20-github.md index f3203d3d1a5..9ed47580d05 100644 --- a/docs/versioned_docs/version-1.0/30-administration/11-forges/20-github.md +++ b/docs/versioned_docs/version-1.0/30-administration/11-forges/20-github.md @@ -32,49 +32,41 @@ Please use this screenshot for reference: 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. This is used 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` TODO ### `WOODPECKER_GITHUB_SKIP_VERIFY` - > Default: `false` Configure if SSL verification should be skipped. diff --git a/docs/versioned_docs/version-1.0/30-administration/11-forges/30-gitea.md b/docs/versioned_docs/version-1.0/30-administration/11-forges/30-gitea.md index 54e94a65147..24a500d3b3e 100644 --- a/docs/versioned_docs/version-1.0/30-administration/11-forges/30-gitea.md +++ b/docs/versioned_docs/version-1.0/30-administration/11-forges/30-gitea.md @@ -25,59 +25,51 @@ services: 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-1.0/30-administration/11-forges/40-gitlab.md b/docs/versioned_docs/version-1.0/30-administration/11-forges/40-gitlab.md index 6753bfafe45..46b40a0f1a4 100644 --- a/docs/versioned_docs/version-1.0/30-administration/11-forges/40-gitlab.md +++ b/docs/versioned_docs/version-1.0/30-administration/11-forges/40-gitlab.md @@ -32,43 +32,36 @@ If you run the Woodpecker CI server on the same host as the GitLab instance, you 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-1.0/30-administration/11-forges/50-bitbucket.md b/docs/versioned_docs/version-1.0/30-administration/11-forges/50-bitbucket.md index 81f71519b45..909da4d693f 100644 --- a/docs/versioned_docs/version-1.0/30-administration/11-forges/50-bitbucket.md +++ b/docs/versioned_docs/version-1.0/30-administration/11-forges/50-bitbucket.md @@ -44,31 +44,26 @@ Webhooks:Read and Write 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 id. 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 diff --git a/docs/versioned_docs/version-1.0/30-administration/15-agent-config.md b/docs/versioned_docs/version-1.0/30-administration/15-agent-config.md index 4055a561395..94fb03f674a 100644 --- a/docs/versioned_docs/version-1.0/30-administration/15-agent-config.md +++ b/docs/versioned_docs/version-1.0/30-administration/15-agent-config.md @@ -76,109 +76,91 @@ At following startups Agent uses own token only. 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-pipeline-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`, `ssh` or `kubernetes`. diff --git a/docs/versioned_docs/version-1.0/30-administration/22-backends/10-docker.md b/docs/versioned_docs/version-1.0/30-administration/22-backends/10-docker.md index 6eac9395c82..8651d2594ef 100644 --- a/docs/versioned_docs/version-1.0/30-administration/22-backends/10-docker.md +++ b/docs/versioned_docs/version-1.0/30-administration/22-backends/10-docker.md @@ -5,19 +5,16 @@ This is the original backend used with Woodpecker. The docker backend executes e ## 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 diff --git a/docs/versioned_docs/version-1.0/30-administration/22-backends/20-local.md b/docs/versioned_docs/version-1.0/30-administration/22-backends/20-local.md index 0368a9ad4fe..c8c5dbc4eb6 100644 --- a/docs/versioned_docs/version-1.0/30-administration/22-backends/20-local.md +++ b/docs/versioned_docs/version-1.0/30-administration/22-backends/20-local.md @@ -77,6 +77,7 @@ manual clone 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 @@ -114,3 +115,4 @@ labels: steps: [...] ``` + diff --git a/docs/versioned_docs/version-1.0/30-administration/22-backends/30-ssh.md b/docs/versioned_docs/version-1.0/30-administration/22-backends/30-ssh.md index 7d8d5414f5c..79e8dc998b1 100644 --- a/docs/versioned_docs/version-1.0/30-administration/22-backends/30-ssh.md +++ b/docs/versioned_docs/version-1.0/30-administration/22-backends/30-ssh.md @@ -16,31 +16,26 @@ The backend will use a random directory in $TMPDIR to store the clone code and e ## Configuration ### `WOODPECKER_BACKEND_SSH_ADDRESS` - > Default: empty The SSH host to run steps with `ssh` backend. ### `WOODPECKER_BACKEND_SSH_USER` - > Default: empty The SSH user to run steps with `ssh` backend. ### `WOODPECKER_BACKEND_SSH_KEY` - > Default: empty Path to the private SSH key to run steps with `ssh` backend. ### `WOODPECKER_BACKEND_SSH_KEY_PASSWORD` - > Default: empty The password for the private key to run steps with `ssh` backend. ### `WOODPECKER_BACKEND_SSH_PASSWORD` - > Default empty The SSH password to run steps with `ssh` backend. diff --git a/docs/versioned_docs/version-1.0/30-administration/22-backends/40-kubernetes.md b/docs/versioned_docs/version-1.0/30-administration/22-backends/40-kubernetes.md index 7c0bcd5f6a6..9ab79b7e6f2 100644 --- a/docs/versioned_docs/version-1.0/30-administration/22-backends/40-kubernetes.md +++ b/docs/versioned_docs/version-1.0/30-administration/22-backends/40-kubernetes.md @@ -11,37 +11,31 @@ The kubernetes backend executes each step inside a newly created pod. A PVC is a ## Configuration ### `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"}`. @@ -65,7 +59,6 @@ By default the pod will use "kubernetes.io/arch" inferred from top-level "platfo See the [kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for more information on using nodeSelector. Example pipeline configuration: - ```yaml steps: build: diff --git a/docs/versioned_docs/version-1.0/30-administration/40-encryption.md b/docs/versioned_docs/version-1.0/30-administration/40-encryption.md index f9f3132f425..78aab913044 100644 --- a/docs/versioned_docs/version-1.0/30-administration/40-encryption.md +++ b/docs/versioned_docs/version-1.0/30-administration/40-encryption.md @@ -1,6 +1,6 @@ # Secrets encryption -By default, Woodpecker does not encrypt secrets in its database. You can enable encryption +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 @@ -8,7 +8,7 @@ using simple AES key or more advanced [Google TINK](https://developers.google.co ### 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 +`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! @@ -22,48 +22,39 @@ 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 +## 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 +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: - ```shell 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: - ```shell tinkey rotate-keyset --in keyset_v1.json --out keyset_v2.json --key-template AES256_GCM ``` diff --git a/docs/versioned_docs/version-1.0/30-administration/70-proxy.md b/docs/versioned_docs/version-1.0/30-administration/70-proxy.md index 8c6ac2733a8..b57b93442f9 100644 --- a/docs/versioned_docs/version-1.0/30-administration/70-proxy.md +++ b/docs/versioned_docs/version-1.0/30-administration/70-proxy.md @@ -108,6 +108,7 @@ 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. diff --git a/docs/versioned_docs/version-1.0/30-administration/90-prometheus.md b/docs/versioned_docs/version-1.0/30-administration/90-prometheus.md index f2d339b99c6..78e00935173 100644 --- a/docs/versioned_docs/version-1.0/30-administration/90-prometheus.md +++ b/docs/versioned_docs/version-1.0/30-administration/90-prometheus.md @@ -38,7 +38,7 @@ Alternatively, the unprotected `/metrics` endpoint might be exposed on the inter List of Prometheus metrics specific to Woodpecker: -```yaml +``` # HELP woodpecker_pipeline_count Pipeline count. # TYPE woodpecker_pipeline_count counter woodpecker_build_count{branch="master",pipeline="total",repo="woodpecker-ci/woodpecker",status="success"} 3 diff --git a/docs/versioned_docs/version-1.0/40-cli.md b/docs/versioned_docs/version-1.0/40-cli.md index bd38de512cb..3f4b46c1e0d 100644 --- a/docs/versioned_docs/version-1.0/40-cli.md +++ b/docs/versioned_docs/version-1.0/40-cli.md @@ -1,14 +1,14 @@ # CLI -## NAME +# NAME woodpecker-cli - command line utility -## SYNOPSIS +# SYNOPSIS woodpecker-cli -```sh +``` [--log-level]=[value] [--server|-s]=[value] [--token|-t]=[value] @@ -16,11 +16,11 @@ woodpecker-cli **Usage**: -```sh +``` woodpecker-cli [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] ``` -## GLOBAL OPTIONS +# GLOBAL OPTIONS **--log-level**="": set logging level (default: info) @@ -28,7 +28,8 @@ woodpecker-cli [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] **--token, -t**="": server auth token -## COMMANDS + +# COMMANDS ## pipeline, build @@ -303,37 +304,37 @@ execute a local pipeline **--backend-ssh-user**="": backend ssh user -**--commit-author-avatar**="": +**--commit-author-avatar**="": -**--commit-author-email**="": +**--commit-author-email**="": -**--commit-author-name**="": +**--commit-author-name**="": -**--commit-branch**="": +**--commit-branch**="": -**--commit-message**="": +**--commit-message**="": -**--commit-ref**="": +**--commit-ref**="": -**--commit-refspec**="": +**--commit-refspec**="": -**--commit-sha**="": +**--commit-sha**="": -**--env**="": +**--env**="": -**--forge-type**="": +**--forge-type**="": -**--forge-url**="": +**--forge-url**="": **--local**: run from local directory **--log-level**="": set logging level (default: info) -**--netrc-machine**="": +**--netrc-machine**="": -**--netrc-password**="": +**--netrc-password**="": -**--netrc-username**="": +**--netrc-username**="": **--network**="": external networks @@ -343,7 +344,7 @@ execute a local pipeline **--pipeline-finished**="": (default: 0) -**--pipeline-link**="": +**--pipeline-link**="": **--pipeline-number**="": (default: 0) @@ -351,63 +352,63 @@ execute a local pipeline **--pipeline-started**="": (default: 0) -**--pipeline-status**="": +**--pipeline-status**="": -**--pipeline-target**="": +**--pipeline-target**="": -**--prev-commit-author-avatar**="": +**--prev-commit-author-avatar**="": -**--prev-commit-author-email**="": +**--prev-commit-author-email**="": -**--prev-commit-author-name**="": +**--prev-commit-author-name**="": -**--prev-commit-branch**="": +**--prev-commit-branch**="": -**--prev-commit-message**="": +**--prev-commit-message**="": -**--prev-commit-ref**="": +**--prev-commit-ref**="": -**--prev-commit-refspec**="": +**--prev-commit-refspec**="": -**--prev-commit-sha**="": +**--prev-commit-sha**="": **--prev-pipeline-created**="": (default: 0) -**--prev-pipeline-event**="": +**--prev-pipeline-event**="": **--prev-pipeline-finished**="": (default: 0) -**--prev-pipeline-link**="": +**--prev-pipeline-link**="": **--prev-pipeline-number**="": (default: 0) **--prev-pipeline-started**="": (default: 0) -**--prev-pipeline-status**="": +**--prev-pipeline-status**="": **--privileged**="": privileged plugins (default: "plugins/docker", "plugins/gcr", "plugins/ecr", "woodpeckerci/plugin-docker-buildx") **--repo**="": full repo name -**--repo-clone-url**="": +**--repo-clone-url**="": -**--repo-link**="": +**--repo-link**="": -**--repo-private**="": +**--repo-private**="": -**--repo-remote-id**="": +**--repo-remote-id**="": -**--repo-trusted**: +**--repo-trusted**: **--server, -s**="": server address **--step-name**="": (default: 0) -**--system-link**="": (default: ) +**--system-link**="": (default: https://github.com/woodpecker-ci/woodpecker) **--system-name**="": (default: woodpecker) -**--system-platform**="": +**--system-platform**="": **--timeout**="": pipeline timeout (default: 0s) diff --git a/docs/versioned_docs/version-1.0/92-development/01-getting-started.md b/docs/versioned_docs/version-1.0/92-development/01-getting-started.md index 3866d57634c..d5f229ae035 100644 --- a/docs/versioned_docs/version-1.0/92-development/01-getting-started.md +++ b/docs/versioned_docs/version-1.0/92-development/01-getting-started.md @@ -24,13 +24,12 @@ 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. () +> 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. (https://www.gnu.org/software/make/) 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` + - 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 diff --git a/docs/versioned_docs/version-1.0/92-development/03-ui.md b/docs/versioned_docs/version-1.0/92-development/03-ui.md index 5affaed6100..b2a12484723 100644 --- a/docs/versioned_docs/version-1.0/92-development/03-ui.md +++ b/docs/versioned_docs/version-1.0/92-development/03-ui.md @@ -3,7 +3,6 @@ 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. @@ -33,7 +32,7 @@ The following list contains some tools and frameworks used by the Woodpecker UI. ## 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. +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 master branch yet) For more information about translations see [Translations](./07-translations.md). diff --git a/docs/versioned_docs/version-1.0/92-development/05-architecture.md b/docs/versioned_docs/version-1.0/92-development/05-architecture.md index 8f3c15ca769..d0093e24a28 100644 --- a/docs/versioned_docs/version-1.0/92-development/05-architecture.md +++ b/docs/versioned_docs/version-1.0/92-development/05-architecture.md @@ -37,7 +37,7 @@ | `server/shared/**` | TODO: move and split [#974](https://github.com/woodpecker-ci/woodpecker/issues/974) | | `server/web/**` | server SPA | -- `../` = `server/` +* `../` = `server/` ### Agent diff --git a/docs/versioned_docs/version-1.0/92-development/08-swagger.md b/docs/versioned_docs/version-1.0/92-development/08-swagger.md index 2c8871b8ec0..6d8d99f6fb5 100644 --- a/docs/versioned_docs/version-1.0/92-development/08-swagger.md +++ b/docs/versioned_docs/version-1.0/92-development/08-swagger.md @@ -11,23 +11,23 @@ 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 +### 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" +// @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) +// @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 @@ -35,36 +35,35 @@ Here's a typical example of how annotations for Swagger documentation look like. type User struct { ID int64 `json:"id" xorm:"pk autoincr 'user_id'"` // ... -} // @name User +} // @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 +* 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 +More enhanced information you can find here https://github.com/swaggo/swag/blob/master/README.md#declarative-comments-format ### Manual code generation -#### generate the server's Go code containing the Swagger +##### generate the server's Go code containing the Swagger ```shell make generate-swagger ``` -#### update the Markdown in the ./docs folder +##### update the Markdown in the ./docs folder ```shell make docs ``` -#### auto-format swagger related godoc +##### auto-format swagger related godoc ```shell go run github.com/swaggo/swag/cmd/swag@latest fmt -g server/api/z.go @@ -73,5 +72,5 @@ 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. +which means, replace the tab (`\t`) with a space (` `). +See https://github.com/swaggo/swag/pull/1594 == once this is merged and released, the mentioned issue is obsolete. diff --git a/docs/versioned_docs/version-1.0/92-development/09-security.md b/docs/versioned_docs/version-1.0/92-development/09-security.md index 2491fe0cc40..e8b2d95f258 100644 --- a/docs/versioned_docs/version-1.0/92-development/09-security.md +++ b/docs/versioned_docs/version-1.0/92-development/09-security.md @@ -1,9 +1,9 @@ # Security -We take security seriously. +We take security seriously. If you discover a security issue, please bring it to their attention right away! -## Reporting a Vulnerability +### 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). diff --git a/docs/versioned_docs/version-1.0/92-development/ui-proxy.svg b/docs/versioned_docs/version-1.0/92-development/ui-proxy.svg index 79809ffa197..6ccb7445870 100644 --- a/docs/versioned_docs/version-1.0/92-development/ui-proxy.svg +++ b/docs/versioned_docs/version-1.0/92-development/ui-proxy.svg @@ -1,6 +1,6 @@ - + - forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler) + forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler) \ No newline at end of file From 8b8c02a9a565f5a69d201b4d6750ef80cdd41c79 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 31 Oct 2023 08:01:48 +0000 Subject: [PATCH 22/22] [pre-commit.ci] auto fixes from pre-commit.com hooks [CI SKIP] for more information, see https://pre-commit.ci --- .../20-usage/22-conditional-execution.md | 2 +- .../version-0.15/20-usage/40-secrets.md | 2 +- .../20-usage/71-project-settings.md | 1 - .../30-administration/15-agent-config.md | 4 +- .../30-administration/80-kubernetes.md | 1 - .../version-0.15/92-development/ui-proxy.svg | 4 +- .../20-usage/71-project-settings.md | 2 +- .../30-administration/10-server-config.md | 6 +- .../30-administration/22-backends/20-local.md | 1 - .../30-administration/40-encryption.md | 6 +- docs/versioned_docs/version-1.0/40-cli.md | 68 +++++++++---------- .../version-1.0/92-development/03-ui.md | 2 +- .../version-1.0/92-development/09-security.md | 2 +- .../version-1.0/92-development/ui-proxy.svg | 4 +- 14 files changed, 51 insertions(+), 54 deletions(-) diff --git a/docs/versioned_docs/version-0.15/20-usage/22-conditional-execution.md b/docs/versioned_docs/version-0.15/20-usage/22-conditional-execution.md index 81e5f009327..432b056343e 100644 --- a/docs/versioned_docs/version-0.15/20-usage/22-conditional-execution.md +++ b/docs/versioned_docs/version-0.15/20-usage/22-conditional-execution.md @@ -150,7 +150,7 @@ when: :::info This feature is currently only available for GitHub, GitLab and Gitea. -Pull requests aren't supported by gitea at the moment ([go-gitea/gitea#18228](https://github.com/go-gitea/gitea/pull/18228)). +Pull requests aren't supported by gitea at the moment ([go-gitea/gitea#18228](https://github.com/go-gitea/gitea/pull/18228)). Path conditions are ignored for tag events. ::: diff --git a/docs/versioned_docs/version-0.15/20-usage/40-secrets.md b/docs/versioned_docs/version-0.15/20-usage/40-secrets.md index 195f3999a49..c2584524a97 100644 --- a/docs/versioned_docs/version-0.15/20-usage/40-secrets.md +++ b/docs/versioned_docs/version-0.15/20-usage/40-secrets.md @@ -14,7 +14,7 @@ pipeline: + secrets: [ docker_username, docker_password ] ``` -Alternatively, you can get a `setting` from secrets using the `from_secret` syntax. +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 pipeline as `PLUGIN_TOKEN`. **NOTE:** the `from_secret` syntax only works with the newer `settings` block. diff --git a/docs/versioned_docs/version-0.15/20-usage/71-project-settings.md b/docs/versioned_docs/version-0.15/20-usage/71-project-settings.md index 5173ff78a0a..b2c6ec6bb6e 100644 --- a/docs/versioned_docs/version-0.15/20-usage/71-project-settings.md +++ b/docs/versioned_docs/version-0.15/20-usage/71-project-settings.md @@ -33,4 +33,3 @@ You can change the visibility of your project by this setting. If a user has acc ## Timeout After this timeout a pipeline has to finish or will be treated as timed out. - diff --git a/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md b/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md index cf3afae54ef..bf490bf087c 100644 --- a/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md +++ b/docs/versioned_docs/version-0.15/30-administration/15-agent-config.md @@ -79,8 +79,8 @@ See [Conditionals Pipeline](../20-usage/20-pipeline-syntax.md#step-when---condit ## All agent configuration options Here is the full list of configuration options and their default variables. -#### `DOCKER_HOST` -> Default: empty +#### `DOCKER_HOST` +> Default: empty Point to an alternate socket file or host. For example, "unix:////run/podman/podman.sock" diff --git a/docs/versioned_docs/version-0.15/30-administration/80-kubernetes.md b/docs/versioned_docs/version-0.15/30-administration/80-kubernetes.md index 6132a51897a..10d1d66d84f 100644 --- a/docs/versioned_docs/version-0.15/30-administration/80-kubernetes.md +++ b/docs/versioned_docs/version-0.15/30-administration/80-kubernetes.md @@ -210,4 +210,3 @@ spec: - name: sock-dir emptyDir: {} ``` - diff --git a/docs/versioned_docs/version-0.15/92-development/ui-proxy.svg b/docs/versioned_docs/version-0.15/92-development/ui-proxy.svg index 6ccb7445870..79809ffa197 100644 --- a/docs/versioned_docs/version-0.15/92-development/ui-proxy.svg +++ b/docs/versioned_docs/version-0.15/92-development/ui-proxy.svg @@ -1,6 +1,6 @@ - + - forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler) \ No newline at end of file + 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-1.0/20-usage/71-project-settings.md b/docs/versioned_docs/version-1.0/20-usage/71-project-settings.md index d65552182e9..319a07e6101 100644 --- a/docs/versioned_docs/version-1.0/20-usage/71-project-settings.md +++ b/docs/versioned_docs/version-1.0/20-usage/71-project-settings.md @@ -21,7 +21,7 @@ Enables handling webhook's pull request event. If disabled, then pipeline won't ### 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. +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 diff --git a/docs/versioned_docs/version-1.0/30-administration/10-server-config.md b/docs/versioned_docs/version-1.0/30-administration/10-server-config.md index 9f86cb1c0e8..9e05c79a9a3 100644 --- a/docs/versioned_docs/version-1.0/30-administration/10-server-config.md +++ b/docs/versioned_docs/version-1.0/30-administration/10-server-config.md @@ -20,9 +20,9 @@ services: + - 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 +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 --git a/docs/versioned_docs/version-1.0/30-administration/22-backends/20-local.md b/docs/versioned_docs/version-1.0/30-administration/22-backends/20-local.md index c8c5dbc4eb6..39ff4c219d1 100644 --- a/docs/versioned_docs/version-1.0/30-administration/22-backends/20-local.md +++ b/docs/versioned_docs/version-1.0/30-administration/22-backends/20-local.md @@ -115,4 +115,3 @@ labels: steps: [...] ``` - diff --git a/docs/versioned_docs/version-1.0/30-administration/40-encryption.md b/docs/versioned_docs/version-1.0/30-administration/40-encryption.md index 78aab913044..e48ece3eec7 100644 --- a/docs/versioned_docs/version-1.0/30-administration/40-encryption.md +++ b/docs/versioned_docs/version-1.0/30-administration/40-encryption.md @@ -1,6 +1,6 @@ # Secrets encryption -By default, Woodpecker does not encrypt secrets in its database. You can enable encryption +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 @@ -8,7 +8,7 @@ using simple AES key or more advanced [Google TINK](https://developers.google.co ### 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 +`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! @@ -45,7 +45,7 @@ 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 +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: diff --git a/docs/versioned_docs/version-1.0/40-cli.md b/docs/versioned_docs/version-1.0/40-cli.md index 3f4b46c1e0d..4829d84e1bb 100644 --- a/docs/versioned_docs/version-1.0/40-cli.md +++ b/docs/versioned_docs/version-1.0/40-cli.md @@ -304,37 +304,37 @@ execute a local pipeline **--backend-ssh-user**="": backend ssh user -**--commit-author-avatar**="": +**--commit-author-avatar**="": -**--commit-author-email**="": +**--commit-author-email**="": -**--commit-author-name**="": +**--commit-author-name**="": -**--commit-branch**="": +**--commit-branch**="": -**--commit-message**="": +**--commit-message**="": -**--commit-ref**="": +**--commit-ref**="": -**--commit-refspec**="": +**--commit-refspec**="": -**--commit-sha**="": +**--commit-sha**="": -**--env**="": +**--env**="": -**--forge-type**="": +**--forge-type**="": -**--forge-url**="": +**--forge-url**="": **--local**: run from local directory **--log-level**="": set logging level (default: info) -**--netrc-machine**="": +**--netrc-machine**="": -**--netrc-password**="": +**--netrc-password**="": -**--netrc-username**="": +**--netrc-username**="": **--network**="": external networks @@ -344,7 +344,7 @@ execute a local pipeline **--pipeline-finished**="": (default: 0) -**--pipeline-link**="": +**--pipeline-link**="": **--pipeline-number**="": (default: 0) @@ -352,53 +352,53 @@ execute a local pipeline **--pipeline-started**="": (default: 0) -**--pipeline-status**="": +**--pipeline-status**="": -**--pipeline-target**="": +**--pipeline-target**="": -**--prev-commit-author-avatar**="": +**--prev-commit-author-avatar**="": -**--prev-commit-author-email**="": +**--prev-commit-author-email**="": -**--prev-commit-author-name**="": +**--prev-commit-author-name**="": -**--prev-commit-branch**="": +**--prev-commit-branch**="": -**--prev-commit-message**="": +**--prev-commit-message**="": -**--prev-commit-ref**="": +**--prev-commit-ref**="": -**--prev-commit-refspec**="": +**--prev-commit-refspec**="": -**--prev-commit-sha**="": +**--prev-commit-sha**="": **--prev-pipeline-created**="": (default: 0) -**--prev-pipeline-event**="": +**--prev-pipeline-event**="": **--prev-pipeline-finished**="": (default: 0) -**--prev-pipeline-link**="": +**--prev-pipeline-link**="": **--prev-pipeline-number**="": (default: 0) **--prev-pipeline-started**="": (default: 0) -**--prev-pipeline-status**="": +**--prev-pipeline-status**="": **--privileged**="": privileged plugins (default: "plugins/docker", "plugins/gcr", "plugins/ecr", "woodpeckerci/plugin-docker-buildx") **--repo**="": full repo name -**--repo-clone-url**="": +**--repo-clone-url**="": -**--repo-link**="": +**--repo-link**="": -**--repo-private**="": +**--repo-private**="": -**--repo-remote-id**="": +**--repo-remote-id**="": -**--repo-trusted**: +**--repo-trusted**: **--server, -s**="": server address @@ -408,7 +408,7 @@ execute a local pipeline **--system-name**="": (default: woodpecker) -**--system-platform**="": +**--system-platform**="": **--timeout**="": pipeline timeout (default: 0s) diff --git a/docs/versioned_docs/version-1.0/92-development/03-ui.md b/docs/versioned_docs/version-1.0/92-development/03-ui.md index b2a12484723..df121e4e184 100644 --- a/docs/versioned_docs/version-1.0/92-development/03-ui.md +++ b/docs/versioned_docs/version-1.0/92-development/03-ui.md @@ -32,7 +32,7 @@ The following list contains some tools and frameworks used by the Woodpecker UI. ## 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. +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 master branch yet) For more information about translations see [Translations](./07-translations.md). diff --git a/docs/versioned_docs/version-1.0/92-development/09-security.md b/docs/versioned_docs/version-1.0/92-development/09-security.md index e8b2d95f258..86f925c0772 100644 --- a/docs/versioned_docs/version-1.0/92-development/09-security.md +++ b/docs/versioned_docs/version-1.0/92-development/09-security.md @@ -1,6 +1,6 @@ # Security -We take security seriously. +We take security seriously. If you discover a security issue, please bring it to their attention right away! ### Reporting a Vulnerability diff --git a/docs/versioned_docs/version-1.0/92-development/ui-proxy.svg b/docs/versioned_docs/version-1.0/92-development/ui-proxy.svg index 6ccb7445870..79809ffa197 100644 --- a/docs/versioned_docs/version-1.0/92-development/ui-proxy.svg +++ b/docs/versioned_docs/version-1.0/92-development/ui-proxy.svg @@ -1,6 +1,6 @@ - + - forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler) \ No newline at end of file + forward requestin dev modeUI Server Port 8010Woodpecker ServerBrowserPort 8000/login/logout/api/.../api/web-config.js/streamEvery other request(404 Handler)