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:
```yaml
pipeline:
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 pipeline steps, `frontend` and `backend`. The names of these steps are completely arbitrary.
## Build Steps
Build steps are steps in your pipeline that execute arbitrary commands inside the specified docker container. The commands are executed using the workspace as the working directory.
```diff
pipeline:
backend:
image: golang
commands:
+ - go build
+ - 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:
```diff
#!/bin/sh
set -e
go build
go test
```
The above shell script is then executed as the docker entrypoint. The below docker command is an (incomplete) example of how the script is executed:
```
docker run --entrypoint=build.sh golang
```
> Please note that only build steps can define commands. You cannot use commands with plugins or services.
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:
You must provide registry credentials on the UI in order to pull private pipeline images defined in your Yaml configuration file.
These credentials are never exposed to your pipeline, which means they cannot be used to push, and are safe to use with pull requests, for example. Pushing to a registry still require setting credentials for the appropriate plugin.
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.
For specific details on configuring access to Google Container Registry, please view the docs [here](https://cloud.google.com/container-registry/docs/advanced-authentication#using_a_json_key_file).
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.
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.
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.
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.
> The step now triggers on master, but also if the target branch of a pull request is `master`. Add an event condition to limit it further to pushes on master only.
Execute a step if the branch is `master` or `develop`:
```diff
when:
branch: [master, develop]
```
Execute a step if the branch starts with `prefix/*`:
```diff
when:
branch: prefix/*
```
Execute a step using custom include and exclude logic:
```diff
when:
branch:
include: [ master, release/* ]
exclude: [ release/1.0.0, release/1.1.* ]
```
Execute a step if the build event is a `tag`:
```diff
when:
event: tag
```
Execute a step if the build event is a `tag` created from the specified branch:
```diff
when:
event: tag
+ branch: master
```
Execute a step for all non-pull request events:
```diff
when:
event: [push, tag, deployment]
```
Execute a step for all build events:
```diff
when:
event: [push, pull_request, tag, deployment]
```
Execute a step if the tag name starts with `release`:
```diff
when:
tag: release*
```
Execute a step when the build status changes:
```diff
when:
status: changed
```
Execute a step when the build is passing or failing:
```diff
when:
status: [ failure, success ]
```
Execute a step for a specific platform:
```diff
when:
platform: linux/amd64
```
Execute a step for a specific platform using wildcards:
```diff
when:
platform: [ linux/*, windows/amd64 ]
```
Execute a step for deployment events matching the target deployment environment:
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:
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.
```
/drone/src/github.com/octocat/hello-world
```
The workspace can be customized using the workspace block in the Yaml file:
```diff
+workspace:
+ base: /go
+ path: src/github.com/octocat/hello-world
pipeline:
build:
image: golang:latest
commands:
- go get
- 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.
```diff
workspace:
+ base: /go
path: src/github.com/octocat/hello-world
pipeline:
deps:
image: golang:latest
commands:
- go get
- go test
build:
image: node:latest
commands:
- go build
```
This would be equivalent to the following docker commands:
```
docker volume create my-named-volume
docker run --volume=my-named-volume:/go golang:latest
docker run --volume=my-named-volume:/go node:latest
```
The path attribute defines the working directory of your build. This is where your code is cloned and will be the default working directory of every step in your build process. The path must be relative and is combined with your base path.
Woodpecker automatically configures a default clone step if not explicitly defined. You can manually configure the clone step in your pipeline for customization:
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.
The status badge displays the status for the latest build to your default branch (e.g. master). You can customize the branch by adding the `branch` query parameter.
Please note status badges do not include pull request results, since the status of a pull request does not provide an accurate representation of your repository state.
