Generate visualizations of GitHub user and repository statistics with GitHub Actions. Visualizations can include data for both private repositories, and for repositories you have contributed to, but do not own.
Generated images automatically switch between GitHub light theme and GitHub dark theme.
These additional SVGs are generated by default, but they are experimental and may be approximate. GitHub APIs can be permission-scoped, cached, delayed, or limited to short time windows. Private repository names are redacted before experimental metrics are written to generated SVGs or JSON reports.
When someone views a profile on GitHub, it is often because they are curious about a user's open source projects and contributions. Unfortunately, that user's stars, forks, and pinned repositories do not necessarily reflect the contributions they make to private repositories. The data likewise does not present a complete picture of the user's total contributions beyond the current year.
This project aims to collect a variety of profile and repository statistics using the GitHub API. It then generates images that can be displayed in repository READMEs, or in a user's Profile README.
Since the project runs on GitHub Actions, no server is required to regularly regenerate the images with updated statistics. Likewise, since the user runs the analysis code themselves via GitHub Actions, they can use their GitHub access token to collect statistics on private repositories that an external service would be unable to access.
If the project is used with an access token that has sufficient permissions to
read private repositories, it may leak details about those repositories in
error messages. For example, the aiohttp library—used for asynchronous API
requests—may include the requested URL in exceptions, which can leak the name
of private repositories. If there is an exception caused by aiohttp, this
exception will be viewable in the Actions tab of the repository fork, and
anyone may be able to see the name of one or more private repositories.
Due to some issues with the GitHub statistics API, there are some situations where it returns inaccurate or incomplete results. Repository view count statistics may be approximate because GitHub only exposes recent traffic data and requires sufficient repository access. Additionally, repositories that were last contributed to more than a year ago may not be included in the statistics due to limitations in the results returned by the API.
For more information on inaccuracies, see issue #2, #3, and #13.
This project intentionally does not generate total lines added, total lines
deleted, or churn metrics. Those values would require GitHub's
/repos/{owner}/{repo}/stats/contributors endpoint, which can remain stuck at
202 Accepted long after GitHub's documentation suggests retrying.
In local testing, five randomly sampled repositories remained pending after a 30-minute poll every 7 seconds, following an earlier roughly 20-minute once-per-minute poll. Because this behavior is unreliable enough to slow or stall image generation, the generator does not call this endpoint and no SVG includes line-change metrics.
To debug the full image generation workflow before pushing, install the Python dependencies and run the generator from the repository root:
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install -r requirements.txt
ACCESS_TOKEN=$(gh auth token) GITHUB_ACTOR=$(gh api user --jq .login) python3 generate_images.pyYou can also keep local settings in a gitignored .env file:
cp .env.example .env
$EDITOR .env
python3 generate_images.pyThe .env file supports simple KEY=value lines and is loaded only when a
value is not already present in the shell environment. This lets local shell
overrides and GitHub Actions secrets remain authoritative.
Local generation may update generated/*.svg, generated/*.json, and
run-report.json. Do not commit .env, and do not paste personal access
tokens into READMEs, issues, workflow logs, or bug reports.
- Create a personal access token (not the default GitHub Actions token) using
the instructions
here.
Personal access token must have permissions:
read:userandrepo. Copy the access token when it is generated – if you lose it, you will have to regenerate the token.- Some users are reporting that it can take a few minutes for the personal access token to work. For more, see #30.
- Create a copy of this repository by clicking here. Note: this is not the same as forking a copy because it copies everything fresh, without the huge commit history.
- Go to the "Secrets" page of your copy of the repository. If this is the README of your copy, click this link to go to the "Secrets" page. Otherwise, go to the "Settings" tab of the newly-created repository and go to the "Secrets" page (bottom left).
- Create a new secret with the name
ACCESS_TOKENand paste the copied personal access token as the value. - It is possible to change the type of statistics reported by adding other
repository secrets.
- To ignore certain repos, add them (in owner/name format e.g.,
jstrieb/github-stats) separated by commas to a new secret—created as before—calledEXCLUDED. - To ignore certain languages, add them (separated by commas) to a new
secret called
EXCLUDED_LANGS. For example, to exclude HTML and TeX you could set the value tohtml,tex. - To show statistics only for "owned" repositories and not forks with
contributions, add an environment variable (under the
envheader in the main workflow) calledEXCLUDE_FORKED_REPOSwith a value oftrue. - These other values are added as secrets by default to prevent leaking information about private repositories. If you're not worried about that, you can change the values directly in the Actions workflow itself.
- To ignore certain repos, add them (in owner/name format e.g.,
- Go to the Actions
Page and press "Run
Workflow" on the right side of the screen to generate images for the first
time.
- The images will be automatically regenerated every 24 hours, but they can be regenerated manually by running the workflow this way.
- Take a look at the images that have been created in the
generatedfolder. - To add your statistics to your GitHub Profile README, copy and paste the
following lines of code into your markdown content. Change the
usernamevalue to your GitHub username. 
 
Experimental metrics are generated by default and can be added with: 
To disable experimental metric generation, set                 
GENERATE_EXPERIMENTALtofalse,0,no, oroffin the workflow environment. - Link back to this repository so that others can generate their own statistics images.
- Star this repo if you like it!
There are a few things you can do to support the project:
- Star the repository (and follow me on GitHub for more)
- Share and upvote on sites like Twitter, Reddit, and Hacker News
- Report any bugs, glitches, or errors that you find
These things motivate me to keep sharing what I build, and they provide validation that my work is appreciated! They also help me improve the project. Thanks in advance!
If you are insistent on spending money to show your support, I encourage you to instead make a generous donation to one of the following organizations. By advocating for Internet freedoms, organizations like these help me to feel comfortable releasing work publicly on the Web.
- Inspired by a desire to improve upon anuraghazra/github-readme-stats
- Makes use of GitHub Octicons to precisely match the GitHub UI