Star
Start here

Flags in git

Keep flag definitions in your repo, reviewed in a pull request. Whether a flag is on, and who it targets, stays with whoever is on call.

export default {
        project: { key: "acme", name: "Acme" },
        environment: { key: "development", name: "Development" },
        flags: [
          {
            key: "new-checkout",
            name: "New checkout flow",
            kind: "boolean",
            clientAvailable: true,
            tags: ["checkout"],
            variations: [{ name: "off", value: false }, { name: "on", value: true }],
            config: {
              enabled: true,
              offVariation: "off",
              fallthroughRollout: {
                variations: [{ variation: "on", weight: 10_000 }, { variation: "off", weight: 90_000 }],
              },
              targets: [{ variation: "on", keys: ["u-ana", "qa-bot"] }],
            },
          },
          {
            key: "promo-banner",
            name: "Promo banner",
            kind: "string",
            variations: [{ name: "none", value: "" }, { name: "sale", value: "Upgrade and save 10%" }],
            config: { enabled: false, offVariation: "none", fallthroughVariation: "sale" },
          },
        ],
      };
import { FeaturekitServer } from "featurekit-server";
      import flags from "./flags.js";

      await new FeaturekitServer({ flags }).start();

What happens on start

The flag…featurekit…
doesn't exist yetCreates it and applies its config.
already existsLeaves its configuration alone. Name, description, tags and variations are updated from the file.
exists, with flagsReset: trueRe-applies config, overwriting whatever was changed in the dashboard.

The project and environment are created if they don't exist. Every change goes through the same validation as the API and lands in the audit log under a config-as-code actor.

Why existing flags are left alone

Someone turns a flag off at 3am during an incident. If every boot re-applied the file, the next deploy would turn it back on, at the moment nobody is watching. Definitions are code; operational state is not.

The file

FieldNotes
project{ key, name }
environment{ key, name, isProduction?, color? }. One per file.
flags[]Up to 1,000. The same fields as creating a flag, plus config.
configThe same fields as a configuration change, minus expectedVersion.

In the file, a variation can be named ("on") instead of indexed (1), anywhere a variation is expected: offVariation, fallthroughVariation, targets, rules and rollout slices. Weights are out of 100,000.

Development and production

flags is a development convenience: a fresh checkout and a fresh database give the same flags. In production start() refuses it, because applying definitions is a deploy step, not something every booting node should do. Create flags from CI with the admin API and a scoped token instead.

flagsReset: true (or FEATUREKIT_FLAGS_RESET=1) re-applies every flag's config on the next start. Use it to reset a development database, not by default.

Next