GitHub Contribution Chart Generator Getting Started (2026)

Getting started overview

The GitHub Contribution Chart Generator is a script designed to transform a user's GitHub contribution graph into an SVG animation, often referred to as a "snake" animation, suitable for embedding in a GitHub profile README. This guide outlines the steps for initialization, configuration, and deployment within a GitHub repository. The process primarily involves setting up a GitHub Actions workflow, which automates the generation and update of the animation.

The core functionality relies on GitHub Actions to fetch contribution data, render the animation, and commit the resulting SVG file back to the repository. This approach eliminates the need for manual execution and ensures the animation remains synchronized with a user's latest contributions. Successful setup enables continuous integration for profile updates.

The following table summarizes the key steps:

Create an account and get keys

The GitHub Contribution Chart Generator does not require a separate account or API keys in the traditional sense, as it operates directly within the GitHub ecosystem. To use the generator, you need an active GitHub account and a GitHub repository named after your username (e.g., github.com/your-username/your-username) to serve as your profile README repository. If you don't have one, create a new public repository with the same name as your GitHub username. GitHub automatically recognizes this repository's README.md file as your profile README.

Authentication for accessing your contribution data is handled automatically by GitHub Actions. When a workflow runs on GitHub, it is granted a temporary GITHUB_TOKEN with specific permissions, which is sufficient for fetching your public contribution data and committing changes back to your repository. This eliminates the need to manually generate or manage personal access tokens for this specific use case, simplifying the setup process for GitHub Actions workflows, as explained in the GitHub Actions automatic token authentication documentation.

Your first request

To generate your first GitHub contribution snake animation, you will configure a GitHub Actions workflow. This involves creating a .yml file within your repository's .github/workflows/ directory. The workflow will define the steps to fetch your data, run the generator, and update your repository.

Step 1: Create your profile repository

If you don't already have one, create a new public GitHub repository with the same name as your GitHub username (e.g., octocat/octocat). This repository will host your profile README. For example, if your GitHub username is exampleuser, create a repository named exampleuser. Include a README.md file in this repository.

Step 2: Add the workflow file

Inside your profile repository, create a directory structure .github/workflows/. Within this directory, create a new file, for example, generate-snake.yml. The full path should be .github/workflows/generate-snake.yml.

Populate generate-snake.yml with the following content. Replace username: exampleuser with your actual GitHub username:

name: Generate GitHub Contribution Snake

on: # Schedule daily updates and manually trigger via workflow_dispatch
  schedule:
    - cron: "0 0 * * *" # Runs at 00:00 UTC daily
  workflow_dispatch

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: Platane/snk@master
        id: snake-gif
        with:
          github_user_name: exampleuser # Replace with your GitHub username
          outputs:
            - dist/github-contribution-grid-snake.svg
            - dist/github-contribution-grid-snake-dark.svg?palette=github-dark
      - uses: EndBug/add-and-commit@v7
        with:
          branch: main
          message: 'Generate Contribution Snake'
          add: 'dist/'

This YAML file defines a GitHub Action workflow named "Generate GitHub Contribution Snake". It schedules the job to run daily at midnight UTC and also allows for manual triggering. The workflow checks out your repository, uses the Platane/snk@master action to generate the snake SVG files (both light and dark themes), and then uses EndBug/add-and-commit@v7 to commit these generated files to your main branch within a dist/ directory.

Step 3: Commit and push the workflow file

Save generate-snake.yml and commit it to your main branch. You can do this via the GitHub web interface or using Git commands:

git add .github/workflows/generate-snake.yml
git commit -m "Add GitHub Contribution Snake workflow"
git push origin main

Upon pushing, navigate to the "Actions" tab in your GitHub repository. The workflow "Generate GitHub Contribution Snake" will start running automatically. Monitor its progress to ensure it completes successfully. Once completed, your dist/ directory will contain the github-contribution-grid-snake.svg and github-contribution-grid-snake-dark.svg files.

Step 4: Embed the SVG in your README.md

Edit your README.md file in your profile repository. Add an image tag pointing to the generated SVG. For example:

## My GitHub Stats

