OpenSustain.investigator

This project provides a command-line tool that searches GitHub repositories while excluding those that have already been starred and therefore reviewed for OpenSustain.tech by the Ly0n account. It uses the GitHub REST API and supports advanced GitHub search syntax, sorting, filtering, and CSV export.

Features

• Run advanced GitHub search queries (e.g. in:readme "climate change" stars:>5)
• Sort results by most recently updated
• Exclude repositories starred by a specific user (default: yourself)
• Exclude repositories owned by a specific user
• Limit the maximum number of repositories returned
• Export results to CSV

Requirements

• Python 3.8 or newer
• A GitHub Personal Access Token (classic)

Setup

1. Clone the repository

   git clone git@github.com:protontypes/opensustain.investigator.git

2. Install dependencies:

   pip install requests

3. Create a GitHub Personal Access Token:

   • Go to GitHub Settings → Developer settings → Personal access tokens
   • Generate a classic token with at least the public_repo scope

Usage

   python3 github_filtered_search.py \
     --token ghp_XXXX \
     --username lyon \
     --query 'in:readme "climate change" stars:>5' \
     --csv climate_results.csv \
     --exclude-starred-user ly0n \ 
     --max 50

Arguments

• --token GitHub Personal Access Token

• --username Your GitHub username (for identification)

• --query GitHub repository search query

• --csv Output CSV file name

• --exclude-owner Exclude repositories owned by a specific user

• --exclude-starred-user USER Exclude repositories starred by another user (default: your username).

• --max Maximum number of repositories to return

Output

The generated CSV file contains the following columns:

• Repository name (owner/repo)
• Repository URL
• Description
• Star count
• Last updated timestamp
• Owner

Notes

• GitHub search results are limited to approximately 1,000 results per query by the GitHub API.
• Excluding starred repositories requires a valid and authorized token.

License

MIT License