Complete Guide: Automating Deployment with GitHub Webhooks, Nginx, and Shell Scripts

Avatar photoByAdil

In this guide, we will walk through how to set up an automated deployment system for your project hosted on GitHub. By leveraging GitHub webhooks, nginx, curl, shell scripts, and systemd, we will create a deployment pipeline that automatically triggers the deployment of your application to a VPS whenever you push to your repository. This method requires no programming language and can be set up with basic configuration and shell scripts.

Table of Contents

  1. Setting Up GitHub Webhook
  2. Configuring Your VPS

    • Installing Nginx
    • Creating the Webhook Handler Script
    • Setting Up Nginx to Trigger the Webhook
  3. Testing the Webhook Endpoint
  4. Automating the Deployment
  5. Monitoring Logs
  6. Conclusion

1. Setting Up GitHub Webhook

Steps to Set Up the Webhook:

  1. Go to your GitHub repository:

    • Navigate to your GitHub repository.
    • Go to the Settings tab.

  2. Add a Webhook:

    • Under Settings, scroll down to Webhooks and click Add Webhook.

  3. Configure Webhook Settings:

    • Payload URL: Set this to the URL where your VPS will listen for incoming requests. Example: http://your-vps-ip/webhook.
    • Content Type: Choose application/json.
    • Secret: Set a secret key to validate the authenticity of requests (e.g., my-secret-key).
    • Events: Select the Push events option. This ensures that the webhook is triggered when a push is made to your repository.
    • Click Add Webhook to save the configuration.

Now, your GitHub repository will send a payload to your VPS every time you push changes to the repository.

2. Configuring Your VPS

2.1 Installing Nginx (Web Server)

You need nginx to listen for incoming requests to the /webhook URL and trigger the webhook handler script.

  1. Install nginx:

Run the following commands to install nginx if it is not already installed: 

   sudo apt update
   sudo apt install -y nginx
  1. Start and enable nginx:

Ensure nginx is running: 

   sudo systemctl start nginx
   sudo systemctl enable nginx
  1. Verify nginx installation:

You can verify nginx is running by visiting your VPS IP in a browser or running: 

   sudo systemctl status nginx

2.2 Creating the Webhook Handler Script

This script will be responsible for handling the webhook requests and performing the necessary deployment actions, such as pulling the latest code from the GitHub repository, installing dependencies, and restarting the application.

  1. Create the handler script:

Create a shell script, for example, /var/www/webhook-handler.sh: 

   sudo nano /var/www/webhook-handler.sh
  1. Add the following script content: 
   #!/bin/bash

   # Log the webhook trigger
   echo "$(date): Webhook triggered" >> /var/log/webhook.log

   # Verify GitHub secret (for security)
   read -r body
   received_signature=$(echo "$body" | openssl dgst -sha256 -hmac "my-secret-key" | awk '{print $2}')
   github_signature=$(echo "$HTTP_X_HUB_SIGNATURE_256" | cut -d= -f2)

   if [[ "$received_signature" != "$github_signature" ]]; then
       echo "$(date): Invalid signature" >> /var/log/webhook.log
       exit 1
   fi

   # Run deployment commands
   cd /path/to/project || exit
   git pull origin development >> /var/log/webhook.log 2>&1
   npm install >> /var/log/webhook.log 2>&1
   npm run build >> /var/log/webhook.log 2>&1
   sudo systemctl restart your-app.service >> /var/log/webhook.log 2>&1

   echo "$(date): Deployment completed" >> /var/log/webhook.log
  • Replace /path/to/project with the actual directory path of your project on the VPS.
  • Replace your-app.service with the name of the systemd service managing your app (if using systemd).
  1. Make the script executable: 
   sudo chmod +x /var/www/webhook-handler.sh

2.3 Setting Up Nginx to Trigger the Webhook Script

Now, you will configure nginx to listen to the /webhook URL and trigger the handler script.

  1. Open the nginx configuration:

Open the nginx configuration file to edit: 

   sudo nano /etc/nginx/sites-available/default
  1. Add the following location block:

In the server block, add the following: 

   location /webhook {
       alias /var/www/webhook-handler.sh;
       fastcgi_param HTTP_X_HUB_SIGNATURE_256 $http_x_hub_signature_256;
       include fastcgi_params;
       fastcgi_pass 127.0.0.1:9000;
   }

This tells nginx to trigger the webhook handler script when it receives a request at /webhook.

  1. Reload nginx:

Apply the changes to nginx: 

   sudo systemctl reload nginx

3. Testing the Webhook Endpoint

To verify that everything is set up correctly, you can send a test request to your webhook URL using curl.

  1. Send a test request:

Replace your-vps-ip with your actual VPS IP address, and use your secret key: 

   curl -X POST http://your-vps-ip/webhook -H "X-Hub-Signature-256: sha256=my-test-key" -d "{}"
  1. Check the logs:

If everything is working correctly, you should see a log entry indicating that the webhook was triggered. Check the logs by running: 

   tail -f /var/log/webhook.log

You should see entries like: 

   Sat Dec 15 15:30:00 UTC 2024: Webhook triggered
   Sat Dec 15 15:30:10 UTC 2024: Deployment completed

4. Automating the Deployment

Once the webhook is triggered, the handler script will execute the following deployment steps:

  1. Pull the latest code from the development branch.
  2. Install dependencies (e.g., npm install).
  3. Build the project (e.g., npm run build).
  4. Restart the application using systemd (systemctl restart).

This entire process is automated, and the app will be deployed without any manual intervention once a push occurs on the GitHub repository.

5. Monitoring Logs

After deployment, you can monitor the logs for any issues or to ensure everything is running smoothly:

  1. View the webhook log:

To monitor the output from the webhook handler script, you can run: 

   tail -f /var/log/webhook.log

This will allow you to see real-time updates whenever a new deployment is triggered.

6. Conclusion

By following this guide, you have successfully set up an automated deployment pipeline using GitHub webhooks, nginx, curl, shell scripts, and systemd. This method allows you to deploy your application to a VPS automatically when changes are pushed to your GitHub repository, all without writing custom code.

This setup is ideal for developers who want to automate their deployments using a simple, effective, and low-code solution. It provides a streamlined process for ensuring that your application is always up to date and running smoothly on your server.

Similar Posts