![GitHub Contribution Snake](https://github.com/exampleuser/exampleuser/blob/output/github-contribution-grid-snake.svg?raw=true)

---

_Generated daily via [GitHub Actions](https://docs.github.com/en/actions)._

Replace exampleuser/exampleuser with your actual username and repository name. The ?raw=true parameter ensures the SVG is rendered directly as an image rather than linking to the file itself on GitHub. Commit these changes to your README.md. Your GitHub profile page should now display the animated contribution snake.

Common next steps

After successfully generating and embedding your first contribution snake animation, consider these common next steps to further customize your profile or automate other aspects of your workflow:

1. Customize the animation: The Platane/snk action offers various parameters to customize the appearance of the snake animation, such as colors, frames per second, and output formats. Refer to the GitHub Contribution Chart Generator README for a full list of configuration options. You can adjust the with: section in your workflow file to experiment with different themes or styles.

2. Add more stats: Beyond the contribution snake, many developers enhance their GitHub profile READMEs with other dynamic content, such as repository statistics, language usage, or recent activity. Explore other GitHub Actions or external services designed for profile customization to integrate additional data visualizations. For example, some tools can display star counts, follower numbers, or top languages per repository, providing a comprehensive overview of your GitHub activity.

3. Optimize workflow frequency: While a daily update schedule is common, you might adjust the cron schedule in your workflow file (e.g., cron: "0 */6 * * *" to run every six hours) based on how frequently you want your contribution snake to update. Be mindful of GitHub Actions usage limits, though for this simple script, daily updates are generally well within typical free tier allowances. Details on scheduling workflows with cron syntax are available in GitHub's documentation.

4. Explore other GitHub Actions: GitHub Actions can automate a wide range of development tasks, from continuous integration/continuous deployment (CI/CD) to dependency management and code quality checks. This initial setup provides a practical introduction to using Actions. Consider exploring the GitHub Marketplace for Actions to discover more tools that can streamline your development workflow or enhance your project's visibility.

5. Integrate with other developer tools: Consider how your GitHub profile can integrate with other platforms. For instance, you might link to a personal website, a portfolio hosted on a platform like Firebase Hosting, or professional profiles on sites like LinkedIn. Maintaining a consistent online presence across developer communities and professional networks can enhance your personal branding.

Troubleshooting the first call

Encountering issues during the initial setup of the GitHub Contribution Chart Generator is common. Here's how to address frequent problems:

1. Workflow not running:

   • Check file path: Ensure your YAML workflow file is correctly located at .github/workflows/your-workflow-name.yml. Incorrect capitalization or directory structure will prevent GitHub Actions from discovering it.
   • Syntax errors: YAML files are sensitive to indentation. Use a YAML linter or text editor with YAML support to check for syntax errors. Even a single space misalignment can cause the workflow to fail to parse.
   • Branch protection: If your main branch is protected, ensure that "Allow GitHub Actions to create and approve pull requests" is enabled in your repository settings under "Actions > General" if the action needs to create pull requests, or ensure that the workflow has appropriate permissions to push directly to the branch.
   • Manual trigger: Go to the "Actions" tab in your repository, select your workflow, and click "Run workflow" to manually trigger it. This can help diagnose if the scheduled trigger is the issue or if the workflow itself has problems.

2. github_user_name not found or incorrect:

   • Verify that the github_user_name parameter in your generate-snake.yml file exactly matches your GitHub username (e.g., exampleuser, not a display name).

3. SVG file not generated or not committed:

   • Workflow logs: Examine the output logs of the GitHub Action run (accessible via the "Actions" tab). Look for error messages in the steps related to Platane/snk@master or EndBug/add-and-commit@v7. These logs often provide specific reasons for failure, such as missing permissions or issues with the upstream service. The GitHub Actions troubleshooting documentation offers general guidance for interpreting logs.
   • Permissions for GITHUB_TOKEN: Ensure your repository's "Settings > Actions > General > Workflow permissions" is set to "Read and write permissions" or that the specific permissions for the GITHUB_TOKEN allow content writing. By default, it might be set to read-only for new repositories.
   • Branch name: If you are not using main as your default branch, update branch: main in the EndBug/add-and-commit@v7 step to reflect your actual default branch name (e.g., master).
   • Output path: Double-check the outputs: path in the Platane/snk@master step and the add: path in the EndBug/add-and-commit@v7 step. They should match (e.g., dist/).

4. SVG not showing on README:

   • Image URL: Ensure the image URL in your README.md is correct and uses the ?raw=true parameter. The format should be https://github.com/YOUR_USERNAME/YOUR_REPO_NAME/blob/YOUR_BRANCH/dist/github-contribution-grid-snake.svg?raw=true. Replace placeholders with your actual details.
   • File existence: Confirm that the SVG file actually exists in your repository at the specified path (e.g., dist/github-contribution-grid-snake.svg) after the workflow has run successfully.
   • Caching: Browser caching can sometimes prevent immediate display of updated images. Try clearing your browser cache or viewing your profile in an incognito window.