https://github.com/benovermyer/github-reports
A script to generate repository statistics for GitHub in chart form.
https://github.com/benovermyer/github-reports
github project-management
Last synced: about 2 months ago
JSON representation
A script to generate repository statistics for GitHub in chart form.
- Host: GitHub
- URL: https://github.com/benovermyer/github-reports
- Owner: BenOvermyer
- License: mit
- Created: 2025-11-21T20:02:20.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-11-21T20:08:14.000Z (7 months ago)
- Last Synced: 2025-11-21T22:08:36.651Z (7 months ago)
- Topics: github, project-management
- Language: Python
- Homepage:
- Size: 45.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GitHub Reports CLI
A Python CLI tool to generate project management charts (burndown, commit summaries, and more) from GitHub repositories using the GitHub REST API.
## Requirements
- Python 3.12+
- [uv (Astral)](https://github.com/astral-sh/uv) for dependency management and running
- A GitHub personal access token (PAT)
### Required GitHub PAT Permissions
Your personal access token must have the following scopes:
- `repo` (Full control of private repositories)
- Required to read issues and commits from private repositories
- `public_repo` (Access public repositories)
- Sufficient for public repositories only
For most use cases, the `repo` scope is recommended. You can generate a PAT at https://github.com/settings/tokens
## Installation
1. Install [uv](https://github.com/astral-sh/uv):
```sh
curl -Ls https://astral.sh/uv/install.sh | sh
# or see uv docs for your OS
```
2. Install dependencies:
```sh
uv sync
```
3. (Optional) Install as CLI:
```sh
uv pip install -e .
```
## Building a Standalone Binary
To build a standalone executable that can be distributed or added to your PATH without requiring a Python environment:
1. Run the publish script:
```sh
./publish.sh
```
2. The binary will be created at `dist/github-reports`.
3. You can move this binary to a directory in your PATH (e.g., `~/.local/bin` or `/usr/local/bin`):
```sh
mv dist/github-reports ~/.local/bin/
```
4. Now you can run the tool from anywhere:
```sh
github-reports --help
```
## Usage
All commands accept a comma-separated list for `--repo` to aggregate data across multiple repositories.
### Burndown Chart
Generate a burndown chart of open/closed issues over time:
```sh
github-reports burndown --repo octocat/Hello-World --token --output burndown.png
github-reports burndown --repo octocat/Hello-World,psf/requests --token --output burndown.png
```
### Commit Summary
Generate a weekly commit count summary per user:
```sh
github-reports commit-summary --repo octocat/Hello-World --token --months 3 --output commits.png
github-reports commit-summary --repo octocat/Hello-World,psf/requests --token --months 6 --output commits.png
```
### Issue Type Breakdown
Pie or bar chart of issue labels:
```sh
github-reports issue-type-breakdown --repo octocat/Hello-World --token --output labels.png --chart-type pie
github-reports issue-type-breakdown --repo octocat/Hello-World,psf/requests --token --output labels.png --chart-type bar
```
### PR Activity Timeline
Line chart of PRs opened/closed/merged per week:
```sh
github-reports pr-activity-timeline --repo octocat/Hello-World --token --output pr_timeline.png
github-reports pr-activity-timeline --repo octocat/Hello-World,psf/requests --token --output pr_timeline.png
```
### Issue Resolution Time
Histogram or boxplot of time taken to close issues:
```sh
github-reports issue-resolution-time --repo octocat/Hello-World --token --output resolution.png --chart-type hist
github-reports issue-resolution-time --repo octocat/Hello-World,psf/requests --token --output resolution.png --chart-type box
```
## Popular Repository Examples
- `octocat/Hello-World` (GitHub's sample repo)
- `psf/requests` (Popular Python HTTP library)
- `django/django` (Popular Python web framework)
You can aggregate across any combination:
```sh
github-reports burndown --repo octocat/Hello-World,django/django,psf/requests --token --output burndown.png
```
## Development
- All dependencies are managed with `uv`.
- CLI entry point: `github_reports/cli.py`
- Utility functions: `github_reports/utils.py`