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.
Woodpecker can 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:
```diff
pipeline:
build:
image: golang
commands:
- go build
- go test
+branches: master
```
Example matching multiple target branches:
```diff
pipeline:
build:
image: golang
commands:
- go build
- go test
+branches: [ master, develop ]
```
Example uses glob matching:
```diff
pipeline:
build:
image: golang
commands:
- go build
- go test
+branches: [ master, feature/* ]
```
Example includes branches:
```diff
pipeline:
build:
image: golang
commands:
- go build
- go test
+branches:
+ include: [ master, feature/* ]
```
Example excludes branches:
```diff
pipeline:
build:
image: golang
commands:
- go build
- go test
+branches:
+ exclude: [ develop, feature/* ]
```
### `when`
If required, Woodpecker can be made to skip whole pipelines based on `when`. This could be utilised to ensure compliance that only certain jobs run on certain agents (regional restrictions). Or targeting architectures.
See [when](#step-when---step-conditional-execution) above to understand all the different types of conditions that can be used.
> Note: You may need to set the agent environment settings, as these are not set automatically. See: [agent configuration](/docs/administration/agent-config) for more details.
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.
Because we had our original `when` block underneath the `build` block, if it was run on the `linux/amd64` agent. It would have cloned the repository, and then skipped the build step. Resulting in a Successful build.
Moving the when block to the root level will ensure that the whole pipeline will run be targeted to agents that match all of the conditions.
Every step of your pipeline executes arbitrary commands inside a specified docker container. The defined commands are executed serially.
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.
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).
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:
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.
For more details check the [secrets docs](/docs/usage/secrets/).
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 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.
For more details check the [volumes docs](/docs/usage/volumes/).
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 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.
For more details check the [matrix build docs](/docs/usage/matrix-builds/).
Woodpecker automatically configures a default clone step if not explicitly defined. You can manually configure the clone step in your pipeline for customization:
> 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.