github-profile-summary-cards

Themes

default	2077	dracula	github	github_dark
gruvbox	monokai	nord_bright	nord_dark	radical
solarized	solarized_dark	tokyonight	vue	zenburn
transparent

More themes

How to use (API)

Profile details card

http://github-profile-summary-cards.vercel.app/api/cards/profile-details?username={username}&theme={theme_name}

• Accept url parameters
  • theme
    • Theme name
  • username
    • Username
  • name
    • Optional override for the displayed name/title (e.g. name=Casper). Defaults to login (name); long values are elided to fit on one line (~22 chars).

Top languages used in repository card

http://github-profile-summary-cards.vercel.app/api/cards/repos-per-language?username={username}&theme={theme_name}&exclude={exclude}

• Accept url parameters
  • theme
    • Theme name
  • username
    • Username
  • exclude:
    • A comma separated list of languages to exclude, e.g., exclude=java,rust,jupyter%20Notebook
      • You can represent a space in the language list by using ‘%20’ when you want to include a space.
    • You can found the supported languages in here
  • exclude_repos:
    • A comma separated list of repository names to exclude (case-insensitive), e.g., exclude_repos=dotfiles,my-fork
    • owner/repo entries also match, e.g., exclude_repos=vn7n24fzkq/dotfiles

Top languages in commits card

http://github-profile-summary-cards.vercel.app/api/cards/most-commit-language?username={username}&theme={theme_name}&exclude={exclude}

• Accept url parameters
  • theme
    • Theme name
  • username
    • Username
  • exclude:
    • A comma separated list of languages to exclude, e.g., exclude=java,rust,jupyter%20Notebook
      • You can represent a space in the language list by using ‘%20’ when you want to include a space.
    • You can found the supported languages in here
  • exclude_repos:
    • A comma separated list of repository names to exclude (case-insensitive), e.g., exclude_repos=dotfiles,my-fork
    • Commits can come from other owners’ repos, so owner/repo entries also match, e.g., exclude_repos=someorg/website

GitHub stats card

http://github-profile-summary-cards.vercel.app/api/cards/stats?username={username}&theme={theme_name}

• Accept url parameters
  • theme
    • Theme name
  • username
    • Username

Productive time card

http://github-profile-summary-cards.vercel.app/api/cards/productive-time?username={username}&theme={theme_name}&timeZone={iana_time_zone}

http://github-profile-summary-cards.vercel.app/api/cards/productive-time?username={username}&theme={theme_name}&utcOffset={utcOffset}

• accept url parameters
  • theme
  • username
  • timeZone
    • IANA time zone name, e.g. Europe/Zurich, America/New_York, or UTC
    • Handles daylight saving time automatically and takes precedence over utcOffset.
  • utcOffset
    • Fixed UTC offset in hours, kept for backward compatibility. Ignored when timeZone is present.
  • exclude_repos
    • A comma-separated list of repository names whose commits are excluded from the chart (case-insensitive), e.g., exclude_repos=dotfiles,my-fork
    • owner/repo entries also match, e.g., exclude_repos=vn7n24fzkq/dotfiles

Example with daylight saving time:

http://github-profile-summary-cards.vercel.app/api/cards/productive-time?username=vn7n24fzkq&theme=nord_bright&timeZone=Europe/Zurich

Custom colors

Every card endpoint also accepts these optional parameters to override individual colors of the selected theme:

title_color, text_color, bg_color, border_color, icon_color, chart_color

Values are hex without the leading # — 3, 4, 6, or 8 digits (the 4/8-digit forms include alpha). Anything else is ignored. For example, the dark theme with a transparent background:

http://github-profile-summary-cards.vercel.app/api/cards/stats?username=vn7n24fzkq&theme=dark&bg_color=00000000

Resolves #110 and #152.

The stats card also accepts hide_logo=true to remove the GitHub logo on the right:

http://github-profile-summary-cards.vercel.app/api/cards/stats?username=vn7n24fzkq&theme=dark&hide_logo=true

Animations ✨ (new)

Cards can now animate! Add an optional animation parameter and the card plays a pure-CSS entrance when it loads — no GIFs, no JavaScript, works right inside your GitHub README. The background/frame appears instantly and the animation plays on the individual pieces (each stat row, each language, each bar), so it reads as the content filling into a ready card.

none (default) · fade · rise · draw · stagger · load · sequence · tint · rgb · rgb-soft

Preset	What it does
fade / rise	Content fades in (and gently slides up for rise).
draw	Bars grow, donut segments pop, and the contributions line draws on.
stagger	Every piece fades in, one after another.
load	A coordinated “loading → loaded” assembly: parts stagger in, then the charts draw on.
sequence	Strict one-by-one reveal: title, each row, each language in order, then the line wipes in from the left along the time axis.
tint	Content fades in while its colours sweep from a shifted hue back to normal — a soft colour settle.
rgb	A continuous “gaming RGB” loop — the whole card (background included) cycles through the spectrum, rotating your theme’s colours.
rgb-soft	The same colour cycle, but only the content — the background keeps its theme colour.

