Debugging builds via SSH

3 minute read

What is an SSH Debug Session?

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.

Configuring SSH access

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:

cat ~/.ssh/

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.

Public Key Setup

Using SSH Debug Sessions

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 $HOME/clone.

Start a debug build

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.

Useful Commands

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:

cs help

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:

cs clear-cache

Common issues

Prompted For Password

The SSH client expects to find the default private key in ~/.ssh/id_rsa. In the case you are using a custom configuration for the identity file, you could be passed it by -i parameter to the SSH client or you could load it into the ssh-agent.

Having said that, if you are still 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.

SSH Debug Session Timeout

The debug build will shutdown itself after 60 minutes

You can shutdown the debug build manually by using

cs exit

Branch no longer exists

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.

Choose Node version

When you start up a new debug build, you will need to choose your version of Node.js.