> ## 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.

# Sync Configuration

> Configure environments, sync targets, and deployment mappings in sync-config.yaml for GitOps workflows on the Kodexa AI Platform with kdx sync.

## Configuration Architecture

The sync system uses a **three-tier architecture** to separate concerns:

| Tier                      | Purpose                                  | Question it answers |
| ------------------------- | ---------------------------------------- | ------------------- |
| **Environments**          | Deployment locations with authentication | **WHERE** to deploy |
| **Targets**               | Organization + manifest bundles          | **WHAT** to deploy  |
| **Branch & Tag Mappings** | Git-based automation rules               | **WHEN** to deploy  |

This separation lets you mix and match environments, targets, and triggers independently — for example, deploying the same target to different environments based on which branch or tag is active.

## Environments (WHERE)

Environments define deployment target locations with authentication:

```yaml theme={null}
environments:
  dev:
    url: https://dev.kodexa-enterprise.com
    api_key_env: KODEXA_DEV_API_KEY

  staging:
    url: https://staging.kodexa-enterprise.com
    api_key_env: KODEXA_STAGING_API_KEY

  prod:
    url: https://platform.kodexa-enterprise.com
    api_key_env: KODEXA_PROD_API_KEY

  # Alternative: use a kdx CLI profile for authentication
  local-dev:
    url: https://dev.kodexa-enterprise.com
    profile: dev-profile
```

<Note>
  API keys are **never stored** in configuration files. They're referenced via environment variables for security. Alternatively, use `profile` to authenticate with a named [kdx CLI profile](/guides/kdx-cli/profiles-configuration) — this is convenient for local development where you already have profiles configured.
</Note>

## Targets (WHAT)

Targets bundle an organization with its manifests:

```yaml theme={null}
targets:
  shared:
    organization: acme-shared
    manifests:
      - manifests/shared.yaml

  division-a:
    organization: acme-division-a
    manifests:
      - manifests/shared.yaml      # Can reuse shared resources
      - manifests/division-a.yaml  # Plus division-specific
```

Targets let you group resources logically. A single target can reference multiple manifest files, and the same manifest can appear in multiple targets — making it easy to share common resources across divisions or teams.

## Branch Mappings (WHEN)

Branch mappings automate deployment based on git branches:

```yaml theme={null}
branch_mappings:
  # Production: deploy all targets
  - pattern: "main"
    targets:
      - target: shared
        environment: prod
      - target: division-a
        environment: prod

  # Staging: deploy for testing
  - pattern: "release/*"
    targets:
      - target: shared
      - target: division-a
    environment: staging

  # Development: division-specific
  - pattern: "feature/div-a/*"
    target: division-a
    environment: dev
```

Each mapping has a `pattern` that matches against the current git branch. When a match is found, the specified targets are deployed to their associated environments.

## Tag Mappings (WHEN)

<Note>
  **NEW in v0.5.0**: Deploy using git tags in addition to branches with `tag_mappings`.
</Note>

Tag mappings work the same way as branch mappings but trigger on git tags instead of branches. This is especially useful for release workflows:

```yaml theme={null}
tag_mappings:
  # Release tags deploy to production
  - pattern: "v*"
    targets:
      - target: shared
        environment: prod
      - target: division-a
        environment: prod

  # Release candidates deploy to staging
  - pattern: "rc-*"
    targets:
      - target: shared
      - target: division-a
    environment: staging

  # Beta tags deploy to dev
  - pattern: "beta-*"
    target: development
    environment: dev
```

<Note>
  You can use both `branch_mappings` and `tag_mappings` in the same configuration. When using `--tag` or `--branch` flags, automatic git detection is overridden with your specified value.
</Note>

## Complete Example

A full `sync-config.yaml` combining all three tiers:

```yaml theme={null}
schema_version: "2.0"

# WHERE: Define deployment environments
environments:
  dev:
    url: https://dev.kodexa-enterprise.com
    api_key_env: KODEXA_DEV_API_KEY

  staging:
    url: https://staging.kodexa-enterprise.com
    api_key_env: KODEXA_STAGING_API_KEY

  prod:
    url: https://platform.kodexa-enterprise.com
    api_key_env: KODEXA_PROD_API_KEY

# WHAT: Define deployment targets
targets:
  shared:
    organization: acme-shared
    manifests:
      - manifests/shared.yaml

  division-a:
    organization: acme-division-a
    manifests:
      - manifests/shared.yaml
      - manifests/division-a.yaml

# WHEN: Define branch-based automation
branch_mappings:
  - pattern: "main"
    targets:
      - target: shared
        environment: prod
      - target: division-a
        environment: prod

  - pattern: "release/*"
    targets:
      - target: shared
      - target: division-a
    environment: staging

  - pattern: "feature/div-a/*"
    target: division-a
    environment: dev

# WHEN: Define tag-based automation (NEW in v0.5.0)
tag_mappings:
  - pattern: "v*"  # Any version tag (e.g., v1.0.0, v2.0)
    targets:
      - target: shared
        environment: prod
      - target: division-a
        environment: prod

  - pattern: "rc-*"  # Release candidates
    targets:
      - target: shared
      - target: division-a
    environment: staging
```

## Configuration Reference

| Option            | Description                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| `schema_version`  | Config format version (currently `"2.0"`)                                                        |
| `environments`    | Map of environment name to URL and API key environment variable (or profile)                     |
| `targets`         | Map of target name to organization slug and manifest files                                       |
| `branch_mappings` | List of git branch patterns with deployment rules                                                |
| `tag_mappings`    | List of git tag patterns with deployment rules (NEW in v0.5.0, same syntax as `branch_mappings`) |