iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
You can add an animated contribution snake to a GitHub profile README, a repository README, or an organization README by running the Platane/snk@v3 GitHub Action. The action reads a selected user’s contribution graph and generates an SVG, GIF, or both. You then publish those files from a stable branch or public asset location and embed them with Markdown. A scheduled workflow can regenerate the files daily.
The animation is a visual rendering of GitHub’s contribution graph, not an independent activity audit. Missing cells can be caused by GitHub’s contribution rules, UTC date boundaries, an incorrect username, organization privacy settings, or workflow permissions.
What the GitHub contribution snake shows
Platane’s snk project converts the cells in a GitHub user’s contribution graph into a snake-game animation. The generated artwork is normally an animated SVG or GIF. The snake moves through the contribution cells, consuming dots and producing a compact visual summary suitable for a README.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →GitHub describes the underlying graph as “a record of contributions you’ve made to repositories on GitHub.” The graph is therefore limited to activity GitHub recognizes as a contribution. It is not a complete list of every commit, issue comment, deployment, or private repository event associated with a person.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Contribution rules that affect the picture
GitHub counts repository creation and forking as contributions. Issues, pull requests, reviews, discussions, discussion answers, and commits count when their eligibility conditions are met. For a commit to appear, its author email must be associated with the GitHub account, the commit must be on the repository’s default branch or gh-pages, and the user must have a qualifying relationship with the repository, such as being a collaborator, organization member, fork owner, or issue or pull-request participant.
GitHub timestamps contributions in Coordinated Universal Time (UTC), not in your local time zone. A commit made near midnight can consequently appear on the adjacent day in the graph. Private activity can be shown to people without repository access only as anonymized counts, so a public README may display activity without revealing the private repository or its details.
Choose where the image will be displayed
Profile README
A profile README lives in a repository whose name exactly matches the GitHub username. If the username is alex, the profile repository is alex. Its README is shown on the user’s profile, making it the most common location for a contribution snake.
Repository README
Any repository README can embed the generated asset. This is useful for a project owner who wants to show the owner’s activity, a maintainer team’s selected account, or a project-specific account. Set the action’s username explicitly when the repository owner is not the person whose graph you want to render.
Organization README
An organization can use the same Markdown image pattern if the generated file is publicly reachable. The source documentation demonstrates profile usage; applying it to an organization or project README is the same asset-hosting and Markdown process. Decide which account should be represented, because the action renders one selected GitHub username at a time.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Organization visibility has an additional limitation: GitHub says organization activity can be affected by SAML single sign-on session state, and viewers outside an organization may see anonymized organization contribution activity.
Create the workflow
Store the workflow in the repository that will own or publish the generated files. The path must be under .github/workflows/; for example, .github/workflows/contribution-snake.yml.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →- Open or create the target repository. Use the profile repository for a profile README, or the repository that contains the README you want to update.
- Create the workflow directory. In the repository editor, choose Add file → Create new file, enter
.github/workflows/contribution-snake.yml, and continue. - Add a scheduled workflow. The following configuration runs at midnight UTC every day and can also be started manually. It renders both SVG and GIF files.
name: Generate contribution snake
on:
schedule:
- cron: "0 0 * * *"
workflow_dispatch:
jobs:
generate:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Generate snake animation
uses: Platane/snk@v3
with:
github_user_name: ${{ github.repository_owner }}
outputs: |
dist/github-contribution-grid-snake.svg
dist/github-contribution-grid-snake.gif${{ github.repository_owner }} selects the owner of the repository running the workflow. For a repository owned by an organization, that value is the organization name, not an individual contributor. Replace it with a specific username when the image should represent someone else.
The contents: write permission is important when a later publishing step commits the generated files to an output branch. Repository settings can restrict the default workflow token, so check the repository’s Settings → Actions → General configuration if a run can generate files but cannot push them.
Publish the generated files
The action creates files in the runner’s dist directory. A README needs a stable, publicly reachable URL, so publish that directory to an output branch or another public asset host. The exact publishing step depends on the branch strategy you choose; the upstream snk examples publish generated output separately from the source branch.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Output-branch approach
- Create an output branch, commonly named
outputorgh-pages. - Configure the workflow’s publishing step to replace the files in that branch with the contents of
dist. - Allow the workflow token to write repository contents. If branch protection blocks the push, permit the workflow’s GitHub App or use a branch that accepts automated updates.
- After the first successful run, open the raw URL for each generated file directly. Confirm that the server returns an image rather than an HTML page or a permission error.
Keep the output branch stable. If you rename it or move the files, every README reference must be updated. A stable branch also lets the daily schedule replace the same filenames without editing the README.
Recommended Free Tools
Manual publication for a one-time image
For a static demonstration, download the generated SVG or GIF from a successful workflow run, commit it to a public directory in the repository, and reference that file from the README. This avoids a publishing branch but does not keep the graph current unless you repeat the process.
Embed the snake in a README
Use a normal Markdown image reference once the public asset URL works:
Replace the example URL with the raw URL of your published SVG. Do not use a workflow-run page URL; that page is not an image and can require authentication.
Serve dark and light versions
Generate two SVG variants, one using the normal palette and one using a dark palette, then select between them with HTML’s <picture> element:
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://your-public-asset-host.example/github-contribution-grid-snake-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://your-public-asset-host.example/github-contribution-grid-snake.svg">
<img alt="Animated GitHub contribution snake" src="https://your-public-asset-host.example/github-contribution-grid-snake.svg">
</picture>The fallback <img> should point to the light asset so readers whose clients do not evaluate the media queries still see an image. Verify that both source URLs are reachable; a missing dark file can make the image disappear when a reader switches themes.
SVG or GIF: which output should you use?
| Consideration | SVG | GIF |
|---|---|---|
| File type | Animated vector image | Animated raster image |
| Typical size and scaling | Typically smaller and remains sharp at different sizes | Pixel dimensions are fixed; scaling can soften edges |
| Theme handling | Easy to provide separate light and dark variants with <picture> |
Uses a configured background and normally needs separate files for different themes |
| Best use | Most profile and project READMEs | Clients that handle animated raster images more consistently |
| Customization | Snake, dots, background, and palette can be configured through snk output options | Snake, dots, background, and palette can also be configured; the background is part of the raster frames |
There is no universal requirement to publish both formats. SVG is generally the practical default for a README because it scales cleanly and works well with separate theme variants. Add a GIF when you need a raster fallback or when a particular renderer does not animate the SVG as expected.
Customize colors and the animation
snk supports color customization for the snake, contribution dots, and background. The output declaration is where you request variants and pass options. Keep the contrast high enough that the least active cells remain visible on both light and dark backgrounds.
Use the default palette first to establish a working pipeline. Then make one change at a time and rerun the workflow manually. This isolates a malformed output option from a publishing or permission failure. Avoid colors that convey a contribution level more strongly than GitHub’s original graph; the animation should remain a readable summary rather than imply activity that the graph does not contain.
Keep the image current
The scheduled trigger in the example runs once per day. GitHub Actions schedules use UTC, so 0 0 * * * means midnight UTC rather than midnight in your local time. A daily run is sufficient for a profile graphic because the underlying graph changes incrementally and GitHub may itself take time to process new activity.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Use Actions → your workflow → Run workflow to regenerate immediately after changing the username, colors, output filenames, or publishing branch. Check the run log, then open the raw asset URL and reload the README. Browser or CDN caching can make a newly generated file appear unchanged for a short period; verify the file’s timestamp or content before changing the workflow again.
Troubleshoot a missing or stale snake
The workflow never starts
- Confirm the YAML file is under
.github/workflows/and has a.ymlor.yamlextension. - Check that Actions are enabled for the repository and that the workflow is not disabled.
- Use Run workflow to test manually; scheduled events can be delayed by GitHub’s queue.
The run succeeds but no SVG or GIF appears
- Confirm the
github_user_namevalue is spelled exactly as the GitHub username. A repository owner expression selects the owner, which may be an organization. - Check the output path and filename. The README URL must match the generated path character for character.
- Inspect the publishing step and its destination branch. A successful generation step does not prove that the files were pushed.
The workflow cannot update the output branch
- Verify that the job has
contents: writepermission. - Review repository-level Actions settings for a read-only default token.
- Check branch protection rules, required reviews, and restrictions on GitHub Actions pushes.
- Confirm the publishing step targets the intended branch and repository.
The README shows a broken image
- Open the generated raw asset URL directly in a private browser window.
- If the URL returns HTML, a login page, or a 404 response, fix hosting or permissions before editing Markdown.
- Check for case-sensitive filename and branch mismatches.
- For theme-aware markup, test both the dark and light
<source>URLs and the fallback<img>.
The graph appears to miss contributions
First check GitHub’s eligibility rules rather than treating the animation as defective. The commit email may not be associated with the account; the commit may be on a non-default branch; or the account may not have a qualifying relationship with the repository. Fork activity, private-repository visibility, and organization access can also change what a viewer sees. UTC timestamps can move an event to a neighboring day. The snake can only reproduce the graph returned for the selected username.
Privacy and organization considerations
Publishing the animation does not expose the names of private repositories. Viewers without access see private activity only as anonymized contribution counts. Nevertheless, the pattern can reveal when an account is active, so consider whether an organization or personal profile should display it.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
For organization-owned repositories, SAML SSO session state can affect organization activity shown in GitHub. An external viewer may see anonymized organization contributions even when an internal member sees more detail. Test the published README while signed out and while signed in with the permissions your audience is likely to have.
Decide on an implementation
| Requirement | Recommended choice | Reason |
|---|---|---|
| Current profile graphic with minimal maintenance | Daily scheduled Action publishing SVG | Regenerates automatically and keeps a stable README URL |
| Light and dark GitHub themes | Two SVG outputs plus <picture> |
Each theme receives an appropriate palette |
| One-time project showcase | Generate once and commit the asset | No scheduled workflow or branch publishing is needed |
| Organization README | Explicit username and publicly reachable output branch | Avoids accidentally rendering the organization owner and works for external viewers |
| Maximum compatibility with a raster-only renderer | Publish GIF, optionally alongside SVG | Provides an animated raster fallback |
Whichever option you choose, document the selected username and output filenames in the repository so another maintainer can diagnose a stale image without guessing. Treat the final animation as a visual summary of GitHub’s contribution graph, with GitHub’s eligibility, privacy, organization, and UTC rules determining what it can show.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
