mirrors/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2024-06-02 09:31:42 +00:00
Code Issues Projects Releases Wiki Activity

Use array syntax in docs (#3242)

Browse source
This commit is contained in:
qwerty287 2024-01-22 08:18:50 +01:00 committed by GitHub
parent 05f24a5706
commit 188d6ed16c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
24 changed files with 166 additions and 138 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
docs/docs/10-intro.md
View file

@ -13,11 +13,11 @@ If you are already using containers in your daily workflow, you'll for sure love
```yaml title=".woodpecker.yaml"
steps:
build:
- name: build
image: debian
commands:
- echo "This is the build step"
a-test-step:
- name: a-test-step
image: debian
commands:
- echo "Testing.."
@ -32,7 +32,7 @@ steps:
```diff
steps:
build:
- name: build
- image: debian
+ image: mycompany/image-with-awscli
commands:
@ -46,11 +46,11 @@ steps:
```yaml title=".woodpecker.yaml"
steps:
build:
- name: build
image: debian
commands:
- touch myfile
a-test-step:
- name: a-test-step
image: debian
commands:
- cat myfile

10
docs/docs/20-usage/10-intro.md
View file

@ -30,7 +30,7 @@ Example pipeline configuration:
```yaml
steps:
build:
- name: build
image: golang
commands:
- go get
@ -38,7 +38,7 @@ steps:
- go test
services:
postgres:
- name: postgres
image: postgres:9.4.5
environment:
- POSTGRES_USER=myapp
@ -48,20 +48,20 @@ Example pipeline configuration with multiple, serial steps:
```yaml
steps:
backend:
- name: backend
image: golang
commands:
- go get
- go build
- go test
frontend:
- name: frontend
image: node:6
commands:
- npm install
- npm test
notify:
- name: notify
image: plugins/slack
channel: developers
username: woodpecker

96
docs/docs/20-usage/20-workflow-syntax.md
View file

@ -4,25 +4,6 @@ The workflow section defines a list of steps to build, test and deploy your code
Example steps:
```yaml
steps:
backend:
image: golang
commands:
- go build
- go test
frontend:
image: node
commands:
- npm install
- npm run test
- npm run build
```
In the above example we define two steps, `frontend` and `backend`. The names of these steps are completely arbitrary.
Another way to name a step is by using the name keyword:
```yaml
steps:
- name: backend
@ -38,7 +19,26 @@ steps:
- npm run build
```
Keep in mind the name is optional, if not added the steps will be numerated.
In the above example we define two steps, `frontend` and `backend`. The names of these steps are completely arbitrary.
The name is optional, if not added the steps will be numerated.
Another way to name a step is by using dictionaries:
```yaml
steps:
backend:
image: golang
commands:
- go build
- go test
frontend:
image: node
commands:
- npm install
- npm run test
- npm run build
```
## Skip Commits
@ -55,7 +55,7 @@ The associated commit is checked out with git to a workspace which is mounted to
```diff
steps:
backend:
- name: backend
image: golang
commands:
+ - go build
@ -69,11 +69,11 @@ The associated commit is checked out with git to a workspace which is mounted to
```yaml title=".woodpecker.yaml"
steps:
build:
- name: build
image: debian
commands:
- echo "test content" > myfile
a-test-step:
- name: a-test-step
image: debian
commands:
- cat myfile
@ -87,18 +87,18 @@ When using the `local` backend, the `image` entry is used to specify the shell,
```diff
steps:
build:
- name: build
+ image: golang:1.6
commands:
- go build
- go test
publish:
- name: publish
+ image: plugins/docker
repo: foo/bar
services:
database:
- name: database
+ image: mysql
```
@ -116,7 +116,7 @@ Woodpecker does not automatically upgrade container images. Example configuratio
```diff
steps:
build:
- name: build
image: golang:latest
+ pull: true
```
@ -129,7 +129,7 @@ Commands of every step are executed serially as if you would enter them into you
```diff
steps:
backend:
- name: backend
image: golang
commands:
+ - go build
@ -178,7 +178,7 @@ Some of the steps may be allowed to fail without causing the whole workflow and
```diff
steps:
backend:
- name: backend
image: golang
commands:
- go build
@ -192,7 +192,7 @@ Woodpecker supports defining a list of conditions for a step by using a `when` b
```diff
steps:
slack:
- name: slack
image: plugins/slack
settings:
channel: dev
@ -209,7 +209,7 @@ Example conditional execution by repository:
```diff
steps:
slack:
- name: slack
image: plugins/slack
settings:
channel: dev
@ -227,7 +227,7 @@ Example conditional execution by branch:
```diff
steps:
slack:
- name: slack
image: plugins/slack
settings:
channel: dev
@ -324,7 +324,7 @@ There are use cases for executing steps on failure, such as sending notification
```diff
steps:
slack:
- name: slack
image: plugins/slack
settings:
channel: dev
@ -457,18 +457,18 @@ Normally steps of a workflow are executed serially in the order in which they ar
```diff
steps:
build: # build will be executed immediately
- name: build # build will be executed immediately
image: golang
commands:
- go build
deploy:
- name: deploy
image: plugins/docker
settings:
repo: foo/bar
+ depends_on: [build, test] # deploy will be executed after build and test finished
test: # test will be executed immediately as no dependencies are set
- name: test # test will be executed immediately as no dependencies are set
image: golang
commands:
- go test
@ -508,7 +508,7 @@ The workspace can be customized using the workspace block in the YAML file:
+ path: src/github.com/octocat/hello-world
steps:
build:
- name: build
image: golang:latest
commands:
- go get
@ -523,12 +523,12 @@ The base attribute defines a shared base volume available to all steps. This ens
path: src/github.com/octocat/hello-world
steps:
deps:
- name: deps
image: golang:latest
commands:
- go get
- go test
build:
- name: build
image: node:latest
commands:
- go build
@ -580,7 +580,7 @@ You can add additional labels as a key value map:
+ hostname: "" # this label will be ignored as it is empty
steps:
build:
- name: build
image: golang
commands:
- go build
@ -622,7 +622,7 @@ You can manually configure the clone step in your workflow for customization:
+ image: woodpeckerci/plugin-git
steps:
build:
- name: build
image: golang
commands:
- go build
@ -633,7 +633,7 @@ Example configuration to override depth:
```diff
clone:
git:
- name: git
image: woodpeckerci/plugin-git
+ settings:
+ partial: false
@ -652,7 +652,7 @@ Example configuration to clone Mercurial repository:
```diff
clone:
hg:
- name: hg
+ image: plugins/hg
+ settings:
+ path: bitbucket.org/foo/bar
@ -673,7 +673,7 @@ To use the ssh git url in `.gitmodules` for users cloning with ssh, and also use
```diff
clone:
git:
- name: git
image: woodpeckerci/plugin-git
settings:
recursive: true
@ -705,7 +705,7 @@ Example conditional execution by repository:
+ repo: test/test
+
steps:
slack:
- name: slack
image: plugins/slack
settings:
channel: dev
@ -724,7 +724,7 @@ Example conditional execution by branch:
+ branch: main
+
steps:
slack:
- name: slack
image: plugins/slack
settings:
channel: dev
@ -862,14 +862,14 @@ Privileged mode is only available to trusted repositories and for security reaso
```diff
steps:
build:
- name: build
image: docker
environment:
- DOCKER_HOST=tcp://docker:2375
commands:
- docker --tls=false ps
services:
- name: services
docker:
image: docker:dind
commands: dockerd-entrypoint.sh --storage-driver=vfs --tls=false

12
docs/docs/20-usage/25-workflows.md
View file

@ -31,7 +31,7 @@ If you still need to pass artifacts between the workflows you need use some stor
```yaml title=".woodpecker/.build.yaml"
steps:
build:
- name: build
image: debian:stable-slim
commands:
- echo building
@ -40,7 +40,7 @@ steps:
```yaml title=".woodpecker/.deploy.yaml"
steps:
deploy:
- name: deploy
image: debian:stable-slim
commands:
- echo deploying
@ -53,7 +53,7 @@ depends_on:
```yaml title=".woodpecker/.test.yaml"
steps:
test:
- name: test
image: debian:stable-slim
commands:
- echo testing
@ -65,7 +65,7 @@ depends_on:
```yaml title=".woodpecker/.lint.yaml"
steps:
lint:
- name: lint
image: debian:stable-slim
commands:
- echo linting
@ -86,7 +86,7 @@ The name for a `depends_on` entry is the filename without the path, leading dots
```diff
steps:
deploy:
- name: deploy
image: debian:stable-slim
commands:
- echo deploying
@ -101,7 +101,7 @@ Workflows that need to run even on failures should set the `runs_on` tag.
```diff
steps:
notify:
- name: notify
image: debian:stable-slim
commands:
- echo notifying

16
docs/docs/20-usage/30-matrix-workflows.md
View file

@ -43,7 +43,7 @@ matrix:
- mariadb:10.1
steps:
build:
- name: build
image: golang:${GO_VERSION}
commands:
- go get
@ -51,7 +51,7 @@ steps:
- go test
services:
database:
- name: database
image: ${DATABASE}
```
@ -59,7 +59,7 @@ Example YAML file after injecting the matrix parameters:
```diff
steps:
build:
- name: build
- image: golang:${GO_VERSION}
+ image: golang:1.4
commands:
@ -71,7 +71,7 @@ Example YAML file after injecting the matrix parameters:
+ - DATABASE=mysql:8
services:
database:
- name: database
- image: ${DATABASE}
+ image: mysql:8
```
@ -88,7 +88,7 @@ matrix:
- latest
steps:
build:
- name: build
image: golang:${TAG}
commands:
- go build
@ -105,7 +105,7 @@ matrix:
- golang:latest
steps:
build:
- name: build
image: ${IMAGE}
commands:
- go build
@ -124,12 +124,12 @@ labels:
platform: ${platform}
steps:
test:
- name: test
image: alpine
commands:
- echo "I am running on ${platform}"
test-arm-only:
- name: test-arm-only
image: alpine
commands:
- echo "I am running on ${platform}"

8
docs/docs/20-usage/40-secrets.md
View file

@ -18,7 +18,7 @@ once their usage is declared in the `secrets` section:
```diff
steps:
docker:
- name: docker
image: docker
commands:
+ - echo $DOCKER_USERNAME
@ -35,7 +35,7 @@ In this example, the secret named `secret_token` would be passed to the setting
```diff
steps:
docker:
- name: docker
image: my-plugin
settings:
+ token:
@ -48,7 +48,7 @@ Please note parameter expressions are subject to pre-processing. When using secr
```diff
steps:
docker:
- name: docker
image: docker
commands:
- - echo ${DOCKER_USERNAME}
@ -64,7 +64,7 @@ There may be scenarios where you are required to store secrets using alternate n
```diff
steps:
docker:
- name: docker
image: plugins/docker
repo: octocat/hello-world
tags: latest

6
docs/docs/20-usage/41-registries.md
View file

@ -12,7 +12,7 @@ Example configuration using a private image:
```diff
steps:
build:
- name: build
+ image: gcr.io/custom/golang
commands:
- go build
@ -55,14 +55,14 @@ With a `Dockerfile` at the root of the project:
```yaml
steps:
build-image:
- name: build-image
image: docker
commands:
- docker build --rm -t local/project-image .
volumes:
- /var/run/docker.sock:/var/run/docker.sock
build-project:
- name: build-project
image: local/project-image
commands:
- ./build.sh

2
docs/docs/20-usage/45-cron.md
View file

@ -8,7 +8,7 @@ To configure cron jobs you need at least push access to the repository.
```diff
steps:
sync_locales:
- name: sync_locales
image: weblate_sync
settings:
url: example.com

16
docs/docs/20-usage/50-environment.md
View file

@ -4,7 +4,7 @@ Woodpecker provides the ability to pass environment variables to individual pipe
```diff
steps:
build:
- name: build
image: golang
+ environment:
+ - CGO=0
@ -19,7 +19,7 @@ Please note that the environment section is not able to expand environment varia
```diff
steps:
build:
- name: build
image: golang
- environment:
- - PATH=$PATH:/go
@ -35,7 +35,7 @@ Please note that the environment section is not able to expand environment varia
```diff
steps:
build:
- name: build
image: golang
commands:
- - export PATH=${PATH}:/go
@ -153,7 +153,7 @@ WOODPECKER_ENVIRONMENT=GOLANG_VERSION:1.18
```diff
steps:
build:
- name: build
- image: golang:1.18
+ image: golang:${GOLANG_VERSION}
commands:
@ -168,7 +168,7 @@ Example commit substitution:
```diff
steps:
docker:
- name: docker
image: plugins/docker
settings:
+ tags: ${CI_COMMIT_SHA}
@ -178,7 +178,7 @@ Example tag substitution:
```diff
steps:
docker:
- name: docker
image: plugins/docker
settings:
+ tags: ${CI_COMMIT_TAG}
@ -206,7 +206,7 @@ Example variable substitution with substring:
```diff
steps:
docker:
- name: docker
image: plugins/docker
settings:
+ tags: ${CI_COMMIT_SHA:0:8}
@ -216,7 +216,7 @@ Example variable substitution strips `v` prefix from `v.1.0.0`:
```diff
steps:
docker:
- name: docker
image: plugins/docker
settings:
+ tags: ${CI_COMMIT_TAG##v}

6
docs/docs/20-usage/51-plugins/10-overview.md
View file

@ -8,19 +8,19 @@ Example pipeline using the Docker and Slack plugins:
```yaml
steps:
build:
- name: build
image: golang
commands:
- go build
- go test
publish:
- name: publish
image: plugins/docker
settings:
repo: foo/bar
tags: latest
notify:
- name: notify
image: plugins/slack
settings:
channel: dev

4
docs/docs/20-usage/51-plugins/20-creating-plugins.md
View file

@ -28,7 +28,7 @@ It's also possible to use complex settings like this:
```yaml
steps:
plugin:
- name: plugin
image: foo/plugin
settings:
complex:
@ -58,7 +58,7 @@ The below example demonstrates how we might configure a webhook plugin in the YA
```yaml
steps:
webhook:
- name: webhook
image: foo/webhook
settings:
url: https://example.com

28
docs/docs/20-usage/60-services.md
View file

@ -8,17 +8,17 @@ In the example below, the MySQL service is assigned the hostname `database` and
```yaml
steps:
build:
- name: build
image: golang
commands:
- go build
- go test
services:
database:
- name: database
image: mysql
cache:
- name: cache
image: redis
```
@ -26,12 +26,12 @@ You can define a port and a protocol explicitly:
```yaml
services:
database:
- name: database
image: mysql
ports:
- 3306
wireguard:
- name: wireguard
image: wg
ports:
- 51820/udp
@ -43,13 +43,13 @@ Service containers generally expose environment variables to customize service s
```diff
services:
database:
- name: database
image: mysql
+ environment:
+ - MYSQL_DATABASE=test
+ - MYSQL_ALLOW_EMPTY_PASSWORD=yes
cache:
- name: cache
image: redis
```
@ -59,17 +59,17 @@ Service and long running containers can also be included in the pipeline section
```diff
steps:
build:
- name: build
image: golang
commands:
- go build
- go test
database:
- name: database
image: redis
+ detach: true
test:
- name: test
image: golang
commands:
- go test
@ -83,7 +83,7 @@ Service containers require time to initialize and begin to accept connections. I
```diff
steps:
test:
- name: test
image: golang
commands:
+ - sleep 15
@ -91,7 +91,7 @@ Service containers require time to initialize and begin to accept connections. I
- go test
services:
database:
- name: database
image: mysql
```
@ -99,13 +99,13 @@ Service containers require time to initialize and begin to accept connections. I
```yaml
services:
database:
- name: database
image: mysql
environment:
- MYSQL_DATABASE=test
- MYSQL_ROOT_PASSWORD=example
steps:
get-version:
- name: get-version
image: ubuntu
commands:
- ( apt update && apt dist-upgrade -y && apt install -y mysql-client 2>&1 )> /dev/null

2
docs/docs/20-usage/70-volumes.md
View file

@ -8,7 +8,7 @@ Volumes are only available to trusted repositories and for security reasons shou
```diff
steps:
build:
- name: build
image: docker
commands:
- docker build --rm -t octocat/hello-world .

20
docs/docs/20-usage/90-advanced-usage.md
View file

@ -12,10 +12,10 @@ To convert this:
```yaml
steps:
test:
- name: test
image: golang:1.18
commands: go test ./...
build:
- name: build
image: golang:1.18
commands: build
```
@ -27,11 +27,11 @@ Just add a new section called **variables** like this:
+ - &golang_image 'golang:1.18'
steps:
test:
- name: test
- image: golang:1.18
+ image: *golang_image
commands: go test ./...
build:
- name: build
- image: golang:1.18
+ image: *golang_image
commands: build
@ -50,14 +50,14 @@ variables:
- &some-plugin codeberg.org/6543/docker-images/print_env
steps:
develop:
- name: develop
image: *some-plugin
settings:
<<: [*base-plugin-settings, *special-setting] # merge two maps into an empty map
when:
branch: develop
main:
- name: main
image: *some-plugin
settings:
<<: *base-plugin-settings # merge one map and ...
@ -80,13 +80,13 @@ variables:
- echo hello
steps:
step1:
- name: step1
image: debian
commands:
- <<: *pre_cmds # prepend a sequence
- echo exec step now do dedicated things
- <<: *post_cmds # append a sequence
step2:
- name: step2
image: debian
commands:
- <<: [*pre_cmds, *hello_cmd] # prepend two sequences
@ -105,13 +105,13 @@ One can create a file containing environment variables, and then source it in ea
```yaml
steps:
init:
- name: init
image: bash
commands:
- echo "FOO=hello" >> envvars
- echo "BAR=world" >> envvars
debug:
- name: debug
image: bash
commands:
- source envvars

18
docs/docs/30-administration/00-deployment/00-overview.md
View file

@ -18,6 +18,24 @@ Woodpecker is having two different kinds of releases: **stable** and **next**.
To find out more about the differences between the two releases, please read the [FAQ](/faq#which-version-of-woodpecker-should-i-use).
### Stable releases
We release a new version every four weeks and will release the current state of the `main` branch.
If there are security fixes or critical bug fixes, we'll release them directly.
There are no backports or similar.
#### Versioning
We use [Semantic Versioning](https://semver.org/) to be able,
to communicate when admins have to do manual migration steps and when they can just bump versions up.
#### Breaking changes
As of semver guidelines, breaking changes will be released as a major version. We will hold back
breaking changes to not release many majors each containing just a few breaking changes.
Prior to the release of a major version, a release candidate (RC) will be published to allow easy testing,
the actual release will be about a week later.
## Hardware Requirements
Below are minimal resources requirements for Woodpecker components itself:

8
docs/docs/30-administration/10-server-config.md
View file

@ -189,9 +189,13 @@ Disable colored debug output.
> Default: empty
Server fully qualified URL of the user-facing hostname and path prefix.
Server fully qualified URL of the user-facing hostname, port (if not default for HTTP/HTTPS) and path prefix.
Example: `WOODPECKER_HOST=http://woodpecker.example.org` or `WOODPECKER_HOST=http://example.org/woodpecker`
Examples:
- `WOODPECKER_HOST=http://woodpecker.example.org`
- `WOODPECKER_HOST=http://example.org/woodpecker`
- `WOODPECKER_HOST=http://example.org:1234/woodpecker`
### `WOODPECKER_WEBHOOK_HOST`

4
docs/docs/30-administration/100-external-configuration-api.md
View file

@ -84,7 +84,7 @@ WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig
"configs": [
{
"name": ".woodpecker.yaml",
"data": "steps:\n backend:\n image: alpine\n commands:\n - echo \"Hello there from Repo (.woodpecker.yaml)\"\n"
"data": "steps:\n - name: backend\n image: alpine\n commands:\n - echo \"Hello there from Repo (.woodpecker.yaml)\"\n"
}
]
}
@ -97,7 +97,7 @@ WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig
"configs": [
{
"name": "central-override",
"data": "steps:\n backend:\n image: alpine\n commands:\n - echo \"Hello there from ConfigAPI\"\n"
"data": "steps:\n - name: backend\n image: alpine\n commands:\n - echo \"Hello there from ConfigAPI\"\n"
}
]
}

4
docs/docs/30-administration/11-forges/20-github.md
View file

@ -1,3 +1,7 @@
---
toc_max_heading_level: 2
---
# GitHub
Woodpecker comes with built-in support for GitHub and GitHub Enterprise.

4
docs/docs/30-administration/11-forges/30-gitea.md
View file

@ -1,3 +1,7 @@
---
toc_max_heading_level: 2
---
# Gitea / Forgejo
Woodpecker comes with built-in support for Gitea and the "soft" fork Forgejo. To enable Gitea you should configure the Woodpecker container using the following environment variables:

4
docs/docs/30-administration/11-forges/40-gitlab.md
View file

@ -1,3 +1,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:

4
docs/docs/30-administration/11-forges/50-bitbucket.md
View file

@ -1,3 +1,7 @@
---
toc_max_heading_level: 2
---
# Bitbucket
Woodpecker comes with built-in support for Bitbucket Cloud. To enable Bitbucket Cloud you should configure the Woodpecker container using the following environment variables:

4
docs/docs/30-administration/22-backends/20-local.md
View file

@ -44,7 +44,7 @@ used to run the commands.
```yaml title=".woodpecker.yaml"
steps:
build:
- name: build
image: bash
commands: [...]
```
@ -55,7 +55,7 @@ Plugins are just executable binaries:
```yaml
steps:
build:
- name: build
image: /usr/bin/tree
```

8
docs/docs/30-administration/22-backends/40-kubernetes.md
View file

@ -17,7 +17,7 @@ Here is an example definition with an arbitrary `resources` definition below the
```yaml
steps:
'My kubernetes step':
- name: 'My kubernetes step'
image: alpine
commands:
- echo "Hello world"
@ -75,7 +75,7 @@ Example pipeline configuration:
```yaml
steps:
build:
- name: build
image: golang
commands:
- go get
@ -107,7 +107,7 @@ Assuming a PVC named "woodpecker-cache" exists, it can be referenced as follows
```yaml
steps:
"Restore Cache":
- name: "Restore Cache"
image: meltwater/drone-cache
volumes:
- woodpecker-cache:/woodpecker/src/cache
@ -123,7 +123,7 @@ Use the following configuration to set the `securityContext` for the pod/contain
```yaml
steps:
test:
- name: test
image: alpine
commands:
- echo Hello world

10
docs/docs/92-development/09-security.md
View file

@ -1,10 +0,0 @@
# Security
We take security seriously.
If you discover a security issue, please bring it to our attention right away!
## Reporting a Vulnerability
Please **DO NOT** file a public issue, instead send your report privately to [`security @ woodpecker-ci.org`](mailto:security@woodpecker-ci.org).
Security reports are greatly appreciated, and we will publicly thank you for it. If you choose to remain anonymous, we will respect your request and keep your name confidential.