mirrors/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2024-06-07 07:59:36 +00:00
Code Issues Projects Releases Wiki Activity

Pipeline docs

Browse source
This commit is contained in:
Laszlo Fogas 2019-11-15 12:03:15 +01:00
parent 6ec3e2ede2
commit 1846a1bb5b
10 changed files with 748 additions and 792 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

151
docs/docs/environment-variables.md Normal file
View file

@ -0,0 +1,151 @@
# Environment variables
Woodpecker provides the ability to define environment variables scoped to individual build steps. Example pipeline step with custom environment variables:
```diff
pipeline:
build:
image: golang
+ environment:
+ - CGO=0
+ - GOOS=linux
+ - GOARCH=amd64
commands:
- go build
- go test
```
Please note that the environment section is not able to expand environment variables. If you need to expand variables they should be exported in the commands section.
```diff
pipeline:
build:
image: golang
- environment:
- - PATH=$PATH:/go
commands:
+ - export PATH=$PATH:/go
- go build
- go test
```
Please be warned that `${variable}` expressions are subject to pre-processing. If you do not want the pre-processor to evaluate your expression it must be escaped:
```diff
pipeline:
build:
image: golang
commands:
- - export PATH=${PATH}:/go
+ - export PATH=$${PATH}:/go
- go build
- go test
```
## Built-in environment variables
This is the reference list of all environment variables available to your build environment. These are injected into your build and plugins containers, at runtime.
| NAME | DESC |
| ---------------------------- | -------------------------------------- |
| `CI=drone` | environment is drone |
| `DRONE=true` | environment is drone |
| `DRONE_ARCH` | environment architecture (linux/amd64) |
| `DRONE_REPO` | repository full name |
| `DRONE_REPO_OWNER` | repository owner |
| `DRONE_REPO_NAME` | repository name |
| `DRONE_REPO_SCM` | repository scm (git) |
| `DRONE_REPO_LINK` | repository link |
| `DRONE_REPO_AVATAR` | repository avatar |
| `DRONE_REPO_BRANCH` | repository default branch (master) |
| `DRONE_REPO_PRIVATE` | repository is private |
| `DRONE_REPO_TRUSTED` | repository is trusted |
| `DRONE_REMOTE_URL` | repository clone url |
| `DRONE_COMMIT_SHA` | commit sha |
| `DRONE_COMMIT_REF` | commit ref |
| `DRONE_COMMIT_BRANCH` | commit branch |
| `DRONE_COMMIT_LINK` | commit link in remote |
| `DRONE_COMMIT_MESSAGE` | commit message |
| `DRONE_COMMIT_AUTHOR` | commit author username |
| `DRONE_COMMIT_AUTHOR_EMAIL` | commit author email address |
| `DRONE_COMMIT_AUTHOR_AVATAR` | commit author avatar |
| `DRONE_BUILD_NUMBER` | build number |
| `DRONE_BUILD_EVENT` | build event (push, pull_request, tag) |
| `DRONE_BUILD_STATUS` | build status (success, failure) |
| `DRONE_BUILD_LINK` | build result link |
| `DRONE_BUILD_CREATED` | build created unix timestamp |
| `DRONE_BUILD_STARTED` | build started unix timestamp |
| `DRONE_BUILD_FINISHED` | build finished unix timestamp |
| `DRONE_PREV_BUILD_STATUS` | prior build status |
| `DRONE_PREV_BUILD_NUMBER` | prior build number |
| `DRONE_PREV_COMMIT_SHA` | prior build commit sha |
| `DRONE_JOB_NUMBER` | job number |
| `DRONE_JOB_STATUS` | job status |
| `DRONE_JOB_STARTED` | job started |
| `DRONE_JOB_FINISHED` | job finished |
| `DRONE_BRANCH` | commit branch |
| `DRONE_TARGET_BRANCH` | The target branch of a Pull Request |
| `DRONE_SOURCE_BRANCH` | The source branch of a Pull Request |
| `DRONE_COMMIT` | commit sha |
| `DRONE_TAG` | commit tag |
| `DRONE_PULL_REQUEST` | pull request number |
| `DRONE_DEPLOY_TO` | deployment target (ie production) |
## String Substitution
Woodpecker provides the ability to substitute environment variables at runtime. This gives us the ability to use dynamic build or commit details in our pipeline configuration.
Example commit substitution:
```diff
pipeline:
docker:
image: plugins/docker
+ tags: ${DRONE_COMMIT_SHA}
```
Example tag substitution:
```diff
pipeline:
docker:
image: plugins/docker
+ tags: ${DRONE_TAG}
```
## String Operations
Woodpecker also emulates bash string operations. This gives us the ability to manipulate the strings prior to substitution. Example use cases might include substring and stripping prefix or suffix values.
| OPERATION | DESC |
| ------------------ | ------------------------------------------------ |
| `${param}` | parameter substitution |
| `${param,}` | parameter substitution with lowercase first char |
| `${param,,}` | parameter substitution with lowercase |
| `${param^}` | parameter substitution with uppercase first char |
| `${param^^}` | parameter substitution with uppercase |
| `${param:pos}` | parameter substitution with substring |
| `${param:pos:len}` | parameter substitution with substring and length |
| `${param=default}` | parameter substitution with default |
| `${param##prefix}` | parameter substitution with prefix removal |
| `${param%%suffix}` | parameter substitution with suffix removal |
| `${param/old/new}` | parameter substitution with find and replace |
Example variable substitution with substring:
```diff
pipeline:
docker:
image: plugins/docker
+ tags: ${DRONE_COMMIT_SHA:0:8}
```
Example variable substitution strips `v` prefix from `v.1.0.0`:
```diff
pipeline:
docker:
image: plugins/docker
+ tags: ${DRONE_TAG##v}
```

