repo-metrics

name

repo-metrics

description

GitHub repo metrics for your-org/your-repo. Tracks total stars, stars added, weekly contributors (unique humans across issues/PRs/comments), new and active PRs, new and active issues, unique visitors, unique clones, and pageviews. Stores traffic + star snapshots to CSV for historical tracking. Use when the user asks for "repo metrics", "GitHub stats", "OSS metrics", "how's the repo doing", or wants contributor/traffic numbers.

Repo Metrics

Fetch weekly GitHub metrics for your-org/your-repo and display a week-over-week summary. Traffic and star counts are persisted to CSV since the GitHub traffic API only retains 14 days.

Metrics tracked

1. Total stars — current stargazer count
2. Stars added — delta from previous snapshot (requires running weekly to build history)
3. Contributors per week — unique humans who opened an issue, opened a PR, or commented on an issue/PR. Bots excluded.
4. New PRs per week — PRs created in the week
5. Active PRs per week — PRs updated in the week
6. New issues per week — issues created in the week
7. Active issues per week — issues updated in the week (capped at 1,000 by search API)
8. Unique visitors per week — from traffic API
9. Unique clones per week — from traffic API
10. Pageviews per week — from traffic API

Prerequisites

Auth priority (first match wins):

1. GITHUB_TOKEN_FOR_REPO_STATS_IN_BUZZ env var — a repo-scoped token, used in cloud runs
2. GITHUB_TOKEN env var — generic fallback
3. gh CLI — auto-detected locally if authenticated (gh auth status). No PAT needed.

For traffic endpoints (views, clones), the token or gh account needs push access to the repo.

The scripts use only the Python standard library — run them with your system python3 (no virtualenv or extra packages needed).

Parameters

• Period — number of days to look back. Default: 14 (two Mon–Sun weeks). Override via user request.
• Repo — defaults to your-org/your-repo.

Workflow

Step 1: Fetch metrics

python3 .agents/skills/repo-metrics/scripts/fetch_metrics.py --days 14 > /tmp/repo_metrics.json

The script:

• Fetches repo metadata (star count)
• Fetches daily traffic (views, clones) and groups into Mon–Sun weeks
• Runs per-week search queries for: new PRs, active PRs, new issues, active issues
• Fetches issue/PR comments and counts unique human authors per week (= contributors)
• Outputs structured JSON with a weeks array containing all metrics per week

Step 2: Store history

python3 .agents/skills/repo-metrics/scripts/store_traffic.py /tmp/repo_metrics.json

Appends to CSVs in reports/github-traffic/:

• daily_traffic.csv — daily views/clones, deduped by date
• stars.csv — snapshot date + star count (for computing “stars added” week-over-week)

Step 3: Present results

Format a week-over-week summary:

📊 your-org/your-repo — Weekly Metrics

                         Apr 21–27    Apr 28–May 3
Total stars              10,000          12,500
Stars added                   —           2,500
Contributors/week            50             120
New PRs/week                  8              40
Active PRs/week              12              45
New issues/week              15              35
Active issues/week          110             140
Unique visitors/week      4,000          20,000
Unique clones/week          100             400
Pageviews/week            8,000          40,000

Step 4: Validate

• If traffic returns 403, flag that the token lacks push access
• If search returns >1,000 results, note the count is capped
• Star count should match what's shown on the repo page
• “Stars added” requires a prior snapshot — will be blank on first run

Important notes

• Traffic data only covers 14 days — run at least every 14 days to avoid gaps.
• Stars added requires historical snapshots — the API doesn’t provide per-day star counts for repos >40K stars. The store script records the current count each run; the delta gives “stars added”.
• Search API caps at 1,000 results per query. “Active issues” may hit this.
• Contributors = unique humans who opened issues, PRs, or commented. Bots excluded by checking user.type == "Bot" or login ending in [bot].
• Weeks are Mon–Sun, matching GitHub’s convention.
• Do NOT log or hardcode tokens — use env vars.