Setup CI/CD Workflow with GitHub Actions

Setup and configure CI/CD workflow with GitHub actions to deploy source code to remote server.

In this guide you are going to learn how to configure GitHub actions to make automated deployments to server once a push is made. We will setup SSH keys to authenticate with the server.

GET STARTED

Prerequisites

Follow this guide to create new user and configure SSH keys which is necessary for GitHub to make secure connections with your server.

Once you have completed the above step you can proceed to GitHub to configure actions.

Take note of the following details from the above setup.

1. Username: The new user you created using adduser command.
2. Hostname: This is the IP address of your server.
3. Private key: This key is created automatically using the ssh-keygen command. Make sure the key is in RSA format which begins with -----BEGIN RSA PRIVATE KEY-----.

These 3 details are necessary to make connection to the server from GitHub.

Setup Secrets

Login to your GitHub account and go to your repository.

Navigate to Settings >> Secrets.

Click New repository secret.

In the Name add SSH_HOST and in value enter the IP address of your server.

Click Add secret.

Again click New repository secret.

In the Name add SSH_USERNAME and in value enter the username you noted above which was created in the post mentioned in the prerequisites section.

Click Add secret.

Again click New repository secret.

In the Name add SSH_KEY and in value enter the private key you noted above which was created in the post mentioned in the prerequisites section.

Click Add secret.

Now you should have your secrets as shown below.

Once the secrets are in place you can setup actions.

Initiate Actions Workflow

Now click on the Actions tab.

You will see a list of workflows that can be configured by default.

You can click on Setup an workflow yourself.

You will see some default configurations here.

Configure Actions Workflow

You can name the workflow file as per your wish. I will name it as deploy.yml.

You can remove all workflows that was included by default.

Copy the below workflow and add it.

name: Identifier Name
on:
  push:
    branches: [ branch-name ]

jobs:
  deploy:    
    runs-on: ubuntu-latest
    steps:
      - uses: actions/[email protected]
      - name: Deploy source-code
        uses: appleboy/[email protected]
        env:
          HOST: ${{ secrets.SSH_HOST }}
          USERNAME: ${{ secrets.SSH_USERNAME }}
          PORT: 22
          KEY: ${{ secrets.SSH_KEY }}
        with:
          source: "*"
          target: "/path/in/your/server"

The above code will perform a deployment to your server when a push is made to a speck branch.

It deploys all the source code located in the root location of your repository. If you need to deploy any specific folder only your can configure it in the source directive.

Make sure the user has permissions on the server to perform deployment.

For example if you are using Nginx or Apache web server which runs using www-data user you need setup permissions and reset the permissions as shown below.

name: Identifier Name
on:
  push:
    branches: [ branch-name ]

jobs:
  deploy:    
    runs-on: ubuntu-latest
    steps:
      - name: Reset Permissions before deployment
        uses: appleboy/[email protected]
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USERNAME }}
          key: ${{ secrets.SSH_KEY }}
          port: 22
          script: |
            sudo chmod -R 755 /path/in/your/server
            sudo chown -R username:username /path/in/your/server
            sudo setfacl -R -m u:www-data:rwx /path/in/your/server 

      - uses: actions/[email protected]
      - name: Deploy source-code
        uses: appleboy/[email protected]
        env:
          HOST: ${{ secrets.SSH_HOST }}
          USERNAME: ${{ secrets.SSH_USERNAME }}
          PORT: 22
          KEY: ${{ secrets.SSH_KEY }}
        with:
          source: "*"
          target: "/path/in/your/server"

      - name: Reset Permissions after deployment
        uses: appleboy/[email protected]
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USERNAME }}
          key: ${{ secrets.SSH_KEY }}
          port: 22
          script: |
            sudo chmod -R 755 /path/in/your/server
            sudo chown -R www-data:www-data /path/in/your/server
            sudo setfacl -R -m u:username:rwx /path/in/your/server

The above deployment configuration configures the user to have full access over the folder for deployment and the configure access for the user www-data which is used by Apache and Nignx.

Once done click Start commit and click Commit new file to complete the setup.

Now you have a deployment configured to be executed whenever a push is made to the speicifc branch.

Conclusion

Now you have learned how to setup and configure GitHub actions workflow for CI/CD.

Thanks for your time. If you face any problem or any feedback, please leave a comment below.