Debug your pipelines locally with Docker
You can test your Bitbucket Pipelines build locally with Docker. For example, you can check whether your Docker image suits the needs of your setup.
Before you begin
Prepare your local environment. Make sure you have a local copy of your Bitbucket repository with your bitbucket-pipelines.yml file ready.
$ cd /Users/myUserName/code
$ git clone git
For the detailed guidelines, see Clone a repository.
In this scenario, we'll be testing the following bitbucket-pipelines.yml file:
Step 1: Install Docker on your machine
The installation procedure differs depending on the operating system that you want to use. Follow the installation guidelines provided by Docker: https://docs.docker.com/engine/installation/
Go to the terminal and run:
$ docker -v
If you have SSH installed, the command returns the version details.
Step 2: Log in to your Docker container
Once your Docker installation is in place, you can log in to your local Docker container:
$ docker run -it --volume=/Users/myUserName/code/localDebugRepo:/localDebugRepo --workdir="/localDebugRepo" --memory=4g --entrypoint=/bin/bash python:2.7
Runs a Docker container with a TTY and with STDIN open. It means that the container opens in an interactive mode and you can run commands in it.
Mounts the local directory called
Any changes to the repository content that occur within the container are reflected in the local clone of your repository.
The command runs with a default setting, which grants the container read and write permissions to the repository. You can limit the access to the local directory to read only by adding
Sets the directory in which you want to start. This is the directory in which you run the commands. By default, it's the root directory of the container.
(Optional) Runs the container with 4 GB of memory, which is the amount of memory that you can use in Pipelines.
You don't have to set the limit for local debugging, but a lot of issues with failed pipelines that pass locally are due to memory constraints, so we recommend it.
macOS (OS X)
You can modify the default memory settings in the status bar ( > Preferences > General).
The Docker image that you want to run. You probably want to use the image that you specified in your bitbucket-pipeline.yml file. For more information, see Using Docker images as build environments.
Starts a bash prompt
The Docker image is running and you can see the ID, for example:
You're inside of your working directory and you can start executing commands.
Step 3: Test Bitbucket Pipelines in your local setup
At this stage, we have the
python:2.7 container open and we're inside the repository directory.
run individual commands of your bitbucket-pipelines.yml to test them
configure tools inside the container
Once you get things working as needed in your local Docker container:
Note the changes.
Add them to your bitbucket-pipelines.yml file.
Push them back up to Bitbucket to build in Pipelines!
The examples below show how you can test the configuration of your bitbucket-pipelines.yml file that we mentioned at the beginning of this guide.
Check the python version:
$ python --version
Run one of your python scripts:
$ python myScript.py
Note: This example works only if you have the myScript.py script in the repo.
Configure things as usual inside the container:
$ pip install scipy
Installing collected packages: scipy
Successfully installed scipy-
Was this helpful?
Thanks for your feedback!