Skip to content
Close up image of a badge that says "Come closer, I've been debugged"

Debugging CircleCI Builds - 3 Tips

Our Europe-based correspondent and senior dev Richie discusses fixing broken things.

Ever found yourself in the situation where your tests are running nicely locally, but when you go to run them on CI, something is breaking?

When that happens, I tend to find myself in this painfully slow feedback loop writing commit message after commit message something like:

fix ci build  or try new fix for ci  or even fix broken fix for ci 

By the time I’m done, I’ve given up the pretence of good commit messages and am writing:

fix again  and  fix again  and then just plain old  fix 

If this sounds familiar, here’s three tips to help with your debugging. These tips are CircleCI specific because that’s what I have experience with – though it’s likely TravisCI and other solutions have similar things you can try.

Tip 1. Use Rebuild With SSH

This is your go-to. There’s a twirl down button beside rebuild with the name rebuild with ssh.

Screenshot from CircleCI showing dropdown menu options saying Rebuild, Rebuild without cache, Rebuild with SSH

Clicking that will fire up a new build, provide you with an ip address to ssh into, keeping the build up for 30 mins after your tests have run.

Screenshot of a message from CircleCI explaining a new build is enabled and providing an ip address to ssh into, keeping the build up for 30 mins after tests have run.

You can jump in there and re-run tests, experiment and debug. Just remember what steps you took so you can adjust your local setup and commit the changes.

Tip 2. Create Build Artifacts

Another technique you might make use of is build artifacts. CircleCI creates an empty directory at the start of each build and sets the  $CIRCLE_ARTIFACTS  environment variable to the path of this directory. At the end of each build, anything you save in there will be available via the artifacts tab on the build page.

Screenshot from CircleCi showing the Artifacts tab on the build page

They are also available via the browser at:

 This is good for things like log files or failure screenshots which many test frameworks can be configured to produce on failures.

Tip 3. Debug Browser Tests With Your Own Local Browser

This one is the Mac Daddy of awesome.

I’m pretty sure I actually did a sort of twirl (like this monkey) when I discovered this.

Gorilla in an enclosure, spinning around until it falls over on the floor

The gist of this one is that when you ssh onto a build VM you can pass the flag -L  with <local port>:localhost:<vm port>  as the argument like so:

ssh -p 64625 ubuntu@ -L 8080:localhost:3000

When this command runs (and assuming you have a web server up and running on the VM on the port you specified, in this case :3000 ), when you visit http://localhost:8080  on your local machine with your favourite browser, you will be able to see what’s going on with your headless VM and then debug it. This is incredibly handy when trying to debug headless selenium tests using ChromeDriver so definitely try it out.

Gif of a man with serious face and seemingly rubber arms flapping in front of and behind him as he also jiggles his legs and the words party hard flash in the image

That’s it! Happy debugging 🙂

Media Suite
is now

All things change, and we change with them. But we're still here to help you build the right thing.

If you came looking for Media Suite, you've found us, we are now MadeCurious.

Media Suite MadeCurious.