GitHub Integration

The GitHub integration is the core of FlagShark. When you install the FlagShark GitHub App, it monitors your repositories for pull requests, detects feature flag changes, and helps you manage flag cleanup. This guide explains how the integration works and what it can do.

How It Works

GitHub App Permissions

The FlagShark GitHub App requests only the permissions necessary for operation:

Permission	Level	Purpose
Contents	Read/Write	Fetch file contents, diffs, and repository trees for flag detection. Write access is used only for creating cleanup PRs.
Pull Requests	Read/Write	Read PR details and post summary comments. Write access enables creating automated cleanup PRs.
Issues	Read/Write	Post comments on pull requests (GitHub's API uses Issues for PR comments).
Metadata	Read	Read repository metadata like name, default branch, and language.

Why Write Access?

Write access to Contents and Pull Requests is needed for:

• Cleanup PRs — Creating automated removal PRs for stale flags
• Branch creation — Creating branches for cleanup PRs
• PR comments — Posting flag summaries on your PRs

If you don't want cleanup PR functionality, you can still use FlagShark for detection only—the write permissions simply won't be exercised.

Webhook Events

FlagShark listens to these GitHub webhook events:

Pull Request Events

Event	Actions	What FlagShark Does
pull_request	opened	Analyze PR for flags, post initial comment
pull_request	synchronize	Re-analyze after new commits, update comment
pull_request	edited	Re-analyze if base branch changed
pull_request	closed	Update removal PR status if applicable
pull_request	reopened	Restore removal PR tracking
pull_request	ready_for_review	Update status for draft → ready

Push Events

Event	What FlagShark Does
push (to default branch)	Single source of truth for flag lifecycle. Detects when flags are added or removed in production.

Installation Events

Event	Actions	What FlagShark Does
installation	created	Create workspace, store repository list
installation	deleted	Clean up workspace and all associated data
installation	suspend	Mark workspace as suspended
installation	unsuspend	Reactivate workspace
installation_repositories	added / removed	Update tracked repository list

Comment Events

Event	What FlagShark Does
issue_comment (on PRs)	Handle @flagshark commands

PR Comment Commands

You can interact with FlagShark by commenting on PRs:

Command	Description
@flagshark rebase	Rebase the cleanup PR onto the latest base branch
@flagshark update	Update the cleanup PR with any new changes
@flagshark regenerate	Regenerate the cleanup PR from scratch

These commands are primarily used with automated cleanup PRs to keep them up to date.

Authentication

FlagShark uses GitHub App authentication for secure API access:

JWT Authentication

1. Private key — Stored securely in AWS Secrets Manager
2. JWT generation — Short-lived tokens (10 minutes) signed with RS256
3. Installation tokens — Exchanged for repository-scoped access (1 hour)

Token Caching

Installation tokens are cached to minimize API calls:

• Tokens cached for ~50 minutes (with 10-minute expiry buffer)
• Automatic refresh when tokens near expiration
• Thread-safe caching for concurrent requests

Security Features

Feature	Description
Webhook signature validation	HMAC-SHA256 verification of all webhooks
Delivery ID deduplication	Prevents replay attacks and duplicate processing
Minimal token scope	Tokens scoped to specific installation
No stored credentials	Private key in Secrets Manager, not in code

Processing Architecture

Webhook Flow

Reliability Features

Feature	Description
SQS queue	Buffers webhooks for reliable processing
Dead letter queue	Captures failed events for investigation
Circuit breaker	Prevents cascade failures on GitHub API issues
Retry with backoff	Automatic retries for transient errors
Idempotent processing	Safe to reprocess events

Installation Flow

When you install the FlagShark GitHub App:

Repository Selection

During installation, you can choose:

• All repositories — FlagShark monitors everything
• Select repositories — Choose specific repos to monitor

You can change this later in your GitHub organization settings.

Data Access

What FlagShark Reads

Data	Purpose
PR diffs	Detect flag changes
File contents (during detection)	Parse code for flags
Repository metadata	Display names, languages
PR metadata	Titles, authors, links
Commit information	Track changes

What FlagShark Writes

Data	Purpose	When
PR comments	Flag summaries	Every PR with flags
Branches	Cleanup PR branches	Automated cleanup only
Pull requests	Cleanup PRs	Automated cleanup only

What FlagShark Stores

Data	Duration	Purpose
Flag lifecycle	Permanent	Track flag age and status
PR metadata	Permanent	Link flags to PRs
Webhook events	7 days	Deduplication
Repository list	While installed	Know which repos to monitor

Managing the Integration

Changing Repository Access

Suspending the Integration

If you need to temporarily disable FlagShark:

FlagShark will stop processing webhooks but retain your data.

Uninstalling

To remove FlagShark completely:

Troubleshooting

PR Comments Not Appearing

1. Check repository access — Ensure FlagShark has access to the repository
2. Check permissions — Verify Issues/PR write access wasn't revoked
3. Check for flags — FlagShark only comments when flags are detected
4. Check rate limits — GitHub API rate limits may delay comments

Flags Not Being Detected

1. Check supported languages — Ensure your language is supported
2. Check provider configuration — Your flag provider must be configured
3. Check file extensions — Ensure files have standard extensions
4. Review the PR diff — FlagShark only analyzes changed lines

Webhook Delivery Issues

To check webhook delivery in GitHub:

Rate Limiting

FlagShark respects GitHub's rate limits:

• Uses conditional requests where possible
• Implements exponential backoff
• Circuit breaker opens after repeated failures

If you see rate limit errors, they usually resolve within an hour.

Enterprise Features

Enterprise GitHub plans unlock additional capabilities:

Feature	Description
GitHub Enterprise Server	Self-hosted GitHub support
SAML SSO	Enterprise authentication
Audit logging	Detailed event logs
Custom domains	Your own GitHub Enterprise domain

Contact sales@flagshark.io for enterprise GitHub integration.

Next Steps