User guide

This guide is for anyone who will use Switchyard: product managers, testers, support staff, or developers new to feature flags. No coding knowledge is needed for most of it. Where a developer has to do something, it says so.

Contents

1. What Switchyard is
2. What it can do for you
3. Words you'll see
4. How it works, in one picture
5. Getting started, step by step
6. Everyday recipes
7. What happens when things go wrong
8. Questions people ask
9. What it can't do yet
10. For developers

#1. What Switchyard is

Think of your app as a house, and every new feature as a room with a light switch. Switchyard is the switchboard for those lights.

Developers build a new feature and put it into the app switched off. Nobody sees it yet. Later, anyone with access to the Switchyard dashboard can switch it on: for everyone at once, only for your own team, only for some countries, or for a small share of users first. No new release of the app is needed, and the change reaches running apps within about a second.

These switches are called feature flags.

The name comes from a railway switchyard, where switches decide which track each train takes. Switchyard decides which version of a feature each user gets.

#2. What it can do for you

#3. Words you'll see

#4. How it works, in one picture

   You, in the dashboard                  Switchyard server
  ┌──────────────────────┐   changes   ┌─────────────────────┐
  │ "New checkout: On    │ ──────────▶ │ stores the settings │
  │  for 10% of users"   │             │ and tells apps      │
  └──────────────────────┘             └─────────┬───────────┘
                                                 │ within ~1 second
                       ┌─────────────────────────┼─────────────────────────┐
                       ▼                         ▼                         ▼
                 ┌───────────┐             ┌───────────┐             ┌───────────┐
                 │ Your app  │             │ Your app  │             │ Your app  │
                 │ (server 1)│             │ (server 2)│             │ (server 3)│
                 └───────────┘             └───────────┘             └───────────┘
     Each app keeps a copy of the settings and answers "is this on for this user?"
     itself, instantly, without asking Switchyard every time.

Two things make it safe and fast:

• Apps keep their own copy. Checking a flag takes well under a millionth of a second and never waits on the network. If Switchyard goes down, apps carry on with the copy they have.
• Changes are pushed. Switchyard tells connected apps the moment something changes, so they fetch the new settings straight away.

#5. Getting started, step by step

Someone technical needs to run the Switchyard server first (locally, or on the internet for free). They'll give you the server address (a web address like https://flags.example.com), and either add your GitHub username to the allowed list or give you the admin token.

#Step 1: Sign in

1. Open the dashboard in your browser.
2. Server URL: the server address you were given. Once it's filled in, a Continue with GitHub button appears if the server offers GitHub sign-in.
3. Either click Continue with GitHub (GitHub may ask you to allow Switchyard the first time), or type the Admin token and click Sign in.

If you see "That GitHub account isn't allowed on this server", ask whoever runs Switchyard to add your GitHub username. "The server rejected that admin token." means the token is wrong. "Couldn't reach the server": check the address, and ask whoever runs the server to allow the dashboard's address (it's a setting on their side).

You stay signed in until you close the browser tab, or choose Sign out from the round account button at the top right (GitHub sign-ins also end after 12 hours). The button next to it switches between light and dark.

#Step 2: Create a project

1. On the Projects page, click New project, and type a Name, for example Shop. The Key fills itself in (shop).
2. Click Create.
3. A box appears with one SDK key for Development and one for Production.
4. Click the copy button next to each and pass them to your developers (in a password manager, not by email or chat).
5. Click I've saved them.

These keys are shown only this once. Switchyard doesn't store them in readable form. If they're lost, you can make new ones (see Replace a leaked SDK key), but apps using the old ones then stop getting updates until they have the new ones.

#Step 3: Your developers connect the app

A developer adds the SDK key to the app and wraps the new feature in a check, roughly "if new-checkout is on, show the new checkout". This is a one-time job per feature. The details are in For developers.

#Step 4: Create a flag

1. Click your project's card. The menu on the left now shows the project's Flags, Segments, History, Changes and Settings.
2. Click New flag, and type a Name, for example New checkout. The Key fills itself in (new-checkout). Tell your developers this key: it must match the one in the code exactly.
3. Click Create.

The flag appears in the table, Off in every environment. New flags always start off, so creating one never changes anything for users.

#Step 5: Switch it on

In the flags table, each environment has a switch. Click it to turn the flag on or off there. The label next to the switch sums up what users get, for example On, Off, or 1 rule · else 10% rollout. With many flags, use the search box above the table.

Connected apps get the change within about a second.

#Step 6: Choose who gets it (optional)

Click the flag's row to open its page. There's a tab for each environment (Production opens first). In a tab:

• The switch at the top turns the flag on or off in that environment.

