github-stats-pages 0.3.1

Retrieve statistics for a user's repositories and populate the information onto a GitHub static page

github-stats-pages

Retrieve statistics for a user's repositories and populate the information onto a GitHub static page

• Overview
• Requirements
• Deployment
  • GitHub Actions Deployment
  • Docker Deployment
  • From Source
• Installation
• Execution
• Versioning
• Continuous Integration
• Authors
• License

Overview

This software is both a GitHub Docker container action and a Python packaged software. The former allows for this to run to generate GitHub pages while the latter gives flexibility to deploy on a variety of compute resources (e.g., cloud, dev). Below outlines how to set this up.

Requirements

Traffic data for repositories are limited to those who have write or ownership access. Thus, regardless of how you choose to deploy, you will need a token. This codebase uses GitHub's Personal Access Token (PAT).

To create one, follow these instructions or go here. For scopes, select: repo and workflow (if you decide to deploy using GitHub Action). Save your PAT in a safe place as you will provide it below.

Deployment

This code is intended to deploy in a number of ways to allow for the greatest flexibility. First, this repository is also as a GitHub Docker container action (see below). Second, this code is package on PyPI. Third, the source code can be forked or cloned. Finally, a Dockerfile is included for containerization.

GitHub Actions Deployment

Deployment is simple with the following:

  - name: Build GitHub stats pages
    uses: astrochun/github-stats-pages@latest
    with:
      username: ${{ github.actor }}
      token: ${{ secrets.GH_TOKEN }}

This here will run for all public repositories.

Inputs

Variable	Description	Required?	Type	Defaults	Examples
username	GitHub username or organization	Yes	str	N/A	astrochun
token	GitHub Personal Access Token (PAT)	Yes	str	N/A	abcdef12345678
include-repos	Comma-separated lists of repositories. This overrides the full list of public repositories	No	str	''	'github-stats-pages,astrochun.github.io'
exclude-repos	Comma-separated lists of repositories to exclude from default public repository list	No	str	''	'repo1'

Other GitHub Action deployment examples:

To override all public repositories and limit to a subset of public repositories, specify a comma-separated list (no spaces between commas) for include-repos argument.

  - name: Build GitHub stats pages
    uses: astrochun/github-stats-pages@latest
    with:
      username: ${{ github.actor }}
      token: ${{ secrets.GH_TOKEN }}
      include-repos: "github-stats-pages"

Alternatively to exclude specific repositories from the list of public repositories, use the exclude-repos argument with a comma-separated list (no spaces between commas).

  - name: Build GitHub stats pages
    uses: astrochun/github-stats-pages@latest
    with:
      username: ${{ github.actor }}
      token: ${{ secrets.GH_TOKEN }}
      exclude-repos: "repo1,repo2"

Note that you can only specify include-repos or exclude-repos. Specifying both will fail!

Docker Deployment

This repository includes a Dockerfile. More details/instructions provided later.

From source

To run this code from original source, you will need to install it.

Installation

Use our PyPI package to get the most stable release:

(venv) $ pip install github-stats-pages

Or if you want the latest version then:

(venv) $ git clone https://github.com/astrochun/github-stats-pages
(venv) $ cd github-stats_pages
(venv) $ python setup.py install

Execution from source

TL;DR: If you decide to run this code from source, there are a few things you should know.

First, this repository includes an entrypoint.sh. You can simply execute it with the following:

(venv) laptop:github_data $ username="<username>"
(venv) laptop:github_data $ token="<personal_access_token>"
(venv) laptop:github_data $ /path/to/github-stats-pages/entrypoint.sh $username $token

Second, it is recommended to create a folder (e.g., github_data) as the contents will ultimately contain multiple files.

More details

Here's an overview providing more details how this codebase works. There are four primary scripts accompanying github-stats-pages

1. get_repo_list
2. gts_run_all_repos
3. merge-csv.sh
4. make_stats_plots

get_repo_list generates a CSV file containing a list of public repositories for a GitHub user/organization. This database allows the code to aggregate statistics for all repositories. To run, simply use the following command:

(venv) laptop:github_data $ get_repo_list -u <username/organization>

This will generate a CSV file called "<username/organization>.csv". It is recommended to create a folder (e.g., github_data) as the contents will ultimately contain multiple files.

Next, let's gather the statistics for all public repositories that are not forks. We use another Python library that does this called github-traffic-stats. It is accompanied by a python script called gts.

To access traffic data, this requires a PAT. See above for instructions. Then you can execute the next script:

(venv) laptop:github_data $ token='abcdef12345678'
(venv) laptop:github_data $ gts_run_all_repos -u <username/organization> -t $token -c <username/organization>.csv

This will generate CSV files with date and time stamps prefixes for clones, traffic, and referrals. With routine running of this code, you will generate additional CSV files that allow for you to extend beyond a two-week window of data aggregation. The data can be merged with the merge-csv.sh script:

(venv) laptop:github_data $ ./merge-csv.sh

This generates three files: merge_clones.csv, merge_traffic.csv and merge_referrers.csv. These files are used in the final step to generate the plots.

Finally to generate static pages containing the visualization, we use the make_stats_plots script:

(venv) laptop:github_data $ make_stats_plots -u <username> -c <username>.csv -t $token

This will generate all contents in the local path. Note that you can specify an output directory with the -o/--out-dir option. Default is the current path.

The resulting folder structure, for example, will be the following:

github_data/
├── data
│   ├── 2021-01-17-00h-46m-clone-stats.csv
│   ├── 2021-01-17-00h-46m-referrer-stats.csv
│   ├── 2021-01-17-00h-46m-traffic-stats.csv
│   ├── ...
│   ├── merged_clone.csv
│   ├── merged_referrer.csv
│   └── merged_traffic.csv
├── repos
│   ├── github-stats-pages.html
│   └── ...
├── styles
|   ├── css
|   │   └── style.css
|   └── js
|       ├── bootstrap.min.js
|       ├── jquery.min.js
|       ├── main.js
|       └── popper.js
├── about.html
├── index.html
├── repositories.html
└── <username>.csv

Versioning

Continuous Integration

Authors

• Chun Ly, Ph.D. (@astrochun)

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE file for details.