| 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
- Total stars — current stargazer count
- Stars added — delta from previous snapshot (requires running weekly to build history)
- Contributors per week — unique humans who opened an issue, opened a PR, or commented on an issue/PR. Bots excluded.
- New PRs per week — PRs created in the week
- Active PRs per week — PRs updated in the week
- New issues per week — issues created in the week
- Active issues per week — issues updated in the week (capped at 1,000 by search API)
- Unique visitors per week — from traffic API
- Unique clones per week — from traffic API
- Pageviews per week — from traffic API
Prerequisites
Auth priority (first match wins):
GITHUB_TOKEN_FOR_REPO_STATS_IN_BUZZ env var — a repo-scoped token, used in cloud runsGITHUB_TOKEN env var — generic fallbackgh 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 datestars.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.
