GitHub Issue Finder for Go DevOps Projects

A Telegram bot that finds and alerts you about good learning opportunities (issues) in popular Go DevOps projects.

Features

Monitors 500+ popular Go DevOps projects
Scores issues based on multiple factors:
- Project star count
- Issue recency
- Number of comments
- Labels (good first issue, help wanted, etc.)
- Difficulty level
- Description quality
- Project activity level
- Maintainer responsiveness
- Contributor friendliness
- Weekend/weekday timing
Sends Telegram alerts for high-scoring issues
Email notifications via SMTP with beautiful HTML templates
Persistent storage to track already notified issues
Configurable check intervals

New Features (v2.0)

Issue Tracking: Track issues you're working on with statuses (interested, assigned, in_progress, completed, abandoned)
Anti-Spam Protection: Rate limiting, cooldown periods, daily/hourly limits, and digest mode
Enhanced Scoring: Better prioritization with configurable weights
CLI Commands: Full command-line interface for managing tracked issues
Email System: SMTP support with HTML templates, rate limiting, and digest mode
Partitioned Display: Issues displayed in sections sorted by score
Assignment Management: Automatic assignment request handling

CLI Commands

# Find new issues
github-issue-finder find

# Find good first issues
github-issue-finder good-first

# Find actionable issues
github-issue-finder actionable

# Find confirmed good first issues (ready for assignment)
github-issue-finder confirmed

# Track an issue you're working on
github-issue-finder track --url https://github.com/kubernetes/kubernetes/issues/123456 \
  --title "Fix bug" --org kubernetes --repo kubernetes --number 123456 \
  --status interested --notes "Good learning opportunity"

# Update issue status
github-issue-finder update --url https://github.com/kubernetes/kubernetes/issues/123456 \
  --status in_progress --notes "Started working on this"

# List tracked issues
github-issue-finder list --all
github-issue-finder list --status in_progress

# Check issue status
github-issue-finder status --url https://github.com/kubernetes/kubernetes/issues/123456

# View statistics
github-issue-finder stats

# Daily digest
github-issue-finder digest

# Test email configuration
github-issue-finder email-test

MCP (Model Context Protocol) Integration

The GitHub Issue Finder supports MCP (Model Context Protocol), enabling seamless integration with AI assistants like Claude Desktop. MCP allows AI assistants to access project features as tools, enabling AI-enhanced comment generation, issue analysis, and automated workflows.

Benefits

AI Assistant Integration: Connect directly to Claude Desktop and other MCP-compatible AI assistants
AI-Accessible Tools: Expose all project features as tools that AI assistants can invoke
Enhanced Workflows: Enable AI-enhanced comment generation and intelligent issue analysis
Automated Discovery: Let AI assistants find and prioritize issues based on your preferences
Smart Tracking: AI can manage your tracked issues and suggest next steps

MCP Server Mode

Run GitHub Issue Finder as an MCP server to connect with AI assistants:

# Run as MCP stdio server (for Claude Desktop)
./github-issue-finder mcp

# Run as MCP HTTP server
./github-issue-finder mcp-http --port 8080

# List available MCP tools
./github-issue-finder mcp-list-tools

# Test MCP server
./github-issue-finder mcp-test

Available MCP Tools

The MCP server exposes 12 tools for AI assistants:

Tool	Description
`find_issues`	Search for issues matching custom criteria
`find_good_first_issues`	Find beginner-friendly issues with good labels
`find_confirmed_issues`	Find triage-confirmed issues ready for assignment
`get_issue_score`	Get detailed scoring breakdown for an issue
`track_issue`	Add an issue to your tracked list
`list_tracked_issues`	View all issues you're tracking
`update_issue_status`	Update status of a tracked issue
`generate_comment`	Generate a professional comment for an issue
`search_repos`	Search configured repositories
`get_stats`	Get overall statistics and metrics
`get_issue_details`	Retrieve detailed information about an issue
`analyze_issue`	Perform deep analysis on an issue

MCP Resources

The MCP server exposes the following resources:

Resource	Description
`tracked://`	All tracked issues with statuses
`config://`	Current configuration settings
`repos://`	Configured repositories list
`issue://{owner}/{repo}/{number}`	Individual issue template

