Roll out to a percentage of users

This guide shows you how to release a feature gradually — for example to 10% of sites first, then 50%, then 100% — using feature flags.

Prerequisites

• The server-side SDK is installed: npm install @forge/feature-flags@latest
• You have a flag created in Developer Console. If not, see Your first feature flag.

Step 1: Choose your targeting unit

Before writing any code, decide what you're rolling out to: sites or users.

Rolling out by site is simpler — all users in a site get the same experience. Rolling out by user allows finer control but means different users in the same site may see different behaviour.

Step 2: Create the flag with the right ID type

When creating the flag in Developer Console:

1. Go to your app → Manage → Feature flags → Create flag
2. Set the ID type to match your choice:
   • installContext for site-level rollouts
   • accountId for user-level rollouts
3. Note the auto-generated Flag ID — you'll use this in code

Step 3: Add the flag check to your resolver

Rolling out by site (installContext)

1
2
import { FeatureFlags } from "@forge/feature-flags";

resolver.define('getFeature', async ({ context }) => {
  const featureFlags = new FeatureFlags();
  await featureFlags.initialize({
    environment: context?.environmentType?.toLowerCase() || "development"
  });

  const user = {
    identifiers: {
      installContext: context?.installContext,
    },
    attributes: {
      installContext: context?.installContext,
    }
  };

  const isEnabled = featureFlags.checkFlag(user, "my-feature-flag", false);
  featureFlags.shutdown();
  return isEnabled;
});

Rolling out by user (accountId)
1
2
import { FeatureFlags } from "@forge/feature-flags";

resolver.define('getFeature', async ({ context }) => {
  const featureFlags = new FeatureFlags();
  await featureFlags.initialize({
    environment: context?.environmentType?.toLowerCase() || "development"
  });

  const user = {
    identifiers: {
      accountId: context?.principal?.accountId,
    },
    attributes: {
      accountId: context?.principal?.accountId,
    }
  };

  const isEnabled = featureFlags.checkFlag(user, "my-feature-flag", false);
  featureFlags.shutdown();
  return isEnabled;
});

Step 4: Configure the rollout percentage in Developer Console

Go to your flag in Developer Console → Setup
Set Pass to your initial rollout percentage (for example, 10)
Set Fail to the remainder (90)
Check the environments you want to activate this for
Click Save

The SDK randomly assigns each installContext or accountId to pass or fail based on these percentages. The assignment is consistent — the same site or user always gets the same result for a given percentage configuration.
Step 5: Increase the rollout over time
To widen the rollout, update the percentage in Developer Console:

Go to your flag → Setup
Increase Pass (for example, from 10 to 50)
Click Save

The change takes effect within 60 seconds for existing instances of the server-side SDK (its polling interval). The client SDK picks up the new configuration on next initialization.
 

Percentage updates are manual — there's no automated time-based progression. See Limitations for details.
 
Step 6: Complete the rollout
Once you're confident in the feature, set Pass to 100% and Fail to 0%. At this point, the flag is effectively permanent — you can clean it up:

Remove the checkFlag call from your code
Delete the flag from Developer Console
Deploy your updated code

Related

Target specific users or organizations — Instead of a percentage, enable for specific people or sites
Use environment-specific flags — Control which environments the rollout applies to
Core concepts — Understand ID types and evaluation