Skip to main content

​
Configuration Architecture

The sync system uses a three-tier architecture to separate concerns:
TierPurposeQuestion it answers
EnvironmentsDeployment locations with authenticationWHERE to deploy
TargetsOrganization + manifest bundlesWHAT to deploy
Branch & Tag MappingsGit-based automation rulesWHEN 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

OptionDescription
schema_versionConfig format version (currently "2.0")
environmentsMap of environment name to URL and API key environment variable (or profile)
targetsMap of target name to organization slug and manifest files
branch_mappingsList of git branch patterns with deployment rules
tag_mappingsList of git tag patterns with deployment rules (NEW in v0.5.0, same syntax as branch_mappings)