github-readme-zodiac
Your GitHub activity, written in the stars. A zodiac-themed profile card for your README — add it with a single URL.
Quick start
Paste this into your profile README and replace YOUR_USERNAME:
That's it — no fork, no token, no setup. Your sign comes from birthdate (or force one with sign=), and the stats come from your public GitHub activity.
Live demo: github-readme-zodiac.vercel.app
All 12 signs
Options
| Param | Description |
|---|
username | GitHub username (required) |
birthdate | YYYY-MM-DD |
sign | Force sign: aries … pisces |
name | Override display name |
role | Override role |
width | Display width in px (240–900, default 360) |
Sister project (Asian zodiac): github-readme-chinese-zodiac
Bonus: pin it as a Gist
Prefer your profile Pins over the README? A fork-based GitHub Action (like productive-box) can keep a text version of the card in a pinned Gist.
| Mode | Where it appears | Setup |
|---|
| SVG card | Profile README | One URL (above) |
| Pinned Gist | Profile Pins | Fork + token + Action (below) |
What a Pin looks like
GitHub only shows about 5 lines of a pinned Gist. Below is the full 12-sign gallery (pin + full gist) from the local preview:
Gist pin preview — 12 signs (PDF)
Also available as HTML (download / open locally): docs/gist-pin-preview.html
Example pin body (Taurus):
♉ TAURUS · Builder ✦
✨ seuthootDev · JUNG SEUNGHOON \
⭐ 4 📦 36 👥 0 ✦-----✦
Consistency ███████████░ 95% \
Builder █████████░░░ 75% ✦--✦
Open the Gist itself to see the full card (description + tagline under the pin fold).
Pin quality (help wanted). Pins work, but the constellation ASCII is still a rough sketch vs real sky maps. SVG cards are the polished path today — see CONTRIBUTING.md if you want to improve src/gist/constellations.js.
How to put this on your profile Pins
Same pattern as productive-box: fork → Action fills your Gist → pin that Gist. No Vercel for Pins.
- Fork this repo
- Create a public Gist and copy its ID
(https://gist.github.com/YOU/GIST_ID — not the .js embed URL)
- Create a PAT with
gist scope → on your fork, add Secrets GH_TOKEN + GIST_ID
- On your fork, add Variable
BIRTHDATE = YYYY-MM-DD (optional but recommended)
- Actions → Update Zodiac Gist → Run workflow
- Pin the Gist on your profile
Details (secrets table, variables, schedule): Fork setup below.
Fork setup
Recommended: fork this repo and run the Action on your fork.
1. Fork
Fork seuthootDev/github-readme-zodiac.
2. Create a public Gist
- https://gist.github.com/
- Filename e.g.
zodiac.md, any placeholder text
- Create public gist
- Copy only the Gist ID (not the
.js embed URL):
https://gist.github.com/YOU/GIST_ID
3. Create a token (once)
https://github.com/settings/tokens → Tokens (classic) → enable gist only.
The token string is shown once — save it. The same PAT can be reused on the Asian sister project.
4. Secrets and Variables on your fork
Settings → Secrets and variables → Actions
Secrets tab:
| Secret | Value |
|---|
GH_TOKEN | PAT with gist scope |
GIST_ID | Gist ID only (see above) |
Variables tab (optional but recommended):
| Variable | Value | Notes |
|---|
BIRTHDATE | YYYY-MM-DD | e.g. 1995-04-24 → zodiac sign |
USERNAME | your GitHub login | default: token owner |
SIGN | scorpio | force a sign |
NAME | display name | optional override |
ROLE | Backend Dev | optional override |
Birthdate is a Variable (BIRTHDATE), not a Secret.
Path: Settings → Secrets and variables → Actions → Variables → New repository variable.
5. Run the Action
- On your fork: Actions → enable workflows if prompted
- Update Zodiac Gist → Run workflow
- Pin the Gist on your profile
Also runs on every push to main and daily at 00:00 UTC.
Pin vs SVG
Stats
Each card shows 3 of 5 traits. Which three appear depends on the sign’s statKeys. Values are weighted from public GitHub signals with no maximum. Bars are relative to the highest of the three shown.
| Stat | Drawn from (roughly) |
|---|
| Consistency | Account age + repos per year |
| Explorer | Distinct languages + public repos |
| Builder | Public repos + stars + forks |
| Open Source | Stars + forks + followers |
| Debugger | Open issues + repos (+ a little stars) |
Sister project (Asian zodiac) uses the same signals with different labels: Discipline / Ingenuity / Craft / Renown / Insight.
Daily forecast & streak
The speech bubble is a daily dev horoscope — a lucky language (picked from your own top languages) and one piece of advice. It changes every day (UTC) and stays the same all day.
The footer shows your current streak and contributions this year. This needs GITHUB_TOKEN on the server (GraphQL); without it the card shows the tagline instead.
How it works
Pinned Gist (fork)
Your fork → GitHub Action
→ GitHub API (your profile)
→ Zodiac + stats
→ PATCH your Gist
→ Pin on your profile
SVG (shared or self-hosted)
README image URL → Vercel /api/card → GitHub API → Zodiac + stats → SVG
Local development
npm start
Open http://localhost:3000
node scripts/preview-all-gists.js
# → scripts/out/all-signs-gist-preview.html
Project layout
action.yml
.github/workflows/update-gist.yml
assets/signs/ # title glyphs
assets/signs-line/ # line-art accent
assets/constellations/ # card constellation art
docs/gist-pin-preview-12-signs.pdf
docs/gist-pin-preview.html
docs/license-*.pdf # Magnific certificates
scripts/update-gist.js
scripts/preview-all-gists.js
scripts/extract-zodiac-signs.py
src/gist/
api/card.js
public/index.html
Contributing
New designs, card copy, sign-flavored roles, pin layouts — ideas are welcome anytime.
Highest-priority gap today: pinned Gist constellation ASCII (see help wanted).
See CONTRIBUTING.md.
Credits / attribution
Card sign artwork is derived from Magnific (Freepik) assets under a free license with attribution:
License
MIT © seuthootDev
Third-party artwork remains under its Magnific license (see certificates above); the MIT license covers this repository’s code.
Roadmap
More from the same author
Want a terminal-style contribution graph too? Sister project:
GitHub stats as macOS / Windows / Ubuntu terminal SVGs — contribution graph, stats, top languages, neofetch.
