self-hosted/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2025-03-11 13:59:36 +02:00
Code Issues Releases Activity

Merge branch 'main' into pr/anbraten/3849

Browse Source
This commit is contained in:
Robert Kaussow 2025-01-20 10:28:18 +01:00 committed by GitHub
commit 48080bebbf
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
155 changed files with 5275 additions and 5340 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.cspell.json
View File

@ -16,6 +16,7 @@
"antfu",
"apimachinery",
"appleboy",
"aquasec",
"Archlinux",
"autoincr",
"automerge",
@ -30,6 +31,7 @@
"buildx",
"caddyfile",
"ccmenu",
"CERTDIR",
"certmagic",
"charmbracelet",
"cicd",
@ -41,7 +43,6 @@
"cpuset",
"creativecommons",
"Curr",
"CERTDIR",
"datacenter",
"DATASOURCE",
"Debugf",

4
.gitpod.yml
View File

@ -26,7 +26,7 @@ tasks:
|| echo WOODPECKER_HOST=$(gp url 8000) >> .env
gp sync-await gitea
gp sync-done woodpecker-server
go run go.woodpecker-ci.org/woodpecker/v2/cmd/server
go run go.woodpecker-ci.org/woodpecker/v3/cmd/server
- name: Agent
env:
WOODPECKER_SERVER: localhost:9000
@ -35,7 +35,7 @@ tasks:
WOODPECKER_HEALTHCHECK: false
command: |
gp sync-await woodpecker-server
go run go.woodpecker-ci.org/woodpecker/v2/cmd/agent
go run go.woodpecker-ci.org/woodpecker/v3/cmd/agent
- name: Gitea
command: |
export DOCKER_COMPOSE_CMD="docker-compose -f docker-compose.gitpod.yaml -p woodpecker"

68
.golangci.yaml
View File

@ -28,11 +28,11 @@ linters-settings:
- '!**/server/pipeline/*.go'
- '!**/server/pipeline/**/*.go'
deny:
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cmd'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/web'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cmd'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/web'
shared:
list-mode: lax
files:
@ -41,25 +41,25 @@ linters-settings:
- '!**/pipeline/shared/*.go'
- '!**/pipeline/shared/**/*.go'
deny:
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cmd'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/pipeline'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/web'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cmd'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/pipeline'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/web'
woodpecker-go:
list-mode: lax
files:
- '**/woodpecker-go/woodpecker/**/*.go'
- '**/woodpecker-go/woodpecker/*.go'
deny:
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cmd'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/pipeline'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/shared'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/web'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cmd'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/pipeline'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/shared'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/web'
agent:
list-mode: lax
files:
@ -68,12 +68,12 @@ linters-settings:
- '**/cmd/agent/**/*.go'
- '**/cmd/agent/*.go'
deny:
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cmd/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cmd/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/web'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/woodpecker-go/woodpecker'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cmd/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cmd/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/web'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/woodpecker-go/woodpecker'
cli:
list-mode: lax
files:
@ -82,11 +82,11 @@ linters-settings:
- '**/cmd/cli/**/*.go'
- '**/cmd/cli/*.go'
deny:
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cmd/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cmd/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/web'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cmd/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cmd/server'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/web'
server:
list-mode: lax
files:
@ -97,11 +97,11 @@ linters-settings:
- '**/web/**/*.go'
- '**/web/*.go'
deny:
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cmd/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/cmd/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v2/woodpecker-go/woodpecker'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cmd/agent'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/cmd/cli'
- pkg: 'go.woodpecker-ci.org/woodpecker/v3/woodpecker-go/woodpecker'
gci:
custom-order: true
sections:

2
.woodpecker/binaries.yaml
View File

@ -99,7 +99,7 @@ steps:
release:
depends_on:
- checksums
image: woodpeckerci/plugin-release:0.2.2
image: woodpeckerci/plugin-release:0.2.3
settings:
api_key:
from_secret: github_token

2
.woodpecker/docker.yaml
View File

@ -185,7 +185,7 @@ steps:
repo: *publish_repos_server
dockerfile: docker/Dockerfile.server.multiarch.rootless
platforms: *platforms_server
tag: ['${CI_COMMIT_TAG%%.*}', '${CI_COMMIT_TAG%.*}-alpine', '${CI_COMMIT_TAG}']
tag: ['${CI_COMMIT_TAG%%.*}', '${CI_COMMIT_TAG%.*}', '${CI_COMMIT_TAG}']
logins: *publish_logins
when: &when-release
event: tag

4
.woodpecker/docs.yaml
View File

@ -50,7 +50,7 @@ steps:
build-cli:
image: *golang_image
commands:
- make docs
- make generate-docs
when:
- path: *when_path
event: [tag, pull_request, push]
@ -69,7 +69,7 @@ steps:
- event: manual
deploy-preview:
image: docker.io/woodpeckerci/plugin-surge-preview:1.3.3
image: docker.io/woodpeckerci/plugin-surge-preview:1.3.4
settings:
path: 'docs/build/'
surge_token:

2
.woodpecker/securityscan.yaml
View File

@ -36,6 +36,6 @@ services:
image: *trivy_plugin
settings:
service: true
db-repository: docker.io/aquasec/trivy-db:2
db-repository: mirror.gcr.io/aquasec/trivy-db:2
ports:
- 10000

229
CHANGELOG.md
View File

