OSS Contribution Finder

Find open-source contribution opportunities via the GitHub API.

Searches for issues labeled "good first issue" (or any label you choose), filtered by language, topic, star count, and activity. Outputs a ranked list ready for contribution.

Contributor Friendliness

The tool detects signals of contributor-friendly repositories (CONTRIBUTING.md, PR/issue templates, CODE_OF_CONDUCT.md) and assigns a friendliness score (0-100). Use --sort friendliness to rank by this score. The score is shown in table and markdown output, and the breakdown is included in JSON.

Install & Quick Start

# Install from git (not yet on PyPI)
pip install git+https://github.com/yunaremaia/oss-contribution-finder.git

# Find Python good-first-issues
oss-contribution-finder --language python --limit 10

Usage

# Find Python good-first-issues
oss-contribution-finder --language python --limit 10

# Find Rust CLI projects with 100+ stars
oss-contribution-finder --language rust --topic cli --min-stars 100

# Export as markdown
oss-contribution-finder --language go --format markdown >> opportunities.md

# JSON output for automation
oss-contribution-finder --language typescript --format json --limit 50

# Only show issues from repositories with a root CONTRIBUTING.md
oss-contribution-finder --language python --require-contributing

# Check rate limit status
oss-contribution-finder --check-rate-limit

Options

Caching

API responses are cached in memory with a default TTL of 1 hour (3600 seconds) to avoid redundant requests during repeated operations. Use --no-cache to bypass cached responses and fetch fresh data directly from GitHub.

Authentication and Proxy

Set GH_TOKEN or GITHUB_TOKEN in your environment to avoid rate limits:

export GH_TOKEN=ghp_your_token_here

Standard proxy environment variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY) are automatically respected for all outgoing requests via urllib.request.ProxyHandler. You can also configure request timeouts via the --timeout option (defaults to 30 seconds):

# Custom timeout for slow networks
oss-contribution-finder --language python --timeout 60

Without a token, searches are limited to 10 requests per minute.

Results include a contributor_friendly boolean in JSON (and a Friendly column in the table / line in Markdown). It is true when a repository has a root CONTRIBUTING.md, a .github/PULL_REQUEST_TEMPLATE.md file, a .github/PULL_REQUEST_TEMPLATE/ directory, or a .github/ISSUE_TEMPLATE/ directory. Detection uses up to two additional GitHub API requests per unique repository, even with --no-enrich or no token. --require-contributing filters on the root file specifically, not on the broader friendly signal. API errors emit a warning; results may then be incomplete, and the filter excludes repositories whose root file it cannot verify.

Examples

# Find documentation contributions
oss-contribution-finder --label "good first issue" --label "documentation" --limit 15

# Find recently updated Python issues in AI/ML
oss-contribution-finder --language python --topic machine-learning --updated-after 2026-08-01

# Generate a weekly digest
oss-contribution-finder --language rust --format markdown --limit 25 > weekly-opportunities.md

Sponsoring

oss-contribution-finder is MIT licensed and free to use. If it saved you time, you can support continued maintenance via GitHub Sponsors or by sending SOL to the project treasury wallet:

Eeztv1nCYUt1fwGWpzKC948gaWfjejYCAuLtUMgzDWbW

Funding platforms are configured in .github/FUNDING.yml.

If this tool is useful to you, a star helps other people find it.

Related tools

• gfi — find well-scoped good first issues to start on
• aipr — pre-screen repos for AI contribution policy
• ghstats — generate a GitHub stats dashboard
• agent-guard — enforce guardrails on AI agent tool calls

Part of a family of focused, single-purpose developer tools — each one does one thing and does it well.

License

MIT