Implement GitHub Informer for cache-based issue watching

[gjkim42]

Problem

The current GitHubSource in internal/source/github.go is stateless — every poll cycle does a full re-fetch from the GitHub API:

1. List all matching issues → 1-10 API calls (paginated, up to maxPages=10)
2. For each matched issue, fetch comments → N API calls
3. Total: ~10 + N calls per cycle

With a pollInterval: 1m, this works fine when labels do server-side filtering (N is small). But if we move to comment-based or other client-side filtering (see related issue), N becomes ALL open issues, potentially hitting 60K+ calls/hour on active repos — far exceeding GitHub's 5K/hr rate limit.

Proposed Solution: GitHub Informer

Implement a cache-based GitHub watcher, analogous to the Kubernetes informer pattern:

K8s Informer	GitHub Informer
Initial List all resources	Initial List all issues + comments
Watch stream for changes	Poll with since param / ETags for deltas
Local cache (store) serves reads	Local cache serves Discover()
Reflector keeps cache in sync	Syncer keeps cache in sync

Architecture

                    ┌─────────────────────────┐
                    │   GitHub Informer        │
                    │                          │
  GitHub API ──────→│  Syncer (ETag/since)     │
  (delta updates)   │         │                │
                    │         ▼                │
                    │  Local Cache             │
                    │  (issues + comments      │
                    │   + labels + reactions)   │
                    └────────┬────────────────┘
                             │
                    ┌────────▼────────────────┐
                    │  GitHubSource.Discover() │
                    │                          │
                    │  Reads from cache, not   │
                    │  from API. Can filter by │
                    │  labels OR comments OR   │
                    │  anything — all free.    │
                    └─────────────────────────┘

How It Works

Initial sync (once):

• List all open issues + their comments → expensive but one-time

Subsequent cycles:

• GET /issues?since=<last_sync_time> → only changed issues (usually 0-5)
• GET /issues/{n}/comments?since=<last_sync_time> → only new comments
• GitHub supports ETags (If-None-Match header) — a 304 Not Modified response does not count against rate limits
• Cost drops from O(issues) to O(changes) per cycle

Key Benefits

1. Decouples data fetching from state evaluation. Once the cache is warm, filtering by labels, comments, reactions, or any future signal mechanism is free — just read from cache.
2. Makes the label vs. comment debate a UX decision, not a technical constraint. The rate limit concern (biggest objection to comment-based filtering) is eliminated.
3. Familiar pattern. The team already works with K8s informers. Same mental model.
4. Backward compatible. GitHubSource.Discover() returns the same []WorkItem — the interface doesn't change, only the implementation.

Implementation Sketch

// GitHubInformer maintains a local cache of GitHub issues and comments.
type GitHubInformer struct {
    owner    string
    repo     string
    token    string
    baseURL  string
    client   *http.Client

    // Cache
    mu       sync.RWMutex
    issues   map[int]*CachedIssue  // issue number → cached data
    lastSync time.Time             // for `since` parameter
    etag     string                // for conditional requests
}

type CachedIssue struct {
    Issue    githubIssue
    Comments []githubComment
    LastSeen time.Time
}

// Sync fetches changes since last sync and updates the cache.
func (i *GitHubInformer) Sync(ctx context.Context) error {
    // Use ?since=<lastSync> to get only changed issues
    // Use If-None-Match for ETag-based conditional requests
    // Update cache incrementally
    // Evict closed issues
}

// GitHubSource.Discover() reads from the informer cache instead of making API calls.
func (s *GitHubSource) Discover(ctx context.Context) ([]WorkItem, error) {
    if err := s.informer.Sync(ctx); err != nil {
        return nil, err
    }
    // Read from cache — filter by labels, comments, whatever is configured
    // Zero additional API calls
}

Considerations