72
docs/docs/getting-started.md Normal file
View file

@ -0,0 +1,72 @@
# 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 version control system (e.g. GitHub).
Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your version control system will automatically send a webhook to Woodpecker which will in turn trigger pipeline execution.
![repository list](/images/repo_list.png)
> Required Permissions
>
>The user who enables a repo in Woodpecker must have `Admin` rights on that repo, so that Woodpecker can add the webhook.
>
> Note that manually creating webhooks yourself is not possible. This is because webhooks are signed using a per-repository secret key which is not exposed to end users.
# Webhooks
When you activate your repository Woodpecker automatically add webhooks to your version control system (e.g. GitHub). There is no manual configuration required.
Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your version control system will automatically send a webhook to Woodpecker which will in turn trigger pipeline execution.
## Configuration
To configure you pipeline you should place a `.drone.yml` file in the root of your repository. The .drone.yml file is used to define your pipeline steps. It is a superset of the widely used docker-compose file format.
Example pipeline configuration:
```yaml
pipeline:
build:
image: golang
commands:
- go get
- go build
- go test
services:
postgres:
image: postgres:9.4.5
environment:
- POSTGRES_USER=myapp
```
Example pipeline configuration with multiple, serial steps:
```yaml
pipeline:
backend:
image: golang
commands:
- go get
- go build
- go test
frontend:
image: node:6
commands:
- npm install
- npm test
notify:
image: plugins/slack
channel: developers
username: drone
```
## 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 version control system and execute your pipeline.

113
docs/docs/matrix-builds.md Normal file
View file

@ -0,0 +1,113 @@
# Matrix builds
Woodpecker has integrated support for matrix builds. Woodpecker executes a separate build task for each combination in the matrix, allowing you to build and test a single commit against multiple configurations.
Example matrix definition:
```yaml
matrix:
GO_VERSION:
- 1.4
- 1.3
REDIS_VERSION:
- 2.6
- 2.8
- 3.0
```
Example matrix definition containing only specific combinations:
```yaml
matrix:
include:
- GO_VERSION: 1.4
REDIS_VERSION: 2.8
- GO_VERSION: 1.5
REDIS_VERSION: 2.8
- GO_VERSION: 1.6
REDIS_VERSION: 3.0
```
## Interpolation
Matrix variables are interpolated in the yaml using the `${VARIABLE}` syntax, before the yaml is parsed. This is an example yaml file before interpolating matrix parameters:
```yaml
pipeline:
build:
image: golang:${GO_VERSION}
commands:
- go get
- go build
- go test
services:
database:
image: ${DATABASE}
matrix:
GO_VERSION:
- 1.4
- 1.3
DATABASE:
- mysql:5.5
- mysql:6.5
- mariadb:10.1
```
Example Yaml file after injecting the matrix parameters:
```diff
pipeline:
build:
- image: golang:${GO_VERSION}
+ image: golang:1.4
commands:
- go get
- go build
- go test
+ environment:
+ - GO_VERSION=1.4
+ - DATABASE=mysql:5.5
services:
database:
- image: ${DATABASE}
+ image: mysql:5.5
```
## Examples
Example matrix build based on Docker image tag:
```yaml
pipeline:
build:
image: golang:${TAG}
commands:
- go build
- go test
matrix:
TAG:
- 1.7
- 1.8
- latest
```
Example matrix build based on Docker image:
```yaml
pipeline:
build:
image: ${IMAGE}
commands:
- go build
- go test
matrix:
IMAGE:
- golang:1.7
- golang:1.8
- golang:latest
```

129
docs/docs/multi-pipeline.md Normal file
View file

