Conflict Detection

Overview

When multiple people work on the same Kodexa environment — some editing resources in the UI and others pushing changes from YAML files — conflicts can occur. The CLI uses sync state files to detect when a resource on the server has changed since your last pull. This prevents accidental overwrites where one person’s changes silently replace another’s, giving you the chance to review and merge before pushing.

How It Works

Each time you run kdx sync pull, the CLI records the changeSequence of every fetched resource in a state file at .sync-state/<env>.yaml. When you later run kdx sync push, the CLI compares the stored sequence against the server’s current value:

Stored state	Server state	What happens
No entry (never pulled)	Any	Pushes normally — no baseline to compare
Sequences match	Same	Pushes normally — no server-side changes
Sequences differ	Changed	Conflict — resource skipped with warning
Entry exists	Resource deleted	Pushes normally — recreates the resource

Example Conflict Output

When a conflict is detected, you will see a warning like:

⚠️  CONFLICT data-definition/freight-agents — server changeSequence is 15
    but was 12 when last pulled on 2026-04-08. Skipping (use --force to overwrite)

The resource is skipped, and all other non-conflicting resources continue to be pushed normally.

The `--force` Flag

Use --force to push conflicted resources anyway, overwriting server-side changes:

kdx sync push --target my-org --env dev --force

Using --force overwrites any changes made to the resource on the server since your last pull. Always review conflicts before force-pushing.

Sync State Files

State files are stored at .sync-state/<env>.yaml in your repository root, one per environment:

# Auto-generated by kdx sync — do not edit manually
schemaVersion: "1.0"
environment: dev4
url: https://dev4.kodexacloud.com
organization: my-org
resources:
  datadefinition/freight-agents:
    changeSequence: 12
    pulledAt: "2026-04-08T20:00:00Z"
  dataform/accessorial:
    changeSequence: 7
    pulledAt: "2026-04-08T20:00:00Z"
  tasktemplate/freight-agents/freight-document-pack:
    changeSequence: 3
    pulledAt: "2026-04-08T20:00:00Z"

Commit state files to git. This allows your team to share the same baseline — if one person pulls and commits the state file, others will get conflict detection even without pulling themselves.

Recommended Workflow

For teams where some users edit resources in the Kodexa UI while others manage YAML files:

# 1. Pull latest state from the environment
kdx sync pull --target my-org --env dev
git add .sync-state/ kodexa-resources/
git commit -m "Sync from dev: $(date)"

# 2. Make your YAML changes
vim kodexa-resources/data-definitions/invoice-data.yaml

# 3. Dry-run to check for conflicts before pushing
kdx sync push --target my-org --env dev --dry-run

# 4. If no conflicts, push
kdx sync push --target my-org --env dev

# 5. If conflicts detected, re-pull to get latest, then merge
kdx sync pull --target my-org --env dev
# Review changes, resolve any differences in YAML files
kdx sync push --target my-org --env dev

Environment Name Resolution

The state file name is derived from the environment:

--env dev4 creates .sync-state/dev4.yaml
--to-url https://dev4.kodexacloud.com creates .sync-state/dev4.kodexacloud.com.yaml
--to-profile myprofile derives the name from the profile’s URL

This means each environment’s state is tracked independently — a conflict on dev4 has no effect on pushes to staging.

Getting Started

Core Operations

Sync & GitOps

Operational Commands

Document Commands

Overview

How It Works

Example Conflict Output

The `--force` Flag

Sync State Files

Recommended Workflow

Environment Name Resolution

​Overview

​How It Works

​Example Conflict Output

​The --force Flag

​Sync State Files

​Recommended Workflow

​Environment Name Resolution

Overview

How It Works

Example Conflict Output

The `--force` Flag

Sync State Files

Recommended Workflow

Environment Name Resolution