How the HelloGitHub GitHub Bot Tracks Starred Repositories via the GitHub Events API

The HelloGitHub bot polls the GitHub Events API for WatchEvent activities, filters them by time window and repository ownership, enriches them with current star counts, and delivers a ranked digest of high-impact repositories.

The HelloGitHub project operates an automated GitHub bot that curates trending repositories by monitoring star activity across the platform. This article explains how the HelloGitHub GitHub Bot tracks starred repositories using the GitHub Events API, examining the specific Python implementation that filters, enriches, and ranks WatchEvent data to surface noteworthy open-source projects.

Fetching Raw Events with get_all_data()

The tracking pipeline begins in script/github_bot/github_bot.py with the get_all_data() function, which authenticates against the GitHub API and retrieves the bot user's received events stream.

The function paginates through up to 10 pages of results (maximum 300 events) from the endpoint https://api.github.com/users/{username}/received_events. Each request includes the bot’s GitHub credentials to ensure access to the full event stream. This raw data collection captures all recent activities—issues, forks, pushes, and stars—that the bot account has received.

from script.github_bot.github_bot import get_all_data

# Retrieve up to 300 recent events for the bot user

raw_events = get_all_data()

According to the source code in lines 90–101, this stage focuses purely on data acquisition, returning a complete list of event dictionaries for downstream processing.

Filtering WatchEvent Activities with check_condition()

Once raw events are collected, the check_condition() function (lines 104–118) implements the core filtering logic to isolate genuine star actions. This validation ensures that only relevant, recent, and external star events proceed to the enrichment stage.

The function applies three strict criteria to each event:

• Event Type Validation – Confirms the event is a WatchEvent (GitHub’s internal type designation for starring a repository)
• Time Window Check – Verifies the event occurred within the configurable DAY threshold (default: 1 day)
• Ownership Exclusion – Discards events where the starred repository belongs to the bot itself, preventing self-stars from polluting the digest

When an event satisfies all conditions, the function annotates it with a human-readable timestamp before returning True, signaling that the star event qualifies for further processing.

Enriching and Ranking Repositories with get_stars()

The final processing stage occurs in get_stars() (lines 134–162), which transforms filtered WatchEvent entries into ranked repository recommendations. This enrichment layer separates high-impact projects from casual stars by evaluating current popularity metrics.

For each qualifying event, the function:

1. Retrieves repository metadata by querying the repo['url'] endpoint to obtain the current stargazers_count
2. Applies the star threshold by comparing the count against the STARS constant (default: 100), retaining repositories with counts ≥ STARS or where the lookup failed (represented as -1)
3. Sorts by impact, ordering the final list in descending order of star count to prioritize the most popular discoveries

The resulting dataset feeds directly into the content generation pipeline, where make_content() formats entries into an HTML table and send_email() dispatches the digest to configured RECEIVERS.

Practical Implementation: Running the Star Tracker

To execute the complete tracking workflow locally, chain the three primary functions to extract, filter, and rank starred repositories:

from script.github_bot.github_bot import get_all_data, analyze, get_stars

# Stage 1: Pull raw events from the GitHub Events API

raw_events = get_all_data()

# Stage 2: Filter for recent WatchEvent entries (excludes bot repos)

star_events = analyze(raw_events)

# Stage 3: Enrich with star counts and filter by popularity threshold

high_impact = get_stars(star_events)

# Display results

for repo in high_impact:
    print(f"{repo['repo_name']} – {repo['repo_stars']} ⭐ (starred {repo['date_time']})")

After processing, generate and dispatch the email digest using the formatting utilities:

from script.github_bot.github_bot import make_content, send_email, RECEIVERS

# Build HTML table rows for each selected repository

email_body = make_content()

# Send the curated digest to configured recipients

send_email(RECEIVERS, email_body)

Customizing the Tracking Thresholds

The bot’s sensitivity is controlled by two configuration constants defined in script/github_bot/github_bot.py. Adjust these values to expand or restrict the tracking scope:

# In script/github_bot/github_bot.py

DAY = 2      # Track stars from the last 2 days (default: 1)

STARS = 250  # Only retain repositories with ≥250 stars (default: 100)

Increasing DAY captures longer-term trending repositories, while raising STARS filters for only the most established projects. Setting either threshold too low may increase noise in the final digest.

Summary

• The HelloGitHub bot monitors the received_events endpoint to capture up to 300 recent activities per execution cycle.
• The check_condition() function isolates WatchEvent entries from the last 24 hours while excluding the bot’s own repositories.
• get_stars() enriches filtered events with live stargazers_count data and applies a minimum threshold of 100 stars by default.
• The pipeline delivers a descending-ranked list of high-impact repositories formatted as an HTML email digest.

Frequently Asked Questions

What GitHub API endpoint does the HelloGitHub bot use to track stars?

The bot queries https://api.github.com/users/{username}/received_events through the get_all_data() function in script/github_bot/github_bot.py. This endpoint returns the authenticated user's received events stream, which includes WatchEvent (star) activities from followed users and watched repositories.

How does the bot prevent self-starred repositories from appearing in the digest?

During the filtering phase, check_condition() validates that the repository owner in the event payload does not match the bot's own username. This ownership check ensures that stars on the HelloGitHub organization's own repositories are discarded before the enrichment stage.

What is the default star threshold and how can I change it?

The default threshold is 100 stars, controlled by the STARS constant in script/github_bot/github_bot.py. To adjust this, modify the constant value before running the bot—repositories with stargazers_count below this number are excluded from the final output unless the API lookup fails (returning -1).

How many events does the bot process in a single run?

The bot paginates through 10 pages of the Events API, processing a maximum of 300 events per execution. This limit balances comprehensive coverage against API rate limits and processing time for the daily digest generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}