Issue Cleaner

Important

This is a reporting tool and it's built entirely using automatic programming

A tool to organize and clean up GitHub issues in your repository.

What It Does

Issue Cleaner downloads all open issues from a GitHub repository and helps you understand them better:

• Groups similar issues together automatically
• Shows which issues are linked to pull requests
• Tracks linked Jira tickets
• Suggests which issues might be ready to close
• Identifies issues that need attention and care
• Shows stats about reporters, labels, and issue activity
• Provides a web interface to browse and filter everything

Setup

Requirements

• Python 3.10 or higher
• Node.js 18 or higher
• uv (Python package manager)

Install uv

# Linux/Mac
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Install Dependencies

# Backend
cd backend
uv sync

# UI
cd ui
npm install

How to Use

Step 1: Run the Scraper

Download issues from a GitHub repository:

cd backend
uv run python main.py all owner/repo

Example:

uv run python main.py all mozilla/mozilla-vpn-client

This creates a file backend/issues_data.json with all the issue data.

Step 2: Copy Data to UI

Or manually:

cp backend/issues_data.json ui/public/issues.json

Step 3: Run

cd ui
npm run dev

Open http://localhost:3000 in your browser.

GitHub Token

You can scrape without a GitHub token, but you're limited to 60 requests per hour. For larger repos, create a .env file in the backend folder:

cd backend
echo "GITHUB_TOKEN=your_github_token_here" > .env

Get a token from: https://github.com/settings/tokens

With a token you get 5,000 requests per hour.

Jira Integration

Generate a Jira token and add the following to the env file

JIRA_SERVER=https://your-company.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your_jira_token_here

What You Can Do

• View all issues in a list
• Filter by reporter, labels, or PR status
• See issues grouped by similarity (clusters)
• Find issues that might be ready to close
• Identify issues that need attention and care
• View linked pull requests and Jira tickets
• Export and share specific issues

Closure Suggestions

The tool can suggest which issues might be ready to close based on a scoring system. Click "Closure Candidates" in the UI to see the top suggestions.

How Scoring Works

Each issue gets points based on these factors:

Factor	Points	Description
Opened by Jira sync user	+100	Issues created automatically from Jira
Opened by team member	+80	Issues created by your team
Age	+1 to +60	1 point per 30 days old (max 60)
No comments	+40	No discussion on the issue
Few comments (1-2)	+25	Little discussion
Some comments (3-5)	+10	Low activity
Has closed PR	+50	Regular closed/merged PR linked
Has closed bot PR	+20	Dependabot/Renovate PR linked
Jira status done/blocked/cancelled	+70	Jira ticket is closable
Multiple Jira, primary not closable	-30	Penalty if main Jira isn't done
High positive reactions (>10)	-30	Many 👍/❤️/🎉/🚀 reactions - people care
Positive reactions (>5)	-15	Some positive reactions
Some reactions (>2)	-5	A few positive reactions

Issues with the highest scores are most likely ready to close.

Configuration

To use team member and Jira sync user scoring, add to ui/.env:

VITE_JIRA_SYNC_USER=jira-bot
VITE_TEAM_MEMBERS=alice,bob,charlie

Care Needed Suggestions

The tool can identify issues that need attention based on a scoring system. Click "Needs Care" in the UI to see issues that may be overlooked or require action.

How Scoring Works

Each issue gets points based on these factors:

Factor	Points	Description
Opened by external contributor	+100	Not from Jira sync user or team members
Age	+1 to +80	1 point per 15 days old (max 80)
Jira status backlog/open/todo	+60	Needs triage or planning
Recent activity on old issues	+1 to +50	Old issues with recent updates get more points
High positive reactions (>10)	+40	Many 👍/❤️/🎉/🚀 reactions - community interest
No Jira link	+40	Missing Jira integration
No linked PRs	+30	Not being actively worked on
Positive reactions (>5)	+25	Some positive reactions
High activity (>10 comments)	+25	Ongoing discussion
Many negative reactions (>5)	+20	Many 👎/😕 reactions - needs attention
Some positive reactions (>2)	+15	A few positive reactions
Active discussion (>5 comments)	+15	Some activity
Negative reactions (>2)	+10	Some negative reactions

Issues with the highest scores need the most attention, especially those from external contributors that have been waiting a long time.

Configuration

The feature uses the same environment variables as Closure Suggestions:

VITE_JIRA_SYNC_USER=jira-bot
VITE_TEAM_MEMBERS=alice,bob,charlie

License

MIT License