• Memory usage: A repo with 10K open issues needs meaningful memory. Mitigate by only caching open issues and evicting closed ones on sync.
• Cold start: First sync is expensive. Could persist cache to ConfigMap/PV for fast restarts, or accept one slow cycle.
• Consistency: Cache is at most pollInterval stale — same as current system (it's polling too).
• Multiple spawners: If multiple TaskSpawners watch the same repo, consider a shared informer (like K8s SharedInformerFactory) to avoid duplicate API calls.
• Webhook upgrade path: The informer architecture naturally supports adding GitHub webhooks later for real-time cache invalidation, replacing polling entirely.

Files That Would Change

• internal/source/github.go — Split into informer + source; Discover() becomes cache reader
• internal/source/github_informer.go — New file for the informer implementation
• cmd/axon-spawner/main.go — Initialize informer, pass to source
• internal/source/github_test.go — Tests for delta sync, ETag handling, cache behavior

Related

• Comment-based workflow control proposal: Moving beyond label-based workflow control #417 (depends on this for viable API rate limits)
• Current polling implementation: internal/source/github.go
• K8s informer pattern: k8s.io/client-go/tools/cache

[axon-agent]

🤖 Axon Agent @gjkim42

Axon Triage Report

Kind: kind/feature

Status: STILL VALID

Evidence:

• The current GitHubSource in internal/source/github.go is fully stateless — Discover() calls fetchAllIssues() (paginated, up to 10 pages) and then fetchComments() for every matched issue on every poll cycle, exactly as described in the issue.
• No caching, ETag support, or since-parameter-based delta fetching exists anywhere in the internal/source/ directory.
• No github_informer.go file exists in the codebase.
• No merged PRs or commits reference this issue or implement an informer/cache pattern for the GitHub source.
• The proposed architecture (cache + delta sync) is a well-defined improvement over the current O(issues) per-cycle API cost.

Duplicates found: None found

• Moving beyond label-based workflow control #417 (label vs comment filtering) is related but distinct — it is about the filtering mechanism, while Implement GitHub Informer for cache-based issue watching #418 is about the underlying caching infrastructure that would make any filtering approach API-efficient. The issue itself references Moving beyond label-based workflow control #417 as a dependency.
• API: Add webhook and GitHub event sources to TaskSpawner for real-time task triggering #268 (webhook/event sources) is complementary — it proposes webhooks for real-time triggering, while Implement GitHub Informer for cache-based issue watching #418 proposes a cache-based polling optimization. The issue notes that the informer architecture would naturally support adding webhooks later.

Recommendation: KEEP OPEN — The feature is well-scoped with a clear implementation sketch and addresses a real scalability limitation in the current polling design.

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kelos Triage Report

Kind: kind/feature

Status: STILL VALID

Evidence:

• The current GitHubSource in internal/source/github.go remains fully stateless. Discover() calls fetchAllIssues() (paginated, up to 10 pages) and then fetchComments() for every matched issue on every poll cycle — exactly as described in the issue.
• No caching, ETag support, since-parameter-based delta fetching, or informer pattern exists anywhere in internal/source/. Confirmed via code search: zero matches for etag, cache, informer, or since in that directory.
• No github_informer.go file exists in the codebase.
• No merged PRs or commits reference issue Implement GitHub Informer for cache-based issue watching #418 or implement a cache/informer pattern for the GitHub source. Searched git log --grep="418" and gh pr list --state merged --search "418" — both returned no results.
• The problem is now more pressing than when originally filed: PR Add comment-based workflow control for GitHub issues #420 landed comment-based workflow control (triggerComment/excludeComments), which means fetchComments() is now called for every matched issue on every poll cycle. This is exactly the O(issues) API cost scenario the issue warns about.
• Related issue Moving beyond label-based workflow control #417 (label vs. comment filtering) is now CLOSED, and its implementation (PR Add comment-based workflow control for GitHub issues #420) directly increases the value of this caching proposal.
• API: Add webhook and GitHub event sources to TaskSpawner for real-time task triggering #268 (webhook/event sources) remains open and is complementary — the informer architecture proposed here would naturally support webhooks as a future cache invalidation mechanism.

Duplicates found: None found

• API: Add webhook and GitHub event sources to TaskSpawner for real-time task triggering #268 (webhook event sources) is complementary but distinct — it proposes real-time webhook triggering, while Implement GitHub Informer for cache-based issue watching #418 proposes cache-based polling optimization. No semantic overlap in implementation.
• API: Add optional PersistentVolumeClaim for workspace caching to avoid repeated full clones #397 (PVC for workspace caching) is about workspace/clone caching, not GitHub API response caching — different scope entirely.

Recommendation: KEEP OPEN — The feature addresses a real and growing scalability limitation. With comment-based filtering now merged (PR #420), the per-cycle API cost has increased, making this caching infrastructure more valuable than when originally proposed.