@ -0,0 +1,129 @@
# Multi-pipeline builds
By default, Woodpecker looks for the pipeline definition in `.drone.yml` in the project root.
The Multi-Pipeline feature allows the pipeline to be splitted to several files and placed in the `.drone/` folder
## Rational
- faster lint/test feedback, the pipeline doesn't have to run fully to have a lint status pushed to the the remote
- better organization of the pipeline along various concerns: testing, linting, feature apps
- utilizaing more agents to speed up build
## Example multi-pipeline definition
```bash
.drone
├── .build.yml
├── .deploy.yml
├── .lint.yml
└── .test.yml
```
.drone/.build.yml
```yaml
pipeline:
build:
image: debian:stable-slim
commands:
- echo building
- sleep 5
```
.drone/.deploy.yml
```yaml
pipeline:
deploy:
image: debian:stable-slim
commands:
- echo deploying
depends_on:
- lint
- build
- test
```
.drone/.test.yml
```yaml
pipeline:
test:
image: debian:stable-slim
commands:
- echo testing
- sleep 5
depends_on:
- build
```
.drone/.lint.yml
```yaml
pipeline:
lint:
image: debian:stable-slim
commands:
- echo linting
- sleep 5
```
## Status lines
Each pipeline has its own status line on Github.
## Flow control
The pipelines run in parallel on a separate agents and share nothing.
Dependencies between pipelines can be set with the `depends_on` element. A pipeline doesn't execute until its dependencies did not complete succesfully.
```diff
pipeline:
deploy:
image: debian:stable-slim
commands:
- echo deploying
+depends_on:
+ - lint
+ - build
+ - test
```
Pipelines that need to run even on failures should set the `run_on` tag.
```diff
pipeline:
notify:
image: debian:stable-slim
commands:
- echo notifying
depends_on:
- deploy
+run_on: [ success, failure ]
```
Some pipelines don't need the source code, set the `skip_clone` tag to skip cloning:
```diff
pipeline:
notify:
image: debian:stable-slim
commands:
- echo notifying
depends_on:
- deploy
run_on: [ success, failure ]
+skip_clone: true
```

809
docs/docs/pipeline.md
View file

