Estimated Reading Time: 3 mins
You may find yourself trying to figure out why a particular build is failing, especially if the build succeeds locally or succeeded in the past.
In order to effectively diagnose the issue, we provide command line access to a replicated instance of your failing build. This SSH debug session will include all configured environment variables from the original build run.
To be able to open an SSH debug session, you will need to configure SSH access on your account. The first thing you will need to do is get your local machine’s SSH key.
If you need to generate a new local key, you can do so by running:
ssh-keygen -b 8192
Or, if you need to fetch your existing local key, you can do so by running:
Once you have your local key, you will need to add it to your Codeship Account Settings, which is accessible by clicking on your name in the top right of your screen. Once there, you will paste your local machine’s key into the box labeled Public SSH Key.
When you start a SSH Debug session from your build’s dropdown menu, we will clone the repository and set up all environment variables that you defined and that we set by default.
Note that your setup commands have not run yet on the debug machine. You usually want to start with those commands. Also note that you default directory is
$HOME, and that your project will be found in
There are several key ways to use SSH sessions to solve your issues:
You can try different versions of your tools and technologies combined with your tests to see if you can isolate any version issues.
Consider manually trying different package versions, or removing packages, to see if modifying the packages installed impacts the behavior you’re trying to solve.
You can see the environment variables with a
printenv command to check for configuration and availability.
You can interact directly with the databases and other services, allowing you to workshop your setup commands before having to run live builds with them.
Inside the SSH session, you have access to default Codeship commands. It provides some convenient methods to debug your project. You can view the available methods by running:
You can view all your environment variables by running:
You can use
grep to filter the Environment:
printenv | grep CI
You can clear the Dependency Cache:
If you are being prompted for a password while connecting to your SSH debug session, you likely have a mismatch with the key you added to your Codeship account.
Try removing the key, verifying or regenerating the key locally and then re-adding it.
Note that after saving your key it will only apply to new builds, so you must trigger your builds after you add your key to be able to connect.
The debug build will shutdown itself after 60 minutes
You can shutdown the debug build manually by using
If you restart a build, or trigger an SSH debug build for a branch that has since been removed from your source control repo you will see the build fail as it is unable to clone the branch it is keyed to.
We also have a couple of code examples and sample projects available, that make it easier to get started with Codeship.