Octogriffin Logo

Setting up Ngrok

GitHub needs to send webhooks to your machine to trigger events. Since localhost isn't accessible from the internet, we use ngrok to create a secure tunnel.

Why do we use Ngrok?
While GitHub provides a tool called smee-client, we prefer ngrok because it provides a Static Domainon the free plan. This means you don't have to update your GitHub App settings every time you restart your computer.
1

Install Ngrok CLI

Download and install the ngrok command line tool for your operating system from the official website.

Go to ngrok.com/download
2

Create Account & Authenticate

Create a free account on ngrok.com. Once logged in, copy your Authtoken from the dashboard and run:

ngrok config add-authtoken YOUR_TOKEN
3

Locate Static Domain

Ngrok automatically assigns a free static domain to your account. You can find it in the dashboard under Universal Gateway > Domains. It will look something like:

corgi-giving-purely.ngrok-free.dev
4

Configure Tunnel Agent

Instead of typing long flags every time, we will define a persistent configuration. Open your ngrok configuration file:

ngrok config edit

Add the following block to the end of the file. Be sure to replace the domain with the one you found in Step 3.

version: "3"
agent:
  authtoken: ... (already here)
tunnels:
  octogriffin:
    proto: http
    addr: 3000
    domain: YOUR_DOMAIN.ngrok-free.dev
5

Start the Tunnel

Now you can start your tunnel with a single short command:

ngrok start octogriffin

Your tunnel is now active at https://YOUR_DOMAIN.ngrok-free.dev. This URL will remain the same every time you run this command.

6

Update GitHub App

Now tell GitHub to send events to this URL.

  1. Go to your GitHub Apps settings.
  2. Click Editnext to your "Octogriffin (Dev)" app.
  3. Scroll down to Webhook URL.
  4. Paste your ngrok URL with the API path appended:
https://YOUR_DOMAIN.ngrok-free.dev/api/v1/webhook
Something went wrong?
Open an Issue on GitHub →