@ -1,64 +1,5 @@
# Pipelines
## 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, Drone automatically adds webhooks to your version control system (e.g. GitHub).
Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your version control system will automatically send a webhook to Drone which will in turn trigger pipeline execution.
![repository list](`/images/repo_list.png)
## Configuration
To configure you pipeline you should place a `.drone.yml` file in the root of your repository. The .drone.yml file is used to define your pipeline steps. It is a superset of the widely used docker-compose file format.
Example pipeline configuration:
```yaml
pipeline:
build:
image: golang
commands:
- go get
- go build
- go test
services:
postgres:
image: postgres:9.4.5
environment:
- POSTGRES_USER=myapp
```
Example pipeline configuration with multiple, serial steps:
```yaml
pipeline:
backend:
image: golang
commands:
- go get
- go build
- go test
frontend:
image: node:6
commands:
- npm install
- npm test
notify:
image: plugins/slack
channel: developers
username: drone
```
## 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 version control system and execute your pipeline.
# Pipelines
The pipeline section defines a list of steps to build, test and deploy your code. Pipeline steps are executed serially, in the order in which they are defined. If a step returns a non-zero exit code, the pipeline immediately aborts and returns a failure status.
Example pipeline:
@ -113,7 +54,7 @@ docker run --entrypoint=build.sh golang
## Images
Drone 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
pipeline:
@ -132,7 +73,7 @@ services:
+ image: mysql
```
Drone supports any valid Docker image from any Docker registry:
Woodpecker supports any valid Docker image from any Docker registry:
```text
image: golang
@ -142,7 +83,7 @@ image: index.docker.io/library/golang
image: index.docker.io/library/golang:1.7
```
Drone 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
pipeline:
@ -168,7 +109,7 @@ pipeline:
- go test
```
Drone 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 Drone agent and are never exposed to your build containers.
Woodpecker matches the registry hostname to each image in your yaml. If the hostnames match, the registry credentials are used to authenticate to your registry and pull the image. Note that registry credentials are used by the Woodpecker agent and are never exposed to your build containers.
Example registry hostnames:
@ -190,7 +131,7 @@ For specific details on configuring access to Google Container Registry, please
## Parallel Execution
Drone supports parallel step execution for same-machine fan-in and fan-out. Parallel steps are configured using the `group` attribute. This instructs the pipeline runner to execute the named group in parallel.
Woodpecker supports parallel step execution for same-machine fan-in and fan-out. Parallel steps are configured using the `group` attribute. This instructs the pipeline runner to execute the named group in parallel.
Example parallel configuration:
@ -218,7 +159,7 @@ In the above example, the `frontend` and `backend` steps are executed in paralle
## Conditional Pipeline Execution
Drone supports defining conditional pipelines to skip commits based on the target branch. If the branch matches the `branches:` block the pipeline is executed, otherwise it is skipped.
Woodpecker supports defining conditional pipelines to skip commits based on the target branch. If the branch matches the `branches:` block the pipeline is executed, otherwise it is skipped.
Example skipping a commit when the target branch is not master:
@ -289,7 +230,7 @@ pipeline:
## Conditional Step Execution
Drone supports defining conditional pipeline steps in the `when` block. If all conditions in the `when` block evaluate to true the step is executed, otherwise it is skipped.
Woodpecker supports defining conditional pipeline steps in the `when` block. If all conditions in the `when` block evaluate to true the step is executed, otherwise it is skipped.
Example conditional execution by branch:
@ -408,7 +349,7 @@ when:
REDIS_VERSION: 2.8
```
Execute a step only on a certain Drone instance:
Execute a step only on a certain Woodpecker instance:
```diff
when:
@ -417,7 +358,7 @@ when:
#### Failure Execution
Drone uses the container exit code to determine the success or failure status of a build. Non-zero exit codes fail the build and cause the pipeline to immediately exit.
Woodpecker uses the container exit code to determine the success or failure status of a build. Non-zero exit codes fail the build and cause the pipeline to immediately exit.
There are use cases for executing pipeline steps on failure, such as sending notifications for failed builds. Use the status constraint to override the default behavior and execute steps even when the build status is failure:
@ -430,430 +371,9 @@ pipeline:
+ status: [ success, failure ]
```
# Services
Drone provides a services section in the Yaml file used for defining service containers. The below configuration composes database and cache containers.
```diff
pipeline:
build:
image: golang
commands:
- go build
- go test
services:
database:
image: mysql
cache:
image: redis
```
Services are accessed using custom hostnames. In the above example the mysql service is assigned the hostname `database` and is available at `database:3306`.
## Configuration
Service containers generally expose environment variables to customize service startup such as default usernames, passwords and ports. Please see the official image documentation to learn more.
```diff
services:
database:
image: mysql
+ environment:
+ - MYSQL_DATABASE=test
+ - MYSQL_ALLOW_EMPTY_PASSWORD=yes
cache:
image: redis
```
## Detachment
Service and long running containers can also be included in the pipeline section of the configuration using the detach parameter without blocking other steps. This should be used when explicit control over startup order is required.
```diff
pipeline:
build:
image: golang
commands:
- go build
- go test
database:
image: redis
+ detach: true
test:
image: golang
commands:
- go test
```
Containers from detached steps will terminate when the pipeline ends.
## Initialization
Service containers require time to initialize and begin to accept connections. If you are unable to connect to a service you may need to wait a few seconds or implement a backoff.
```diff
pipeline:
test:
image: golang
commands:
+ - sleep 15
- go get
- go test
services:
database:
image: mysql
```
# Plugins
Plugins are Docker containers 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.
Example pipeline using the Docker and Slack plugins:
```yaml
pipeline:
build:
image: golang
commands:
- go build
- go test
publish:
image: plugins/docker
repo: foo/bar
tags: latest
notify:
image: plugins/slack
channel: dev
```
## Plugin Isolation
Plugins are executed in Docker containers and are isolated from the other steps in your build pipeline. Plugins do share the build workspace, mounted as a volume, and therefore have access to your source tree.
## Plugin Marketplace
Plugins are packaged and distributed as Docker containers. They are conceptually similar to software libraries (think npm) and can be published and shared with the community. You can find a list of available plugins at [http://plugins.drone.io](http://plugins.drone.io).
# Environment variables
Drone provides the ability to define environment variables scoped to individual build steps. Example pipeline step with custom environment variables:
```diff
pipeline:
build:
image: golang
+ environment:
+ - CGO=0
+ - GOOS=linux
+ - GOARCH=amd64
commands:
- go build
- go test
```
Please note that the environment section is not able to expand environment variables. If you need to expand variables they should be exported in the commands section.
```diff
pipeline:
build:
image: golang
- environment:
- - PATH=$PATH:/go
commands:
+ - export PATH=$PATH:/go
- go build
- go test
```
Please be warned that `${variable}` expressions are subject to pre-processing. If you do not want the pre-processor to evaluate your expression it must be escaped:
```diff
pipeline:
build:
image: golang
commands:
- - export PATH=${PATH}:/go
+ - export PATH=$${PATH}:/go
- go build
- go test
```
## Built-in environment variables
This is the reference list of all environment variables available to your build environment. These are injected into your build and plugins containers, at runtime.
| NAME | DESC |
| ---------------------------- | -------------------------------------- |
| `CI=drone` | environment is drone |
| `DRONE=true` | environment is drone |
| `DRONE_ARCH` | environment architecture (linux/amd64) |
| `DRONE_REPO` | repository full name |
| `DRONE_REPO_OWNER` | repository owner |
| `DRONE_REPO_NAME` | repository name |
| `DRONE_REPO_SCM` | repository scm (git) |
| `DRONE_REPO_LINK` | repository link |
| `DRONE_REPO_AVATAR` | repository avatar |
| `DRONE_REPO_BRANCH` | repository default branch (master) |
| `DRONE_REPO_PRIVATE` | repository is private |
| `DRONE_REPO_TRUSTED` | repository is trusted |
| `DRONE_REMOTE_URL` | repository clone url |
| `DRONE_COMMIT_SHA` | commit sha |
| `DRONE_COMMIT_REF` | commit ref |
| `DRONE_COMMIT_BRANCH` | commit branch |
| `DRONE_COMMIT_LINK` | commit link in remote |
| `DRONE_COMMIT_MESSAGE` | commit message |
| `DRONE_COMMIT_AUTHOR` | commit author username |
| `DRONE_COMMIT_AUTHOR_EMAIL` | commit author email address |
| `DRONE_COMMIT_AUTHOR_AVATAR` | commit author avatar |
| `DRONE_BUILD_NUMBER` | build number |
| `DRONE_BUILD_EVENT` | build event (push, pull_request, tag) |
| `DRONE_BUILD_STATUS` | build status (success, failure) |
| `DRONE_BUILD_LINK` | build result link |
| `DRONE_BUILD_CREATED` | build created unix timestamp |
| `DRONE_BUILD_STARTED` | build started unix timestamp |
| `DRONE_BUILD_FINISHED` | build finished unix timestamp |
| `DRONE_PREV_BUILD_STATUS` | prior build status |
| `DRONE_PREV_BUILD_NUMBER` | prior build number |
| `DRONE_PREV_COMMIT_SHA` | prior build commit sha |
| `DRONE_JOB_NUMBER` | job number |
| `DRONE_JOB_STATUS` | job status |
| `DRONE_JOB_STARTED` | job started |
| `DRONE_JOB_FINISHED` | job finished |
| `DRONE_BRANCH` | commit branch |
| `DRONE_TARGET_BRANCH` | The target branch of a Pull Request |
| `DRONE_SOURCE_BRANCH` | The source branch of a Pull Request |
| `DRONE_COMMIT` | commit sha |
| `DRONE_TAG` | commit tag |
| `DRONE_PULL_REQUEST` | pull request number |
| `DRONE_DEPLOY_TO` | deployment target (ie production) |
## String Substitution
Drone provides the ability to substitute environment variables at runtime. This gives us the ability to use dynamic build or commit details in our pipeline configuration.
Example commit substitution:
```diff
pipeline:
docker:
image: plugins/docker
+ tags: ${DRONE_COMMIT_SHA}
```
Example tag substitution:
```diff
pipeline:
docker:
image: plugins/docker
+ tags: ${DRONE_TAG}
```
## String Operations
Drone also emulates bash string operations. This gives us the ability to manipulate the strings prior to substitution. Example use cases might include substring and stripping prefix or suffix values.
| OPERATION | DESC |
| ------------------ | ------------------------------------------------ |
| `${param}` | parameter substitution |
| `${param,}` | parameter substitution with lowercase first char |
| `${param,,}` | parameter substitution with lowercase |
| `${param^}` | parameter substitution with uppercase first char |
| `${param^^}` | parameter substitution with uppercase |
| `${param:pos}` | parameter substitution with substring |
| `${param:pos:len}` | parameter substitution with substring and length |
| `${param=default}` | parameter substitution with default |
| `${param##prefix}` | parameter substitution with prefix removal |
| `${param%%suffix}` | parameter substitution with suffix removal |
| `${param/old/new}` | parameter substitution with find and replace |
Example variable substitution with substring:
```diff
pipeline:
docker:
image: plugins/docker
+ tags: ${DRONE_COMMIT_SHA:0:8}
```
Example variable substitution strips `v` prefix from `v.1.0.0`:
```diff
pipeline:
docker:
image: plugins/docker
+ tags: ${DRONE_TAG##v}
```
# Secrets
Drone provides the ability to store named parameters external to the Yaml configuration file, in a central secret store. Individual steps in the yaml can request access to these named parameters at runtime.
Secrets are exposed to your pipeline steps and plugins as uppercase environment variables and can therefore be referenced in the commands section of your pipeline.
```diff
pipeline:
docker:
image: docker
commands:
+ - echo $DOCKER_USERNAME
+ - echo $DOCKER_PASSWORD
secrets: [ docker_username, docker_password ]
```
Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped.
```diff
pipeline:
docker:
image: docker
commands:
- - echo ${DOCKER_USERNAME}
- - echo ${DOCKER_PASSWORD}
+ - echo $${DOCKER_USERNAME}
+ - echo $${DOCKER_PASSWORD}
secrets: [ docker_username, docker_password ]
```
## Adding Secrets
Secrets are added to the Drone secret store on the UI or with the CLI.
## Alternate Names
There may be scenarios where you are required to store secrets using alternate names. You can map the alternate secret name to the expected name using the below syntax:
```diff
pipeline:
docker:
image: plugins/docker
repo: octocat/hello-world
tags: latest
+ secrets:
+ - source: docker_prod_password
+ target: docker_password
```
## Pull Requests
Secrets are not exposed to pull requests by default. You can override this behavior by creating the secret and enabling the `pull_request` event type.
```diff
drone secret add \
-repository octocat/hello-world \
-image plugins/docker \
+ -event pull_request \
+ -event push \
+ -event tag \
-name docker_username \
-value <value>
```
Please be careful when exposing secrets to pull requests. If your repository is open source and accepts pull requests your secrets are not safe. A bad actor can submit a malicious pull request that exposes your secrets.
## Examples
Create the secret using default settings. The secret will be available to all images in your pipeline, and will be available to all push, tag, and deployment events (not pull request events).
```diff
drone secret add \
-repository octocat/hello-world \
-name aws_access_key_id \
-value <value>
```
Create the secret and limit to a single image:
```diff
drone 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
drone secret add \
-repository octocat/hello-world \
+ -image plugins/s3 \
+ -image peloton/drone-ecs \
-name aws_access_key_id \
-value <value>
```
Create the secret and enable for multiple hook events:
```diff
drone 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
drone secret add \
-repository octocat/hello-world \
-name ssh_key \
+ -value @/root/ssh/id_rsa
```
# Volumes
Drone gives the ability to define Docker volumes in the Yaml. You can use this parameter to mount files or folders on the host machine into your containers.
> Volumes are only available to trusted repositories and for security reasons should only be used in private environments.
```diff
pipeline:
build:
image: docker
commands:
- docker build --rm -t octocat/hello-world .
- docker run --rm octocat/hello-world --test
- docker push octocat/hello-world
- docker rmi octocat/hello-world
volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
```
Please note that Drone mounts volumes on the host machine. This means you must use absolute paths when you configure volumes. Attempting to use relative paths will result in an error.
```diff
- volumes: [ ./certs:/etc/ssl/certs ]
+ volumes: [ /etc/ssl/certs:/etc/ssl/certs ]
```
# Webhooks
When you activate your repository Drone automatically add webhooks to your version control system (e.g. GitHub). There is no manual configuration required.
Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your version control system will automatically send a webhook to Drone which will in turn trigger pipeline execution.
## Required Permissions
The user who enables a repo in Drone must have `Admin` rights on that repo, so that Drone can add the webhook.
Note that manually creating webhooks yourself is not possible. This is because webhooks are signed using a per-repository secret key which is not exposed to end users.
## Skip Commits
Drone gives the ability to skip individual commits by adding `[CI SKIP]` to the commit message. Note this is case-insensitive.
Woodpecker gives the ability to skip individual commits by adding `[CI SKIP]` to the commit message. Note this is case-insensitive.
```diff
git commit -m "updated README [CI SKIP]"
@ -861,7 +381,7 @@ git commit -m "updated README [CI SKIP]"
## Skip Branches
Drone gives the ability to skip commits based on the target branch. The below example will skip a commit when the target branch is not master.
Woodpecker gives the ability to skip commits based on the target branch. The below example will skip a commit when the target branch is not master.
```diff
pipeline:
@ -876,7 +396,7 @@ pipeline:
Please see the pipeline conditions [documentation]({{< ref "usage/config/pipeline-conditions.md" >}}) for more options and details.
# Workspace
## Workspace
The workspace defines the shared volume and working directory shared by all pipeline steps. The default workspace matches the below pattern, based on your repository url.
@ -940,9 +460,9 @@ git clone https://github.com/octocat/hello-world \
/go/src/github.com/octocat/hello-world
```
# Cloning
## Cloning
Drone automatically configures a default clone step if not explicitly defined. You can manually configure the clone step in your pipeline for customization:
Woodpecker automatically configures a default clone step if not explicitly defined. You can manually configure the clone step in your pipeline for customization:
```diff
+clone:
@ -983,7 +503,7 @@ clone:
+ path: bitbucket.org/foo/bar
```
## Git Submodules
### Git Submodules
To use the credentials that cloned the repository to clone it's submodules, update `.gitmodules` to use `https` instead of `git`:
@ -1008,9 +528,9 @@ pipeline:
...
```
# Privileged mode
## Privileged mode
Drone gives the ability to configure privileged mode in the Yaml. You can use this parameter to launch containers with escalated capabilities.
Woodpecker gives the ability to configure privileged mode in the Yaml. You can use this parameter to launch containers with escalated capabilities.
> Privileged mode is only available to trusted repositories and for security reasons should only be used in private environments.
@ -1030,302 +550,9 @@ services:
+ privileged: true
```
# Promoting
Drone provides the ability to promote individual commits or tags (e.g. promote to production). When you promote a commit or tag it triggers a new pipeline execution with event type `deployment`. You can use the event type and target environment to limit step execution.
```diff
pipeline:
build:
image: golang
commands:
- go build
- go test
publish:
image: plugins/docker
registry: registry.heroku.com
repo: registry.heroku.com/my-staging-app/web
when:
+ event: deployment
+ environment: staging
publish_to_prod:
image: plugins/docker
registry: registry.heroku.com
repo: registry.heroku.com/my-production-app/web
when:
+ event: deployment
+ environment: production
```
The above example demonstrates how we can configure pipeline steps to only execute when the deployment matches a specific target environment.
## Triggering Deployments
Deployments are triggered from the command line utility. They are triggered from an existing build. This is conceptually similar to promoting builds.
```text
drone deploy <repo> <build> <environment>
```
Promote the specified build number to your staging environment:
```text
drone deploy octocat/hello-world 24 staging
```
Promote the specified build number to your production environment:
```text
drone deploy octocat/hello-world 24 production
```
# Matrix builds
Drone has integrated support for matrix builds. Drone executes a separate build task for each combination in the matrix, allowing you to build and test a single commit against multiple configurations.
Example matrix definition:
```yaml
matrix:
GO_VERSION:
- 1.4
- 1.3
REDIS_VERSION:
- 2.6
- 2.8
- 3.0
```
Example matrix definition containing only specific combinations:
```yaml
matrix:
include:
- GO_VERSION: 1.4
REDIS_VERSION: 2.8
- GO_VERSION: 1.5
REDIS_VERSION: 2.8
- GO_VERSION: 1.6
REDIS_VERSION: 3.0
```
## Interpolation
Matrix variables are interpolated in the yaml using the `${VARIABLE}` syntax, before the yaml is parsed. This is an example yaml file before interpolating matrix parameters:
```yaml
pipeline:
build:
image: golang:${GO_VERSION}
commands:
- go get
- go build
- go test
services:
database:
image: ${DATABASE}
matrix:
GO_VERSION:
- 1.4
- 1.3
DATABASE:
- mysql:5.5
- mysql:6.5
- mariadb:10.1
```
Example Yaml file after injecting the matrix parameters:
```diff
pipeline:
build:
- image: golang:${GO_VERSION}
+ image: golang:1.4
commands:
- go get
- go build
- go test
+ environment:
+ - GO_VERSION=1.4
+ - DATABASE=mysql:5.5
services:
database:
- image: ${DATABASE}
+ image: mysql:5.5
```
## Examples
Example matrix build based on Docker image tag:
```yaml
pipeline:
build:
image: golang:${TAG}
commands:
- go build
- go test
matrix:
TAG:
- 1.7
- 1.8
- latest
```
Example matrix build based on Docker image:
```yaml
pipeline:
build:
image: ${IMAGE}
commands:
- go build
- go test
matrix:
IMAGE:
- golang:1.7
- golang:1.8
- golang:latest
```
# Multi-pipeline builds
By default, Drone looks for the pipeline definition in `.drone.yml` in the project root.
The Multi-Pipeline feature allows the pipeline to be splitted to several files and placed in the `.drone/` folder
## Example multi-pipeline definition
```bash
.drone
├── .build.yml
├── .deploy.yml
├── .lint.yml
└── .test.yml
```
.drone/.build.yml
```yaml
pipeline:
build:
image: debian:stable-slim
commands:
- echo building
- sleep 5
```
.drone/.deploy.yml
```yaml
pipeline:
deploy:
image: debian:stable-slim
commands:
- echo deploying
depends_on:
- lint
- build
- test
```
.drone/.test.yml
```yaml
pipeline:
test:
image: debian:stable-slim
commands:
- echo testing
- sleep 5
depends_on:
- build
```
.drone/.lint.yml
```yaml
pipeline:
lint:
image: debian:stable-slim
commands:
- echo linting
- sleep 5
```
## Flow control
The pipelines run in parallel on a separate agents and share nothing.
Dependencies between pipelines can be set with the `depends_on` element. A pipeline doesn't execute until its dependencies did not complete succesfully.
```diff
pipeline:
deploy:
image: debian:stable-slim
commands:
- echo deploying
+depends_on:
+ - lint
+ - build
+ - test
```
Pipelines that need to run even on failures should set the `run_on` tag.
```diff
pipeline:
notify:
image: debian:stable-slim
commands:
- echo notifying
depends_on:
- deploy
+run_on: [ success, failure ]
```
Some pipelines don't need the source code, set the `skip_clone` tag to skip cloning:
```diff
pipeline:
notify:
image: debian:stable-slim
commands:
- echo notifying
depends_on:
- deploy
run_on: [ success, failure ]
+skip_clone: true
```
## Status lines
Each pipeline has its own status line on Github.
## Rational
- faster lint/test feedback, the pipeline doesn't have to run fully to have a lint status pushed to the the remote
- better organization of the pipeline along various concerns: testing, linting, feature apps
- utilizaing more agents to speed up build
# Badges
Drone has integrated support for repository status badges. These badges can be added to your website or project readme file to display the status of your code.
Woodpecker has integrated support for repository status badges. These badges can be added to your website or project readme file to display the status of your code.
Badge endpoint:

31
docs/docs/plugins.md Normal file
View file

@ -0,0 +1,31 @@
# Plugins
Plugins are Docker containers 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.
Example pipeline using the Docker and Slack plugins:
```yaml
pipeline:
build:
image: golang
commands:
- go build
- go test
publish:
image: plugins/docker
repo: foo/bar
tags: latest
notify:
image: plugins/slack
channel: dev
```
## Plugin Isolation
Plugins are executed in Docker containers and are isolated from the other steps in your build pipeline. Plugins do share the build workspace, mounted as a volume, and therefore have access to your source tree.
## Creating a plugin
See a [detailed plugin example](/usage/bash-plugin).

120
docs/docs/secrets.md Normal file
View file

@ -0,0 +1,120 @@
# Secrets
Woodpecker provides the ability to store named parameters external to the Yaml configuration file, in a central secret store. Individual steps in the yaml can request access to these named parameters at runtime.
Secrets are exposed to your pipeline steps and plugins as uppercase environment variables and can therefore be referenced in the commands section of your pipeline.
```diff
pipeline:
docker:
image: docker
commands:
+ - echo $DOCKER_USERNAME
+ - echo $DOCKER_PASSWORD
secrets: [ docker_username, docker_password ]
```
Please note parameter expressions are subject to pre-processing. When using secrets in parameter expressions they should be escaped.
```diff
pipeline:
docker:
image: docker
commands:
- - echo ${DOCKER_USERNAME}
- - echo ${DOCKER_PASSWORD}
+ - echo $${DOCKER_USERNAME}
+ - echo $${DOCKER_PASSWORD}
secrets: [ docker_username, docker_password ]
```
## Adding Secrets
Secrets are added to the Woodpecker secret store on the UI or with the CLI.
## Alternate Names
There may be scenarios where you are required to store secrets using alternate names. You can map the alternate secret name to the expected name using the below syntax:
```diff
pipeline:
docker:
image: plugins/docker
repo: octocat/hello-world
tags: latest
+ secrets:
+ - source: docker_prod_password
+ target: docker_password
```
## Pull Requests
Secrets are not exposed to pull requests by default. You can override this behavior by creating the secret and enabling the `pull_request` event type.
```diff
drone secret add \
-repository octocat/hello-world \
-image plugins/docker \
+ -event pull_request \
+ -event push \
+ -event tag \
-name docker_username \
-value <value>
```
Please be careful when exposing secrets to pull requests. If your repository is open source and accepts pull requests your secrets are not safe. A bad actor can submit a malicious pull request that exposes your secrets.
## Examples
Create the secret using default settings. The secret will be available to all images in your pipeline, and will be available to all push, tag, and deployment events (not pull request events).
```diff
drone secret add \
-repository octocat/hello-world \
-name aws_access_key_id \
-value <value>
```
Create the secret and limit to a single image:
```diff
drone 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
drone secret add \
-repository octocat/hello-world \
+ -image plugins/s3 \
+ -image peloton/drone-ecs \
-name aws_access_key_id \
-value <value>
```
Create the secret and enable for multiple hook events:
```diff
drone 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
drone secret add \
-repository octocat/hello-world \
-name ssh_key \
+ -value @/root/ssh/id_rsa
```

80
docs/docs/services.md Normal file
View file

@ -0,0 +1,80 @@
# Services
Woodpecker provides a services section in the Yaml file used for defining service containers. The below configuration composes database and cache containers.
```diff
pipeline:
build:
image: golang
commands:
- go build
- go test
services:
database:
image: mysql
cache:
image: redis
```
Services are accessed using custom hostnames. In the above example the mysql service is assigned the hostname `database` and is available at `database:3306`.
## Configuration
Service containers generally expose environment variables to customize service startup such as default usernames, passwords and ports. Please see the official image documentation to learn more.
```diff
services:
database:
image: mysql
+ environment:
+ - MYSQL_DATABASE=test
+ - MYSQL_ALLOW_EMPTY_PASSWORD=yes
cache:
image: redis
```
## Detachment
Service and long running containers can also be included in the pipeline section of the configuration using the detach parameter without blocking other steps. This should be used when explicit control over startup order is required.
```diff
pipeline:
build:
image: golang
commands:
- go build
- go test
database:
image: redis
+ detach: true
test:
image: golang
commands:
- go test
```
Containers from detached steps will terminate when the pipeline ends.
## Initialization
Service containers require time to initialize and begin to accept connections. If you are unable to connect to a service you may need to wait a few seconds or implement a backoff.
```diff
pipeline:
test:
image: golang
commands:
+ - sleep 15
- go get
- go test
services:
database:
image: mysql
```

25
docs/docs/volumes.md Normal file
View file

@ -0,0 +1,25 @@
# Volumes
Woodpecker gives the ability to define Docker volumes in the Yaml. You can use this parameter to mount files or folders on the host machine into your containers.
> Volumes are only available to trusted repositories and for security reasons should only be used in private environments.
```diff
pipeline:
build:
image: docker
commands:
- docker build --rm -t octocat/hello-world .
- docker run --rm octocat/hello-world --test
- docker push octocat/hello-world
- docker rmi octocat/hello-world
volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
```
Please note that Woodpecker mounts volumes on the host machine. This means you must use absolute paths when you configure volumes. Attempting to use relative paths will result in an error.
```diff
- volumes: [ ./certs:/etc/ssl/certs ]
+ volumes: [ /etc/ssl/certs:/etc/ssl/certs ]
```

10
docs/mkdocs.yml
View file

@ -4,8 +4,16 @@ repo_url: 'https://github.com/laszlocph/woodpecker'
copyright: 'Creative Commons Attribution-ShareAlike 4.0 International Public License.<br />It is a derivative work of the https://github.com/drone/docs git repository'
nav:
- Home: index.md
- Server setup: server-setup.md
- Server Setup: server-setup.md
- Getting Started: getting-started.md
- Pipelines: pipeline.md
- Services: services.md
- Plugins: plugins.md
- Environment Variables: environment-variables.md
- Secrets: secrets.md
- Volumes: volumes.md
- Matrix Builds: matrix-builds.md
- Multi Pipeline Builds: multi-pipeline.md
theme:
name: 'material'
logo: 'images/favicon.svg'