Table of Contents
- Create an SSH Key on Your Server
- Add Key to SSH Config
- Create a Deploy Key on GitHub
Ask ten people how to deploy a web app, and you'll end up with ten different ways of how to do it. I've deployed multiple small web apps in the past months, and the only thing that's clear to me is that deployment is more of an art than science.
While learning how to deploy apps, I took note of every tool and practice I found helpful. Some of them are a bit too cumbersome to use in every project (e.g., Docker), while others are so useful and easy to set up that I keep using them everywhere. Deploy keys are part of that latter group.
A GitHub deploy key is an SSH key that gives read –and optionally write– access to a single repository on GitHub. It makes it easy to pull your app's code to a server automatically.
With a deploy key, you just connect to your server, do a
git pull, and you're done! Forget about connecting with an SFTP and uploading your files manually.
This tutorial will show you how to use GitHub deploy keys in your next project. Let's get started!
If you're planning on using deploy keys, I suppose you have something to deploy, right? 🤔
In any case, before you continue with the next sections, make sure that:
- You have a repository with your app's code on GitHub.
- You have access to a Linux server with git installed.
If so, continue to the next section. Otherwise, you can learn how to come up with exciting ideas using this framework.
Create an SSH Key on Your Server
A deploy key is, ultimately, an SSH key. So you'll start by creating an SSH key on your server.
First, connect to your server using the terminal. Once you're in, create an SSH key by executing the following command in the terminal:
$ sh-keygen -t ed25519 -C "USERNAME@EMAIL.com"
This command will create and store an SSH key. You use two parameters:
-tto specify which algorithm to use to generate the key. In this case, you use ED25519, which is a very secure and efficient algorithm.
-Cto append your email as a comment at the end of the key.
You can learn more about these parameters here. But don't worry too much about them. You don't need to know much more than that.
After running the command, you'll get a couple of questions asking you to specify a path and set a passphrase for the key. You can save the key at the default path and skip setting a passphrase. So just hit Enter when prompted.
Add Key to SSH Config
Next, you'll create an SSH config file. This file allows you to define the instructions required to connect to remote servers using SSH. It's quite handy to manage multiple servers' SSH keys, or to keep deploy keys of different repositories in the same server.
You can create and edit an SSH config file by running these commands:
$ touch ~/.ssh/config $ chmod 600 ~/.ssh/config $ vim ~/.ssh/config # Or: nano ~/.ssh/config
These commands will create an SSH config file, set the correct permissions, and open it using vim. You can also use nano to open the file if you like crappy text editors 😉
An SSH config file consists of sections specifying the instructions required for each server you'll connect to. So, in this case, you'll provide the instructions needed to connect to your repository. For that, copy this text to the file:
Host github-YOUR-APP HostName github.com AddKeysToAgent yes PreferredAuthentications publickey IdentityFile ~/.ssh/id_ed25519
In the code snippet above, you provide the settings required to connect to GitHub, using the SSH key you just created. You specify the following parameters:
- Host: name you'll use in the command terminal to identify this server.
- HostName: real hostname that you'll connect to.
- AddKeysToAgent: specifies if it should add the private key to the
- PreferredAuthentications: order in which the client tries authentication methods.
- IdentityFile: specifies a file from which the key is read.
That's all you need to do on the server. Next, you'll use your SSH to create a deploy key on GitHub.
Create a Deploy Key on GitHub
First, you'll copy the public key from the SSH key you created earlier. The easiest way of doing that is to run:
$ cat ~/.ssh/id_ed25519.pub
Then select and copy the resulting text from the command line. It should look something like this:
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILs35pzG5jZakTEHDWeRErgkAmabhQj2yj/onxlIQgli firstname.lastname@example.org
Next, open your preferred browser and go to the repository with your app's code on GitHub. There, click on Settings, select Deploy keys, and then click on Add deploy key.
Copy the key in the Key textbox and set a title to the key. You can leave Allow write access unchecked, and click on Add key.
Next, you can go back to your server's terminal and clone your repository. You can do that by running this command:
$ git clone git@github-YOUR-APP:dylanjcastillo/random.git
This will clone your app's repository to your server. Please remember to replace
github-YOUR-APP by the
Host you specified in the SSH config file. Otherwise, it won't work.
This tutorial showed you how to use deploy keys to pull your app's code from a GitHub repository to a server automatically. Using a deploy key will save you time and provide you with a safer way to deploy your app.
In this tutorial, you've learned:
- How to create an SSH key on your server.
- What an SSH config file is and how to use it.
- How to add a deploy key to your GitHub repository.
If you have any questions or feedback, let me know in the comments!