https://github.com/lukehagar/stats-action
A github action to grab github stats for further processing
https://github.com/lukehagar/stats-action
Last synced: 6 months ago
JSON representation
A github action to grab github stats for further processing
- Host: GitHub
- URL: https://github.com/lukehagar/stats-action
- Owner: LukeHagar
- License: mit
- Created: 2024-02-26T13:30:13.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-08T21:14:54.000Z (about 2 years ago)
- Last Synced: 2024-04-21T01:24:00.884Z (about 2 years ago)
- Language: TypeScript
- Size: 631 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# 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](https://github.com/settings/tokens?type=beta)
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`:
```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](https://github.com/LukeHagar/stats/).
## 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
```json
{
"topLanguages": [
{
"languageName": "TypeScript",
"color": "#3178c6",
"value": 1234567,
"percentage": 45.5
}
]
}
```
### Contribution Stats
```json
{
"contributionStats": {
"longestStreak": 42,
"currentStreak": 7,
"mostActiveDay": "Tuesday",
"averagePerDay": 3.5,
"averagePerWeek": 24.5,
"averagePerMonth": 105.0,
"monthlyBreakdown": [
{ "month": "2024-01", "contributions": 120 }
]
}
}
```
### Top Repositories
```json
{
"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](https://bun.sh) v1.0+
### Setup
```bash
# 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](LICENSE.md)