Simple SSH Deployment with GitHub Actions: A Quick Start Guide

In the world of modern software development, deploying applications swiftly and efficiently is crucial. GitHub Actions is a powerful tool that enables developers to automate various tasks in their workflows, including the automatic deployment of code to remote servers. In this blog post, we will explore how to set up GitHub Actions to automate the deployment process to a Virtual Private Server (VPS).

Prerequisites

Before we dive into the details, make sure you have the following prerequisites in place:

1. GitHub Repository: You should have a GitHub repository containing your project code.
2. VPS Access: You must have access to a VPS with SSH connectivity. Ensure that you have the necessary credentials and permissions to access the server.
3. Required Tools: The VPS should have the necessary tools and dependencies installed for your project, such as Git and build tools (e.g., Grunt, Gulp, etc.). You can use package managers like apt or yum to install these tools.

Setting Up GitHub Actions

GitHub Actions allows you to automate workflows by defining a YAML file (.github/workflows) within your repository. In this example, we will create a workflow that triggers when code is pushed to the ‘live’ branch and deploys it to the VPS.

Create a .github/workflows/deployment.yml file in your repository with the following content:

name: Deployment

on:
  push:
    branches:
      - live

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: SSH into VPS and Deploy
        uses: appleboy/ssh-action@master
        env:
          HOST: ${{ secrets.HOST }}
          USERNAME: ${{ secrets.USERNAME }}
          KEY: ${{ secrets.SSHKEY }}
          SCRIPT: |
            cd ${{ secrets.PROJECT_PATH }}
            git pull origin live
            grunt build

Let’s break down what this script does:

• on: Specifies the trigger for the workflow. In this case, it triggers on a push event to the ‘live’ branch.
• jobs: Defines a job named ‘deploy’ that runs on the latest version of Ubuntu.
• steps: Lists the individual steps to execute within the job.
  • Checkout code: This step checks out the code from the repository.
  • SSH into VPS and Deploy: This step uses the appleboy/ssh-action to SSH into the VPS, navigate to the project directory, pull the latest changes from the ‘live’ branch, and execute the build process (e.g., Grunt) to deploy the application.

Setting up Secrets

To keep sensitive information like SSH keys and server credentials secure, use GitHub Secrets. Navigate to your GitHub repository, go to the ‘Settings’ tab, and select ‘Secrets.’ Create secrets for the following variables used in the workflow:

• HOST: The IP address or domain name of your VPS.
• USERNAME: Your SSH username for accessing the VPS.
• SSHKEY: Your SSH private key, allowing the GitHub Actions workflow to authenticate with the VPS.
• PROJECT_PATH: The path to your project directory on the VPS.

Understanding SSH Key Compatibility

SSH (Secure Shell) keys come in different formats, and compatibility between the private key used in GitHub Actions and the authorized_keys file on your VPS is essential for a successful SSH connection.

When you generate an SSH key pair, it usually consists of two parts: the private key and the public key. The public key is placed in the authorized_keys file on the remote server, allowing the server to authenticate the private key when establishing an SSH connection.

To ensure proper access, follow these steps:

1. Generate an SSH Key Pair: If you haven’t already, generate an SSH key pair on your local machine using the ssh-keygen command: ssh-keygen -t rsa -b 4096 -C "[email protected]" This command generates a pair of keys: a private key (usually stored in ~/.ssh/id_rsa) and a corresponding public key (stored in ~/.ssh/id_rsa.pub).
2. Copy the Public Key to the VPS: Take the contents of your public key (id_rsa.pub) and append it to the ~/.ssh/authorized_keys file on your VPS. You can do this manually or by using the ssh-copy-id command: ssh-copy-id username@your_vps_ip Replace username with your VPS username and your_vps_ip with the VPS’s IP address or hostname.
3. Use the Same Private Key in GitHub Actions: Ensure that the private key you use in your GitHub Actions workflow matches the one you have on your local machine. You should not generate a separate key pair for GitHub Actions.

By following these steps, you ensure that the private key used by GitHub Actions can be authenticated by the authorized_keys file on your VPS, allowing for a successful SSH connection during the automated deployment process.

With SSH key compatibility in place, your GitHub Actions workflow will seamlessly connect to your VPS and deploy your code, simplifying your deployment process while maintaining security.

Conclusion

Automating deployment with GitHub Actions is a powerful way to streamline your development workflow. This not only saves time but also ensures consistency and reliability in your deployment process.