Skip to content
FlagSwiftDocs

Move configuration between servers

Copy an organization's projects, flags and segments to another server, or keep a backup, by exporting one file and importing it after a check.

Time
About 12 min
Who can do it
Admins (config.export to export, config.import to import)
Where
Settings, Export and import
You finish with
The same configuration on a second server, or a backup file

What and why#

Export and import move an organization's configuration as one JSON file. Use it to seed a new server from staging, to take a backup before a risky change, or to move to a different deployment. Importing always checks the whole file first and shows you what would change before anything is written.

Configuration, not state#

The file holds the things you would otherwise build by hand: projects, environments, segments, flags with every environment's configuration, and custom roles. It leaves out everything that belongs to a running system: people and their roles, API keys, flag history, audit entries, metrics, code references, releases and alert rules.

Safe by design#

The import is a dry run until you apply it, it is all or nothing, and it never deletes. A second import of the same file reports nothing to change, so you can run it repeatedly.

Before you start#

  • You need the config.export permission on the source and config.import on the target. Administrators have both. The Settings panel shows only the half you hold.
  • Know what travels. The file holds projects, environments, segments, flags with every environment's configuration, and custom roles.
  • Know what does not. People and their roles, API keys, flag history, audit entries, metrics, code references, releases and alert rules stay behind, so create keys on the target yourself.
  • On the target, the projects you import into must not be archived, and the environments the flags use must exist there or be in the file.

Walk through it#

  1. Export from the source

    Open Settings, find Export and import and press Export. You get a JSON file named flagswift-config-YYYY-MM-DD.json with everything in the organization. The export is recorded in the audit log as config.exported. The file is marked as format flagswift.config, version 1.

    The Export and import panel on a signed-in Admin's Settings page. Each half shows only if you hold that permission.
    You should see. Your browser downloads the file. It opens as readable JSON with projects, environments, segments, flags and roles lists.
  2. Choose the file on the target

    On the target server open the same panel and press Choose file. The file is checked straight away and nothing is written. The panel lists, for each of projects, environments, segments, flags and roles, how many would be new, updated or unchanged, plus any problems in red and warnings in grey.

  3. Pick how to treat what already exists

    When something already exists
    ChoiceAPI modeDescription
    Keep what is hereskip (default)Only adds what is missing. Existing projects, segments, flags and roles are left exactly as they are.
    Replace with the fileoverwriteUpdates existing projects, segments, flags and roles to match the file. A flag's type cannot change. Things the file does not mention are left alone.
    The dry-run report after choosing a file. Apply import stays off while there are problems in red or nothing to change.

    Changing the choice re-checks the file, so the counts always match what Apply will do.

  4. Apply it

    When the report shows the changes you expect and no problems, press Apply import and confirm Apply this import?. The button stays off while the file has problems or there is nothing to change. The import is recorded once in the audit log as config.imported with the counts.

    You should see. A Configuration imported message appears. Choosing the same file again reports nothing to change.

Do it with the API

Send the same body with "dryRun": false to apply. The export file is not wrapped in the usual envelope: it is the document itself. A file with problems is still a 200 with errors and nothing changed. See Export and import.

Request
# The Dashboard API acts as a signed-in person: POST /api/auth/login first (keep the cookie).
# 1. Export (config.export). "projects" is optional and narrows it to those project keys.
curl -s -b jar.txt -o flagswift-config.json \
  "https://flags.example.com/api/config/export?projects=web,api"

# 2. Dry run on the target (config.import). dryRun defaults to true.
jq -n --slurpfile doc flagswift-config.json \
  '{document: $doc[0], mode: "skip", dryRun: true}' |
curl -s -b jar-target.txt -X POST https://target.example.com/api/config/import \
  -H "Content-Type: application/json" --data @-
