Note from the publisher: You have managed to find some of our old content and it may be outdated and/or incorrect. Try searching in our docs or on the blog for current information.

“It worked on my machine, but broke in production” is a common issue engineers run into on a regular basis. CircleCI 1.0 users have found it useful to debug such build failures by using SSH access, which we have now enabled for builds running on our 2.0 platform.

Additionally for 2.0, we have introduced CircleCI CLI, which helps users reproduce the CircleCI environment locally. This functionality allows users to iterate quickly and debug issues in their local environment.

Which One Should I Use?

Local Builds via CircleCI CLI

If you want to keep your code base contained and need to quickly remediate issues or debug your configuration syntax, running builds locally via CircleCI CLI may be the right option for you.

We have seen users commit their config and run a build few times to validate their YAML syntax. You can use circleci build to experiment and validate your syntax quickly on your local machine. Once the config is validated, you can commit it.

You may also want to use local builds if you need an easy way to troubleshoot container configurations. Local builds allow you to quickly retry database configurations or validate if services have been setup correctly.

Finally, for testing projects, you can clone the repo, install the CircleCI CLI and run circleci build. This is a great way to get things up and running quickly with the same environment as your team.

SSH Access

Testing across a network into builds via SSH has been a popular and valuable feature to many CircleCI users. SSH access to builds allows you to access the execution environment through a SSH session to troubleshoot build failures, access log files, analyze running processes and more. You can SSH directly into a failed build to see what went wrong. After each build, you have the option of rebuilding with SSH access enabled. While the box is running, you’ll be able to SSH into it and poke around for problems.

How Do I Use These?

For SSH access to your jobs, you can follow this guide.

To run CircleCI locally, install the CircleCI CLI by following this guide.