How Detection Works

FlagShark uses a sophisticated two-phase architecture to detect feature flags and track their lifecycle. This guide explains how flags are detected, when they're persisted to your inventory, and why this architecture ensures accurate tracking.

The Two-Phase Architecture

FlagShark operates in two distinct phases:

1. PR Preview Phase: When you open or update a pull request, FlagShark analyzes the diff and posts a comment showing which flags are being added or removed. This is a preview - flags aren't persisted yet.

2. Lifecycle Tracking Phase: When code reaches your default branch (via merge or direct push), FlagShark detects the actual flag changes and persists them to your inventory. This is the source of truth.

flowchart TB
    subgraph "GitHub Events"
        PR["Pull Request<br/>(opened/updated)"]
        MERGE["PR Merged"]
        DIRECT["Direct Push<br/>to main/master"]
    end
    
    subgraph "FlagShark Processing"
        PRPROC["PR Processor<br/>(Preview Only)"]
        PUSHPROC["Push Flag Detector<br/>(Lifecycle Tracking)"]
    end
    
    subgraph "Outputs"
        COMMENT["GitHub PR Comment<br/>(Preview)"]
        DB["DynamoDB<br/>(Flag Lifecycle)"]
        DASH["Dashboard<br/>(Flag Inventory)"]
    end
    
    PR --> PRPROC
    PRPROC --> COMMENT
    
    MERGE --> PUSHPROC
    DIRECT --> PUSHPROC
    PUSHPROC --> DB
    DB --> DASH

Why This Architecture?

Single Source of Truth

By tracking flags only when they reach the default branch, FlagShark avoids duplicate entries and ensures your inventory reflects what's actually in production.

Consider this scenario without the two-phase approach:

• You open a PR adding new-checkout-flag
• Flag is tracked immediately
• You close the PR without merging
• Flag is now in your inventory but not in your code

With FlagShark's architecture, this can't happen. Flags only enter your inventory when they're actually in your default branch.

Complete Coverage

Not all code changes go through pull requests. Some teams:

• Push hotfixes directly to main during incidents
• Use automated tools that commit directly
• Have legacy workflows that bypass PRs

FlagShark catches all of these. Every push to your default branch is analyzed, whether it came from a merged PR or a direct commit.

Accurate State

When a PR is merged, FlagShark compares the before and after states of your default branch. This means:

• Flags that were added in the PR are detected as FLAG_ADDED
• Flags that were removed are detected as FLAG_REMOVED
• The exact commit SHA and author are captured

The Detection Flow

Here's the complete flow from GitHub event to your dashboard:

sequenceDiagram
    participant GH as GitHub
    participant API as FlagShark API
    participant SQS as SQS Queue
    participant Proc as Webhook Processor
    participant DB as DynamoDB
    participant Dash as Dashboard
    
    Note over GH,Dash: Phase 1: PR Preview
    GH->>API: PR opened webhook
    API->>SQS: Queue message
    SQS->>Proc: Process PR event
    Proc->>Proc: Parse diff, detect flags
    Proc->>GH: Post comment (preview)
    Note right of Proc: Flags NOT persisted yet
    
    Note over GH,Dash: Phase 2: Lifecycle Tracking (Merge)
    GH->>API: Push webhook (merge commit)
    API->>SQS: Queue message
    SQS->>Proc: Process push event
    Proc->>GH: Compare before/after commits
    Proc->>Proc: Detect added/removed flags
    Proc->>DB: Save FLAG_ADDED events
    Proc->>DB: Save FLAG_REMOVED events
    Proc->>GH: Post commit status
    DB->>Dash: Flags appear in inventory
    
    Note over GH,Dash: Direct Push (Also Tracked!)
    GH->>API: Push webhook (direct commit)
    API->>SQS: Queue message
    SQS->>Proc: Process push event
    Proc->>DB: Save flag events
    Note right of Proc: No PR association, but still tracked

What Gets Tracked Where

Phase 1: PR Preview

When you open or update a pull request, FlagShark:

The comment shows:

• Flags being added (new to the codebase)
• Flags being removed (cleanup)
• File locations and line numbers
• SDK method used

Phase 2: Lifecycle Tracking

When code reaches your default branch, FlagShark:

Merged PRs

When a PR is merged, GitHub sends a push event for the merge commit. FlagShark:

• Detects the flag changes
• Links them to the PR that introduced them
• Captures the PR author as the flag owner

Direct Pushes

When code is pushed directly to main/master (no PR), FlagShark:

• Detects the flag changes
• Records the commit author
• Tracks the flag without a PR association

Repository Scans vs. Real-time Detection

FlagShark offers two complementary ways to discover flags:

Repository Scans

• When: Triggered manually or when you first track a repository
• What: Analyzes the entire default branch
• Purpose: Discover existing flags that were added before FlagShark

Real-time Detection

• When: Every push to the default branch
• What: Analyzes only the changes in that push
• Purpose: Track flags as they're added or removed

Both contribute to the same flag inventory. A typical workflow:

Commit Status Checks

After processing a push event, FlagShark posts a commit status check to GitHub:

This gives you visibility into flag detection directly in GitHub's commit history.

Deduplication

FlagShark prevents duplicate tracking:

• Webhook deduplication: Each GitHub webhook has a unique delivery ID. FlagShark tracks processed deliveries to prevent double-processing.
• Flag deduplication: Before emitting a FLAG_ADDED event, FlagShark checks if the flag is already active in that repository.
• Event idempotency: The same flag change won't create multiple events even if webhooks are retried.

Related Documentation

• Flag Detection - Overview of detection capabilities
• Supported Languages - Languages and SDKs we support
• GitHub Comments - How PR comments work
• Configuration - Custom flag patterns