GitHub Profiler

A Go CLI that analyzes a GitHub account via the GitHub REST API and produces a JSON evidence document describing the authenticated user's engineering activity. It is useful for building an engineering CV, portfolio, or profile: for every repository the user has contributed to, it records commit activity, programming languages, permissions, and links back to the actual commits.

Features

• Authenticates against GitHub and scans every repository the token can access (owned, collaborated, and organization membership).
• Per repository, captures:
  • Metadata: URL, visibility, description, default branch, fork/archived flags
  • Your permissions (admin, maintain, push, triage, pull)
  • Activity: total commit count, first and last contribution dates
  • Language breakdown with byte counts and percentages
  • The 20 most recent commits (SHA, message, author, date, URL)
  • A human-readable safe_summary line suitable for a CV
• Aggregate totals across all scanned repositories.
• Concurrent scanning (worker pool) for speed.
• Skips forked repositories by default; optionally includes them.
• Optional -since filter to count only commits after a given date.

Requirements

• Go 1.25 or newer (go.mod declares go 1.25.0)
• A GitHub personal access token (classic or fine-grained) with read access to the repositories you want to scan. A classic token with the repo scope works for private repositories; a public-only token covers public contributions.

Installation

go build -o github-profiler .

Create a GitHub token

The CLI requires a token in GITHUB_TOKEN. Keep it private: do not commit it, add it to a source file, or share it in screenshots.

Option 1: GitHub CLI (recommended)

Install GitHub CLI, then authenticate in your browser:

gh auth login

Choose GitHub.com, HTTPS, then Login with a web browser. Confirm the authorization, then use the token GitHub CLI stores securely for the current shell:

export GITHUB_TOKEN="$(gh auth token)"
./github-profiler

Verify the account at any time with:

gh auth status

Option 2: GitHub website

Open GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token. Give it a descriptive name, short expiration, and access to the repositories you want to scan. Grant repository Contents: Read-only, generate the token, copy it immediately, then run:

export GITHUB_TOKEN='github_pat_...'
./github-profiler

For private repositories across multiple organizations, a fine-grained token may not cover every resource owner. If your organization allows it, create a classic token with the repo scope instead. See GitHub's official personal access token guide for current permission and organization-approval requirements.

Usage

The token is read from the GITHUB_TOKEN environment variable; it is required.

export GITHUB_TOKEN=ghp_xxx
./github-profiler

The tool logs its progress to stderr and writes the evidence document to a timestamped filename by default, such as evidence-20260806T120000.123456789Z.json. Set -file-name-with-timestamp=false to write to the exact -output path.

Flags

Flag	Default	Description	Token permission when enabled
-output	evidence.json	Output JSON file path.	—
-file-name-with-timestamp	true	Append a UTC timestamp to the output filename.	—
-with-toon	false	Write TOON output with a .toon extension.	—
-since	(none)	Only count commits since this date.	—
-concurrency	4	Number of repositories scanned concurrently.	—
-max-recent-commits	20	Maximum recent commits recorded per repository.	—
-max-repositories	0	Maximum contributed repositories in final output.	—
-max-repository-scans	0	Maximum eligible repositories to scan.	—
-include-forks	false	Include forked repositories in the scan.	—
-exclude-private	false	Exclude private repositories from the scan.	—
-include-pull-requests	false	Include pull requests authored by you.	Classic: repo; fine-grained: Pull requests: Read-only
-include-reviews	false	Include pull request reviews submitted by you.	Classic: repo; fine-grained: Pull requests: Read-only
-include-issues	false	Include issues authored by you.	Classic: repo; fine-grained: Issues: Read-only
-include-discussions	false	Include discussions created by you.	Classic: repo; fine-grained: Discussions: Read-only
-exclude-repo	(none)	Exclude an owner/name repository; may be repeated.	—
-exclude-org	(none)	Exclude repositories owned by an organization; may be repeated.	—
-sort-repo-by	last-contribution-date-desc	Repository sort criterion; may be repeated.	—

For example, to skip a private repository and a fork:

./github-profiler \
-max-repository-scans 50 \
-max-repositories 20 \
-max-recent-commits 10 \
-exclude-repo your-account/private-project \
-exclude-repo upstream/example-fork \
-exclude-org example-organization

Exclusions are applied before -max-repository-scans, so it caps the number of repositories actually scanned. Repositories are considered in GitHub's full-name sort order. -max-repositories is applied afterwards: it limits the final sorted contributed-repository results and recalculates their totals.

Optional contribution evidence

Commits are always included. The following flags add opt-in evidence and allow a repository to appear when it contains one of these contributions but no attributed commit:

./github-profiler \
-include-pull-requests \
-include-reviews \
-include-issues \
-include-discussions

For a fine-grained token, grant read access to Pull requests, Issues, and Discussions for the selected repositories. Reviews can generate substantially more API requests because GitHub exposes them per pull request.