https://github-profile-summary-cards.vercel.app/api/cards/stats?username=vn7n24fzkq&theme=default&animation=load

Speed: every preset has a sensible default. Add duration (in seconds, 0.2–10) to make it faster or slower — it scales the whole thing, including the staggered/draw-on timing (for the rgb presets it’s the colour-cycle period):

https://github-profile-summary-cards.vercel.app/api/cards/stats?username=vn7n24fzkq&theme=default&animation=load&duration=3

Any unrecognized animation value is treated as none, an invalid duration falls back to the preset default, and visitors with prefers-reduced-motion set always get the final, un-animated card.

🌈 Feeling fancy? Turn on the RGB.

Give your profile that gaming-keyboard glow. rgb-soft cycles your card’s colours forever while the background stays put:

https://github-profile-summary-cards.vercel.app/api/cards/profile-details?username=YOUR_NAME&theme=github_dark&animation=rgb-soft

Want the whole card — border and all — in on it? Use animation=rgb. Too much? Slow it right down with &duration=10. 😎

---

Organization cards

All endpoints above accept either a user login or an organization login as username. The owner type is auto-detected; no extra parameter is needed.

The same URLs return organization-flavored cards when the login resolves to an organization:

• profile-details swaps the contributions overlay for a “repos created over time” chart and shows Public Repos / Created at / Email|Location|Website.
• repos-per-language and most-commit-language aggregate across the organization’s public repos (top 50 for the commit card to stay within API rate limits).
• stats shows Total Stars / Total Repos / Total Forks / Open Issues.
• productive-time is not supported for organizations (it relies on per-user contribution data); the endpoint returns a small error card explaining this.

The same GitHub Action setup also works for organizations — set USERNAME to the org login. The generated profile-summary-card-output/ will contain 4 cards per theme instead of 5.

Hosted API vs GitHub Action. On the hosted API (*.vercel.app), the language and stats cards aggregate your top 100 repositories by stars — this keeps each request within the serverless time limit and light on the shared rate limit. The GitHub Action runs with your own token and no time limit, so it includes all of your repositories. (The total-repo count is exact either way.)

---

Setting up your GitHub token

Every way of running this project — locally, in a GitHub Action, on Vercel — needs a GitHub personal access token (PAT). If you’ve never created one, read this section first.

Who owns the token?

A PAT always belongs to a user account, not to an organization. Even when you point this tool at an organization (e.g. microsoft), the token comes from a user — typically you. The token only grants whatever access that user already has. For public data (which is what the cards display), any logged-in GitHub user can read it, so a token from any account works.

The cards only ever display public data, so a token from any user account can render any user or organization — you don’t need to be a member of the org or grant any org-specific scope.

Step 1: pick a token type

GitHub offers two PAT styles. Either works for this project.

• Fine-grained PAT (recommended). Newer, scoped to specific repos or orgs, mandatory expiration. Create one at https://github.com/settings/personal-access-tokens/new.
• Classic PAT. Older, broad scopes, optional expiration. Create one at https://github.com/settings/tokens/new.

Step 2: grant the right permissions

For public users and orgs (the typical case), you need very little:

Token type	What to enable
Fine-grained PAT	Repository access: “Public repositories (read-only)”. Account permissions: leave defaults — public profile and organization data are read without any explicit grant.
Classic PAT	Check public_repo and read:user.

For private repos (to include private activity in your totals — see below), escalate:

Token type	What to enable
Fine-grained PAT	“Repository access”: “All repositories” or pick specific private repos. Read-only is enough.
Classic PAT	Add repo (full repo access).

Always set an expiration (90 days is a good default) and copy the token immediately — GitHub only shows it once.

Step 3: put the token where it needs to go

Where the token lives depends on how you’re running the tool. Same token, different home.

Local development (npm run dev, npm run test:local, or vercel dev)

Copy .env.example to .env in the repo root and paste the token in:

GITHUB_TOKEN=your_github_token_here

.env is already in .gitignore — do not commit it. All of the commands below auto-load it.

Three ways to preview locally:

• npm run dev — runs the real card handlers on a local server at http://localhost:3000/ and live-reloads on save; type a user or org login to render every card. Best for iterating.
• npm run test:local -- <login> [utcOffset] [exclude] — renders all cards for one login to profile-summary-card-output/.
• vercel dev — full Vercel emulation of the API routes and the /demo page.

GitHub Actions (production card refresh on your profile repo)

Go to the repo where the workflow will run — typically https://github.com/<your-username>/<your-username> — and:

