Skip to content

About

Self-hosted GitHub profile stats cards (stats, languages, streak, organization) generated by GitHub Actions - no server, no downtime, zero dependencies. 10 themes.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

Profile Stats Cards

Marketplace Test License: MIT

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.

Cards: stats, languages, streak, organization and activity (both styles) in several themes

Cards

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)

GitHub stats card

GitHub stats card

Top languages card

Top languages card

Streak card

Streak card

Activity card (activity_style: line)

Activity card (activity_style: line)

Activity card (activity_style: years)

Activity card (activity_style: years)

Organization card

Organization card

Files are named github-<card>.svg (light theme) and github-<card>-<theme>.svg (other themes).

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
light
dark
dark
dimmed
dimmed
transparent
transparent
midnight
midnight
aurora
aurora
sunset
sunset
forest
forest
mono
mono
high-contrast
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 end

Keys: bg, bg2, border, title, label, value, accent, track.

Quick start (reusable workflow)

  1. 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"
  2. Run it once from the Actions tab (Run workflow).

  3. 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 }}

Use as an action step

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

Options

  • org: organization login for the org card, e.g. cards: org + org: my-company. Public repositories only. cards: all includes the org card only when org is set. "Members" needs a token with organization read access (a PAT); with the default GITHUB_TOKEN that row is simply left out. hide also works there (stars, forks, repos, active, issues, prs, members and language names).
  • hide: comma-separated, case-insensitive. Stats rows: stars, commits, private, prs, issues, contributed, repos; and/or language names for the languages card (percentages are recomputed without them). Example: hide: issues,private,html,css.
  • activity_style (activity card): line draws one continuous line of monthly contributions across the years; years draws one line per year on a Jan-Dec axis to compare years. activity_years limits how many recent years are shown; 0 (default) means every year with contributions for line and the last 3 years for years. both writes both charts: github-activity.svg (line) and github-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

Private repositories

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 languages card uses public repositories only, unless include_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.

Run locally

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 option

github_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.

Adding a new card

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>.json

Development

python3 -m unittest discover -s tests -t .   # unit + render tests, offline
python3 preview.py                           # visual check of every card x theme

Tests run on every push and pull request. Bug reports and ideas: use the issue forms.

License

MIT

About

Self-hosted GitHub profile stats cards (stats, languages, streak, organization) generated by GitHub Actions - no server, no downtime, zero dependencies. 10 themes.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages