Cloning the Application Code on Remote Servers

Some deployment strategies clone on the remote servers the application code hosted on an external repository (e.g. GitHub). Depending on your local and remote configuration, this process may fail.

This article explains the most common solutions for those problems. The examples below use GitHub.com, but you can translate those ideas to other Git services, such as BitBucket and GitLab.

SSH Agent Forwarding

Agent forwarding is the strategy recommended by this bundle and used by default. If enabled, remote servers can use your local SSH keys to access other external services. First, execute this command in your local machine, to verify that you can access to GitHub web site using SSH:

$ ssh -T git@github.com

Hi <your-name-here>! You've successfully authenticated, but GitHub does not
provide shell access.

Now log in any of your remote servers and execute the same command:

• If you see the same output, agent forwarding is working and you can use it to deploy the applications. This option is enabled by default and can be changed with the useSshAgentForwarding option in your deployer.
• If you encounter the error Permission denied (publickey), check that:
  • The local SSH config file has not disabled agent forwarding for that host (see this tutorial for more details).
  • The remote SSH server hasn't disabled agent forwarding (see this tutorial for more details).
  • Read this GitHub guide to troubleshoot agent forwarding issues.

Deploy Keys

If you can't or don't want to use SSH agent forwarding, the other simple way to clone the code on remote servers is using deploy keys. They are SSH keys stored on your remote servers and they grant access to a single GitHub repository. The key is attached to a given repository instead of to a personal user account. Follow these steps:

1. Log in into one of your remote servers.

2. Execute this command to generate a new key:

   $ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
   

   Press <Enter> for all questions asked to use the default answers. This makes your key to not have a "passphrase", but don't worry because your key will still be safe.

3. The command generates two files, one of the private key and the other one for the public key. The deploy key is the public key. Display its contents so you can copy them. For example: cat ~/.ssh/id_rsa.pub (you'll see some random characters that start with ssh-rsa and end with your own email).

4. Go to the page of your code repository on GitHub and click on the Settings option (the URL is https://github.com/<user-name>/<repo-name>/settings).

5. Click on the Deploy keys option on the sidebar menu.

6. Click on the Add deploy key button, give it a name (e.g. server-1) and paste the contents of the public key that you copied earlier.

7. Click on the Add key button to add the key and your remote server will now be able to clone that specific repository.

8. If the same server needs access to other repositories, repeat the process to add the same public key in other repositories.

9. If other servers need access to this repository, repeat the process to generate keys on those servers and add them in this repository.

Read this guide if you any problem generating the SSH keys: Connecting to GitHub with SSH.

Other Cloning Techniques

If you can't or don't want to use SSH Agent Forwarding or Deploy Keys, you can use HTTPS Oauth Tokens and even create Machine Users and add them as collaborators in your GitHub repositories. Read this guide to learn more about those techniques.