1. Click Settings → Secrets and variables → Actions.
2. Click New repository secret.
3. Name it SUMMARY_GITHUB_TOKEN (this is the name the example workflow below references).
4. Paste the token as the value and save.

The workflow file references the secret as ${{ secrets.SUMMARY_GITHUB_TOKEN }}. Never paste the raw token into the YAML.

If you want the bot to push generated cards back to the repo, two options work:

• Built-in GITHUB_TOKEN plus permissions: contents: write in the workflow (the jobs.build block in the example workflow below already includes this line). GitHub’s auto-provided token has read-only permissions by default on many repos, so this permissions: line is what actually grants it push access for scheduled cron runs.
• Your own PAT stored under a custom secret name such as SUMMARY_GITHUB_TOKEN. Useful if you’d rather not adjust workflow permissions, or if your repo’s default workflow permissions are locked to read-only.

Vercel (your own deployment of the API)

In your Vercel project: Settings → Environment Variables → Add.

• Key: GITHUB_TOKEN
• Value: paste the token
• Environments: check Production, Preview, and Development.

Redeploy after saving so the new env var takes effect.

Common mistakes

• Committing the token. If .env shows up in git status, stop — confirm it matches the entry in .gitignore before continuing. If you’ve already pushed a commit containing a token, revoke it at https://github.com/settings/tokens and create a new one.
• Using ${{ secrets.GITHUB_TOKEN }} (the built-in token) without setting workflow permissions. The auto-provided GITHUB_TOKEN is often read-only by default. If you want to use it for pushing, add permissions: contents: write to the workflow; otherwise switch to your own PAT under a custom secret name (e.g. SUMMARY_GITHUB_TOKEN).
• Token created under an org account. Not a thing — GitHub doesn’t issue PATs to orgs. Always create from your user Settings → Developer settings.

Including private-repo activity without exposing repo names

The cards never render private repo names, titles, commit messages, or per-repo star counts — they only show aggregate numbers and language labels. So you can safely have your totals reflect private-repo activity without leaking which repos exist. To enable this you need both a PAT with private read scope and a GitHub profile setting:

1. Scope the token to read private repos.

   Token type	What to enable
   Fine-grained PAT (recommended)	Repository access: pick the specific private repos you want counted (or “All repositories”). Permissions: Contents: read, Issues: read, Pull requests: read, Metadata: read. Whitelisting specific repos keeps the blast radius small if the token leaks.
   Classic PAT	repo + read:user. Add read:org if the private repos belong to an organization. Note that repo is broad — it grants read and write to every private repo your account can see; prefer Fine-grained whenever possible.

2. Opt in to private contributions on your profile. Visit https://github.com/settings/profile, scroll to Contribution settings, and check “Include private contributions on my profile.” Without this toggle, contributionsCollection returns zero for private activity even with a fully-scoped token.

After both settings are in place, the following counts will include private-repo activity:

• ✅ Stats: Total Commits, Total PRs, Total Issues
• ✅ Profile Details: contribution chart (daily contribution counts in the area chart)
• ✅ Repos Per Language donut
• ✅ Most Commit Language donut
• ✅ Productive Time heatmap

Two counters in the Stats / Profile Details cards stay public-only by design in the current code — Total Stars and Contributed to. Their GraphQL queries hard-code privacy: PUBLIC (see src/github-api/profile-details.ts:55 and :74). If you want private-repo stars to roll up into the Stats card too, remove those filters or set up an opt-in env var — file an issue and we can scope a change.

What the cards still don’t expose. Even with everything above enabled, the SVGs never include: repo names, repo descriptions or topics, per-repo star counts, commit messages, author emails, commit SHAs, or issue/PR titles. The worst-case inference from the public cards is something like “this account made N commits last year across mostly-TypeScript repos” — no specific private repo is identifiable.

---

How to use (GitHub Actions)

This action generate your github profile summary cards and make a commit to your repo. You can also trigger action by yourself after add this action.

:star: Follow tutorial ( Recommendation ) :star:

First step

• Create a Personal access token and add it as a repo secret named SUMMARY_GITHUB_TOKEN. If you’ve never done this, see Setting up your GitHub token above for a step-by-step walkthrough including required scopes and where the secret goes.
• For additional context, the project’s wiki tutorial covers the same ground with screenshots.

Use template ( create a repository )

• github-profile-summary-cards-example

• Action already setup in this template, you just need click use this template button to create your profile readme.

• After replace GITHUB_TOKEN with your repo secret and trigger action you can use everything in profile-summary-card-output folder.

Add to exist repository

• Add this action to repo and replace GITHUB_TOKEN in action yml file with your repo secret.

---

GitHub Actions usage

After the action finished. You can see all of summary cards are in folder which named profile-summary-card-output.

Note: Some summary cards might not be updated in time, because github raw file has cache time.

name: GitHub-Profile-Summary-Cards

