Estimated Reading Time: 5 mins
To follow this tutorial on your own computer, please install the
jet CLI locally first.
To deploy using SSH and SCP with Codeship Pro, you will need to create a container that can connect to your server via SSH. Then, you will pass this container the necessary deployment commands.
The first thing you will need to do is generate a usable SSH key locally. If you have an existing key, you can use it, or you can use the following recommended commands to generate the key:
ssh-keygen -t rsa -b 4096 -C "firstname.lastname@example.org" -f keyfile.rsa
When you run this command, it will generate two files in your local repository:
keyfile.rsa contains the private key that you will add to your repository so that it can be used by your Codeship Pro build containers to authenticate with your external servers. Note the instructions below for encrypting this file to keep it secure at all times.
keyfile.rsa.pub is the corresponding public key, which you will add to all resources that your Codeship Pro builds will be attempting to authenticate with.
Now that the you have the
keyfile.rsa file, you will need to encrypt this file into either a encrypted build arguments file or an encrypted environment variable file to saved in your repository and used during your builds.
If you only need the SSH key to be available at runtime - that is, via your codeship-steps.yml file after all of your containers have built successfully - then you will need to create an encrypted environment variable file.
If you only need the SSH key to be available at buildtime - that is, via your Dockerfile as your containers build - then you will need to create an encrypted build arguments file.
Note that you may need the key as both a build argument and an environment variable, since build arguments are only available via the Dockerfile and environment variables are only available via the codeship-steps.yml file after your containers have built.
Whether using build arguments or environemnt variables, you will need to be sure to replace newlines with
\n so that the entire SSH key is in one line. For example:
PRIVATE_SSH_KEY=-----BEGIN RSA PRIVATE KEY-----\nMIIJKAIBAAKCFgEA2LcSb6INQUVZZ0iZJYYkc8dMHLLqrmtIrzZ...
You will ultimately add the encrypted key to a service with the
encrypted_env_file option or the
app: build: . encrypted_args_file: sshkey.args.encrypted
app: build: . encrypted_env_file: sshkey.env.encrypted
Before running any command that requires the SSH key to be available, make sure to run the following commands in that container.
These commands will load the SSH key into the required container directory so that is available for use. This will usually happen inside your Dockerfile, although in some cases it may happen with via a script in your codeship-steps.yml file:
mkdir -p "$HOME/.ssh" echo -e $PRIVATE_SSH_KEY >> $HOME/.ssh/id_rsa
$PRIVATE_SSH_KEY will change depending on what you have specifically named your build argument or environment variable.
Now you will need to connect VIA SSH and deploy you code. This is accomplished via standard SSH commands set up as steps in your codeship-steps.yml file.
- service: ssh command: scp -rp . email@example.com:/path/on/server/
Note that the
service references on the step will be whatever service you have set your key up in via your codeship-services.yml file.
Also note that you may run your SSH commands separately, as individual steps, or you may group them together as a single script that you call:
- service: ssh command: ssh-deploy.sh
If your SSH authentication commands are failing, there are several troubleshooting steps to take.
First, try connecting using that key locally to verify the key and the corresponding public key are configured and working as intended.
Next, try running your deployments locally with the local to see if you recieve the same error messages.
Often times these issues are related to character escaping or issues loading the key into the proper directory, so running
ls commands will help you verify that the correct key has been loaded and that it is where you want it to be.
We also have a couple of code examples and sample projects available, that make it easier to get started with Codeship.