Skip to main content

Snake Contribution Animation

The Snake Contribution Animation is a visually unique and engaging way to represent your yearly activity. This feature adds a looping GIF or SVG of a "snake" chasing and consuming your contribution blocks, creating a dynamic element on your profile.

How the Snake Animation Works​

Unlike static image cards, the snake animation is a generated file (usually an SVG). This file must be generated by a script and committed back to your profile repository regularly to stay up-to-date with your latest activity. This entire process is fully automated using a GitHub Action that runs on a schedule.

GitHub Action Setup​

To automate the snake animation, you must create a YAML workflow file named snake.yml inside your profile repository's .github/workflows/ directory.

1. The Workflow File (snake.yml)​

Use the following content for your workflow file. This configuration uses the recommended lowlighter/metrics action, sets it to run daily, and ensures the necessary permissions are granted.

name: Generate Snake Animation

on:
  schedule:
    # Runs at 1 AM UTC every day
    - cron: "0 01 * * *"
  workflow_dispatch:
    # Allows manual trigger via the GitHub Actions tab

jobs:
  generate:
    runs-on: ubuntu-latest
    permissions:
      contents: write # CRITICAL: This grants permission to commit the new file

    steps:
      - uses: actions/checkout@v4
      - uses: lowlighter/metrics@latest # Use the metrics action

        with:
          # REQUIRED: GitHub token (automatically provided by GitHub)
          token: ${{ secrets.GITHUB_TOKEN }}
          
          # Output configuration
          output_name: output/github-snake.svg 
          user: ${{ github.repository_owner }} # Automatically detects your username
          
          # Plugin configuration for the snake
          template: snake
          base: "" # Base is disabled to focus only on the snake plugin
          plugin_isocalendar: yes
          plugin_isocalendar_duration: full-year

Once your workflow runs successfully (you can check the Actions tab on GitHub), the generated file will be saved to your repository. Embed the image in your main README.md using the path where the action saved the file:

My 2024 GitHub Activity​

![Snake Animation](https://raw.githubusercontent.com/YOUR_USERNAME/YOUR_USERNAME/output/github-snake.svg)

(Replace YOUR_USERNAME with your actual GitHub username.)