Setting Up a GitHub Webhook with NGINX and Ubuntu

As I set up my new site + blog I took some notes on the process that might be helpful or interesting to share as a reference.

These steps are how I configured this site to deploy whenever I push changes to its GitHub repository. For these instructions I am using the Zola static site generator, a virtual private server running Ubuntu and NGINX hosted on Linode, and GitHub. However, the general concept applies to any script you want to run as a response to a webhook event.

Step 1: Write your automation script

Create a script. Here's a sample for my site, used from the excellent tutorial at osc.garden.

#!/usr/bin/env bash
set -eo pipefail

project_dir="/path/to/project-directory"
out_dir="/path/to/output-directory"

cd "$project_dir"
git pull
git submodule update
zola build --output-dir "$out_dir" --force

Make the file executable:

chmod +x /path/to/project-directory/update-script.sh

Notes: It probably goes without saying, but make sure you install all the tools and files used for your script / project. In my case this involves:

• Zola — sudo snap install --edge zola
• GitHub CLI — see install instructions in documentation; authenticate with gh auth login and follow the steps
• GitHub repository cloned to project directory — gh repo clone your-github-username/your-repo-name

I saved the script in a directory where I'll put related files for the project.

Step 2: Install webhook

Webhook is available on GitHub. This is what will listen for the webhook event from github and run the script.

sudo apt-get install webhook

Step 3: Create a hooks.json file

Create a hooks.json file in your project directory with the following content:

[
  {
    "id": "your-webhook-url",
    "execute-command": "/path/to/project-directory/update-script.sh",
    "command-working-directory": "/path/to/project-directory",
    "trigger-rule": {
      "and": [
        {
          "match": {
            "type": "payload-hmac-sha256",
            "secret": "your-secret-token",
            "parameter": {
              "source": "header",
              "name": "X-Hub-Signature-256"
            }
          }
        }
      ]
    }
  }
]

Notes:

• id is part of the URL that the webhook server listens on - name this something descriptive!
• execute-command is the script to run when the webhook is fired
• trigger-rule is a configuration that can be set up to require the incoming webhook request to contain a specific payload; this is a form of security so that only requests with the correct secret are handled by the webhook server (that said, please read the webhook docs if you are unsure about anything - this is not security advice!)
  • you can provide a passphrase here under secret
  • you can provide the hash to use under type
  • seriously please look at the webhook docs

Step 4: Set up NGINX as a proxy

You can run webhook using the following command: /path/to/webhook -hooks /path/to/your-git-repo/hooks.json -verbose. It will start up on port 9000 and provide you with one HTTP endpoint.

If you wanted to, you could open port 9000 on your server / firewall and set up TLS certificates so webhook can use HTTPS. However! I opted to use NGINX as a proxy instead. I already have NGINX set up with my TLS certificates, the firewall is already configured, etc. So, I used the following NGINX configuration:

location /hooks/ {
proxy_pass http://localhost:9000/hooks/;
}

Note: I chose to use localhost instead of 127.0.0.1 or ::1 because I will let my server figure out whether to use IPv4 or IPv6. Networking!

Step 5: Set up webhook as a service

Create a webhook.service file in /etc/systemd/system/webhook.service with the following content:

[Unit]
Description=Webhook for updating your-site.com
After=network.target

[Service]
Type=simple
User=your-username
ExecStart=/usr/bin/webhook -hooks /path/to/project-directory/hooks.json -verbose
Restart=on-failure
RestartSec=5s
StandardOutput=journal
StandardError=journal
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable webhook
sudo systemctl start webhook

Verify that the service is running:

sudo systemctl status webhook

Having this run as a service is important so it starts up after server reboots — keeping your server ready to receive webhook calls!

Step 6: Set up webhook in GitHub

Go to your GitHub repository settings, navigate to Webhooks, and add a new webhook with the following details:

• Payload URL: https://your-site.com/hooks/your-webhook-url
• Content type: application/json
• Secret: your-secret-token

Step 7: Deploy!

And there you have it! Your webhook is set to automatically run whenever you push changes to your repository. Have fun!