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.

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:

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