https://github.com/devzom/github-monthly-report
Semi-automated bash tool for generating monthly tax deductible reports based on GitHub merged pull requests as TXT or PDF files with summary
https://github.com/devzom/github-monthly-report
bash bash-script deductible pull-request reports
Last synced: 4 months ago
JSON representation
Semi-automated bash tool for generating monthly tax deductible reports based on GitHub merged pull requests as TXT or PDF files with summary
- Host: GitHub
- URL: https://github.com/devzom/github-monthly-report
- Owner: devzom
- License: mit
- Created: 2025-08-28T09:37:17.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-11-06T09:41:55.000Z (8 months ago)
- Last Synced: 2025-11-06T11:24:26.241Z (8 months ago)
- Topics: bash, bash-script, deductible, pull-request, reports
- Language: Shell
- Homepage:
- Size: 38.1 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Monthly work report generator based on GitHub PR diffs
Comprehensive tool for generating monthly tax deductible reports based on GitHub pull requests.
Automatically downloads diff files and creates organized summaries for tax reporting purposes.
By default it produces `.txt` files, but can be configured to generate `.pdf` files as well.
Supports flexible organization targeting - either specify the organization as a parameter or set a default in the script.
## Setups
- Bash shell (macOS/Linux) or Git Bash/WSL (Windows)
- _GitHub CLI_ `gh` installed and authenticated
- `jq` command-line JSON processor
### Installing GitHub CLI and jq
```bash
# macOS (Homebrew)
brew install gh jq
# Ubuntu/Debian
sudo apt update && apt install gh && apt install jq
```
**Windows:**
```powershell
# Using winget (Windows 10 1709+)
winget install --id GitHub.cli && winget install stedolan.jq
# Using Chocolatey
choco install gh && choco install jq
```
**Other platforms:** Visit https://cli.github.com/ for installation instructions
### Authentication
#### Initial GitHub CLI auth:
```bash
# Authenticate with GitHub
gh auth login
```
##### Follow prompts to
1. Choose GitHub.com
2. Select HTTPS or SSH protocol
3. Authenticate via web browser or personal access token
4. Choose your preferred git protocol
#### Required permissions:
- Read access to repositories in the target organization
- Ability to view pull requests and their diffs
### Script setup
More details
#### Make script executable (macOS/Linux):
```bash
chmod +x generate-report.sh
```
#### Windows setup:
For Windows users, you have several options:
1. **Git Bash** (Recommended):
- Install Git for Windows (includes Git Bash)
- Open Git Bash terminal
- Navigate to script directory and run as shown in usage examples
2. **Windows WSL**:
- Install WSL2 with Ubuntu
- Install dependencies within WSL environment
- Run script from WSL terminal
3. **PowerShell with Git Bash**:
```powershell
# Run from PowerShell
bash ./generate-report.sh
```
## Organization configuration
You have two options for specifying the target GitHub organization:
### Option 1: Pass as parameter (recommended)
Simply provide the organization name as the first parameter when running the script:
```bash
./generate-report.sh my-org-name
```
### Option 2: Edit default in script file
Alternatively, you can set a default organization by editing the script:
```bash
# Modify this line in generate-report.sh:
repositoryOwner="your-org-name"
```
> [!TIP]
> Using the parameter approach (Option 1) is more flexible as it allows you to work with different organizations without modifying the script.
#### PDF Generation workflow (optional)
To generate diff files as PDF documents, you need to install the following dependencies via Homebrew:
```bash
brew install enscript ghostscript
```
## Usage
### Configuration
The script need to configure organization / repo owner.
To use with a different organization, modify the `repositoryOwner` variable at the top of the script.
### With organization parameter (recommended)
#### macOS/Linux/Windows (Git Bash):
```bash
# Generate report for current month (uses default org from script)
./generate-report.sh
# Generate report for current month with specific organization
./generate-report.sh my-org-name
# Generate report for specific month with organization
./generate-report.sh my-org-name 2025-07
# Generate report for custom date range with organization
./generate-report.sh my-org-name 2025-07-01 2025-07-31
```
### Output
1. **Console log**: Detailed PR information with repository, title, PR number, close date, diff URL, and PR URL
2. **Summary by repository**: Count of PRs per repository
3. **Diff file downloads**: Individual diff files saved locally in organized directory structure
4. **Summary file**: Master list linking PR titles to their corresponding diff files
### Example output
More details
```
Generating report for period: 2025-07-01 to 2025-07-31
======================================================
Fetching merged pull requests...
Found 8 merged pull requests
PR DIFFS FOR TAX DEDUCTIBLE REPORT
==================================
Repository: your-org-name/repositoryExample
Title: prefix-168: Fix export and release o pkg
PR number: #218
Closed at: 2025-04-29T11:25:40Z
Diff URL: https://github.com/your-org-name/repositoryExample/pull/218.diff
PR URL: https://github.com/your-org-name/repositoryExample/pull/218
------------------------------------------------------------
SUMMARY BY REPOSITORY
====================
6 PRs: your-org-name/repositoryExample
1 PRs: your-org-name/repositoryExample2
1 PRs: your-org-name/repositoryExample3
DIFF URLS
================================
https://github.com/your-org-name/repositoryExample/pull/218.diff
...
GENERATING DIFFs
===============================================
✓✓✓ Generated: diffs/2025-07-01_2025-07-31/repositoryExample-217.......txt
...
✓✓✓ Generated summary: diffs/2025-07-01_2025-07-31/summary.txt
```
## Features
- **Organization targeting**: Pass organization name as parameter or use default from script
- **Smart date from/to handling**: Automatically detects month boundaries and handles edge cases
- **Local diffs storage**: Downloads actual diff files and stores them in organized directory structure
- **File organization**: Creates time-stamped directories (`YYYY-MM-DD_YYYY-MM-DD`) for easy archiving
- **Summary generation**: Creates master summary file linking PR titles to their diff files
- **Multiple outputs**: Console report, individual diff files, and summary file
- **Large diff fallback**: Automatically falls back to the [List pull request files](https://docs.github.com/en/rest/pulls/pulls#list-pull-requests-files) REST API when a diff exceeds GitHub's 300-file limit
- **Error handling**: Gracefully handles missing PRs, network issues, and invalid dates
- **Filename sanitization**: Cleans PR titles for safe filesystem usage
## Structure
The script creates the following directory structure:
```
diffs/
└── YYYY-MM-DD_YYYY-MM-DD/
├── summary.txt
├── repo-name-123-PR_Title_Sanitized.txt
├── repo-name-124-Another_PR_Title.txt
└── ...
```
- **summary.txt**: Master file with format `[PR Title]-[filename]` for each diff
- **Individual diffs files**: Named as `{repo-short-name}-{pr-number}-{sanitized-title}.txt`
## GitHub CLI commands used
The script uses these GitHub CLI commands internally:
```bash
# Search for merged PRs
gh search prs --author=@me --owner="your-org-name" --merged --created="YYYY-MM-DD..YYYY-MM-DD" --json title,repository,url,closedAt,number
# Download individual diff files
gh pr diff "PR_NUMBER" --repo "REPO_NAME"
# Fallback for large diffs (300+ files) using REST API
gh api "repos/OWNER/REPO/pulls/PR_NUMBER/files" --paginate
# https://docs.github.com/en/rest/pulls/pulls?apiVersion=2022-11-28#list-pull-requests-files
```