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

# 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

$apify call github-docs-issue-aggregator --input INPUT_EXAMPLE.json

Via API

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

{
  "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

{
  "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

{
  "languages": ["python"],
  "minStars": 100,
  "maxStars": 10000,
  "maxResults": 10,
  "issueTypes": ["documentation"]
}

Find Beginner-Friendly JavaScript Projects

{
  "languages": ["javascript"],
  "topics": ["beginner-friendly"],
  "minStars": 50,
  "maxStars": 5000,
  "maxResults": 10,
  "issueTypes": ["good-first-issue", "documentation"]
}

🔌 Integration

JavaScript/Node.js

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

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

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

# Install dependencies
npm install

# Set environment variables
export GITHUB_TOKEN=your_token_here

# Run locally
npm start

Deploy Updates

# 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! 🎉