Demystifying Shippable's deployment keys

When you enable a project on Shippable, you can see that a key gets added to your repository's "Deployment Keys" on GitHub or BitBucket. However, when you visit your subscription dashboard on Shippable, there's another "Deployment Key" listed there that doesn't match what you see in your repository settings. I'm going to try and clear that up for you in this post.


Shippable uses two key pairs:

  1. ~/.ssh/project_rsa and ~/.ssh/ for git clone, git pull and git fetch operations
  2. ~/.ssh/id_rsa and ~/.ssh/ for git submodule operations, and any other commands that use SSH which you include in your YML files

Project keys

Every time you enable a project, we generate an SSH key and sets that on GitHub as the deployment key for the project. This happens only for private projects because we uses the APIs to fetch the YML file and figure out what we need to build. This is the key you see when you go to the Deployment Keys settings for your project. During the build, this key pair is available at ~/.ssh/project_rsa and ~/.ssh/

We use this key to do two things:

  1. All git clone/pull/fetch operations that happen in the git_sync step of your build. Because the filenames are not standard key names, we use ssh-agent so git will use these keys when talking to GitHub or BitBucket.
  2. We also use this key pair to encrypt and decrypt secure environment variables in your project. This means that if you ever disable and re-enable a project on Shippable, you will need to re-encrypt the secure environment variables in your YML file.

Subscription keys (a.k.a "Deployment Keys")

We also generate a second set of keys for every subscription. This is what you see when you expand the "Deployment Keys" accordion on the subscriptions dashboard. We ask that you use this the "deployment key" when you want to integrate with services like Heroku, and also when you need to pull in submodules or dependencies from other private repositories. These keys are placed at ~/.ssh/id_rsa and /.ssh/ during the build. This way, when you do a git push heroku or git submodule update you don't need to worry about ssh-agent and the likes. Git will use id_rsa by default and do the right thing.

Why do we use two key pairs?

If we didn't do this, you would never be able to pull submodules or other dependencies from other private repositories. On GitHub and BitBucket, a key pair can only be associated with a single project or user account. Once we set the project keys as the deployment key on your repository, you would not be able to re-use the same key on another user account to allow pulling code from other repositories. The only other alternative we had at the time was to add the key automatically to your user account, but we decided that this is too invasive and gives us far more permissions that we actually need. By managing two key pairs and making them both available to the build we're letting you decide when and how to grant the additional access required for submodules and dependencies from other private repositories.

No Comments