Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

CommandDirectionUse it for
kdx sync pullPlatform -> filesDownload configured resources into the metadata repository
kdx sync pull --discoverPlatform -> manifest + filesDiscover resources and merge them into manifests before pulling
kdx sync pushFiles -> platformPush local metadata changes to one environment
kdx sync deployFiles -> platformDeploy 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:
QuestionConfig sectionExample
Where can this repo deploy?environmentsdev, qa, prod URLs and API key env vars
What resource sets can be deployed?targetsfinance, claims, shared manifests
When should targets deploy?branch_mappings, tag_mappingsmain -> 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:
  1. Labels
  2. Core organization resources such as data definitions, data forms, document stores, data stores, modules, prompts, and Service Bridges
  3. Knowledge type definitions
  4. Knowledge feature instances
  5. Intakes and Activity Plans
  6. Project templates and projects
  7. Task templates, task statuses, and knowledge sets
  8. Project-scoped bindings, triggers, and project resources 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.

Working with Claude Code

Use Kodexa metadata skills to author syncable configuration in Git.