Common Workflows

These workflows cover most day-to-day use of Environment Sync: promoting changes to production (all of them, or just the ones that are ready), starting to use sync on a project that already exists, undoing a bad push, re-aligning an environment after manual changes, and standing up a new environment from the committed files. The concepts behind each step live in How It Works; every flag in Reference.

Promote changes from development to production

You model in the Data Studio on a development instance. Production only ever receives what git has reviewed.

1. Make your changes on the development instance: collections, fields, flows, permissions.
2. Pull them into the repository and commit:

   d6s sync pull --from dev
   git add directus/
   git commit -m "Add author bio fields"
   

   
   The files are deterministic, so the commit shows your change and nothing else. On a development instance other people also use, a scoped pull (--collections posts, or a resource flag like --flows) keeps their in-progress work out of your diff.
3. Open a pull request. Reviewers read the change as plain JSON diffs. A CI check can add the target's view of the same change:

   d6s sync diff --to production --json
   

4. On merge, apply:

   d6s sync push --to production --yes
   

   
   The default merge mode creates and updates but never deletes. A second run reports nothing to push.

Promote only the changes that are ready

A shared development or staging instance usually carries more than one piece of work at a time. Say the posts changes are ready to ship, and half-finished authors changes are not. Scope the pull to what ships:

d6s sync pull --from staging --collections posts

What that pull just did:

• The posts schema files were rewritten with the new state.
• The authors schema files were not touched. They still hold what the last full pull captured, which is the state production already runs. The half-finished authors work never entered the repository.
• Configuration resources refreshed too, because a collections scope only narrows schema. Nothing changed there, so those files came back byte-identical and git status shows only the posts files. If a flow had also changed on staging, its file would show up here; hold it back with --no-flows on the pull. One thing you cannot hold back on its own: the ride-along resources. Permissions travel with policies and operations with flows, and they have no --no- flags of their own, so a teammate's new permission rows come along with any pull that refreshes policies.

Commit, then diff and push as usual:

git add directus/
git commit -m "Add post fields"
d6s sync diff --to production
d6s sync push --to production

A push always applies the whole committed folder. The posts change applies. The authors files already match production, so nothing happens there. And since the unfinished authors work is not in the repository, it cannot ship, no matter what state staging is in.

For a configuration-only change, flip the scope: select the resource type and skip schema.

d6s sync pull --from staging --flows --no-schema

The What a pull touches table shows exactly which files each combination refreshes and which it leaves alone.

Adopt Environment Sync on an existing project

Most projects don't start from an empty instance. You have a development instance, a production instance, and months of changes applied to each by hand. Here's how to get from that to a synced setup.

1. Decide which instance is closest to the state you want everywhere. Usually that's production: it's the environment you've been careful with.
2. Pull it as your baseline and commit:

   d6s profile add production --url https://cms.example.com   # offers to save a credential; or pass --token
   d6s sync pull --from production
   git add directus/ directus.config.json
   git commit -m "Baseline from production"
   

3. See how far each other environment has drifted:

   d6s profile add staging --url https://staging.example.com
   d6s sync diff --to staging
   

   
   The first diff on a long-lived pair of instances can be long. Read it as an inventory of drift, not a to-do list: everything listed is a place where staging and production genuinely disagree, accumulated over however long the two were maintained by hand.
4. Bring the environment in line gradually. A merge push adds and updates what staging is missing without deleting anything, so staging-only experiments survive:

   d6s sync push --to staging
   

   
   Once nothing on staging is worth keeping outside the committed files, a mirror push finishes the job and makes it match exactly.
5. Expect a few identity questions on the first push. Staging and production often hold records that are plausibly the same one (two roles named "Editor", two flows built from the same template). The CLI asks instead of guessing; answer once, then commit the updated id_map.json. The questions do not come back.

From then on, the project runs the promote workflow: change on dev, pull, review, push.

Roll back a bad push

A change made it to production and turned out to be wrong. The committed files are the record of every state production has been in, so rollback is a git operation followed by a push. One asymmetry matters:

• If the bad change modified something, reverting the commit and pushing with merge restores the old values.
• If the bad change added something, merge cannot undo it: after the revert, the field or record is simply absent from your files, and merge never deletes what the files don't mention. Removal is a deletion, and deletions need mirror.

Say the bad commit added a summary field and a notification flow, and tweaked the note on articles.title. Revert it, then preview the undo in mirror mode (the default merge preview plans no deletions, so it cannot show you a removal):

git revert <bad-commit>
d6s sync diff --to production --mode mirror

● Comparing committed files with production — https://cms.example.com (mirror — INCLUDES DELETIONS)
● Schema — 2 changes: 0 added, 1 modified, 1 deleted
✖ DELETE  field articles.summary
~         field articles.title (meta.note)
● Data — 1 change: 0 created, 0 updated, 1 deleted
~ directus_flows  +0 new  ~0 updated  ✖1 deleted (f7)

The ~ line restores the old note. The ✖ DELETE and ✖1 deleted lines are the undo, and they should name exactly what the bad change added, and nothing else. If anything else shows up for deletion, your files are stale somewhere: stop, run a full pull from production on a scratch branch, read that diff to see what production actually holds, and fold anything worth keeping into your files before mirroring.

d6s sync push --to production --mode mirror

The push repeats the plan, then the deletion gate demands typed consent:

This push permanently deletes 1 record and 1 schema item from production. Type "production" to confirm:

In automation, the same push requires --dangerously-allow-delete instead.

When the bad change is tangled up with good ones, fixing forward is often simpler than reverting: correct it on the development instance, pull, and promote the fix like any other change.

Rebase an environment from production after drift

Sometimes production changes outside the deployment path, usually an urgent manual fix. Staging and the repository no longer reflect reality. Bring the fix into git, then re-align the lower environment. This is what mirror is for: making an environment match the committed state exactly.

1. Pull the full state from production. The manual change appears as an ordinary git diff, which is your record of what the hotfix actually was:

   d6s sync pull --from production
   git diff
   git add directus/
   git commit -m "Adopt production hotfix"
   

2. Preview what re-aligning staging would mean:

   d6s sync diff --to staging --mode mirror
   

   
   Read the deletions closely. Anything that exists only on staging and falls inside the sync's scope is on the list. (The mode matters: a default merge preview plans no deletions, so only a mirror diff shows what re-aligning would remove.)
3. Make staging match the committed state:

   d6s sync push --to staging --mode mirror
   

   
   Interactively, the push names the losses and asks you to type the profile name; in automation it requires --dangerously-allow-delete. See deletion gates.

Stand up a new environment

Going from an empty instance to a working copy of your project's shape:

1. Provision a fresh Directus instance and create its admin account as usual.
2. Add a profile for it:

   d6s profile add staging --url https://staging.example.com --token <token>
   

3. Preview, then push the committed files:

   d6s sync diff --to staging
   d6s sync push --to staging
   

   
   Schema applies first, then the configuration records import.
4. Commit the updated id_map.json. The push records which target record each committed record became, and that map is how every later push updates records instead of duplicating them.

Things to expect on a first push:

• Identity questions. If the target already holds records the CLI cannot tell apart from the committed ones (two policies named "Administrator" is the classic case), an interactive push asks you to choose. Answer once, commit the map, and the questions do not come back. See record identity.
• Secrets stay behind. Stripped values (API keys in settings, concealed fields, flow credentials) never travel with the files. Set them on the new instance directly.