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
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>
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
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 |
1 maintainer
Metadata
1 maintainer
Release files for bitbucket-pipeline-runner 0.6.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| bitbucket_pipeline_runner-0.6.2.tar.gz | 36.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| bitbucket_pipeline_runner-0.6.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 79.4 kB
Release files / bitbucket_pipeline_runner-0.6.2.tar.gz
| Download URL | bitbucket_pipeline_runner-0.6.2.tar.gz |
|---|---|
| Size | 36.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e87eff52f751fdfd0a7b0dd3be67a085d8b4d6eb94ad66f64a6d6db3fb9456a7
|
|
BLAKE2b-256 checksum How to use checksums |
61482f0379c4bf7825b630e5bb2d524c1bbf59892ee23926fcb1b07f26663ba4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 20, 2026.
Transparency logRelease files / bitbucket_pipeline_runner-0.6.2-py3-none-any.whl
| Download URL | bitbucket_pipeline_runner-0.6.2-py3-none-any.whl |
|---|---|
| Size | 42.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e945e4559754f7e5ab7e140c70cdc0ab6ec1f563cf38f04d7e34e002b29c9b0e
|
|
BLAKE2b-256 checksum How to use checksums |
e048bfba5184974188f2679142b7b063fa496b0842c0657ad8c3e3687227e839
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 20, 2026.
Transparency log
