GitHub stats cards for your profile README, generated by GitHub Actions in your own repository. No hosted service that can be paused or rate-limited, no dependencies: plain Python (stdlib) + the GitHub GraphQL API.
| Card | Shows |
|---|---|
stats |
Total stars, commits this year, private contributions (last year), pull requests, issues, repositories contributed to, public repos, total contributions (last year) |
languages |
Top languages by code size in your own (non-fork) repositories |
streak |
Total contributions since you joined, current and longest daily streak |
activity |
Monthly contributions over the years as a line chart: one continuous line or one line per year (activity_style) |
org |
Organization: stars, forks, public/active repos, open issues & PRs, members, top languages (set org) |
Files are named github-<card>.svg (light theme) and github-<card>-<theme>.svg (other themes).
Pick any with themes: dark,midnight (or all). Gradient backgrounds are built in;
transparent has no background and fits both light and dark pages with a single file.
light |
dark |
dimmed |
transparent |
midnight |
aurora |
sunset |
forest |
mono |
high-contrast |
Custom colors on top of any theme (e.g. your brand), validated hex values only:
themes: dark
colors: accent=#ff0066,title=#ff0066,bg2=#2a0018 # bg2 = gradient endKeys: bg, bg2, border, title, label, value, accent, track.
-
In your profile repository (
<you>/<you>) create.github/workflows/stats-card.yml:name: Stats card on: schedule: - cron: "0 0 * * *" # daily workflow_dispatch: jobs: card: uses: spidero/github-stats-card/.github/workflows/card.yml@v1 permissions: contents: write with: cards: stats,languages,streak # or "all"
-
Run it once from the Actions tab (
Run workflow). -
Add the cards to your
README.md(replace<you>; repeat for every card):<img alt="GitHub stats" src="https://raw.githubusercontent.com/<you>/<you>/output/github-stats-dark.svg#gh-dark-mode-only"> <img alt="GitHub stats" src="https://raw.githubusercontent.com/<you>/<you>/output/github-stats.svg#gh-light-mode-only">
The workflow pushes the github-*.svg files to the output branch and only touches
those files, so it can share the branch with other generators.
Optional inputs of the reusable workflow:
| Input | Default | Description |
|---|---|---|
github_user_name |
repository owner | User to generate the card for |
cards |
stats |
Comma-separated cards or all |
include_private |
false |
Use private repos (needs token) |
org |
Organization for the org card |
|
colors |
Theme color overrides, see Themes | |
hide |
Items to hide, see Options | |
exclude_repos |
Repository names to skip | |
exclude_archived |
false |
Skip archived repositories |
activity_style |
line |
activity card: line, years or both, see Options |
activity_years |
0 (auto) |
activity card: number of years shown |
show_credit |
true |
Small project link in the corner |
branch |
output |
Branch the SVG files go to |
title |
per card | Custom title (all cards) |
themes |
light,dark |
Themes to render or all, see Themes |
Secret: token (optional), see Private repositories.
uses: spidero/github-stats-card/.github/workflows/card.yml@v1
permissions:
contents: write
with:
title: My GitHub activity
secrets:
token: ${{ secrets.STATS_TOKEN }}If you already have a workflow (e.g. one that publishes other SVGs), add a step:
- uses: spidero/github-stats-card@v1
with:
github_user_name: <you>
cards: stats,languages
output_dir: dist
# token: ${{ secrets.STATS_TOKEN }}Then publish dist/ the same way you publish your other files.
| Input | Default | Description |
|---|---|---|
github_user_name |
(required) | User to generate the card for |
cards |
stats |
Comma-separated cards or all |
include_private |
false |
Use private repos (needs a PAT) |
org |
Organization for the org card |
|
colors |
Theme color overrides, see Themes | |
hide |
Items to hide, see Options | |
exclude_repos |
Repository names to skip | |
exclude_archived |
false |
Skip archived repositories |
activity_style |
line |
activity card: line, years or both, see Options |
activity_years |
0 (auto) |
activity card: number of years shown |
show_credit |
true |
Small project link in the corner |
output_dir |
dist |
Where the SVG files are written |
token |
github.token |
Token for the GitHub GraphQL API |
title |
per card | Custom title (all cards) |
themes |
light,dark |
Themes to render or all, see Themes |
org: organization login for theorgcard, e.g.cards: org+org: my-company. Public repositories only.cards: allincludes theorgcard only whenorgis set. "Members" needs a token with organization read access (a PAT); with the defaultGITHUB_TOKENthat row is simply left out.hidealso works there (stars,forks,repos,active,issues,prs,membersand language names).hide: comma-separated, case-insensitive. Stats rows:stars,commits,private,prs,issues,contributed,repos; and/or language names for thelanguagescard (percentages are recomputed without them). Example:hide: issues,private,html,css.activity_style(activitycard):linedraws one continuous line of monthly contributions across the years;yearsdraws one line per year on a Jan-Dec axis to compare years.activity_yearslimits how many recent years are shown;0(default) means every year with contributions forlineand the last 3 years foryears.bothwrites both charts:github-activity.svg(line) andgithub-activity-years.svg(one line per year), plus the other themes as usual.exclude_repos/exclude_archived: skip repositories when counting stars, public repos and languages. Commits, PRs, issues and contributions are your activity and are reported by GitHub as totals, so they cannot be filtered per repository.- Bundled third-party code (e.g. an Arduino
libraries/folder) inflating languages? Mark it as vendored in that repository's.gitattributes, so GitHub stops counting it:libraries/** linguist-vendored
The default GITHUB_TOKEN can only see public data (and the current repository), so for
example pull requests in private repositories are not counted.
To include them, create a fine-grained personal access token (Settings → Developer settings → Personal access tokens) with All repositories and read-only permissions (Metadata, Pull requests, Issues), then save it as a repository secret:
gh secret set STATS_TOKEN -R <you>/<you>and pass it as token (see examples above). Only the numbers are shown on the card,
never repository names.
Notes:
- "Private contributions" is shown only when Private contributions is enabled in your profile settings. GitHub exposes it as one total, not split by commits/PRs/issues.
- "Commits" counts public commits only, as GitHub reports private ones only in the total above.
- The
languagescard uses public repositories only, unlessinclude_private: true(then every repository the token can see). Only language names and sizes are used. - When the token expires, the card simply stops updating until you set a new one.
python3 -m github_cards --list # available cards
GITHUB_TOKEN=$(gh auth token) python3 -m github_cards <you> dist --cards all [--include-private]
python3 -m github_cards --help # every optiongithub_user_name and output_dir are the two positional arguments and token is the
GITHUB_TOKEN environment variable. Every other action input has a CLI flag with the same
name in kebab case (activity_style -> --activity-style, exclude_repos -> --exclude-repos);
true/false inputs are switches:
include_private: true -> --include-private, exclude_archived: true -> --exclude-archived,
show_credit: false -> --no-credit.
Every module in github_cards/cards/ is one card; it is picked up
automatically by the CLI, the action and the reusable workflow. Create
github_cards/cards/<name>.py:
from ..svg import card, stat_row
DESCRIPTION = "Followers and stars"
QUERY = """
query($login: String!) {
user(login: $login) { name login followers { totalCount } }
}
"""
def fetch(api, login, options):
# options: title, hide, include_private, exclude_repos, exclude_archived, org,
# activity_style, activity_years
# Return plain JSON-serialisable data (it is also saved as sample data)
user = api.query(QUERY, login=login)["user"]
return {"name": user["name"] or user["login"], "followers": user["followers"]["totalCount"]}
def render(data, theme, options):
body = stat_row(theme, 0, "Followers", data["followers"])
return card(theme, options.get("title") or f"{data['name']}'s followers", body, height=110)Building blocks in github_cards/svg.py: card (frame, title,
footer), stat_row, ring, bar, human (number formatting), fmt_date.
Use the fade class for fade-in; content must stay visible without animations
(link previews, reduced motion), so animate from a hidden state, never to a visible one. Colors come from
github_cards/themes.py (THEMES[theme]["accent"] etc.);
adding a theme there makes it available everywhere.
Design without a token or network, using the sample data in samples/:
# fetch fresh sample data for all cards (once)
GITHUB_TOKEN=$(gh auth token) python3 -m github_cards <you> /tmp/x --cards all --include-private --dump-data samples/<you>.json
# render every card in every theme into preview/index.html and open it
python3 preview.py samples/<you>.jsonpython3 -m unittest discover -s tests -t . # unit + render tests, offline
python3 preview.py # visual check of every card x themeTests run on every push and pull request. Bug reports and ideas: use the issue forms.




