How the HelloGitHub Bot Handles Timezone Differences When Processing GitHub Events

The HelloGitHub bot eliminates timezone mismatches by converting UTC timestamps from the GitHub Events API to China Standard Time (UTC+8) using a fixed offset before filtering recent events.

The HelloGitHub repository maintains an automated bot that tracks GitHub repository stars and activity. When processing event timestamps from GitHub's API, the bot must handle timezone differences to ensure accurate filtering of recent events against the local system time.

The Challenge of Timezone Differences in Event Processing

GitHub's Events API returns timestamps in UTC format (ISO-8601 with a Z suffix), while the bot operates in China Standard Time (CST, UTC+8). Without normalization, comparing a UTC timestamp against datetime.datetime.now() (which returns local system time) creates a 8-hour discrepancy, causing the bot to incorrectly filter events or miss recent activity entirely.

UTC to Local Time Conversion Strategy

The bot implements a three-step normalization process in script/github_bot/github_bot.py to handle timezone differences consistently.

Parsing GitHub's ISO-8601 Timestamps

The bot extracts the created_at field from GitHub event payloads, which contains strings like "2024-01-15T08:30:00Z". The code uses datetime.datetime.strptime with the format specifier %Y-%m-%dT%H:%M:%SZ to parse this into a naive datetime object representing the UTC time.

Applying the China Standard Time Offset

After parsing, the bot applies a fixed 8-hour offset using datetime.timedelta(hours=8) to convert the UTC time to China Standard Time. This hardcoded offset aligns the event timestamp with the bot's local operating environment.

Filtering by the Configured Day Window

The normalized timestamp is then compared against the current local time using datetime.datetime.now(). The bot checks if the event occurred within the configured DAY window (a configurable threshold defining how many days back to process events), ensuring only recent activity is processed regardless of the original UTC timestamp.

Implementation in github_bot.py

The core logic resides in script/github_bot/github_bot.py around lines 108-110, where the bot processes WatchEvent types (star events):

import datetime

# Configuration: how many days back to look for events

DAY = 7

def process_event(data):
    # Convert UTC created_at to China Standard Time (UTC+8)

    create_time = datetime.datetime.strptime(
        data['created_at'], "%Y-%m-%dT%H:%M:%SZ"
    ) + datetime.timedelta(hours=8)   # Apply timezone offset

    
    # Check if event is within the configured day window

    date_condition = create_time >= (
        datetime.datetime.now() - datetime.timedelta(days=DAY)
    )
    
    if data['type'] == 'WatchEvent' and date_condition:
        # Store normalized timestamp for downstream processing

        data['date_time'] = create_time.strftime("%Y-%m-%d %H:%M:%S")
        return True
    return False

This implementation ensures that timezone differences between GitHub's UTC timestamps and the bot's local system time are resolved before any date comparisons occur, preventing off-by-hours filtering errors.

Summary

• The HelloGitHub bot receives UTC timestamps from GitHub's Events API but operates in China Standard Time (UTC+8).
• It handles timezone differences by parsing ISO-8601 strings and applying a fixed 8-hour offset using datetime.timedelta.
• All timestamp comparisons against datetime.datetime.now() occur after normalization to ensure accurate filtering within the configured DAY window.
• The logic is implemented in script/github_bot/github_bot.py and specifically processes WatchEvent types for star tracking.

Frequently Asked Questions

Does the bot handle daylight saving time changes?

No, the implementation uses a fixed 8-hour offset via datetime.timedelta(hours=8) rather than a timezone-aware datetime object. China Standard Time (CST) does not observe daylight saving time, so the hardcoded offset remains accurate year-round without additional logic.

What happens if the system timezone differs from UTC+8?

The bot assumes the host system runs in China Standard Time, as it compares the normalized timestamp against datetime.datetime.now() (which returns local system time). If the system timezone were different, the date_condition check would produce incorrect results unless the hours=8 offset were adjusted to match the actual local timezone offset from UTC.

Can the timezone offset be configured instead of hardcoded?

Currently, the offset is hardcoded as hours=8 in script/github_bot/github_bot.py. To support other timezones, you would need to modify the timedelta value or replace the fixed offset with a configurable variable (e.g., TIMEZONE_OFFSET = int(os.getenv('TZ_OFFSET', 8))) and adjust the comparison logic accordingly.

Why does the bot convert to local time instead of keeping everything in UTC?

The bot converts to local time (UTC+8) to align with the datetime.datetime.now() call used for the sliding window filter (DAY). By ensuring both the event timestamp and the current time are in the same timezone representation, the code avoids complex timezone-aware datetime comparisons and simplifies the "recent event" logic to basic arithmetic operations on naive datetime objects.

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