MCP Prompts

Pre-built prompts for common AI workflows:

Prompt	Description
`find_resume_worthy_issues`	Find issues that would look great on your resume
`analyze_and_suggest`	Analyze an issue and suggest next steps
`create_contribution_plan`	Create a structured contribution plan
`generate_issue_comment`	Generate a professional issue comment

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "github-issue-finder": {
      "command": "/path/to/github-issue-finder",
      "args": ["mcp"]
    }
  }
}

For HTTP mode:

{
  "mcpServers": {
    "github-issue-finder": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

AI Enhancement Configuration

Configure the MCP client for AI-enhanced features in your config.yaml:

mcp:
  client:
    enabled: true
    servers:
      - name: "claude"
        command: "claude-mcp-server"
        args: []
      - name: "openai"
        url: "http://localhost:8081/mcp"
    timeout: 30s
    retry_count: 3

MCP Configuration Reference

Full MCP configuration options:

mcp:
  server:
    enabled: true
    type: stdio              # stdio or http
    port: 8080               # HTTP port (if type: http)
    host: "localhost"        # HTTP host
    
  client:
    enabled: true
    timeout: 30s
    retry_count: 3
    retry_delay: 1s
    
    servers:
      - name: "local"
        command: "/path/to/github-issue-finder"
        args: ["mcp"]
        env:
          GITHUB_TOKEN: "${GITHUB_TOKEN}"
          
  tools:
    enabled:
      - find_issues
      - find_good_first_issues
      - find_confirmed_issues
      - get_issue_score
      - track_issue
      - list_tracked_issues
      - update_issue_status
      - generate_comment
      - search_repos
      - get_stats
      - get_issue_details
      - analyze_issue
      
  resources:
    enabled: true
    cache_ttl: 5m
    
  prompts:
    enabled: true
    custom_prompts_dir: "./prompts"

Environment Variables for MCP

# MCP Server Settings
MCP_ENABLED=true
MCP_SERVER_TYPE=stdio          # stdio or http
MCP_HTTP_PORT=8080
MCP_HTTP_HOST=localhost

# MCP Client Settings
MCP_CLIENT_ENABLED=true
MCP_CLIENT_TIMEOUT=30s
MCP_CLIENT_RETRY_COUNT=3

Email Configuration

Basic Email Setup

Set the following environment variables:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your-app-password
[email protected]
[email protected]

Email Modes

EMAIL_MODE=instant - Send emails immediately when issues are found
EMAIL_MODE=digest - Send daily digest at configured time

Email Rate Limiting

MAX_EMAILS_PER_HOUR=10 - Maximum emails per hour
MAX_EMAILS_PER_DAY=50 - Maximum emails per day

Email Templates

Beautiful HTML email templates are available for:

New issue notification (with score breakdown)
Daily digest
Assignment confirmation
Assignment request sent

Scoring Configuration

All scoring weights can be customized via environment variables:

# Scoring Weights (0.0 - 1.0)
SCORING_STAR_WEIGHT=0.08              # Project popularity
SCORING_COMMENT_WEIGHT=0.15           # Less competition bonus
SCORING_RECENCY_WEIGHT=0.15           # Newer issues
SCORING_LABEL_WEIGHT=0.20             # Good labels (GFI, help wanted)
SCORING_DIFFICULTY_WEIGHT=0.12        # Simpler issues
SCORING_DESCRIPTION_WEIGHT=0.10       # Clear description
SCORING_ACTIVITY_WEIGHT=0.10          # Active project
SCORING_MAINTAINER_WEIGHT=0.10        # Responsive maintainers

# Bonus Scores
SCORING_CONTRIBUTOR_FRIENDLY_BONUS=0.15  # Beginner-friendly labels
SCORING_WEEKEND_BONUS=0.05               # Issues opened on weekends
SCORING_MAX_SCORE=1.5                    # Maximum possible score

Anti-Spam Configuration

# Notification Limits
MAX_NOTIFICATIONS_PER_HOUR=10
DAILY_NOTIFICATION_LIMIT=30
MAX_NOTIFICATIONS_PER_PROJECT=2
NOTIFICATION_COOLDOWN_HOURS=24

# Comment Limits
MAX_COMMENTS_PER_DAY=5

# GitHub API Limits
MAX_GITHUB_CALLS_PER_HOUR=4000

# Digest Mode
DIGEST_MODE=false
DIGEST_TIME=09:00

Assignment Configuration

# Enable automatic assignment requests
ASSIGNMENT_ENABLED=true
ASSIGNMENT_AUTO_MODE=false    # Set true for automatic without prompts
ASSIGNMENT_MAX_DAILY=5
ASSIGNMENT_COOLDOWN_MINS=30
ASSIGNMENT_CHECK_ELIGIBILITY=true
ASSIGNMENT_AUTO_COMMENT=false

Display Configuration

DISPLAY_MODE=partitioned      # Options: partitioned, simple, json
DISPLAY_MAX_GOOD_FIRST=15     # Max good first issues to show
DISPLAY_MAX_OTHER=10          # Max other issues to show
DISPLAY_MAX_ASSIGNED=10       # Max assigned issues to show
DISPLAY_SHOW_SCORE_BREAKDOWN=true

Supported Projects & Categories

🔧 Kubernetes Tools (100+ projects)

kubernetes/kubernetes (105k★)
helm/helm (25k★)
cilium/cilium (18k★)
rancher/rancher (22k★)
And 100+ more...

📈 Monitoring Tools (100+ projects)

prometheus/prometheus (53k★)
grafana/grafana (58k★)
jaegertracing/jaeger (19k★)
thanos-io/thanos (12k★)
And 100+ more...

🚀 CI/CD Tools (80+ projects)

argoproj/argo-cd (15k★)
drone/drone (28k★)
tektoncd/pipeline (8k★)
fluxcd/flux2 (6k★)
And 80+ more...

🔐 Security Tools (30+ projects)

aquasecurity/trivy (21k★)
kyverno/kyverno (5k★)
falcosecurity/falco (5k★)
And 30+ more...

🤖 ML/AI Projects (50+ projects)

tensorflow/tensorflow (185k★)
pytorch/pytorch (85k★)
huggingface/transformers (140k★)
And 50+ more...

Setup

Prerequisites

Go 1.21 or higher
PostgreSQL database
GitHub Personal Access Token
Telegram Bot Token (optional)
SMTP credentials (optional)

Installation

Clone the repository:

git clone <your-repo-url>
cd github-issue-finder

Install dependencies:

go mod download

Set up environment variables:

cp .env.example .env
# Edit .env with your credentials

Create PostgreSQL database:

CREATE DATABASE issue_finder;

Run the application:

make run
# or
go run main.go

Makefile Commands

make build          # Build binary
make run            # Run the application
make test           # Run tests
make test-coverage  # Run tests with coverage
make email-test     # Test email configuration
make digest         # Show daily digest
make lint           # Run linter
make fmt            # Format code
make db-stats       # Show database statistics
make help           # Show all commands

Issue Scoring

Issues are scored based on configurable weights:

Factor	Weight	Description
Stars	8%	Project popularity
Comments	15%	Less competition = higher score
Recency	15%	Newer issues score higher
Labels	20%	Good first issue, help wanted, etc.
Difficulty	12%	Simpler issues score higher
Description	10%	Clear steps, code examples
Activity	10%	Active project
Maintainer	10%	Responsive maintainers

Score ranges:

🔥 0.8+: Excellent learning opportunity
⭐ 0.6-0.8: Good opportunity
✨ Below 0.6: Worth considering

Bonus Factors

Good first issue label: +0.30
Confirmed/triage-accepted: +0.35
Help wanted label: +0.10
No assignee: +0.10
Documentation: +0.15
CNCF project: +0.10
TLS/Security related: +0.10
Beginner-friendly: +0.15
Weekend posting: +0.05

Penalty Factors

Cloud provider specific: -0.50
Needs triage: -0.15
Blocked/waiting: -0.20
Has assignee: -0.25
Has linked PR: -0.30
Wontfix/invalid: -0.50

Database Schema

The tool uses PostgreSQL to track:

seen_issues: Issues already discovered
issue_history: All discovered issues with scores
tracked_issues: Issues you're working on
notification_log: Notification history
comment_log: Comment history
assignment_requests: Assignment request history

Running as a Service

systemd

Create /etc/systemd/system/github-issue-finder.service:

[Unit]
Description=GitHub Issue Finder
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/github-issue-finder
EnvironmentFile=/path/to/.env
ExecStart=/usr/local/bin/github-issue-finder
Restart=always

[Install]
WantedBy=multi-user.target

Docker

docker build -t github-issue-finder .
docker run -d \
  --name github-issue-finder \
  --env-file .env \
  --link postgres:postgres \
  github-issue-finder

Development

Running tests

make test
make test-coverage

Building

make build

Linting

make lint
make fmt

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Name		Name	Last commit message	Last commit date
docs		docs
k9s		k9s
review-tools		review-tools
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
AUTO_FINDER_README.md		AUTO_FINDER_README.md
Dockerfile		Dockerfile
Makefile		Makefile
QUALIFIED_ISSUES_UPDATE.md		QUALIFIED_ISSUES_UPDATE.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
UPDATE_SUMMARY.md		UPDATE_SUMMARY.md
add_all.py		add_all.py
add_email.py		add_email.py
add_email_alert.py		add_email_alert.py
add_email_config.py		add_email_config.py
ai_enhanced.go		ai_enhanced.go
ai_enhanced_test.go		ai_enhanced_test.go
anti_spam.go		anti_spam.go
apply_fixes.py		apply_fixes.py
assign_best_issues.py		assign_best_issues.py
assign_issues.sh		assign_issues.sh
assignment_manager.go		assignment_manager.go
auto_finder.go		auto_finder.go
check_issues.sh		check_issues.sh
commands.go		commands.go
comment_manager.go		comment_manager.go
comment_quality.go		comment_quality.go
comment_quality_test.go		comment_quality_test.go
complete_email_setup.py		complete_email_setup.py
config.go		config.go
config.yaml		config.yaml
contribution_policy.go		contribution_policy.go
debug_script.py		debug_script.py
display.go		display.go
docker-compose.yml		docker-compose.yml
email_alert_lines.txt		email_alert_lines.txt
email_sender.go		email_sender.go
email_templates.go		email_templates.go
enhanced_scorer.go		enhanced_scorer.go
file_storage.go		file_storage.go
filter_and_assign.py		filter_and_assign.py
filter_issues.py		filter_issues.py
fix_all.py		fix_all.py
fix_email.py		fix_email.py
fix_main.py		fix_main.py
fix_telegram_v2.py		fix_telegram_v2.py
go.mod		go.mod
go.sum		go.sum
healthcheck.sh		healthcheck.sh
insert_email.py		insert_email.py
insert_email_alert.py		insert_email_alert.py
issue_analyzer.go		issue_analyzer.go
issue_analyzer_test.go		issue_analyzer_test.go
issue_tracker.go		issue_tracker.go
issues.log		issues.log
local_notifier.go		local_notifier.go
logger.go		logger.go
main.go		main.go
main_test.go		main_test.go
mcp_client.go		mcp_client.go
mcp_client_test.go		mcp_client_test.go
mcp_http.go		mcp_http.go
mcp_prompts.go		mcp_prompts.go
mcp_prompts_test.go		mcp_prompts_test.go
mcp_resources.go		mcp_resources.go
mcp_resources_test.go		mcp_resources_test.go
mcp_server.go		mcp_server.go
mcp_server_test.go		mcp_server_test.go
monitor.go		monitor.go
new_features_test.go		new_features_test.go
notification_bridge.sh		notification_bridge.sh
patch.py		patch.py
patch_main.py		patch_main.py
qualified_issue_finder.go		qualified_issue_finder.go
repo_manager.go		repo_manager.go
run.sh		run.sh
scheduled_push.log		scheduled_push.log
setup.sh		setup.sh
show_good_first_issues.sh		show_good_first_issues.sh
show_results.sh		show_results.sh
smart_comment.go		smart_comment.go
smart_comment_test.go		smart_comment_test.go
smart_limiter.go		smart_limiter.go
test.sh		test.sh
utils.go		utils.go

Latest commit

History

Folders and files

Repository files navigation