Resource Deployments - Kodexa Developer Portal

Deploy Kodexa resources (taxonomies, models, stores, data forms) using modern GitOps workflows with automatic validation, version control, and multi-environment promotion.

Overview

Resource deployment enables you to manage your Kodexa project configurations as code, with all the benefits of Git-based workflows:

📝 Version Control - Track all changes in Git
👥 Team Collaboration - Review changes through pull requests
🔄 Rollback - Easily revert to previous configurations
🌍 Multi-Environment - Promote changes across dev/staging/production
✅ Automated Testing - Validate before deployment

Resource Types

Kodexa supports two scopes of resources:

Organization-Level Resources

Shared across multiple projects:

Resource	Description	Example Use Case
Taxonomies	Classification hierarchies	Document types, entity categories
Stores	Storage configurations	Document stores, vector databases
Knowledge Types	Rule templates	Conditional logic definitions
Feature Types	Generic capabilities	Text extraction, OCR
Feature Instances	Environment-specific deployments	Production OCR, Dev OCR
Models	ML models	Document classifiers, extractors
Project Templates	Reusable project structures	Invoice processing template
Data Forms	UI configurations	Invoice data form

Project-Level Resources

Project-specific configurations:

Resource	Description	Example Use Case
Projects	Project metadata	Invoice automation project
Knowledge Items	Project-specific rules	US tax calculation rules
Assistants	AI assistant configs	Invoice processing assistant

Quick Start

1. Configure Environment

Set up authentication using environment variables:

# Install kdx CLI
brew install kodexa-ai/tap/kdx

# Set environment variables for production
export KODEXA_URL=https://platform.kodexa.com
export KODEXA_ACCESS_TOKEN=your-api-key

Get your API token from your Kodexa profile settings at https://platform.kodexa.com/profile

2. Pull Existing Resources

Use the kdx CLI to download your existing configuration:

# Pull from production environment
kdx sync pull --target prod --env production

This creates a kodexa-metadata/ directory with your resources:

kodexa-metadata/
├── sync-config.yaml
├── manifests/
│   └── production.yaml
└── my-org/
    ├── organization.yaml
    ├── taxonomies/
    │   └── document-classification.yaml
    ├── stores/
    │   └── document-store.yaml
    ├── feature-types/
    │   └── text-extraction.yaml
    └── models/
        └── doc-classifier-v3.yaml

3. Review Configuration

The sync creates a v2 configuration structure:

# kodexa-metadata/sync-config.yaml
version: 2
metadata_dir: kodexa-metadata

# Define deployment targets
targets:
  prod:
    url: https://platform.kodexa.com
    description: Production environment

# Define environments
environments:
  production:
    description: Production deployment

# Branch-based deployment
branch_mappings:
  - branch: main
    target: prod
    environment: production

# Resource manifests
manifests:
  - manifests/production.yaml

# kodexa-metadata/manifests/production.yaml
organizations:
  - slug: my-organization
    resources:
      - type: taxonomy
        slug: document-classification
      - type: store
        slug: document-store
      - type: featureType
        slug: text-extraction
      - type: model
        slug: doc-classifier-v3

4. Create Git Repository

# Initialize repository
git init
git add .
git commit -m "Initial Kodexa configuration"

# Push to GitHub
git remote add origin git@github.com:your-org/kodexa-config.git
git push -u origin main

5. Set Up GitHub Actions

Create .github/workflows/deploy.yml:

name: Deploy to Kodexa

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Kodexa
        uses: kodexa-ai/kdx-sync-action@v1
        with:
          kodexa-url: ${{ secrets.KODEXA_URL }}
          kodexa-token: ${{ secrets.KODEXA_TOKEN }}

6. Configure Secrets

In GitHub repository settings, add:

KODEXA_URL - Your Kodexa platform URL
KODEXA_TOKEN - Your API token

Working with Resources

Adding a New Taxonomy

Create YAML file

