SandeepKomal

Posted on Oct 16

I turned my GitHub year into a 3D solar system for my profile README

#showdev #github #githubactions #opensource

GitHub's contribution graph is a grid of green squares. It's useful, but it doesn't tell much of a story, and everyone's looks the same.

So I built Git3D Universe: a free GitHub Action that turns your year of contributions into a small 3D solar system, drawn as one self-contained SVG for your profile README.

⭐ Source (MIT): github.com/SandeepKomal/Git3D-Universe

What's in the picture

🥧 Your year as a 3D pie. One wedge per month, read clockwise like a clock face. Each wedge rises with that month's contributions and carries its name.
🏆 Your busiest month in gold. It's outlined, with its name and total floating above the pie.
🪐 Your repos as planets. Your top repositories orbit the pie, sized by stars, passing behind it on the far side and in front of it on the near side. The most-starred one gets rings.
📊 Your contribution mix. A small upright 3D pie in the corner shows how your year splits between commits, pull requests, issues and code review, with each share labelled, so it never depends on colour alone. The four colours were checked for colour-blind separation.
📅 Your peak day in a glass card in the corner.
✨ A glowing core in the middle, and planets that orbit with plain CSS animation.

Day and night, in your own timezone

There are two themes:

aurora: deep space, with a navy sky, stars and nebulas.
daylight: a soft dawn sky with the same colour wheel (teal, sky, indigo, violet, rose and gold).

The example workflow checks once an hour, works out the time in your timezone, and switches between them. Your profile is daylight during your day and deep space at night.

Add it to your profile in 2 steps

You need a profile repository: a public repo with the same name as your username (your-username/your-username).

Step 1: add the workflow

Create .github/workflows/git3d-universe.yml in your profile repo. The full workflow, with timezone switching and checks on the generated image, is in the README. The core of it is one step:

- name: Generate Git3D Universe
  uses: SandeepKomal/Git3D-Universe@v2.0.0
  with:
    username: ${{ github.repository_owner }}
    github-token: ${{ secrets.GITHUB_TOKEN }}
    theme: aurora            # or daylight
    output: profile/git3d-universe.svg

Set your timezone at the top of the workflow (for example Asia/Kolkata, America/New_York or Europe/London). Then open the Actions tab and run Git3D Universe once by hand.

Step 2: show it in your README

![Git3D Universe](./profile/git3d-universe.svg)

That's it. The workflow keeps the image up to date and commits it only when something changed.

Built to be trusted

A profile widget runs on your repo every hour, so I kept it small and boring where it matters:

No hosted rendering service. The image is drawn inside your own GitHub Actions run. Data comes straight from GitHub's GraphQL API.
No npm dependencies at runtime.
Uses the built-in GITHUB_TOKEN. No personal token is needed, and the token is passed through an environment variable, never on the command line.
Least privilege. The workflow needs only contents: write, to commit the SVG.
Safe text. Repo names, descriptions and language colours are escaped and checked before they go into the SVG.
Reduced motion respected. Turn the orbits off with no-motion: true.
Pin a release. Use the v2.0.0 tag or a commit SHA rather than main.

Try it locally first

Want to see it before touching your profile? It runs on Node 18+ with no dependencies:

git clone https://github.com/SandeepKomal/Git3D-Universe
cd Git3D-Universe

npm run sample      # draws a sample universe in out/, no network needed
GITHUB_TOKEN=<token> node src/cli.mjs --user YOUR_LOGIN --out profile/git3d-universe.svg

Options: --theme aurora|daylight, --no-motion, --sample.

Want a whole profile, not just the universe?

Git3D Universe is also built into my other project, README-Glassfolio. It makes a complete profile README (banner, stats, heatmap, languages, projects and Connect buttons) with the 3D universe included, and publishes it in one click.

Tell me what your universe looks like

It's free and open source (MIT):

💻 GitHub: SandeepKomal/Git3D-Universe
🐛 Ideas or bugs: open an issue

If you add it to your profile, drop your GitHub link in the comments. I'd love to see whose busiest month is December. 😄 A ⭐ on the repo helps other developers find it.

Happy orbiting! 🪐

DEV Community