Configuration

FlagShark works out of the box with default configurations for popular feature flag providers. For custom setups or advanced use cases, you can create a .flagshark.yaml configuration file in your repository root.

Configuration File

Create a .flagshark.yaml file in the root of your repository:

# .flagshark.yaml
version: 1

# Custom provider configurations
providers:
  - name: "LaunchDarkly Go SDK"
    package_path: "github.com/launchdarkly/go-server-sdk/v7"
    import_aliases: ["ld", "launchdarkly"]
    methods:
      - name: "BoolVariation"
        flag_key_index: 0
        context_index: 1
        min_params: 3

Provider Configuration

Provider Structure

Each provider has the following properties:

providers:
  - name: "Provider Name"           # Display name for this provider
    package_path: "import/path"     # Package import path to match
    import_aliases: ["alias"]       # Common import aliases
    methods:                        # Methods that evaluate flags
      - name: "methodName"
        flag_key_index: 0           # Position of flag key argument
        context_index: 1            # Position of context/user argument
        min_params: 2               # Minimum number of parameters

Method Configuration

Property	Description	Required
name	Method name to detect	Yes
flag_key_index	Zero-based index of the flag key parameter	Yes
context_index	Zero-based index of the context parameter	No
min_params	Minimum number of parameters for valid call	No
default_value_index	Index of the default value parameter	No

Example: LaunchDarkly Go

providers:
  - name: "LaunchDarkly Go SDK"
    package_path: "github.com/launchdarkly/go-server-sdk/v7"
    import_aliases: ["ld", "launchdarkly", "ldclient"]
    methods:
      - name: "BoolVariation"
        flag_key_index: 0
        context_index: 1
        default_value_index: 2
        min_params: 3
      - name: "StringVariation"
        flag_key_index: 0
        context_index: 1
        default_value_index: 2
        min_params: 3
      - name: "IntVariation"
        flag_key_index: 0
        context_index: 1
        default_value_index: 2
        min_params: 3
      - name: "Float64Variation"
        flag_key_index: 0
        context_index: 1
        default_value_index: 2
        min_params: 3
      - name: "JSONVariation"
        flag_key_index: 0
        context_index: 1
        default_value_index: 2
        min_params: 3

Example: Unleash

providers:
  - name: "Unleash"
    package_path: "github.com/Unleash/unleash-client-go/v3"
    import_aliases: ["unleash"]
    methods:
      - name: "IsEnabled"
        flag_key_index: 0
        min_params: 1
      - name: "GetVariant"
        flag_key_index: 0
        min_params: 1

Example: Custom Internal SDK

providers:
  - name: "ACME Feature Flags"
    package_path: "github.com/acme/feature-flags"
    import_aliases: ["ff", "features", "featureflags"]
    methods:
      - name: "IsEnabled"
        flag_key_index: 0
        min_params: 1
      - name: "GetValue"
        flag_key_index: 0
        default_value_index: 1
        min_params: 2
      - name: "GetVariant"
        flag_key_index: 0
        context_index: 1
        min_params: 2

Multiple Providers

You can configure multiple providers in one file:

version: 1

providers:
  # LaunchDarkly for backend
  - name: "LaunchDarkly Server"
    package_path: "github.com/launchdarkly/go-server-sdk/v7"
    methods:
      - name: "BoolVariation"
        flag_key_index: 0
        min_params: 3

  # Unleash for experiments
  - name: "Unleash"
    package_path: "github.com/Unleash/unleash-client-go/v3"
    methods:
      - name: "IsEnabled"
        flag_key_index: 0
        min_params: 1

  # Internal wrapper
  - name: "ACME Flags"
    package_path: "github.com/acme/flags"
    methods:
      - name: "Check"
        flag_key_index: 0
        min_params: 1

Language-Specific Examples

TypeScript/JavaScript

providers:
  - name: "LaunchDarkly React"
    package_path: "launchdarkly-react-client-sdk"
    import_aliases: ["ld", "launchdarkly"]
    methods:
      - name: "useFlags"
        flag_key_index: -1  # Special: extracts keys from destructuring
      - name: "variation"
        flag_key_index: 0
        min_params: 2

Python

providers:
  - name: "LaunchDarkly Python"
    package_path: "ldclient"
    import_aliases: ["ld", "launchdarkly"]
    methods:
      - name: "variation"
        flag_key_index: 0
        context_index: 1
        default_value_index: 2
        min_params: 3
      - name: "bool_variation"
        flag_key_index: 0
        context_index: 1
        min_params: 3

Rust