# kodexa-metadata/my-org/taxonomies/invoice-fields.yaml
slug: invoice-fields
name: Invoice Field Classification
description: Classify invoice document fields
version: "1.0.0"
taxons:
  - slug: vendor-info
    name: Vendor Information
    children:
      - slug: vendor-name
        name: Vendor Name
      - slug: vendor-address
        name: Vendor Address
  - slug: line-items
    name: Line Items
    children:
      - slug: description
        name: Description
      - slug: quantity
        name: Quantity
      - slug: unit-price
        name: Unit Price

Add to manifest

# kodexa-metadata/manifests/production.yaml
organizations:
  - slug: my-organization
    resources:
      - type: taxonomy
        slug: invoice-fields  # Add this

Test Locally

# Validate configuration
kdx sync deploy --target prod --env production --dry-run

Commit and Push

git add kodexa-metadata/
git commit -m "feat: add invoice field classification taxonomy"
git push

GitHub Actions Deploys

GitHub Actions automatically:

Validates the configuration
Syncs to Kodexa
Reports results

Adding a Document Store

# kodexa-metadata/my-org/stores/invoice-documents.yaml
slug: invoice-documents
name: Invoice Document Store
description: Central repository for invoice documents
type: document
configuration:
  storage_backend: s3
  retention_days: 365
  enable_versioning: true

Add to manifest:

# kodexa-metadata/manifests/production.yaml
organizations:
  - slug: my-organization
    resources:
      - type: store
        slug: invoice-documents

Adding a Feature Type

# kodexa-metadata/my-org/feature-types/ocr-extraction.yaml
slug: ocr-extraction
name: OCR Text Extraction
description: Extract text from scanned documents using OCR
version: "2.0.0"
capabilities:
  - text_extraction
  - layout_analysis
parameters:
  - name: language
    type: string
    default: "eng"
  - name: dpi
    type: integer
    default: 300

Adding a Feature Instance

# kodexa-metadata/my-org/feature-instances/ocr-prod.yaml
slug: ocr-prod
name: OCR Extraction - Production
feature_type_slug: ocr-extraction
configuration:
  language: "eng"
  dpi: 600
  enable_gpu: true
resources:
  memory: "4Gi"
  cpu: "2"
environments:
  production: true
  staging: false
  development: false

Sync Configuration

The sync-config.yaml defines deployment targets, environments, and resource manifests using the v2 format:

Basic Configuration

# kodexa-metadata/sync-config.yaml
version: 2
metadata_dir: kodexa-metadata

# Deployment targets
targets:
  prod:
    url: https://platform.kodexa.com
    description: Production Kodexa instance

# Environments
environments:
  production:
    description: Production deployment

# Resource manifests
manifests:
  - manifests/production.yaml

Multi-Environment Configuration

# kodexa-metadata/sync-config.yaml
version: 2
metadata_dir: kodexa-metadata

# Define multiple targets
targets:
  dev:
    url: https://dev.kodexa.com
    description: Development environment
  staging:
    url: https://staging.kodexa.com
    description: Staging environment
  prod:
    url: https://platform.kodexa.com
    description: Production environment

# Define environments
environments:
  development:
    description: Development deployment
  staging:
    description: Staging deployment
  production:
    description: Production deployment

# Branch-based deployment
branch_mappings:
  - branch: main
    target: prod
    environment: production
  - branch: staging
    target: staging
    environment: staging
  - branch: develop
    target: dev
    environment: development

# Different manifests per environment
manifests:
  - manifests/development.yaml
  - manifests/staging.yaml
  - manifests/production.yaml

Manifest Composition

Organize resources across multiple manifest files:

# kodexa-metadata/sync-config.yaml
manifests:
  - manifests/shared-taxonomies.yaml
  - manifests/shared-stores.yaml
  - manifests/production-features.yaml
  - manifests/production-models.yaml

# kodexa-metadata/manifests/shared-taxonomies.yaml
organizations:
  - slug: my-organization
    resources:
      - type: taxonomy
        slug: document-classification
      - type: taxonomy
        slug: invoice-fields

