Retrieve statistics for a user's repositories and populate the information onto a GitHub static page
Project description
github-stats-pages
Retrieve statistics for a user's repositories and populate the information onto a GitHub static page
- Overview
- Requirements
- Deployment
- Installation
- Execution
- Versioning
- Continuous Integration
- Authors
- License
- Used by
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).
Some key features of this software:
- Flexible - Designed to be deployed in a number of ways
- Python - Most of the code is Python (excluding static assets) with static types
- Copy-left license: This is supported by open source and thus is open source with an MIT License!
- Continuous Integration - We currently have 100% code coverage of the Python codebase and the Docker action
- Environmentally friendly - Websitecarbon.com reported that a GitHub Pages deployment of this code has a lower carbon footprint than 90% of web pages tested
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
TL;DR
For easy deployment, try this GitHub template. Simply:
- Use it!
- Add a Personal access token, as a repository secret,
GH_TOKEN
. See above (Settings > Secrets) - Enable GitHub Actions (Settings > Actions)
- Enable GitHub pages through the settings page and select
gh-pages
(Settings > Pages) - Sit back and enjoy that ☕️ !
The Nitty Gritty
GitHub Pages deployment is simple with the following GitHub Actions cronjob
workflow:
name: Deploy GitHub pages with traffic stats
on:
schedule:
- cron: "0 3 * * *"
jobs:
build-n-publish:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Get current date
id: date
run: echo "::set-output name=date::$(date +'%Y-%m-%d')"
- name: Build GitHub stats pages
uses: astrochun/github-stats-pages@latest
with:
username: ${{ github.actor }}
token: ${{ secrets.GH_TOKEN }}
- name: Upload data to main branch
uses: EndBug/add-and-commit@v7.0.0
with:
add: 'data'
branch: main
message: "Update data: ${{ steps.date.outputs.date }}"
author_name: 'github-actions[bot]'
author_email: '41898282+github-actions[bot]@users.noreply.github.com'
- name: Upload static files to gh-pages
uses: peaceiris/actions-gh-pages@v3
with:
personal_token: ${{ secrets.GH_TOKEN }}
publish_dir: ./public
keep_files: false
user_name: 'github-actions[bot]'
user_email: '41898282+github-actions[bot]@users.noreply.github.com'
publish_branch: gh-pages
commit_message: "Update static pages: ${{ steps.date.outputs.date }}"
This workflow 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
get_repo_list
gts_run_all_repos
merge-csv.sh
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.
Used by
A list of repos using github-stats-pages
can be found here
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for github_stats_pages-0.3.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8acde87dcd6a8b119402d84f06cfe3eeed388482ee2edd597c2b94e6aa7731bf |
|
MD5 | 974a78174f00c3f78cb10eeb673e724b |
|
BLAKE2b-256 | fad51a4f49c7be930d633b876d0996f5df65daa91a960b7ded8f53044ebc031c |