LaunchDarkly Integration

FlagShark integrates with LaunchDarkly in two independent ways. Understanding which one you need will save setup time.

	CLI cross-reference	SaaS LD-sync
Where configured	.flagshark.yml platforms: block	Dashboard → Settings → Integrations
Credential storage	Env var (LAUNCHDARKLY_API_TOKEN by default)	AWS Secrets Manager (entered in dashboard)
What it does	Checks scan results against your LD project; flags missing or archived in LD	Polls LD for readyForCodeRemoval flags and opens cleanup PRs
When it runs	During every flagshark scan	Daily, via a scheduled Lambda
Plan required	All plans	Team or higher

---

Integration 1 — CLI Cross-Reference

During a flagshark scan, FlagShark can cross-reference every flag key it detects in your code against your LaunchDarkly project. It emits two signals:

Signal	Severity	Meaning
missing-in-platform	error	Flag key found in code but does not exist in LD
archived-in-platform	warning	Flag key found in code but is archived in LD

Configuration

Add a platforms block to .flagshark.yml:

platforms:
  launchdarkly:
    project: my-project-key      # required
    environment: production      # required
    token_env: LAUNCHDARKLY_API_TOKEN   # optional — this is the default

The token_env field names the environment variable that holds your API access token. If omitted, LAUNCHDARKLY_API_TOKEN is used.

Export the token before running a scan:

export LAUNCHDARKLY_API_TOKEN=api-xxxxxxxxxxxxxxxxxxxxxxxx
flagshark scan

Getting an API Access Token

---

Integration 2 — SaaS LD-Sync (Dashboard)

1. 1
   Flag Ready

   for removal
2. 2
   Daily Sync
3. 3
   Query

   LD + code refs
4. 4
   Filter & Validate
5. 5
   Cleanup PR

The SaaS LD-sync is a scheduled Lambda that polls LaunchDarkly once per day for flags marked "ready for code removal" and automatically creates cleanup PRs in your GitHub repositories.

Prerequisites

1. LaunchDarkly Code References — Must be set up and running in your repositories. Without them, FlagShark cannot determine which repos contain each flag.
2. API access token — Reader role or higher, with access to your LD project.
3. FlagShark Workspace — With the GitHub repositories you want to clean up.

Setting Up the Connection

Getting an API Access Token for the Dashboard

Connection Settings

Setting	Description	Default
API access token	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

Before creating a cleanup PR, FlagShark verifies the flag is OFF in all critical environments. This prevents removing flags that are still serving live traffic.

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.

Excluded Maintainers and Repository Filtering

If certain flag maintainers should be excluded from automatic cleanup, or if you want to restrict (or exclude) specific repositories, configure these options in the dashboard connection form. They are stored in the FlagShark database alongside the connection — not in .flagshark.yml.

• Excluded maintainers — Flag maintainer emails to skip (e.g., a platform team that manages flags manually)
• Repositories — Allowlist of repository names to create PRs in; if empty, all repos in your GitHub org are eligible
• Excluded repos — Repository names to always skip, even if they have code references to the flag

Multiple Projects

You can connect multiple LaunchDarkly projects to a single workspace:

Each project connection operates independently with its own settings.

---

How the Daily Sync Works

Sync Schedule

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

1. Fetch ready flags — Query LD for flags with staleState: readyForCodeRemoval via GET /api/v2/flags/{project}?filter=staleState:readyForCodeRemoval
2. Get code references — Determine which repos contain each flag via GET /api/v2/code-refs/statistics/{project}
3. Filter flags — Check critical environments, excluded maintainers, and repository filters
4. Queue for cleanup — Send eligible flags to the cleanup processor
5. Track processed — Record processed flags in the flagshark-ld-processed DynamoDB table to prevent duplicate PRs

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 access 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 (check the flagshark-ld-processed tracking table)
3. Excluded maintainer — Flag maintainer is in the exclusion list (configured in the dashboard)
4. No code references — LD Code References not set up for the repo
5. Repository not tracked — Repo not included in FlagShark workspace or is in the excluded repos list

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 in the dashboard
• Check your subscription is active (Team plan or higher required)
• Review AWS CloudWatch logs for errors (Enterprise only)

CLI: Token Not Found

LAUNCHDARKLY_API_TOKEN not set

• Export the env var before running flagshark scan, or set it in your CI secrets
• To use a different variable name, set token_env: MY_CUSTOM_VAR in the platforms.launchdarkly block of .flagshark.yml

---

Best Practices

Workflow Integration

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

Flag Lifecycle

1. 1
   Created
2. 2
   Dev & Rollout
3. 3
   100% Enabled
4. 4
   Mark for Removal
5. 5
   Cleanup PR
6. 6
   Merge

Security Recommendations

1. Use service account tokens — Not personal tokens
2. Minimum permissions — Reader role is sufficient for both integrations
3. Rotate tokens periodically — Update in the dashboard (SaaS) or re-export the env var (CLI)
4. Review PRs before merging — Don't auto-merge cleanup PRs

---

API Reference

The SaaS LD-sync uses these LaunchDarkly 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