github-metrics

name	github-metrics
description	How to calculate GitHub community pulse metrics using the `gh` CLI. Use this skill whenever the user asks for pull request metrics, issue metrics, community pulse, average merge times, top contributors, or bug reports over a specific timeframe.

GitHub Community Metrics (gh-pulse)

Use this skill when you need to calculate metrics about GitHub repositories, such as PRs created, issues created, average merge times, and top contributors.

Tools to use

You should use the gh CLI for querying GitHub's API. To get raw data over a specific timeframe, you should leverage the --search flag with date queries.

Fetching PR Metrics

To fetch PRs created within a month (e.g., Dec 2024), use:

gh pr list -R <owner>/<repo> --search "created:2024-12-01..2024-12-31" --state all --json number,state,createdAt,mergedAt,author --limit 1000

This gives you a JSON array of PR objects. You can then process this JSON using tools like jq or a small Python script to calculate:

• Total: Length of the array.
• Merged: Count where state is "MERGED" (or where mergedAt is not null). Note that GitHub CLI's state field might say MERGED or it might just say CLOSED with a mergedAt timestamp depending on the query, so prefer using mergedAt or state.
• Closed: Count where state is "CLOSED" and it's not merged.
• Average Time-to-Merge: For each merged PR, parse createdAt and mergedAt (ISO 8601), compute the difference in days, sum them up, divide by merged count. Round to one decimal.
• Top Contributor: Tally author.login of each PR, find the maximum.

Fetching Issue Metrics

To fetch Issues created within a timeframe, use:

gh issue list -R <owner>/<repo> --search "created:2024-12-01..2024-12-31 is:issue" --state all --json number,state,labels --limit 1000

• Total: Length of the array.
• Bugs: Filter where at least one label's name contains "bug" (case-insensitive substring).
• Resolved/Closed Bugs: Of those bugs, count how many have state as "CLOSED".

Best Practices

• Write a short Python script to orchestrate the gh calls and compute metrics. This is much more reliable and robust than attempting complex bash strings.
• Always add --limit large enough to capture the month's activity (e.g., --limit 1000).