add-autogate

Adding an Autogate

Autogates enable gradual rollout of risky code changes independent of binary releases. Unlike compatibility flags (which are permanent, date-based behavioral changes), autogates are temporary gates that can be toggled on/off via internal tooling during rollout, then removed once the change is stable.

When to use an autogate vs a compat flag

Autogates and compat flags are separate mechanisms — an autogate does not become a compat flag.

Step 1: Add the enum value

Edit src/workerd/util/autogate.h. Add a new entry to the AutogateKey enum before NumOfKeys:

enum class AutogateKey {
  TEST_WORKERD,
  // ... existing gates ...
  // Brief description of what this gate controls.
  MY_NEW_FEATURE,
  NumOfKeys  // Reserved for iteration.
};

Naming convention: SCREAMING_SNAKE_CASE for the enum value.

Step 2: Add the string mapping

Edit src/workerd/util/autogate.c++. Add a case to the KJ_STRINGIFY switch before the NumOfKeys case:

kj::

Naming convention: kebab-case for the string name. This string is what appears in runtime configuration (prefixed with workerd-autogate-). The enum name and string name should match to avoid confusion.

Step 3: Guard your code

Use Autogate::isEnabled() to conditionally execute the new code path:

Step 4: Test

Three ways to test autogated code:

A. The @all-autogates test variant (automatic):

Every wd_test() and kj_test() generates a @all-autogates variant that enables all gates. If your feature is tested by existing tests, they'll automatically run with the gate enabled:

B. Targeted C++ test setup:

In a C++ test file, enable specific gates:

C. Environment variable:

Set WORKERD_ALL_AUTOGATES=1 to enable all gates when no explicit config is provided.

Step 5: Build and verify

Step 6: Remove the gate (after rollout)

Once the human user explicitly confirms that the feature is stable and fully rolled out:

1. Remove the AutogateKey enum value from autogate.h
2. Remove the case from KJ_STRINGIFY in autogate.c++
3. Remove all Autogate::isEnabled() checks, keeping only the new code path

Checklist

• Enum value added to AutogateKey in autogate.h (before NumOfKeys)
• Comment describes what the gate controls
• String mapping added to KJ_STRINGIFY in autogate.c++
• Code guarded with Autogate::isEnabled()
• Old code path preserved (for rollback)
• @all-autogates test variant passes
• Tests cover both gated and ungated paths

Files touched