• Rules pick out groups of users. Click Add rule and fill in the sentence:

  • If [attribute] [condition] [values]. The conditions come in groups: text (is one of, starts with, ends with, contains, matches pattern), numbers (is less than, is at least, …), versions (is version, is a version before, …), dates (is before, is after) and segments (is in segment, is not in segment).
  • Then serve On, Off, or Rollout (a slider and a box for the percentage). For a flag with variations: one Variation, or a Split with a percentage for each (they must add up to 100%).

  Attribute is a piece of information about the user that your developers send, such as email, country or plan. Ask them which ones your app sends. Type each value and press Enter (or a comma): each becomes a tag you can remove with its ✕. Pasting IN, SG makes two tags.

• Add condition adds another line to the same rule. A rule only matches when all its lines match.

• Rules are checked from the top. The first one that matches decides. Use the ↑ and ↓ buttons to reorder.

• Everyone else decides for users no rule picked out.

• Prerequisites (above the rules) let a flag depend on another: "Only if New checkout gives On". Until it does, everyone gets this flag's off value.

• For a flag with variations, When off, serve (next to the switch) picks the variation everyone gets while it's off.

As soon as you change something, a bar appears at the bottom: Unsaved changes in Production, with Discard and Save. You can edit both tabs and save them together. If you try to leave the page with unsaved changes, the dashboard asks first.

#Step 7: Check what happened

Click History in the menu on the left. Each line says who did what and when (hover over the time for the exact date). Click Show details to see the settings before and after.

Made a mistake? Click Undo on that line and confirm. The flag goes back to how it was before that change, apps get it within about a second, and the undo shows up in History too, so it can be undone in turn.

#6. Everyday recipes

#Try a feature with your own team first

1. Open the flag, pick the Production tab, and switch it On.
2. Add rule: If email ends with @yourcompany.com then serve On.
3. Everyone else: Off.
4. Save. Only people with your company email see it.

(Comparisons are exact, capital letters included. Ask developers to send emails in lowercase so Someone@YourCompany.com still matches.)

#Release to more and more users

1. Keep your team's rule from the recipe above, if you like.
2. Set Everyone else to Rollout and drag the slider (or type) to 10. Save.
3. Watch for problems. When happy, change it to 50, then 100.

The same 10% stay in when you go up to 50%, so nobody sees the feature appear and disappear.

#Different behaviour in different countries

Add rule: If country is one of IN, SG then serve On. Everyone else: Off. (Your app must send country; ask your developers which codes it uses.)

#Emergency: switch something off now

In the project's flags table, click the flag's switch for Production so it shows Off. That's it. Off beats every rule, so within about a second nobody gets the feature. Your rules are kept, so switching it back on restores exactly what you had.

#Retire a flag

When a feature is fully released and the developers have removed the check from the code, open the flag, click the ⋮ button at the top right, and choose Archive flag. It disappears everywhere. If any app still checks it, that app gets the default value written in its code. Its history is kept.

#Replace a leaked SDK key

If an SDK key was shared by mistake:

1. Click Settings in the menu on the left, then Rotate next to that environment, and confirm.
2. Copy the new key from the box that appears, then click I've saved them.
3. Give the new key to your developers.

The old key stops working immediately. Apps still using it keep their last settings but receive no further changes until they're given the new key.

#Offer a choice instead of on/off

1. New flag, and under What it serves pick Text (or Number, or JSON).
2. Type the variations, for example green, blue, orange. When switched on, a new flag serves the first; while off, the last.
3. Open the flag. Under Everyone else, pick Split and set, say, 50% green and 50% orange, to compare them.

Your developers read the value with stringVariation("checkout-button", user, "green") (or the number and JSON versions).

#Use a flag in a web page

1. Open the flag and switch on Available to browsers (under its name).
2. Give your developers the environment's client-side ID from Settings. It's not secret.

The page asks Switchyard for that flag's value for the visitor, and follows changes within about a second. It can't see the flag's rules or any flag not made available to browsers.

#Target the same group from many flags

1. Click Segments in the menu on the left, then New segment, for example Beta testers.
2. Under Always in, type user keys. Under Also anyone who matches, add rules like "email ends with @yourcompany.com". Never in keeps people out whatever the rules say.
3. Save. In any flag, add a rule: If is in segment Beta testers then serve On.

Change the segment once and every flag using it follows. A segment can't be deleted while a flag uses it: the segment's page lists those flags.

#Require a second pair of eyes for Production

An admin opens Settings and turns on Requires approval for Production. From then on, switching a flag or saving its rules there asks for approval instead of changing anything:

1. Make the change as usual. A box asks why (optional) and whether it should apply as soon as it's approved or at a set time. Click Request approval.
2. The request shows under Waiting changes on the flag's page and under Changes in the menu.
3. Someone else who could make the change clicks Approve (or Reject). Approving applies it, in your name. You can't approve your own request, but you can Cancel it while it waits.

