LaunchDarkly Integration

The LaunchDarkly integration enables FlagShark to automatically detect flags that are ready for code removal and create cleanup PRs for them. When you mark a flag as "ready for code removal" in LaunchDarkly, FlagShark uses LaunchDarkly's code references to find where the flag exists in your codebase and generates removal PRs.

How It Works

Prerequisites

Before connecting LaunchDarkly:

1. LaunchDarkly Code References — Must be set up and running in your repositories
2. API Access Token — Reader role (or higher) with access to your project
3. FlagShark Workspace — With the repositories you want to clean up

Setting Up the Integration

Screenshot needed: unknown → unknown

Getting a LaunchDarkly API Token

Configuration Options

Setting	Description	Default
API Key	LaunchDarkly API access token	Required
Project Key	The LD project to monitor	Required
Critical Environments	Environments where flag must be OFF before cleanup	["production"]
Max PRs per Run	Maximum cleanup PRs created per scheduled run	5
Enabled	Whether the connection is active	On

Critical Environments

Critical environments are a safety feature. Before FlagShark creates a cleanup PR for a flag, it verifies the flag is turned OFF in all critical environments.

Example: If production is a critical environment:

• Flag is OFF in production → Cleanup PR created
• Flag is ON in production → Flag skipped (too risky to remove)

Max PRs per Run

To avoid overwhelming your team with cleanup PRs, FlagShark limits how many are created per daily run. Start with 5 and increase as your team gets comfortable with the workflow.

Multiple Projects

You can connect multiple LaunchDarkly projects to a single workspace:

Each project connection operates independently with its own settings.

Filtering and Exclusions

Excluded Maintainers

If certain flag maintainers should be excluded from automatic cleanup (e.g., platform flags managed by a specific team), you can specify their emails:

excluded_maintainers:
  - platform-team@company.com
  - infrastructure@company.com

Repository Filtering

By default, FlagShark creates cleanup PRs for any repository in your GitHub organization that has code references to the flag. You can restrict this to specific repositories:

repositories:
  - web-app
  - mobile-app
  - api-service

Or exclude specific repositories:

excluded_repos:
  - legacy-monolith
  - archived-service

Understanding the Sync Process

Daily Sync Schedule

The LaunchDarkly sync runs automatically every 24 hours. During each run:

1. Fetch ready flags — Query LD for flags with staleState: readyForCodeRemoval
2. Get code references — Determine which repos contain each flag
3. Filter flags — Apply exclusions and check critical environments
4. Queue for cleanup — Send eligible flags to the cleanup processor
5. Track processed — Record processed flags to prevent duplicates

Sync Status

View sync status in Settings → Integrations:

Status	Meaning
Connected	Integration is active and syncing
Last Sync	Timestamp of most recent sync
Flags Processed	Total flags processed to date
Pending	Flags queued for cleanup

What Gets Synced

Data	Source	Usage
Flag key & name	LD Flags API	Identify the flag
Flag creation date	LD Flags API	Age tracking
Flag maintainer	LD Flags API	Filtering
Stale state	LD Flags API	Determine if ready for removal
Code references	LD Code Refs API	Find repositories
Environment status	LD Flags API	Critical environment checks

Cleanup PR Generation

When a flag passes all filters, FlagShark creates a cleanup PR:

PR Contents

• Title: [FlagShark] Remove feature flag: {flag-key}
• Branch: flagshark/remove-{flag-key}
• Body: Links to LaunchDarkly, age information, original PR (if tracked)
• Code changes: Flag usage removed using Piranha technology

Code Removal

FlagShark uses Piranha, an open-source tool from Uber, to intelligently remove flag code:

• Removes flag checks and related dead code
• Preserves the "on" branch (feature enabled) by default
• Handles complex conditionals and nested logic
• Supports multiple languages (TypeScript, Python, Go, Java, etc.)

Troubleshooting

Connection Test Fails

"Invalid API key"

• Verify the token is copied correctly (no extra spaces)
• Check the token hasn't been revoked in LaunchDarkly
• Ensure the token has Reader role or higher

"Project not found"

• Verify the project key matches exactly (case-sensitive)
• Ensure the API token has access to this project

Flags Not Being Processed

Flag is ready in LD but no PR created

Check these common causes:

1. Critical environment check failed — Flag is still ON in production
2. Already processed — Flag was processed in a previous run
3. Excluded maintainer — Flag maintainer is in exclusion list
4. No code references — LD Code References not set up for the repo
5. Repository not tracked — Repo not included in FlagShark workspace

Duplicate PRs

If you're seeing duplicate cleanup PRs:

1. Check the flagshark-ld-processed tracking table
2. Ensure you're not running multiple workspace connections for the same project
3. Contact support if the issue persists

Sync Not Running

"Last sync" shows old date

• Verify the connection is enabled
• Check your subscription is active
• Review AWS CloudWatch logs for errors (Enterprise only)

Best Practices

Workflow Integration

1. Mark flags in LD when feature is fully rolled out
2. Wait for sync (runs daily) to create cleanup PR
3. Review the PR to verify changes are correct
4. Merge and deploy following your normal process

Flag Lifecycle

Security Recommendations

1. Use service account tokens — Not personal tokens
2. Minimum permissions — Reader role is sufficient
3. Rotate tokens periodically — Update in FlagShark when rotated
4. Review PRs before merging — Don't auto-merge cleanup PRs

API Reference

For advanced users, the LaunchDarkly integration uses these LD API endpoints:

Endpoint	Purpose
GET /api/v2/flags/{project}?filter=staleState:readyForCodeRemoval	Fetch flags ready for removal
GET /api/v2/code-refs/statistics/{project}	Get code reference mapping
GET /api/v2/projects	List available projects (used in UI)

Next Steps