GitHub Visualizer

A Real-Time GitHub commit visualizer inspired by Gource, written in Svelte, vis.js and Ably.

Read about how it was built in my recent blog post

Deploying this application to a supported hosting provider gives you a real-time visualization of the commits to your GitHub organization or repository. It would be perfect for large screens, lobby displays, and places where it might be useful to see your efforts being visualised!

Pre-requisites

• An Ably account and API key.
• A GitHub account with sufficient privileges to add a GitHub Webhook to your account or repository.
• A cloud service for public hosting (we're using Netlify).
• A password of your choice, to secure your webhooks.

Usage Overview

To use this application to visualize your own git commits, you will need to deploy the WebApp (including the bundled GitHub webhook) to a location where GitHub can call it. We suggest Netlify or Azure Static WebApps, which both allow you to deploy a static web application, along with hosting bundled serverless functions from the same repository. This repository is configured to seamlessly run on both Netlify and Azure out of the box without modification.

1. Create an Ably account and API key
2. Create a GitHub account with sufficient privileges to add a WebHook to your account or repository
3. Deploy with either Netlify or Azure Static Web Apps a. Add the env variable ABLY_API_KEY to your deployed app. b. Add the env variable GITHUB_WEBHOOK_SECRET to your deployed app (containing a password you make up)
4. Configure a GitHub Web Hook a. Add a GitHub webhook pointing to your deployed app - https://your-deployed-app.com/api/github-hook (the URL of your app will differ - but the API location will always be the same - /api/github-hook) b. Set the SECRET to the same password you configured in your applications environment variable.
5. Visit the URL and watch your commits fly in!

Getting and Managing an Ably API key

In order to run this app, you will need an Ably API key. If you are not already signed up, you can sign up now for a free Ably account. Once you have an Ably account:

1. Log into your app dashboard.
2. Under “Your apps”, click on “Manage app” for any app you wish to use for this tutorial, or create a new one with the “Create New App” button.
3. Click on the “API Keys” tab.
4. Copy the secret “API Key” value from your Root key, we will use this to configure our app.

This app uses Ably Channels and Token Authentication.

Configuring your Deployment, Ably API keys and Secrets

You'll need to configure settings on both GitHub and your Netlify/Azure to make this application work:

Deployment with Netlify

We've bundled a netlify.toml file in the root of the repository, which will configure your build and deployment settings. You will need to add two environment configuration settings using the netlify UI:

ABLY_API_KEY=your-ably-api-key
GITHUB_WEBHOOK_SECRET=a-secret-password-that-you-make-up

You can configure your secrets in netlify by going to your app dashboard and visiting:

Site Overview > Site Settings > Build and Deploy > Environment > Environment Variables

Click on Edit Variables to add the values for ABLY_API_KEY and GITHUB_WEBHOOK_SECRET.

The rest of the Netlify build is configured via the netlify.toml file included in this repository.

Deployment with Azure Static Web Apps

Use the Azure Portal to create a new Static Web Application, select custom, and use the following configuration values:

    app_location: "/"
    api_location: "api"
    output_location: "dist"

You can either enter these in the Azure Portal UI, or you can directly edit the GitHub build .yml file that gets created in the .github file afterwards if you missed this or made a mistake.

GitHub Setup

You can install GitHub WebHooks on either specific GitHub repositories or the entire organization. The configuration settings are the same regardless.

To configure for your entire organization (i.e. all repositories in the organization) do the following:

• Visit https://github.com/organizations/{your-org}/settings/profile
• Click on Webhooks on the left-hand menu under Code, planning and automation
• Click on Add webhook
• Enter the URL of your deployed app (including the path to the webhook API) into Payload URL e.g. https://your-deployed-app.com/api/github-webhook
• Set the content type to application/json
• Enter a password of your choosing into Secret - there are no password requirements, your password only needs to match the one your chose as your GITHUB_WEBHOOK_SECRET environment variable.
• Enable SSL verification
• Select Just the push event for the WebHook trigger

You can repeat these steps repository-by-repository if you prefer.

Local Development

To run the app locally, once cloned, you will need to create an .env file in root directory, to configure your ABLY_API_KEY and GITHUB_WEBHOOK_SECRET:

ABLY_API_KEY=your-ably-api-key
GITHUB_WEBHOOK_SECRET=a-secret-password-that-you-make-up

Next install the Netlify CLI, to run the serverless functions locally, then install the dependencies and run the start script:

npm install netlify-cli -g
npm install
npm run start

Once running, you can browse to http://localhost:8080

You can also run tests in the CLI:

npm run test

Note: You will need to restart the dev server if you modify your .env file.

Accepting WebHook callbacks in local dev

Because GitHub needs a public URL to send WebHook data to, you'll need to make the github-hook API in this repository accessible to the internet to do local development.

You could:

• Use a service like ngrok for local development - exposing http://localhost:7071 to the internet - and use the Azure Static Web Apps SDK.
• Deploy the app to Netlify - using a deployed instance of the app to accept the WebHook data.
• Deploy the app to Azure Static Web Apps - using a deployed instance of the app to accept the WebHook data.
• Deploy an AWS lambda function with contents of ./api/github-hook to accept the callbacks (unsupported, but achieves the same effect as the previous two suggestions)

Note: The github-hook code contains no logic (it just accepts, verifies and forwards the hook data to an ably channel). You can rely on a deployed instance of this hook as long as your ably API key and channel names are consistent.