github/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2025-08-10 18:31:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update Documentation (fix diffs and add settings) (#569)

Browse Source 
* Add migration guide for plugin settings

* Update screenshot snippets

* Adjust plugin settings

* Fix diff insertion

Co-authored-by: John Olheiser <john.olheiser@gmail.com>
This commit is contained in:
6543 2021-12-06 18:18:53 +01:00 committed by GitHub
parent 71b9179078
commit 7fb9191cce
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 180 additions and 162 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

291
docs/docs/20-usage/20-pipeline-syntax.md
View File

@ -111,18 +111,15 @@ See [when](#step-when---step-conditional-execution) above to understand all the
Example targeting a specific platform: Example targeting a specific platform:
```diff ```diff
pipeline: pipeline:
build: build:
image: golang image: golang
commands: commands:
- go build - go build
- go test - go test
-when:
-platform: [ linux/arm* ]
+when: +when:
+ platform: [ linux/arm* ] + platform: [ linux/arm* ]
``` ```
Assuming we have two agents, one `arm` and one `amd64`. Previously this pipeline would have executed on **either agent**, as Woodpecker is not fussy about where it runs the pipelines. Assuming we have two agents, one `arm` and one `amd64`. Previously this pipeline would have executed on **either agent**, as Woodpecker is not fussy about where it runs the pipelines.
@ -134,38 +131,37 @@ This can be utilised in conjunction with other when blocks as well.
Example `when` pipeline & step block: Example `when` pipeline & step block:
```yml ```diff
pipeline: pipeline:
build: build:
image: golang image: golang
commands: commands:
- go build - go build
- go test - go test
publish: publish:
image: plugins/docker image: plugins/docker
repo: foo/bar settings:
+when: repo: foo/bar
+tag: release* + when:
+ tag: release*
+when: +when:
+ platform: [ linux/arm* ] + platform: [ linux/arm* ]
``` ```
### `platform` ### `platform`
To configure your pipeline to select an agent with a specific platform, you can use `platform` key. To configure your pipeline to select an agent with a specific platform, you can use `platform` key.
```diff ```diff
+platform: linux/arm64 +platform: linux/arm64
pipeline: pipeline:
build: build:
image: golang image: golang
commands: commands:
- go build - go build
- go test - go test
``` ```
### Skip Commits ### Skip Commits
@ -190,12 +186,12 @@ Every step of your pipeline executes arbitrary commands inside a specified docke
The associated commit of a current pipeline run is checked out with git to a workspace which is mounted to every step of the pipeline as the working directory. The associated commit of a current pipeline run is checked out with git to a workspace which is mounted to every step of the pipeline as the working directory.
```diff ```diff
pipeline: pipeline:
backend: backend:
image: golang image: golang
commands: commands:
+ - go build + - go build
+ - go test + - go test
``` ```
### File changes are incremental ### File changes are incremental
@ -221,20 +217,20 @@ pipeline:
Woodpecker uses Docker images for the build environment, for plugins and for service containers. The image field is exposed in the container blocks in the Yaml: Woodpecker uses Docker images for the build environment, for plugins and for service containers. The image field is exposed in the container blocks in the Yaml:
```diff ```diff
pipeline: pipeline:
build: build:
+ image: golang:1.6 + image: golang:1.6
commands: commands:
- go build - go build
- go test - go test
publish: publish:
+ image: plugins/docker + image: plugins/docker
repo: foo/bar repo: foo/bar
services: services:
database: database:
+ image: mysql + image: mysql
``` ```
Woodpecker supports any valid Docker image from any Docker registry: Woodpecker supports any valid Docker image from any Docker registry:
@ -250,10 +246,10 @@ image: index.docker.io/library/golang:1.7
Woodpecker does not automatically upgrade docker images. Example configuration to always pull the latest image when updates are available: Woodpecker does not automatically upgrade docker images. Example configuration to always pull the latest image when updates are available:
```diff ```diff
pipeline: pipeline:
build: build:
image: golang:latest image: golang:latest
+ pull: true + pull: true
``` ```
#### Images from private registries #### Images from private registries
@ -265,12 +261,12 @@ These credentials are never exposed to your pipeline, which means they cannot be
Example configuration using a private image: Example configuration using a private image:
```diff ```diff
pipeline: pipeline:
build: build:
+ image: gcr.io/custom/golang + image: gcr.io/custom/golang
commands: commands:
- go build - go build
- go test - go test
``` ```
Woodpecker matches the registry hostname to each image in your yaml. If the hostnames match, the registry credentials are used to authenticate to your registry and pull the image. Note that registry credentials are used by the Woodpecker agent and are never exposed to your build containers. Woodpecker matches the registry hostname to each image in your yaml. If the hostnames match, the registry credentials are used to authenticate to your registry and pull the image. Note that registry credentials are used by the Woodpecker agent and are never exposed to your build containers.
@ -302,12 +298,12 @@ For specific details on configuring access to Google Container Registry, please
Commands of every pipeline step are executed serially as if you would enter them into your local shell. Commands of every pipeline step are executed serially as if you would enter them into your local shell.
```diff ```diff
pipeline: pipeline:
backend: backend:
image: golang image: golang
commands: commands:
+ - go build + - go build
+ - go test + - go test
``` ```
There is no magic here. The above commands are converted to a simple shell script. The commands in the above example are roughly converted to the below script: There is no magic here. The above commands are converted to a simple shell script. The commands in the above example are roughly converted to the below script:
@ -353,23 +349,23 @@ Woodpecker supports parallel step execution for same-machine fan-in and fan-out.
Example parallel configuration: Example parallel configuration:
```diff ```diff
pipeline: pipeline:
backend: backend:
+ group: build + group: build
image: golang image: golang
commands: commands:
- go build - go build
- go test - go test
frontend: frontend:
+ group: build + group: build
image: node image: node
commands: commands:
- npm install - npm install
- npm run test - npm run test
- npm run build - npm run build
publish: publish:
image: plugins/docker image: plugins/docker
repo: octocat/hello-world repo: octocat/hello-world
``` ```
In the above example, the `frontend` and `backend` steps are executed in parallel. The pipeline runner will not execute the `publish` step until the group completes. In the above example, the `frontend` and `backend` steps are executed in parallel. The pipeline runner will not execute the `publish` step until the group completes.
@ -403,31 +399,31 @@ The workspace can be customized using the workspace block in the Yaml file:
+ base: /go + base: /go
+ path: src/github.com/octocat/hello-world + path: src/github.com/octocat/hello-world
pipeline: pipeline:
build: build:
image: golang:latest image: golang:latest
commands: commands:
- go get - go get
- go test - go test
``` ```
The base attribute defines a shared base volume available to all pipeline steps. This ensures your source code, dependencies and compiled binaries are persisted and shared between steps. The base attribute defines a shared base volume available to all pipeline steps. This ensures your source code, dependencies and compiled binaries are persisted and shared between steps.
```diff ```diff
workspace: workspace:
+ base: /go + base: /go
path: src/github.com/octocat/hello-world path: src/github.com/octocat/hello-world
pipeline: pipeline:
deps: deps:
image: golang:latest image: golang:latest
commands: commands:
- go get - go get
- go test - go test
build: build:
image: node:latest image: node:latest
commands: commands:
- go build - go build
``` ```
This would be equivalent to the following docker commands: This would be equivalent to the following docker commands:
@ -442,9 +438,9 @@ docker run --volume=my-named-volume:/go node:latest
The path attribute defines the working directory of your build. This is where your code is cloned and will be the default working directory of every step in your build process. The path must be relative and is combined with your base path. The path attribute defines the working directory of your build. This is where your code is cloned and will be the default working directory of every step in your build process. The path must be relative and is combined with your base path.
```diff ```diff
workspace: workspace:
base: /go base: /go
+ path: src/github.com/octocat/hello-world + path: src/github.com/octocat/hello-world
``` ```
```text ```text
@ -466,22 +462,23 @@ Woodpecker automatically configures a default clone step if not explicitly defin
+clone: +clone:
+ git: + git:
+ image: woodpeckerci/plugin-git + image: woodpeckerci/plugin-git
pipeline: pipeline:
build: build:
image: golang image: golang
commands: commands:
- go build - go build
- go test - go test
``` ```
Example configuration to override depth: Example configuration to override depth:
```diff ```diff
clone: clone:
git: git:
image: woodpeckerci/plugin-git image: woodpeckerci/plugin-git
+ depth: 50 + settings:
+ depth: 50
``` ```
Example configuration to use a custom clone plugin: Example configuration to use a custom clone plugin:
@ -495,10 +492,11 @@ clone:
Example configuration to clone Mercurial repository: Example configuration to clone Mercurial repository:
```diff ```diff
clone: clone:
hg: hg:
+ image: plugins/hg + image: plugins/hg
+ path: bitbucket.org/foo/bar + settings:
+ path: bitbucket.org/foo/bar
``` ```
#### Git Submodules #### Git Submodules
@ -506,21 +504,22 @@ clone:
To use the credentials that cloned the repository to clone it's submodules, update `.gitmodules` to use `https` instead of `git`: To use the credentials that cloned the repository to clone it's submodules, update `.gitmodules` to use `https` instead of `git`:
```diff ```diff
[submodule "my-module"] [submodule "my-module"]
path = my-module path = my-module
- url = git@github.com:octocat/my-module.git -url = git@github.com:octocat/my-module.git
+ url = https://github.com/octocat/my-module.git +url = https://github.com/octocat/my-module.git
``` ```
To use the ssh git url in `.gitmodules` for users cloning with ssh, and also use the https url in Woodpecker, add `submodule_override`: To use the ssh git url in `.gitmodules` for users cloning with ssh, and also use the https url in Woodpecker, add `submodule_override`:
```diff ```diff
clone: clone:
git: git:
image: woodpeckerci/plugin-git image: woodpeckerci/plugin-git
recursive: true settings:
+ submodule_override: recursive: true
+ my-module: https://github.com/octocat/my-module.git + submodule_override:
+ my-module: https://github.com/octocat/my-module.git
pipeline: pipeline:
... ...
@ -533,17 +532,17 @@ Woodpecker gives the ability to configure privileged mode in the Yaml. You can u
> Privileged mode is only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](/docs/usage/project-settings#trusted) to enable trusted mode. > Privileged mode is only available to trusted repositories and for security reasons should only be used in private environments. See [project settings](/docs/usage/project-settings#trusted) to enable trusted mode.
```diff ```diff
pipeline: pipeline:
build: build:
image: docker image: docker
environment: environment:
- DOCKER_HOST=tcp://docker:2375 - DOCKER_HOST=tcp://docker:2375
commands: commands:
- docker --tls=false ps - docker --tls=false ps
services: services:
docker: docker:
image: docker:dind image: docker:dind
command: [ "--storage-driver=vfs", "--tls=false" ] command: [ "--storage-driver=vfs", "--tls=false" ]
+ privileged: true + privileged: true
``` ```

6
docs/docs/20-usage/22-conditional-execution.md
View File

@ -12,7 +12,8 @@ Example conditional execution by branch:
pipeline: pipeline:
slack: slack:
image: plugins/slack image: plugins/slack
channel: dev settings:
channel: dev
+ when: + when:
+ branch: master + branch: master
``` ```
@ -90,7 +91,8 @@ There are use cases for executing pipeline steps on failure, such as sending not
pipeline: pipeline:
slack: slack:
image: plugins/slack image: plugins/slack
channel: dev settings:
channel: dev
+ when: + when:
+ status: [ success, failure ] + status: [ success, failure ]
``` ```

12
docs/docs/20-usage/50-environment.md
View File

@ -146,7 +146,8 @@ Example commit substitution:
pipeline: pipeline:
docker: docker:
image: plugins/docker image: plugins/docker
+ tags: ${CI_COMMIT_SHA} settings:
+ tags: ${CI_COMMIT_SHA}
``` ```
Example tag substitution: Example tag substitution:
@ -155,7 +156,8 @@ Example tag substitution:
pipeline: pipeline:
docker: docker:
image: plugins/docker image: plugins/docker
+ tags: ${CI_COMMIT_TAG} settings:
+ tags: ${CI_COMMIT_TAG}
``` ```
## String Operations ## String Operations
@ -182,7 +184,8 @@ Example variable substitution with substring:
pipeline: pipeline:
docker: docker:
image: plugins/docker image: plugins/docker
+ tags: ${CI_COMMIT_SHA:0:8} settings:
+ tags: ${CI_COMMIT_SHA:0:8}
``` ```
Example variable substitution strips `v` prefix from `v.1.0.0`: Example variable substitution strips `v` prefix from `v.1.0.0`:
@ -191,5 +194,6 @@ Example variable substitution strips `v` prefix from `v.1.0.0`:
pipeline: pipeline:
docker: docker:
image: plugins/docker image: plugins/docker
+ tags: ${CI_COMMIT_TAG##v} settings:
+ tags: ${CI_COMMIT_TAG##v}
``` ```

8
docs/docs/20-usage/51-plugins/10-plugins.md
View File

@ -16,12 +16,14 @@ pipeline:
publish: publish:
image: plugins/docker image: plugins/docker
repo: foo/bar settings:
tags: latest repo: foo/bar
tags: latest
notify: notify:
image: plugins/slack image: plugins/slack
channel: dev settings:
channel: dev
``` ```
## Plugin Isolation ## Plugin Isolation

9
docs/docs/20-usage/51-plugins/20-sample-plugin.md
View File

@ -10,10 +10,11 @@ The below example demonstrates how we might configure a webhook plugin in the Ya
pipeline: pipeline:
webhook: webhook:
image: foo/webhook image: foo/webhook
url: http://foo.com settings:
method: post url: http://foo.com
body: | method: post
hello world body: |
hello world
``` ```
## Write the logic ## Write the logic

4
docs/docs/20-usage/71-project-settings.md
View File

@ -1,6 +1,6 @@
# Project settings # Project settings
As the owner of a project in Woodpecker you can change some project related settings via the Webinterface. As the owner of a project in Woodpecker you can change project related settings via the web interface.
![project settings](./project-settings.png) ![project settings](./project-settings.png)
@ -10,7 +10,7 @@ The path to the pipeline config file or folder. By default it is left empty whic
## Repository hooks ## Repository hooks
Your Version-Control-System will notify Woodpecker about some events via webhooks. If you want your pipeline to only run on specific webhooks, you can check them by this setting. Your Version-Control-System will notify Woodpecker about events via webhooks. If you want your pipeline to only run on specific webhooks, you can check them with this setting.
## Project settings ## Project settings

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

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 32 KiB

After

Width:  |  Height:  |  Size: 25 KiB

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

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 128 KiB

After

Width:  |  Height:  |  Size: 21 KiB

BIN
docs/docs/30-administration/20-vcs/github_oauth.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 154 KiB

After

Width:  |  Height:  |  Size: 25 KiB

12
docs/docs/91-migrations.md
View File

@ -51,7 +51,17 @@ Some versions need some changes to the server configuration or the pipeline conf
- `/var/lib/drone/drone.sqlite` -> `/var/lib/woodpecker/woodpecker.sqlite` - `/var/lib/drone/drone.sqlite` -> `/var/lib/woodpecker/woodpecker.sqlite`
- `drone.sqlite` -> `woodpecker.sqlite` - `drone.sqlite` -> `woodpecker.sqlite`
- ... - Plugin Settings moved into `settings` section:
```diff
pipline:
something:
image: my/plugin
- setting1: foo
- setting2: bar
+ settings:
+ setting1: foo
+ setting2: bar
```
## 0.14.0 ## 0.14.0