{"id":44462145,"url":"https://github.com/montge/github-repo-public-indexer","last_synced_at":"2026-02-12T19:10:37.956Z","repository":{"id":319124308,"uuid":"1077679746","full_name":"montge/github-repo-public-indexer","owner":"montge","description":"Automated tool to index and document all repositories in a GitHub organization. Two-phase process: collect metadata via API, generate public-facing README with AI.","archived":false,"fork":false,"pushed_at":"2025-10-16T16:17:07.000Z","size":115,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-17T18:19:37.081Z","etag":null,"topics":["automation","ci-cd","documentation-generator","github-api","github-organization","metadata-collection","open-source","python","repository-documentation","repository-indexer"],"latest_commit_sha":null,"homepage":null,"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/montge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING_TEMPLATE.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-10-16T15:27:56.000Z","updated_at":"2025-10-16T16:17:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"e616847f-42a5-49af-a2b7-0797e2dc3fed","html_url":"https://github.com/montge/github-repo-public-indexer","commit_stats":null,"previous_names":["montge/github-repo-public-indexer"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/montge/github-repo-public-indexer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/montge%2Fgithub-repo-public-indexer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/montge%2Fgithub-repo-public-indexer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/montge%2Fgithub-repo-public-indexer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/montge%2Fgithub-repo-public-indexer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/montge","download_url":"https://codeload.github.com/montge/github-repo-public-indexer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/montge%2Fgithub-repo-public-indexer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29378125,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T19:05:20.189Z","status":"ssl_error","status_checked_at":"2026-02-12T19:01:44.216Z","response_time":55,"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":["automation","ci-cd","documentation-generator","github-api","github-organization","metadata-collection","open-source","python","repository-documentation","repository-indexer"],"created_at":"2026-02-12T19:10:37.745Z","updated_at":"2026-02-12T19:10:37.950Z","avatar_url":"https://github.com/montge.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Organization Repository Indexer\n\nA two-phase tool for creating comprehensive, public-facing documentation of all repositories within a GitHub organization.\n\n## Quick Start\n\n```bash\n# 1. Setup this indexer tool\n./setup.sh\n# Edit .env with your credentials\n\n# 2. Collect repository metadata\nsource venv/bin/activate\npython collect_repos.py --summary\n# Generates: repositories.json\n\n# 3. Prepare your public-facing repository\ncd ../my-org-public-repos  # Your target repo\ncp ../github-repo-public-indexer/repositories.json .\n\n# 4. Generate README with Cursor/Windsurf\n# - Open Cursor/Windsurf in the target repo directory\n# - Use PROMPT_TEMPLATE.md with repositories.json\n# - Review and commit the generated README.md\n```\n\n**Important:** The tool fetches metadata via GitHub API - no need to clone all your org's repositories.\n\nSee **[USAGE.md](USAGE.md)** and **[WORKFLOW.md](WORKFLOW.md)** for detailed instructions.\n\n## Overview\n\n### The Problem\nOrganizations with multiple GitHub repositories often lack centralized, up-to-date documentation showing:\n- What repositories exist and their purposes\n- Current status (active, archived, experimental)\n- Licensing information\n- Points of contact and ownership\n- Technology stacks and dependencies\n\n### The Solution\nA **two-phase automated approach**:\n\n**Phase 1: Data Collection**\n- Script fetches all repository metadata via GitHub API\n- Generates structured JSON file with comprehensive information\n- Handles pagination, rate limits, and errors gracefully\n\n**Phase 2: Documentation Generation**\n- JSON file is provided to Cursor/Windsurf AI assistant\n- AI analyzes data and generates human-readable README\n- Organized, categorized, and easy-to-navigate documentation\n\n### Why Two Phases?\n- **Separation of concerns**: Data collection vs. presentation\n- **Reusability**: JSON can be used for multiple outputs\n- **Flexibility**: Different documentation styles from same data\n- **Context management**: Avoid AI context limits\n- **Caching**: Avoid re-fetching data during iteration\n\n## Project Status\n\n**Current Version:** 0.1.0 (Pre-release)\n\n- [x] Requirements gathering\n- [x] Specification documentation\n- [x] JSON schema design\n- [x] Workflow documentation\n- [x] Prompt template creation\n- [x] **Phase 1 script implementation (Python)**\n- [x] **Testing infrastructure (pytest, CI/CD)**\n- [ ] Achieve 95% test coverage\n- [ ] Testing with sample organization\n- [ ] Phase 2 validation with Cursor/Windsurf\n- [ ] Refinement and optimization\n- [ ] Production deployment (v1.0.0)\n\n## Documentation\n\n### Quick References\n- **[USAGE.md](USAGE.md)** - Installation and usage guide\n- **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - One-page summary\n- **[TESTING.md](TESTING.md)** - Testing guide and best practices\n- **[CLAUDE.md](CLAUDE.md)** - Guide for Claude Code development\n\n### Design and Architecture\n- **[SPECIFICATION.md](SPECIFICATION.md)** - Full project scope and requirements\n- **[JSON_SCHEMA.md](JSON_SCHEMA.md)** - Output data structure\n- **[WORKFLOW.md](WORKFLOW.md)** - End-to-end process guide\n\n### Phase 2 Documentation Generation\n- **[PROMPT_TEMPLATE.md](PROMPT_TEMPLATE.md)** - Template for Cursor/Windsurf\n- **[CONTRIBUTING_TEMPLATE.md](CONTRIBUTING_TEMPLATE.md)** - Template CONTRIBUTING.md for index repositories\n\n## Implementation Details\n\n### Phase 1 (Implemented)\nPython-based data collection tool with:\n- **GitHub API Client** (`src/github_client.py`) - Authentication and rate limiting\n- **Metadata Collector** (`src/metadata_collector.py`) - Extracts comprehensive repo data\n- **JSON Generator** (`src/json_generator.py`) - Creates validated output\n- **CLI Interface** (`collect_repos.py`) - User-friendly command-line tool with progress bars\n\nKey features:\n- Automatic rate limit handling\n- Graceful error recovery\n- Rich console output with progress tracking\n- Configurable via CLI options or environment variables\n- JSON validation and backup\n- **GitHub Enterprise Server support** - Works with custom GitHub instances\n\n### Next Steps\n\n1. **Test with Your Organization**\n   ```bash\n   python collect_repos.py --org your-org-name --summary\n   ```\n\n2. **Generate Documentation**\n   - Use `PROMPT_TEMPLATE.md` with Cursor/Windsurf\n   - Attach the generated `repositories.json`\n   - Review and refine the output\n\n3. **Automate Updates**\n   - Schedule regular runs (weekly/monthly)\n   - Track changes over time\n   - Keep documentation current\n\n## Use Cases\n\n- **Open Source Projects**: Share your organization's repositories with the community\n- **Internal Teams**: Document internal tools and libraries\n- **Compliance**: Track licensing across all repositories\n- **Onboarding**: Help new team members discover existing projects\n- **Portfolio**: Showcase your organization's work\n- **Archival**: Document repository history and evolution\n\n## Technology Stack\n\n- **Python 3.8+** (tested on 3.8-3.12)\n- **PyGithub** - GitHub API client\n- **Click** - CLI framework\n- **Rich** - Beautiful terminal output\n- **python-dotenv** - Environment management\n- **pytest** - Testing framework with 95% coverage target\n\n## Contributing\n\nContributions welcome! Please:\n- Follow the architecture in SPECIFICATION.md\n- Ensure JSON output matches JSON_SCHEMA.md\n- Add tests for new features\n- Update documentation\n\n## Future Enhancements\n\n- Parallel processing for large organizations\n- API response caching\n- Diff tool to compare runs\n- GitHub Actions automation\n- Web dashboard interface\n- Multi-organization support\n\n## License\n\nApache License 2.0 - See [LICENSE](LICENSE) file for details.\n\n## Contact\n\nFor questions or suggestions, please open an issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmontge%2Fgithub-repo-public-indexer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmontge%2Fgithub-repo-public-indexer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmontge%2Fgithub-repo-public-indexer/lists"}