I’m a big fan of not having to run my own CI service. When possible I would rather use a managed solution and not have to worry about an additional server cluster to maintain. This is particularly true for open source projects. However, the debugging flow with most of the CI vendors is a bit of a pain, particularly with the initial setup.

This is the typical workflow:

  1. Update the CI build script and configurations.
  2. Commit and push the code to GitHub.
  3. Log into the CI provider logging interface and watch it run.
  4. Typically run into an error and then repeat steps 1 to 3 until the build passes.

This flow is more painful if the build takes a few minutes and the error happens at the very end. You end up waiting a long time to see the error, commit what you hope is a fix, push it, hope and wait to see if the build is fixed.

Killer Debugging Feature

I’m not the one who usually buys into the single killer feature hype. However, in the case of CircleCI they have a feature that blew my mind when I first saw it and still does today: ssh login. Being able to ssh into the machine to debug and poke around the environment is a godsend.

The way the feature is implemented also empowers developers to debug the actual error, instead of having to ping the ops team to figure out what is wrong the build. CircleCI provides a link to enable a Build with SSH in a few spots:

Once you click on the “Enable SSH for this build” button, it will provide a ssh command which you can copy and paste in your terminal to get into the Virtual Machine.

Once you get in there you can cd to your project and debug to your heart’s content.

Demo of ssh debugging

For this debugging demo I’m using the circle branch of the tongueroo/hi project available on GitHub.

For this example, I’ve committed code and it results in a build error. I look on the build page and see the error on the TEST section:

Apparently, I forgot to install the ufo gem which I’m using to build a docker image as part of the test command. I run the build again and enable ssh for debugging this time.

The box will stay up for 30 minutes while for debugging. Now I copy the ssh command to get into the box.

$ ssh -p 64633 ubuntu@
$ cd hi
$ ufo docker build
No command 'ufo' found, did you mean:
 Command 'ufw' from package 'ufw' (main)
 Command 'dfo' from package 'dfo' (universe)
 Command 'udo' from package 'udo' (universe)
ufo: command not found

Above, I ran the command again to confirm that error. This is a case of me forgetting to install the dependent ufo tool. Now, I’m going to install the ufo tool and then continue messing around until I get the build passing.

$ cd hi
$ gem install --no-ri --no-rdoc ufo
$ env # checkout env variables
$ ls # checkout ls
$ ufo docker build
$ docker tag -f $(ufo docker image_name) hi_web
$ docker-compose run web bundle exec rake db:create db:migrate
$ docker-compose run web bundle exec rake
1 runs, 1 assertions, 0 failures, 0 errors, 0 skips

The beautiful thing here is that I can do a lot of testing upfront without committing code because I can ssh into the environment and do not have to go through the slower commit and push cycle. I can even poke around and inspect the environmental variables. At then end, once I have a high level of confidence then I do the final commit and upload. Here the confirmation that the build is fixed.


The ssh feature from CircleCI is extremely helpful and one of the main reasons CircleCI is current my goto when I need to use hosted CI. The CircleCI documentation for the ssh login feature is here. I hope other providers implement this handy feature. If there is, indeed, other hosted CI vendors out there that do provide this feature, feel free to let me know and I’ll add it to the list.