# kodexa-metadata/manifests/production-features.yaml
organizations:
  - slug: my-organization
    resources:
      - type: featureType
        slug: ocr-extraction
      - type: featureInstance
        slug: ocr-prod

Multi-Environment Deployment

Deploy the same configuration to multiple environments using branch mappings:

Branch-Based Strategy

Configure automatic deployment based on Git branches:

# kodexa-metadata/sync-config.yaml
version: 2
metadata_dir: kodexa-metadata

targets:
  dev:
    url: https://dev.kodexa.com
  staging:
    url: https://staging.kodexa.com
  prod:
    url: https://platform.kodexa.com

environments:
  development:
    description: Dev environment
  staging:
    description: Staging environment
  production:
    description: Production environment

branch_mappings:
  - branch: develop
    target: dev
    environment: development
  - branch: staging
    target: staging
    environment: staging
  - branch: main
    target: prod
    environment: production

Workflow:

develop branch → dev.kodexa.com (development)
staging branch → staging.kodexa.com (staging)
main branch    → platform.kodexa.com (production)

GitHub Actions for Multi-Environment

# .github/workflows/multi-environment.yml
name: Multi-Environment Deploy

on:
  push:
    branches:
      - main
      - staging
      - develop

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set environment variables
        run: |
          if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
            echo "KODEXA_TARGET=prod" >> $GITHUB_ENV
            echo "KODEXA_ENVIRONMENT=production" >> $GITHUB_ENV
          elif [[ "${{ github.ref }}" == "refs/heads/staging" ]]; then
            echo "KODEXA_TARGET=staging" >> $GITHUB_ENV
            echo "KODEXA_ENVIRONMENT=staging" >> $GITHUB_ENV
          else
            echo "KODEXA_TARGET=dev" >> $GITHUB_ENV
            echo "KODEXA_ENVIRONMENT=development" >> $GITHUB_ENV
          fi

      - name: Deploy to ${{ env.KODEXA_ENVIRONMENT }}
        run: |
          export KODEXA_URL=${{ secrets[format('KODEXA_{0}_URL', env.KODEXA_TARGET)] }}
          export KODEXA_ACCESS_TOKEN=${{ secrets[format('KODEXA_{0}_TOKEN', env.KODEXA_TARGET)] }}
          kdx sync deploy --target ${{ env.KODEXA_TARGET }} --env ${{ env.KODEXA_ENVIRONMENT }}

Manual Environment Deployment

Deploy to specific environments locally:

# Deploy to development
export KODEXA_URL=https://dev.kodexa.com
export KODEXA_ACCESS_TOKEN=dev-token
kdx sync deploy --target dev --env development

# Deploy to staging
export KODEXA_URL=https://staging.kodexa.com
export KODEXA_ACCESS_TOKEN=staging-token
kdx sync deploy --target staging --env staging

# Deploy to production
export KODEXA_URL=https://platform.kodexa.com
export KODEXA_ACCESS_TOKEN=prod-token
kdx sync deploy --target prod --env production

Pull Request Workflow

Validate changes before deployment:

# .github/workflows/pr-validation.yml
name: Validate Resources

on:
  pull_request:
    paths:
      - 'kodexa-metadata/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate configuration
        run: |
          export KODEXA_URL=${{ secrets.KODEXA_DEV_URL }}
          export KODEXA_ACCESS_TOKEN=${{ secrets.KODEXA_DEV_TOKEN }}
          kdx sync deploy --target dev --env development --dry-run

      - name: Comment results
        uses: actions/github-script@v7
        with:
          script: |
            const message = `### ✅ Resource Validation

            Your changes are valid and ready to deploy.

            Resources validated against development environment.`;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: message
            });

Common Workflows

Add New Resource

# 1. Create feature branch
git checkout -b feature/add-vendor-taxonomy

# 2. Add resource file
cat > kodexa-metadata/my-org/taxonomies/vendor-types.yaml << EOF
slug: vendor-types
name: Vendor Type Classification
version: "1.0.0"
taxons:
  - slug: corporate
    name: Corporate Vendor
  - slug: individual
    name: Individual Vendor
