Vincent A. Cicirello

Posted on Aug 25, 2022

The user-statistician GitHub Action mentioned in Awesome-README

#github #showdev #tutorial #webdev

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

GitHub Actions
Build Status
Source Info
Contributors
Support

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…

View on GitHub

I also have a website with more information on this, and other GitHub Actions, that I maintain.

Vincent Cicirello - Open source GitHub Actions for workflow automation

Features information on several open source GitHub Actions for workflow automation that we have developed to automate parts of the CI/CD pipeline, and other repetitive tasks. The GitHub Actions featured include jacoco-badge-generator, generate-sitemap, user-statistician, and javadoc-cleanup.

actions.cicirello.org

Where You Can Find Me

On the Web:

Vincent A. Cicirello - Professor of Computer Science

Vincent A. Cicirello - Professor of Computer Science at Stockton University - is a researcher in artificial intelligence, evolutionary computation, swarm intelligence, and computational intelligence, with a Ph.D. in Robotics from Carnegie Mellon University. He is an ACM Senior Member, IEEE Senior Member, AAAI Life Member, EAI Distinguished Member, and SIAM Member.

cicirello.org