The user-statistician GitHub Action generates an SVG with a detailed summary of your activity on GitHub that you can include in your GitHub Profile README (or even on your personal website), including various statistics about your repositories (e.g., stars, forks, most-starred repo, most-forked repo, etc), various contribution statistics (e.g., commits, issues, pull requests, pull request reviews, etc), as well as a pie chart summarizing the distribution of languages in your public repositories. It also includes international support with 16 locales to choose from. The intended use-case is to run on a schedule via a GitHub workflow in your GitHub profile repository. It is implemented in Python as a Container Action, and uses the GitHub CLI to query the GitHub GraphQL API to gather the data.
Recently, the user-statistician GitHub Action was added to the tools section of Awesome README, which is an Awesome List that includes a curated collection of examples of Awesome READMEs from open source projects, as well as tools enabling creating Awesome READMEs. The Awesome README list is a great place to go if you are looking for ideas for how to improve the READMEs of your open source projects. The Awesome README list covers READMEs more generally, but the tools section includes a few tools focused on Profile READMEs, in addition to many tools for project READMEs more generally. The user-statistician GitHub Action is in the Tools Section.
Functionality: The user-statistician is highly customizable. Here are a few of the ways you can customize it.
- International support with 16 natural languages to choose from: Bahasa Indonesia, Bengali, English, French, German, Hindi, Italian, Japanese, Korean, Lithuanian, Polish, Portuguese, Russian, Spanish, Turkish, Ukrainian.
- Several color themes, and you can specify custom colors as well.
- You can omit any stats you don't want to display.
- You can reorder the sections of the SVG from the default order.
- You can rearrange the order of the stats within a section.
- You can omit entire sections if you want (e.g., perhaps you just want the repository stats, or maybe the repository stats and the language distribution chart, etc).
- You can specify how many languages to include in the language distribution pie chart, or you can allow the action to choose the number of languages, which is the default behavior. If you allow the action to choose, it includes all languages that individually comprise at least 1 percent of the total, and it then groups the remaining low-percentage languages as "Other".
- The language distribution pie chart includes an optional animated rotation that you can enable.
- You can feature a repository of your choice.
- ... and several other supported customizations.
Contents: The rest of this post is organized as follows:
- How to Configure, including an example workflow and example SVG, a list of quickstart workflows, and detailed steps.
- Find Out More.
- Where You Can Find Me.
How to Configure
Let's begin with an example. Here is an example workflow from my profile repository. This workflow uses most of the defaults. However, I've used the colors
input to change the color theme to dark
. And I've used the featured-repository
input to feature a repository in the top section of the SVG. You'd want to change that to one of your own repositories before using this specific workflow. This workflow runs daily at 3am (see the cron
) and also runs manually via the workflow_dispatch
event. It needs the GITHUB_TOKEN
as an environment variable in order to query the GitHub GraphQL API. The default permissions that are automatically granted to GITHUB_TOKEN
are sufficient.
name: user-statistician
on:
schedule:
- cron: '0 3 * * *'
workflow_dispatch:
jobs:
stats:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Generate the user stats image for GitHub profile
uses: cicirello/user-statistician@v1
with:
colors: dark
featured-repository: Chips-n-Salsa
env:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
The above workflow, when run in a repository owned by me, produced the following (on the day of this DEV post):
Quickstart Workflows
The GitHub repository includes a directory of Quickstart Workflows for anticipated common desired configuration options. These include:
- all-defaults.yml: This runs the action on a daily schedule using all of the default settings, which is a light color theme.
- dark.yml: This runs the action on a daily schedule with a dark color theme, but otherwise uses all of the default settings.
- dark-dimmed.yml: This runs the action on a daily schedule with a dark-dimmed color theme, but otherwise uses all of the default settings.
- contributions.yml: This runs the action on a daily schedule, only generating the contribution stats (hiding the other sections), with a dark-dimmed theme.
- repositories.yml: This runs the action on a daily schedule, only generating the repositories stats (hiding the other sections), with a dark-dimmed theme.
- languages.yml: This runs the action on a daily schedule, only generating the languages distribution chart (hiding the other sections), with a dark theme.
- multiple-stats-cards.yml: This runs the action on a daily schedule, generating three separate SVGs, one for the contribution stats, one for the repositories stats, and one for the language distribution chart. It uses the dark theme for all three. Note that if you use this one, you'll have three images to insert into your Profile README.
Step by Step Instructions.
Here are the steps to use one of the quickstart workflows.
Step 0: Create a Profile Repository
Your GitHub Profile is a special GitHub repository. Start by creating a repository with the same name as your username. Initialize it with a README.md.
Step 1: Workflows Directory
In that repository, create a directory .github/workflows
. The .github
directory is a special directory where you can configure various GitHub features, such as CI/CD workflows, dependabot, etc. And the .github/workflows
directory is where GitHub expects GitHub Actions workflow files.
Step 2: Choose a Quickstart Workflow
Pick one of the quickstart workflows, such as whichever is closest to your desired configuration. Put it in the .github/workflows
directory, commit it, and push. If you didn't change the name of the file, then it will run when you push it to your repository since it has been configured to run on a push to that filename (assuming your branch is either named main
or master
). If you changed the name of the file, then edit the paths
attribute on the push
event with the new name of the workflow file.
The workflow is configured to run on a schedule daily. You can change the schedule to your liking. See the cron
configuration toward the top of the workflow.
You can also choose to run it manually because it is also configured on the workflow_dispatch
event. To do this, navigate to the Actions tab for your profile repository. Select the workflow from the list of workflows on the left. You'll notice that it indicates: "This workflow has a workflow_dispatch
event trigger." To the right of that click the "Run workflow" button to run the workflow manually.
Step 3: Add a Link to the Image in Your README
You'll find the SVG in the images
directory (which the action creates if it doesn't already exist). If you don't like the directory name, or even the name of the SVG file, the action includes inputs to change that.
Add a link to it in the README.md
in your profile repository. If you used one of these workflows as is, without using the inputs to change the file name of the image, then you can add the image to your profile with the following Markdown:
![My user statistics](images/userstats.svg)
Step 4: Customize
Now that you have tried out one of the quickstart workflows, take a look at the documentation to learn how to further customize.
Find Out More
To learn more, such as documentation on how to further customize, check out the GitHub Repository, and star it if you like it.
cicirello / user-statistician
Generate a GitHub stats SVG for your GitHub Profile README in GitHub Actions
user-statistician
Check out all of our GitHub Actions: https://actions.cicirello.org/
About user-statistician
The cicirello/user-statistician GitHub Action generates a detailed visual summary of your activity on GitHub in the form of an SVG suitable to display on your GitHub Profile README Although the intended use-case is to generate an SVG image for your GitHub Profile README you can also potentially link to the image from a personal website, or from anywhere else where you'd like to share a summary of your activity on GitHub. The SVG that the action generates includes statistics for the repositories that you own, your contribution statistics (e.g., commits, issues, PRs, etc), as well as the distribution of languages within public repositories that you own The user stats image can be customized, including the colors such as with one of the built-in themes or your own set of customβ¦
I also have a website with more information on this, and other GitHub Actions, that I maintain.
Where You Can Find Me
On the Web:
Follow me here on DEV:
Follow me on GitHub:
Vincent A Cicirello
If you want to generate the equivalent to the above for your own GitHub profile, check out the cicirello/user-statistician GitHub Action.
Top comments (0)