stats-action/README.md

GitHub Stats Action

A GitHub Action that collects comprehensive statistics for a user's GitHub profile and outputs them to a JSON file. Perfect for building profile READMEs, dashboards, or personal analytics.

Features

• Profile Data: Name, bio, company, location, social links
• Contribution Stats: Total contributions, streaks, most active day, monthly breakdown
• Repository Metrics: Stars, forks, views, top repositories
• Code Statistics: Lines added/deleted, commit counts, languages with percentages
• Social Stats: Followers, following, stars given
• Activity Data: Pull requests, issues, PR reviews, discussions

Requirements

Personal Access Token (PAT)

This action requires a Personal Access Token - the default GITHUB_TOKEN will not work because:

• Contribution calendar data requires authentication as the actual user
• Repository view counts require push access across all repositories
• The viewer GraphQL query returns data for the token owner

Required PAT Scopes

Scope	Purpose
read:user	Access user profile data
repo	Access repository statistics, views, and private repos

Creating a PAT

1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Click "Generate new token"
3. Select the scopes listed above
4. Copy the token and add it as a repository secret (e.g., USER_PAT)

Usage

Basic Workflow

Create .github/workflows/stats.yaml:

name: Collect GitHub Stats

on:
  schedule:
    - cron: '0 0 * * *'  # Run daily at midnight
  workflow_dispatch:      # Allow manual trigger

jobs:
  collect-stats:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Collect GitHub Stats
        uses: LukeHagar/stats-action@v1
        env:
          GITHUB_TOKEN: ${{ secrets.USER_PAT }}

      - name: Commit stats
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "chore: update github stats"
          file_pattern: github-user-stats.json

Template Repository

For a complete setup with visualization, use the stats template repository.

Output

The action creates a github-user-stats.json file with the following structure:

Profile Information

Field	Type	Description
name	string	Display name
username	string	GitHub username
avatarUrl	string	Profile picture URL
bio	string | null	Profile bio
company	string | null	Company name
location	string | null	Location
email	string | null	Public email
twitterUsername	string | null	Twitter/X handle
websiteUrl	string | null	Website URL
createdAt	string	Account creation date (ISO 8601)

Statistics

Field	Type	Description
totalCommits	number	Total commits (from GitHub search)
commitCount	number	Commits from contributor stats
totalPullRequests	number	Total PRs created
totalPullRequestReviews	number	Total PR reviews
totalContributions	number	All-time contributions
openIssues	number	Open issues created
closedIssues	number	Closed issues created
discussionsStarted	number	Discussions started
discussionsAnswered	number	Discussion answers marked as correct
repositoriesContributedTo	number	Repos contributed to

Repository Metrics

Field	Type	Description
starCount	number	Total stars received
forkCount	number	Total forks of your repos
starsGiven	number	Repos you've starred
repoViews	number	Total repo views (last 14 days)

Code Statistics

Field	Type	Description
linesAdded	number	Total lines added
linesDeleted	number	Total lines deleted
linesOfCodeChanged	number	Total lines changed (added + deleted)
codeByteTotal	number	Total bytes of code

Social

Field	Type	Description
followers	number	Follower count
following	number	Following count

Languages

{
  "topLanguages": [
    {
      "languageName": "TypeScript",
      "color": "#3178c6",
      "value": 1234567,
      "percentage": 45.5
    }
  ]
}

Contribution Stats

{
  "contributionStats": {
    "longestStreak": 42,
    "currentStreak": 7,
    "mostActiveDay": "Tuesday",
    "averagePerDay": 3.5,
    "averagePerWeek": 24.5,
    "averagePerMonth": 105.0,
    "monthlyBreakdown": [
      { "month": "2024-01", "contributions": 120 }
    ]
  }
}

Top Repositories

{
  "topRepos": [
    {
      "name": "repo-name",
      "description": "Repo description",
      "stars": 100,
      "forks": 25,
      "isArchived": false,
      "primaryLanguage": "TypeScript",
      "updatedAt": "2024-01-15T10:30:00Z",
      "createdAt": "2023-06-01T08:00:00Z"
    }
  ]
}

Full Contribution Calendar

The contributionsCollection field contains the complete contribution calendar with daily data for building heatmaps.

Development

Prerequisites

• Bun v1.0+

Setup

# Install dependencies
bun install

# Run locally (requires GITHUB_TOKEN env var)
export GITHUB_TOKEN=your_pat_here
bun run start

# Run tests
bun test

# Type check
bun run typecheck

Project Structure

├── src/
│   ├── index.ts       # Main action logic
│   ├── index.test.ts  # Tests
│   └── Types.ts       # TypeScript type definitions
├── action.yml         # GitHub Action definition
├── package.json
└── tsconfig.json

License

MIT - see LICENSE.md