Overview

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. For a live example, see Vincent A. Cicirello's GitHub Profile, the developer of the action. Although the intended use-case is to generate an SVG image for your GitHub Profile README, you can also potentially link to the GitHub stats 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, pull requests, etc), as well as the distribution of languages within public repositories that you own visualized as a pie chart. 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 colors. You can also pick and choose which sections of the card to include, as well as the order of appearance of the sections; and you can choose to hide individual stats.

The user-statistician action runs entirely on GitHub, and is implemented in Python. It uses the GitHub GraphQL API to collect the necessary data. The contribution counts are as reported by the GitHub GraphQL API. For details of how GitHub counts contributions, see GitHub's documentation. The repository, contribution, and language data included on the card is all public. This is true even of the Private Contributions entry on the stats image, as the restrictedContributionsCount returned from the query executed by the action will only be non-zero if you have opted in to sharing private contributions via GitHub's profile settings. You can also hide the Private Contributions entry regardless of your GitHub settings, or any of the other entries that you don't want to display. Each statistic also auto-hides if the associated count is 0.

The user-statistician action runs entirely on GitHub. To use it, you just need to set up a workflow in your GitHub Profile repository (or technically any repository that you own) on a schedule (daily should be sufficient), and then add a link to the image in your README. The action handles committing and pushing the generated image to the repository.

Features: The features of the user-statistician GitHub Action include the following:

• Generates detailed stats for your GitHub Profile README all in a single SVG.
• Ability to generate separate SVGs for the individual categories of stats if you prefer.
• Highly customizable (color themes, custom colors, section ordering, custom title).
• International with option to generate the SVG in over 24 languages, including: Bahasa Indonesia, Bengali, Dutch, English, French, German, Hindi, Hungarian, Italian, Japanese, Korean, Lithuanian, Norwegian, Odia, Polish, Portuguese, Romanian, Russian, Santali, Serbian, Spanish, Thai, Turkish, and Ukrainian.
• Runs entirely on GitHub.
• Updates the SVG on a schedule of your choice (e.g., daily), rather than on-demand when someone views your profile, which has the following advantages:
  • The SVG is simply served when requested, avoiding the delay associated with waiting for API queries to gather the data to generate the SVG.
  • The API queries associated with generating the SVG happen once per cycle of your configured schedule, regardless of how frequently your profile is visited, decreasing system load.

The user-statistician source code repository is hosted on GitHub; and is licensed under the MIT License. Also in the GitHub repository you will find detailed instructions for use including several sample ready-to-use GitHub workflows.

The user-statistician GitHub Action is developed by Vincent A. Cicirello. It was originally implemented for my own use, but I have decided to share it with others.

Live Examples

The first example below uses all of the default settings, except it switches the color theme to dark (my preference on GitHub). The second uses custom colors to match the color palette of my personal website.

Tech Stack

The user-statistician GitHub Action utilizes the following:

• Python 3 (implemented almost entirely in Python);
• The pyaction Docker container, which is a Docker container designed to support GitHub Actions development in the Python language (also see pyaction's GitHub repository);
• The cicirello/python-github-action-template repository, a template that we maintain to assist developers getting started developing a GitHub Action in Python;
• GitHub CLI;
• GitHub GraphQL API;
• GitHub Octicons for the icons in the stats image;
• JSON for managing the various language translations;
• Docker since it is implemented as a container action; and
• GitHub Container Registry, which is where we pull pyaction from at runtime for faster action loading (e.g., pulling the base Docker container from GitHub while an action is running on a GitHub server should be faster than pulling from Docker Hub).

Blog Posts About the user-statistician

As the author of the user-statistician, I occasionally post about this, and other software that I maintain on DEV.to. See my DEV.to profile for a full list of such posts. Below is a selection of blog posts specifically about the user-statistician.

• Hacktoberfest 2023 Update from Maintainer of the user-statistician GitHub Action, posted on DEV on October 9, 2023.

  A progress update on introducing additional locales for increased International support.

• Hacktoberfest 2023 Contributors Wanted: Additional Translations for the user-statistician GitHub Action, posted on DEV on September 30, 2023.

  An invitation to potential Hacktoberfest 2023 contributors for the addition of more language translations, and also explaining the process of adding a new locale.

• Hacktoberfest Progress Update: Translation Contributions Still Welcome, posted on DEV on October 12, 2022.

  This is an update on Hacktoberfest 2022 progress on adding more language translations to the user-statistician GitHub Action.

• Hacktoberfest Language Translation Contributors Wanted for the user-statistician GitHub Action, posted on DEV on September 30, 2022.

  Post seeking Hacktoberfest 2022 contributors for language translations for the user-statistician GitHub Action.

• Halloween Themes for the user-statistician GitHub Action, posted on DEV on September 28, 2022.

  This post introduces new Halloween themes available for the user-statistician GitHub Action.

• Configuring GitHub's Linguist to Improve Repository Language Reporting, posted on DEV on August 31, 2022.

  This blog post is a how to for configuring GitHub's Linguist in a GitHub repository, such as for the purpose of correcting errors in the detected languages, or directing Linguist to report languages that are excluded by default, within the context of tools such as the user-statistician GitHub Action that I developed and maintain, which generates a chart summarizing the language usage in all of your public repositories, as well as for the language charts built into every GitHub repository.

• The user-statistician GitHub Action mentioned in Awesome-README, posted on DEV on August 25, 2022.

  In this blog post, I provide an update on the user-statistician GitHub Action's functionality that I maintain, which was recently mentioned in Awesome README (an Awesome List), along with detailed steps for configuring a GitHub workflow within your own GitHub profile repository.

• Progress and Lessons Learned Internationalizing the user-statistician GitHub Action, posted on DEV on October 13, 2021.

  This post serves a dual purpose: (a) providing a midway progress report on Hacktoberfest 2021, and (b) providing insights learned related to the internationalization effort for the user-statistician GitHub Action.

• Hacktoberfest Participants Help Us Internationalize the user-statistician GitHub Action, posted on DEV on September 29, 2021.

  I decided to participate in Hacktoberfest as a project maintainer for October 2021. I used Hacktoberfest as an opportunity to Internationalize the user-statistician GitHub Action, with Hacktoberfest contributors providing translations to various languages.

• Generate a GitHub stats SVG for your GitHub Profile README in GitHub Actions, posted on DEV on July 29, 2021.

  This post introduced a GitHub Action that I implemented, called the user-statistician, which is designed to query the GitHub GraphQL API and generate an SVG image summarizing your activity on GitHub.