EOF

# 3. Add to manifest
# Edit kodexa-metadata/manifests/production.yaml to include:
# - type: taxonomy
#   slug: vendor-types

# 4. Validate locally
export KODEXA_URL=https://platform.kodexa.com
export KODEXA_ACCESS_TOKEN=your-token
kdx sync deploy --target prod --env production --dry-run

# 5. Commit and push
git add .
git commit -m "feat: add vendor type taxonomy"
git push origin feature/add-vendor-taxonomy

# 6. Open pull request on GitHub
# 7. GitHub Actions validates automatically
# 8. After approval, merge deploys to production

Update Existing Resource

# 1. Pull latest changes
git checkout main
git pull

# 2. Create branch
git checkout -b fix/update-invoice-form

# 3. Modify resource
vim kodexa-metadata/my-org/data-forms/invoice-form.yaml

# 4. Test locally
kdx sync deploy --target prod --env production --dry-run

# 5. Commit and deploy
git add .
git commit -m "fix: update invoice form field validation"
git push origin fix/update-invoice-form

Promote from Dev to Production

# 1. Test in development
git checkout develop
git pull
# Make changes, test

# 2. Merge to staging
git checkout staging
git merge develop
git push
# Automatic deployment to staging

# 3. After validation, merge to main
git checkout main
git merge staging
git push
# Automatic deployment to production

Rollback Changes

# Find the commit to rollback to
git log --oneline

# Create rollback branch from previous commit
git checkout -b rollback/revert-taxonomy-change abc1234

# Push and merge
git push origin rollback/revert-taxonomy-change
# Create PR and merge

Troubleshooting

Resource Not Found

Error: Resource 'my-taxonomy' not found in target environment Cause: Resource doesn’t exist in target environment or not in manifest Fix:

# Check manifest includes the resource
cat kodexa-metadata/manifests/production.yaml

# Add to manifest if missing
# Then deploy
kdx sync deploy --target prod --env production

Environment Variable Issues

Error: KODEXA_URL not set Cause: Required environment variables not configured Fix:

# Set required variables
export KODEXA_URL=https://platform.kodexa.com
export KODEXA_ACCESS_TOKEN=your-api-key

# Or use .env file
cat > .env << EOF
KODEXA_URL=https://platform.kodexa.com
KODEXA_ACCESS_TOKEN=your-api-key
EOF

source .env

Validation Errors

Error: Feature instance references unknown feature type Cause: Feature instance references a feature type that doesn’t exist Fix:

# Add the missing feature type first
cat > kodexa-metadata/my-org/feature-types/missing-type.yaml << EOF
slug: missing-type
name: Missing Feature Type
version: "1.0.0"
EOF

# Add to manifest
# Edit kodexa-metadata/manifests/production.yaml

# Deploy both together
kdx sync deploy --target prod --env production

Target or Environment Not Found

Error: Target 'prod' not found in sync-config.yaml Cause: Target or environment not defined in configuration Fix:

# Add to sync-config.yaml
targets:
  prod:
    url: https://platform.kodexa.com
    description: Production environment

environments:
  production:
    description: Production deployment

Conflicting Changes

Error: Merge conflict in YAML files Fix:

# Pull latest from target environment
kdx sync pull --target prod --env production

# Resolve conflicts manually
vim kodexa-metadata/my-org/taxonomies/conflicted-file.yaml

# Test resolution
kdx sync deploy --target prod --env production --dry-run

# Commit resolution
git add .
git commit -m "fix: resolve merge conflict"

Best Practices

1. Use Semantic Versioning

slug: invoice-classifier
version: "2.1.0"  # Major.Minor.Patch

2. Document Dependencies

# invoice-automation-project.yaml
slug: invoice-automation
# Dependencies:
#   - taxonomy: invoice-fields v1.0.0
#   - store: invoice-documents v1.0.0
#   - model: invoice-classifier v2.1.0

3. Test in Lower Environments First

