Debugging Codefresh builds locally
Codefresh provides detailed logs for each pipeline that show all the execution results. If however, you wish to run a build step locally you can easily install Docker on your workstation and simulate the same executions Codefresh performs on its platform runners.
You need to have Docker installed on your local workstation. You can follow the official instructions to install it. Notice that if you use Linux, the Docker version offered by your native package manager is not always the latest version.
Once docker is installed, check that it runs correctly with:
docker run hello-world
You should get a short welcome message.
Simulating a Codefresh build step
Codefresh is running each build step in the context of a Docker container. To fully replicate a build step locally you need to:
- use the same docker image as a build context
- mount the shared codefresh volume at
- place your git source project inside the volume
- execute the same command defined in your
For more details on how Codefresh runs build steps see the introduction to pipelines.
Detailed steps are shown below.
Step 1 - Clone or update locally your source project
Clone your git repository and checkout the branch the build in Codefresh failed on.
If your repository is already cloned locally, make sure to run
git pull so your local cloned
repository will be updated with the latest changes (make sure you have checked out
the correct branch first).
Step 2 - Login to your Docker registry
If the docker image that you use is a public one (such as node, python, maven, etc.) you can skip this step.
If the docker image you use is a private one, you should log in to the respective registry from the command line.
For example if your image is in the Codefresh Docker registry, you can create a Token from the Codefresh UI and use it locally.
Check the documentation of your own Docker registry (e.g. GRC, Quay.io, Bintray) on how to achieve this.
The docker login command should return with a success message.
Step 3 - Mount your git project inside the container
To mount your project inside the Docker container run the following command:
docker run -it -v $(pwd):/codefresh/volume/<your_repo_name> <image_name_and_tag> /bin/bash
<your_repo_name>with the name of your git project
<image_name_and_tag>with the full name of your Docker image
In the case of the Codefresh registry you can easily get the name from the Codefresh UI
Notice that if your image does not have bash available you can use
/bin/sh instead, as the last part of the command.
Step 4 - Change the work directory to the root project
The docker command above will put you in a shell inside the container.
Now you’re running within the container with your repository mounted as a volume under
/codefresh/volume/<your_repo_name>. You make sure you’re running the
same commands that you’re using in Codefresh from the same working_directory that
your failed step is using.
Working directory refers to your starting point within the container. By default (if you’re
not referring to it in the Codefresh step) it’ll be your cloned repository path which is
Navigate to your working directory within the container:
Of your build step uses another working directory then use that one instead (e.g.
Step 5 - Execute the build command
Finally we execute the same build command that was defined in the
This process fully simulates debugging of Codefresh steps locally in your machine to resolve issues in your code that may appear during the CI process.
Let’s assume that we have a Python/Flask application that fails during unit-tests in Codefresh and we want to run the tests locally (without actually installing python on the workstation, docker is enough). The name of the project is
python-flask-example-app in Github.
First we login to the Codefresh Registry locally using a token that can be obtained from the User settings.
$ docker login r.cfcr.io -u kostis-codefresh -p <TOKEN_HERE> Login Succeeded
Then we find the image from the UI, in our case it is
We make sure that we are in the correct branch in our local workstation, and then we start the docker container mounting the source code as well:
$ cd /my-workspace/python-flask-example $ git checkout master $ git pull $ docker run -it -v $(pwd):/codefresh/volume/python-flask-example r.cfcr.io/kostis-codefresh/kostis-codefresh/python-flask-sampleapp:master-b168342 bash #
Finally we enter the correct directory and run our unit tests:
# cd /codefresh/volume/python-flask-example # python setup.py test
Now the unit tests will run and we can see their results in detail.