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

Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
Click "Generate new token"
Select the scopes listed above
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

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

README.md

GitHub Stats Action