GitHub Actions Deploy through SSH

In this guide, we will show you how to deploy your code to a remote server using GitHub Actions through SSH.

GitHub Actions is a powerful tool that enables you to automate your software development workflows directly from your GitHub repository. By connecting GitHub Actions to your remote server through SSH, you can automate your deployment process and ensure that your code is always up to date.

The following step-by-step instructions will get you started with GitHub Actions and help you create a workflow that will deploy your code with ease.

Pre-requisites

Before you begin, you’ll need the following:

• A remote server that you want to deploy to
• An SSH key pair. You can generate a new key pair with the ssh-keygen command
• Access to the private key for the SSH key pair

Step 1: Add the public key to the remote server

To allow GitHub Actions to connect to your remote server, you’ll need to add the public key from your SSH key pair to the authorized keys on the remote server. To do this, follow these steps:

1. Log in to your remote server using SSH.
2. Create a new directory called ~/.ssh if it doesn’t already exist:

   mkdir -p ~/.ssh
   

3. Create a new file called ~/.ssh/authorized_keys if it doesn’t already exist:

   touch ~/.ssh/authorized_keys
   

4. Open the ~/.ssh/authorized_keys file in a text editor and paste the contents of the public key file (~/.ssh/id_rsa.pub by default) at the end of the file.
5. Save and close the ~/.ssh/authorized_keys file.

Step 2: Configure GitHub Deploy Key

You’ll need to add the public key of your SSH key pair as a deploy key in your GitHub repository. To do this, follow these steps:

1. Open your GitHub repository in your web browser.
2. Under "Security" click on the "Deploy keys" tab item on the left side.
3. Click on "Add deploy key".
4. Give it any "Title" you wish.
5. In the "Key" text area, paste the contents of the public key file (~/.ssh/id_rsa.pub by default).
6. Click on the "Add key" button.

Step 3: Configure GitHub Actions Secret

While on the Settings tab we will need to add the private key of our SSH key as a [GitHub Actions Secret](). Follow these steps to do that:

1. Click on the "Secrets and variables" tab item on the left to expand it.
2. Then click on "Actions" sub item.
3. On the right side of the screen, click on the green "New repository secret" button.
4. In the "Name" field, enter SSH_PRIVATE_KEY.
5. In the "Value" field, paste the contents of the private key file (~/.ssh/id_rsa by default).
6. Click on the "Add secret" button.

Step 4: Create the Github Action Workflow

You’ll need to create a Github Action workflow that connects to your remote server using SSH and executes the necessary deployment commands. To do this, follow these steps:

1. Create a new file called .github/workflows/deploy.yml in the root directory of your Github repository or project folder if you are working locally.

2. Open the deploy.yml file in a text editor.

3. Copy and paste the following YAML code into the deploy.yml file:

   	name: Deploy to remote server
   	on:
   	  push:
   		branches:
   		  - main
   
   	jobs:
   	  deploy:
   		runs-on: ubuntu-latest
   		steps:
   		- name: Checkout code
   		  uses: actions/checkout@v2
   		
   		- name: Setup SSH Key
   		  uses: webfactory/ssh-agent@v0.5.0
   		  with:
   			ssh-private-key: ${{ secrets.DEPLOY_KEY }}
   		
   		- name: Deploy code
   		  uses: appleboy/ssh-action@master
   		  with:
   			host: your-remote-server.com
   			username: your-ssh-username
   			key: ${{ secrets.SSH_PRIVATE_KEY }}
   			script: |
   			  cd /var/www/my-app
   			  git pull origin main
   			  npm install
   			  npm run build
   

4. In the with section of the Deploy code step, replace your-remote-server.com with the hostname or IP address of your remote server, and replace your-ssh-username with the username that you use to connect to your remote server.

5. In the script section of the Deploy code step, replace /var/www/my-app with the path to your project on your remote server, and replace the deployment commands relevant for your project.

This workflow is triggered when a push is made to the main branch. It checks out the code using actions/checkout@v2 action, and then sets up the SSH key using the webfactory/ssh-agent action, finally it uses the appleboy/ssh-action action to execute commands on the remote server.

The deployment commands in this example, changes directory to /var/www/my-app, pulls the latest changes from the main branch, installs the necessary packages and builds the application.

That’s it, thank you for following along. Please feel free to comment below for any questions or feedback. To learn more about GitHub Actions click here.