GitHub Open-Source Beginner Issue Finder An Apify Actor that discovers open-source GitHub repositories with beginner issues, making it easy for new contributors to find beginner-friendly contribution opportunities. ## 🎯 Problem Statement Many developers want to contribute to open-source but struggle to find projects with documentation work that's beginner-friendly. Simultaneously, maintainers have stale README files, missing API docs, and outdated tutorials. This Actor bridges that gap by aggregating documentation-focused issues across GitHub. ## ✨ Key Features ### 1. Smart GitHub Repository Search - Search by programming language (JavaScript, Python, TypeScript, Go, Rust, etc.) - Filter by topics (open-source, beginner-friendly, documentation, etc.) - Set minimum/maximum star threshold (find active, maintained projects) - Filter by activity level (last updated within X days) ### 2. Issue Detection & Categorization Extract and categorize issues by type: - Documentation Issues (labeled documentation, docs) - Good First Issues (labeled good-first-issue) - README Issues (stale/outdated README, missing migration guides) - Help Wanted (labeled help-wanted, easy-fix) - Beginner-Friendly (low complexity, high learning value) ### 3. Repository Intelligence Extraction For each repo, collect: - Repository name, URL, description - Star count & contributor count - Primary language & topics - Last commit date (maintenance indicator) - Open issues count - Issue details: title, URL, creation date, labels - Contributor difficulty (estimate from issue comments) - Maintenance health score (0-10) - Community welcomingness assessment ### 4. Output & Filtering - Ranked results by contributor activity, star count, issue recency - Grouped by language for easy browsing - JSON schema output with: - Repository metadata - Categorized issues with direct links - Contributor statistics - Maintenance health score - Statistics including language distribution, issue type distribution ### 5. AI-Powered Insights (Optional) - Suggest best repos for different skill levels - Estimate contribution effort for each issue - Highlight projects with "welcoming" communities ## 📋 Prerequisites - Apify Account: Sign up at https://apify.com (free tier available) - Apify CLI: Install with npm install -g apify-cli - GitHub Personal Access Token (optional, but recommended for higher rate limits) - Get one at: https://github.com/settings/tokens - Required scopes: public_repo (read-only access) ## 🚀 Quick Start ### 1. Deploy to Apify Platform bash # Login to Apify apify login # Deploy the Actor apify push ### 2. Configure Environment Variables In the Apify Console: 1. Go to your Actor → Settings → Environment Variables 2. Add GITHUB_TOKEN with your GitHub personal access token 3. Mark it as Secret ✅ 4. Optionally add OPENAI_API_KEY if using AI features ### 3. Run the Actor #### Via Apify Console 1. Go to your Actor page 2. Click Start button 3. Configure input parameters 4. Click Run #### Via Apify CLI bash apify call github-docs-issue-aggregator --input INPUT_EXAMPLE.json #### Via API bash curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~github-docs-issue-aggregator/runs" \ -H "Authorization: Bearer YOUR_APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d @INPUT_EXAMPLE.json ## 📥 Input Schema The Actor accepts the following input parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | languages | array | Yes | ["javascript", "python", "typescript"] | Programming languages to search for | | topics | array | No | ["open-source", "beginner-friendly"] | GitHub topics to filter by | | minStars | number | No | 100 | Minimum number of stars | | maxStars | number | No | 50000 | Maximum number of stars | | issueTypes | array | No | ["documentation", "good-first-issue", "readme"] | Types of issues to find | | daysActive | number | No | 30 | Repositories updated within last N days | | maxResults | number | No | 10 | Maximum number of repositories to return | | sortBy | string | No | "stars" | Sort by: "stars", "issues", or "recency" | | includeAiInsights | boolean | No | false | Include AI-powered insights in output | | githubToken | string | No | - | GitHub personal access token (recommended for higher rate limits) | ### Example Input json { "languages": ["python", "javascript"], "topics": ["beginner-friendly", "open-source"], "minStars": 100, "maxStars": 10000, "issueTypes": ["documentation", "good-first-issue"], "daysActive": 30, "maxResults": 10, "sortBy": "stars", "includeAiInsights": false } ## 📤 Output Schema The Actor returns a structured JSON object. See output-schema.json for the complete JSON schema definition. ### Output Structure json { "timestamp": "2024-12-06T15:00:00.000Z", "queryParams": { "languages": ["python"], "topics": ["open-source"], "minStars": 100, "maxStars": 10000 }, "repositoriesFound": 5, "repositories": [ { "fullName": "owner/repo", "name": "repo", "url": "https://github.com/owner/repo", "description": "Repository description", "stars": 1234, "forks": 56, "contributors": 12, "openIssues": 45, "language": "Python", "topics": ["open-source", "beginner-friendly"], "lastUpdated": "2024-11-15T10:00:00Z", "maintenanceScore": 8.5, "communityWelcomingness": "welcoming", "issues": [ { "number": 123, "title": "Update README.md", "url": "https://github.com/owner/repo/issues/123", "type": "documentation", "createdAt": "2024-11-01T00:00:00Z", "comments": 5, "estimatedEffort": "easy" } ] } ], "statistics": { "totalIssuesFound": 277, "avgStarsPerRepo": 7929, "languageDistribution": { "Python": 5 }, "issueTypeDistribution": { "documentation": 254, "good-first-issue": 14, "help-wanted": 9 }, "avgRepoAge": "70.2 months" } } ## 🔧 Configuration ### Environment Variables Set these in Apify Console → Actor Settings → Environment Variables: - GITHUB_TOKEN (Recommended) - Your GitHub personal access token - Mark as Secret ✅ - Increases rate limit from 60 to 5,000 requests/hour - OPENAI_API_KEY (Optional) - Your OpenAI API key - Mark as Secret ✅ - Enables AI-powered search optimization ## 📊 Usage Examples ### Find Python Repositories with Documentation Issues json { "languages": ["python"], "minStars": 100, "maxStars": 10000, "maxResults": 10, "issueTypes": ["documentation"] } ### Find Beginner-Friendly JavaScript Projects json { "languages": ["javascript"], "topics": ["beginner-friendly"], "minStars": 50, "maxStars": 5000, "maxResults": 10, "issueTypes": ["good-first-issue", "documentation"] } ## 🔌 Integration ### JavaScript/Node.js javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN', }); const run = await client.actor('YOUR_USERNAME/github-docs-issue-aggregator').call({ languages: ['python', 'javascript'], minStars: 100, maxStars: 10000, maxResults: 10, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ### Python python from apify_client import ApifyClient client = ApifyClient('YOUR_APIFY_TOKEN') run = client.actor('YOUR_USERNAME/github-docs-issue-aggregator').call( run_input={ 'languages': ['python', 'javascript'], 'minStars': 100, 'maxStars': 10000, 'maxResults': 10, } ) dataset_items = client.dataset(run['defaultDatasetId']).list_items() for item in dataset_items.items: print(item) ### cURL bash curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~github-docs-issue-aggregator/runs" \ -H "Authorization: Bearer YOUR_APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "languages": ["python"], "minStars": 100, "maxStars": 10000, "maxResults": 10 }' ## 📈 Rate Limits - Without GitHub Token: 60 requests/hour (unauthenticated) - With GitHub Token: 5,000 requests/hour (authenticated) The Actor automatically handles rate limits and will wait if needed. ## 🛠️ Development ### Local Testing bash # Install dependencies npm install # Set environment variables export GITHUB_TOKEN=your_token_here # Run locally npm start ### Deploy Updates bash # Push to Apify apify push ## 📄 License MIT License - feel free to use and modify for your needs. ## 🙏 Acknowledgments Built for the Apify platform. Special thanks to: - GitHub for the excellent API - Apify for the platform - The open-source community for inspiration --- Happy Contributing! 🎉