Feature Flags How-to Guides#

Practical tasks for configuring and managing feature flags.

Configure Helm for feature flags#

Set up Helm values to inject Unleash configuration into your deployments.

1. Add configuration to values.yaml#

# charts/your-app/values.yaml
unleash:
  url: "https://gitlab.com/api/v4/feature_flags/unleash/<PROJECT_ID>"
  appName: "your-app-name"
  environment: "development"
  refreshInterval: 15
  idSecretName: "your-app-unleash-id"
  idSecretKey: "unleash-instance-id"

Replace <PROJECT_ID> with your GitLab project ID.

2. Create a VaultStaticSecret for the Instance ID#

# templates/unleash-secret.yaml
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
  name: unleash-secret
spec:
  type: kv-v2
  mount: dev
  path: skao-team-system/your-app
  destination:
    name: unleash-secrets
    create: true

3. Inject environment variables in your deployment template#

env:
  - name: UNLEASH_URL
    value: {{ .Values.unleash.url | quote }}
  - name: UNLEASH_APP_NAME
    value: {{ .Values.unleash.appName | quote }}
  - name: UNLEASH_ENVIRONMENT
    value: {{ .Values.unleash.environment | quote }}
  - name: UNLEASH_REFRESH_INTERVAL
    value: {{ .Values.unleash.refreshInterval | quote }}
  - name: UNLEASH_INSTANCE_ID
    valueFrom:
      secretKeyRef:
        name: {{ .Values.unleash.idSecretName }}
        key: {{ .Values.unleash.idSecretKey }}

4. Deploy with Helm#

make k8s-install-chart
# or
make k8s-upgrade-chart

Get GitLab feature flag credentials#

Retrieve the credentials needed to connect to GitLab Feature Flags.

  1. Open your project in GitLab

  2. Navigate to Deploy → Feature flags

  3. Click Configure to view credentials

  4. Copy the following values:

    • API URL — Use as UNLEASH_URL

    • Instance ID — Use as UNLEASH_INSTANCE_ID

    • Application name — Use as UNLEASH_APP_NAME

Store the Instance ID securely in Vault, not in code or configuration files.

Check a feature flag in Python#

Basic flag check#

if client.is_enabled("my-feature-flag"):
    # New behaviour
    do_new_thing()
else:
    # Original behaviour
    do_original_thing()

With fallback function#

Always provide a fallback for when the application cannot reach the Unleash server:

is_enabled = client.is_enabled(
    "my-feature-flag",
    fallback_function=lambda: False
)

With user context#

Pass context for user-specific targeting:

context = {"userId": "user@example.com"}
is_enabled = client.is_enabled("user-targeted-flag", context)

Check a feature flag in React#

Basic flag check#

import { useFlag } from '@unleash/proxy-client-react';

const MyComponent = () => {
  const isEnabled = useFlag('my-feature-flag');

  return isEnabled ? <NewFeature /> : <OriginalFeature />;
};

Get feature variant#

import { useVariant } from '@unleash/proxy-client-react';

const MyComponent = () => {
  const variant = useVariant('my-feature-flag');

  if (variant.name === 'blue') {
    return <BlueVersion />;
  }
  return <DefaultVersion />;
};

Check multiple flags#

import { useFlags } from '@unleash/proxy-client-react';

const MyComponent = () => {
  const flags = useFlags(['flag-one', 'flag-two']);
  // flags.flagOne, flags.flagTwo
};

Create a feature flag in GitLab#

  1. Open your project in GitLab

  2. Navigate to Deploy → Feature flags

  3. Click New feature flag

  4. Enter the flag name (use naming conventions)

  5. Add a description

  6. Configure strategies:

    • All users — Enable for everyone

    • Percent rollout — Enable for a percentage of users

    • User IDs — Enable for specific users

    • User list — Enable for a predefined user group

  7. Set the environment scope (e.g., production, staging)

  8. Click Create feature flag

Remove a feature flag#

Once you fully roll out and stabilize a feature, remove the flag to reduce complexity.

1. Remove flag checks from code#

Delete all is_enabled or useFlag calls for the flag:

# Before
if client.is_enabled("my-feature"):
    do_new_thing()
else:
    do_old_thing()

# After
do_new_thing()

2. Remove old code paths#

Delete the code that handled the disabled state.

3. Deploy the changes#

Push the updated code through CI/CD.

4. Delete the flag from GitLab#

  1. Navigate to Deploy → Feature flags

  2. Find your flag

  3. Click the delete button

  4. Confirm deletion

Handle Unleash client errors#

Wrap client initialisation in try/except:

try:
    self.unleash_client = UnleashClient(
        url=os.environ["UNLEASH_API_URL"],
        app_name=os.getenv("UNLEASH_ENVIRONMENT", "development"),
        instance_id=os.environ["UNLEASH_INSTANCE_ID"],
        disable_metrics=True,
    )
    self.unleash_client.initialize_client()
except Exception as e:
    logger.error("Error initialising feature toggler: %s", e)
    # Fall back to default behaviour

Always use fallback_function when checking flags:

# Returns False if client fails or flag doesn't exist
is_enabled = client.is_enabled(
    "my-flag",
    fallback_function=lambda: False
)

Override flags for testing#

Bypass the Unleash server for local development or testing.

Environment variable override#

Set UNLEASH_INACTIVE to disable the client entirely:

export UNLEASH_INACTIVE=true

Mock client in tests#

from unittest.mock import Mock

mock_client = Mock()
mock_client.is_enabled.return_value = True

# Inject mock into your code under test
my_service._feature_toggler = mock_client

Configure flag strategies per environment#

Use different flag configurations across data centres and environments.

Example configuration matrix:

Datacentre

Environment

Component

Flag Status

STFC

CI/Test

Component X

enabled

STFC

Staging

Subsystem A

enabled

ITF

Integration

SKA MID ITF

disabled

AA

Production

SKA MID AA

enabled

In GitLab, configure different strategies per environment scope to achieve this behaviour.