kdx sync: GitOps for Kodexa Metadata and Resources

Automating with GitHub Actions? Use the official kdx-sync-action. See the CI/CD Integration guide.

What Sync Is For

kdx sync turns Kodexa metadata into a version-controlled repository. Use it when a project is larger than a one-off CLI change and the configuration should be reviewed, promoted, and repeatable. Use sync for:

Activity Plans and triggers
Task templates and task statuses
Data definitions and data forms
Project templates and project resource bindings
Modules and prompt templates
Service Bridges
Knowledge types, features, sets, and project knowledge items
Labels, intakes, document stores, and data stores

Command Flow

Command	Direction	Use it for
`kdx sync pull`	Platform -> files	Download configured resources into the metadata repository
`kdx sync pull --discover`	Platform -> manifest + files	Discover resources and merge them into manifests before pulling
`kdx sync push`	Files -> platform	Push local metadata changes to one environment
`kdx sync deploy`	Files -> platform	Deploy targets selected by branch, tag, or explicit flags

Repository Layout

project-root/
├── sync-config.yaml
├── .sync-state/
│   ├── dev.yaml
│   └── prod.yaml
├── manifests/
│   ├── shared.yaml
│   └── finance.yaml
└── kodexa-resources/
    ├── activity-plans/
    │   └── invoice-intake.yaml
    ├── data-definitions/
    │   └── invoice-data.yaml
    ├── data-forms/
    │   └── invoice-review.yaml
    ├── document-stores/
    │   └── invoice-documents.yaml
    ├── modules/
    │   └── invoice-extractor/
    │       └── module.yml
    ├── service-bridges/
    │   └── finance-erp.yaml
    ├── task-templates/
    │   └── invoice-review.yaml
    ├── task-statuses/
    │   ├── in-review.yaml
    │   └── approved.yaml
    ├── project-templates/
    │   └── invoice-processing.yaml
    └── projects/
        ├── invoice-processing.yaml
        └── invoice-processing/
            ├── knowledge-items/
            │   └── vendor-rules.yaml
            ├── triggers/
            │   └── intake-starts-activity.yaml
            └── project-links.yaml

Configuration Layers

sync-config.yaml answers three questions:

Question	Config section	Example
Where can this repo deploy?	`environments`	`dev`, `qa`, `prod` URLs and API key env vars
What resource sets can be deployed?	`targets`	`finance`, `claims`, `shared` manifests
When should targets deploy?	`branch_mappings`, `tag_mappings`	`main -> dev`, `release/* -> prod`

Minimal example:

schema_version: "2"
environments:
  dev:
    url: https://dev.kodexa.com
    api_key_env: KODEXA_DEV_API_KEY
    api_version: v2
targets:
  finance:
    organization: acme-finance
    manifests:
      - manifests/finance.yaml
branch_mappings:
  - pattern: main
    target: finance
    environment: dev

Organization Resources

Organization resources are reusable building blocks:

Activity Plans
Data Definitions
Data Forms
Document Stores
Data Stores
Modules
Prompt Templates
Service Bridges
Knowledge Item Types
Knowledge Feature Types
Knowledge Feature Instances
Knowledge Sets
Labels
Intakes
Task Templates
Task Statuses
Project Templates
Projects

Task templates and task statuses are organization-level resources in the Activity model. Projects bind the ones they use through project-resource links.

Project Resources

Project folders contain resources and bindings that make a specific project runnable:

Project metadata
Project resource links
Triggers
Project knowledge items
Project-specific knowledge sets when used

An Activity Plan usually lives at the organization level. A project binding says that the project is allowed to run it with that project’s document stores, task templates, data definitions, forms, users, and integrations.

Push Ordering

kdx sync push and kdx sync deploy push resources in dependency order. For example:

Labels
Core organization resources such as data definitions, data forms, document stores, data stores, modules, prompts, and Service Bridges
Knowledge type definitions
Knowledge feature instances
Intakes and Activity Plans
Project templates and projects
Task templates, task statuses, and knowledge sets
Project-scoped bindings, triggers, workflows, and workspaces when present

This ordering lets references resolve when project templates or project bindings point at shared resources.

Conflict Detection

Sync records server state in .sync-state/. Commit those files so the next push can detect when the server changed after your last pull.

kdx sync pull --target finance --env dev
git add kodexa-resources .sync-state manifests sync-config.yaml
git commit -m "Pull finance metadata"

kdx sync push --target finance --env dev --dry-run

Use --force only when you intentionally want local files to overwrite server-side changes.

Next Steps

Getting Started

Build the first metadata repository.

Configuration

Define environments, targets, branch mappings, and tag mappings.

Manifests & Resource Types

Learn manifest shape and current resource names.

Pull, Push & Deploy

See command flags and operational behavior.

Conflict Detection

Understand sync state and stale-write protection.

CI/CD Integration

Automate deployments from GitHub Actions and other CI systems.

Getting Started

Core Operations

Sync & GitOps

Operational Commands

Document Commands

kdx sync: GitOps for Kodexa Metadata and Resources

What Sync Is For

Command Flow

Repository Layout

Configuration Layers

Organization Resources

Project Resources

Push Ordering

Conflict Detection

Next Steps

Getting Started

Configuration

Manifests & Resource Types

Pull, Push & Deploy

Conflict Detection

CI/CD Integration

​What Sync Is For

​Command Flow

​Repository Layout

​Configuration Layers

​Organization Resources

​Project Resources

​Push Ordering

​Conflict Detection

​Next Steps

Getting Started

Configuration

Manifests & Resource Types

Pull, Push & Deploy

Conflict Detection

CI/CD Integration

What Sync Is For

Command Flow

Repository Layout

Configuration Layers

Organization Resources

Project Resources

Push Ordering

Conflict Detection

Next Steps