@ -1,15 +1,19 @@
# Changelog
## [3.0.0](https://github.com/woodpecker-ci/woodpecker/releases/tag/v3.0.0) - 2024-12-13
## [3.0.0](https://github.com/woodpecker-ci/woodpecker/releases/tag/v3.0.0) - 2025-01-18
### ❤️ Thanks to all contributors! ❤️
@6543, @Fishbowler, @M0Rf30, @anbraten, @cduchenoy, @fernandrone, @gnowland, @greenaar, @hg, @j04n-f, @jenrik, @johanneskastl, @jolheiser, @lafriks, @lukashass, @meln5674, @not-my-profile, @pat-s, @qwerty287, @smainz, @tori-27, @tsufeki, @xoxys, @xtexChooser, @zc-devs
@6543, @Fishbowler, @Levy-Tal, @M0Rf30, @anbraten, @cduchenoy, @cevatkerim, @fernandrone, @gedankenstuecke, @gnowland, @greenaar, @hg, @j04n-f, @jenrik, @johanneskastl, @jolheiser, @lafriks, @lukashass, @meln5674, @not-my-profile, @pat-s, @plafue, @qwerty287, @smainz, @stevapple, @tori-27, @tsufeki, @xoxys, @xtexChooser, @zc-devs
### 💥 Breaking changes
- Add rootless (alpine) images [[#4617](https://github.com/woodpecker-ci/woodpecker/pull/4617)]
- Unify CLI bin name [[#4673](https://github.com/woodpecker-ci/woodpecker/pull/4673)]
- Support Git as only VCS [[#4346](https://github.com/woodpecker-ci/woodpecker/pull/4346)]
- Add rolling semver tags, remove `latest` tag [[#4600](https://github.com/woodpecker-ci/woodpecker/pull/4600)]
- Drop native Let's Encrypt support [[#4541](https://github.com/woodpecker-ci/woodpecker/pull/4541)]
- Set new default approval mode based on repo visibility [[#4456](https://github.com/woodpecker-ci/woodpecker/pull/4456)]
- Require approval for prs from public repos by default [[#4456](https://github.com/woodpecker-ci/woodpecker/pull/4456)]
- Do not set empty environment variables [[#4193](https://github.com/woodpecker-ci/woodpecker/pull/4193)]
- Unify cli commands and flags [[#4481](https://github.com/woodpecker-ci/woodpecker/pull/4481)]
- Move pipeline logs command [[#4480](https://github.com/woodpecker-ci/woodpecker/pull/4480)]
@ -48,6 +52,8 @@
### 🔒 Security
- Don't log DB passwords [[#4583](https://github.com/woodpecker-ci/woodpecker/pull/4583)]
- Do not log forge tokens [[#4551](https://github.com/woodpecker-ci/woodpecker/pull/4551)]
- Add server config to disable user registered agents [[#4206](https://github.com/woodpecker-ci/woodpecker/pull/4206)]
- chore: fix `http-proxy-middleware` CVE [[#4257](https://github.com/woodpecker-ci/woodpecker/pull/4257)]
- Allow altering trusted clone plugins and filter them via tag [[#4074](https://github.com/woodpecker-ci/woodpecker/pull/4074)]
@ -57,12 +63,98 @@
### ✨ Features
- Add user as docker backend_option [[#4526](https://github.com/woodpecker-ci/woodpecker/pull/4526)]
- Add dns config option to official feature set [[#4418](https://github.com/woodpecker-ci/woodpecker/pull/4418)]
- Implement org/user agents [[#3539](https://github.com/woodpecker-ci/woodpecker/pull/3539)]
- Replay pipeline using `cli exec` by downloading metadata [[#4103](https://github.com/woodpecker-ci/woodpecker/pull/4103)]
- Update clone plugin to support sha256 [[#4136](https://github.com/woodpecker-ci/woodpecker/pull/4136)]
### 📚 Documentation
- Improve 3.0.0 migration notes [[#4737](https://github.com/woodpecker-ci/woodpecker/pull/4737)]
- Add docs for 3.0 [[#4705](https://github.com/woodpecker-ci/woodpecker/pull/4705)]
- fix(deps): update docs npm deps non-major [[#4733](https://github.com/woodpecker-ci/woodpecker/pull/4733)]
- chore(deps): update dependency @types/react to v19.0.5 [[#4714](https://github.com/woodpecker-ci/woodpecker/pull/4714)]
- fix(deps): update docs npm deps non-major [[#4702](https://github.com/woodpecker-ci/woodpecker/pull/4702)]
- fix(deps): update react monorepo to v19 (major) [[#4529](https://github.com/woodpecker-ci/woodpecker/pull/4529)]
- Refactor `secrets` page in docs [[#4644](https://github.com/woodpecker-ci/woodpecker/pull/4644)]
- fix(deps): update docs npm deps non-major [[#4661](https://github.com/woodpecker-ci/woodpecker/pull/4661)]
- chore(deps): lock file maintenance [[#4647](https://github.com/woodpecker-ci/woodpecker/pull/4647)]
- chore(deps): update dependency concurrently to v9.1.1 [[#4631](https://github.com/woodpecker-ci/woodpecker/pull/4631)]
- Add docker in docker example to advanced usage in docs [[#4620](https://github.com/woodpecker-ci/woodpecker/pull/4620)]
- fixed a typo [[#4621](https://github.com/woodpecker-ci/woodpecker/pull/4621)]
- Fix misleading example in Workflow syntax/Privileged mode [[#4613](https://github.com/woodpecker-ci/woodpecker/pull/4613)]
- Update docs section about "Custom clone plugins" [[#4618](https://github.com/woodpecker-ci/woodpecker/pull/4618)]
- Search in plugin tags [[#4604](https://github.com/woodpecker-ci/woodpecker/pull/4604)]
- chore(deps): update dependency @types/react to v18.3.18 [[#4599](https://github.com/woodpecker-ci/woodpecker/pull/4599)]
- Update About [[#4555](https://github.com/woodpecker-ci/woodpecker/pull/4555)]
- chore(deps): update dependency marked to v15.0.4 [[#4570](https://github.com/woodpecker-ci/woodpecker/pull/4570)]
- Expand docs around the deprecation of former secret syntax [[#4561](https://github.com/woodpecker-ci/woodpecker/pull/4561)]
- fix(deps): update docs npm deps non-major [[#4568](https://github.com/woodpecker-ci/woodpecker/pull/4568)]
- Show client flags [[#4542](https://github.com/woodpecker-ci/woodpecker/pull/4542)]
- chore(deps): update react monorepo to v19 (major) [[#4523](https://github.com/woodpecker-ci/woodpecker/pull/4523)]
- chore(deps): update docs npm deps non-major [[#4519](https://github.com/woodpecker-ci/woodpecker/pull/4519)]
- chore(deps): update dependency isomorphic-dompurify to v2.18.0 [[#4493](https://github.com/woodpecker-ci/woodpecker/pull/4493)]
- fix(deps): update docs npm deps non-major [[#4484](https://github.com/woodpecker-ci/woodpecker/pull/4484)]
- Add migration notes for restructured cli commands [[#4476](https://github.com/woodpecker-ci/woodpecker/pull/4476)]
- Various fixes for `awesome.md` [[#4448](https://github.com/woodpecker-ci/woodpecker/pull/4448)]
- chore(deps): update dependency isomorphic-dompurify to v2.17.0 [[#4449](https://github.com/woodpecker-ci/woodpecker/pull/4449)]
- fix(deps): update docs npm deps non-major [[#4441](https://github.com/woodpecker-ci/woodpecker/pull/4441)]
- chore(deps): update dependency @docusaurus/tsconfig to v3.6.2 [[#4433](https://github.com/woodpecker-ci/woodpecker/pull/4433)]
- Bump minimum nodejs to v20 [[#4417](https://github.com/woodpecker-ci/woodpecker/pull/4417)]
- Add microsoft teams plugin [[#4400](https://github.com/woodpecker-ci/woodpecker/pull/4400)]
- fix(deps): update docs npm deps non-major [[#4394](https://github.com/woodpecker-ci/woodpecker/pull/4394)]
- chore(deps): update dependency @types/node to v22 [[#4395](https://github.com/woodpecker-ci/woodpecker/pull/4395)]
- chore(deps): update dependency marked to v15 [[#4396](https://github.com/woodpecker-ci/woodpecker/pull/4396)]
- Kubernetes documentation enhancements [[#4374](https://github.com/woodpecker-ci/woodpecker/pull/4374)]
- Podman is not (official) supported [[#4367](https://github.com/woodpecker-ci/woodpecker/pull/4367)]
- Add EditorConfig-Checker Plugin to docs [[#4371](https://github.com/woodpecker-ci/woodpecker/pull/4371)]
- Update netrc option description [[#4342](https://github.com/woodpecker-ci/woodpecker/pull/4342)]
- Fix deployment event note [[#4283](https://github.com/woodpecker-ci/woodpecker/pull/4283)]
- Improve migration notes [[#4291](https://github.com/woodpecker-ci/woodpecker/pull/4291)]
- Add instructions how to build images locally [[#4277](https://github.com/woodpecker-ci/woodpecker/pull/4277)]
- chore(deps): update docs npm deps non-major [[#4238](https://github.com/woodpecker-ci/woodpecker/pull/4238)]
- Correct spelling [[#4279](https://github.com/woodpecker-ci/woodpecker/pull/4279)]
- Add Telegram plugin [[#4229](https://github.com/woodpecker-ci/woodpecker/pull/4229)]
- Remove archived plugin [[#4227](https://github.com/woodpecker-ci/woodpecker/pull/4227)]
- Use "Woodpecker Authors" as copyright on website [[#4225](https://github.com/woodpecker-ci/woodpecker/pull/4225)]
- chore(deps): update dependency cookie to v1 [[#4224](https://github.com/woodpecker-ci/woodpecker/pull/4224)]
- fix(deps): update docs npm deps non-major [[#4221](https://github.com/woodpecker-ci/woodpecker/pull/4221)]
- Fix errant apostrophe in docker-compose documentation [[#4203](https://github.com/woodpecker-ci/woodpecker/pull/4203)]
- chore(deps): update dependency concurrently to v9 [[#4176](https://github.com/woodpecker-ci/woodpecker/pull/4176)]
- chore(deps): update docs npm deps non-major [[#4164](https://github.com/woodpecker-ci/woodpecker/pull/4164)]
- Update image filter error message [[#4143](https://github.com/woodpecker-ci/woodpecker/pull/4143)]
- Docs: reference to built-in docker compose and remove deprecated version from compose examples [[#4123](https://github.com/woodpecker-ci/woodpecker/pull/4123)]
- directory key is allowed for services [[#4127](https://github.com/woodpecker-ci/woodpecker/pull/4127)]
- [docs] Removes dot prefix from pipeline configuration filenames [[#4105](https://github.com/woodpecker-ci/woodpecker/pull/4105)]
- Use kaniko plugin in docs as example [[#4072](https://github.com/woodpecker-ci/woodpecker/pull/4072)]
- Add some posts and videos [[#4070](https://github.com/woodpecker-ci/woodpecker/pull/4070)]
- Move event type descriptions from Terminology to Workflow Syntax [[#4062](https://github.com/woodpecker-ci/woodpecker/pull/4062)]
- Add community posts from discussions [[#4058](https://github.com/woodpecker-ci/woodpecker/pull/4058)]
- Add a pull request template with some basic guidelines [[#4055](https://github.com/woodpecker-ci/woodpecker/pull/4055)]
- Add examples of CI environment variable values [[#4009](https://github.com/woodpecker-ci/woodpecker/pull/4009)]
- Fix inline author warning [[#4040](https://github.com/woodpecker-ci/woodpecker/pull/4040)]
- Updated Secrets image filter docs [[#4028](https://github.com/woodpecker-ci/woodpecker/pull/4028)]
- Update dependency marked to v14 [[#4036](https://github.com/woodpecker-ci/woodpecker/pull/4036)]
- Update docs npm deps non-major [[#4033](https://github.com/woodpecker-ci/woodpecker/pull/4033)]
- Overhaul README [[#3995](https://github.com/woodpecker-ci/woodpecker/pull/3995)]
- fix(deps): update docs npm deps non-major [[#3990](https://github.com/woodpecker-ci/woodpecker/pull/3990)]
- Add spellchecking for docs [[#3787](https://github.com/woodpecker-ci/woodpecker/pull/3787)]
### 🐛 Bug Fixes
- Check organization first [[#4723](https://github.com/woodpecker-ci/woodpecker/pull/4723)]
- Fix mobile view of the popup [[#4717](https://github.com/woodpecker-ci/woodpecker/pull/4717)]
- Apply changed files filter to closed PR [[#4711](https://github.com/woodpecker-ci/woodpecker/pull/4711)]
- Add margins to moving WP svg logo [[#4697](https://github.com/woodpecker-ci/woodpecker/pull/4697)]
- Add hosts for detached steps [[#4674](https://github.com/woodpecker-ci/woodpecker/pull/4674)]
- Fix addon `nil` values [[#4666](https://github.com/woodpecker-ci/woodpecker/pull/4666)]
- fix cli exec statement in debug tab [[#4643](https://github.com/woodpecker-ci/woodpecker/pull/4643)]
- Fix misaligned step list indentation [[#4609](https://github.com/woodpecker-ci/woodpecker/pull/4609)]
- Ignore blocked pipelines for badge rendering [[#4582](https://github.com/woodpecker-ci/woodpecker/pull/4582)]
- Remove related pipeline logs during pipeline deletion [[#4572](https://github.com/woodpecker-ci/woodpecker/pull/4572)]
- Weakly decode backend options [[#4577](https://github.com/woodpecker-ci/woodpecker/pull/4577)]
- Add client error to sdk and fix purge cli [[#4574](https://github.com/woodpecker-ci/woodpecker/pull/4574)]
- Fix pipeline purge cli command [[#4569](https://github.com/woodpecker-ci/woodpecker/pull/4569)]
- Fix BB ambiguous commit status key [[#4544](https://github.com/woodpecker-ci/woodpecker/pull/4544)]
- fix: addon JSON pointers [[#4508](https://github.com/woodpecker-ci/woodpecker/pull/4508)]
- Fix apparmorProfile being ignored when it's the only field [[#4507](https://github.com/woodpecker-ci/woodpecker/pull/4507)]
@ -70,7 +162,6 @@
- Cleanup openapi generation [[#4331](https://github.com/woodpecker-ci/woodpecker/pull/4331)]
- Support github refresh tokens [[#3811](https://github.com/woodpecker-ci/woodpecker/pull/3811)]
- Fix not working overflow on repo list message [[#4420](https://github.com/woodpecker-ci/woodpecker/pull/4420)]
- Fix avatar column type [[#4340](https://github.com/woodpecker-ci/woodpecker/pull/4340)]
- fix `error="io: read/write on closed pipe"` on k8s backend [[#4281](https://github.com/woodpecker-ci/woodpecker/pull/4281)]
- Move update notifier dot into settings button [[#4334](https://github.com/woodpecker-ci/woodpecker/pull/4334)]
- gitea: add check if pull_request webhook is missing pull info [[#4305](https://github.com/woodpecker-ci/woodpecker/pull/4305)]
@ -94,66 +185,26 @@
- Truncate creation in list [[#3952](https://github.com/woodpecker-ci/woodpecker/pull/3952)]
- Fix panic if forge is unreachable [[#3944](https://github.com/woodpecker-ci/woodpecker/pull/3944)]
### 📚 Documentation
- Show client flags [[#4542](https://github.com/woodpecker-ci/woodpecker/pull/4542)]
- chore(deps): update react monorepo to v19 (major) [[#4523](https://github.com/woodpecker-ci/woodpecker/pull/4523)]
- chore(deps): update docs npm deps non-major [[#4519](https://github.com/woodpecker-ci/woodpecker/pull/4519)]
- chore(deps): lock file maintenance [[#4502](https://github.com/woodpecker-ci/woodpecker/pull/4502)]
- chore(deps): lock file maintenance [[#4501](https://github.com/woodpecker-ci/woodpecker/pull/4501)]
- chore(deps): update dependency isomorphic-dompurify to v2.18.0 [[#4493](https://github.com/woodpecker-ci/woodpecker/pull/4493)]
- fix(deps): update docs npm deps non-major [[#4484](https://github.com/woodpecker-ci/woodpecker/pull/4484)]
- Add migration notes for restructured cli commands [[#4476](https://github.com/woodpecker-ci/woodpecker/pull/4476)]
- Various fixes for `awesome.md` [[#4448](https://github.com/woodpecker-ci/woodpecker/pull/4448)]
- chore(deps): lock file maintenance [[#4453](https://github.com/woodpecker-ci/woodpecker/pull/4453)]
- chore(deps): update dependency isomorphic-dompurify to v2.17.0 [[#4449](https://github.com/woodpecker-ci/woodpecker/pull/4449)]
- fix(deps): update docs npm deps non-major [[#4441](https://github.com/woodpecker-ci/woodpecker/pull/4441)]
- chore(deps): update dependency @docusaurus/tsconfig to v3.6.2 [[#4433](https://github.com/woodpecker-ci/woodpecker/pull/4433)]
- chore(deps): lock file maintenance [[#4435](https://github.com/woodpecker-ci/woodpecker/pull/4435)]
- Bump minimum nodejs to v20 [[#4417](https://github.com/woodpecker-ci/woodpecker/pull/4417)]
- chore(deps): lock file maintenance [[#4402](https://github.com/woodpecker-ci/woodpecker/pull/4402)]
- Add microsoft teams plugin [[#4400](https://github.com/woodpecker-ci/woodpecker/pull/4400)]
- fix(deps): update docs npm deps non-major [[#4394](https://github.com/woodpecker-ci/woodpecker/pull/4394)]
- chore(deps): update dependency @types/node to v22 [[#4395](https://github.com/woodpecker-ci/woodpecker/pull/4395)]
- chore(deps): update dependency marked to v15 [[#4396](https://github.com/woodpecker-ci/woodpecker/pull/4396)]
- Podman is not (official) supported [[#4367](https://github.com/woodpecker-ci/woodpecker/pull/4367)]
- Add EditorConfig-Checker Plugin to docs [[#4371](https://github.com/woodpecker-ci/woodpecker/pull/4371)]
- Update netrc option description [[#4342](https://github.com/woodpecker-ci/woodpecker/pull/4342)]
- Fix deployment event note [[#4283](https://github.com/woodpecker-ci/woodpecker/pull/4283)]
- Improve migration notes [[#4291](https://github.com/woodpecker-ci/woodpecker/pull/4291)]
- Add instructions how to build images locally [[#4277](https://github.com/woodpecker-ci/woodpecker/pull/4277)]
- chore(deps): update docs npm deps non-major [[#4238](https://github.com/woodpecker-ci/woodpecker/pull/4238)]
- Correct spelling [[#4279](https://github.com/woodpecker-ci/woodpecker/pull/4279)]
- Add Telegram plugin [[#4229](https://github.com/woodpecker-ci/woodpecker/pull/4229)]
- Remove archived plugin [[#4227](https://github.com/woodpecker-ci/woodpecker/pull/4227)]
- Use "Woodpecker Authors" as copyright on website [[#4225](https://github.com/woodpecker-ci/woodpecker/pull/4225)]
- chore(deps): update dependency cookie to v1 [[#4224](https://github.com/woodpecker-ci/woodpecker/pull/4224)]
- fix(deps): update docs npm deps non-major [[#4221](https://github.com/woodpecker-ci/woodpecker/pull/4221)]
- Fix errant apostrophe in docker-compose documentation [[#4203](https://github.com/woodpecker-ci/woodpecker/pull/4203)]
- chore(deps): lock file maintenance [[#4186](https://github.com/woodpecker-ci/woodpecker/pull/4186)]
- chore(deps): update dependency concurrently to v9 [[#4176](https://github.com/woodpecker-ci/woodpecker/pull/4176)]
- chore(deps): update docs npm deps non-major [[#4164](https://github.com/woodpecker-ci/woodpecker/pull/4164)]
- Update image filter error message [[#4143](https://github.com/woodpecker-ci/woodpecker/pull/4143)]
- Docs: reference to built-in docker compose and remove deprecated version from compose examples [[#4123](https://github.com/woodpecker-ci/woodpecker/pull/4123)]
- directory key is allowed for services [[#4127](https://github.com/woodpecker-ci/woodpecker/pull/4127)]
- [docs] Removes dot prefix from pipeline configuration filenames [[#4105](https://github.com/woodpecker-ci/woodpecker/pull/4105)]
- Use kaniko plugin in docs as example [[#4072](https://github.com/woodpecker-ci/woodpecker/pull/4072)]
- Add some posts and videos [[#4070](https://github.com/woodpecker-ci/woodpecker/pull/4070)]
- Move event type descriptions from Terminology to Workflow Syntax [[#4062](https://github.com/woodpecker-ci/woodpecker/pull/4062)]
- Add community posts from discussions [[#4058](https://github.com/woodpecker-ci/woodpecker/pull/4058)]
- Add a pull request template with some basic guidelines [[#4055](https://github.com/woodpecker-ci/woodpecker/pull/4055)]
- Add examples of CI environment variable values [[#4009](https://github.com/woodpecker-ci/woodpecker/pull/4009)]
- Fix inline author warning [[#4040](https://github.com/woodpecker-ci/woodpecker/pull/4040)]
- Updated Secrets image filter docs [[#4028](https://github.com/woodpecker-ci/woodpecker/pull/4028)]
- Update dependency marked to v14 [[#4036](https://github.com/woodpecker-ci/woodpecker/pull/4036)]
- Update docs npm deps non-major [[#4033](https://github.com/woodpecker-ci/woodpecker/pull/4033)]
- Overhaul README [[#3995](https://github.com/woodpecker-ci/woodpecker/pull/3995)]
- fix(deps): update docs npm deps non-major [[#3990](https://github.com/woodpecker-ci/woodpecker/pull/3990)]
- Add spellchecking for docs [[#3787](https://github.com/woodpecker-ci/woodpecker/pull/3787)]
### 📈 Enhancement
- Harmonize en texts [[#4716](https://github.com/woodpecker-ci/woodpecker/pull/4716)]
- feat: add linter support for step-level `depends_on` existence [[#4657](https://github.com/woodpecker-ci/woodpecker/pull/4657)]
- Reduce version redundancy [[#4707](https://github.com/woodpecker-ci/woodpecker/pull/4707)]
- Add priority menu to tabs [[#4641](https://github.com/woodpecker-ci/woodpecker/pull/4641)]
- feat(bitbucketdatacenter): Add support for fetching and converting projects to teams [[#4663](https://github.com/woodpecker-ci/woodpecker/pull/4663)]
- Migrate from Windi to Tailwind [[#4614](https://github.com/woodpecker-ci/woodpecker/pull/4614)]
- Do not start metrics collector if metrics are disabled [[#4667](https://github.com/woodpecker-ci/woodpecker/pull/4667)]
- Improve badge coloring [[#4447](https://github.com/woodpecker-ci/woodpecker/pull/4447)]
- Inline web helpers [[#4639](https://github.com/woodpecker-ci/woodpecker/pull/4639)]
- Use filled status icons and harmonize contextually [[#4584](https://github.com/woodpecker-ci/woodpecker/pull/4584)]
- Two row layout for title and context of pipeline list [[#4625](https://github.com/woodpecker-ci/woodpecker/pull/4625)]
- Remove workflow-level volumes and networks [[#4636](https://github.com/woodpecker-ci/woodpecker/pull/4636)]
- Migrate away from goblin [[#4624](https://github.com/woodpecker-ci/woodpecker/pull/4624)]
- Use lighter red shades for error messages [[#4611](https://github.com/woodpecker-ci/woodpecker/pull/4611)]
- Avoid usage of inline css style [[#4629](https://github.com/woodpecker-ci/woodpecker/pull/4629)]
- Use icon sizes relative to font size [[#4575](https://github.com/woodpecker-ci/woodpecker/pull/4575)]
- Use docusaurus faster [[#4528](https://github.com/woodpecker-ci/woodpecker/pull/4528)]
- Add settings title action [[#4499](https://github.com/woodpecker-ci/woodpecker/pull/4499)]
- Use pagination helper to list pipelines in cli [[#4478](https://github.com/woodpecker-ci/woodpecker/pull/4478)]
- Some UI improvements [[#4497](https://github.com/woodpecker-ci/woodpecker/pull/4497)]
- Add status filter to list pipeline API [[#4494](https://github.com/woodpecker-ci/woodpecker/pull/4494)]
@ -164,7 +215,9 @@
- Increase log level when failing to fetch YAML [[#4107](https://github.com/woodpecker-ci/woodpecker/pull/4107)]
- Trim space to all config flags that allow to read value from file [[#4468](https://github.com/woodpecker-ci/woodpecker/pull/4468)]
- Change default icon size to 20 [[#4458](https://github.com/woodpecker-ci/woodpecker/pull/4458)]
- Use same default sort for repo and org repo list [[#4461](https://github.com/woodpecker-ci/woodpecker/pull/4461)]
- Add visibility icon to repo list [[#4460](https://github.com/woodpecker-ci/woodpecker/pull/4460)]
- Improve tab layout and add hover effect [[#4431](https://github.com/woodpecker-ci/woodpecker/pull/4431)]
- Unify pipeline status icons [[#4414](https://github.com/woodpecker-ci/woodpecker/pull/4414)]
- Improve project settings descriptions [[#4410](https://github.com/woodpecker-ci/woodpecker/pull/4410)]
- Add count badge to visualize counters in tab title [[#4419](https://github.com/woodpecker-ci/woodpecker/pull/4419)]
@ -183,6 +236,7 @@
- Add options to control the database connections (open,idle,timeout) [[#4212](https://github.com/woodpecker-ci/woodpecker/pull/4212)]
- Move Queue creation behind new func that evaluates queue type [[#4252](https://github.com/woodpecker-ci/woodpecker/pull/4252)]
- Add additional error message on swagger v2 to v3 convert [[#4254](https://github.com/woodpecker-ci/woodpecker/pull/4254)]
- Fix wording for privileged plugins linter error [[#4280](https://github.com/woodpecker-ci/woodpecker/pull/4280)]
- Deprecate `secrets` [[#4235](https://github.com/woodpecker-ci/woodpecker/pull/4235)]
- Agent edit/detail view: change the help url based on the backend [[#4219](https://github.com/woodpecker-ci/woodpecker/pull/4219)]
- Use middleware to load org [[#4208](https://github.com/woodpecker-ci/woodpecker/pull/4208)]
@ -215,6 +269,45 @@
### 📦️ Dependency
- fix(deps): update web npm deps non-major [[#4735](https://github.com/woodpecker-ci/woodpecker/pull/4735)]
- chore(deps): update woodpeckerci/plugin-release docker tag to v0.2.3 [[#4734](https://github.com/woodpecker-ci/woodpecker/pull/4734)]
- chore(deps): update docker.io/woodpeckerci/plugin-surge-preview docker tag to v1.3.4 [[#4732](https://github.com/woodpecker-ci/woodpecker/pull/4732)]
- fix(deps): update golang-packages to v0.32.1 [[#4727](https://github.com/woodpecker-ci/woodpecker/pull/4727)]
- fix(deps): update module google.golang.org/protobuf to v1.36.3 [[#4726](https://github.com/woodpecker-ci/woodpecker/pull/4726)]
- fix(deps): update golang-packages [[#4725](https://github.com/woodpecker-ci/woodpecker/pull/4725)]
- chore(deps): lock file maintenance [[#4721](https://github.com/woodpecker-ci/woodpecker/pull/4721)]
- fix(deps): update module code.gitea.io/sdk/gitea to v0.20.0 [[#4710](https://github.com/woodpecker-ci/woodpecker/pull/4710)]
- fix(deps): update dependency simple-icons to v14.2.0 [[#4709](https://github.com/woodpecker-ci/woodpecker/pull/4709)]
- chore(deps): update dependency jsdom to v26 [[#4704](https://github.com/woodpecker-ci/woodpecker/pull/4704)]
- fix(deps): update web npm deps non-major [[#4703](https://github.com/woodpecker-ci/woodpecker/pull/4703)]
- chore(deps): update gitea/gitea docker tag to v1.23 [[#4701](https://github.com/woodpecker-ci/woodpecker/pull/4701)]
- fix(deps): update golang-packages [[#4688](https://github.com/woodpecker-ci/woodpecker/pull/4688)]
- fix(deps): update golang-packages [[#4678](https://github.com/woodpecker-ci/woodpecker/pull/4678)]
- fix(deps): update module golang.org/x/term to v0.28.0 [[#4671](https://github.com/woodpecker-ci/woodpecker/pull/4671)]
- chore(deps): lock file maintenance [[#4672](https://github.com/woodpecker-ci/woodpecker/pull/4672)]
- fix(deps): update dependency simple-icons to v14.1.0 [[#4668](https://github.com/woodpecker-ci/woodpecker/pull/4668)]
- fix(deps): update module golang.org/x/oauth2 to v0.25.0 [[#4665](https://github.com/woodpecker-ci/woodpecker/pull/4665)]
- chore(deps): update pre-commit hook golangci/golangci-lint to v1.63.4 [[#4660](https://github.com/woodpecker-ci/woodpecker/pull/4660)]
- fix(deps): update module github.com/moby/term to v0.5.2 [[#4658](https://github.com/woodpecker-ci/woodpecker/pull/4658)]
- fix(deps): update web npm deps non-major [[#4659](https://github.com/woodpecker-ci/woodpecker/pull/4659)]
- chore(deps): update docker.io/woodpeckerci/plugin-ready-release-go docker tag to v3.1.1 [[#4642](https://github.com/woodpecker-ci/woodpecker/pull/4642)]
- fix(deps): update dependency simple-icons to v14.0.1 [[#4640](https://github.com/woodpecker-ci/woodpecker/pull/4640)]
- fix(deps): update module github.com/google/go-github/v67 to v68 [[#4635](https://github.com/woodpecker-ci/woodpecker/pull/4635)]
- fix(deps): update dependency vue-i18n to v11 [[#4634](https://github.com/woodpecker-ci/woodpecker/pull/4634)]
- fix(deps): update dependency simple-icons to v14 [[#4633](https://github.com/woodpecker-ci/woodpecker/pull/4633)]
- chore(deps): update dependency vite to v6.0.6 [[#4632](https://github.com/woodpecker-ci/woodpecker/pull/4632)]
- fix(deps): update github.com/getkin/kin-openapi digest to cea0a13 [[#4630](https://github.com/woodpecker-ci/woodpecker/pull/4630)]
- chore(deps): lock file maintenance [[#4540](https://github.com/woodpecker-ci/woodpecker/pull/4540)]
- fix(deps): update web npm deps non-major [[#4440](https://github.com/woodpecker-ci/woodpecker/pull/4440)]
- fix(deps): update golang-packages [[#4615](https://github.com/woodpecker-ci/woodpecker/pull/4615)]
- fix(deps): update module gitlab.com/gitlab-org/api/client-go to v0.118.0 [[#4606](https://github.com/woodpecker-ci/woodpecker/pull/4606)]
- fix(deps): update module github.com/cenkalti/backoff/v4 to v5 [[#4601](https://github.com/woodpecker-ci/woodpecker/pull/4601)]
- fix(deps): update golang-packages [[#4586](https://github.com/woodpecker-ci/woodpecker/pull/4586)]
- fix(deps): update module golang.org/x/net to v0.33.0 [security] [[#4585](https://github.com/woodpecker-ci/woodpecker/pull/4585)]
- fix(deps): update golang-packages [[#4579](https://github.com/woodpecker-ci/woodpecker/pull/4579)]
- Replace discontinued mitchellh/mapstructure by maintained fork [[#4573](https://github.com/woodpecker-ci/woodpecker/pull/4573)]
- chore(deps): update docker.io/woodpeckerci/plugin-codecov docker tag to v2.1.6 [[#4566](https://github.com/woodpecker-ci/woodpecker/pull/4566)]
- fix(deps): update github.com/muesli/termenv digest to 8c990cd [[#4565](https://github.com/woodpecker-ci/woodpecker/pull/4565)]
- fix(deps): update module google.golang.org/grpc to v1.69.0 [[#4563](https://github.com/woodpecker-ci/woodpecker/pull/4563)]
- fix(deps): update golang-packages [[#4553](https://github.com/woodpecker-ci/woodpecker/pull/4553)]
- Update kin-openapi [[#4560](https://github.com/woodpecker-ci/woodpecker/pull/4560)]
@ -228,6 +321,8 @@
- chore(deps): update docker.io/alpine docker tag to v3.21 [[#4520](https://github.com/woodpecker-ci/woodpecker/pull/4520)]
- chore(deps): update dependency vite to v6 [[#4485](https://github.com/woodpecker-ci/woodpecker/pull/4485)]
- chore(deps): update docker.io/woodpeckerci/plugin-ready-release-go docker tag to v3 [[#4506](https://github.com/woodpecker-ci/woodpecker/pull/4506)]
- chore(deps): lock file maintenance [[#4502](https://github.com/woodpecker-ci/woodpecker/pull/4502)]
- chore(deps): lock file maintenance [[#4501](https://github.com/woodpecker-ci/woodpecker/pull/4501)]
- chore(deps): update docker.io/woodpeckerci/plugin-surge-preview docker tag to v1.3.3 [[#4495](https://github.com/woodpecker-ci/woodpecker/pull/4495)]
- fix(deps): update golang-packages [[#4477](https://github.com/woodpecker-ci/woodpecker/pull/4477)]
- fix(deps): update dependency @vueuse/core to v12 [[#4486](https://github.com/woodpecker-ci/woodpecker/pull/4486)]
@ -235,12 +330,15 @@
- chore(deps): update woodpeckerci/plugin-release docker tag to v0.2.2 [[#4483](https://github.com/woodpecker-ci/woodpecker/pull/4483)]
- chore(deps): update pre-commit hook golangci/golangci-lint to v1.62.2 [[#4482](https://github.com/woodpecker-ci/woodpecker/pull/4482)]
- fix(deps): update golang-packages [[#4452](https://github.com/woodpecker-ci/woodpecker/pull/4452)]
- chore(deps): lock file maintenance [[#4453](https://github.com/woodpecker-ci/woodpecker/pull/4453)]
- fix(deps): update golang-packages [[#4411](https://github.com/woodpecker-ci/woodpecker/pull/4411)]
- chore(deps): update pre-commit hook igorshubovych/markdownlint-cli to v0.43.0 [[#4443](https://github.com/woodpecker-ci/woodpecker/pull/4443)]
- chore(deps): update postgres docker tag to v17.2 [[#4442](https://github.com/woodpecker-ci/woodpecker/pull/4442)]
- chore(deps): lock file maintenance [[#4435](https://github.com/woodpecker-ci/woodpecker/pull/4435)]
- chore(deps): update docker.io/woodpeckerci/plugin-trivy docker tag to v1.3.0 [[#4434](https://github.com/woodpecker-ci/woodpecker/pull/4434)]
- chore(deps): update web npm deps non-major [[#4432](https://github.com/woodpecker-ci/woodpecker/pull/4432)]
- fix(deps): update golang-packages [[#4401](https://github.com/woodpecker-ci/woodpecker/pull/4401)]
- chore(deps): lock file maintenance [[#4402](https://github.com/woodpecker-ci/woodpecker/pull/4402)]
- chore(deps): update web npm deps non-major [[#4391](https://github.com/woodpecker-ci/woodpecker/pull/4391)]
- fix(deps): update dependency @intlify/unplugin-vue-i18n to v6 [[#4397](https://github.com/woodpecker-ci/woodpecker/pull/4397)]
- chore(deps): update pre-commit hook golangci/golangci-lint to v1.62.0 [[#4390](https://github.com/woodpecker-ci/woodpecker/pull/4390)]
@ -263,6 +361,7 @@
- fix(deps): update dependency vue-i18n to v10.0.4 [[#4200](https://github.com/woodpecker-ci/woodpecker/pull/4200)]
- chore(deps): update pre-commit hook pre-commit/pre-commit-hooks to v5 [[#4192](https://github.com/woodpecker-ci/woodpecker/pull/4192)]
- fix(deps): update dependency simple-icons to v13.13.0 [[#4196](https://github.com/woodpecker-ci/woodpecker/pull/4196)]
- chore(deps): lock file maintenance [[#4186](https://github.com/woodpecker-ci/woodpecker/pull/4186)]
- chore(deps): update web npm deps non-major [[#4174](https://github.com/woodpecker-ci/woodpecker/pull/4174)]
- chore(deps): update docker.io/postgres docker tag to v17 [[#4179](https://github.com/woodpecker-ci/woodpecker/pull/4179)]
- fix(deps): update dependency @intlify/unplugin-vue-i18n to v5 [[#4183](https://github.com/woodpecker-ci/woodpecker/pull/4183)]
@ -296,17 +395,13 @@
### Misc
- Use mirror.gcr.io as `trivy` registry [[#4729](https://github.com/woodpecker-ci/woodpecker/pull/4729)]
- Add docs-dependencies target to makefile [[#4719](https://github.com/woodpecker-ci/woodpecker/pull/4719)]
- Move link checks into cron-curated issue dashboard [[#4515](https://github.com/woodpecker-ci/woodpecker/pull/4515)]
- Add settings title action [[#4499](https://github.com/woodpecker-ci/woodpecker/pull/4499)]
- Use same default sort for repo and org repo list [[#4461](https://github.com/woodpecker-ci/woodpecker/pull/4461)]
- Add dns config option to official feature set [[#4418](https://github.com/woodpecker-ci/woodpecker/pull/4418)]
- Remove `renovate` branch triggers [[#4437](https://github.com/woodpecker-ci/woodpecker/pull/4437)]
- Improve tab layout and add hover effect [[#4431](https://github.com/woodpecker-ci/woodpecker/pull/4431)]
- Dont run pipeline on push events to renovate branches [[#4406](https://github.com/woodpecker-ci/woodpecker/pull/4406)]
- Harden and correct fifo task queue tests [[#4377](https://github.com/woodpecker-ci/woodpecker/pull/4377)]
- Kubernetes documentation enhancements [[#4374](https://github.com/woodpecker-ci/woodpecker/pull/4374)]
- Use release-helper for release/* branches [[#4301](https://github.com/woodpecker-ci/woodpecker/pull/4301)]
- Fix wording for privileged plugins linter error [[#4280](https://github.com/woodpecker-ci/woodpecker/pull/4280)]
- Fix renovate support for `xgo` [[#4276](https://github.com/woodpecker-ci/woodpecker/pull/4276)]
- Improve nix development environment [[#4256](https://github.com/woodpecker-ci/woodpecker/pull/4256)]
- [pre-commit.ci] pre-commit autoupdate [[#4209](https://github.com/woodpecker-ci/woodpecker/pull/4209)]

12
Makefile
View File

@ -337,9 +337,17 @@ spellcheck:
pnpx cspell lint --no-progress stdin
##@ Docs
.PHONY: docs
docs: ## Generate docs (currently only for the cli)
.PHONY: docs-dependencies
docs-dependencies: ## Install docs dependencies
(cd docs/; pnpm install --frozen-lockfile)
.PHONY: generate-docs
generate-docs: ## Generate docs (currently only for the cli)
CGO_ENABLED=0 go generate cmd/cli/app.go
CGO_ENABLED=0 go generate cmd/server/openapi.go
.PHONY: build-docs
build-docs: generate-docs docs-dependencies ## Build the docs
(cd docs/; pnpm build)
endif

2
docker-compose.gitpod.yaml
View File

@ -13,7 +13,7 @@ services:
- pgsql:/var/lib/postgresql/data/pgdata
gitea:
image: gitea/gitea:1.22
image: gitea/gitea:1.23
ports:
- 3000:3000
volumes:

7
docs/.prettierrc.js
View File

@ -1,9 +1,6 @@
import { readFile } from 'node:fs/promises';
const config = require('../.prettierrc.json');
// eslint-disable-next-line antfu/no-top-level-await
const config = JSON.parse(await readFile(new URL('../.prettierrc.json', import.meta.url)));
export default {
module.exports = {
...config,
plugins: ['@ianvs/prettier-plugin-sort-imports'],
importOrder: [

BIN
docs/blog/2024-12-28-release-v3.0.0/approval-requirements.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 57 KiB

BIN
docs/blog/2024-12-28-release-v3.0.0/debug-pipelines.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

115
docs/blog/2024-12-28-release-v3.0.0/index.md Normal file
View File

@ -0,0 +1,115 @@
---
title: Woodpecker 3.0.0
description: Introducing Woodpecker 2.5.0
slug: release-v300
authors:
- name: pat-s
title: Maintainer of Woodpecker
url: https://github.com/pat-s
image_url: https://github.com/pat-s.png
tags: [release, major]
hide_table_of_contents: false
---
We are excited to announce the release of Woodpecker 3.0.0! Along with various cleanup improvements, you can now register your own agents as a user and replay pipelines directly from the server using cli exec.
<!--truncate-->
## Breaking Changes
To enhance the usability of Woodpecker and comply with evolving security standards, we periodically implement migrations. While we strive to minimize changes, some adjustments are essential for an improved user experience.
We acknowledge that this release includes a significant number of changes, many of which require users to update their pipeline definitions. We understand that this can be a tedious task, especially when managing multiple repositories and pipelines.
Rest assured that each modification was carefully considered and thoroughly discussed, with specific reasoning behind every decision.
A substantial portion of these updates aims to transition away from outdated and suboptimal Drone definitions. Your patience and understanding as we implement these necessary changes are greatly appreciated. If you encounter any major issues during your migration to a new version, please don't hesitate to reach out. The Woodpecker maintainers are always eager to reassess and improve our updates based on your feedback.
Security has been a primary focus in this major release. In addition to patching known vulnerabilities (which have also been backported to v2 releases), we have enhanced the secrets handling mechanism to prevent accidental leaks and simplify the process of keeping sensitive information fully encrypted.
For a complete list of migration steps, please refer to the [migration guide](/migrations).
### `from_secret:` as the powerful replacement for the `secrets:` keyword
Specifically, the `secrets:` keyword has been deprecated in favor of a more flexible (and secure) way to specify secrets: `from_secret:`.
This new approach provides more flexibility (by using different names for the source and destination secrets) and ensures a safe internal secret parsing through a unified engine.
Because secrets defined via `secrets:` were simple env vars in the end, this change also removes potential confusion about the differences between values specified in `environment:` and `secrets`.
Now, both are defined in `environment:` using an expressive syntax:
```yaml
steps:
name:
image: alpine
commands:
- echo "The secret is $TOKEN_ENV"
environment:
TOKEN_ENV:
from_secret: SECRET_TOKEN
```
## Register Your Own Agents for Users or Organizations [#3539](https://github.com/woodpecker-ci/woodpecker/pull/3539)
WoodpeckerCI now lets you register custom agents scoped to individual users or organizations. This means you can bring your own agents, configured to meet the unique needs of your projects, and assign them to specific users or organizational workflows.
This update provides flexibility for teams with diverse requirements, allowing them to integrate agents tailored to specific tasks or environments seamlessly into their pipelines.
## Replay Pipelines Locally Using `cli exec` [#4103](https://github.com/woodpecker-ci/woodpecker/pull/4103)
Debugging pipelines no longer requires endless small adjustments and repeated pushes. With the new `woodpecker-cli exec` feature, you can download pipeline metadata directly from the server and replay it locally. This allows you to test and fix issues in a similar environment to the server, all from your machine.
![debug-pipelines-option](debug-pipelines.png)
By locally debugging, this feature accelerates the development process and provides deeper insights into pipeline behavior without relying on server-side execution for every small change.
:::info
In order to use this feature, all required pipeline elements must be passed, e.g. secrets.
However, secrets are not included in the pipeline metadata and must be passed manually to the local execution call.
:::
## Rootless images
Woodpecker now supports running rootless images by adjusting the entrypoints and directory permissions in the containers in a way that allows non-privileged users to execute tasks.
In addition, all images published by Woodpecker (Server, Agent, CLI) now use a non-privileged user (`woodpecker` with UID and GID 1000) by default.
:::info
The agent image must remain rootful by default to be able to mount the Docker socket when Woodpecker is used with the `docker` backend.
The helm chart will start to use a non-privileged user by utilizing `securityContext`.
Running a completely rootless agent with the `docker` backend may be possible by using a rootless docker daemon.
However, this requires more work and is currently not supported.
:::
## Fine grained control over approvals options
Woodpecker 3.0.0 introduces enhanced approval options. Beyond requiring approval for all pipeline events, you can now configure it specifically for all pull requests or only for pull requests originating from forks.
By default, public repositories will now mandate approval for pull requests from forks. This helps prevent potentially malicious PRs from exposing secrets or performing unauthorized actions without the repository owner's awareness.
![screenshot of new approval-requirements options](approval-requirements.png)
## UI
We have fixed many UI-related bugs in this version.
Many were small misalignment related to padding, margins or other edge cases related to small screen sizes.
We also aimed to harmonize the icons across the UI, specifically across logical subgroups, such as status-icons or admin panel icons.
UI elements are now sized in a relative way, meaning they will all scale relative when you change the font-size or zoom in/out.
## Deleting old pipeline logs
Deleting a pipeline now successfully also deletes its related logs.
Beforehand, there was an issue where the logs were not deleted and were kept in the DB forever.
You might want to check [#4572](https://github.com/woodpecker-ci/woodpecker/pull/4572) for more details including a snippet how to delete orphaned entries of a Postgres DB.
:::info
There is no option yet to auto-delete old pipeline logs after a specific time or event.
Please follow [#1068](https://github.com/woodpecker-ci/woodpecker/issues/1068) for future updates.
:::
## Migration to standard Linux CRON syntax
CRON definitions now follow standard Linux syntax without seconds. An automatic migration will attempt to update your settings - ensure the update completes successfully.
## Known Issues
The generic `pipeline definition not found` is still present and not yet understood.
This error message can be triggered by various elements (which the most likely one being a (temporary) connection issue with the forge) and the error return/output must be improved first in order to take appropriate action.

2
docs/docs/30-administration/22-backends/50-custom-backends.md
View File

@ -2,7 +2,7 @@
If none of our backends fits your usecase, you can write your own.
Therefore, implement the interface `"go.woodpecker-ci.org/woodpecker/woodpecker/v2/pipeline/backend/types".Backend` and
Therefore, implement the interface `"go.woodpecker-ci.org/woodpecker/woodpecker/v3/pipeline/backend/types".Backend` and
build a custom agent using your backend with this `main.go`:
```go

19
docs/docs/50-about.md
View File

@ -1,19 +0,0 @@
# About
Woodpecker is a community-driven open source CI/CD tool. It is lightweight, fast and simple to use. It can be used with many different Git providers and runners.
## History
Woodpecker was originally forked from Drone 0.8 by [@laszlocph](https://github.com/laszlocph) in 2019 after its license model was changed.
A few important time points:
- [`2fbaa56`](https://github.com/woodpecker-ci/woodpecker/commit/2fbaa56eee0f4be7a3ca4be03dbd00c1bf5d1274) is the first commit of the fork, made on Apr 3, 2019.
- The first release [v0.8.91](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.8.91) was published on Apr 6, 2019.
- On Aug 27, 2019, the project was renamed to "Woodpecker" ([`630c383`](https://github.com/woodpecker-ci/woodpecker/commit/630c383181b10c4ec375e500c812c4b76b3c52b8)).
- The first release under the name "Woodpecker" was published on Sep 9, 2019 ([v0.8.104](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.8.104)).
## Differences to Drone
Woodpecker is a community-driven open source software published under the Apache License 2.0 and will always remain so. Drone CI is managed by [Harness](https://harness.io/) and is available in two editions: [Open Source under Apache License 2.0 and Enterprise under Polyform Small Business license](https://docs.drone.io/enterprise/#is-drone-open-source).
In terms of Drone's feature set, Woodpecker is somewhere between [Drone Enterprise and OSS](https://docs.drone.io/enterprise/#what-is-the-difference-between-open-source-and-enterprise), but also has some unique features.

2
docs/docs/92-development/09-openapi.md
View File

@ -55,5 +55,5 @@ make generate-openapi
```
```bash title="update the Markdown in the ./docs folder"
make docs
make generate-docs
```

58
docs/docusaurus.config.ts
View File

@ -1,8 +1,31 @@
import * as path from 'path';
import type { VersionBanner, VersionOptions } from '@docusaurus/plugin-content-docs';
import type * as Preset from '@docusaurus/preset-classic';
import type { Config } from '@docusaurus/types';
import { themes } from 'prism-react-renderer';
import versions from './versions.json';
const docsVersions: { [version: string]: VersionOptions } = {
current: {
label: 'Next 🚧',
banner: 'unreleased' as VersionBanner,
},
};
const includeVersions = ['current', versions[0]];
versions.forEach((v, index) => {
const version = {
label: `${v}.x${index === 0 ? '' : ' 💀'}`,
};
if (index !== 0 && process.env.NODE_ENV !== 'development') {
version['banner'] = 'unmaintained';
includeVersions.push(v);
}
docsVersions[v] = version;
});
const config = {
title: 'Woodpecker CI',
tagline: 'Woodpecker is a simple, yet powerful CI/CD engine with great extensibility.',
@ -63,6 +86,10 @@ const config = {
to: '/api',
label: 'API',
},
{
to: '/about',
label: 'About',
},
],
},
{
@ -168,7 +195,7 @@ const config = {
},
announcementBar: {
id: 'github-star',
content: ` If you like Woodpecker-CI, <a href=https://github.com/woodpecker-ci/woodpecker rel="noopener noreferrer" target="_blank">give us a star on GitHub</a> ! ⭐️`,
content: `If you like Woodpecker-CI, <a href=https://github.com/woodpecker-ci/woodpecker rel="noopener noreferrer" target="_blank">give us a star on GitHub</a> ! ⭐️`,
backgroundColor: 'var(--ifm-color-primary)',
textColor: 'var(--ifm-color-gray-900)',
},
@ -236,30 +263,9 @@ const config = {
sidebarPath: require.resolve('./sidebars.js'),
editUrl: 'https://github.com/woodpecker-ci/woodpecker/edit/main/docs/',
includeCurrentVersion: true,
lastVersion: '2.8',
onlyIncludeVersions:
process.env.NODE_ENV === 'development' ? ['current', '2.8'] : ['current', '2.8', '2.7', '2.6', '1.0'],
versions: {
current: {
label: 'Next 🚧',
banner: 'unreleased',
},
'2.8': {
label: '2.8.x',
},
'2.7': {
label: '2.7.x 💀',
banner: 'unmaintained',
},
'2.6': {
label: '2.6.x 💀',
banner: 'unmaintained',
},
'1.0': {
label: '1.0.x 💀',
banner: 'unmaintained',
},
},
lastVersion: versions[0],
onlyIncludeVersions: includeVersions,
versions: docsVersions,
},
blog: {
blogTitle: 'Blog',
@ -284,7 +290,7 @@ const config = {
// Theme Options for modifying how redoc renders them
theme: {
// Change with your site colors
primaryColor: '#1890ff',
primaryColor: '#4caf50',
},
},
],

5
docs/package.json
View File

@ -3,7 +3,7 @@
"version": "0.0.0",
"private": true,
"scripts": {
"start": "cd ../ && make docs && cd docs && docusaurus start",
"start": "cd ../ && make generate-docs && cd docs && docusaurus start",
"build": "pnpm build:woodpecker-plugins && docusaurus build",
"build:woodpecker-plugins": "cd plugins/woodpecker-plugins && pnpm i && pnpm build",
"swizzle": "docusaurus swizzle",
@ -18,7 +18,7 @@
"@docusaurus/faster": "^3.7.0",
"@docusaurus/plugin-content-blog": "^3.7.0",
"@docusaurus/preset-classic": "^3.7.0",
"@easyops-cn/docusaurus-search-local": "^0.46.1",
"@easyops-cn/docusaurus-search-local": "^0.48.0",
"clsx": "^2.1.1",
"prism-react-renderer": "^2.4.1",
"react": "^19.0.0",
@ -41,6 +41,7 @@
"@docusaurus/module-type-aliases": "^3.7.0",
"@docusaurus/tsconfig": "3.7.0",
"@docusaurus/types": "^3.7.0",
"@ianvs/prettier-plugin-sort-imports": "^4.4.0",
"@types/node": "^22.10.5",
"@types/react": "^19.0.0",
"@types/react-helmet": "^6.1.11",

3216
docs/pnpm-lock.yaml generated
View File

File diff suppressed because it is too large Load Diff

98
docs/src/pages/migrations.md
View File

@ -1,5 +1,7 @@
# Migrations
To enhance the usability of Woodpecker and meet evolving security standards, occasional migrations are necessary. While we aim to minimize these changes, some are unavoidable. If you experience significant issues during a migration to a new version, please let us know so maintainers can reassess the updates.
## `next`
- No changes
@ -8,11 +10,35 @@
### User-facing migrations
#### Security
#### Workflow syntax changes
- The "gated" option, which restricted which pipelines can start right away without requiring approval, has been replaced by "require-approval" option. Even though this feature ([#3348](https://github.com/woodpecker-ci/woodpecker/pull/3348)) was backported to 2.8, no default is explicitly set.
The new default in 3.0 is to require approval only for forked repositories.
This allows easier management of dependency bots and other trusted entities having write access to the repository.
- `secrets` have been entirely removed in favor of `environment` combined with the `from_secret` syntax ([#4363](https://github.com/woodpecker-ci/woodpecker/pull/4363)).
As `secrets` are just normal env vars which are masked, the goal was to allow them to be declared next to normal env vars and at the same time reduce the keyword syntax count.
Additionally, the `from_secret` syntax gives more flexibility in naming.
Whereas beforehand `secrets` where always named after their initial secret name, the `from_secret` reference can now be different.
Last, one can inject multiple different env vars from the same secret reference.
2.x:
```yaml
secrets: [my_token]
```
3.x:
```yaml
environment:
MY_TOKEN:
from_secret: my_token
```
Learn more about using [secrets](https://woodpecker-ci.org/docs/next/usage/secrets#usage)
- The `includes` and `excludes` event filter options have been removed
- Previously, env vars have been automatically sanitized to uppercase.
As this has been confusing, the type-case of the secret definition is now respected ([#3375](https://github.com/woodpecker-ci/woodpecker/pull/3375)).
- The `environment` filter option has been removed in favor of `when.evaluate`
- Grouping of steps via `steps.[name].group` should now be done using `steps.[name].depends_on`
#### Environment variables
@ -43,6 +69,12 @@ The following built-in environment variables have been removed/replaced:
Environment variables which are empty after workflow parsing are not being injected into the build but filtered out beforehand ([#4193](https://github.com/woodpecker-ci/woodpecker/pull/4193))
#### Security
- The "gated" option, which restricted which pipelines can start right away without requiring approval, has been replaced by "require-approval" option. Even though this feature ([#3348](https://github.com/woodpecker-ci/woodpecker/pull/3348)) was backported to 2.8, no default is explicitly set.
The new default in 3.0 is to require approval only for forked repositories.
This allows easier management of dependency bots and other trusted entities having write access to the repository.
#### Former deprecations
The following syntax deprecations will now result in an error:
@ -51,38 +83,6 @@ The following syntax deprecations will now result in an error:
- `platform:` ([#3916](https://github.com/woodpecker-ci/woodpecker/pull/3916))
- `branches:` ([#3916](https://github.com/woodpecker-ci/woodpecker/pull/3916))
#### Workflow syntax changes
- Grouping of steps via `steps.[name].group` should now be done using `steps.[name].depends_on`
- The `includes` and `excludes` event filter options have been removed
- Previously, env vars have been automatically sanitized to uppercase.
As this has been confusing, the type-case of the secret definition is now respected ([#3375](https://github.com/woodpecker-ci/woodpecker/pull/3375)).
- `secrets` have been entirely removed in favor of `environment` combined with the `from_secret` syntax.
As `secrets` are just normal env vars which are masked, the goal was to allow them to be declared next to normal env vars and at the same time reduce the keyword syntax count.
Additionally, the `from_secret` syntax gives more flexibility in naming.
Whereas beforehand `secrets` where always named after their initial secret name, the `from_secret` reference can now be different.
Last, one can inject multiple different env vars from the same secret reference.
2.x:
```yaml
secrets: [my_token]
```
3.x:
```yaml
environment:
MY_TOKEN:
from_secret: my_token
```
- The `environment` filter option has been removed in favor of `when.evaluate`
#### API changes
- Removed deprecated `registry/` endpoint. Use `registries`, `/authorize/token`
#### CLI changes
The following restructuring was done to achieve a more consistent grouping:
@ -101,6 +101,12 @@ The following restructuring was done to achieve a more consistent grouping:
| `woodpecker-cli pipeline logs` | `woodpecker-cli pipeline log show` |
| `woodpecker-cli (registry,secret,...) info` | `woodpecker-cli (registry,secret,...) show` |
([#4467](https://github.com/woodpecker-ci/woodpecker/pull/4467) and [#4481](https://github.com/woodpecker-ci/woodpecker/pull/4481))
#### API changes
- Removed deprecated `registry/` endpoint. Use `registries`, `/authorize/token`
#### Miscellaneous
- For `woodpecker-cli` containers, `/woodpecker` has been set as the default `workdir`
@ -111,10 +117,10 @@ The following restructuring was done to achieve a more consistent grouping:
- SDK changes:
- The SDK fields `start_time`, `end_time`, `created_at`, `started_at`, `finished_at` and `reviewed_at` have been renamed to `started`, `finished`, `created`, `started`, `finished`, `reviewed` ([#3968](https://github.com/woodpecker-ci/woodpecker/pull/3968))
- The `trusted` field of the repo model was changed from `boolean` to `object`
- The `trusted` field of the repo model was changed from `boolean` to `object` ([#4025](https://github.com/woodpecker-ci/woodpecker/pull/4025))
- CRON definitions now use standard Linux syntax without seconds.
All custom CRON definitions which do not use keywords such as `@daily` or `@weekly` must be updated.
- CRON definitions now follow standard Linux syntax without seconds. An automatic migration will attempt to update your
settings - ensure the update completes successfully.
Example definition for a CRON job running at 8 am daily:
@ -131,21 +137,21 @@ The following restructuring was done to achieve a more consistent grouping:
```
- Native Let's Encrypt certificate support has been dropped as it was almost unused and causing frequent issues.
Let's Encrypt needs to be set up standalone now. The SSL key pair can still be used in `WOODPECKER_SERVER_CERT` and `WOODPECKER_SERVER_KEY` as an alternative to using a reverse proxy for TLS termination.
Let's Encrypt needs to be set up standalone now. The SSL key pair can still be used in `WOODPECKER_SERVER_CERT` and `WOODPECKER_SERVER_KEY` as an alternative to using a reverse proxy for TLS termination. ([#4541](https://github.com/woodpecker-ci/woodpecker/pull/4541))
- The filename of the CLI binary changed for DEB and RPM packages, it is now called `woodpecker-cli` instead of `woodpecker`.
### Admin-facing migrations
#### Updated tokens
The Webhook tokens have been changed for enhanced security and therefore existing repositories need to be updated using the `Repair all` button in the admin settings ([#4013](https://github.com/woodpecker-ci/woodpecker/pull/4013)).
#### Image tags
- The `latest` tag has been dropped to avoid accidental major version upgrades.
A dedicated semver tag specification must be used, i.e., either a fixed version (like `v3.0.0`) or a rolling tag (e.g. `v3.0` or `v3`).
- Git is now the only officially supported SCM.
No others were supported previously, but the existence of the env var `CI_REPO_SCM` indicated that others might be.
The env var has now been removed including unused code associated with it.
- Previously, some (official) plugins were granted the `privileged` option by default to allow simplified usage.
To streamline this process and enhance security transparency, no plugin is granted the `privileged` options by default anymore.
To allow the use of these plugins in >= 3.0, they must be set explicitly through `WOODPECKER_PLUGINS_PRIVILEGED` on the admin side.
@ -174,6 +180,10 @@ The following restructuring was done to achieve a more consistent grouping:
- Webhook signatures now use the `rfc9421` protocol
- Git is now the only officially supported SCM.
No others were supported previously, but the existence of the env var `CI_REPO_SCM` indicated that others might be.
The env var has now been removed including unused code associated with it. ([#4346](https://github.com/woodpecker-ci/woodpecker/pull/4346))
#### Rootless images
The `server` and `cli` images now use a non-privileged user (`woodpecker`) by default.

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

@ -33,7 +33,12 @@ Here you can find documentation for previous versions of Woodpecker.
| | | |
| ------- | ---------- | ------------------------------------------------------------------------------------- |
| 2.7.3 | 2024-11-28 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.7.3/docs/docs/) |
| 3.0.0 | 2025-01-11 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v3.0.0/docs/docs/) |
| 2.8.3 | 2025-01-11 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.8.3/docs/docs/) |
| 2.8.2 | 2024-12-19 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.8.2/docs/docs/) |
| 2.8.1 | 2024-12-13 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.8.1/docs/docs/) |
| 2.8.0 | 2024-11-28 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.8.0/docs/docs/) |
| 2.7.3 | 2024-11-05 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.7.3/docs/docs/) |
| 2.7.2 | 2024-11-03 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.7.2/docs/docs/) |
| 2.7.1 | 2024-09-07 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.7.1/docs/docs/) |
| 2.7.0 | 2024-07-18 | [Documentation](https://github.com/woodpecker-ci/woodpecker/tree/v2.7.0/docs/docs/) |

2
docs/versioned_docs/version-1.0/92-development/08-swagger.md
View File

@ -61,7 +61,7 @@ make generate-swagger
##### update the Markdown in the ./docs folder
```shell
make docs
make generate-docs
```
##### auto-format swagger related godoc

89
docs/versioned_docs/version-2.6/10-intro.md
View File

@ -1,89 +0,0 @@
# Welcome to Woodpecker
Woodpecker is a simple, yet powerful CI/CD engine with great extensibility. It focuses on executing pipelines inside [containers](https://opencontainers.org/).
If you are already using containers in your daily workflow, you'll for sure love Woodpecker.
![woodpecker](woodpecker.png)
## `.woodpecker.yaml`
- Place your pipeline in a file named `.woodpecker.yaml` in your repository
- Pipeline steps can be named as you like
- Run any command in the commands section
```yaml title=".woodpecker.yaml"
steps:
- name: build
image: debian
commands:
- echo "This is the build step"
- name: a-test-step
image: debian
commands:
- echo "Testing.."
```
### Steps are containers
- Define any container image as context
- either use your own and install the needed tools in a custom image
- or search for available images that are already tailored for your needs in image registries like [Docker Hub](https://hub.docker.com/search?type=image)
- List the commands that should be executed in the container
```diff
steps:
- name: build
- image: debian
+ image: mycompany/image-with-awscli
commands:
- aws help
```
### File changes are incremental
- Woodpecker clones the source code in the beginning
- File changes are persisted throughout individual steps as the same volume is being mounted in all steps
```yaml title=".woodpecker.yaml"
steps:
- name: build
image: debian
commands:
- touch myfile
- name: a-test-step
image: debian
commands:
- cat myfile
```
## Plugins are straightforward
- If you copy the same shell script from project to project
- Pack it into a plugin instead
- And make the yaml declarative
- Plugins are Docker images with your script as an entrypoint
```dockerfile title="Dockerfile"
FROM laszlocloud/kubectl
COPY deploy /usr/local/deploy
ENTRYPOINT ["/usr/local/deploy"]
```
```bash title="deploy"
kubectl apply -f $PLUGIN_TEMPLATE
```
```yaml title=".woodpecker.yaml"
steps:
- name: deploy-to-k8s
image: laszlocloud/my-k8s-plugin
settings:
template: config/k8s/service.yaml
```
See [plugin docs](./20-usage/51-plugins/51-overview.md).
## Continue reading
- [Create a Woodpecker pipeline for your repository](./20-usage/10-intro.md)
- [Setup your own Woodpecker instance](./30-administration/00-deployment/00-overview.md)

72
docs/versioned_docs/version-2.6/20-usage/10-intro.md
View File

@ -1,72 +0,0 @@
# Getting started
## Repository Activation
To activate your project navigate to your account settings. You will see a list of repositories which can be activated with a simple toggle. When you activate your repository, Woodpecker automatically adds webhooks to your forge (e.g. GitHub, Gitea, ...).
Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your forge will automatically send a webhook to Woodpecker which will in turn trigger the pipeline execution.
![repository list](repo-list.png)
## Required Permissions
The user who enables a repo in Woodpecker must have `Admin` rights on that repo, so that Woodpecker can add the webhook.
:::note
Note that manually creating webhooks yourself is not possible.
This is because webhooks are signed using a per-repository secret key which is not exposed to end users.
:::
## Configuration
To configure your pipeline you must create a `.woodpecker.yaml` file in the root of your repository. The `.woodpecker.yaml` file is used to define your pipeline steps.
:::note
We support most of YAML 1.2, but preserve some behavior from 1.1 for backward compatibility.
Read more at: [https://github.com/go-yaml/yaml](https://github.com/go-yaml/yaml/tree/v3)
:::
Example pipeline configuration:
```yaml
steps:
- name: build
image: golang
commands:
- go get
- go build
- go test
services:
- name: postgres
image: postgres:9.4.5
environment:
- POSTGRES_USER=myapp
```
Example pipeline configuration with multiple, serial steps:
```yaml
steps:
- name: backend
image: golang
commands:
- go get
- go build
- go test
- name: frontend
image: node:6
commands:
- npm install
- npm test
- name: notify
image: plugins/slack
channel: developers
username: woodpecker
```
## Execution
To trigger your first pipeline execution you can push code to your repository, open a pull request, or push a tag. Any of these events triggers a webhook from your forge and execute your pipeline.

133
docs/versioned_docs/version-2.6/20-usage/40-secrets.md
View File

@ -1,133 +0,0 @@
# Secrets
Woodpecker provides the ability to store named parameters external to the YAML configuration file, in a central secret store. These secrets can be passed to individual steps of the pipeline at runtime.
Woodpecker provides three different levels to add secrets to your pipeline. The following list shows the priority of the different levels. If a secret is defined in multiple levels, will be used following this priorities: Repository secrets > Organization secrets > Global secrets.
1. **Repository secrets**: They are available to all pipelines of an repository.
2. **Organization secrets**: They are available to all pipelines of an organization.
3. **Global secrets**: Can be configured by an instance admin.
They are available to all pipelines of the **whole** Woodpecker instance and should therefore **only** be used for secrets that are allowed to be read by **all** users.
## Usage
### Use secrets in commands
Secrets are exposed to your pipeline steps and plugins as uppercase environment variables and can therefore be referenced in the commands section of your pipeline,
once their usage is declared in the `secrets` section:
```diff
steps:
- name: docker
image: docker
commands:
+ - echo $docker_username
+ - echo $DOCKER_PASSWORD
+ secrets: [ docker_username, DOCKER_PASSWORD ]
```
The case of the environment variables is not changed, but secret matching is done case-insensitively. In the example above, `DOCKER_PASSWORD` would also match if the secret is called `docker_password`.
### Use secrets in settings and environment
You can set an setting or environment value from secrets using the `from_secret` syntax.
In this example, the secret named `secret_token` would be passed to the setting named `token`,which will be available in the plugin as environment variable named `PLUGIN_TOKEN` (See [plugins](./51-plugins/20-creating-plugins.md#settings) for details), and to the environment variable `TOKEN_ENV`.
```diff
steps:
- name: docker
image: my-plugin
+ environment:
+ TOKEN_ENV:
+ from_secret: secret_token
+ settings:
+ token:
+ from_secret: secret_token
```
### Note about parameter pre-processing
Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped.
```diff
steps:
- name: docker
image: docker
commands:
- - echo ${docker_username}
- - echo ${DOCKER_PASSWORD}
+ - echo $${docker_username}
+ - echo $${DOCKER_PASSWORD}
secrets: [ docker_username, DOCKER_PASSWORD ]
```
### Use in Pull Requests events
Secrets are not exposed to pull requests by default. You can override this behavior by creating the secret and enabling the `pull_request` event type, either in UI or by CLI, see below.
:::note
Please be careful when exposing secrets to pull requests. If your repository is open source and accepts pull requests your secrets are not safe. A bad actor can submit a malicious pull request that exposes your secrets.
:::
## Image filter
To prevent abusing your secrets from malicious usage, you can limit a secret to a list of images. If enabled they are not available to any other plugin (steps without user-defined commands). If you or an attacker defines explicit commands, the secrets will not be available to the container to prevent leaking them.
## Adding Secrets
Secrets are added to the Woodpecker in the UI or with the CLI.
### CLI Examples
Create the secret using default settings. The secret will be available to all images in your pipeline, and will be available to all push, tag, and deployment events (not pull request events).
```bash
woodpecker-cli secret add \
-repository octocat/hello-world \
-name aws_access_key_id \
-value <value>
```
Create the secret and limit to a single image:
```diff
woodpecker-cli secret add \
-repository octocat/hello-world \
+ -image plugins/s3 \
-name aws_access_key_id \
-value <value>
```
Create the secrets and limit to a set of images:
```diff
woodpecker-cli secret add \
-repository octocat/hello-world \
+ -image plugins/s3 \
+ -image peloton/woodpecker-ecs \
-name aws_access_key_id \
-value <value>
```
Create the secret and enable for multiple hook events:
```diff
woodpecker-cli secret add \
-repository octocat/hello-world \
-image plugins/s3 \
+ -event pull_request \
+ -event push \
+ -event tag \
-name aws_access_key_id \
-value <value>
```
Loading secrets from file using curl `@` syntax. This is the recommended approach for loading secrets from file to preserve newlines:
```diff
woodpecker-cli secret add \
-repository octocat/hello-world \
-name ssh_key \
+ -value @/root/ssh/id_rsa
```

45
docs/versioned_docs/version-2.6/20-usage/51-plugins/51-overview.md
View File

@ -1,45 +0,0 @@
# Plugins
Plugins are pipeline steps that perform pre-defined tasks and are configured as steps in your pipeline. Plugins can be used to deploy code, publish artifacts, send notification, and more.
They are automatically pulled from the default container registry the agent's have configured.
Example pipeline using the Docker and Slack plugins:
```yaml
steps:
- name: build
image: golang
commands:
- go build
- go test
- name: publish
image: plugins/docker
settings:
repo: foo/bar
tags: latest
- name: notify
image: plugins/slack
settings:
channel: dev
```
## Plugin Isolation
Plugins are just pipeline steps. They share the build workspace, mounted as a volume, and therefore have access to your source tree.
## Finding Plugins
For official plugins, you can use the Woodpecker plugin index:
- [Official Woodpecker Plugins](https://woodpecker-ci.org/plugins)
:::tip
There are also other plugin lists with additional plugins. Keep in mind that [Drone](https://www.drone.io/) plugins are generally supported, but could need some adjustments and tweaking.
- [Drone Plugins](http://plugins.drone.io)
- [Geeklab Woodpecker Plugins](https://woodpecker-plugins.geekdocs.de/)
:::

129
docs/versioned_docs/version-2.6/20-usage/90-advanced-usage.md
View File

@ -1,129 +0,0 @@
# Advanced usage
## Advanced YAML syntax
YAML has some advanced syntax features that can be used like variables to reduce duplication in your pipeline config:
### Anchors & aliases
You can use [YAML anchors & aliases](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) as variables in your pipeline config.
To convert this:
```yaml
steps:
- name: test
image: golang:1.18
commands: go test ./...
- name: build
image: golang:1.18
commands: build
```
Just add a new section called **variables** like this:
```diff
+variables:
+ - &golang_image 'golang:1.18'
steps:
- name: test
- image: golang:1.18
+ image: *golang_image
commands: go test ./...
- name: build
- image: golang:1.18
+ image: *golang_image
commands: build
```
### Map merges and overwrites
```yaml
variables:
- &base-plugin-settings
target: dist
recursive: false
try: true
- &special-setting
special: true
- &some-plugin codeberg.org/6543/docker-images/print_env
steps:
- name: develop
image: *some-plugin
settings:
<<: [*base-plugin-settings, *special-setting] # merge two maps into an empty map
when:
branch: develop
- name: main
image: *some-plugin
settings:
<<: *base-plugin-settings # merge one map and ...
try: false # ... overwrite original value
ongoing: false # ... adding a new value
when:
branch: main
```
### Sequence merges
```yaml
variables:
pre_cmds: &pre_cmds
- echo start
- whoami
post_cmds: &post_cmds
- echo stop
hello_cmd: &hello_cmd
- echo hello
steps:
- name: step1
image: debian
commands:
- <<: *pre_cmds # prepend a sequence
- echo exec step now do dedicated things
- <<: *post_cmds # append a sequence
- name: step2
image: debian
commands:
- <<: [*pre_cmds, *hello_cmd] # prepend two sequences
- echo echo from second step
- <<: *post_cmds
```
### References
- [Official YAML specification](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases)
- [YAML Cheatsheet](https://learnxinyminutes.com/docs/yaml)
## Persisting environment data between steps
One can create a file containing environment variables, and then source it in each step that needs them.
```yaml
steps:
- name: init
image: bash
commands:
- echo "FOO=hello" >> envvars
- echo "BAR=world" >> envvars
- name: debug
image: bash
commands:
- source envvars
- echo $FOO
```
## Declaring global variables
As described in [Global environment variables](./50-environment.md#global-environment-variables), you can define global variables:
```ini
WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2
```
Note that this tightly couples the server and app configurations (where the app is a completely separate application). But this is a good option for truly global variables which should apply to all steps in all pipelines for all apps.

BIN
docs/versioned_docs/version-2.6/20-usage/project-settings.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 165 KiB

BIN
docs/versioned_docs/version-2.6/20-usage/repo-list.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 21 KiB

76
docs/versioned_docs/version-2.6/30-administration/00-deployment/00-overview.md
View File

@ -1,76 +0,0 @@
# Deployment
A Woodpecker deployment consists of two parts:
- A server which is the heart of Woodpecker and ships the web interface.
- Next to one server, you can deploy any number of agents which will run the pipelines.
Each agent is able to process one pipeline step by default.
If you have four agents installed and connected to the Woodpecker server, your system will process four workflows in parallel.
:::tip
You can add more agents to increase the number of parallel workflows or set the agent's `WOODPECKER_MAX_WORKFLOWS=1` environment variable to increase the number of parallel workflows for that agent.
:::
## Which version of Woodpecker should I use?
Woodpecker is having two different kinds of releases: **stable** and **next**.
Find more information about the different versions [here](/versions).
## Hardware Requirements
Below are minimal resources requirements for Woodpecker components itself:
| Component | Memory | CPU |
| --------- | ------ | --- |
| Server | 200 MB | 1 |
| Agent | 32 MB | 1 |
Note, that those values do not include the operating system or workload (pipelines execution) resources consumption.
In addition you need at least some kind of database which requires additional resources depending on the selected database system.
## Installation
You can install Woodpecker on multiple ways:
- Using [docker-compose](./10-docker-compose.md) with the official [container images](./10-docker-compose.md#docker-images)
- Using [Kubernetes](./20-kubernetes.md) via the Woodpecker Helm chart
- Using binaries, DEBs or RPMs you can download from [latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest)
## Authentication
Authentication is done using OAuth and is delegated to your forge which is configured using environment variables.
See the complete reference for all supported forges [here](../11-forges/11-overview.md).
## Database
By default Woodpecker uses a SQLite database which requires zero installation or configuration. See the [database settings](../30-database.md) page to further configure it or use MySQL or Postgres.
## SSL
Woodpecker supports SSL configuration by using Let's encrypt or by using own certificates. See the [SSL guide](../60-ssl.md). You can also put it behind a [reverse proxy](#behind-a-proxy)
## Metrics
A [Prometheus endpoint](../90-prometheus.md) is exposed.
## Behind a proxy
See the [proxy guide](../70-proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok.
In the case you need to use Woodpecker with a URL path prefix (like: <https://example.org/woodpecker/>), add the root path to [`WOODPECKER_HOST`](../10-server-config.md#woodpecker_host).
## Third-party installation methods
:::info
These installation methods are not officially supported. If you experience issues with them, please open issues in the specific repositories.
:::
- [Using NixOS](./30-nixos.md) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker)
- [On Alpine Edge](https://pkgs.alpinelinux.org/packages?name=woodpecker&branch=edge&repo=&arch=&maintainer=)
- [On Arch Linux](https://archlinux.org/packages/?q=woodpecker)
- [Using YunoHost](https://apps.yunohost.org/app/woodpecker)
- [On Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html)

9
docs/versioned_docs/version-2.6/30-administration/00-deployment/20-kubernetes.md
View File

@ -1,9 +0,0 @@
# Kubernetes
We recommended to deploy Woodpecker using the [Woodpecker helm chart](https://github.com/woodpecker-ci/helm).
Have a look at the [`values.yaml`](https://github.com/woodpecker-ci/helm/blob/main/charts/woodpecker/values.yaml) config files for all available settings.
The chart contains two subcharts, `server` and `agent` which are automatically configured as needed.
The chart started off with two independent charts but was merged into one to simplify the deployment at start of 2023.
A couple of backend-specific config env vars exists which are described in the [kubernetes backend docs](../22-backends/40-kubernetes.md).

594
docs/versioned_docs/version-2.6/40-cli.md
View File

@ -1,594 +0,0 @@
# CLI
# NAME
woodpecker-cli - A new cli application
# SYNOPSIS
woodpecker-cli
```
[--config|-c]=[value]
[--disable-update-check]
[--log-file]=[value]
[--log-level]=[value]
[--nocolor]
[--pretty]
[--server|-s]=[value]
[--token|-t]=[value]
```
# DESCRIPTION
Woodpecker command line utility
**Usage**:
```
woodpecker-cli [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
```
# GLOBAL OPTIONS
**--config, -c**="": path to config file
**--disable-update-check**: disable update check
**--log-file**="": Output destination for logs. 'stdout' and 'stderr' can be used as special keywords. (default: "stderr")
**--log-level**="": set logging level (default: "info")
**--nocolor**: disable colored debug output, only has effect if pretty output is set too
**--pretty**: enable pretty-printed debug output
**--server, -s**="": server address
**--token, -t**="": server auth token
# COMMANDS
## pipeline
manage pipelines
### ls
show pipeline history
**--branch**="": branch filter
**--event**="": event filter
**--format**="": format output (default: "\x1b[33mPipeline #{{ .Number }} \x1b[0m\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nAuthor: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}\nMessage: {{ .Message }}\n")
**--limit**="": limit the list size (default: 25)
**--status**="": status filter
### last
show latest pipeline details
**--branch**="": branch name (default: "main")
**--format**="": format output (default: "Number: {{ .Number }}\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\n")
### logs
show pipeline logs
### info
show pipeline details
**--format**="": format output (default: "Number: {{ .Number }}\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\n")
### stop
stop a pipeline
### start
start a pipeline
**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value
### approve
approve a pipeline
### decline
decline a pipeline
### queue
show pipeline queue
**--format**="": format output (default: "\x1b[33m{{ .FullName }} #{{ .Number }} \x1b[0m\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nAuthor: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}\nMessage: {{ .Message }}\n")
### ps
show pipeline steps
**--format**="": format output (default: "\x1b[33mStep #{{ .PID }} \x1b[0m\nStep: {{ .Name }}\nState: {{ .State }}\n")
### create
create new pipeline
**--branch**="": branch to create pipeline from
**--format**="": format output (default: "\x1b[33mPipeline #{{ .Number }} \x1b[0m\nStatus: {{ .Status }}\nEvent: {{ .Event }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nAuthor: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}\nMessage: {{ .Message }}\n")
**--var**="": key=value
## log
manage logs
### purge
purge a log
## deploy
deploy code
**--branch**="": branch filter (default: "main")
**--event**="": event filter (default: "push")
**--format**="": format output (default: "Number: {{ .Number }}\nStatus: {{ .Status }}\nCommit: {{ .Commit }}\nBranch: {{ .Branch }}\nRef: {{ .Ref }}\nMessage: {{ .Message }}\nAuthor: {{ .Author }}\nTarget: {{ .Deploy }}\n")
**--param, -p**="": custom parameters to be injected into the step environment. Format: KEY=value
**--status**="": status filter (default: "success")
## exec
execute a local pipeline
**--backend-docker-api-version**="": the version of the API to reach, leave empty for latest.
**--backend-docker-cert**="": path to load the TLS certificates for connecting to docker server
**--backend-docker-host**="": path to docker socket or url to the docker server
**--backend-docker-ipv6**: backend docker enable IPV6
**--backend-docker-network**="": backend docker network
**--backend-docker-tls-verify**: enable or disable TLS verification for connecting to docker server
**--backend-docker-volumes**="": backend docker volumes (comma separated)
**--backend-engine**="": backend engine to run pipelines on (default: "auto-detect")
**--backend-http-proxy**="": if set, pass the environment variable down as "HTTP_PROXY" to steps
**--backend-https-proxy**="": if set, pass the environment variable down as "HTTPS_PROXY" to steps
**--backend-k8s-namespace**="": backend k8s namespace (default: "woodpecker")
**--backend-k8s-pod-annotations**="": backend k8s additional worker pod annotations
**--backend-k8s-pod-image-pull-secret-names**="": backend k8s pull secret names for private registries (default: "regcred")
**--backend-k8s-pod-labels**="": backend k8s additional worker pod labels
**--backend-k8s-secctx-nonroot**: `run as non root` Kubernetes security context option
**--backend-k8s-storage-class**="": backend k8s storage class
**--backend-k8s-storage-rwx**: backend k8s storage access mode, should ReadWriteMany (RWX) instead of ReadWriteOnce (RWO) be used? (default: true)
**--backend-k8s-volume-size**="": backend k8s volume size (default 10G) (default: "10G")
**--backend-local-temp-dir**="": set a different temp dir to clone workflows into (default: "/tmp")
**--backend-no-proxy**="": if set, pass the environment variable down as "NO_PROXY" to steps
**--commit-author-avatar**="":
**--commit-author-email**="":
**--commit-author-name**="":
**--commit-branch**="":
**--commit-message**="":
**--commit-ref**="":
**--commit-refspec**="":
**--commit-sha**="":
**--env**="":
**--forge-type**="":
**--forge-url**="":
**--local**: run from local directory
**--netrc-machine**="":
**--netrc-password**="":
**--netrc-username**="":
**--network**="": external networks
**--pipeline-created**="": (default: 0)
**--pipeline-event**="": (default: "manual")
**--pipeline-finished**="": (default: 0)
**--pipeline-number**="": (default: 0)
**--pipeline-parent**="": (default: 0)
**--pipeline-started**="": (default: 0)
**--pipeline-status**="":
**--pipeline-target**="":
**--pipeline-url**="":
**--prev-commit-author-avatar**="":
**--prev-commit-author-email**="":
**--prev-commit-author-name**="":
**--prev-commit-branch**="":
**--prev-commit-message**="":
**--prev-commit-ref**="":
**--prev-commit-refspec**="":
**--prev-commit-sha**="":
**--prev-pipeline-created**="": (default: 0)
**--prev-pipeline-event**="":
**--prev-pipeline-finished**="": (default: 0)
**--prev-pipeline-number**="": (default: 0)
**--prev-pipeline-started**="": (default: 0)
**--prev-pipeline-status**="":
**--prev-pipeline-url**="":
**--privileged**="": privileged plugins (default: "plugins/docker", "plugins/gcr", "plugins/ecr", "woodpeckerci/plugin-docker-buildx", "codeberg.org/woodpecker-plugins/docker-buildx")
**--repo**="": full repo name
**--repo-clone-ssh-url**="":
**--repo-clone-url**="":
**--repo-path**="": path to local repository
**--repo-private**="":
**--repo-remote-id**="":
**--repo-trusted**:
**--repo-url**="":
**--step-name**="": (default: 0)
**--system-name**="": (default: "woodpecker")
**--system-platform**="":
**--system-url**="": (default: "https://github.com/woodpecker-ci/woodpecker")
**--timeout**="": pipeline timeout (default: 1h0m0s)
**--volumes**="": pipeline volumes
**--workflow-name**="": (default: 0)
**--workflow-number**="": (default: 0)
**--workspace-base**="": (default: "/woodpecker")
**--workspace-path**="": (default: "src")
## info
show information about the current user
## registry
manage registries
### add
adds a registry
**--hostname**="": registry hostname (default: "docker.io")
**--password**="": registry password
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
**--username**="": registry username
### rm
remove a registry
**--hostname**="": registry hostname (default: "docker.io")
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
### update
update a registry
**--hostname**="": registry hostname (default: "docker.io")
**--password**="": registry password
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
**--username**="": registry username
### info
display registry info
**--hostname**="": registry hostname (default: "docker.io")
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
### ls
list registries
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
## secret
manage secrets
### add
adds a secret
**--event**="": secret limited to these events
**--global**: global secret
**--image**="": secret limited to these images
**--name**="": secret name
**--organization, --org**="": organization id or full-name (e.g. 123 or octocat)
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
**--value**="": secret value
### rm
remove a secret
**--global**: global secret
**--name**="": secret name
**--organization, --org**="": organization id or full-name (e.g. 123 or octocat)
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
### update
update a secret
**--event**="": secret limited to these events
**--global**: global secret
**--image**="": secret limited to these images
**--name**="": secret name
**--organization, --org**="": organization id or full-name (e.g. 123 or octocat)
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
**--value**="": secret value
### info
display secret info
**--global**: global secret
**--name**="": secret name
**--organization, --org**="": organization id or full-name (e.g. 123 or octocat)
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
### ls
list secrets
**--global**: global secret
**--organization, --org**="": organization id or full-name (e.g. 123 or octocat)
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
## repo
manage repositories
### ls
list all repos
**--format**="": format output (default: "\x1b[33m{{ .FullName }}\x1b[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }})")
**--org**="": filter by organization
### info
show repository details
**--format**="": format output (default: "Owner: {{ .Owner }}\nRepo: {{ .Name }}\nURL: {{ .ForgeURL }}\nConfig path: {{ .Config }}\nVisibility: {{ .Visibility }}\nPrivate: {{ .IsSCMPrivate }}\nTrusted: {{ .IsTrusted }}\nGated: {{ .IsGated }}\nClone url: {{ .Clone }}\nAllow pull-requests: {{ .AllowPullRequests }}\n")
### add
add a repository
### update
update a repository
**--config**="": repository configuration path (e.g. .woodpecker.yml)
**--gated**: repository is gated
**--pipeline-counter**="": repository starting pipeline number (default: 0)
**--timeout**="": repository timeout (default: 0s)
**--trusted**: repository is trusted
**--unsafe**: validate updating the pipeline-counter is unsafe
**--visibility**="": repository visibility
### rm
remove a repository
### repair
repair repository webhooks
### chown
assume ownership of a repository
### sync
synchronize the repository list
**--format**="": format output (default: "\x1b[33m{{ .FullName }}\x1b[0m (id: {{ .ID }}, forgeRemoteID: {{ .ForgeRemoteID }})")
## user
manage users
### ls
list all users
**--format**="": format output (default: "{{ .Login }}")
### info
show user details
**--format**="": format output (default: "User: {{ .Login }}\nEmail: {{ .Email }}")
### add
adds a user
### rm
remove a user
## lint
lint a pipeline configuration file
## log-level
get the logging level of the server, or set it with [level]
## cron
manage cron jobs
### add
add a cron job
**--branch**="": cron branch
**--name**="": cron name
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
**--schedule**="": cron schedule
### rm
remove a cron job
**--id**="": cron id
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
### update
update a cron job
**--branch**="": cron branch
**--id**="": cron id
**--name**="": cron name
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
**--schedule**="": cron schedule
### info
display info about a cron job
**--id**="": cron id
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
### ls
list cron jobs
**--repository, --repo**="": repository id or full-name (e.g. 134 or octocat/hello-world)
## setup
setup the woodpecker-cli for the first time
**--server-url**="": The URL of the woodpecker server
**--token**="": The token to authenticate with the woodpecker server
## update
update the woodpecker-cli to the latest version
**--force**: force update even if the latest version is already installed

18
docs/versioned_docs/version-2.6/50-about.md
View File

@ -1,18 +0,0 @@
# About
Woodpecker has been originally forked from Drone 0.8 as the Drone CI license was changed after the 0.8 release from Apache 2.0 to a proprietary license. Woodpecker is based on this latest freely available version.
## History
Woodpecker was originally forked by [@laszlocph](https://github.com/laszlocph) in 2019.
A few important time points:
- [`2fbaa56`](https://github.com/woodpecker-ci/woodpecker/commit/2fbaa56eee0f4be7a3ca4be03dbd00c1bf5d1274) is the first commit of the fork, made on Apr 3, 2019.
- The first release [v0.8.91](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.8.91) was published on Apr 6, 2019.
- On Aug 27, 2019, the project was renamed to "Woodpecker" ([`630c383`](https://github.com/woodpecker-ci/woodpecker/commit/630c383181b10c4ec375e500c812c4b76b3c52b8)).
- The first release under the name "Woodpecker" was published on Sep 9, 2019 ([v0.8.104](https://github.com/woodpecker-ci/woodpecker/releases/tag/v0.8.104)).
## Differences to Drone
Woodpecker is a community-focused software that still stay free and open source forever, while Drone is managed by [Harness](https://harness.io/) and published under [Polyform Small Business](https://polyformproject.org/licenses/small-business/1.0.0/) license.

160
docs/versioned_docs/version-2.6/91-migrations.md
View File

@ -1,160 +0,0 @@
# Migrations
Some versions need some changes to the server configuration or the pipeline configuration files.
<!--
## 3.0.0
- Update all webhooks by pressing the "Repair all" button in the admin settings as the webhook token claims have changed
-->
## `next`
- Deprecated `steps.[name].group` in favor of `steps.[name].depends_on` (see [workflow syntax](./20-usage/20-workflow-syntax.md#depends_on) to learn how to set dependencies)
- Removed `WOODPECKER_ROOT_PATH` and `WOODPECKER_ROOT_URL` config variables. Use `WOODPECKER_HOST` with a path instead
- Pipelines without a config file will now be skipped instead of failing
- Deprecated `includes` and `excludes` support from **event** filter
- Deprecated uppercasing all secret env vars, instead, the value of the `secrets` property is used. [Read more](./20-usage/40-secrets.md#use-secrets-in-commands)
- Deprecated alternative names for secrets, use `environment` with `from_secret`
- Deprecated slice definition for env vars
- Deprecated `environment` filter, use `when.evaluate`
- Use `WOODPECKER_EXPERT_FORGE_OAUTH_HOST` instead of `WOODPECKER_DEV_GITEA_OAUTH_URL` or `WOODPECKER_DEV_OAUTH_HOST`
- Deprecated `WOODPECKER_WEBHOOK_HOST` in favor of `WOODPECKER_EXPERT_WEBHOOK_HOST`
## 2.0.0
- Dropped deprecated `CI_BUILD_*`, `CI_PREV_BUILD_*`, `CI_JOB_*`, `*_LINK`, `CI_SYSTEM_ARCH`, `CI_REPO_REMOTE` built-in environment variables
- Deprecated `platform:` filter in favor of `labels:`, [read more](./20-usage/20-workflow-syntax.md#filter-by-platform)
- Secrets `event` property was renamed to `events` and `image` to `images` as both are lists. The new property `events` / `images` has to be used in the api. The old properties `event` and `image` were removed.
- The secrets `plugin_only` option was removed. Secrets with images are now always only available for plugins using listed by the `images` property. Existing secrets with a list of `images` will now only be available to the listed images if they are used as a plugin.
- Removed `build` alias for `pipeline` command in CLI
- Removed `ssh` backend. Use an agent directly on the SSH machine using the `local` backend.
- Removed `/hook` and `/stream` API paths in favor of `/api/(hook|stream)`. You may need to use the "Repair repository" button in the repo settings or "Repair all" in the admin settings to recreate the forge hook.
- Removed `WOODPECKER_DOCS` config variable
- Renamed `link` to `url` (including all API fields)
- Deprecated `CI_COMMIT_URL` env var, use `CI_PIPELINE_FORGE_URL`
## 1.0.0
- The signature used to verify extension calls (like those used for the [config-extension](./30-administration/100-external-configuration-api.md)) done by the Woodpecker server switched from using a shared-secret HMac to an ed25519 key-pair. Read more about it at the [config-extensions](./30-administration/100-external-configuration-api.md) documentation.
- Refactored support for old agent filter labels and expressions. Learn how to use the new [filter](./20-usage/20-workflow-syntax.md#labels)
- Renamed step environment variable `CI_SYSTEM_ARCH` to `CI_SYSTEM_PLATFORM`. Same applies for the cli exec variable.
- Renamed environment variables `CI_BUILD_*` and `CI_PREV_BUILD_*` to `CI_PIPELINE_*` and `CI_PREV_PIPELINE_*`, old ones are still available but deprecated
- Renamed environment variables `CI_JOB_*` to `CI_STEP_*`, old ones are still available but deprecated
- Renamed environment variable `CI_REPO_REMOTE` to `CI_REPO_CLONE_URL`, old is still available but deprecated
- Renamed environment variable `*_LINK` to `*_URL`, old ones are still available but deprecated
- Renamed API endpoints for pipelines (`<owner>/<repo>/builds/<buildId>` -> `<owner>/<repo>/pipelines/<pipelineId>`), old ones are still available but deprecated
- Updated Prometheus gauge `build_*` to `pipeline_*`
- Updated Prometheus gauge `*_job_*` to `*_step_*`
- Renamed config env `WOODPECKER_MAX_PROCS` to `WOODPECKER_MAX_WORKFLOWS` (still available as fallback)
- The pipelines are now also read from `.yaml` files, the new default order is `.woodpecker/*.yml` and `.woodpecker/*.yaml` (without any prioritization) -> `.woodpecker.yml` -> `.woodpecker.yaml`
- Dropped support for [Coding](https://coding.net/), [Gogs](https://gogs.io) and Bitbucket Server (Stash).
- `/api/queue/resume` & `/api/queue/pause` endpoint methods were changed from `GET` to `POST`
- rename `pipeline:` key in your workflow config to `steps:`
- If you want to migrate old logs to the new format, watch the error messages on start. If there are none we are good to go, else you have to plan a migration that can take hours. Set `WOODPECKER_MIGRATIONS_ALLOW_LONG` to true and let it run.
- Using `repo-id` in favor of `owner/repo` combination
- :warning: The api endpoints `/api/repos/{owner}/{repo}/...` were replaced by new endpoints using the repos id `/api/repos/{repo-id}`
- To find the id of a repo use the `/api/repos/lookup/{repo-full-name-with-slashes}` endpoint.
- The existing badge endpoint `/api/badges/{owner}/{repo}` will still work, but whenever possible try to use the new endpoint using the `repo-id`: `/api/badges/{repo-id}`.
- The UI urls for a repository changed from `/repos/{owner}/{repo}/...` to `/repos/{repo-id}/...`. You will be redirected automatically when using the old url.
- The woodpecker-go api-client is now using the `repo-id` instead of `owner/repo` for all functions
- Using `org-id` in favour of `owner` name
- :warning: The api endpoints `/api/orgs/{owner}/...` were replaced by new endpoints using the orgs id `/api/repos/{org-id}`
- To find the id of orgs use the `/api/orgs/lookup/{org_full_name}` endpoint.
- The UI urls for a organization changed from `/org/{owner}/...` to `/orgs/{org-id}/...`. You will be redirected automatically when using the old url.
- The woodpecker-go api-client is now using the `org-id` instead of `org name` for all functions
- The `command:` field has been removed from steps. If you were using it, please check if the entrypoint of the image you used is a shell.
- If it is a shell, simply rename `command:` to `commands:`.
- If it's not, you need to prepend the entrypoint before and also rename it (e.g., `commands: <entrypoint> <cmd>`).
## 0.15.0
- Default value for custom pipeline path is now empty / un-set which results in following resolution:
`.woodpecker/*.yml` -> `.woodpecker.yml` -> `.drone.yml`
Only projects created after updating will have an empty value by default. Existing projects will stick to the current pipeline path which is `.drone.yml` in most cases.
Read more about it at the [Project Settings](./20-usage/75-project-settings.md#pipeline-path)
- From version `0.15.0` ongoing there will be three types of docker images: `latest`, `next` and `x.x.x` with an alpine variant for each type like `latest-alpine`.
If you used `latest` before to try pre-release features you should switch to `next` after this release.
- Dropped support for `DRONE_*` environment variables. The according `WOODPECKER_*` variables must be used instead.
Additionally some alternative namings have been removed to simplify maintenance:
- `WOODPECKER_AGENT_SECRET` replaces `WOODPECKER_SECRET`, `DRONE_SECRET`, `WOODPECKER_PASSWORD`, `DRONE_PASSWORD` and `DRONE_AGENT_SECRET`.
- `WOODPECKER_HOST` replaces `DRONE_HOST` and `DRONE_SERVER_HOST`.
- `WOODPECKER_DATABASE_DRIVER` replaces `DRONE_DATABASE_DRIVER` and `DATABASE_DRIVER`.
- `WOODPECKER_DATABASE_DATASOURCE` replaces `DRONE_DATABASE_DATASOURCE` and `DATABASE_CONFIG`.
- Dropped support for `DRONE_*` environment variables in pipeline steps. Pipeline meta-data can be accessed with `CI_*` variables.
- `CI_*` prefix replaces `DRONE_*`
- `CI` value is now `woodpecker`
- `DRONE=true` has been removed
- Some variables got deprecated and will be removed in future versions. Please migrate to the new names. Same applies for `DRONE_` of them.
- CI_ARCH => use CI_SYSTEM_ARCH
- CI_COMMIT => CI_COMMIT_SHA
- CI_TAG => CI_COMMIT_TAG
- CI_PULL_REQUEST => CI_COMMIT_PULL_REQUEST
- CI_REMOTE_URL => use CI_REPO_REMOTE
- CI_REPO_BRANCH => use CI_REPO_DEFAULT_BRANCH
- CI_PARENT_BUILD_NUMBER => use CI_BUILD_PARENT
- CI_BUILD_TARGET => use CI_BUILD_DEPLOY_TARGET
- CI_DEPLOY_TO => use CI_BUILD_DEPLOY_TARGET
- CI_COMMIT_AUTHOR_NAME => use CI_COMMIT_AUTHOR
- CI_PREV_COMMIT_AUTHOR_NAME => use CI_PREV_COMMIT_AUTHOR
- CI_SYSTEM => use CI_SYSTEM_NAME
- CI_BRANCH => use CI_COMMIT_BRANCH
- CI_SOURCE_BRANCH => use CI_COMMIT_SOURCE_BRANCH
- CI_TARGET_BRANCH => use CI_COMMIT_TARGET_BRANCH
For all available variables and their descriptions have a look at [built-in-environment-variables](./20-usage/50-environment.md#built-in-environment-variables).
- Prometheus metrics have been changed from `drone_*` to `woodpecker_*`
- Base path has moved from `/var/lib/drone` to `/var/lib/woodpecker`
- Default workspace base path has moved from `/drone` to `/woodpecker`
- Default SQLite database location has changed:
- `/var/lib/drone/drone.sqlite` -> `/var/lib/woodpecker/woodpecker.sqlite`
- `drone.sqlite` -> `woodpecker.sqlite`
- Plugin Settings moved into `settings` section:
```diff
steps:
something:
image: my/plugin
- setting1: foo
- setting2: bar
+ settings:
+ setting1: foo
+ setting2: bar
```
- `WOODPECKER_DEBUG` option for server and agent got removed in favor of `WOODPECKER_LOG_LEVEL=debug`
- Remove unused server flags which can safely be removed from your server config: `WOODPECKER_QUIC`, `WOODPECKER_GITHUB_SCOPE`, `WOODPECKER_GITHUB_GIT_USERNAME`, `WOODPECKER_GITHUB_GIT_PASSWORD`, `WOODPECKER_GITHUB_PRIVATE_MODE`, `WOODPECKER_GITEA_GIT_USERNAME`, `WOODPECKER_GITEA_GIT_PASSWORD`, `WOODPECKER_GITEA_PRIVATE_MODE`, `WOODPECKER_GITLAB_GIT_USERNAME`, `WOODPECKER_GITLAB_GIT_PASSWORD`, `WOODPECKER_GITLAB_PRIVATE_MODE`
- Dropped support for manually setting the agents platform with `WOODPECKER_PLATFORM`. The platform is now automatically detected.
- Use `WOODPECKER_STATUS_CONTEXT` instead of the deprecated options `WOODPECKER_GITHUB_CONTEXT` and `WOODPECKER_GITEA_CONTEXT`.
## 0.14.0
No breaking changes
## From Drone
:::warning
Migration from Drone is only possible if you were running Drone <= v0.8.
:::
1. Make sure you are already running Drone v0.8
2. Upgrade to Woodpecker v0.14.4, migration will be done during startup
3. Upgrade to the latest Woodpecker version. Pay attention to the breaking changes listed above.

67
docs/versioned_docs/version-2.6/92-awesome.md
View File

@ -1,67 +0,0 @@
# Awesome Woodpecker
A curated list of awesome things related to Woodpecker CI.
If you have some missing resources, please feel free to [open a pull-request](https://github.com/woodpecker-ci/woodpecker/edit/main/docs/docs/92-awesome.md) and add them.
## Official Resources
- [Woodpecker CI pipeline configs](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) - Complex setup containing different kind of pipelines
- [Golang tests](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/test.yaml)
- [Typescript, eslint & Vue](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/web.yaml)
- [Docusaurus & publishing to GitHub Pages](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docs.yaml)
- [Docker container building](https://github.com/woodpecker-ci/woodpecker/blob/main/.woodpecker/docker.yaml)
## Projects using Woodpecker
- [Woodpecker CI](https://github.com/woodpecker-ci/woodpecker/tree/main/.woodpecker) itself
- [All official plugins](https://github.com/woodpecker-ci?q=plugin&type=all)
- [dessalines/thumb-key](https://github.com/dessalines/thumb-key/blob/main/.woodpecker.yml) - Android Jetpack compose linting and building
- [Vieter](https://git.rustybever.be/vieter-v/vieter) - Archlinux/Pacman repository server & automated package build system
- [Rieter](https://git.rustybever.be/Chewing_Bever/rieter) - Rewrite of the Vieter project in Rust
- [Alex](https://git.rustybever.be/Chewing_Bever/alex) - Minecraft server wrapper designed to automate backups & complement Docker installations
## Tools
- [Convert Drone CI pipelines to Woodpecker CI](https://codeberg.org/lafriks/woodpecker-pipeline-transform)
- [Ansible NAS](https://github.com/davestephens/ansible-nas/) - a homelab Ansible playbook that can set up Woodpecker CI and Gitea
- [picus](https://github.com/windsource/picus) - Picus connects to a Woodpecker CI server and creates an agent in the cloud when there are pending workflows.
- [Hetzner cloud](https://www.hetzner.com/cloud) based [Woodpecker compatible autoscaler](https://git.ljoonal.xyz/ljoonal/hetzner-ci-autoscaler) - Creates and destroys VPS instances based on the count of pending & running jobs.
- [woodpecker-lint](https://git.schmidl.dev/schtobia/woodpecker-lint) - A repository for linting a Woodpecker config file via pre-commit hook
- [Grafana Dashboard](https://github.com/Janik-Haag/woodpecker-grafana-dashboard) - A dashboard visualizing information exposed by the Woodpecker prometheus endpoint.
- [woodpecker-autoscaler](https://github.com/Lerentis/woodpecker-autoscaler) - Yet another Woodpecker autoscaler currently targeting [Hetzner cloud](https://www.hetzner.com/cloud) that works in parallel to other autoscaler implementations.
## Configuration Services
- [Dynamic Pipelines for Nix Flakes](https://github.com/pinpox/woodpecker-flake-pipeliner) - Define pipelines as Nix Flake outputs
## Pipelines
- [Collection of pipeline examples](https://codeberg.org/Codeberg-CI/examples)
## Posts & tutorials
- [Setup Gitea with Woodpecker CI](https://containers.fan/posts/setup-gitea-with-woodpecker-ci/)
- [Step-by-step guide to modern, secure and Open-source CI setup](https://devforth.io/blog/step-by-step-guide-to-modern-secure-ci-setup/)
- [Using Woodpecker CI for my static sites](https://jan.wildeboer.net/2022/07/Woodpecker-CI-Jekyll/)
- [Woodpecker CI @ Codeberg](https://www.sarkasti.eu/articles/post/woodpecker/)
- [Deploy Docker/Compose using Woodpecker CI](https://hinty.io/vverenko/deploy-docker-compose-using-woodpecker-ci/)
- [Installing Woodpecker CI in your personal homelab](https://pwa.io/articles/installing-woodpecker-in-your-homelab/)
- [Locally Cached Nix CI with Woodpecker](https://blog.kotatsu.dev/posts/2023-04-21-woodpecker-nix-caching/)
- [How to run Cypress auto-tests on Woodpecker CI and report results to Slack](https://devforth.io/blog/how-to-run-cypress-auto-tests-on-woodpecker-ci-and-report-results-to-slack/)
- [Quest For CICD - WoodpeckerCI](https://omaramin.me/posts/woodpecker/)
- [Getting started with Woodpecker CI](https://systeemkabouter.eu/getting-started-with-woodpecker-ci.html)
- [Installing gitea and woodpecker using binary packages](https://neelex.com/2023/03/26/Installing-gitea-using-binary-packages/)
- [Deploying mdbook to codeberg pages using woodpecker CI](https://www.markpitblado.me/blog/deploying-mdbook-to-codeberg-pages-using-woodpecker-ci/)
- [Deploy a Fly app with Woodpecker CI](https://joeroe.io/2024/01/09/deploy-fly-woodpecker-ci.html)
- [Ansible - using Woodpecker as an alternative to Semaphore](https://pat-s.me/ansible-using-woodpecker-as-an-alternative-to-semaphore/)
## Videos
- [Replace Ansible Semaphore with Woodpecker CI](https://www.youtube.com/watch?v=d610YPvCB0E)
- ["unexpected EOF" error when trying to pair Woodpecker CI served through the Caddy with Gitea](https://www.youtube.com/watch?v=n7Hyvt71Np0)
- [CICD Environment in Docker Swarm behind Caddy Server - Part 2 Woodpeckerci](https://www.youtube.com/watch?v=rkbw_k7JvS0)
## Plugins
We have a separate [index](/plugins) for plugins.

BIN
docs/versioned_docs/version-2.6/woodpecker.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 70 KiB

2
docs/versioned_docs/version-2.7/92-development/09-swagger.md
View File

@ -55,7 +55,7 @@ make generate-swagger
```
```bash title="update the Markdown in the ./docs folder"
make docs
make generate-docs
```
```bash title="auto-format swagger related godoc"

2
docs/versioned_docs/version-2.8/92-development/09-swagger.md
View File

@ -55,7 +55,7 @@ make generate-swagger
```
```bash title="update the Markdown in the ./docs folder"
make docs
make generate-docs
```
```bash title="auto-format swagger related godoc"

26
docs/versioned_docs/version-3.0/10-intro/index.md Normal file
View File

@ -0,0 +1,26 @@
# Welcome to Woodpecker
Woodpecker is a CI/CD tool. It is designed to be lightweight, simple to use and fast. Before we dive into the details, let's have a look at some of the basics.
## Have you ever heard of CI/CD or pipelines?
Don't worry if you haven't. We'll guide you through the basics. CI/CD stands for Continuous Integration and Continuous Deployment. It's basically like a conveyor belt that moves your code from development to production doing all kinds of
checks, tests and routines along the way. A typical pipeline might include the following steps:
1. Running tests
2. Building your application
3. Deploying your application
[Have a deeper look into the idea of CI/CD](https://www.redhat.com/en/topics/devops/what-is-ci-cd)
## Do you know containers?
If you are already using containers in your daily workflow, you'll for sure love Woodpecker. If not yet, you'll be amazed how easy it is to get started with [containers](https://opencontainers.org/).
## Already have access to a Woodpecker instance?
Then you might want to jump directly into it and [start creating your first pipelines](../20-usage/10-intro.md).
## Want to start from scratch and deploy your own Woodpecker instance?
Woodpecker is [pretty lightweight](../30-administration/00-getting-started.md#hardware-requirements) and will even run on your Raspberry Pi. You can follow the [deployment guide](../30-administration/00-getting-started.md) to set up your own Woodpecker instance.

110
docs/versioned_docs/version-3.0/20-usage/10-intro.md Normal file
View File

@ -0,0 +1,110 @@
# Your first pipeline
Let's get started and create your first pipeline.
## 1. Repository Activation
To activate your repository in Woodpecker navigate to the repository list and `New repository`. You will see a list of repositories from your forge (GitHub, Gitlab, ...) which can be activated with a simple click.
![new repository list](repo-new.png)
To enable a repository in Woodpecker you must have `Admin` rights on that repository, so that Woodpecker can add something
that is called a webhook (Woodpecker needs it to know about actions like pushes, pull requests, tags, etc.).
## 2. Define first workflow
After enabling a repository Woodpecker will listen for changes in your repository. When a change is detected, Woodpecker will check for a pipeline configuration. So let's create a file at `.woodpecker/my-first-workflow.yaml` inside your repository:
```yaml title=".woodpecker/my-first-workflow.yaml"
when:
- event: push
branch: main
steps:
- name: build
image: debian
commands:
- echo "This is the build step"
- echo "binary-data-123" > executable
- name: a-test-step
image: golang:1.16
commands:
- echo "Testing ..."
- ./executable
```
**So what did we do here?**
1. We defined your first workflow file `my-first-workflow.yaml`.
2. This workflow will be executed when a push event happens on the `main` branch,
because we added a filter using the `when` section:
```diff
+ when:
+ - event: push
+ branch: main
...
```
3. We defined two steps: `build` and `a-test-step`
The steps are executed in the order they are defined, so `build` will be executed first and then `a-test-step`.
In the `build` step we use the `debian` image and build a "binary file" called `executable`.
In the `a-test-step` we use the `golang:1.16` image and run the `executable` file to test it.
You can use any image from registries like the [Docker Hub](https://hub.docker.com/search?type=image) you have access to:
```diff
steps:
- name: build
- image: debian
+ image: my-company/image-with-aws_cli
commands:
- aws help
```
## 3. Push the file and trigger first pipeline
If you push this file to your repository now, Woodpecker will already execute your first pipeline.
You can check the pipeline execution in the Woodpecker UI by navigating to the `Pipelines` section of your repository.
![pipeline view](./pipeline.png)
As you probably noticed, there is another step in called `clone` which is executed before your steps. This step clones your repository into a folder called `workspace` which is available throughout all steps.
This for example allows the first step to build your application using your source code and as the second step will receive
the same workspace it can use the previously built binary and test it.
## 4. Use a plugin for reusable tasks
Sometimes you have some tasks that you need to do in every project. For example, deploying to Kubernetes or sending a Slack message. Therefore you can use one of the [official and community plugins](/plugins) or simply [create your own](./51-plugins/20-creating-plugins.md).
If you want to get a Slack notification after your pipeline has finished, you can add a Slack plugin to your pipeline:
```yaml
steps:
# ...
- name: notify me on Slack
image: plugins/slack
settings:
channel: developers
username: woodpecker
password:
from_secret: slack_token
when:
status: [success, failure] # This will execute the step on success and failure
```
To configure a plugin you can use the `settings` section.
Sometime you need to provide secrets to the plugin. You can do this by using the `from_secret` key. The secret must be defined in the Woodpecker UI. You can find more information about secrets [here](./40-secrets.md).
Similar to the `when` section at the top of the file which is for the complete workflow, you can use the `when` section for each step to define when a step should be executed.
Learn more about [plugins](./51-plugins/51-overview.md).
As you now have a basic understanding of how to create a pipeline, you can dive deeper into the [workflow syntax](./20-workflow-syntax.md) and [plugins](./51-plugins/51-overview.md).

0
docs/versioned_docs/version-2.6/20-usage/100-troubleshooting.md → docs/versioned_docs/version-3.0/20-usage/100-troubleshooting.md
View File

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

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

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 31 KiB

37
docs/versioned_docs/version-2.6/20-usage/15-terminology/index.md → docs/versioned_docs/version-3.0/20-usage/15-terminology/index.md
View File

@ -1,13 +1,5 @@
# Terminology
## Woodpecker architecture
![Woodpecker architecture](architecture.svg)
## Pipeline, workflow & step
![Relation between pipelines, workflows and steps](pipeline-workflow-step.svg)
## Glossary
- **Woodpecker CI**: The project name around Woodpecker.
@ -15,33 +7,31 @@
- **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][Pipeline]**: A sequence of [workflows][Workflow] that are executed on the code. Pipelines are triggered by events.
- **[Workflow][Workflow]**: A sequence of steps and services that are executed as part of a [pipeline][Pipeline]. Workflows are represented by YAML files. Each workflow has its own isolated [workspace][Workspace], and often additional resources like a shared network (docker).
- **Steps**: Individual commands, actions or tasks within a [workflow][Workflow].
- **Code**: Refers to the files tracked by the version control system used by the [forge][Forge].
- **Repos**: Short for repositories, these are storage locations where code is stored.
- **Forge**: The hosting platform or service where the repositories are hosted.
- **Workspace**: A folder shared between all steps of a [workflow][Workflow] containing the repository and all the generated data from previous steps.
- **Event**: Triggers the execution of a [pipeline][Pipeline], such as a [forge][Forge] event like `push`, or `manual` triggered manually from the UI.
- **[Forge][Forge]**: The hosting platform or service where the repositories are hosted.
- **[Workspace][workspace]**: A folder shared between all steps of a [workflow][Workflow] containing the repository and all the generated data from previous steps.
- **[Event][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].
- **[Matrix][Matrix]**: A configuration option that allows the execution of [workflows][Workflow] for each value in the 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.
- **[Plugins][Plugin]**: Plugins 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].
- **Service extension**: Some parts of Woodpecker internal services like secrets storage or config fetcher can be replaced through service extensions.
## Pipeline events
## Woodpecker architecture
- `push`: A push event is triggered when a commit is pushed to a branch.
- `pull_request`: A pull request event is triggered when a pull request is opened or a new commit is pushed to it.
- `pull_request_closed`: A pull request closed event is triggered when a pull request is closed or merged.
- `tag`: A tag event is triggered when a tag is pushed.
- `release`: A release event is triggered when a release, pre-release or draft is created. (You can apply further filters using [evaluate](../20-workflow-syntax.md#evaluate) with [environment variables](../50-environment.md#built-in-environment-variables).)
- `manual`: A manual event is triggered when a user manually triggers a pipeline.
- `cron`: A cron event is triggered when a cron job is executed.
![Woodpecker architecture](architecture.svg)
## Pipeline, workflow & step
![Relation between pipelines, workflows and steps](pipeline-workflow-step.svg)
## Conventions
@ -54,6 +44,7 @@ Sometimes there are multiple terms that can be used to describe something. This
<!-- References -->
[Event]: ../20-workflow-syntax.md#event
[Pipeline]: ../20-workflow-syntax.md
[Workflow]: ../25-workflows.md
[Forge]: ../../30-administration/11-forges/11-overview.md

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

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

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 21 KiB

73
docs/versioned_docs/version-2.6/20-usage/20-workflow-syntax.md → docs/versioned_docs/version-3.0/20-usage/20-workflow-syntax.md
View File

@ -6,6 +6,11 @@ The Workflow section defines a list of steps to build, test and deploy your code
An exception to this rule are steps with a [`status: [failure]`](#status) condition, which ensures that they are executed in the case of a failed run.
:::
:::note
We support most of YAML 1.2, but preserve some behavior from 1.1 for backward compatibility.
Read more at: [https://github.com/go-yaml/yaml](https://github.com/go-yaml/yaml/tree/v3)
:::
Example steps:
```yaml
@ -99,7 +104,7 @@ When using the `local` backend, the `image` entry is used to specify the shell,
- go test
- name: publish
+ image: plugins/docker
+ image: woodpeckerci/plugin-kaniko
repo: foo/bar
services:
@ -174,12 +179,6 @@ Woodpecker provides the ability to pass environment variables to individual step
For more details, check the [environment docs](./50-environment.md).
### `secrets`
Woodpecker provides the ability to store named parameters external to the YAML configuration file, in a central secret store. These secrets can be passed to individual steps of the workflow at runtime.
For more details, check the [secrets docs](./40-secrets.md).
### `failure`
Some of the steps may be allowed to fail without causing the whole workflow and therefore pipeline to report a failure (e.g., a step executing a linting check). To enable this, add `failure: ignore` to your step. If Woodpecker encounters an error while executing the step, it will report it as failed but still executes the next steps of the workflow, if any, without affecting the status of the workflow.
@ -196,7 +195,7 @@ 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 is evaluated to true if _all_ subconditions are true.
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 is evaluated to true if _all_ sub-conditions are true.
A condition can be a check like:
```diff
@ -215,7 +214,7 @@ A condition can be a check like:
The `slack` step is executed if one of these conditions is met:
1. The pipeline is executed from a pull request in the repo `test/test`
2. The pipeline is executed from a push to `maiǹ`
2. The pipeline is executed from a push to `main`
#### `repo`
@ -283,7 +282,16 @@ when:
#### `event`
Available events: `push`, `pull_request`, `pull_request_closed`, `tag`, `release`, `deployment`, `cron`, `manual`
The available events are:
- `push`: triggered when a commit is pushed to a branch.
- `pull_request`: triggered when a pull request is opened or a new commit is pushed to it.
- `pull_request_closed`: triggered when a pull request is closed or merged.
- `tag`: triggered when a tag is pushed.
- `release`: triggered when a release, pre-release or draft is created. (You can apply further filters using [evaluate](#evaluate) with [environment variables](./50-environment.md#built-in-environment-variables).)
- `deployment`: triggered when a deployment is created in the repository. (This event can be triggered from Woodpecker directly. GitHub also supports webhook triggers.)
- `cron`: triggered when a cron job is executed.
- `manual`: triggered when a user manually triggers a pipeline.
Execute a step if the build event is a `tag`:
@ -470,7 +478,7 @@ Normally steps of a workflow are executed serially in the order in which they ar
- go build
- name: deploy
image: plugins/docker
image: woodpeckerci/plugin-kaniko
settings:
repo: foo/bar
+ depends_on: [build, test] # deploy will be executed after build and test finished
@ -518,7 +526,9 @@ For more details check the [services docs](./60-services.md).
## `workspace`
The workspace defines the shared volume and working directory shared by all workflow steps. The default workspace matches the pattern `/woodpecker/src/github.com/octocat/hello-world`, based on your repository URL.
The workspace defines the shared volume and working directory shared by all workflow steps.
The default workspace base is `/woodpecker` and the path is extended with the repository URL (`src/{url-without-schema}`).
So an example would be `/woodpecker/src/github.com/octocat/hello-world`.
The workspace can be customized using the workspace block in the YAML file:
@ -535,6 +545,10 @@ The workspace can be customized using the workspace block in the YAML file:
- go test
```
:::note
Plugins will always have the workspace base at `/woodpecker`
:::
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
@ -590,7 +604,7 @@ For more details check the [matrix build docs](./30-matrix-workflows.md).
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_agent_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.
@ -672,16 +686,6 @@ Example configuration to use a custom clone plugin:
+ image: octocat/custom-git-plugin
```
Example configuration to clone Mercurial repository:
```diff
clone:
- name: hg
+ image: plugins/hg
+ settings:
+ path: bitbucket.org/foo/bar
```
### Git Submodules
To use the credentials that cloned the repository to clone it's submodules, update `.gitmodules` to use `https` instead of `git`:
@ -749,6 +753,25 @@ Woodpecker supports to define multiple workflows for a repository. Those workflo
Workflows that should run even on failure should set the `runs_on` tag. See [here](./25-workflows.md#flow-control) for an example.
## Advanced network options for steps
:::warning
Only allowed if 'Trusted Network' option is enabled in repo settings by an admin.
:::
### `dns`
If the backend engine understands to change the DNS server and lookup domain,
this options will be used to alter the default DNS config to a custom one for a specific step.
```yaml
steps:
- name: build
image: plugin/abc
dns: 1.2.3.4
dns_search: 'internal.company'
```
## Privileged mode
Woodpecker gives the ability to configure privileged mode in the YAML. You can use this parameter to launch containers with escalated capabilities.
@ -766,8 +789,8 @@ Privileged mode is only available to trusted repositories and for security reaso
commands:
- docker --tls=false ps
- name: services
docker:
services:
- name: docker
image: docker:dind
commands: dockerd-entrypoint.sh --storage-driver=vfs --tls=false
+ privileged: true

16
docs/versioned_docs/version-2.6/20-usage/25-workflows.md → docs/versioned_docs/version-3.0/20-usage/25-workflows.md
View File

@ -23,13 +23,13 @@ If you still need to pass artifacts between the workflows you need use some stor
```bash
.woodpecker/
├── .build.yaml
├── .deploy.yaml
├── .lint.yaml
└── .test.yaml
├── build.yaml
├── deploy.yaml
├── lint.yaml
└── test.yaml
```
```yaml title=".woodpecker/.build.yaml"
```yaml title=".woodpecker/build.yaml"
steps:
- name: build
image: debian:stable-slim
@ -38,7 +38,7 @@ steps:
- sleep 5
```
```yaml title=".woodpecker/.deploy.yaml"
```yaml title=".woodpecker/deploy.yaml"
steps:
- name: deploy
image: debian:stable-slim
@ -51,7 +51,7 @@ depends_on:
- test
```
```yaml title=".woodpecker/.test.yaml"
```yaml title=".woodpecker/test.yaml"
steps:
- name: test
image: debian:stable-slim
@ -63,7 +63,7 @@ depends_on:
- build
```
```yaml title=".woodpecker/.lint.yaml"
```yaml title=".woodpecker/lint.yaml"
steps:
- name: lint
image: debian:stable-slim

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

156
docs/versioned_docs/version-3.0/20-usage/40-secrets.md Normal file
View File

@ -0,0 +1,156 @@
# Secrets
Woodpecker provides the ability to store named variables in a central secret store.
These secrets can be passed securely to individual pipeline steps using the `from_secret` keyword.
Three different levels of secrets are available.
The following list shows the priority of these.
If a secret is defined in multiple levels, the following precedence applies: Repository secrets > Organization secrets > Global secrets.
1. **Repository secrets**: Available to all pipelines of a repository.
1. **Organization secrets**: Available to all pipelines of an organization.
1. **Global secrets**: Can only be set by instance admins.
Global secret are available to all pipelines of the **entire** Woodpecker instance and should therefore be used with caution.
:::tip
In addition to the native secret integration, external secret providers can be utilized by interacting with them directly within pipeline steps.
Access to these providers can be configured using Woodpecker secrets, enabling the retrieval of secrets from the respective external sources.
:::
:::warning
Woodpecker can mask secrets from its native secret store, but it cannot apply the same protection to external secrets. As a result, these external secrets may be exposed in the pipeline logs.
:::
## Usage
You can set a setting or environment value from Woodpecker secrets using the `from_secret` syntax.
The example below passes a secret called `secret_token` which will be stored in an environment variable named `TOKEN_ENV`:
```diff
steps:
- name: 'step name'
image: registry/repo/image:tag
commands:
+ - echo "The secret is $TOKEN_ENV"
+ environment:
+ TOKEN_ENV:
+ from_secret: secret_token
```
The same syntax can be used to pass secrets to (plugin) settings.
A secret named `secret_token` is assigned to the setting `TOKEN`, which will then be available in the plugin as environment variable `PLUGIN_TOKEN` (see [plugins](./51-plugins/20-creating-plugins.md#settings) for details).
`PLUGIN_TOKEN` is then internally consumed by the plugin itself and will be honored during execution.
```diff
steps:
- name: 'step name'
image: registry/repo/image:tag
+ settings:
+ TOKEN:
+ from_secret: secret_token
```
### Note about parameter pre-processing
Please note that parameter expressions undergo pre-processing, meaning they are evaluated before the pipeline starts.
If secrets are to be used in expressions, they must be properly escaped (using `$$`) to ensure correct handling.
```diff
steps:
- name: docker
image: docker
commands:
- - echo ${TOKEN_ENV}
+ - echo $${TOKEN_ENV}
environment:
TOKEN_ENV:
from_secret: secret_token
```
### Use in Pull Requests events
By default, secrets are not exposed to pull requests.
However, you can change this behavior by creating the secret and enabling the `pull_request` event type.
This can be configured either through the UI or via the CLI, as demonstrated below.
:::warning
Be cautious when exposing secrets to pull requests.
If your repository is public and initiates pull request runs without requiring approval, your secrets may be at risk.
Malicious actors could potentially exploit this to expose or transmit your secrets to an external location.
:::
## Plugins filter
To prevent abusing your secrets from malicious usage, you can limit a secret to a list of plugins.
If enabled they are not available to any other plugin (steps without user-defined commands).
Plugins have the advantage that they cannot run arbitrary commands, hence they cannot be used to expose secrets (in contrast to arbitrary steps).
:::note
If you specify a tag, the filter will honor it.
However, if the same image appears multiple times in the list, the least privileged entry takes precedence.
For example, an image without a tag will permit all tags, even if another entry with a pinned tag is included.
:::
![plugins filter](./secrets-plugins-filter.png)
## Adding Secrets
Secrets can be added through the UI or via the CLI.
### CLI Examples
Create the secret using default settings.
The secret will be available to all images in your pipeline, and will be available to all `push`, `tag`, and `deployment` events (not `pull_request` events).
```bash
woodpecker-cli repo secret add \
--repository octocat/hello-world \
--name aws_access_key_id \
--value <value>
```
Create the secret and limit it to a single image:
```diff
woodpecker-cli secret add \
--repository octocat/hello-world \
+ --image woodpeckerci/plugin-s3 \
--name aws_access_key_id \
--value <value>
```
Create the secrets and limit it to a set of images:
```diff
woodpecker-cli repo secret add \
--repository octocat/hello-world \
+ --image woodpeckerci/plugin-s3 \
+ --image woodpeckerci/plugin-docker-buildx \
--name aws_access_key_id \
--value <value>
```
Create the secret and enable it for multiple hook events:
```diff
woodpecker-cli repo secret add \
--repository octocat/hello-world \
--image woodpeckerci/plugin-s3 \
+ --event pull_request \
+ --event push \
+ --event tag \
--name aws_access_key_id \
--value <value>
```
Secrets can be loaded from a file using the `@` syntax.
This method is recommended for loading secrets from a file, as it ensures that newlines are preserved (this is for example important for SSH keys).
Here’s an example:
```diff
woodpecker-cli repo secret add \
-repository octocat/hello-world \
-name ssh_key \
+ -value @/root/ssh/id_rsa
```

8
docs/versioned_docs/version-2.6/20-usage/41-registries.md → docs/versioned_docs/version-3.0/20-usage/41-registries.md
View File

@ -32,12 +32,8 @@ Example registry hostname matching logic:
- Hostname `gcr.io` matches image `gcr.io/foo/bar`
- Hostname `docker.io` matches `golang`
- Hostname `docker.io` matches `library/golang`
- Hostname `docker.io` matches `bradyrydzewski/golang`
- Hostname `docker.io` matches `bradyrydzewski/golang:latest`
:::note
The flow above doesn't work in Kubernetes. There is [workaround](../30-administration/22-backends/40-kubernetes.md#images-from-private-registries).
:::
- Hostname `docker.io` matches `bradrydzewski/golang`
- Hostname `docker.io` matches `bradrydzewski/golang:latest`
## Global registry support

10
docs/versioned_docs/version-2.6/20-usage/45-cron.md → docs/versioned_docs/version-3.0/20-usage/45-cron.md
View File

@ -23,12 +23,6 @@ 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 <https://pkg.go.dev/github.com/robfig/cron?utm_source=godoc#hdr-CRON_Expression_Format>. If you need general understanding of the cron syntax <https://it-tools.tech/crontab-generator> is a good place to start and experiment.
The supported schedule syntax can be found at <https://pkg.go.dev/github.com/gdgvda/cron#hdr-CRON_Expression_Format>. If you need general understanding of the cron syntax <https://it-tools.tech/crontab-generator> is a good place to start and experiment.
Examples: `@every 5m`, `@daily`, `0 30 * * * *` ...
:::info
Woodpeckers cron syntax starts with seconds instead of minutes as used by most linux cron schedulers.
Example: "At minute 30 every hour" would be `0 30 * * * *` instead of `30 * * * *`
:::
Examples: `@every 5m`, `@daily`, `30 * * * *` ...

187
docs/versioned_docs/version-2.6/20-usage/50-environment.md → docs/versioned_docs/version-3.0/20-usage/50-environment.md
View File

@ -48,97 +48,94 @@ Please note that the environment section is not able to expand environment varia
This is the reference list of all environment variables available to your pipeline containers. These are injected into your pipeline step and plugins containers, at runtime.
| NAME | Description |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `CI` | CI environment name (value: `woodpecker`) |
| | **Repository** |
| `CI_REPO` | repository full name `<owner>/<name>` |
| `CI_REPO_OWNER` | repository owner |
| `CI_REPO_NAME` | repository name |
| `CI_REPO_REMOTE_ID` | repository remote ID, is the UID it has in the forge |
| `CI_REPO_SCM` | repository SCM (git) |
| `CI_REPO_URL` | repository web URL |
| `CI_REPO_CLONE_URL` | repository clone URL |
| `CI_REPO_CLONE_SSH_URL` | repository SSH clone URL |
| `CI_REPO_DEFAULT_BRANCH` | repository default branch (main) |
| `CI_REPO_PRIVATE` | repository is private |
| `CI_REPO_TRUSTED` | repository is trusted |
| | **Current Commit** |
| `CI_COMMIT_SHA` | commit SHA |
| `CI_COMMIT_REF` | commit ref |
| `CI_COMMIT_REFSPEC` | commit ref spec |
| `CI_COMMIT_BRANCH` | commit branch (equals target branch for pull requests) |
| `CI_COMMIT_SOURCE_BRANCH` | commit source branch (empty if event is not `pull_request` or `pull_request_closed`) |
| `CI_COMMIT_TARGET_BRANCH` | commit target branch (empty if event is not `pull_request` or `pull_request_closed`) |
| `CI_COMMIT_TAG` | commit tag name (empty if event is not `tag`) |
| `CI_COMMIT_PULL_REQUEST` | commit pull request number (empty if event is not `pull_request` or `pull_request_closed`) |
| `CI_COMMIT_PULL_REQUEST_LABELS` | labels assigned to pull request (empty if event is not `pull_request` or `pull_request_closed`) |
| `CI_COMMIT_MESSAGE` | commit message |
| `CI_COMMIT_AUTHOR` | commit author username |
| `CI_COMMIT_AUTHOR_EMAIL` | commit author email address |
| `CI_COMMIT_AUTHOR_AVATAR` | commit author avatar |
| `CI_COMMIT_PRERELEASE` | release is a pre-release (empty if event is not `release`) |
| | **Current pipeline** |
| `CI_PIPELINE_NUMBER` | pipeline number |
| `CI_PIPELINE_PARENT` | number of parent pipeline |
| `CI_PIPELINE_EVENT` | pipeline event (see [pipeline events](../20-usage/15-terminology/index.md#pipeline-events)) |
| `CI_PIPELINE_URL` | link to the web UI for the pipeline |
| `CI_PIPELINE_FORGE_URL` | link to the forge's web UI for the commit(s) or tag that triggered the pipeline |
| `CI_PIPELINE_DEPLOY_TARGET` | pipeline deploy target for `deployment` events (i.e. production) |
| `CI_PIPELINE_DEPLOY_TASK` | pipeline deploy task for `deployment` events (i.e. migration) |
| `CI_PIPELINE_STATUS` | pipeline status (success, failure) |
| `CI_PIPELINE_CREATED` | pipeline created UNIX timestamp |
| `CI_PIPELINE_STARTED` | pipeline started UNIX timestamp |
| `CI_PIPELINE_FINISHED` | pipeline finished UNIX timestamp |
| `CI_PIPELINE_FILES` | changed files (empty if event is not `push` or `pull_request`), it is undefined if more than 500 files are touched |
| | **Current workflow** |
| `CI_WORKFLOW_NAME` | workflow name |
| | **Current step** |
| `CI_STEP_NAME` | step name |
| `CI_STEP_NUMBER` | step number |
| `CI_STEP_STATUS` | step status (success, failure) |
| `CI_STEP_STARTED` | step started UNIX timestamp |
| `CI_STEP_FINISHED` | step finished UNIX timestamp |
| `CI_STEP_URL` | URL to step in UI |
| | **Previous commit** |
| `CI_PREV_COMMIT_SHA` | previous commit SHA |
| `CI_PREV_COMMIT_REF` | previous commit ref |
| `CI_PREV_COMMIT_REFSPEC` | previous commit ref spec |
| `CI_PREV_COMMIT_BRANCH` | previous commit branch |
| `CI_PREV_COMMIT_SOURCE_BRANCH` | previous commit source branch |
| `CI_PREV_COMMIT_TARGET_BRANCH` | previous commit target branch |
| `CI_PREV_COMMIT_URL` | previous commit link in forge |
| `CI_PREV_COMMIT_MESSAGE` | previous commit message |
| `CI_PREV_COMMIT_AUTHOR` | previous commit author username |
| `CI_PREV_COMMIT_AUTHOR_EMAIL` | previous commit author email address |
| `CI_PREV_COMMIT_AUTHOR_AVATAR` | previous commit author avatar |
| | **Previous pipeline** |
| `CI_PREV_PIPELINE_NUMBER` | previous pipeline number |
| `CI_PREV_PIPELINE_PARENT` | previous pipeline number of parent pipeline |
| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (see [pipeline events](../20-usage/15-terminology/index.md#pipeline-events)) |
| `CI_PREV_PIPELINE_URL` | previous pipeline link in CI |
| `CI_PREV_PIPELINE_FORGE_URL` | previous pipeline link to event in forge |
| `CI_PREV_PIPELINE_DEPLOY_TARGET` | previous pipeline deploy target for `deployment` events (ie production) |
| `CI_PREV_PIPELINE_DEPLOY_TASK` | previous pipeline deploy task for `deployment` events (ie migration) |
| `CI_PREV_PIPELINE_STATUS` | previous pipeline status (success, failure) |
| `CI_PREV_PIPELINE_CREATED` | previous pipeline created UNIX timestamp |
| `CI_PREV_PIPELINE_STARTED` | previous pipeline started UNIX timestamp |
| `CI_PREV_PIPELINE_FINISHED` | previous pipeline finished UNIX timestamp |
| | &emsp; |
| `CI_WORKSPACE` | Path of the workspace where source code gets cloned to |
| | **System** |
| `CI_SYSTEM_NAME` | name of the CI system: `woodpecker` |
| `CI_SYSTEM_URL` | link to CI system |
| `CI_SYSTEM_HOST` | hostname of CI server |
| `CI_SYSTEM_VERSION` | version of the server |
| | **Forge** |
| `CI_FORGE_TYPE` | name of forge (gitea, github, ...) |
| `CI_FORGE_URL` | root URL of configured forge |
| | **Internal** - Please don't use! |
| `CI_SCRIPT` | Internal script path. Used to call pipeline step commands. |
| `CI_NETRC_USERNAME` | Credentials for private repos to be able to clone data. (Only available for specific images) |
| `CI_NETRC_PASSWORD` | Credentials for private repos to be able to clone data. (Only available for specific images) |
| `CI_NETRC_MACHINE` | Credentials for private repos to be able to clone data. (Only available for specific images) |
| NAME | Description | Example |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `CI` | CI environment name | `woodpecker` |
| | **Repository** | |
| `CI_REPO` | repository full name `<owner>/<name>` | `john-doe/my-repo` |
| `CI_REPO_OWNER` | repository owner | `john-doe` |
| `CI_REPO_NAME` | repository name | `my-repo` |
| `CI_REPO_REMOTE_ID` | repository remote ID, is the UID it has in the forge | `82` |
| `CI_REPO_URL` | repository web URL | `https://git.example.com/john-doe/my-repo` |
| `CI_REPO_CLONE_URL` | repository clone URL | `https://git.example.com/john-doe/my-repo.git` |
| `CI_REPO_CLONE_SSH_URL` | repository SSH clone URL | `git@git.example.com:john-doe/my-repo.git` |
| `CI_REPO_DEFAULT_BRANCH` | repository default branch | `main` |
| `CI_REPO_PRIVATE` | repository is private | `true` |
| `CI_REPO_TRUSTED_NETWORK` | repository has trusted network access | `false` |
| `CI_REPO_TRUSTED_VOLUMES` | repository has trusted volumes access | `false` |
| `CI_REPO_TRUSTED_SECURITY` | repository has trusted security access | `false` |
| | **Current Commit** | |
| `CI_COMMIT_SHA` | commit SHA | `eba09b46064473a1d345da7abf28b477468e8dbd` |
| `CI_COMMIT_REF` | commit ref | `refs/heads/main` |
| `CI_COMMIT_REFSPEC` | commit ref spec | `issue-branch:main` |
| `CI_COMMIT_BRANCH` | commit branch (equals target branch for pull requests) | `main` |
| `CI_COMMIT_SOURCE_BRANCH` | commit source branch (set only for `pull_request` and `pull_request_closed` events) | `issue-branch` |
| `CI_COMMIT_TARGET_BRANCH` | commit target branch (set only for `pull_request` and `pull_request_closed` events) | `main` |
| `CI_COMMIT_TAG` | commit tag name (empty if event is not `tag`) | `v1.10.3` |
| `CI_COMMIT_PULL_REQUEST` | commit pull request number (set only for `pull_request` and `pull_request_closed` events) | `1` |
| `CI_COMMIT_PULL_REQUEST_LABELS` | labels assigned to pull request (set only for `pull_request` and `pull_request_closed` events) | `server` |
| `CI_COMMIT_MESSAGE` | commit message | `Initial commit` |
| `CI_COMMIT_AUTHOR` | commit author username | `john-doe` |
| `CI_COMMIT_AUTHOR_EMAIL` | commit author email address | `john-doe@example.com` |
| `CI_COMMIT_AUTHOR_AVATAR` | commit author avatar | `https://git.example.com/avatars/5dcbcadbce6f87f8abef` |
| `CI_COMMIT_PRERELEASE` | release is a pre-release (empty if event is not `release`) | `false` |
| | **Current pipeline** | |
| `CI_PIPELINE_NUMBER` | pipeline number | `8` |
| `CI_PIPELINE_PARENT` | number of parent pipeline | `0` |
| `CI_PIPELINE_EVENT` | pipeline event (see [`event`](../20-usage/20-workflow-syntax.md#event)) | `push`, `pull_request`, `pull_request_closed`, `tag`, `release`, `manual`, `cron` |
| `CI_PIPELINE_URL` | link to the web UI for the pipeline | `https://ci.example.com/repos/7/pipeline/8` |
| `CI_PIPELINE_FORGE_URL` | link to the forge's web UI for the commit(s) or tag that triggered the pipeline | `https://git.example.com/john-doe/my-repo/commit/eba09b46064473a1d345da7abf28b477468e8dbd` |
| `CI_PIPELINE_DEPLOY_TARGET` | pipeline deploy target for `deployment` events | `production` |
| `CI_PIPELINE_DEPLOY_TASK` | pipeline deploy task for `deployment` events | `migration` |
| `CI_PIPELINE_CREATED` | pipeline created UNIX timestamp | `1722617519` |
| `CI_PIPELINE_STARTED` | pipeline started UNIX timestamp | `1722617519` |
| `CI_PIPELINE_FILES` | changed files (empty if event is not `push` or `pull_request`), it is undefined if more than 500 files are touched | `[]`, `[".woodpecker.yml","README.md"]` |
| | **Current workflow** | |
| `CI_WORKFLOW_NAME` | workflow name | `release` |
| | **Current step** | |
| `CI_STEP_NAME` | step name | `build package` |
| `CI_STEP_NUMBER` | step number | `0` |
| `CI_STEP_STARTED` | step started UNIX timestamp | `1722617519` |
| `CI_STEP_URL` | URL to step in UI | `https://ci.example.com/repos/7/pipeline/8` |
| | **Previous commit** | |
| `CI_PREV_COMMIT_SHA` | previous commit SHA | `15784117e4e103f36cba75a9e29da48046eb82c4` |
| `CI_PREV_COMMIT_REF` | previous commit ref | `refs/heads/main` |
| `CI_PREV_COMMIT_REFSPEC` | previous commit ref spec | `issue-branch:main` |
| `CI_PREV_COMMIT_BRANCH` | previous commit branch | `main` |
| `CI_PREV_COMMIT_SOURCE_BRANCH` | previous commit source branch (set only for `pull_request` and `pull_request_closed` events) | `issue-branch` |
| `CI_PREV_COMMIT_TARGET_BRANCH` | previous commit target branch (set only for `pull_request` and `pull_request_closed` events) | `main` |
| `CI_PREV_COMMIT_URL` | previous commit link in forge | `https://git.example.com/john-doe/my-repo/commit/15784117e4e103f36cba75a9e29da48046eb82c4` |
| `CI_PREV_COMMIT_MESSAGE` | previous commit message | `test` |
| `CI_PREV_COMMIT_AUTHOR` | previous commit author username | `john-doe` |
| `CI_PREV_COMMIT_AUTHOR_EMAIL` | previous commit author email address | `john-doe@example.com` |
| `CI_PREV_COMMIT_AUTHOR_AVATAR` | previous commit author avatar | `https://git.example.com/avatars/12` |
| | **Previous pipeline** | |
| `CI_PREV_PIPELINE_NUMBER` | previous pipeline number | `7` |
| `CI_PREV_PIPELINE_PARENT` | previous pipeline number of parent pipeline | `0` |
| `CI_PREV_PIPELINE_EVENT` | previous pipeline event (see [`event`](../20-usage/20-workflow-syntax.md#event)) | `push`, `pull_request`, `pull_request_closed`, `tag`, `release`, `manual`, `cron` |
| `CI_PREV_PIPELINE_URL` | previous pipeline link in CI | `https://ci.example.com/repos/7/pipeline/7` |
| `CI_PREV_PIPELINE_FORGE_URL` | previous pipeline link to event in forge | `https://git.example.com/john-doe/my-repo/commit/15784117e4e103f36cba75a9e29da48046eb82c4` |
| `CI_PREV_PIPELINE_DEPLOY_TARGET` | previous pipeline deploy target for `deployment` events | `production` |
| `CI_PREV_PIPELINE_DEPLOY_TASK` | previous pipeline deploy task for `deployment` events | `migration` |
| `CI_PREV_PIPELINE_STATUS` | previous pipeline status | `success`, `failure` |
| `CI_PREV_PIPELINE_CREATED` | previous pipeline created UNIX timestamp | `1722610173` |
| `CI_PREV_PIPELINE_STARTED` | previous pipeline started UNIX timestamp | `1722610173` |
| `CI_PREV_PIPELINE_FINISHED` | previous pipeline finished UNIX timestamp | `1722610383` |
| | &emsp; | |
| `CI_WORKSPACE` | Path of the workspace where source code gets cloned to | `/woodpecker/src/git.example.com/john-doe/my-repo` |
| | **System** | |
| `CI_SYSTEM_NAME` | name of the CI system | `woodpecker` |
| `CI_SYSTEM_URL` | link to CI system | `https://ci.example.com` |
| `CI_SYSTEM_HOST` | hostname of CI server | `ci.example.com` |
| `CI_SYSTEM_VERSION` | version of the server | `2.7.0` |
| | **Forge** | |
| `CI_FORGE_TYPE` | name of forge | `bitbucket` , `bitbucket_dc` , `forgejo` , `gitea` , `github` , `gitlab` |
| `CI_FORGE_URL` | root URL of configured forge | `https://git.example.com` |
| | **Internal** - Please don't use! | |
| `CI_SCRIPT` | Internal script path. Used to call pipeline step commands. | |
| `CI_NETRC_USERNAME` | Credentials for private repos to be able to clone data. (Only available for specific images) | |
| `CI_NETRC_PASSWORD` | Credentials for private repos to be able to clone data. (Only available for specific images) | |
| `CI_NETRC_MACHINE` | Credentials for private repos to be able to clone data. (Only available for specific images) | |
## Global environment variables
@ -172,7 +169,7 @@ Example commit substitution:
```diff
steps:
- name: docker
image: plugins/docker
image: woodpeckerci/plugin-kaniko
settings:
+ tags: ${CI_COMMIT_SHA}
```
@ -182,7 +179,7 @@ Example tag substitution:
```diff
steps:
- name: docker
image: plugins/docker
image: woodpeckerci/plugin-kaniko
settings:
+ tags: ${CI_COMMIT_TAG}
```
@ -210,7 +207,7 @@ Example variable substitution with substring:
```diff
steps:
- name: docker
image: plugins/docker
image: woodpeckerci/plugin-kaniko
settings:
+ tags: ${CI_COMMIT_SHA:0:8}
```
@ -220,7 +217,7 @@ Example variable substitution strips `v` prefix from `v.1.0.0`:
```diff
steps:
- name: docker
image: plugins/docker
image: woodpeckerci/plugin-kaniko
settings:
+ tags: ${CI_COMMIT_TAG##v}
```

4
docs/versioned_docs/version-2.6/20-usage/51-plugins/20-creating-plugins.md → docs/versioned_docs/version-3.0/20-usage/51-plugins/20-creating-plugins.md
View File

@ -10,7 +10,7 @@ These are passed to your plugin as uppercase env vars with a `PLUGIN_` prefix.
Using a setting like `url` results in an env var named `PLUGIN_URL`.
Characters like `-` are converted to an underscore (`_`). `some_String` gets `PLUGIN_SOME_STRING`.
CamelCase is not respected, `anInt` get `PLUGIN_ANINT`.
CamelCase is not respected, `anInt` get `PLUGIN_ANINT`. <!-- cspell:ignore ANINT -->
### Basic settings
@ -42,7 +42,7 @@ Values like this are converted to JSON and then passed to your plugin. In the ex
### Secrets
Secrets should be passed as settings too. Therefore, users should use [`from_secret`](../40-secrets.md#use-secrets-in-settings-and-environment).
Secrets should be passed as settings too. Therefore, users should use [`from_secret`](../40-secrets.md#usage).
## Plugin library

70
docs/versioned_docs/version-3.0/20-usage/51-plugins/51-overview.md Normal file
View File

@ -0,0 +1,70 @@
# Plugins
Plugins are pipeline steps that perform pre-defined tasks and are configured as steps in your pipeline.
Plugins can be used to deploy code, publish artifacts, send notification, and more.
They are automatically pulled from the default container registry the agent's have configured.
```dockerfile title="Dockerfile"
FROM cloud/kubectl
COPY deploy /usr/local/deploy
ENTRYPOINT ["/usr/local/deploy"]
```
```bash title="deploy"
kubectl apply -f $PLUGIN_TEMPLATE
```
```yaml title=".woodpecker.yaml"
steps:
- name: deploy-to-k8s
image: cloud/my-k8s-plugin
settings:
template: config/k8s/service.yaml
```
Example pipeline using the Docker and Slack plugins:
```yaml
steps:
- name: build
image: golang
commands:
- go build
- go test
- name: publish
image: woodpeckerci/plugin-kaniko
settings:
repo: foo/bar
tags: latest
- name: notify
image: plugins/slack
settings:
channel: dev
```
## Plugin Isolation
Plugins are just pipeline steps. They share the build workspace, mounted as a volume, and therefore have access to your source tree.
While normal steps are all about arbitrary code execution, plugins should only allow the functions intended by the plugin author.
That's why there are a few limitations. The workspace base is always mounted at `/woodpecker`, but the working directory is dynamically
adjusted accordingly, as user of a plugin you should not have to care about this. Also, you cannot use the plugin together with `commands`
or `entrypoint` which will fail. Using `environment` is possible, but in this case, the plugin is internally not treated as plugin
anymore. The container then cannot access secrets with plugin filter anymore and the containers won't be privileged without explicit definition.
## Finding Plugins
For official plugins, you can use the Woodpecker plugin index:
- [Official Woodpecker Plugins](https://woodpecker-ci.org/plugins)
:::tip
There are also other plugin lists with additional plugins. Keep in mind that [Drone](https://www.drone.io/) plugins are generally supported, but could need some adjustments and tweaking.
- [Drone Plugins](http://plugins.drone.io)
- [Geeklab Woodpecker Plugins](https://woodpecker-plugins.geekdocs.de/)
:::

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

2
docs/versioned_docs/version-2.6/20-usage/60-services.md → docs/versioned_docs/version-3.0/20-usage/60-services.md
View File

@ -110,5 +110,5 @@ steps:
commands:
- ( apt update && apt dist-upgrade -y && apt install -y mysql-client 2>&1 )> /dev/null
- sleep 30s # need to wait for mysql-server init
- echo 'SHOW VARIABLES LIKE "version"' | mysql -uroot -hdatabase test -pexample
- echo 'SHOW VARIABLES LIKE "version"' | mysql -u root -h database test -p example
```

0
docs/versioned_docs/version-2.6/20-usage/70-volumes.md → docs/versioned_docs/version-3.0/20-usage/70-volumes.md
View File

0
docs/versioned_docs/version-2.6/20-usage/72-linter.md → docs/versioned_docs/version-3.0/20-usage/72-linter.md
View File

22
docs/versioned_docs/version-2.6/20-usage/75-project-settings.md → docs/versioned_docs/version-3.0/20-usage/75-project-settings.md
View File

@ -25,10 +25,9 @@ Only activate this option if you trust all users who have push access to your re
Otherwise, these users will be able to steal secrets that are only available for `deploy` events.
:::
## Protected
## Require approval for
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.
To prevent malicious pipelines from extracting secrets or running harmful commands or to prevent accidental pipeline runs, you can require approval for an additional review process. Depending on the enabled option, a pipeline will be put on hold after creation and will only continue after approval. The default restrictive setting is `Approvals for forked repositories`.
## Trusted
@ -40,15 +39,20 @@ Only server admins can set this option. If you are not a server admin this optio
:::
## Only inject Git credentials into trusted clone plugins
## Custom trusted clone plugins
The clone step may require Git credentials (e.g. for private repos) which are injected via `netrc`.
During the clone process, Git credentials (e.g., for private repositories) may be required.
These credentials are provided via [`netrc`](https://everything.curl.dev/usingcurl/netrc.html).
By default, they are only injected into trusted clone plugins listed in the env var `WOODPECKER_PLUGINS_TRUSTED_CLONE`.
If this option is disabled, the Git credentials are injected into every clone plugin, regardless of whether it is trusted or not.
These credentials are injected only into trusted plugins specified in the environment variable `WOODPECKER_PLUGINS_TRUSTED_CLONE` (an instance-wide Woodpecker server setting) or declared in this repository-level setting.
:::note
This option has no effect on steps other than the clone step.
With these credentials, it’s possible to perform any Git operations, including pushing changes back to the repo.
To prevent unauthorized access or misuse, a plugin allowlist is required, either on the instance level or the repository level.
Without an explicit allowlist, a malicious contributor could exploit a custom clone plugin in a Pull Request to reveal or transfer these credentials during the clone step.
:::info
This setting does not affect subsequent steps, nor does it allow direct pushes to the repository.
To enable pushing changes, you can inject Git credentials as a secret or use a dedicated plugin, such as [appleboy/drone-git-push](https://woodpecker-ci.org/plugins/Git%20Push).
:::
## Project visibility

0
docs/versioned_docs/version-2.6/20-usage/80-badges.md → docs/versioned_docs/version-3.0/20-usage/80-badges.md
View File

222
docs/versioned_docs/version-3.0/20-usage/90-advanced-usage.md Normal file
View File

@ -0,0 +1,222 @@
# Advanced usage
## Advanced YAML syntax
YAML has some advanced syntax features that can be used like variables to reduce duplication in your pipeline config:
### Anchors & aliases
You can use [YAML anchors & aliases](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) as variables in your pipeline config.
To convert this:
```yaml
steps:
- name: test
image: golang:1.18
commands: go test ./...
- name: build
image: golang:1.18
commands: build
```
Just add a new section called **variables** like this:
```diff
+variables:
+ - &golang_image 'golang:1.18'
steps:
- name: test
- image: golang:1.18
+ image: *golang_image
commands: go test ./...
- name: build
- image: golang:1.18
+ image: *golang_image
commands: build
```
### Map merges and overwrites
```yaml
variables:
- &base-plugin-settings
target: dist
recursive: false
try: true
- &special-setting
special: true
- &some-plugin codeberg.org/6543/docker-images/print_env
steps:
- name: develop
image: *some-plugin
settings:
<<: [*base-plugin-settings, *special-setting] # merge two maps into an empty map
when:
branch: develop
- name: main
image: *some-plugin
settings:
<<: *base-plugin-settings # merge one map and ...
try: false # ... overwrite original value
ongoing: false # ... adding a new value
when:
branch: main
```
### Sequence merges
```yaml
variables:
pre_cmds: &pre_cmds
- echo start
- whoami
post_cmds: &post_cmds
- echo stop
hello_cmd: &hello_cmd
- echo hello
steps:
- name: step1
image: debian
commands:
- <<: *pre_cmds # prepend a sequence
- echo exec step now do dedicated things
- <<: *post_cmds # append a sequence
- name: step2
image: debian
commands:
- <<: [*pre_cmds, *hello_cmd] # prepend two sequences
- echo echo from second step
- <<: *post_cmds
```
### References
- [Official YAML specification](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases)
- [YAML cheat sheet](https://learnxinyminutes.com/docs/yaml)
## Persisting environment data between steps
One can create a file containing environment variables, and then source it in each step that needs them.
```yaml
steps:
- name: init
image: bash
commands:
- echo "FOO=hello" >> envvars
- echo "BAR=world" >> envvars
- name: debug
image: bash
commands:
- source envvars
- echo $FOO
```
## Declaring global variables
As described in [Global environment variables](./50-environment.md#global-environment-variables), you can define global variables:
```ini
WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2
```
Note that this tightly couples the server and app configurations (where the app is a completely separate application). But this is a good option for truly global variables which should apply to all steps in all pipelines for all apps.
## Docker in docker (dind) setup
:::warning
This set up will only work on trusted repositories and for security reasons should only be used in private environments.
See [project settings](./75-project-settings.md#trusted) to enable "trusted" mode.
:::
The snippet below shows how a step can communicate with the docker daemon running in a `docker:dind` service.
:::note
If your goal is to build/publish OCI images, consider using the [Docker Buildx Plugin](https://woodpecker-ci.org/plugins/Docker%20Buildx) instead.
:::
First we need to define a service running a docker with the `dind` tag.
This service must run in `privileged` mode:
```yaml
services:
- name: docker
image: docker:dind # use 'docker:<major-version>-dind' or similar in production
privileged: true
ports:
- 2376
```
Next, we need to set up TLS communication between the `dind` service and the step that wants to communicate with the docker daemon (unauthenticated TCP connections have been deprecated [as of docker v27](https://github.com/docker/cli/blob/v27.4.0/docs/deprecated.md#unauthenticated-tcp-connections) and will result in an error in v28).
This can be achieved by letting the daemon generate TLS certificates and share them with the client through an agent volume mount (`/opt/woodpeckerci/dind-certs` in the example below).
```diff
services:
- name: docker
image: docker:dind # use 'docker:<major-version>-dind' or similar in production
privileged: true
+ environment:
+ DOCKER_TLS_CERTDIR: /dind-certs
+ volumes:
+ - /opt/woodpeckerci/dind-certs:/dind-certs
ports:
- 2376
```
In the docker client step:
1. Set the `DOCKER_*` environment variables shown below to configure the connection with the daemon.
These generic docker environment variables that are framework-agnostic (e.g. frameworks like [TestContainers](https://testcontainers.com/), [Spring Boot Docker Compose](https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-docker-compose) do all respect them).
2. Mount the volume to the location where the daemon has created the certificates (`/opt/woodpeckerci/dind-certs`)
Test the connection with the docker client:
```diff
steps:
- name: test
image: docker:cli # in production use something like 'docker:<major version>-cli'
+ environment:
+ DOCKER_HOST: "tcp://docker:2376"
+ DOCKER_CERT_PATH: "/dind-certs/client"
+ DOCKER_TLS_VERIFY: "1"
+ volumes:
+ - /opt/woodpeckerci/dind-certs:/dind-certs
commands:
- docker version
```
This step should output the server and client version information if everything has been set up correctly.
Full example:
```yaml
steps:
- name: test
image: docker:cli # use 'docker:<major-version>-cli' or similar in production
environment:
DOCKER_HOST: 'tcp://docker:2376'
DOCKER_CERT_PATH: '/dind-certs/client'
DOCKER_TLS_VERIFY: '1'
volumes:
- /opt/woodpeckerci/dind-certs:/dind-certs
commands:
- docker version
services:
- name: docker
image: docker:dind # use 'docker:<major-version>-dind' or similar in production
privileged: true
environment:
DOCKER_TLS_CERTDIR: /dind-certs
volumes:
- /opt/woodpeckerci/dind-certs:/dind-certs
ports:
- 2376
```

0
docs/versioned_docs/version-2.6/20-usage/_category_.yaml → docs/versioned_docs/version-3.0/20-usage/_category_.yaml
View File

0
docs/versioned_docs/version-2.6/20-usage/cron-settings.png → docs/versioned_docs/version-3.0/20-usage/cron-settings.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 40 KiB

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

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 113 KiB

After

Width:  |  Height:  |  Size: 113 KiB

BIN
docs/versioned_docs/version-3.0/20-usage/pipeline.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 430 KiB

BIN
docs/versioned_docs/version-3.0/20-usage/project-settings.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 353 KiB

BIN
docs/versioned_docs/version-3.0/20-usage/repo-new.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 351 KiB

BIN
docs/versioned_docs/version-3.0/20-usage/secrets-plugins-filter.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

59
docs/versioned_docs/version-3.0/30-administration/00-getting-started.md Normal file
View File

@ -0,0 +1,59 @@
# Getting started
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 [workflow](../20-usage/15-terminology/index.md) by default. If you have 4 agents installed and connected to the Woodpecker server, your system will process four workflows (not pipelines) in parallel.
:::tip
You can add more agents to increase the number of parallel workflows or set the agent's `WOODPECKER_MAX_WORKFLOWS=1` environment variable to increase the number of parallel workflows per agent.
:::
## Which version of Woodpecker should I use?
Woodpecker is having two different kinds of releases: **stable** and **next**.
Find more information about the different versions [here](/versions).
## Hardware Requirements
Below are minimal resources requirements for Woodpecker components itself:
| Component | Memory | CPU |
| --------- | ------ | --- |
| Server | 200 MB | 1 |
| Agent | 32 MB | 1 |
Note, that those values do not include the operating system or workload (pipelines execution) resource consumption.
In addition you need at least some kind of database which requires additional resources depending on the selected database system.
## Installation
You can install Woodpecker on multiple ways. If you are not sure which one to choose, we recommend using the [docker compose](./05-deployment-methods/10-docker-compose.md) method for the beginning:
- Using [docker compose](./05-deployment-methods/10-docker-compose.md) with the official [container images](./05-deployment-methods/10-docker-compose.md#docker-images)
- Using [Kubernetes](./05-deployment-methods/20-kubernetes.md) via the Woodpecker Helm chart
- Using binaries, DEBs or RPMs you can download from [latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest)
- Or using a [third-party installation method](./05-deployment-methods/30-third-party.md)
## Database
By default Woodpecker uses a SQLite database which requires zero installation or configuration. See the [database settings](./10-database.md) page if you want to use a different database system like MySQL or PostgreSQL.
## Forge
What would be a CI/CD system without any code? By connecting Woodpecker to your [forge](../20-usage/15-terminology/index.md) like GitHub or Gitea you can start running pipelines on events like pushes or pull requests. Woodpecker will also use your forge for authentication and to report back the status of your pipelines. See the [forge settings](./11-forges/11-overview.md) to connect it to Woodpecker.
## Configuration
Check the [server configuration](./10-server-config.md) and [agent configuration](./15-agent-config.md) pages to see if you need to adjust any additional parts and after that you should be ready to start with [your first pipeline](../20-usage/10-intro.md).
## Agent
The agent is the worker which executes the [workflows](../20-usage/15-terminology/index.md).
Woodpecker agents can execute work using a [backend](../20-usage/15-terminology/index.md) like [docker](./22-backends/10-docker.md) or [kubernetes](./22-backends/40-kubernetes.md).
By default if you choose to deploy an agent using [docker compose](./05-deployment-methods/10-docker-compose.md) the agent simply use docker for the backend as well.
So nothing to worry about here. If you still prefer to adjust the agent to your needs, check the [agent configuration](./15-agent-config.md) page.

30
docs/versioned_docs/version-3.0/30-administration/04-image-variants.md Normal file
View File

@ -0,0 +1,30 @@
# Image variants
:::info
The `latest` tag has been deprecated as of v3.0 and will be completely removed in the future.
This was done to prevent accidental major version upgrades.
:::
- `vX.Y.Z`: SemVer tags for specific releases, no entrypoint shell (scratch image)
- `vX.Y`
- `vX`
- `vX.Y.Z-alpine`: SemVer tags for specific releases, based on Alpine, rootless for Server and CLI (as of v3.0).
- `vX.Y-alpine`
- `vX-alpine`
- `next`: Built from the `main` branch
- `pull_<PR_ID>`: Images built from Pull Request branches.
## Image registries
Images are pushed to DockerHub and Quay.
[woodpecker-server (DockerHub)](https://hub.docker.com/repository/docker/woodpeckerci/woodpecker-server)
[woodpecker-server (Quay)](https://quay.io/repository/woodpeckerci/woodpecker-server)
[woodpecker-agent (DockerHub)](https://hub.docker.com/repository/docker/woodpeckerci/woodpecker-agent)
[woodpecker-agent (Quay)](https://quay.io/repository/woodpeckerci/woodpecker-agent)
[woodpecker-cli (DockerHub)](https://hub.docker.com/repository/docker/woodpeckerci/woodpecker-cli)
[woodpecker-cli (Quay)](https://quay.io/repository/woodpeckerci/woodpecker-cli)
[woodpecker-autoscaler (DockerHub)](https://hub.docker.com/repository/docker/woodpeckerci/autoscaler)

43
docs/versioned_docs/version-2.6/30-administration/00-deployment/10-docker-compose.md → docs/versioned_docs/version-3.0/30-administration/05-deployment-methods/10-docker-compose.md
View File

@ -1,12 +1,10 @@
# docker-compose
# docker compose
The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start a Woodpecker server with a single agent.
The below [docker compose](https://docs.docker.com/compose/) configuration can be used to start a Woodpecker server with a single agent.
It relies on a number of environment variables that you must set before running `docker-compose up`. The variables are described below.
It relies on a number of environment variables that you must set before running `docker compose up`. The variables are described below.
```yaml title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
@ -43,8 +41,6 @@ volumes:
Woodpecker needs to know its own address. You must therefore provide the public address of it in `<scheme>://<hostname>` format. Please omit trailing slashes:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
@ -53,11 +49,10 @@ Woodpecker needs to know its own address. You must therefore provide the public
+ - 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 ports configured. It uses a separate port for gRPC and for HTTP. The agent performs gRPC calls and connects to the gRPC port.
They can be configured with `*_ADDR` variables:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
@ -67,10 +62,9 @@ They can be configured with `*_ADDR` variables:
+ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR}
```
Reverse proxying can also be [configured for gRPC](../70-proxy.md#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](../40-advanced/10-proxy.md#caddy). If the agents are connecting over the internet, it should also be SSL encrypted. The agent then needs to be configured to be secure:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
@ -83,8 +77,6 @@ Reverse proxying can also be [configured for gRPC](../70-proxy.md#caddy). If the
As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon:
```diff title="docker-compose.yaml"
version: '3'
services:
[...]
woodpecker-agent:
@ -96,8 +88,6 @@ As agents run pipeline steps as docker containers they require access to the hos
Agents require the server address for agent-to-server communication. The agent connects to the server's gRPC port:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-agent:
[...]
@ -108,8 +98,6 @@ Agents require the server address for agent-to-server communication. The agent c
The server and agents use a shared secret to authenticate communication. This should be a random string of your choosing and should be kept private. You can generate such string with `openssl rand -hex 32`:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
@ -127,21 +115,26 @@ The server and agents use a shared secret to authenticate communication. This sh
Image variants:
- The `latest` image is the latest stable release
- The `vX.X.X` images are stable releases
- The `vX.X` images are based on the current release branch (e.g. `release/v1.0`) and can be used to get bugfixes asap
- The `vX.X` images are based on the current release branch (e.g. `release/v1.0`) and can be used to get bug fixes asap
- The `vX` same as `vX.X` variant but also includes feature releases
- The `next` images are based on the current `main` branch
:::note
The `latest` tag is not available on purpose (and has been dropped with the 3.x release) to prevent accidental major version upgrades.
Hence, users are forced to specify a fixed or rolling tag, omitting the tag identifier (which equals to pulling `latest` implicitly) won't work.
:::
```bash
# server
docker pull woodpeckerci/woodpecker-server:latest
docker pull woodpeckerci/woodpecker-server:latest-alpine
docker pull woodpeckerci/woodpecker-server:v3
docker pull woodpeckerci/woodpecker-server:v3-alpine
# agent
docker pull woodpeckerci/woodpecker-agent:latest
docker pull woodpeckerci/woodpecker-agent:latest-alpine
docker pull woodpeckerci/woodpecker-agent:v3
docker pull woodpeckerci/woodpecker-agent:v3-alpine
# cli
docker pull woodpeckerci/woodpecker-cli:latest
docker pull woodpeckerci/woodpecker-cli:latest-alpine
docker pull woodpeckerci/woodpecker-cli:v3
docker pull woodpeckerci/woodpecker-cli:v3-alpine
```

50
docs/versioned_docs/version-3.0/30-administration/05-deployment-methods/20-kubernetes.md Normal file
View File

@ -0,0 +1,50 @@
# Kubernetes
We recommended to deploy Woodpecker using the [Woodpecker helm chart](https://github.com/woodpecker-ci/helm).
Have a look at the [`values.yaml`](https://github.com/woodpecker-ci/helm/blob/main/charts/woodpecker/values.yaml) config files for all available settings.
The chart contains two sub-charts, `server` and `agent` which are automatically configured as needed.
The chart started off with two independent charts but was merged into one to simplify the deployment at start of 2023.
A couple of backend-specific config env vars exists which are described in the [kubernetes backend docs](../22-backends/40-kubernetes.md).
## Metrics
Please see [Prometheus](../40-advanced/90-prometheus.md) for general information on configuration and usage.
For Kubernetes, you must set the following values when deploying via Helm chart to enable in-cluster metrics gathering:
```yaml
metrics:
enabled: true
port: 9001
```
This activates the `/metrics` endpoint on port `9001` without authentication. This port is not exposed externally by default. Use the instructions at [Prometheus](../40-advanced/90-prometheus.md) if you want to enable authenticated external access to metrics.
To enable Prometheus pod monitoring discovery, you must also make the following settings:
<!-- cspell:disable -->
```yaml
prometheus:
podmonitor:
enabled: true
interval: 60s
labels: {}
```
<!-- cspell:enable -->
### Troubleshooting Metrics
If you are not receiving metrics despite the steps above, ensure that in your Prometheus configuration either your namespace is explicitly configured in `podMonitorNamespaceSelector` or the selectors are disabled.
```yaml
# Search all available namespaces
podMonitorNamespaceSelector:
matchLabels: {}
# Enable all available pod monitors
podMonitorSelector:
matchLabels: {}
```

12
docs/versioned_docs/version-3.0/30-administration/05-deployment-methods/30-third-party.md Normal file
View File

@ -0,0 +1,12 @@
# Distribution packages
:::info
Woodpecker itself is not responsible for creating these packages. Please reach out to the people responsible for packaging Woodpecker for the individual distributions.
:::
- [NixOS](./40-nixos.md) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker)
- [Alpine (Edge)](https://pkgs.alpinelinux.org/packages?name=woodpecker&branch=edge&repo=&arch=&maintainer=)
- [Arch Linux](https://archlinux.org/packages/?q=woodpecker)
- [openSUSE](https://software.opensuse.org/package/woodpecker)
- [YunoHost](https://apps.yunohost.org/app/woodpecker)
- [Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html)

4
docs/versioned_docs/version-2.6/30-administration/00-deployment/30-nixos.md → docs/versioned_docs/version-3.0/30-administration/05-deployment-methods/40-nixos.md
View File

@ -10,6 +10,8 @@ In practice, the settings are specified declaratively in the NixOS configuration
## General Configuration
<!-- cspell:words Optimisation -->
```nix
{ config
, ...
@ -85,4 +87,4 @@ All configuration options can be found via [NixOS Search](https://search.nixos.o
## Tips and tricks
There are some resources on how to utilize Woodpecker more effectively with NixOS on the [Awesome Woodpecker](../../92-awesome.md) page, like using the runners nix-store in the pipeline.
There are some resources on how to utilize Woodpecker more effectively with NixOS on the [Awesome Woodpecker](/awesome) page, like using the runners nix-store in the pipeline.

3
docs/versioned_docs/version-3.0/30-administration/05-deployment-methods/_category_.yaml Normal file
View File

@ -0,0 +1,3 @@
label: 'Deployment methods'
collapsible: true
collapsed: true

2
docs/versioned_docs/version-2.6/30-administration/30-database.md → docs/versioned_docs/version-3.0/30-administration/10-database.md
View File

@ -7,8 +7,6 @@ The default database engine of Woodpecker is an embedded SQLite database which r
By default Woodpecker uses a SQLite database stored under `/var/lib/woodpecker/`. If using containers, you can mount a [data volume](https://docs.docker.com/storage/volumes/#create-and-manage-volumes) to persist the SQLite database.
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]

149
docs/versioned_docs/version-2.6/30-administration/10-server-config.md → docs/versioned_docs/version-3.0/30-administration/10-server-config.md
View File

@ -26,14 +26,14 @@ You can **also restrict** registration, by keep registration closed and:
```ini
WOODPECKER_OPEN=false
WOODPECKER_ADMIN=johnsmith,janedoe
WOODPECKER_ADMIN=john.smith,jane_doe
```
### Only allow registration of users, who are members of approved organizations
```ini
WOODPECKER_OPEN=true
WOODPECKER_ORGS=dolores,dogpatch
WOODPECKER_ORGS=dolores,dog-patch
```
## Administrators
@ -41,7 +41,7 @@ WOODPECKER_ORGS=dolores,dogpatch
Administrators should also be enumerated in your configuration.
```ini
WOODPECKER_ADMIN=johnsmith,janedoe
WOODPECKER_ADMIN=john.smith,jane_doe
```
## Filtering repositories
@ -51,7 +51,21 @@ Woodpecker operates with the user's OAuth permission. Due to the coarse permissi
Use the `WOODPECKER_REPO_OWNERS` variable to filter which GitHub user's repos should be synced only. You typically want to put here your company's GitHub name.
```ini
WOODPECKER_REPO_OWNERS=mycompany,mycompanyossgithubuser
WOODPECKER_REPO_OWNERS=my_company,my_company_oss_github_user
```
## Disallow normal users to create agents
By default, users can create new agents for their repos they have admin access to.
If an instance admin doesn't want this feature enabled, they can disable the API and hide the Web UI elements.
:::note
You should set this option if you have, for example,
global secrets and don't trust your users to create a rogue agent and pipeline for secret extraction.
:::
```ini
WOODPECKER_DISABLE_USER_AGENT_REGISTRATION=true
```
## Global registry setting
@ -63,17 +77,15 @@ Point it to your server's docker config.
WOODPECKER_DOCKER_CONFIG=/root/.docker/config.json
```
## Handling sensitive data in docker-compose and docker-swarm
## Handling sensitive data in **docker compose** and **docker swarm**
To handle sensitive data in docker-compose or docker-swarm configurations there are several options:
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.
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
@ -133,7 +145,7 @@ The examples below show how to place a banner message in the top navigation bar
### `woodpecker.js`
```javascript
// place/copy a minified version of jQuery or ZeptoJS here ...
// place/copy a minified version of your preferred lightweight JavaScript library here ...
!(function () {
'use strict';
function e() {} /*...*/
@ -161,17 +173,35 @@ Configures the logging level. Possible values are `trace`, `debug`, `info`, `war
Output destination for logs.
'stdout' and 'stderr' can be used as special keywords.
### `WOODPECKER_LOG_XORM`
### `WOODPECKER_DATABASE_LOG`
> Default: `false`
Enable XORM logs.
Enable logging in database engine (currently xorm).
### `WOODPECKER_LOG_XORM_SQL`
### `WOODPECKER_DATABASE_LOG_SQL`
> Default: `false`
Enable XORM SQL command logs.
Enable logging of sql commands.
### `WOODPECKER_DATABASE_MAX_CONNECTIONS`
> Default: `100`
Max database connections xorm is allowed create.
### `WOODPECKER_DATABASE_IDLE_CONNECTIONS`
> Default: `2`
Amount of database connections xorm will hold open.
### `WOODPECKER_DATABASE_CONNECTION_TIMEOUT`
> Default: `3 Seconds`
Time an active database connection is allowed to stay open.
### `WOODPECKER_DEBUG_PRETTY`
@ -197,14 +227,6 @@ Examples:
- `WOODPECKER_HOST=http://example.org/woodpecker`
- `WOODPECKER_HOST=http://example.org:1234/woodpecker`
### `WOODPECKER_WEBHOOK_HOST`
> Default: value from `WOODPECKER_HOST` config env
Server fully qualified URL of the Webhook-facing hostname and path prefix.
Example: `WOODPECKER_WEBHOOK_HOST=http://woodpecker-server.cicd.svc.cluster.local:8000`
### `WOODPECKER_SERVER_ADDR`
> Default: `:8000`
@ -253,12 +275,6 @@ 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`
@ -305,7 +321,7 @@ Example: `org1,org2`
> Default: empty
Comma-separated list of syncable repo owners. ???
Repositories by those owners will be allowed to be used in woodpecker.
Example: `user1,user2`
@ -327,11 +343,21 @@ Always use authentication to clone repositories even if they are public. Needed
List of event names that will be canceled when a new pipeline for the same context (tag, branch) is created.
### `WOODPECKER_DEFAULT_CLONE_IMAGE`
### `WOODPECKER_DEFAULT_CLONE_PLUGIN`
> Default is defined in [shared/constant/constant.go](https://github.com/woodpecker-ci/woodpecker/blob/main/shared/constant/constant.go)
The default docker image to be used when cloning the repo
The default docker image to be used when cloning the repo.
It is also added to the trusted clone plugin list.
### `WOODPECKER_DEFAULT_WORKFLOW_LABELS`
> By default run workflows on any agent if no label conditions are set in workflow definition.
You can specify default label/platform conditions that will be used for agent selection for workflows that does not have labels conditions set.
Example: `platform=linux/amd64,backend=docker`
### `WOODPECKER_DEFAULT_PIPELINE_TIMEOUT`
@ -354,11 +380,20 @@ Context: when someone does log into Woodpecker, a temporary session token is cre
As long as the session is valid (until it expires or log-out),
a user can log into Woodpecker, without re-authentication.
### `WOODPECKER_ESCALATE`
### `WOODPECKER_PLUGINS_PRIVILEGED`
Docker images to run in privileged mode. Only change if you are sure what you do!
You should specify the tag of your images too, as this enforces exact matches.
### WOODPECKER_PLUGINS_TRUSTED_CLONE
> 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!
Plugins which are trusted to handle the Git credential info in clone steps.
If a clone step use an image not in this list, Git credentials will not be injected and users have to use other methods (e.g. secrets) to clone non-public repos.
You should specify the tag of your images too, as this enforces exact matches.
<!--
### `WOODPECKER_VOLUME`
@ -403,6 +438,12 @@ A shared secret used by server and agents to authenticate communication. A secre
Read the value for `WOODPECKER_AGENT_SECRET` from the specified filepath
### `WOODPECKER_DISABLE_USER_AGENT_REGISTRATION`
> Default: false
[Read about "Disallow normal users to create agents"](./10-server-config.md#disallow-normal-users-to-create-agents)
### `WOODPECKER_KEEPALIVE_MIN_TIME`
> Default: empty
@ -475,53 +516,15 @@ 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: empty
Specify a configuration service endpoint, see [Configuration Extension](./100-external-configuration-api.md)
Specify a configuration service endpoint, see [Configuration Extension](./40-advanced/100-external-configuration-api.md)
### `WOODPECKER_FORGE_TIMEOUT`
> Default: 3s
> Default: 5s
Specify timeout when fetching the Woodpecker configuration from forge. See <https://pkg.go.dev/time#ParseDuration> for syntax reference.

12
docs/versioned_docs/version-2.6/30-administration/11-forges/100-addon.md → docs/versioned_docs/version-3.0/30-administration/11-forges/100-addon.md
View File

@ -38,9 +38,9 @@ Addons use RPC to communicate to the server and are implemented using the [`go-p
This example will use the Go language.
Directly import Woodpecker's Go packages (`go.woodpecker-ci.org/woodpecker/woodpecker/v2`) and use the interfaces and types defined there.
Directly import Woodpecker's Go packages (`go.woodpecker-ci.org/woodpecker/v3`) and use the interfaces and types defined there.
In the `main` function, just call `"go.woodpecker-ci.org/woodpecker/v2/server/forge/addon".Serve` with a `"go.woodpecker-ci.org/woodpecker/v2/server/forge".Forge` as argument.
In the `main` function, just call `"go.woodpecker-ci.org/woodpecker/v3/server/forge/addon".Serve` with a `"go.woodpecker-ci.org/woodpecker/v3/server/forge".Forge` as argument.
This will take care of connecting the addon forge to the server.
### Example structure
@ -52,9 +52,9 @@ import (
"context"
"net/http"
"go.woodpecker-ci.org/woodpecker/v2/server/forge/addon"
forgeTypes "go.woodpecker-ci.org/woodpecker/v2/server/forge/types"
"go.woodpecker-ci.org/woodpecker/v2/server/model"
"go.woodpecker-ci.org/woodpecker/v3/server/forge/addon"
forgeTypes "go.woodpecker-ci.org/woodpecker/v3/server/forge/types"
"go.woodpecker-ci.org/woodpecker/v3/server/model"
)
func main() {
@ -64,5 +64,5 @@ func main() {
type config struct {
}
// `config` must implement `"go.woodpecker-ci.org/woodpecker/v2/server/forge".Forge`. You must directly use Woodpecker's packages - see imports above.
// `config` must implement `"go.woodpecker-ci.org/woodpecker/v3/server/forge".Forge`. You must directly use Woodpecker's packages - see imports above.
```

4
docs/versioned_docs/version-2.6/30-administration/11-forges/11-overview.md → docs/versioned_docs/version-3.0/30-administration/11-forges/11-overview.md
View File

@ -8,6 +8,8 @@
| Event: Tag | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Event: Pull-Request | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Event: Release | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: |
| Event: Deploy | :white_check_mark: | :x: | :x: | :x: | :x: | :x: |
| Event: Deploy¹ | :white_check_mark: | :x: | :x: | :x: | :x: | :x: |
| [Multiple workflows](../../20-usage/25-workflows.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [when.path filter](../../20-usage/20-workflow-syntax.md#path) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: |
¹ The deployment event can be triggered for all forges from Woodpecker directly. However, only GitHub can trigger them using webhooks.

0
docs/versioned_docs/version-2.6/30-administration/11-forges/20-github.md → docs/versioned_docs/version-3.0/30-administration/11-forges/20-github.md
View File

14
docs/versioned_docs/version-2.6/30-administration/11-forges/30-gitea.md → docs/versioned_docs/version-3.0/30-administration/11-forges/30-gitea.md
View File

@ -22,8 +22,6 @@ Otherwise, the communication should go via the `docker0` gateway (usually 172.17
To configure the Docker network if the network's name is `gitea`, configure it like this:
```diff title="docker-compose.yaml"
version: '3'
services:
[...]
woodpecker-agent:
@ -48,6 +46,10 @@ For reference see [Configuration Cheat Sheet](https://docs.gitea.io/en-us/config
![gitea oauth setup](gitea_oauth.gif)
:::warning
Make sure your Gitea configuration allows requesting the API with a fixed page length of 50. The default value for the maximum page size is 50, but if you set a value lower than 50, some Woodpecker features will not work properly. Also see the [Configuration Cheat Sheet](https://docs.gitea.com/administration/config-cheat-sheet#api-api).
:::
## 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.
@ -93,11 +95,3 @@ Read the value for `WOODPECKER_GITEA_SECRET` from the specified filepath
> Default: `false`
Configure if SSL verification should be skipped.
## Advanced options
### `WOODPECKER_DEV_GITEA_OAUTH_URL`
> Default: value of `WOODPECKER_GITEA_URL`
Configures the user-facing Gitea server address. Should be used if `WOODPECKER_GITEA_URL` points to an internal URL used for API requests.

8
docs/versioned_docs/version-2.6/30-administration/11-forges/35-forgejo.md → docs/versioned_docs/version-3.0/30-administration/11-forges/35-forgejo.md
View File

@ -4,10 +4,6 @@ toc_max_heading_level: 2
# Forgejo
:::warning
Forgejo support is experimental.
:::
Woodpecker comes with built-in support for Forgejo. To enable Forgejo you should configure the Woodpecker container using the following environment variables:
```ini
@ -50,6 +46,10 @@ For reference see [Configuration Cheat Sheet](https://forgejo.org/docs/latest/ad
![forgejo oauth setup](gitea_oauth.gif)
:::warning
Make sure your Forgejo configuration allows requesting the API with a fixed page length of 50. The default value for the maximum page size is 50, but if you set a value lower than 50, some Woodpecker features will not work properly. Also see the [Configuration Cheat Sheet](https://forgejo.org/docs/latest/admin/config-cheat-sheet/#api-api).
:::
## 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.

2
docs/versioned_docs/version-2.6/30-administration/11-forges/40-gitlab.md → docs/versioned_docs/version-3.0/30-administration/11-forges/40-gitlab.md
View File

@ -4,7 +4,7 @@ toc_max_heading_level: 2
# GitLab
Woodpecker comes with built-in support for the GitLab version 8.2 and higher. To enable GitLab you should configure the Woodpecker container using the following environment variables:
Woodpecker comes with built-in support for the GitLab version 12.4 and higher. To enable GitLab you should configure the Woodpecker container using the following environment variables:
```ini
WOODPECKER_GITLAB=true

0
docs/versioned_docs/version-2.6/30-administration/11-forges/50-bitbucket.md → docs/versioned_docs/version-3.0/30-administration/11-forges/50-bitbucket.md
View File

7
docs/versioned_docs/version-2.6/30-administration/11-forges/60-bitbucket_datacenter.md → docs/versioned_docs/version-3.0/30-administration/11-forges/60-bitbucket_datacenter.md
View File

@ -11,8 +11,6 @@ Woodpecker comes with experimental support for Bitbucket Datacenter / Server, fo
To enable Bitbucket Server you should configure the Woodpecker container using the following environment variables:
```diff title="docker-compose.yaml"
version: '3'
services:
woodpecker-server:
[...]
@ -35,7 +33,10 @@ Woodpecker uses `git+https` to clone repositories, however, Bitbucket Server doe
## Registration
Woodpecker must be registered with Bitbucket Datacenter / Server. In the administration section of Bitbucket choose "Application Links" and then "Create link". Woodpecker should be listed as "External Application" and the direction should be set to "Incomming". Note the client id and client secret of the registration to be used in the configuration of Woodpecker.
Woodpecker must be registered with Bitbucket Datacenter / Server.
In the administration section of Bitbucket choose "Application Links" and then "Create link".
Woodpecker should be listed as "External Application" and the direction should be set to "Incoming".
Note the client id and client secret of the registration to be used in the configuration of Woodpecker.
See also [Configure an incoming link](https://confluence.atlassian.com/bitbucketserver/configure-an-incoming-link-1108483657.html).

0
docs/versioned_docs/version-2.6/30-administration/11-forges/_category_.yaml → docs/versioned_docs/version-3.0/30-administration/11-forges/_category_.yaml
View File

0
docs/versioned_docs/version-2.6/30-administration/11-forges/bitbucket_oauth.png → docs/versioned_docs/version-3.0/30-administration/11-forges/bitbucket_oauth.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 29 KiB

After

Width:  |  Height:  |  Size: 29 KiB

0
docs/versioned_docs/version-2.6/30-administration/11-forges/bitbucket_permissions.png → docs/versioned_docs/version-3.0/30-administration/11-forges/bitbucket_permissions.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 20 KiB

0
docs/versioned_docs/version-2.6/30-administration/11-forges/gitea_oauth.gif → docs/versioned_docs/version-3.0/30-administration/11-forges/gitea_oauth.gif
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 129 KiB

After

Width:  |  Height:  |  Size: 129 KiB

0
docs/versioned_docs/version-2.6/30-administration/11-forges/github_oauth.png → docs/versioned_docs/version-3.0/30-administration/11-forges/github_oauth.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 25 KiB

After

Width:  |  Height:  |  Size: 25 KiB

7
docs/versioned_docs/version-2.6/30-administration/15-agent-config.md → docs/versioned_docs/version-3.0/30-administration/15-agent-config.md
View File

@ -120,11 +120,14 @@ Configures the path of the agent config file.
Configures the number of parallel workflows.
### `WOODPECKER_FILTER_LABELS`
### `WOODPECKER_AGENT_LABELS`
> Default: empty
Configures labels to filter pipeline pick up. Use a list of key-value pairs like `key=value,second-key=*`. `*` can be used as a wildcard. By default, agents provide three additional labels `platform=os/arch`, `hostname=my-agent` and `repo=*` which can be overwritten if needed. To learn how labels work, check out the [pipeline syntax page](../20-usage/20-workflow-syntax.md#labels).
Configures custom labels for the agent, to let workflows filter by it.
Use a list of key-value pairs like `key=value,second-key=*`. `*` can be used as a wildcard.
By default, agents provide three additional labels `platform=os/arch`, `hostname=my-agent` and `repo=*` which can be overwritten if needed.
To learn how labels work, check out the [pipeline syntax page](../20-usage/20-workflow-syntax.md#labels).
### `WOODPECKER_HEALTHCHECK`

65
docs/versioned_docs/version-2.6/30-administration/22-backends/10-docker.md → docs/versioned_docs/version-3.0/30-administration/22-backends/10-docker.md
View File

@ -18,9 +18,24 @@ FROM woodpeckerci/woodpecker-server:latest-alpine
RUN apk add -U --no-cache docker-credential-ecr-login
```
## Podman support
## Step specific configuration
While the agent was developed with Docker/Moby, Podman can also be used by setting the environment variable `DOCKER_HOST` to point to the Podman socket. In order to work without workarounds, Podman 4.0 (or above) is required.
### Run user
By default the docker backend starts the step container without the `--user` flag. This means the step container will use the default user of the container. To change this behavior you can set the `user` backend option to the preferred user/group:
```yaml
steps:
- name: example
image: alpine
commands:
- whoami
backend_options:
docker:
user: 65534:65534
```
The syntax is the same as the [docker run](https://docs.docker.com/engine/reference/run/#user) `--user` flag.
## Image cleanup
@ -32,6 +47,8 @@ The following commands **are destructive** and **irreversible** it is highly rec
### Remove all unused images
<!-- cspell:ignore trunc -->
```bash
docker image rm $(docker images --filter "dangling=true" -q --no-trunc)
```
@ -42,6 +59,12 @@ docker image rm $(docker images --filter "dangling=true" -q --no-trunc)
docker volume rm $(docker volume ls --filter name=^wp_* --filter dangling=true -q)
```
## Tips and tricks
### Podman
There is no official support for Podman, but one can try to set the environment variable `DOCKER_HOST` to point to the Podman socket. It might work. See also the [Blog posts](https://woodpecker-ci.org/blog).
## Configuration
### `WOODPECKER_BACKEND_DOCKER_NETWORK`
@ -62,3 +85,41 @@ Enable IPv6 for the networks used by pipeline containers (steps). Make sure you
List of default volumes separated by comma to be mounted to all pipeline containers (steps). For example to use custom CA
certificates installed on host and host timezone use `/etc/ssl/certs:/etc/ssl/certs:ro,/etc/timezone:/etc/timezone`.
### `WOODPECKER_BACKEND_DOCKER_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_BACKEND_DOCKER_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_BACKEND_DOCKER_LIMIT_SHM_SIZE`
> Default: `0`
The maximum amount of memory of `/dev/shm` allowed in bytes. There is no limit if `0`.
### `WOODPECKER_BACKEND_DOCKER_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_BACKEND_DOCKER_LIMIT_CPU_SHARES`
> Default: `0`
The relative weight vs. other containers.
### `WOODPECKER_BACKEND_DOCKER_LIMIT_CPU_SET`
> Default: empty
Comma-separated list to limit the specific CPUs or cores a pipeline container can use.
Example: `WOODPECKER_BACKEND_DOCKER_LIMIT_CPU_SET=1,2`

0
docs/versioned_docs/version-2.6/30-administration/22-backends/20-local.md → docs/versioned_docs/version-3.0/30-administration/22-backends/20-local.md
View File

67
docs/versioned_docs/version-2.6/30-administration/22-backends/40-kubernetes.md → docs/versioned_docs/version-3.0/30-administration/22-backends/40-kubernetes.md
View File

@ -8,11 +8,11 @@ The Kubernetes backend executes steps inside standalone Pods. A temporary PVC is
## Images from private registries
In order to pull private container images defined in your pipeline YAML you must provide [registry credentials in Kubernetes Secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).
As the Secret is Agent-wide, it has to be placed in namespace defined by `WOODPECKER_BACKEND_K8S_NAMESPACE`.
Besides, you need to provide the Secret name to Agent via `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES`.
In addition to [registries specified in the UI](../../20-usage/41-registries.md), you may provide [registry credentials in Kubernetes Secrets](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) to pull private container images defined in your pipeline YAML.
## Job specific configuration
Place these Secrets in namespace defined by `WOODPECKER_BACKEND_K8S_NAMESPACE` and provide the Secret names to Agents via `WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES`.
## Step specific configuration
### Resources
@ -50,9 +50,24 @@ See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/container
`serviceAccountName` specifies the name of the ServiceAccount which the Pod will mount. This service account must be created externally.
See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/security/service-accounts/) for more information on using service accounts.
```yaml
steps:
- name: 'My kubernetes step'
image: alpine
commands:
- echo "Hello world"
backend_options:
kubernetes:
# Use the service account `default` in the current namespace.
# This usually the same as wherever woodpecker is deployed.
serviceAccountName: default
```
To give steps access to the Kubernetes API via service account, take a look at [RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
### Node selector
`nodeSelector` specifies the labels which are used to select the node on which the job will be executed.
`nodeSelector` specifies the labels which are used to select the node on which the step will be executed.
Labels defined here will be appended to a list which already contains `"kubernetes.io/arch"`.
By default `"kubernetes.io/arch"` is inferred from the agents' platform. One can override it by setting that label in the `nodeSelector` section of the `backend_options`.
@ -107,7 +122,7 @@ steps:
limits:
memory: 256Mi
nodeSelector:
beta.kubernetes.io/instance-type: p3.8xlarge
beta.kubernetes.io/instance-type: Standard_D2_v3
tolerations:
- key: 'key1'
operator: 'Equal'
@ -119,7 +134,19 @@ steps:
### Volumes
To mount volumes a PersistentVolume (PV) and PersistentVolumeClaim (PVC) are needed on the cluster which can be referenced in steps via the `volumes` option.
Assuming a PVC named `woodpecker-cache` exists, it can be referenced as follows in a step:
Persistent volumes must be created manually. Use the Kubernetes [Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) documentation as a reference.
_If your PVC is not highly available or NFS-based, you may also need to integrate affinity settings to ensure that your steps are executed on the correct node._
NOTE: If you plan to use this volume in more than one workflow concurrently, make sure you have configured the PVC in `RWX` mode. Keep in mind that this feature must be supported by the used CSI driver:
```yaml
accessModes:
- ReadWriteMany
```
Assuming a PVC named `woodpecker-cache` exists, it can be referenced as follows in a plugin step:
```yaml
steps:
@ -133,6 +160,19 @@ steps:
[...]
```
Or as follows when using a normal image:
```yaml
steps:
- name: "Edit cache"
image: alpine:latest
volumes:
- woodpecker-cache:/woodpecker/src/cache
commands:
- echo "Hello World" > /woodpecker/src/cache/output.txt
[...]
```
### Security context
Use the following configuration to set the [Security Context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for the Pod/container running a given pipeline step:
@ -156,6 +196,8 @@ Note that the `backend_options.kubernetes.securityContext` object allows you to
By default, the properties will be set at the Pod level. Properties that are only supported on the container level will be set there instead. So, the
configuration shown above will result in something like the following Pod spec:
<!-- cspell:disable -->
```yaml
kind: Pod
spec:
@ -170,7 +212,9 @@ spec:
[...]
```
You can also restrict a container's syscalls with [seccomp](https://kubernetes.io/docs/tutorials/security/seccomp/) profile
<!-- cspell:enable -->
You can also restrict a syscalls of containers with [seccomp](https://kubernetes.io/docs/tutorials/security/seccomp/) profile.
```yaml
backend_options:
@ -193,7 +237,7 @@ backend_options:
```
:::note
AppArmor syntax follows [KEP-24](https://github.com/kubernetes/enhancements/blob/fddcbb9cbf3df39ded03bad71228265ac6e5215f/keps/sig-node/24-apparmor/README.md).
The feature requires Kubernetes v1.30 or above.
:::
### Annotations and labels
@ -230,7 +274,8 @@ See [this issue](https://github.com/woodpecker-ci/woodpecker/issues/2510) for mo
### `KUBERNETES_SERVICE_HOST` environment variable
Like the below env vars used for configuration, this can be set in the environment fonfiguration of the agent. It configures the address of the Kubernetes API server to connect to.
Like the below env vars used for configuration, this can be set in the environment for configuration of the agent.
It configures the address of the Kubernetes API server to connect to.
If running the agent within Kubernetes, this will already be set and you don't have to add it manually.
@ -292,7 +337,7 @@ Determines if Pod annotations can be defined from a step's backend options.
Additional node selector to apply to worker pods. Must be a YAML object, e.g. `{"topology.kubernetes.io/region":"eu-central-1"}`.
### `WOODPECKER_BACKEND_K8S_SECCTX_NONROOT`
### `WOODPECKER_BACKEND_K8S_SECCTX_NONROOT` <!-- cspell:ignore SECCTX NONROOT -->
> Default: `false`

6
docs/versioned_docs/version-2.6/30-administration/22-backends/50-custom-backends.md → docs/versioned_docs/version-3.0/30-administration/22-backends/50-custom-backends.md
View File

@ -1,6 +1,6 @@
# Custom backends
If none of our backends fits your usecases, you can write your own.
If none of our backends fits your usecase, you can write your own.
Therefore, implement the interface `"go.woodpecker-ci.org/woodpecker/woodpecker/v2/pipeline/backend/types".Backend` and
build a custom agent using your backend with this `main.go`:
@ -9,8 +9,8 @@ build a custom agent using your backend with this `main.go`:
package main
import (
"go.woodpecker-ci.org/woodpecker/v2/cmd/agent/core"
backendTypes "go.woodpecker-ci.org/woodpecker/v2/pipeline/backend/types"
"go.woodpecker-ci.org/woodpecker/v3/cmd/agent/core"
backendTypes "go.woodpecker-ci.org/woodpecker/v3/pipeline/backend/types"
)
func main() {

0
docs/versioned_docs/version-2.6/30-administration/22-backends/_category_.yaml → docs/versioned_docs/version-3.0/30-administration/22-backends/_category_.yaml
View File

22
docs/versioned_docs/version-2.6/30-administration/70-proxy.md → docs/versioned_docs/version-3.0/30-administration/40-advanced/10-proxy.md
View File

@ -4,6 +4,8 @@
This guide provides a brief overview for installing Woodpecker server behind the Apache2 web-server. This is an example configuration:
<!-- cspell:ignore apacheconf -->
```apacheconf
ProxyPreserveHost On
@ -87,13 +89,13 @@ woodpecker.example.com {
}
# expose gRPC
woodpeckeragent.example.com {
woodpecker-agent.example.com {
reverse_proxy h2c://woodpecker-server:9000
}
```
:::note
Above configuration shows how to create reverse-proxies for web and agent communication. If your agent uses SSL do not forget to enable [`WOODPECKER_GRPC_SECURE`](./15-agent-config.md#woodpecker_grpc_secure).
Above configuration shows how to create reverse-proxies for web and agent communication. If your agent uses SSL do not forget to enable [`WOODPECKER_GRPC_SECURE`](../15-agent-config.md#woodpecker_grpc_secure).
:::
## Tunnelmole
@ -132,9 +134,9 @@ Set `WOODPECKER_HOST` to the ngrok URL (usually xxx.ngrok.io) and start the serv
To install the Woodpecker server behind a [Traefik](https://traefik.io/) load balancer, you must expose both the `http` and the `gRPC` ports. Here is a comprehensive example, considering you are running Traefik with docker swarm and want to do TLS termination and automatic redirection from http to https.
```yaml
version: '3.8'
<!-- cspell:words redirectscheme certresolver -->
```yaml
services:
server:
image: woodpeckerci/woodpecker-server:latest
@ -155,13 +157,13 @@ services:
# web server
- traefik.http.services.woodpecker-service.loadbalancer.server.port=8000
- traefik.http.routers.woodpecker-secure.rule=Host(`cd.yourdomain.com`)
- traefik.http.routers.woodpecker-secure.rule=Host(`cd.your-domain.com`)
- traefik.http.routers.woodpecker-secure.tls=true
- traefik.http.routers.woodpecker-secure.tls.certresolver=letsencrypt
- traefik.http.routers.woodpecker-secure.entrypoints=websecure
- traefik.http.routers.woodpecker-secure.entrypoints=web-secure
- traefik.http.routers.woodpecker-secure.service=woodpecker-service
- traefik.http.routers.woodpecker.rule=Host(`cd.yourdomain.com`)
- traefik.http.routers.woodpecker.rule=Host(`cd.your-domain.com`)
- traefik.http.routers.woodpecker.entrypoints=web
- traefik.http.routers.woodpecker.service=woodpecker-service
@ -173,13 +175,13 @@ services:
- traefik.http.services.woodpecker-grpc.loadbalancer.server.port=9000
- traefik.http.services.woodpecker-grpc.loadbalancer.server.scheme=h2c
- traefik.http.routers.woodpecker-grpc-secure.rule=Host(`woodpecker-grpc.yourdomain.com`)
- traefik.http.routers.woodpecker-grpc-secure.rule=Host(`woodpecker-grpc.your-domain.com`)
- traefik.http.routers.woodpecker-grpc-secure.tls=true
- traefik.http.routers.woodpecker-grpc-secure.tls.certresolver=letsencrypt
- traefik.http.routers.woodpecker-grpc-secure.entrypoints=websecure
- traefik.http.routers.woodpecker-grpc-secure.entrypoints=web-secure
- traefik.http.routers.woodpecker-grpc-secure.service=woodpecker-grpc
- traefik.http.routers.woodpecker-grpc.rule=Host(`woodpecker-grpc.yourdomain.com`)
- traefik.http.routers.woodpecker-grpc.rule=Host(`woodpecker-grpc.your-domain.com`)
- traefik.http.routers.woodpecker-grpc.entrypoints=web
- traefik.http.routers.woodpecker-grpc.service=woodpecker-grpc

17
docs/versioned_docs/version-2.6/30-administration/100-external-configuration-api.md → docs/versioned_docs/version-3.0/30-administration/40-advanced/100-external-configuration-api.md
View File

@ -3,7 +3,7 @@
To provide additional management and preprocessing capabilities for pipeline configurations Woodpecker supports an HTTP API which can be enabled to call an external config service.
Before the run or restart of any pipeline Woodpecker will make a POST request to an external HTTP API sending the current repository, build information and all current config files retrieved from the repository. The external API can then send back new pipeline configurations that will be used immediately or respond with `HTTP 204` to tell the system to use the existing configuration.
Every request sent by Woodpecker is signed using a [http-signature](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures) by a private key (ed25519) generated on the first start of the Woodpecker server. You can get the public key for the verification of the http-signature from `http(s)://your-woodpecker-server/api/signature/public-key`.
Every request sent by Woodpecker is signed using a [http-signature](https://datatracker.ietf.org/doc/html/rfc9421) by a private key (ed25519) generated on the first start of the Woodpecker server. You can get the public key for the verification of the http-signature from `http(s)://your-woodpecker-server/api/signature/public-key`.
A simplistic example configuration service can be found here: [https://github.com/woodpecker-ci/example-config-service](https://github.com/woodpecker-ci/example-config-service)
@ -26,7 +26,7 @@ WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig
"uid": "",
"user_id": 0,
"namespace": "",
"name": "woodpecker-testpipe",
"name": "woodpecker-test-pipe",
"slug": "",
"scm": "git",
"git_http_url": "",
@ -54,7 +54,7 @@ WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig
"author_avatar": "https://myforge.com/avatars/d6b3f7787a685fcdf2a44e2c685c7e03",
"author_email": "my@email.com",
"branch": "main",
"changed_files": ["somefilename.txt"],
"changed_files": ["some-file-name.txt"],
"commit": "2fff90f8d288a4640e90f05049fe30e61a14fd50",
"created_at": 0,
"deploy_to": "",
@ -81,12 +81,11 @@ WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig
"updated_at": 0,
"verified": false
},
"configs": [
{
"name": ".woodpecker.yaml",
"data": "steps:\n - name: backend\n image: alpine\n commands:\n - echo \"Hello there from Repo (.woodpecker.yaml)\"\n"
}
]
"netrc": {
"machine": "https://example.com",
"login": "user",
"password": "password"
}
}
```

Some files were not shown because too many files have changed in this diff Show More