The user-statistician GitHub Action mentioned in Awesome-README
Tags: github, showdev, tutorial, webdev
Published: 2022-08-25 13:59:32

The [user-statistician](https://github.com/cicirello/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](https://github.com/cicirello/user-statistician) GitHub Action was added to the tools section of [Awesome README](https://github.com/matiassingers/awesome-readme), which is an [Awesome List](https://github.com/sindresorhus/awesome) 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](https://github.com/matiassingers/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](https://github.com/cicirello/user-statistician) GitHub Action is in the [Tools Section](https://github.com/matiassingers/awesome-readme#tools). 

__Functionality:__ The [user-statistician](https://github.com/cicirello/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](#how-to-configure), including an example workflow and example SVG, a [list of quickstart workflows](#quickstart-workflows), and [detailed steps](#step-by-step-instructions).
* [Find Out More](#find-out-more).
* [Where You Can Find Me](#where-you-can-find-me).


## How to Configure

Let's begin with an example. Here is an example workflow from [my profile repository](https://github.com/cicirello/cicirello). 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.

```YAML
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):

![Example from My GitHub Profile](https://raw.githubusercontent.com/cicirello/cicirello/master/images/userstats.svg)


### Quickstart Workflows 

The GitHub repository includes a directory of [Quickstart Workflows](https://github.com/cicirello/user-statistician/tree/main/quickstart) for anticipated common desired configuration options. These include:
* [all-defaults.yml](https://github.com/cicirello/user-statistician/blob/main/quickstart/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](https://github.com/cicirello/user-statistician/blob/main/quickstart/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](https://github.com/cicirello/user-statistician/blob/main/quickstart/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](https://github.com/cicirello/user-statistician/blob/main/quickstart/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](https://github.com/cicirello/user-statistician/blob/main/quickstart/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](https://github.com/cicirello/user-statistician/blob/main/quickstart/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](https://github.com/cicirello/user-statistician/blob/main/quickstart/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:

```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](https://github.com/cicirello/user-statistician) 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.

{% github cicirello/user-statistician %}

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

{% embed https://actions.cicirello.org %}


## Where You Can Find Me

On the Web:

{% embed https://www.cicirello.org/ %}

Follow me here on DEV:

{% user cicirello %}

Follow me on GitHub:

{% github cicirello/cicirello %}

| [![Liberapay](https://actions.cicirello.org/images/Liberapay.svg)](https://liberapay.com/cicirello) | [![Ko-Fi](https://actions.cicirello.org/images/ko-fi.svg)](https://ko-fi.com/cicirello) |
| :---: | :---: |
| [![GitHub Sponsors](https://actions.cicirello.org/images/github-sponsors.svg)](https://github.com/sponsors/cicirello) | |