Skip to main content
Automating with GitHub Actions? Use the official kdx-sync-action for zero-configuration CI/CD deployments. See the CI/CD Integration guide for complete setup instructions.

​
Overview

The kdx sync command enables GitOps workflows for Kodexa platform metadata. Store your organization and project configurations in version control, review changes through pull requests, and promote configurations across environments with confidence.

​
Key Benefits

Version Control

Track all metadata changes in Git with full history and audit trails

Code Review

Review infrastructure changes through pull requests before deployment

Multi-Environment

Promote tested configurations from dev → staging → production

Offline Validation

Validate changes locally before pushing to remote environments

​
Repository Layout

Metadata is organized under a kodexa-resources/ root directory with a hierarchical structure: 
project-root/
├── sync-config.yaml                     # Configuration: environments, targets, branch mappings
├── .sync-state/                         # Conflict detection state (commit to git)
│   ├── dev.yaml
│   └── prod.yaml
├── manifests/
│   ├── shared.yaml                     # Shared resources across divisions
│   ├── division-a.yaml                 # Division-specific resources
│   └── division-b.yaml
└── kodexa-resources/
    ├── data-definitions/
    │   ├── invoice-taxonomy.yaml
    │   └── contract-taxonomy.yaml
    ├── data-forms/
    │   ├── invoice-review.yaml
    │   └── validation-summary.yaml
    ├── data-stores/
    │   ├── document-store.yaml
    │   └── vector-store.yaml
    ├── exception-types/
    │   └── missing-field.yaml
    ├── labels/
    │   └── priority-high.yaml
    ├── knowledge-item-types/
    │   └── conditional-knowledge.yaml
    ├── knowledge-feature-types/
    │   └── text-extraction.yaml
    ├── knowledge-feature-instances/
    │   ├── ocr-extraction-prod.yaml
    │   └── fast-extraction-dev.yaml
    ├── knowledge-sets/
    │   └── invoice-instructions.yaml
    ├── modules/
    │   └── classifier-v3/
    │       └── module.yml
    ├── project-templates/
    │   └── data-extraction-starter.yaml
    ├── prompt-templates/
    │   └── invoice-analysis.yaml
    ├── service-bridges/
    │   └── external-api.yaml
    └── projects/
        ├── finance-automation.yaml       # Project definition
        └── finance-automation/
            ├── assistants/
            │   └── invoice-assistant.yaml
            ├── assistant-connections/
            │   └── store-to-invoice-assistant.yaml
            ├── task-templates/
            │   ├── review.yaml
            │   └── validation.yaml
            ├── task-statuses/
            │   ├── draft.yaml
            │   └── approved.yaml
            ├── knowledge-items/
            │   └── tax-calculation.yaml
            ├── workflows/
            │   └── invoice-pipeline.yaml
            └── project-links.yaml        # Linked taxonomies, forms, stores

​
Organization-Level Resources

These resources are shared across multiple projects:
  • Data Definitions - Classification hierarchies and metadata schemas (formerly taxonomies)
  • Data Forms - UI form configurations for task review and data entry
  • Data Stores - Document, vector, or graph storage configurations
  • Exception Types - Definitions for validation exceptions and error categories
  • Knowledge Item Types - Templates for rule definitions
  • Knowledge Feature Types - Generic capability definitions
  • Knowledge Feature Instances - Environment-specific deployments of features
  • Knowledge Sets - Collections of knowledge items for extraction guidance
  • Labels - Classification labels for organizing resources
  • Modules - ML models and custom modules for classification or extraction
  • Project Templates - Reusable project configurations for bootstrapping new projects
  • Prompt Templates - Reusable prompts for AI assistants
  • Service Bridges - External API proxy endpoints with centralized authentication

​
Project-Level Resources

Project-specific configurations nested under projects/<project-slug>/:
  • Project metadata - References to shared resources and environment mappings
  • Task Templates - Definitions for review tasks, including plan templates that orchestrate sub-tasks and execution steps
  • Task Statuses - Workflow status definitions for tasks (e.g., Draft, In Review, Approved)
  • Knowledge Items - Project-specific knowledge implementations
  • Assistants - AI assistant configurations
  • Assistant Connections - Connections between assistants and other resources (stores, tasks, channels)
  • Project Links - Links to org-level resources (taxonomies, data forms, stores) used by the project

​
What’s Next

Getting Started

Step-by-step tutorial for your first sync workflow

Configuration

Set up environments, targets, and branch mappings

Manifests & Resource Types

Define what resources to sync

Pull, Push & Discover

Sync commands and discover mode

Conflict Detection

How changeSequence prevents stale overwrites

CI/CD Integration

Automate with GitHub Actions