Use Platane’s snk GitHub Action to turn a GitHub contribution graph into an animated snake, then commit the generated SVG or GIF where your README can load it. A scheduled workflow can regenerate the files daily, while a <picture> element can switch between light and dark SVG versions.
The reliable setup is: create the correct profile or documentation repository, add a workflow using Platane/snk@v3, grant it permission to write generated assets, verify the files directly, and embed those files with Markdown or HTML.
As an Amazon Associate I earn from qualifying purchases.
What the GitHub contribution snake actually shows
snk reads the contribution graph for a selected GitHub username and renders the graph’s cells as a snake-game animation. The project can generate animated SVG and GIF files, and its GitHub Action can run on a schedule so the image remains current.
The animation is a visual representation of GitHub’s contribution record, not an independent event log. GitHub defines the graph as a record of contributions made to repositories on GitHub. Contributions are timestamped in Coordinated Universal Time (UTC), so a contribution made near midnight can appear on a different calendar day from the one shown by your local clock.
#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.
Repository creation and forking always count as contributions. Issues, pull requests, reviews, discussions, discussion answers, and commits count only when GitHub’s qualifying conditions are met. For a commit, the 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 such as collaborator, organization member, fork owner, or issue or pull-request participant.
Private activity may be displayed as anonymized counts to people who cannot access the relevant repositories. Viewers outside an organization can likewise see anonymized organization contribution activity. The snake therefore summarizes the graph that GitHub exposes to the viewer; it is not a complete audit of every repository event.
Choose where the generated files will live
The image can be displayed in several kinds of README, but the repository and publishing arrangement determine the path you use in Markdown.
Recommended Free Tools
| Use case | Where to place the files | Practical implication |
|---|---|---|
| Personal profile README | The public repository whose name exactly matches the GitHub username | Relative image paths are simple because the README and generated assets can share a branch. |
| Repository README | The repository that owns the README, or a separate public asset repository | Keep the generated files in the same repository for relative paths, or use a stable public URL when the assets are elsewhere. |
| Organization README | The organization’s public profile or documentation repository | Every viewer must be able to reach the image URL; private or permission-dependent assets will not render for everyone. |
| Dedicated output branch | A branch containing only generated assets | This keeps the default branch tidy, but the README must reference a stable raw or hosted URL for that branch. |
For a personal profile, GitHub recognizes the profile README only when the repository is public and its name exactly matches the account username. For a repository or organization README, the same embedding pattern works as long as the generated file is publicly reachable.
Decide between SVG, GIF, and theme-aware output
| Choice | Best fit | Trade-off |
|---|---|---|
| Animated SVG | Most README use cases | Usually smaller than a raster animation and sharp at different display sizes. |
| GIF | Places that need an animated raster image or a configurable background | Typically larger and less flexible for dark/light theme switching. |
| One image | Simple documentation or a fixed visual style | The same colors appear in both GitHub light and dark modes. |
Light and dark SVGs in <picture> |
Profile and project READMEs viewed in both themes | Requires two generated files and correct source paths. |
Start with an SVG unless a consuming site specifically requires GIF. You can generate more than one output in a single run, including a normal SVG, a dark-palette SVG, and a GIF.
Prerequisites and decisions before creating the workflow
- Use a repository where the README is stored and where the workflow can write generated files.
- Decide whether assets belong on the default branch or a separate output branch.
- Confirm that the image URL will be public if people outside the repository or organization must see it.
- Choose the username whose graph should be rendered.
${{ github.repository_owner }}is the usual value when the repository owner is also the subject of the animation. - Plan a scheduled run if the image should update without manual intervention.
Repository permissions are a frequent cause of failure. The workflow needs permission to write repository contents when it commits files or publishes an output branch. Branch protection, organization policy, or a disabled Actions workflow can still block a write even when the YAML appears correct.
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.
Step-by-step: generate and commit the snake in the repository
1. Create or open the target repository
For a profile README, create or use the public repository named exactly for the username. For a project or organization README, open the repository that contains that README. The generated files can live beside the README, which allows short relative image paths.
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 →2. Add the workflow file
Create .github/workflows/contribution-snake.yml with this example. It supports a manual run, a daily scheduled run, SVG and GIF output, and a commit back to the current branch.
name: Generate contribution snake
on:
workflow_dispatch:
schedule:
- cron: '17 0 * * *'
permissions:
contents: write
jobs:
snake:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Generate SVG and GIF
uses: Platane/snk@v3
with:
github_user_name: ${{ github.repository_owner }}
outputs: |
github-snake.svg
github-snake-dark.svg?palette=github-dark
github-snake.gif
- name: Commit generated assets
run: |
git config user.name 'github-actions[bot]'
git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
git add github-snake.svg github-snake-dark.svg github-snake.gif
git diff --cached --quiet || (git commit -m 'Update contribution snake [skip ci]' && git push)The github_user_name input selects the graph to render. Replace it with a specific username when the repository owner and the person represented by the animation are different. The output list asks snk to create three files; remove the GIF line if you do not need a raster version.
3. Run it once manually
Commit the workflow, open the repository’s Actions tab, select Generate contribution snake, choose Run workflow, and start the job. A successful run should leave the generated files in the branch checked out by the workflow. Open each file from the repository interface before editing the README.
4. Confirm the write permission
The top-level permissions block requests contents: write. If repository or organization policy prevents that permission, the generation step may succeed while the commit or publication step fails. In that case, allow the workflow to write contents, use an approved publishing branch, or have an administrator adjust the repository’s Actions policy.
Free tools Windows power users keep installed
One-click scans. No signup required.
Embed the animation in a README
One SVG or GIF
If the generated asset is on the same branch as the README, use a relative path:
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.
Use ./github-snake.gif for the GIF. Relative paths avoid hard-coding an account name and work well when the README and asset are committed together.
Light and dark versions
Use HTML’s <picture> element to let GitHub choose an SVG according to the viewer’s color-scheme preference:
<picture>
<source media='(prefers-color-scheme: dark)' srcset='./github-snake-dark.svg'>
<source media='(prefers-color-scheme: light)' srcset='./github-snake.svg'>
<img alt='Animated GitHub contribution snake' src='./github-snake.svg'>
</picture>The final <img> is the fallback. Check that both source files exist at exactly those paths; a typo in either path can make the dark-mode version disappear even though the light image works.
Assets on an output branch or separate host
When generated files are published to an output branch, copy the branch’s stable raw or hosted asset URLs into the README instead of using relative paths that point at the wrong branch. Open each URL directly in a browser first. The direct test separates a hosting or publishing problem from a Markdown problem.
Keep the image current with scheduling
The schedule in the example runs once per day at 00:17 UTC. GitHub schedules use UTC, and the actual start can be delayed when Actions capacity is busy. The workflow_dispatch trigger remains useful when you want an immediate refresh after a contribution or a configuration change.
A scheduled job updates only when it can complete the whole pipeline: the workflow must be enabled, snk must receive the intended username, the generated output must be written to the expected path, and the commit or branch publication must have write access. A schedule alone does not make a file update if any of those stages fails.
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
Customize the animation without changing the graph
snk supports customization of the snake, contribution-dot, and background colors through its output options. Keep the graph data and the visual styling conceptually separate: changing a palette does not add contributions or alter GitHub’s eligibility rules.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors- Use the default palette when you want the image to resemble GitHub’s contribution graph.
- Generate a dark-palette SVG for dark-mode backgrounds rather than forcing a light asset into every theme.
- Use GIF when you need a raster animation or a configurable background and the larger file is acceptable.
- Keep the alternative output names explicit, such as
github-snake-dark.svg, so README paths remain understandable.
If an output option is malformed, snk may fail before producing the file. Add one output at a time while customizing, run the workflow manually, and confirm the generated asset before adding more variants.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Using the same snake in repositories and organizations
The profile README is the documented showcase, but the underlying mechanism is ordinary Markdown image embedding. A repository README or an organization README can display the same generated SVG or GIF when its URL is public and stable.
For a project repository
Generate the graph for the repository owner, a maintainer, or another account whose contributions you intentionally want to show. Store the asset in that repository for a relative link, or publish it separately when several repositories should reuse one file. Make the alt text describe the image rather than implying that it is a complete activity report.
For an organization
Decide whether the snake represents one account or an organization-facing account. Viewers without access to private organization repositories may see anonymized activity, and organization contribution visibility can be affected by SAML single sign-on session state. Test the README while signed out or with a viewer account that has the same access level as your intended audience.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11For several READMEs
One stable public asset URL can be embedded in multiple READMEs, but every consumer then depends on the same publishing job. If different projects need different colors or usernames, generate separate outputs with unambiguous filenames.
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.
Why contributions can be missing
An apparently empty day is not automatically an animation defect. Check the graph itself and then check the conditions that make an event count:
- The commit author email may not be associated with the GitHub account.
- The commit may be on a branch other than the default branch or
gh-pages. - The account may lack the qualifying relationship to the repository, such as collaborator, organization member, fork owner, or issue or pull-request participant.
- Private or organization activity may be anonymized for the viewer.
- The UTC timestamp may place the event on a neighboring day.
- The workflow may be rendering a different username than the one you inspected.
Compare the GitHub profile graph with the generated image after the workflow has completed. snk cannot display a contribution that GitHub does not expose in the selected account’s graph.
Troubleshooting checklist
The SVG or GIF was not produced
- Open the failed workflow run and identify whether the failure is in the snk step or a later publishing step.
- Confirm the Action reference is
Platane/snk@v3and that the workflow is enabled. - Check spelling and indentation under
github_user_nameandoutputs. - Run the workflow manually after reducing the output list to one SVG.
The file exists but the README is blank
- Open the generated file directly from the repository or its published raw URL.
- Compare the README path with the filename and branch, including capitalization.
- If using
<picture>, verify both<source>URLs and the fallback<img>URL. - Replace the relative path with the direct public asset URL temporarily to isolate a path issue.
The image never changes
- Check that the scheduled workflow is enabled and that a recent run completed successfully.
- Confirm the workflow can write the output branch or commit to the target branch.
- Verify that the selected username is correct.
- Open the newest generated file directly rather than relying on an old README preview.
Dark mode is wrong
Ensure the dark SVG was actually generated with the dark palette option, that its URL exists, and that the dark <source> appears before the fallback image. If the dark file is missing, the browser will use the fallback light asset.
Which setup should you use?
For one profile or project, commit an SVG beside the README and schedule the workflow daily. Add a second dark SVG when the README is viewed in both themes. Use a GIF only when its raster format or background controls solve a specific display requirement. For protected default branches or many consuming READMEs, publish generated files to a dedicated output branch or another stable public host, then test the direct asset URLs before changing Markdown.
This arrangement keeps the implementation small while respecting what the animation can and cannot say: it is an automatically refreshed visual summary of GitHub’s contribution graph, governed by GitHub’s UTC timestamps, eligibility rules, privacy settings, and the username supplied to the workflow.
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.
