{"id":31848376,"url":"https://github.com/brenofariasdasilva/github-activity-reports-generator","last_synced_at":"2026-04-09T21:52:47.788Z","repository":{"id":316429451,"uuid":"1063319402","full_name":"BrenoFariasdaSilva/GitHub-Activity-Reports-Generator","owner":"BrenoFariasdaSilva","description":"Generates detailed reports of GitHub activity (issues, sub-issues, PRs, and commits) from multiple repositories within a date range. Saves raw JSON responses and produces per-author Quarto reports in QMD, PDF, and DOCX formats.","archived":false,"fork":false,"pushed_at":"2025-10-06T21:32:32.000Z","size":273,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-06T23:26:49.476Z","etag":null,"topics":["activity-tracker","automation","commits","contributions","data-collection","docx","github","issues","latex","pdf","pull-requests","qmd","quarto","report-generator","reports","scraper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BrenoFariasdaSilva.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-09-24T13:14:31.000Z","updated_at":"2025-10-06T21:32:36.000Z","dependencies_parsed_at":"2025-09-24T15:36:01.450Z","dependency_job_id":null,"html_url":"https://github.com/BrenoFariasdaSilva/GitHub-Activity-Reports-Generator","commit_stats":null,"previous_names":["brenofariasdasilva/github-activity-reports-generator"],"tags_count":0,"template":false,"template_full_name":"BrenoFariasdaSilva/Template-Project","purl":"pkg:github/BrenoFariasdaSilva/GitHub-Activity-Reports-Generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrenoFariasdaSilva%2FGitHub-Activity-Reports-Generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrenoFariasdaSilva%2FGitHub-Activity-Reports-Generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrenoFariasdaSilva%2FGitHub-Activity-Reports-Generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrenoFariasdaSilva%2FGitHub-Activity-Reports-Generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BrenoFariasdaSilva","download_url":"https://codeload.github.com/BrenoFariasdaSilva/GitHub-Activity-Reports-Generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrenoFariasdaSilva%2FGitHub-Activity-Reports-Generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279011063,"owners_count":26084864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["activity-tracker","automation","commits","contributions","data-collection","docx","github","issues","latex","pdf","pull-requests","qmd","quarto","report-generator","reports","scraper"],"created_at":"2025-10-12T10:24:41.958Z","updated_at":"2026-04-09T21:52:47.774Z","avatar_url":"https://github.com/BrenoFariasdaSilva.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \n# [GitHub-Activity-Reports-Generator.](https://github.com/BrenoFariasdaSilva/GitHub-Activity-Reports-Generator) \u003cimg src=\"https://github.com/BrenoFariasdaSilva.png\"  width=\"3%\" height=\"3%\"\u003e\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \n---\n\nThis project is a **GitHub Activity Reports Generator** that collects and organizes information about issues, sub-issues, pull requests (PRs), and commits from specified repositories within a defined date range.  \nIt saves raw JSON responses to `./responses/` and generates **Quarto Markdown reports** grouped by author, with outputs in PDF, DOCX, and QMD formats stored in `./reports/`.\n  \n---\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n![GitHub Code Size in Bytes](https://img.shields.io/github/languages/code-size/BrenoFariasdaSilva/GitHub-Activity-Reports-Generator)\n![GitHub Commits](https://img.shields.io/github/commit-activity/t/BrenoFariasDaSilva/GitHub-Activity-Reports-Generator/main)\n![GitHub Last Commit](https://img.shields.io/github/last-commit/BrenoFariasdaSilva/GitHub-Activity-Reports-Generator)\n![GitHub Forks](https://img.shields.io/github/forks/BrenoFariasDaSilva/GitHub-Activity-Reports-Generator)\n![GitHub Language Count](https://img.shields.io/github/languages/count/BrenoFariasDaSilva/GitHub-Activity-Reports-Generator)\n![GitHub License](https://img.shields.io/github/license/BrenoFariasdaSilva/GitHub-Activity-Reports-Generator)\n![GitHub Stars](https://img.shields.io/github/stars/BrenoFariasdaSilva/GitHub-Activity-Reports-Generator)\n![wakatime](https://wakatime.com/badge/github/BrenoFariasdaSilva/GitHub-Activity-Reports-Generator.svg)\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \n![RepoBeats Statistics](https://repobeats.axiom.co/api/embed/85ae4e5b591ce5aebee352186f43f84ec68519b8.svg \"Repobeats analytics image\")\n\n\u003c/div\u003e\n\n## Table of Contents\n- [GitHub-Activity-Reports-Generator. ](#github-activity-reports-generator-)\n  - [Table of Contents](#table-of-contents)\n  - [Introduction](#introduction)\n  - [Features](#features)\n  - [TODO / Roadmap](#todo--roadmap)\n  - [Requirements](#requirements)\n  - [Setup](#setup)\n    - [1. Install Python](#1-install-python)\n      - [Linux](#linux)\n      - [macOS](#macos)\n      - [Windows](#windows)\n    - [2. Install `make` utility](#2-install-make-utility)\n      - [Linux](#linux-1)\n      - [macOS](#macos-1)\n      - [Windows](#windows-1)\n    - [3. Clone the repository](#3-clone-the-repository)\n    - [4. Virtual environment (strongly recommended)](#4-virtual-environment-strongly-recommended)\n    - [5. Install dependencies](#5-install-dependencies)\n    - [6. Environment Variables Configuration](#6-environment-variables-configuration)\n      - [Full list of environment variables](#full-list-of-environment-variables)\n    - [main.py configuration](#mainpy-configuration)\n  - [Usage](#usage)\n  - [Results](#results)\n    - [Example structure](#example-structure)\n    - [Convert QMD to other formats](#convert-qmd-to-other-formats)\n  - [Contributing](#contributing)\n  - [Collaborators](#collaborators)\n  - [License](#license)\n    - [Apache License 2.0](#apache-license-20)\n\n## Introduction\n\nThe **GitHub Activity Reports Generator** is a Python-based tool designed to streamline the process of collecting and analyzing contributions across multiple GitHub repositories. It connects to the GitHub API, retrieves issues, sub-issues, pull requests, and commits within a specified date range, and organizes the data per author. The tool saves raw JSON responses for traceability and produces structured, per-author reports in Quarto Markdown (`.qmd`) format, which can be rendered into PDF, DOCX, or other formats. This enables teams, project managers, and educators to gain clear insights into individual and team contributions, track progress over time, and maintain accurate records of repository activity.\n\n## Features\n\n- Collects **issues** (created and updated) within a given date range.  \n- Fetches **sub-issues** (via GitHub API).  \n- Extracts **PRs strictly linked to issues** (via timeline).  \n- Gathers **commits** from PRs and direct commit searches.  \n- Maps GitHub usernames to **real author names**.  \n- Saves **raw JSON responses**.  \n- Generates **Quarto Markdown reports per author** (qmd, that can be converted to PDF, DOCX, etc.).  \n- Supports **multiple repositories**, automatically sorted alphabetically.  \n- Deduplicates commits by SHA.  \n- Includes sound notification when finished.  \n\n## TODO / Roadmap\n\nThe following improvements and enhancements are planned for this project. These items are also documented in the `main.py` header description:\n\n- **Organize responses directory** → Create subdirectories per repository and separate folders for each issue, storing all related content inside.  \n- **Incremental data fetching** → Avoid re-fetching all data every time; only retrieve new or updated items.  \n- **GraphQL support** → Implement GraphQL queries for `/Projects` content to improve efficiency and flexibility.  \n\n## Requirements\n\n- Python **3.9 or higher**  \n- A valid GitHub **Personal Access Token (Classic)** with at least `repo` and `read:org` scopes  \n- `make` utility installed on your system  \n- Internet connection (to fetch data from GitHub API)  \n- [Quarto CLI](https://quarto.org/) installed system-wide (required for report rendering)  \n- [Quarto PDF dependencies](https://quarto.org/docs/output-formats/pdf/) installed (for PDF output)\n\nDependencies in the `requirements.txt` include:\n- `certifi` → Provides trusted CA certificates for secure HTTPS requests.  \n- `charset-normalizer` → Handles encoding/decoding of response text when fetching from the GitHub API.  \n- `colorama` → Enables colored terminal output for status and progress messages.  \n- `DateTime` → Simplifies working with dates and times (used alongside `pytz`).  \n- `idna` → Ensures proper handling of internationalized domain names in URLs.  \n- `python-dotenv` → Loads environment variables from a `.env` file (e.g., GitHub token).  \n- `pytz` → Provides time zone support for date/time handling and conversions.  \n- `requests` → Core HTTP library used to interact with the GitHub API.  \n- `setuptools` → Build system utility required for packaging and environment setup.  \n- `urllib3` → Low-level HTTP library that powers `requests`, handling connections and retries.  \n- `zope.interface` → Dependency of `DateTime`, provides interface definitions and enforcement.  \n\n## Setup\n\nBefore running the project, ensure that both **Python** and the **make utility** are installed on your system. Follow the instructions below according to your operating system.\n\n### 1. Install Python\n\nThe project requires **Python 3.9 or higher**.\n\n#### Linux\nOn Debian/Ubuntu-based distributions:\n\n```bash\nsudo apt update\nsudo apt install python3 python3-venv python3-pip -y\n```\n\nOn Fedora/RHEL-based distributions:\n\n```bash\nsudo dnf install python3 python3-venv python3-pip -y\n```\n\nVerify installation:\n\n```bash\npython3 --version\n```\n\n#### macOS\n1. Install via Homebrew (recommended):\n\n```bash\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\" # if Homebrew not installed\nbrew install python\n```\n\n2. Verify installation:\n\n```bash\npython3 --version\n```\n\n#### Windows\n1. Download Python from the official website: [https://www.python.org/downloads/windows/](https://www.python.org/downloads/windows/)\n2. Run the installer and check **“Add Python to PATH”**.\n3. Verify installation:\n\n```powershell\npython --version\n```\n\n---\n\n### 2. Install `make` utility\n\nThe `make` utility is used to automate tasks such as setting up the virtual environment and installing dependencies.\n\n#### Linux\n`make` is usually pre-installed. If not:\n\n```bash\nsudo apt install build-essential -y  # Debian/Ubuntu\nsudo dnf install make -y            # Fedora/RHEL\nmake --version\n```\n\n#### macOS\n`make` comes pre-installed with Xcode Command Line Tools:\n\n```bash\nxcode-select --install\nmake --version\n```\n\n#### Windows\n1. Install via [Chocolatey](https://chocolatey.org/):\n\n```powershell\nchoco install make\n```\n\nOr, install [GnuWin32 Make](http://gnuwin32.sourceforge.net/packages/make.htm).\n\n2. Verify installation:\n\n```powershell\nmake --version\n```\n\n---\n\n### 3. Clone the repository\n\n```bash\ngit clone https://github.com/BrenoFariasDaSilva/GitHub-Activity-Reports-Generator.git\ncd GitHub-Activity-Reports-Generator\n```\n\n### 4. Virtual environment (strongly recommended)\n\nWith `make`:\n\n```bash\nmake venv\nsource venv/bin/activate # Linux/macOS\nvenv\\Scripts\\activate # Windows\n```\n\nOr manually:\n\n```bash\npython -m venv venv\nsource venv/bin/activate # Linux/macOS\nvenv\\Scripts\\activate # Windows\n```\n\n### 5. Install dependencies\n\n1. Install **Quarto CLI** (required for report rendering): [Quarto Installation Guide](https://quarto.org/docs/get-started/)  \n\n```bash\nquarto --version  # verify installation\n```\n\n2. Install **TinyTeX** for PDF output:\n\n```bash\nquarto install tinytex\n```\n\n3. Install Python packages:\n\nWith `make`:\n\n```bash\nmake dependencies\n```\n\nOr manually:\n\n```bash\npip install -r requirements.txt\n```\n\n---\n\n### 6. Environment Variables Configuration\n\nCopy the `.env-example` file and rename it `.env`. Edit it with your GitHub credentials and repositories. For full details, see the [Environment Variables Configuration](#environment-variables-configuration) section above.\n\n#### Full list of environment variables\n\nThe `.env` file supports the following variables:\n\n```env\n# GitHub authentication token (classic, required)\nGITHUB_CLASSIC_TOKEN=your_classic_github_token_here\n```\n\nOnly **classic tokens** are supported (with `repo` and `read:org` scopes). You can generate a new classic token in your GitHub account settings under Developer Settings \u003e Personal Access Tokens \u003e Tokens (classic), or by the following link: [Generate new token (classic)](https://github.com/settings/tokens)\n\nAlso, you need to configure the owner and repositories to fetch the data from:\n\n```env\n# Owner of the repositories (GitHub organization or username, required)\nGitHub URL Template to fill the variables: https://github.com/{owner}/{repo}\nOWNER=OWNER_NAME_HERE\n\n# Dictionary with project names and their repositories (JSON string, required)\n# Example: {\"ProjectA\": [\"repo1\", \"repo2\"], \"ProjectB\": [\"repo3\"]}\nREPOS='{\"ANY_NAME_FOR_REPOS_LIST\": [\"REPO_NAME_1\", \"REPO_NAME_2\"]}'\n```\n\nLastly, there is the user mapping configuration, to map GitHub usernames to real names:\n\n```env\n# If true, only generate reports for users listed in USER_MAP\n# If false, generate reports for all contributors\nUSER_MAP_ONLY=true\n\n# Dictionary with canonical names and their possible variations (JSON string, optional but recommended)\n# Example: {\"John Doe\": [\"jdoe\", \"john_d\", \"John_Doe\"]}\nUSER_MAP='{\n  \"YOUR NAME\": [\"Your_GitHub_Username\", \"Your full name with underscores\"]\n}'\n```\n\n---\n\n### main.py configuration\n\nInside the `main.py` file, you can adjust the following constants if needed:\n\n```python\nSAVE_JSONS = False # Set to True to save raw JSON responses in ./responses/\nVERBOSE = False # Set to True to print detailed messages during execution\n```\n\n## Usage\n\nRun the `main.py` file with `make`:\n\n```bash\nmake run SINCE=2024-01-01 UNTIL=2024-12-31\n```\n\nIf no dates are provided (by simply running `make`), it defaults to fetching all data from `2000-01-01` to the current date. This is adjustable in the `Makefile`, at the `SINCE` and `UNTIL` variables.\n\nOr manually:\n\n```bash\nsource venv/bin/activate # On Linux/macOS\nvenv\\Scripts\\activate # On Windows\npython3 main.py --since 2024-01-01 --until 2024-12-31\n```\n\n## Results\n\nAfter running the project, you will obtain:  \n\n- **Raw data** → JSON files with issues, PRs, and commits from the configured repositories, stored in the `responses/` folder.  \n- **Per-author reports** → Contributions grouped by author (based on `USER_MAP`) within the selected date range. Reports are generated as Quarto `.qmd` files and automatically rendered into **PDF** and **DOCX** formats inside the `reports/` directory.  \n- **Traceability** → Clear tracking of how many issues, PRs, and commits were authored by each contributor.  \n- **Navigation** → Hyperlinked references to GitHub issues, PRs, and commits for quick access back to the platform.  \n\n### Example structure\n\n```\nresponses/\n├── issue_123.json\n├── pr_456_commits.json\n└── repo_commits_page_1.json\n\nreports/YYYY-MM-DD_YYYY-MM-DD/Author_Name/\n├── Author_Name_YYYY-MM-DD_YYYY-MM-DD.qmd\n├── Author_Name_YYYY-MM-DD_YYYY-MM-DD.pdf\n└── Author_Name_YYYY-MM-DD_YYYY-MM-DD.docx\n```\n\n### Convert QMD to other formats\n\nIf you need to modify the `.qmd` report file, then you need to manually convert it to other formats, so the changes are reflected.\n\nTo convert to PDF:\n\n```bash\nquarto render reports/YYYY-MM-DD_YYYY-MM-DD/Author_Name/activity_Author_Name.qmd --to pdf\n```\n\nTo convert to DOCX:\n\n```bash\nquarto render reports/YYYY-MM-DD_YYYY-MM-DD/Author_Name/activity_Author_Name.qmd --to docx\n```\n\nThis will create `reports/YYYY-MM-DD_YYYY-MM-DD/activity_Author_Name.pdf` and `reports/YYYY-MM-DD_YYYY-MM-DD/activity_Author_Name.docx` in the same directory. The other available formats include `html` and `latex`.\n\nRead the guide on the official Quarto website for more details: [Quarto Output Formats](https://quarto.org/docs/output-formats/all-formats.html).\n\n## Contributing\n\nContributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. If you have suggestions for improving the code, your insights will be highly welcome.\nIn order to contribute to this project, please follow the guidelines below or read the [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on how to contribute to this project, as it contains information about the commit standards and the entire pull request process.\nPlease follow these guidelines to make your contributions smooth and effective:\n\n1. **Set Up Your Environment**: Ensure you've followed the setup instructions in the [Setup](#setup) section to prepare your development environment.\n\n2. **Make Your Changes**:\n   - **Create a Branch**: `git checkout -b feature/YourFeatureName`\n   - **Implement Your Changes**: Make sure to test your changes thoroughly.\n   - **Commit Your Changes**: Use clear commit messages, for example:\n     - For new features: `git commit -m \"FEAT: Add some AmazingFeature\"`\n     - For bug fixes: `git commit -m \"FIX: Resolve Issue #123\"`\n     - For documentation: `git commit -m \"DOCS: Update README with new instructions\"`\n     - For refactorings: `git commit -m \"REFACTOR: Enhance component for better aspect\"`\n     - For snapshots: `git commit -m \"SNAPSHOT: Temporary commit to save the current state for later reference\"`\n   - See more about crafting commit messages in the [CONTRIBUTING.md](CONTRIBUTING.md) file.\n\n3. **Submit Your Contribution**:\n   - **Push Your Changes**: `git push origin feature/YourFeatureName`\n   - **Open a Pull Request (PR)**: Navigate to the repository on GitHub and open a PR with a detailed description of your changes.\n\n4. **Stay Engaged**: Respond to any feedback from the project maintainers and make necessary adjustments to your PR.\n\n5. **Celebrate**: Once your PR is merged, celebrate your contribution to the project!\n\n## Collaborators\n\nWe thank the following people who contributed to this project:\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"#\" title=\"defina o titulo do link\"\u003e\n        \u003cimg src=\"https://github.com/BrenoFariasdaSilva.png\" width=\"100px;\" alt=\"My Profile Picture\"/\u003e\u003cbr\u003e\n        \u003csub\u003e\n          \u003cb\u003eBreno Farias da Silva\u003c/b\u003e\n        \u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## License\n\n### Apache License 2.0\n\nThis project is licensed under the [Apache License 2.0](LICENSE). This license permits use, modification, distribution, and sublicense of the code for both private and commercial purposes, provided that the original copyright notice and a disclaimer of warranty are included in all copies or substantial portions of the software. It also requires a clear attribution back to the original author(s) of the repository. For more details, see the [LICENSE](LICENSE) file in this repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrenofariasdasilva%2Fgithub-activity-reports-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrenofariasdasilva%2Fgithub-activity-reports-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrenofariasdasilva%2Fgithub-activity-reports-generator/lists"}