Mirror Profiles

A mirror profile is a connection profile for an environment you only push configuration to, such as staging or production. You author configuration against one profile, usually the development one, and replicate it outward. The tracked files stay the single source of truth for every environment.

Before starting, make sure you have a configuration directory with at least one profile. For more information, see the Configuration Directory page.

The Problem Mirrors Solve

The goal is that the configuration in version control is identical for every environment. Promoting a change then becomes a low-risk operation: you switch profile and apply the same files. Anything that must differ between environments belongs in the profile, which carries the cluster URL, the credentials, and the mapping from project directory to project identifier. Treat divergence in the tracked files as a warning sign.

Two things get in the way of that goal:

• Record identifiers differ between instances

  A pull records the identifier of each workflow and source it downloads. Those identifiers exist only on the instance they came from, so an apply that matches on them finds nothing on a second instance and creates duplicates instead of updating what is there.

• A pull against the wrong environment overwrites the shared files

  Every profile shares one set of tracked files. Pulling while a staging or production profile is active replaces those files with that one environment’s state, which is the opposite of what promotion needs.

Marking a profile as a mirror addresses both.

What the Mirror Flag Changes

• Apply matches records by name

  config apply and config validate match by name rather than by identifier, which is the same behavior as passing --apply-by-name. Each run reports which profile it is treating as a mirror, so you can confirm from the output that the profile is set up as intended. Where two records on the target share a name, the run reports an error rather than guessing.

• Pull asks for confirmation first

  config pull warns that pulling on a mirror overwrites the shared files with that environment’s data, and waits for confirmation. The pull is not blocked, so pass --yes for a non-interactive run.

An explicit --apply-by-name or --no-apply-by-name on the command line overrides the profile flag either way.

Everything else behaves the same. Deletions stay off unless you pass --allow-deletion, and an apply still shows the difference and asks for confirmation.

Mark a Profile as a Mirror

squirro profile create is the only command that asks the mirror question. The squirro init wizard does not, so the profile it creates is never a mirror, which is correct: that is the one you author on. Create the mirror profiles for your other environments afterward.

squirro profile create prod

The command explains what a mirror profile is, then asks Is this an apply-only (mirror) profile?. Answer no for the profile you author configuration on, and yes for every environment you replicate to.

Note

The question defaults to yes as soon as one profile already exists in that scope, on the assumption that the first profile you create is the one you author on and every later one is a mirror. It is only a default, so answer no where that does not hold.

The command then works through the project directories it finds under projects/, asking for each whether to connect it to a project on that instance and, if so, for the project identifier. An empty identifier leaves that directory unconnected and the command moves on to the next one. When nothing ends up connected, it offers to name one more directory, defaulting to the profile name, before reporting that no project is connected. Add a mapping later with squirro project create.

The profile list marks which profiles are mirrors.

squirro profile list

The flag is stored as "mirror": true in the profile JSON file. No command changes it after creation, so to convert an existing profile, edit .squirro/profiles/<name>.json, or ~/.squirro/profiles/<name>.json for a user-scoped profile.

The Promotion Workflow

Author on the primary profile, then replicate outward without pulling.

1. Run squirro --profile dev config pull to start from the state of the development instance.

2. Edit the tracked files.

3. Run squirro --profile dev config apply to push the change to development.

4. Run squirro --profile staging config apply to replicate it outward, with no pull in between.

5. Run squirro --profile prod config apply to replicate it to production.

Preview any of those with config apply --dry-run, or with config validate, which resolves record matching from the profile the same way and therefore previews the apply it is describing.

Important

Never run config pull against a mirror profile as part of this loop. The pull would replace the tracked files with that environment’s state and lose the configuration you are promoting. That is what the confirmation prompt exists to catch.

Setting Up a New Environment

To bring a new instance under the same configuration:

1. Create a profile for it with squirro profile create, answering yes to the mirror question.

2. Connect each project directory to a project on that instance when the command asks, or register them later with squirro project create <folder> <project-id> --profile <name>.

3. Run squirro --profile <name> connection to confirm the credentials work.

4. Preview with squirro --profile <name> config apply --dry-run, then apply.

The new environment then matches the tracked configuration, and later changes reach it with a single apply.

Next Steps

For the full set of configuration commands and their options, see the Main Commands page.