GitHub Automatic Contributation Visualizations
We've seen those fancy GitHub 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:
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:
- cron: "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!