Package: github-stats-pages
github-stats-pagesRetrieve statistics for a user's repositories and populate the information onto a GitHub static pageCategoriesStatusGeneralCI/CDPyPIOverviewRequirementsDeploymentGitHub Actions DeploymentDocker DeploymentFrom SourceInstallationExecutionFAQVersioningContinuous IntegrationAuthorsLicenseUsed byOverviewThis 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 waysPython - Most of the code is Python (excluding static assets) with static typesCopy-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 actionEnvironmentally friendly -Websitecarbon.comreported that a GitHub Pages deployment of this code has a lower carbon
footprint than 90% of web pages testedRequirementsTraffic datafor 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 usesGitHub's Personal Access Token (PAT).To create one, follow theseinstructionsor gohere.
For scopes, select:repo. Save your PAT in a safe place as you will need it later.DeploymentThis code is intended to deploy in a number of ways to allow for the greatest flexibility.
First, this repository is also as aGitHub Docker container action(seebelow).
Second, this code is package onPyPI.
Third, the source code can beforkedor cloned.
Finally, aDockerfileis included for containerization.GitHub Actions DeploymentTL;DRFor easy deployment, try thisGitHub template. Simply:Use it!Add a Personal access token, as a repository secret,GH_TOKEN.
Seeabove(Settings > Secrets)If not already enabled, enable GitHub Actions (Settings > Actions)Sit back and enjoy that ☕️ !Note: After the first Action run, you may need to enable GitHub pages through
the  settings page and selectgh-pages(Settings > Pages)The Nitty GrittyGitHub Pages deployment is simple with the following GitHub Actionscronjobworkflow:name:Deploy GitHub pages with traffic statson:schedule:-cron:"03***"jobs:build-n-publish:runs-on:ubuntu-latestenv:BOT_NAME:'github-actions[bot]'BOT_EMAIL:'41898282+github-actions[bot]@users.noreply.github.com'steps:-name:Checkoutuses:actions/checkout@v2-name:Get current dateid:daterun:echo "::set-output name=date::$(date +'%Y-%m-%d')"-name:Build GitHub stats pagesuses:astrochun/github-stats-pages@latestwith:username:${{ github.repository_owner }}token:${{ secrets.GH_TOKEN }}-name:Upload data to main branchuses:EndBug/add-and-commit@v7.0.0with:add:'data'branch:mainmessage:"Updatedata:${{steps.date.outputs.date}}"author_name:env.BOT_NAMEauthor_email:env.BOT_EMAIL-name:Upload static files to gh-pagesuses:peaceiris/actions-gh-pages@v3with:personal_token:${{ secrets.GH_TOKEN }}publish_dir:./publickeep_files:falseuser_name:env.BOT_NAMEuser_email:env.BOT_EMAILpublish_branch:gh-pagescommit_message:"Updatestaticpages:${{steps.date.outputs.date}}"This workflow will run for all public repositories.InputsVariableDescriptionRequired?TypeDefaultsExamplesusernameGitHub username or organizationYesstrN/AastrochuntokenGitHub Personal Access Token (PAT)YesstrN/Aabcdef12345678include-reposComma-separated lists of repositories. This overrides the full list of public repositoriesNostr'''github-stats-pages,astrochun.github.io'exclude-reposComma-separated lists of repositories to exclude from default public repository listNostr'''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) forinclude-reposargument.-name:Build GitHub stats pagesuses:astrochun/github-stats-pages@latestwith:username:${{ github.repository_owner }}token:${{ secrets.GH_TOKEN }}include-repos:"github-stats-pages"Alternatively to exclude specific repositories from the list of public repositories,
use theexclude-reposargument with a comma-separated list (no spaces between commas).-name:Build GitHub stats pagesuses:astrochun/github-stats-pages@latestwith:username:${{ github.repository_owner }}token:${{ secrets.GH_TOKEN }}exclude-repos:"repo1,repo2"Note that you can only specifyinclude-reposorexclude-repos.Specifying both will fail!Docker DeploymentThis repository includes aDockerfile.
More details/instructions provided later.From sourceTo run this code from original source, you will need to install it.InstallationUse ourPyPI packageto
get the most stable release:(venv) $ pip install github-stats-pagesOr 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 installExecution from sourceTL;DR: If you decide to run this code from source, there are a few things you should know.First, this repository includes anentrypoint.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 $tokenSecond, it is recommended to create a folder (e.g.,github_data) as the contents
will ultimately contain multiple files.More detailsHere's an overview providing more details how this codebase works.
There are four primary scripts accompanyinggithub-stats-pagesget_repo_listgts_run_all_reposmake_stats_plotsmerge_csvget_repo_listgenerates 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 calledgithub-traffic-stats. It
is accompanied by apythonscript calledgts.To access traffic data, this requires a PAT. Seeabovefor 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>.csvThis 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 themerge-csv.shscript:(venv) laptop:github_data $ merge_csvThis generates four files: merged_clone.csv, merged_paths.csv, merged_referrers.csv,
and merge_traffic.csv. These files are used in the final step to generate the
plots.Finally to generate static pages containing the visualization, we
use themake_stats_plotsscript:(venv) laptop:github_data $ make_stats_plots -u <username> -c <username>.csv -t $tokenThis will generate all contents in the local path. Note that you can specify
an output directory with the-o/--out-diroption. 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_paths.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>.csvFAQ1. How do I add old data?If you ran this code outside your production deployment (e.g., GitHub pages),
it is in fact straightforward to include those data.For GitHub Pages deployment, simply:git cloneyour copy of thegithub-statsrepoMove/copy previous CSV files to thedatafolder in themainbranch.
These files follow a YYYY-MM-DD prefixThen add, commit, and push:git add data/????-??-??*stats.csv,git commit -m "Add old data",git pushOn the next GitHub Action scheduled run, the live pages will automatically incorporate these data.For any other deployments (e.g., cloud), simply:Move/copy/rsync/scpthe previous CSV files to thedatafolder in the deployed instanceUpon the nextcronjobor script run, the old data will automatically be incorporated.2. How do I add content to the home page (index.html)?The deployedindex.htmlcan be customized to provide a biography, cool
graphics, and/or additional statistics. This is possible through aGitHub profile READMEthat you can create. The link above provides instruction for setting up one. This software
will convert the markdown content to HTML and include it in theindex.html.
An example of the outcome can be foundhere.Many GitHub users have developed fancy GitHub profile READMEs:https://github.com/abhisheknaiidu/awesome-github-profile-readme.
By including those in your profile README, they should be included in your deployed version.
If it doesn't work, feel free to reach out.Note: While a GitHub profile README does not work for an organization in the same manner as
individual GitHub accounts, this software will still use its content if it is publicly available.
Here's anexample3. What happens when I renamed a repository?This software will retrieve the latest list of public repositories. When the
statistics pages are then generated, it searches thedata/folder for the
information for each repo. As such, there is an issue with renaming of
repositories. This will be apparent in the logs with the following warnings:WARNING: Possible issue with repository name, ...
If you renamed it, you will need to update data/ contentsTo rectify this issue, you cangit cloneyour GitHub repository, and rename
each occurrence of the old repositories with the new ones using your preferred
IDE or command-line options (e.g.,sed). Thengit add,git commit, andgit pushthese changes. The next scheduled run will then work as intended.VersioningContinuous IntegrationAuthorsChun Ly, Ph.D. (@astrochun)See also the list ofcontributorswho participated in this project.LicenseThis project is licensed under theMIT License- see theLICENSEfile for details.Used byA list of repos usinggithub-stats-pagescan be foundhere.