Bitbucket Pipeline Runner

Tool to run Bitbucket Pipelines locally.

Installation

The prefered way of installing pipeline-runner is with pipx

pipx install bitbucket-pipeline-runner

Basic usage

To run a pipeline

cd <project-directory>
pipeline-runner run <pipeline-name>

To list available pipelines

cd <project-directory>
pipeline-runner list

Environment variables

bitbucket pipeline runner already sets all BITBUCKET_* environment variables in the step's run environment. It will also source any .env file in the current directory, for all project specific environment variables.

Artifacts and logs

Persistent data like artifacts generated from your pipelines and execution logs can be found in your user's data directory.

On Linux:

${XDG_DATA_HOME:-~/.local/share}/pipeline-runner

On macOS:

~/Library/Application Support/pipeline-runner

Caches

Caches defined in your pipelines are stored in your user's cache directory. Unlike Bitbucket Pipelines, caches are always saved even if they already exists. This is subject to change in the future, to follow the behaviour of Bitbucket Pipelines.

On Linux:

${XDG_CACHE_HOME:-~/.cache}/pipeline-runner

On macOS:

~/Library/Caches/pipeline-runner

Note: Docker cache is stored in a docker volume instead.

SSH Agent Forwarding

Warning

SSH Agent forwarding is not available for Docker Desktop on Windows
See: https://docs.docker.com/desktop/features/networking/#ssh-agent-forwarding

You can expose your ssh-agent to the container running the pipelines. This is useful if the pipeline needs to clone from a private repository, for example. To do so, run the pipeline with the --ssh flag:

pipeline-runner run --ssh <pipeline-name>

Note

Any personal git and/or ssh configuration won't be available inside the container running the pipeline. If you have more than one ssh key linked to an account on the target git hosting, ensure that the one you need to use is the first one in the agent.

Alternate Platform

To force a different plaform for the pipeline container, you can set the following environment variable:

# Replace linux/amd64 by the target platform
export PIPELINE_RUNNER_DOCKER_PLATFORM=linux/amd64

Note that this affects only the pipeline container, ie. the one that runs your script. It will not affect the services requested by the pipeline.

If you are running on Apple Silicon, you can force docker to run all containers on a different platform:

export DOCKER_DEFAULT_PLATFORM=linux/amd64

Warning

This feature is still experimental

Debugging

A few features are available to help with debugging.

Breakpoints

Breakpoints, or pauses, can be added during the execution of a pipeline. To do so, add a # pipeline-runner[breakpoint] entry in script:

    example_with_breakpoint:
      - step:
          name: Step with breakpoint
          script:
            - echo "do something"
            - '# pipeline-runner[breakpoint]'
            - echo "do something else"

The execution will stop at the breakpoint to allow the user to check the state of the pipeline. Note that the entry must be put in quotes to avoid it being interpreted as a yaml comment.

CPU Limits Enforcing

By default, no cpu limits are enforced, meaning that the pipeline will run as fast as it can. You can mimick the cpu limits enforced by Bitbucket Pipelines with the --cpu-limits. This is useful to replicate more closely the speed at which a pipeline runs in the real thing.

Supported features

Most features of Bitbucket Pipelines should work out of the box. If you find something that is not working properly, please open an issue.

Feature	Supported	Note
Variables	✅
Artifacts	✅
Docker Service	✅
Caches	✅
Custom Caches	✅
Private Runner Images	✅
Pipes	✅
Parallel Steps	✅	The steps will run, but in sequence.
OIDC	✅	OIDC Setup