A classic token with repo covers all private-repository features above. For public repositories, GitHub permits many endpoints without those private-repository scopes.

Repository sorting

Use -sort-repo-by once or multiple times. Criteria are evaluated in the order provided: the first is the primary sort and each later criterion breaks ties.

./github-profiler \
-sort-repo-by=star-count-desc \
-sort-repo-by=project-size-desc

Available criteria:

• creation-date-desc, creation-date-asc
• first-contribution-date-desc, first-contribution-date-asc
• last-contribution-date-desc, last-contribution-date-asc
• star-count-desc, star-count-asc
• fork-count-desc, fork-count-asc
• commit-count-desc, commit-count-asc
• project-size-desc, project-size-asc

Without this flag, repositories remain sorted by latest contribution first. project-size uses the repository size reported by GitHub, in KB. Each repository also includes its star_count, fork_count, and project_size_kb in the output JSON.

Environment variables

Variable	Required	Default	Description
GITHUB_TOKEN	yes	—	Personal access token used for API calls.
GITHUB_API_URL	no	https://api.github.com	Override for GitHub Enterprise API base URL.

Output format

The output is a pretty-printed JSON document with the following top-level structure:

{
"profile": {
"github": "octocat",
"name": "The Octocat",
"email": "octocat@example.com",
"generated_at": "2026-08-06T12:00:00Z"
},
"totals": {
"accessible_repositories": 12,
"contributed_repositories": 8,
"public_repositories": 5,
"private_repositories": 3,
"commits": 342
},
"repositories": [
{
"repository": "octocat/hello-world",
"owner": "octocat",
"name": "hello-world",
"url": "https://github.com/octocat/hello-world",
"visibility": "public",
"description": "My first repository",
"default_branch": "main",
"fork": false,
"archived": false,
"star_count": 80,
"fork_count": 9,
"project_size_kb": 108,
"permissions": {
"admin": true,
"maintain": true,
"push": true,
"triage": true,
"pull": true
},
"activity": {
"commit_count": 42,
"first_contribution": "2023-01-15T10:00:00Z",
"last_contribution": "2026-07-30T09:30:00Z"
},
"languages": [
{ "name": "Go", "bytes": 20480, "percentage": 80.0 },
{ "name": "Markdown", "bytes": 5120, "percentage": 20.0 }
],
"recent_commits": [
{
"sha": "abc123",
"message": "Fix flaky test",
"author": "octocat",
"email": "octocat@example.com",
"date": "2026-07-30T09:30:00Z",
"url": "https://github.com/octocat/hello-world/commit/abc123"
}
],
"safe_summary": "Contributed to My first repository, using primarily Go, Markdown."
}
],
"warnings": [
"Only repositories accessible to the supplied token were scanned.",
"Commit attribution depends on GitHub associating commits with the authenticated username.",
"Squashed commits, alternate unverified emails, reviews, issues, discussions, and pair-programming activity may be missing.",
"Private repository names and commit messages must be reviewed before publishing."
]
}

Details worth knowing:

• Repositories with no commits attributed to the authenticated user are omitted.
• Repositories are sorted by most recent contribution (descending).
• Languages are sorted by byte count (descending), with percentages rounded to two decimals.
• Only the first line of each commit message is included in recent_commits.
• The output file is written with 0600 permissions to keep private data safe.

How it works

1. GET /user — identifies the authenticated user.
2. GET /user/repos (paginated, 100 per page) — lists all accessible repositories, covering owner, collaborator, and organization_member affiliations.
3. For each repository, concurrently:
   • GET /repos/{owner}/{repo}/commits?author={username} (paginated, optional since)
   • GET /repos/{owner}/{repo}/languages
4. Results are aggregated into the evidence document and written to the output file.

Project structure

The project stays as a single main package because it is a small, self-contained CLI. Files are separated by responsibility so the application flow and GitHub integration are easy to navigate:

.
├── main.go # CLI orchestration: fetch, analyze, sort, and write
├── config.go # Flags, environment variables, and validation
├── models.go # GitHub API and evidence-document data structures
├── github_client.go # GitHub REST requests, pagination, and API errors
├── analyzer.go # Concurrent repository analysis and commit evidence
├── evidence.go # Evidence-document creation and aggregate totals
├── output.go # JSON serialization and secure file writing
└── helpers.go # Date, repository-name, summary, and rounding helpers

If the CLI gains more commands or integrations, the next step would be to move these concerns into internal/ packages (for example internal/github and internal/evidence) while keeping main.go as the command entry point.

Caveats

• The scan only sees repositories the supplied token can access. Totals reflect what the token can see, not necessarily the entire account.
• Commit counts depend on GitHub's author association. Squashed commits, commits made under unverified or alternate emails, reviews, issues, discussions, and pair-programming work are not counted.
• The output contains private repository names and commit messages — review the JSON before sharing or publishing it.