Short answer: A README cannot run code, so a GitHub Actions workflow in your profile repository draws the snake once a day as an SVG file and saves it to the repository; the README then shows that file as a picture. Add the workflow, run it once from the Actions tab, and put a <picture> with a light and a dark version in your README.
The snake is the moving line that crawls across a contribution graph and eats the green squares. It looks like a live widget, but it is an ordinary animated SVG picture made fresh every day from your contribution calendar.
What do you need first?
A profile README: a public repository with exactly your username as its name (octocat/octocat), with a README.md at the top. GitHub shows that file on your profile. How to make a GitHub profile README covers it step by step.
Which workflow draws the snake?
The best-known one uses the open-source Platane/snk action. Its author's own example, with the time moved off the full hour, saved as .github/workflows/snake.yml in your profile repository:
name: generate animation
on:
schedule:
- cron: "20 4 * * *"
workflow_dispatch:
jobs:
generate:
permissions:
contents: write
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: generate github-contribution-grid-snake.svg
uses: Platane/snk/svg-only@v3
with:
github_user_name: ${{ github.repository_owner }}
outputs: |
dist/github-contribution-grid-snake.svg
dist/github-contribution-grid-snake-dark.svg?palette=github-dark
- name: push github-contribution-grid-snake.svg to the output branch
uses: crazy-max/ghaction-github-pages@v3.1.0
with:
target_branch: output
build_dir: dist
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}What each part does:
| Part | What it does |
|---|---|
cron: "20 4 * * *" | Runs every day at 04:20 UTC |
workflow_dispatch | Adds a Run workflow button, for the first run |
contents: write | Lets the workflow save files to your repository |
svg-only@v3 | Draws the snake as SVG (faster than the version that can also make a GIF) |
outputs | A light and a dark picture |
| The last step | Saves the pictures to a separate branch called output |
Why 04:20 and not midnight? GitHub's docs say scheduled runs can be delayed at times of high load, especially at the start of every hour, so a time in the middle of the hour is safer.
How do you show the snake in your README?
After the first run (Actions, the workflow, Run workflow), the pictures exist on the output branch. Show them with a <picture>, so dark-mode visitors get the dark one; replace USER with your username:
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/USER/USER/output/github-contribution-grid-snake-dark.svg" />
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/USER/USER/output/github-contribution-grid-snake.svg" />
<img alt="Contribution snake eating my GitHub contribution graph" src="https://raw.githubusercontent.com/USER/USER/output/github-contribution-grid-snake.svg" />
</picture>Until the workflow has run once, those addresses do not exist and the README shows a broken picture. Dark mode images in a GitHub README explains the <picture> trick in more detail.
How do you change the snake's colours?
Add options to each output line, like a web address:
outputs: |
dist/github-contribution-grid-snake.svg?color_snake=orange&color_dots=#ebedf0,#bfd6f6,#8dbdff,#64a1f4,#3c7dd9color_snake is the snake. color_dots takes exactly five colours: an empty day first, then from the fewest contributions to the most. palette picks a preset: github, github-dark or github-light.
Why did my snake stop updating?
| What you see | Why | Fix |
|---|---|---|
| It stopped after about two months | GitHub turns off scheduled workflows in a public repository after 60 days without activity | Actions, the workflow, Enable workflow |
| The run fails at the push step | The workflow may not write to the repository | Keep permissions: contents: write in the workflow |
| A broken picture in the README | The workflow has not run yet, or the username in the address is wrong | Run it once by hand; check the address |
| The run starts late | Scheduled runs wait at busy times | Nothing to fix; it catches up |
Where can you check this?
Can you add the snake without an outside action?
Profile README Studio has a contribution snake block with your choice of snake colour and six dot palettes (GitHub green, blue, purple, pink, Halloween and grey). It writes a workflow that draws the snake with its own code and the repository's own token, so no other action or server is involved, saves a light and a dark picture, and writes the README code for both. Run the workflow once from the Actions tab after adding it.