on:
  schedule: # execute every 24 hours
    - cron: "* */24 * * *"
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    name: generate-github-profile-summary-cards
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4
      - uses: vn7n24fzkq/github-profile-summary-cards@release
        env: # default use ${{ secrets.SUMMARY_GITHUB_TOKEN }}, you should replace with your personal access token
          GITHUB_TOKEN: ${{ secrets.SUMMARY_GITHUB_TOKEN }}
        with:
          USERNAME: ${{ github.repository_owner }}
          # BRANCH_NAME is optional, default to main, branch name to push cards
          BRANCH_NAME: "main"
          # UTC_OFFSET is optional, default to zero. Ignored when TIME_ZONE is set.
          UTC_OFFSET: 8
          # TIME_ZONE is optional; use an IANA zone (e.g. Europe/Zurich) to handle daylight saving time.
          TIME_ZONE: ""
          # EXCLUDE is an optional comma seperated list of languages to exclude, defaults to ""
          EXCLUDE: ""
          # AUTO_PUSH is optional, a boolean variable default to true, whether automatically push generated files to desired branch
          AUTO_PUSH: true
          # THEME is optional; set it to generate only that one theme (e.g. github_dark). Leave empty to generate every theme.
          THEME: ""
          # ANIMATION is optional; bake a CSS animation into the cards: none | fade | rise | draw | stagger | load | sequence | tint | rgb | rgb-soft. Empty = no animation.
          ANIMATION: ""
          # DURATION is optional; animation speed in seconds (0.2–10). Only applies when ANIMATION is set. Empty = preset default.
          DURATION: ""
          # NAME is optional; override the displayed name/title on the profile-details card (elided to ~22 chars). Empty = default "login (name)".
          NAME: ""

THEME and ANIMATION are independent:

• neither → every theme, no animation (the default, unchanged).
• THEME only → just that theme, no animation.
• ANIMATION only → every theme, each with that animation.
• both → that one theme with that animation.

---

Development (Devbox)

This project uses devbox to ensure a reproducible development environment (Node.js 22, Python 3).

1. Setup

# Install devbox
curl -fsSL https://get.jetpack.io/devbox | bash

# Enter shell (installs all dependencies automatically)
devbox shell

2. Local Testing

We provide a script to generate cards locally for visual verification. Prerequisite: A GITHUB_TOKEN. If you’ve never created one, follow Setting up your GitHub token above — for local use, copy .env.example to .env and paste your token in.

# Generate cards for a user (defaults to vn7n24fzkq when no login is given)
npm run test:local -- vn7n24fzkq 8

# Generate cards for an organization (auto-detected)
npm run test:local -- microsoft 0

# Optional third arg: comma-separated languages to exclude
npm run test:local -- microsoft 0 java,jupyter%20notebook

# Use an IANA time zone instead of a fixed offset (handles DST)
TIME_ZONE=Europe/Zurich npm run test:local -- vn7n24fzkq 8

Outputs are written to profile-summary-card-output/<theme>/. Open profile-summary-card-output/default/README.md to preview every card in the default theme. When you point this at an organization, the productive-time slot is replaced by 4-productive-time-unsupported.svg so you can verify the explanatory error card the Vercel route would return.

No token? Test the Action’s output pipeline with mock data. npm run test:action runs the exact generation flow the GitHub Action uses (theme filtering, animation, duration, name, preview markdown) against local fixtures — no token, no network. It honours the same knobs as the Action inputs, via env vars:

# One theme, sequence animation at 4s, custom title — writes profile-summary-card-output/github_dark/
THEME=github_dark ANIMATION=sequence DURATION=4 NAME="Casper" UTC_OFFSET=8 npm run test:action

# Use an IANA time zone instead of UTC_OFFSET (handles daylight saving time)
THEME=github_dark TIME_ZONE=Europe/Zurich npm run test:action

# All themes, no animation (the Action's default)
npm run test:action

3. Run the API Locally

A lightweight local dev server is bundled — no Vercel CLI required:

npm run dev
# then open http://localhost:3000/

The dev server mounts the same route handlers used in production (api/cards/*), so requests like http://localhost:3000/api/cards/profile-details?username=<login>&theme=<theme> exercise the exact code path Vercel runs. The index page at / includes a form that renders every card for a given login + theme, plus a theme/animation picker and a Replay button to watch the entrance animation.

No token? No problem. When no GITHUB_TOKEN is set, the dev server automatically serves mock cards from local fixtures — no network calls — which is ideal for iterating on themes and animations. Add &mock=1 to any card URL to force fixtures even when a token is present, or &mock=0 to force live data.

If you’d rather use the real Vercel runtime (closer match to production behaviour but requires linking the repo to a Vercel project):

npm i -g vercel
vercel dev

Deploy your own API on Vercel

Quickly deploy your own version!