> ## 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.
# kdx sync: GitOps for Kodexa Metadata and Resources
> Manage Kodexa Activity Plans, data definitions, data forms, modules, project templates, project bindings, and other metadata with kdx sync.
**Automating with GitHub Actions?** Use the official [kdx-sync-action](https://github.com/kodexa-ai/kdx-sync-action). See the [CI/CD Integration guide](/guides/kdx-cli/sync/ci-cd).
## 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
```text theme={null}
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:
```yaml theme={null}
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, 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.
```bash theme={null}
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
Build the first metadata repository.
Define environments, targets, branch mappings, and tag mappings.
Learn manifest shape and current resource names.
See command flags and operational behavior.
Understand sync state and stale-write protection.
Automate deployments from GitHub Actions and other CI systems.