Local-BBP

Local-BBP is an open-source CLI tool written in Go, designed to simulate Bitbucket pipelines on your local machine. This tool allows developers to test and debug their pipeline configurations faster and more efficiently before pushing to Bitbucket.

Why Local-BBP?

As a developer, I often find that the first few pipeline runs for a new project fail due to configuration issues. This can be incredibly time-consuming and frustrating, as each failure requires a push to Bitbucket, a wait for the pipeline to run, and then reviewing the results to identify and fix issues. With Local-BBP, I can run and debug these pipelines locally, saving time and reducing the number of failed runs in the actual CI environment.

Supported Features

• Run pipeline
  • Sequential steps
  • Parallel steps
• Custom Step Image
• Private image repository access
• Artifacts
• Smart caches
• Pipe
• Services
  • Sidecars
  • Default Docker
  • Custom Docker
• Secret variables from file
• Stage
• Conditional steps
• Settings
  • Default image
  • Timeout
  • Container Size
• Validate bitbucket-pipelines.yml file
• Integration marketplace search

Installation

You can install the latest version of Local-BBP using the following command:

curl -s https://raw.githubusercontent.com/zhex/local-bbp/main/scripts/install.sh | bash

Usages

You need to have Docker installed on your machine to run Local-BBP.

To simulate your Bitbucket pipeline locally, navigate to the project directory containing your bitbucket-pipelines.yml file and run the following command to list the available pipelines:

bbp list

then run the default pipeline:

bbp run

This command will execute your default pipeline steps as defined in the bitbucket-pipelines.yml file.

You can also specify a specific pipeline to run using the -n flag:

bbp run -n default

When first running the command, Local-BBP will init the config file in the ~/.bbp/config.json also download the Linux docker cli binaries.

example config file:

{
    // the default workdir in the build container
    "workDir": "/opt/atlassian/pipelines/agent/build",
    
    // the default image to use in the build container if not specified in the bitbucket-pipelines.yaml file
    "defaultImage": "atlassian/default-image:4",
    
    // the default output directory for the pipeline results, base on the project directory if relative path is used 
    "outputDir": "bbp",
    
    // the default linux docker version to use in the build container 
    // download automatically from https://download.docker.com/linux/static/stable/
    "dockerVersion": "19.03.15",
    
    // the default docker image for running the docker daemon for the build container
    "defaultDockerImage": "docker:27.0.3-dind-alpine3.20",
    
    // the path for the cli to download required tools
    "toolDir": "/Users/zhex/.bbp/tools",
    
    // default timeout for a single pipeline step (in minutes)
    "maxStepTimout": 120,
    
    // default timeout for the whole pipeline (in minutes)
    "maxPipeTimout": 240,
}

You can also specify a path to the project directory containing the bitbucket-pipelines.yml file:

bbp run -n "pr/**" -p /path/to/project

Support secret variables by providing a path to the secrets file:

bbp run -n default -s /path/to/secrets

The secret file format is the same as dot env file. Sample secrets file:

MY_SECRET="my-secret-value"
MY_OTHER_SECRET="my-other-secret-value"

use the -v flag to view the verbose output for more details:

bbp run -n default -v

Also, you can validate your bitbucket-pipelines.yml file using the following command:

bbp validate

The validation rules are based on the official Bitbucket Pipelines configuration schema.

Differences between Local-BBP and Bitbucket Pipelines

Local-BBP is designed to simulate Bitbucket Pipelines as closely as possible, but there are some differences between the two:

• Environment: Local-BBP runs pipelines on your local machine, so it may not have access to the same resources as the Bitbucket Pipelines environment.
• Features: Local-BBP does not support all the features of Bitbucket Pipelines, such as host runners and custom runner size.
• Service Access: In Local-BBP, service names are used as hostnames similar to Docker Compose. In Bitbucket Pipelines, sidecar services are accessed via localhost.
• Step Condition: Bitbucket Pipeline compares all commits between source and target branches in pull-request pipelines,, while in other pipelines, it compares the last commit. Local-BBP includes uncommitted changes for easier development.

License

Local-BBP is released under the MIT License. See LICENSE for more details.

Support

For any issues or questions, please open an issue on our GitHub repository.