GitHub Readme Stats 📊

This project builds upon the previous work by Jainam Desai¹. Please consider starring this repository if you find it useful! ⭐️

Installation

To integrate this action into your repository, start by creating a GitHub Action workflow file. In your repository, navigate to/create .github/workflows/update-readme.yaml.

name: Update Readme

on:
  schedule:
    - cron: "1 3 * * *" # best to run at random time of day
  workflow_dispatch:

jobs:
  Update:
    name: Update Stats
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: mahyarmirrashed/github-readme-stats@main # v1.0 and other tags exist, as well
        with:
          GITHUB_TOKEN: ${{ secrets.PAT }}
          TIMEZONE: "America/Winnipeg"
          INCLUDES:
            "--include DAY_STATS --include WEEK_STATS --include LANGUAGE_STATS"

Next, generate a Personal Access Token (PAT) in your GitHub Settings Page. There, select the Generate new token: fine-grained, repo-scoped option.

Give your token a name (e.g. "Profile Stats"), an expiration (e.g. 30 days), and a description. For the permissions, you need to give access to "All repositories", and selecting "read-only" "Content" access for the "Repository Permissions". Then, generate the token.

Once the token is generated, copy it, and create a new repository secret for your repository. (It will be located at an address like https://github.com/<user>/<repo>/settings/secrets/actions.) There, create a new repository secret, name it PAT, and paste the generated token in the body!

Warning

Generally, it is not safe to give such encompassing permissions for a Personal Access Token, like read permissions for all repositories. However, there is no other way to get the statistics you desire without this permission.

I created this GitHub action to keep the processing of this information local to GitHub's infrastructure (unlike WakaTime² to reduce potential attack surfaces.

Usage

This action operates by updating a specific section in your README.md file.

Adding the Markers

Insert the following markers where you want the statistics to appear:

<!-- README-STATS:START -->

<!-- README-STATS:END -->

When the GitHub Action runs, it will populate the section between these markers with your chosen statistics.

Example Configuration

To include daily, weekly, and language statistics, set the INCLUDES parameter as follows:

INCLUDES: "--include DAY_STATS --include WEEK_STATS --include LANGUAGE_STATS"

Configuration

You can customize the statistics included and their order by modifying the INCLUDES parameter in your workflow file.

Available Includes

• DAY_STATS: Commit statistics based on the time of day.
• WEEK_STATS: Commit statistics based on the day of the week.
• LANGUAGE_STATS: Programming language usage statistics.

Troubleshooting

• README.md Not Found: Ensure that README.md exists in the root of your repository and that you’ve added the <!-- README-STATS:START --> and <!-- README-STATS:END --> markers.
• Permissions Error: Verify that your PAT has the necessary scopes (repo and read:user).
• Incorrect Timezone: Make sure the timezone string is valid (e.g., "America/Winnipeg").

Contributions

Contributions are welcome! Please open an issue or submit a pull request for any enhancements or bug fixes.

Footnotes

1. https://github.com/th3c0d3br34ker/github-readme-info ↩

2. https://wakatime.com/plugins/status?onboarding=true ↩