Git Sync

API workflows are part of a codebase. They change when the endpoints change, they differ between branches, and they are worth reviewing. Git Sync exists so a Space can live next to the project it describes, in a format Git can actually read.

There is no server and no hosted workspace involved. Lumen Flow writes files to a folder on your Mac; the version control is your own.

One entity, one small file

A synced Space is mirrored to a folder with a predictable layout:

<folder>/
├─ lumen-sync.json
├─ space.json
├─ flows/<name>__<id>.json
├─ profiles/<name>__<id>.json
└─ auth/<name>__<id>.json

Each flow, profile, and credential is its own JSON file. Renaming a Flow changes the filename, but the identity of the record is the id inside the file — the name is there so diffs stay readable.

Because the unit is one small file per entity, a pull request shows what actually changed: a header added to one call, a validation rule tightened, a profile variable renamed. Not a single opaque blob rewritten from top to bottom.

Two-way, and additive by design

Sync runs in both directions:

• App to disk · when you change something in Lumen Flow, the folder is rewritten shortly afterwards, batching rapid edits together.
• Disk to app · a watcher notices when the files change underneath you, which is what happens after a git pull or a branch switch, and reads them back in.

Reading back in is not the same as importing a collection. Collection import always creates new items; Git Sync uses the same internal identifiers that are already in the files, so it updates the records you have instead of duplicating them on every round trip. There are also manual controls to force an export or a re-read from disk when you want to be explicit about it.

Secrets stay out of the folder

By default, secret values are not written to the synced folder. Where a secret would go, the file carries a redaction marker instead, and the real value stays in the macOS Keychain.

If you do need secrets to travel with the Space — across your own machines, for instance — you can set a vault passphrase for it. Secrets are then written as encrypted envelopes rather than plain text, and the passphrase itself stays in the local Keychain and is never written to the folder. Without the passphrase, the encrypted values cannot be read back.