For targeting changes, Compare shows the rules now and the rules asked for, side by side.

#Switch something on at a set time

On the flag's page, click the clock next to an environment's switch, pick a time and click Schedule. To change rules later instead of now, edit them and click Schedule in the bar at the bottom instead of Save. The server makes the change within about 15 seconds of that time, even with nobody signed in. Scheduled changes are listed under Changes, where you can cancel them.

#Add a Staging environment

Admins: Settings → Add environment. Give it a name, and choose whether it starts with every flag off or with a copy of another environment's settings. Copy the new SDK key from the box that appears and give it to your developers. An environment that isn't protected can be deleted from the ⋮ menu on its card.

#Tell a Slack channel about changes

In Slack, create an incoming webhook for the channel and copy its URL. Then, as an admin: Settings → Add webhook, choose Slack, paste the URL and click Add webhook. Click the paper plane to send a test. From then on, every change posts a line like "alice turned on new-checkout in production".

#Let a script or CI pipeline change flags

Admins: API tokens in the menu → New token. Give it a name (History will show it), a role, and if you like a single project and an expiry date. Copy the token from the box that appears: it isn't shown again. Delete it on the same page to stop it working at once.

#7. What happens when things go wrong

#8. Questions people ask

How fast do changes reach users? Usually within a second for apps that are connected. In a test with 1,000 connected apps, all had the change within about 0.6 seconds.

Does checking flags slow the app down? No. The app answers from its own copy of the settings, in a few billionths of a second, without a network call.

Will the same user always get the same answer? Yes. For the same flag, the same user always lands in the same group, on every server and after every restart.

Can I undo a change? Yes: History, then Undo on the change. It works for switching a flag on or off, changing who gets it, and renaming. Creating or archiving a flag can't be undone from there.

Who can change flags? It depends on your role, shown in the account menu at the top right:

• Viewer: sees everything, changes nothing.
• Editor: changes flags and segments, except in protected environments.
• Admin: everything, including protected environments, projects, SDK keys and people's roles.

Production starts protected, so only admins can switch or retarget flags there; a padlock note says so on the flag's page. Admins change roles under Members and protection on the Settings page. Signing in with the admin token makes you an admin. History shows GitHub sign-ins by their username; changes made with the admin token show as "admin".

What's the difference between the admin token and an SDK key? The admin token lets a person change settings in the dashboard. An SDK key lets an app read the settings of one environment. It can't change anything. Keep both secret.

Why does my flag show On, but some users don't get the feature? When a flag is on, its rules and Everyone else decide who gets what. Check the flag's page. Rules about users only work if your app tells Switchyard who the user is, so ask your developers if a rule never seems to match.

Does a change in Development affect Production? No. Each environment has its own switch and its own rules.

#9. What it can't do yet

Switchyard is being built in phases, and these are still to come:

• Apps in languages other than Java and JavaScript (web pages and React are covered by switchyard-web).
• A hosted version. Someone runs the server for you; the deploy guide shows how to do it on free plans.
• Experiments with results: splits are there, but measuring which variation did better is up to your analytics.

See PLAN.md for the full plan.

#10. For developers

Add the Java client to your app (how), create one client when the app starts, and check flags where the feature lives:

SwitchyardClient flags = SwitchyardClient.builder(System.getenv("SWITCHYARD_SDK_KEY"))
    .baseUri("https://flags.example.com")
    .build();

// Plain on/off
if (flags.isEnabled("new-checkout", false)) {
    showNewCheckout();
}

// With rules or a percentage rollout: say who the user is
EvaluationContext user = EvaluationContext.builder(userId)      // a stable ID for this user
    .attribute("email", email.toLowerCase())
    .attribute("country", countryCode)
    .build();
if (flags.isEnabled("new-checkout", user, false)) {
    showNewCheckout();
}

The last argument (false here) is the default value: what the app uses before it has the settings, and for flags that don't exist. Pick the safe choice, usually false.

Tell the people using the dashboard which attributes your app sends (email, country, …), since rules can only match what the app provides. Rules never match a check made without a user, and percentage rollouts only include it at 100%.

In a Node.js (or Deno, Bun) server, the JavaScript client works the same way:

import { SwitchyardClient } from 'switchyard-js';

const flags = new SwitchyardClient({ sdkKey: process.env.SWITCHYARD_SDK_KEY!, baseUrl: 'https://flags.example.com' });
if (flags.isEnabled('new-checkout', { key: userId, attributes: { email: email.toLowerCase() } }, false)) {
  showNewCheckout();
}

Both libraries give the same answer for the same user. To see rules and rollouts in action, run the demo.

More: the Java client README, the JavaScript client README, the exact evaluation rules, and the admin API.

View this page's source on GitHub