Automating GitHub Issue Cleanup with Python and the GitHub API#

Essential Concepts for GitHub Issue Automation#

Successful automation of GitHub issue cleanup requires understanding several key concepts:

• GitHub Issues: The fundamental unit for tracking tasks, bugs, features, and other work items within a GitHub repository. Issues have states (open, closed), labels, assignees, comments, and activity timelines.
• Stale Issues: Issues that meet specific criteria indicating they are no longer actively being worked on or are relevant. Common criteria include:
  • Lack of activity (comments, commits linked) for a defined period (e.g., 6 months).
  • Specific labels (e.g., “question,” “discussion,” “answered”) where closure is appropriate.
  • Association with completed milestones or projects.
• GitHub API: A RESTful interface that allows external applications to interact with GitHub data programmatically. This includes reading repository information, listing issues, adding comments, applying labels, and closing issues. Access requires authentication.
• Personal Access Tokens (PATs): Secure credentials used to authenticate with the GitHub API on behalf of a user or organization. PATs grant specific permissions (scopes) to interact with repositories and user data. Using PATs is a standard and recommended authentication method for scripts and tools.
• Python Libraries: High-level programming languages like Python are well-suited for scripting automation tasks. Several Python libraries simplify interaction with the GitHub API, abstracting the complexities of HTTP requests and authentication. PyGitHub is a popular example, providing an object-oriented interface to GitHub resources.

The combination of Python’s scripting capabilities and the GitHub API’s programmatic access enables the creation of custom automation workflows tailored to specific repository needs and cleanup criteria.

Setting Up for Automation: Authentication and Libraries#

Interacting with the GitHub API requires authentication to identify the requesting application and control its permissions. The recommended approach for scripts is using a Personal Access Token.

1
pip install PyGitHub

Automating Issue Cleanup: A Step-by-Step Approach#

The process involves writing a Python script that uses the generated PAT to connect to GitHub, fetches issues from a target repository, applies defined cleanup logic, and performs actions via the API.

1
import os
2
from github import Github
3

4
# Retrieve token from environment variable for security
5
github_token = os.environ.get('GITHUB_TOKEN')
6
if not github_token:
7
    raise ValueError("GITHUB_TOKEN environment variable not set.")
8

9
# Authenticate with GitHub
10
g = Github(github_token)
11

12
# Specify the repository (e.g., 'owner/repo_name')
13
repo_name = "octocat/Spoon-Knife" # Replace with your repository name
14
try:
15
    repo = g.get_repo(repo_name)
16
    print(f"Successfully connected to repository: {repo_name}")
17
except Exception as e:
18
    print(f"Error connecting to repository {repo_name}: {e}")
19
    exit(1)

1
import datetime
2

3
days_stale = 180
4
stale_date = datetime.datetime.now() - datetime.timedelta(days=days_stale)
5

6
# Fetch open issues updated before the stale_date
7
# The GitHub API supports filtering by state and update time
8
# Note: PyGitHub might require iterating and checking updated_at for client-side filtering
9
# A direct search query is often more efficient for complex criteria
10
query = f'repo:{repo_name} is:issue is:open updated:<{stale_date.strftime("%Y-%m-%d")}'
11
print(f"Searching for issues with query: {query}")
12

13
try:
14
    stale_issues = g.search_issues(query=query)
15
    print(f"Found {stale_issues.totalCount} potentially stale issues.")
16
except Exception as e:
17
    print(f"Error searching issues: {e}")
18
    stale_issues = [] # Handle potential API errors

1
stale_label_name = "stale"
2
closure_comment = (
3
    "This issue has been automatically marked as stale because it has not had "
4
    f"recent activity. It will be closed in {days_to_close} days if no further activity occurs. "
5
    "Thank you for your contributions."
6
)
7
days_to_close = 7 # Example: close issues 7 days after initial stale marking
8

9
try:
10
    # Ensure the 'stale' label exists
