{"id":31581175,"url":"https://github.com/devzom/github-monthly-report","last_synced_at":"2026-03-02T11:01:10.139Z","repository":{"id":317507024,"uuid":"1046166536","full_name":"devzom/github-monthly-report","owner":"devzom","description":"Semi-automated bash tool for generating monthly tax deductible reports based on GitHub merged pull requests as TXT or PDF files with summary","archived":false,"fork":false,"pushed_at":"2025-11-06T09:41:55.000Z","size":39,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-06T11:24:26.241Z","etag":null,"topics":["bash","bash-script","deductible","pull-request","reports"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devzom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-28T09:37:17.000Z","updated_at":"2025-11-06T09:49:29.000Z","dependencies_parsed_at":"2025-10-01T11:38:16.789Z","dependency_job_id":null,"html_url":"https://github.com/devzom/github-monthly-report","commit_stats":null,"previous_names":["devzom/github-monthly-report"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/devzom/github-monthly-report","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devzom%2Fgithub-monthly-report","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devzom%2Fgithub-monthly-report/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devzom%2Fgithub-monthly-report/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devzom%2Fgithub-monthly-report/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devzom","download_url":"https://codeload.github.com/devzom/github-monthly-report/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devzom%2Fgithub-monthly-report/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29999216,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T09:59:02.300Z","status":"ssl_error","status_checked_at":"2026-03-02T09:59:02.001Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","bash-script","deductible","pull-request","reports"],"created_at":"2025-10-05T21:54:22.511Z","updated_at":"2026-03-02T11:01:10.126Z","avatar_url":"https://github.com/devzom.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Monthly work report generator based on GitHub PR diffs\n\nComprehensive tool for generating monthly tax deductible reports based on GitHub pull requests.\nAutomatically downloads diff files and creates organized summaries for tax reporting purposes.\nBy default it produces `.txt` files, but can be configured to generate `.pdf` files as well.\n\nSupports flexible organization targeting - either specify the organization as a parameter or set a default in the script.\n\n## Setups\n\n- Bash shell (macOS/Linux) or Git Bash/WSL (Windows)\n- _GitHub CLI_ `gh` installed and authenticated\n- `jq` command-line JSON processor\n\n### Installing GitHub CLI and jq\n\n\n```bash\n# macOS (Homebrew)\nbrew install gh jq\n\n# Ubuntu/Debian\nsudo apt update \u0026\u0026 apt install gh \u0026\u0026 apt install jq\n```\n\n**Windows:**\n```powershell\n# Using winget (Windows 10 1709+)\nwinget install --id GitHub.cli \u0026\u0026 winget install stedolan.jq\n# Using Chocolatey\nchoco install gh \u0026\u0026 choco install jq\n```\n\n**Other platforms:** Visit https://cli.github.com/ for installation instructions\n\n### Authentication\n\n#### Initial GitHub CLI auth:\n\n```bash\n# Authenticate with GitHub\ngh auth login\n```\n\n##### Follow prompts to\n1. Choose GitHub.com\n2. Select HTTPS or SSH protocol\n3. Authenticate via web browser or personal access token\n4. Choose your preferred git protocol\n\n#### Required permissions:\n- Read access to repositories in the target organization\n- Ability to view pull requests and their diffs\n\n### Script setup\n\u003cdetails\u003e\n\u003csummary\u003eMore details\u003c/summary\u003e\n\n#### Make script executable (macOS/Linux):\n```bash\nchmod +x generate-report.sh\n```\n\n#### Windows setup:\nFor Windows users, you have several options:\n\n1. **Git Bash** (Recommended):\n    - Install Git for Windows (includes Git Bash)\n    - Open Git Bash terminal\n    - Navigate to script directory and run as shown in usage examples\n\n2. **Windows WSL**:\n    - Install WSL2 with Ubuntu\n    - Install dependencies within WSL environment\n    - Run script from WSL terminal\n\n3. **PowerShell with Git Bash**:\n   ```powershell\n   # Run from PowerShell\n   bash ./generate-report.sh\n   ```\n\n\u003c/details\u003e\n\n## Organization configuration\n\nYou have two options for specifying the target GitHub organization:\n\n### Option 1: Pass as parameter (recommended)\nSimply provide the organization name as the first parameter when running the script:\n\n```bash\n./generate-report.sh my-org-name\n```\n\n### Option 2: Edit default in script file\nAlternatively, you can set a default organization by editing the script:\n\n```bash\n# Modify this line in generate-report.sh:\nrepositoryOwner=\"your-org-name\"\n```\n\n\u003e [!TIP]\n\u003e Using the parameter approach (Option 1) is more flexible as it allows you to work with different organizations without modifying the script.\n\n#### PDF Generation workflow (optional)\n\nTo generate diff files as PDF documents, you need to install the following dependencies via Homebrew:\n\n```bash\nbrew install enscript ghostscript\n```\n\n## Usage\n\n### Configuration\n\nThe script need to configure organization / repo owner.\nTo use with a different organization, modify the `repositoryOwner` variable at the top of the script.\n\n### With organization parameter (recommended)\n\n#### macOS/Linux/Windows (Git Bash):\n```bash\n# Generate report for current month (uses default org from script)\n./generate-report.sh\n# Generate report for current month with specific organization\n./generate-report.sh my-org-name\n# Generate report for specific month with organization\n./generate-report.sh my-org-name 2025-07\n# Generate report for custom date range with organization\n./generate-report.sh my-org-name 2025-07-01 2025-07-31\n```\n\n### Output\n\n1. **Console log**: Detailed PR information with repository, title, PR number, close date, diff URL, and PR URL\n2. **Summary by repository**: Count of PRs per repository\n3. **Diff file downloads**: Individual diff files saved locally in organized directory structure\n4. **Summary file**: Master list linking PR titles to their corresponding diff files\n\n### Example output\n\n\u003cdetails\u003e\n\n\u003csummary\u003eMore details\u003c/summary\u003e\n\n```\n    Generating report for period: 2025-07-01 to 2025-07-31\n    ======================================================\n    Fetching merged pull requests...\n    Found 8 merged pull requests\n\n    PR DIFFS FOR TAX DEDUCTIBLE REPORT\n    ==================================\n\n    Repository: your-org-name/repositoryExample\n    Title: prefix-168: Fix export and release o pkg\n    PR number: #218\n    Closed at: 2025-04-29T11:25:40Z\n    Diff URL: https://github.com/your-org-name/repositoryExample/pull/218.diff\n    PR URL: https://github.com/your-org-name/repositoryExample/pull/218\n    ------------------------------------------------------------\n\n    SUMMARY BY REPOSITORY\n    ====================\n    6 PRs: your-org-name/repositoryExample\n    1 PRs: your-org-name/repositoryExample2\n    1 PRs: your-org-name/repositoryExample3\n\n    DIFF URLS\n    ================================\n    https://github.com/your-org-name/repositoryExample/pull/218.diff\n    ...\n\n    GENERATING DIFFs\n    ===============================================\n    ✓✓✓ Generated: diffs/2025-07-01_2025-07-31/repositoryExample-217.......txt\n    ...\n\n    ✓✓✓ Generated summary: diffs/2025-07-01_2025-07-31/summary.txt\n```\n\n\u003c/details\u003e\n\n## Features\n\n- **Organization targeting**: Pass organization name as parameter or use default from script\n- **Smart date from/to handling**: Automatically detects month boundaries and handles edge cases\n- **Local diffs storage**: Downloads actual diff files and stores them in organized directory structure\n- **File organization**: Creates time-stamped directories (`YYYY-MM-DD_YYYY-MM-DD`) for easy archiving\n- **Summary generation**: Creates master summary file linking PR titles to their diff files\n- **Multiple outputs**: Console report, individual diff files, and summary file\n- **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\n- **Error handling**: Gracefully handles missing PRs, network issues, and invalid dates\n- **Filename sanitization**: Cleans PR titles for safe filesystem usage\n\n## Structure\n\nThe script creates the following directory structure:\n\n```\ndiffs/\n└── YYYY-MM-DD_YYYY-MM-DD/\n    ├── summary.txt\n    ├── repo-name-123-PR_Title_Sanitized.txt\n    ├── repo-name-124-Another_PR_Title.txt\n    └── ...\n```\n\n- **summary.txt**: Master file with format `[PR Title]-[filename]` for each diff\n- **Individual diffs files**: Named as `{repo-short-name}-{pr-number}-{sanitized-title}.txt`\n\n## GitHub CLI commands used\n\nThe script uses these GitHub CLI commands internally:\n```bash\n# Search for merged PRs\ngh search prs --author=@me --owner=\"your-org-name\" --merged --created=\"YYYY-MM-DD..YYYY-MM-DD\" --json title,repository,url,closedAt,number\n\n# Download individual diff files\ngh pr diff \"PR_NUMBER\" --repo \"REPO_NAME\"\n\n# Fallback for large diffs (300+ files) using REST API\ngh api \"repos/OWNER/REPO/pulls/PR_NUMBER/files\" --paginate\n# https://docs.github.com/en/rest/pulls/pulls?apiVersion=2022-11-28#list-pull-requests-files\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevzom%2Fgithub-monthly-report","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevzom%2Fgithub-monthly-report","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevzom%2Fgithub-monthly-report/lists"}