Sync Configuration

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:

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

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 — this is convenient for local development where you already have profiles configured.

Targets (WHAT)

Targets bundle an organization with its manifests:

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:

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)

NEW in v0.5.0: Deploy using git tags in addition to branches with tag_mappings.

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

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

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.

Complete Example

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

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`)

Getting Started

Core Operations

Sync & GitOps

Operational Commands

Document Commands

Configuration Architecture

Environments (WHERE)

Targets (WHAT)

Branch Mappings (WHEN)

Tag Mappings (WHEN)

Complete Example

Configuration Reference

​Configuration Architecture

​Environments (WHERE)

​Targets (WHAT)

​Branch Mappings (WHEN)

​Tag Mappings (WHEN)

​Complete Example

​Configuration Reference

Configuration Architecture

Environments (WHERE)

Targets (WHAT)

Branch Mappings (WHEN)

Tag Mappings (WHEN)

Complete Example

Configuration Reference