GitHub Automatic Contributation Visualizations

We've seen those fancy G​itHub profile pages with automatically updating graphs, how do they work though?

Images, sometimes SVGs, and even rarely videos is the answer. They actually break down into two categories of assets thoough, ones that we only need to drop a link to in our Markdown files, and the rest that we need to actually generate the asset, have it hosted somewhere, and then link in our Markdown files. This isn't a how-to-link-images in Markdown tutorial though, this is how we use GitHub actions to automatically generate, commit, and push these assets to our repos - allowing us to set them up once and never think about them again!

GitHub Action

To make this easy, I've decided not to actually create my own visulation from scratch, but rather use two existing ones:

• Platane/snk
• yoshi389111/github-profile-3d-contrib

These two are setup to be usable by GitHub actions already, for assets that aren't you'll have to write your own shell commands within your action to generate the assets yourself.

First to create our GitHub Action, we need to add a .yml file to the .github/workflows directory in our repository. This contains two primary sections, on and jobs, representing when the action runs, and what the action does when it runs.

name: generate animation

on:
  # ...

jobs:
  # ...

In addition to these there are many more properties, one you'll like want is a name so we can see what action is running.

When to run

There are a number of events that can be added to the on section that can trigger the action, from cron-schedules, to pushes to branchs, even to manual button pressed:

  # every midnight
  schedule:
    - c​ron: "0 0 * * *"

  # every push on the main branch
  push:
    branches:
    - main

  # when manually dispatched
  workflow_dispatch:

There is nothing missing from workflow_dispatch, it can be provided custom arguments for custom inputs, but as this example has none, it is complete.

What to run

The actual tasks the action runs is determined by the jobs section, while it supports multiple jobs we are only going to use one:

jobs:
  generate:
    runs-on: ubuntu-latest

    steps:
      -

Here we define the name of the job, what operating system it runs these steps on, and an array of steps for it to run.

- name: generate github-contribution-grid-snake.svg
  uses: Platane/snk/svg-only@v2
  with:
    github_user_name: ${{ github.repository_owner }}
    outputs: |
      dist/github-contribution-grid-snake-light.svg
      dist/github-contribution-grid-snake-dark.svg?palette=github-dark
- uses: yoshi389111/github-profile-3d-contrib@0.6.0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    USERNAME: ${{ github.repository_owner }}
- name: push github-contribution-grid-snake.svg to the output branch
  uses: crazy-max/ghaction-github-pages@v2.6.0
  with:
    target_branch: output
    build_dir: .
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Each step of the steps array can contain a name, uses if it's using an already-created action, with to pass arguments to already-created action, and finally env to set environment variables.

If you need to run your own commands, you can also provide a multiline string to the run property.

As you can see there are three actions here, one to generate the snake, one to generate the 3D contributation graph, and a third to push these assets to the output branch of the repository.

If you wish to have this done on an existing branch, you'd need to first checkout that branch, which while it's not difficult to do with another action, isn't required for this example.

Each action had it's own GitHub repo and action page, which lists all the configurables and how to use them, but one thing that isn't obvious is that in order for an action to be able to make commits or any change to the current repo, it needs to be given write access.

This can be granted by going to Settings, then Actions, General, and finally by scrolling to the Workflow permissions section and changing the selection from Read repository contents permission to Read and write permissions.

Using the Assets

Now as these assets are on another branch, you will need to link to them both absolutely and in their raw forms - easiest way to get these absolute raw URLs it by navigating to the file and clicking the Raw button located beside the Delete and Edit buttons, giving you a URL in this format:

https://raw.githubusercontent.com/OWNER/REPO/BRANCH/PATH/FILENAME

which you can use Markdown to directly link to!

Advanced Usages

This is the least that GitHub actions is capitable of, but if all you desire is images that automatically update on their own, or have tried using these libraries locally without success, then this is as far as you'll need to go!