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. Pull Existing Resources

Use the kdx CLI to download your existing configuration:

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

# Configure authentication
kdx config set-profile prod \
  --url https://platform.kodexa.com \
  --api-key your-api-key

# Pull configuration
kdx sync pull --from-profile prod

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

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

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

3. 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 }}

4. Configure Secrets

In GitHub repository settings, add:

KODEXA_URL - Your Kodexa platform URL
KODEXA_TOKEN - Your API token

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

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

Test Locally

# Validate configuration
kdx sync push --dry-run

Commit and Push

git add kodexa-metadata/my-org/taxonomies/invoice-fields.yaml
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

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 which resources to manage:

Resource-Based (Recommended)

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

organizations:
  - slug: my-organization
    resources:
      # Taxonomies
      - type: taxonomy
        slug: invoice-fields

      - type: taxonomy
        slug: document-types

      # Stores
      - type: store
        slug: invoice-documents

      # Feature types
      - type: featureType
        slug: ocr-extraction

      # Feature instances
      - type: featureInstance
        slug: ocr-prod

      # Models
      - type: model
        slug: invoice-classifier-v3

      # Data forms
      - type: dataForm
        slug: invoice-form

Project-Based (Legacy)

# Sync entire organizations and projects
metadata_dir: kodexa-metadata

organizations:
  - slug: my-organization
    projects:
      - invoice-automation
      - contract-processing

Multi-Environment Deployment

Deploy the same configuration to multiple environments:

Environment Strategy

Option 1: Branch-Based

main → production
staging → staging environment
develop → development environment

Option 2: Directory-Based

kodexa-metadata/
├── environments/
│   ├── production/sync-config.yaml
│   ├── staging/sync-config.yaml
│   └── development/sync-config.yaml
└── shared/
    └── taxonomies/

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: Determine environment
        id: env
        run: |
          if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
            echo "name=production" >> $GITHUB_OUTPUT
          elif [[ "${{ github.ref }}" == "refs/heads/staging" ]]; then
            echo "name=staging" >> $GITHUB_OUTPUT
          else
            echo "name=development" >> $GITHUB_OUTPUT
          fi

      - name: Deploy to ${{ steps.env.outputs.name }}
        uses: kodexa-ai/kdx-sync-action@v1
        with:
          kodexa-url: ${{ secrets[format('KODEXA_{0}_URL', steps.env.outputs.name)] }}
          kodexa-token: ${{ secrets[format('KODEXA_{0}_TOKEN', steps.env.outputs.name)] }}

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
        uses: kodexa-ai/kdx-sync-action@v1
        with:
          kodexa-url: ${{ secrets.KODEXA_URL }}
          kodexa-token: ${{ secrets.KODEXA_TOKEN }}
          dry-run: true  # Validate only, don't deploy

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

            Your changes are valid and ready to deploy.

            **Resources to create:** ${{ steps.validate.outputs.resources-created }}
            **Resources to update:** ${{ steps.validate.outputs.resources-updated }}
            **Resources unchanged:** ${{ steps.validate.outputs.resources-skipped }}`;

            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"
# ... taxonomy definition
EOF

# 3. Validate locally
kdx sync push --dry-run

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

# 5. Open pull request on GitHub
# 6. GitHub Actions validates automatically
# 7. 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 push --dry-run

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

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 Cause: Resource doesn’t exist in target environment Fix:

# Ensure resource exists in sync-config.yaml
# Then push to create it
kdx sync push

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

# Then commit both
git add .
git commit -m "fix: add missing feature type dependency"

Conflicting Changes

Error: Merge conflict in YAML files Fix:

# Pull latest from target environment
kdx sync pull --from-profile prod

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

# Test resolution
kdx sync push --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
kdx sync push --to-profile dev

# Promote to staging
kdx sync push --to-profile staging

# Finally production
kdx sync push --to-profile prod

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:

taxonomies/
├── invoice-fields.yaml
├── vendor-types.yaml
└── payment-methods.yaml

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. Pull Existing Resources

​2. Create Git Repository

​3. Set Up GitHub Actions

​4. Configure Secrets

​Working with Resources

​Adding a New Taxonomy

​Adding a Document Store

​Adding a Feature Type

​Adding a Feature Instance

​Sync Configuration

​Resource-Based (Recommended)

​Project-Based (Legacy)

​Multi-Environment Deployment

​Environment Strategy

​GitHub Actions for Multi-Environment

​Pull Request Workflow

​Common Workflows

​Add New Resource

​Update Existing Resource

​Rollback Changes

​Troubleshooting

​Resource Not Found

​Validation Errors

​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

​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. Pull Existing Resources

2. Create Git Repository

3. Set Up GitHub Actions

4. Configure Secrets

Working with Resources

Adding a New Taxonomy

Adding a Document Store

Adding a Feature Type

Adding a Feature Instance

Sync Configuration

Resource-Based (Recommended)

Project-Based (Legacy)

Multi-Environment Deployment

Environment Strategy

GitHub Actions for Multi-Environment

Pull Request Workflow

Common Workflows

Add New Resource

Update Existing Resource

Rollback Changes

Troubleshooting

Resource Not Found

Validation Errors

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

Next Steps