Pipeline steps are defined as a series of shell commands. The commands are executed inside the root directory of your git repository. The root of your git repository, also called the workspace, is shared by all steps in your pipeline.

Example configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

kind: pipeline
type: docker
name: default

steps:
- name: backend
  image: golang
  commands:
  - go build
  - go test

- name: frontend
  image: node
  commands:
  - npm install
  - npm test

Commands

The commands are executed inside the root directory of your git repository. The root of your git repository, also called the workspace, is shared by all steps in your pipeline. This allows file artifacts to persist between steps. NB “commands” overrides the docker entrypoint.

 5
 6
 7
 8
 9
10

steps:
- name: backend
  image: golang
  commands:
  - go build
  - go test

The above commands are converted to a simple shell script. The commands in the above example are roughly converted to the below script:

1
2
3
4
5
6

#!/bin/sh
set -e
set -x

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=backend.sh golang

The container exit code is used to determine whether the step is passing or failing. If a command returns a non-zero exit code, the step is marked as failing. The overall pipeline status is also marked as failing, and remaining pipeline steps are skipped (unless explicitly configured to run on failure).

Environment

The environment section provides the ability to define environment variables scoped to individual pipeline steps.

 5
 6
 7
 8
 9
10
11
12
13

steps:
- name: backend
  image: golang
  environment:
    GOOS: linux
    GOARCH: amd64
  commands:
  - go build
  - go test

Plugins

Plugins are docker containers that encapsulate commands, and can be shared and re-used in your pipeline. Examples of plugins include sending Slack notifications, building and publishing Docker images, and uploading artifacts to S3.

Example Slack plugin:

15
16
17
18

- name: notify
  image: plugins/slack
  settings:
    webhook: https://hooks.slack.com/services/...

The great thing about plugins is they are just Docker containers. This means you can easily encapsulate logic, bundle in a Docker container, and share your plugin with your organization or with the broader community.

Conditions

The when section provides the ability to conditionally limit the execution of steps at runtime. The below example limits step execution by branch, however, you can limit execution by event, reference, status and more.

 5
 6
 7
 8
 9
10
11
12
13

steps:
- name: backend
  image: golang
  commands:
  - go build
  - go test
  when:
    branch:
    - master

Use the status condition to override the default runtime behavior and execute steps even when the pipeline status is failure:

15
16
17
18
19
20
21
22

- name: notify
  image: plugins/slack
  settings:
    webhook: https://hooks.slack.com/services/...
  when:
    status:
    - failure
    - success

See the Conditions article for additional details:

Failure

The failure attribute lets you customize how the system handles failure of an individual step. This can be useful if you want to allow a step to fail without failing the overall pipeline.

 5
 6
 7
 8
 9
10
11

steps:
- name: backend
  image: golang
  failure: ignore
  commands:
  - go build
  - go test

Available options are:

1
2
3
4
5
6

failure: ""
failure: "fail"
failure: "fail-fast"
failure: "fast"
failure: "always"
failure: "ignore"

Detach

The detach attribute lets execute the pipeline step in the background. The runner starts the step, detaches and runs in the background, and immediately proceeds to the next step.

The target use case for this feature is to start a service or daemon, and then execute unit tests against the service in subsequent steps.

 5
 6
 7
 8
 9
10
11
12

steps:
- name: backend
  image: golang
  detach: true
  commands:
  - go build
  - go test
  - go run main.go -http=:3000

Privileged Mode

The privileged attribute runs the container with escalated privileges. This is the equivalent of running a container with the --privileged flag.

 5
 6
 7
 8
 9
10
11
12

steps:
- name: backend
  image: golang
  privileged: true
  commands:
  - go build
  - go test
  - go run main.go -http=:3000