Skip to content
FlagSwiftDocs

Export and import

Move an organization's configuration out as one file and back in: to back it up, copy staging into a new server, or seed a fresh install. Importing checks the whole file first and never deletes anything.

What the file holds#

  • Projects, by key, with name, description and colour.
  • Environments, with whether each is production and whether it requires approval.
  • Segments, with members, rules and includes. A segment scoped to a project carries that project's key in project; an organization-wide one has none, and files without project are read as organization-wide. On import, a scoped segment whose project is not in the organization or the file is skipped with a warning, and an existing segment's scope is never changed.
  • Flags: type, variants, owner, removal and expiry dates, archived state, and every environment’s configuration (on or off, rollout, targeting, rules, segments, prerequisites, variant allocation).
  • Custom roles.

It leaves out everything that belongs to a running system rather than to its configuration: people and their roles, API keys and secrets, flag history and versions, audit entries, metrics, code references, releases and alert rules. Who last changed a flag, and when, is not carried either.

Exporting#

In Settings, choose Export. You need the config.export permission, which administrators have. Each export is recorded in the audit log as config.exported.

Export#

GET/api/config/export?projects=web,api

Downloads a JSON file. projects is optional and narrows it to those project keys; environments and custom roles always come along.

Authorization

config.export

Importing#

Choose a file in Settings. It is checked first and the console shows what would be created and updated, every problem found, and any warnings. Nothing changes until you press Apply import. You need config.import.

When something already exists
ModeTypeDescription
skipdefaultOnly add what is missing. Existing projects, segments, flags and roles are left exactly as they are.
overwritemodeUpdate 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.
  • Importing is all or nothing. One problem anywhere and nothing is written; on PostgreSQL, and MongoDB run as a replica set, the writes also commit together.
  • It never deletes. A flag missing from the file stays.
  • Environments are only ever created, never changed, because whether one is production or needs approval protects everyone.
  • In an environment that requires approval, existing flags are not changed and new flags arrive switched off. You get a warning saying how many.
  • A flag whose kill switch is active is left unchanged.
  • Segments, prerequisites, variants, allocations and rules are checked the way the console checks them, so a file cannot create a configuration you could not build by hand.
  • You cannot import a role with permissions you do not hold yourself.
  • The import is recorded once in the audit log as config.imported, with the counts.

Import#

POST/api/config/import
Body
FieldTypeDescription
documentobjectThe file's contents, as exported.
modestringskip (default) or overwrite.
dryRunbooleanDefaults to true: check and report without writing. Send false to apply.
Response
{
  "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": []
}

A file with problems is still a 200: errors lists each one with its path, and applied is false.

Authorization

config.import

Limits

A file can be up to 8 MB, with at most 200 projects, 5,000 flags, 2,000 segments and 25 custom roles. For larger estates, export and import project by project.