Response to the dry run
{
  "status": "success",
  "message": "Checked. Nothing was changed.",
  "data": {
    "applied": false,
    "dryRun": true,
    "mode": "skip",
    "summary": {
      "projects":     { "create": 1, "update": 0, "skip": 0 },
      "environments": { "create": 0, "update": 0, "skip": 3 },
      "segments":     { "create": 2, "update": 0, "skip": 0 },
      "flags":        { "create": 14, "update": 0, "skip": 0 },
      "roles":        { "create": 0, "update": 0, "skip": 0 }
    },
    "errors": [],
    "warnings": []
  }
}

Apply the import

Check the dry run first and apply only when errors is empty. A request body over 8 MB is refused with a 400 saying The file is too large. The limit is 8 MB. before the file is read. When a file has problems the message reads The file has problems. Nothing was changed.

Request
jq -n --slurpfile doc flagswift-config.json \
  '{document: $doc[0], mode: "skip", dryRun: false}' |
curl -s -b jar-target.txt -X POST https://target.example.com/api/config/import \
  -H "Content-Type: application/json" --data @-
Response when applied
{
  "status": "success",
  "message": "Configuration imported",
  "data": { "applied": true, "dryRun": false, "mode": "skip", "errors": [], "warnings": [] }
}

Rules to know#

  • Importing is all or nothing. One problem anywhere and nothing is written.
  • It never deletes. A flag that is not in the file stays where it is.
  • Environments are only created, never changed, because production and approval settings protect everyone.
  • In an environment that requires approval, existing flags are not changed and new flags arrive switched off. You get a warning with the count.
  • A flag whose kill switch is active is left unchanged, and a flag's type cannot change.
  • You cannot import a role with permissions you do not hold, or a role that allows production changes if you cannot make them yourself.
  • A file can be up to 8 MB, with at most 200 projects, 50 environments, 5,000 flags, 2,000 segments and 25 custom roles. For larger estates, export and import project by project with the API's projects filter.

Scripting it

The same flow is available over HTTP. POST /api/config/import takes dryRun, which defaults to true, so you must send false to write. Console API calls need a signed-in session, not an API key.

Good to know#

Take a backup before you replace

Replace with the file overwrites existing flags, segments, projects and roles with the file's version, and an import is hard to undo. Export the target first so you have the previous state in a file.

Do the keys last

Keys do not travel. Import first, then create an API key on the target for each app, update the apps to use them, and only then switch traffic over.
Can I export just one project in the console?
The console exports the whole organization. To narrow it to some projects, call the export endpoint with ?projects=key1,key2. Environments and custom roles always come along.
Will flag history come across?
No. Flag history and versions are not part of the file.
Can I import into an organization that already has flags?
Yes. With Keep what is here only missing items are added. With Replace with the file, items that exist in both are updated and everything not in the file is left alone.
Is the export safe to store?
It holds no keys, passwords or people, but it does hold your flag configuration and targeting lists, so store it as you would your config files.

If something goes wrong#

That file is not valid JSON

Why: The file was edited or truncated, or is not an export.

Fix: Export again, or restore the original file.

This is not a FlagSwift configuration file, or Unsupported version

Why: The file does not have format flagswift.config, or it has a version this server does not read (this one reads version 1).

Fix: Use a file exported from FlagSwift, and upgrade the target if it is older than the source.

Project is not in the file or this organization / Configures environment which is not in this organization or the file

Why: A flag points at a project or environment that does not exist on the target.

Fix: Re-export with the project and environments included, or create the environment on the target first. Environments in the file are created for you.

Is a boolean flag here and a string flag in the file

Why: A flag with the same key has a different type on the target, and a flag's type cannot change.

Fix: Rename or archive the flag on one side, then import again.

Apply import is greyed out

Why: The report has problems, or there is nothing to change.

Fix: Fix the problems listed in red. If the report says nothing to change, the target already matches the file.

The file is too large

Why: The file is over 8 MB, or has more projects, flags, segments or roles than the limits allow.

Fix: Export and import project by project.

What to check#

  • Import the same file again as a check. It should report nothing to change.
  • Open a few flags on the target and compare their rollout and targeting with the source.
  • Find the config.exported and config.imported entries in the audit log.
  • Create API keys for the target and update your apps to use them.