11
    try:
12
        stale_label = repo.get_label(stale_label_name)
13
    except: # Label doesn't exist, create it
14
        stale_label = repo.create_label(stale_label_name, "f9d0c4", "Indicates inactivity")
15
        print(f"Created label: {stale_label_name}")
16

17
    for issue in stale_issues:
18
        print(f"Processing issue #{issue.number}: {issue.title}")
19

20
        # Action 1: Add 'stale' label if not already present
21
        if stale_label_name not in [label.name for label in issue.labels]:
22
            issue.add_to_labels(stale_label)
23
            print(f" - Added '{stale_label_name}' label.")
24

25
        # Action 2: Add a comment if not already commented by the bot/script recently
26
        # (More complex logic might be needed to avoid spamming comments)
27
        recent_comments = [c for c in issue.get_comments() if c.created_at > stale_date] # Basic check
28
        if not any(closure_comment in c.body for c in recent_comments): # Avoid duplicate comments
29
             issue.create_comment(closure_comment)
30
             print(" - Added closure comment.")
31

32
        # Action 3 (Optional/Advanced): Close issues labeled 'stale' with comment older than X days
33
        # This would be a separate pass or integrated logic checking comment age
34
        # Example:
35
        # if stale_label_name in [label.name for label in issue.labels] and \
36
        #    any(closure_comment in c.body and c.created_at < (datetime.datetime.now() - datetime.timedelta(days=days_to_close)) for c in issue.get_comments()):
37
        #    issue.edit(state='closed')
38
        #    print(" - Closed issue.")
39

40
except Exception as e:
41
    print(f"Error processing issues: {e}")
42

43
print("Issue cleanup process completed.")

Real-World Applications and Examples#

Automated issue cleanup is valuable for various scenarios:

• Managing Large, Popular Repositories: Open source projects or large internal projects often receive numerous issues, some of which are low priority or duplicates that never get explicitly closed. Automation helps surface important issues by archiving inactive ones. Example: A widely used library might automatically label issues with no activity for 90 days as “stale” and close them after another 30 days, significantly reducing the manual burden on maintainers.
• Keeping Track of Feature Requests or Discussions: Issues created for potential features or general discussions can become irrelevant as the project evolves. Automation can help prune these, perhaps by closing discussion issues after a fixed period or labeling them as “archived.” Example: A project uses issues for feature ideas. After a release cycle is completed, issues tagged for that cycle but not implemented and inactive for 6 months are automatically labeled “future consideration” or closed.
• Ensuring Project Focus: For projects with specific milestones, issues tied to completed milestones that remain open might indicate oversight. An automated script could list or label such issues for final review. Example: At the end of v2.0 development, a script identifies any open issues still linked to the v2.0 milestone that haven’t been updated in 30 days, adding a “review-for-v2.1” label or closing them.

These examples highlight how tailored cleanup criteria and actions, powered by Python and the GitHub API, contribute to a cleaner, more manageable repository state.

Key Takeaways for Automating GitHub Issue Cleanup#

• Automated issue cleanup improves repository navigability and team focus by managing stale issues.
• Python scripting combined with the GitHub API provides a flexible solution.
• Authentication using Personal Access Tokens with appropriate scopes is essential and must be handled securely (e.g., environment variables).
• Libraries like PyGitHub simplify interaction with the GitHub API.
• Defining clear, objective criteria for identifying stale issues (e.g., age, inactivity, labels) is paramount before writing code.
• Implementing cleanup actions (labeling, commenting, closing) should consider a cautious, multi-stage approach (e.g., label/comment first, close later).
• Leveraging the GitHub API’s search capabilities is efficient for filtering issues based on complex criteria.
• Scheduling the script using tools like GitHub Actions ensures regular maintenance without manual intervention.
• Applying cleanup automation to scenarios like large repositories, feature request tracking, or milestone management yields tangible benefits in project organization.