Metadata-Version: 2.1
Name: bitbucket-pipeline-runner
Version: 0.4.9a0
Summary: Run a bitbucket pipeline locally
Home-page: https://github.com/mathieu-lemay/pipeline-runner
License: MIT
Author: Mathieu Lemay
Author-email: acidrain1@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: GitPython (>=3.1.12,<4.0.0)
Requires-Dist: PyYAML (>=6.0,<7.0)
Requires-Dist: boto3 (>=1.34.64,<2.0.0)
Requires-Dist: click (>=8.0.1,<9.0.0)
Requires-Dist: coloredlogs (>=15.0,<16.0)
Requires-Dist: cryptography (>=43.0.0,<44.0.0)
Requires-Dist: docker (>=7.0.0,<8.0.0)
Requires-Dist: platformdirs (>=4.3.6,<5.0.0)
Requires-Dist: pydantic (>=2.0,<3.0)
Requires-Dist: pydantic-settings (>=2.0.3,<3.0.0)
Requires-Dist: pyfzf (>=0.3.0,<0.4.0)
Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
Requires-Dist: python-slugify (>=8.0.0,<9.0.0)
Requires-Dist: requests (>=2.31.0,<3.0.0)
Requires-Dist: tenacity (>=9.0.0,<10.0.0)
Project-URL: Repository, https://github.com/mathieu-lemay/pipeline-runner
Description-Content-Type: text/markdown

# Bitbucket Pipeline Runner

Tool to run Bitbucket Pipelines locally.

## Installation
The prefered way of installing pipeline-runner is with [pipx](https://pipx.pypa.io/stable/installation/)
```shell
pipx install bitbucket-pipeline-runner
```

## Basic usage
To run a pipeline
```shell
cd <project-directory>
pipeline-runner run <pipeline-name>
```

To list available pipelines
```shell
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.

## Supported features
| Feature               | Supported  | Note                                           |
| --------------------- | :--------: | :--------------------------------------------: |
| Variables             | ✅         |                                                |
| Artifacts             | ✅         |                                                |
| Docker Service        | ✅         |                                                |
| Caches                | ✅         |                                                |
| Custom Caches         | ✅         |                                                |
| Private Runner Images | ✅         |                                                |
| Pipes                 | ✅         |                                                |
| OIDC                  | ❌         | Theoretically possible but way too impractical |

## 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` like so
```
    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.

### 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.