# Test in dev
export KODEXA_URL=https://dev.kodexa.com
export KODEXA_ACCESS_TOKEN=dev-token
kdx sync deploy --target dev --env development

# Promote to staging
git checkout staging
git merge develop
git push

# Finally production
git checkout main
git merge staging
git push

4. Use Meaningful Commit Messages

git commit -m "feat: add OCR feature instance for production

- Configured with high-accuracy model
- Enabled GPU acceleration
- Set memory limit to 4GB"

5. Keep Resources Modular

Break large configurations into smaller, focused files and manifests:

kodexa-metadata/
├── manifests/
│   ├── shared-taxonomies.yaml
│   ├── shared-stores.yaml
│   ├── production-features.yaml
│   └── production-models.yaml
└── my-org/
    ├── taxonomies/
    │   ├── invoice-fields.yaml
    │   ├── vendor-types.yaml
    │   └── payment-methods.yaml
    └── feature-types/
        ├── ocr-extraction.yaml
        └── text-extraction.yaml

6. Use Environment-Specific Manifests

# kodexa-metadata/sync-config.yaml
branch_mappings:
  - branch: develop
    target: dev
    environment: development
  - branch: main
    target: prod
    environment: production

manifests:
  - manifests/shared.yaml           # Both environments
  - manifests/dev-only.yaml         # Dev-specific
  - manifests/production-only.yaml  # Prod-specific

Next Steps

GitOps with GitHub Actions

Complete GitHub Actions deployment guide

CLI Metadata Sync

Local development with kdx CLI

Resource Operations

CRUD operations for resources

KDX CLI Overview

Learn about the kdx CLI

Getting Started

Deployment

Notebooks

Cookie Cutters

​Overview

​Resource Types

​Organization-Level Resources

​Project-Level Resources

​Quick Start

​1. Configure Environment

​2. Pull Existing Resources

​3. Review Configuration

​4. Create Git Repository

​5. Set Up GitHub Actions

​6. Configure Secrets

​Working with Resources

​Adding a New Taxonomy

​Adding a Document Store

​Adding a Feature Type

​Adding a Feature Instance

​Sync Configuration

​Basic Configuration

​Multi-Environment Configuration

​Manifest Composition

​Multi-Environment Deployment

​Branch-Based Strategy

​GitHub Actions for Multi-Environment

​Manual Environment Deployment

​Pull Request Workflow

​Common Workflows

​Add New Resource

​Update Existing Resource

​Promote from Dev to Production

​Rollback Changes

​Troubleshooting

​Resource Not Found

​Environment Variable Issues

​Validation Errors

​Target or Environment Not Found

​Conflicting Changes

​Best Practices

​1. Use Semantic Versioning

​2. Document Dependencies

​3. Test in Lower Environments First

​4. Use Meaningful Commit Messages

​5. Keep Resources Modular

​6. Use Environment-Specific Manifests

​Next Steps

GitOps with GitHub Actions

CLI Metadata Sync

Resource Operations

KDX CLI Overview

Overview

Resource Types

Organization-Level Resources

Project-Level Resources

Quick Start

1. Configure Environment

2. Pull Existing Resources

3. Review Configuration

4. Create Git Repository

5. Set Up GitHub Actions

6. Configure Secrets

Working with Resources

Adding a New Taxonomy

Adding a Document Store

Adding a Feature Type

Adding a Feature Instance

Sync Configuration

Basic Configuration

Multi-Environment Configuration

Manifest Composition

Multi-Environment Deployment

Branch-Based Strategy

GitHub Actions for Multi-Environment

Manual Environment Deployment

Pull Request Workflow

Common Workflows

Add New Resource

Update Existing Resource

Promote from Dev to Production

Rollback Changes

Troubleshooting

Resource Not Found

Environment Variable Issues

Validation Errors

Target or Environment Not Found

Conflicting Changes

Best Practices

1. Use Semantic Versioning

2. Document Dependencies

3. Test in Lower Environments First

4. Use Meaningful Commit Messages

5. Keep Resources Modular

6. Use Environment-Specific Manifests

Next Steps