providers:
  - name: "LaunchDarkly Rust"
    package_path: "launchdarkly_server_sdk"
    import_aliases: ["ld", "launchdarkly"]
    methods:
      - name: "bool_variation"
        flag_key_index: 1  # After &self
        min_params: 3
      - name: "string_variation"
        flag_key_index: 1
        min_params: 3

Global Settings

Control detection behavior across all providers:

version: 1

global_settings:
  enable_fallback_detection: true    # Detect flags even without matching imports
  strict_import_matching: false      # Require exact import path matching
  detect_in_comments: false          # Skip flag-like strings in comments
  detect_in_strings: true            # Detect flags in string literals

Global Settings Reference

Setting	Default	Description
enable_fallback_detection	true	When enabled, FlagShark attempts to detect flag patterns even when it can't match the import to a known provider. Useful for custom or wrapper libraries.
strict_import_matching	false	When enabled, requires exact package path matching. Disable for more flexible detection with aliased imports.
detect_in_comments	false	When enabled, detects flag names mentioned in code comments. Usually disabled to avoid false positives.
detect_in_strings	true	When enabled, detects flag keys passed as string literals. Required for most SDK patterns.

Example: Strict Mode

For high-precision detection with minimal false positives:

version: 1

global_settings:
  enable_fallback_detection: false
  strict_import_matching: true
  detect_in_comments: false
  detect_in_strings: true

Example: Broad Detection

For maximum coverage, including custom wrappers:

version: 1

global_settings:
  enable_fallback_detection: true
  strict_import_matching: false
  detect_in_comments: false
  detect_in_strings: true

Advanced Configuration

Excluding Directories

Exclude directories from analysis:

version: 1

exclude:
  - "vendor/"
  - "node_modules/"
  - "*.test.ts"
  - "**/__tests__/**"
  - "dist/"
  - "build/"

Exclude Patterns

Use glob patterns to exclude files:

exclude:
  - "**/*.test.ts"        # All test files
  - "**/*.spec.js"        # All spec files
  - "**/mocks/**"         # Mock directories
  - "scripts/**"          # Scripts directory

Include Only Specific Paths

Limit analysis to specific directories:

include:
  - "src/**"
  - "lib/**"
  - "packages/*/src/**"

Validation

Validate Your Configuration

FlagShark validates your configuration when processing PRs. If there's an issue, you'll see an error in the PR comment:

⚠️ Configuration Error in .flagshark.yaml

Line 12: Invalid method configuration
  - 'flag_key_index' must be a non-negative integer

Testing Configuration Locally

Test your configuration before pushing:

# Validate configuration syntax
flagshark validate .flagshark.yaml

# Test detection with your config
flagshark scan --config .flagshark.yaml src/

Configuration Precedence

FlagShark uses configuration in this order:

1. Repository .flagshark.yaml - Highest priority
2. Organization defaults - Set in FlagShark dashboard
3. FlagShark built-in defaults - For common providers

Organization Defaults

Set organization-wide defaults in your FlagShark dashboard:

Inheriting Organization Config

In your repository, inherit and extend organization config:

version: 1

# Inherit all organization defaults
inherit: true

# Add repository-specific providers
providers:
  - name: "Repo-Specific SDK"
    package_path: "github.com/myteam/flags"
    methods:
      - name: "isEnabled"
        flag_key_index: 0

Common Configurations

Monorepo Setup

For monorepos with different flag providers per package:

version: 1

# Root config applies to all packages
providers:
  - name: "Shared Flags"
    package_path: "@company/feature-flags"
    methods:
      - name: "isEnabled"
        flag_key_index: 0

# Package-specific overrides
packages:
  - path: "packages/web"
    providers:
      - name: "LaunchDarkly React"
        package_path: "launchdarkly-react-client-sdk"
        methods:
          - name: "useFlags"
            flag_key_index: -1

  - path: "packages/api"
    providers:
      - name: "LaunchDarkly Node"
        package_path: "launchdarkly-node-server-sdk"
        methods:
          - name: "variation"
            flag_key_index: 0

Test File Handling

Configure how test files are handled:

version: 1

# Exclude test files from flag tracking
exclude:
  - "**/*.test.ts"
  - "**/*.spec.ts"
  - "**/__tests__/**"

# Or include them but mark as test usage
test_patterns:
  - "**/*.test.ts"
  - "**/*.spec.ts"

Troubleshooting Configuration

Config Not Being Used

If your configuration isn't being applied:

Flags Not Detected

If flags aren't detected with custom config:

Related Documentation

• Supported Languages - Default language support
• Flag Detection - How detection works
• Flag Not Detected - Detection troubleshooting