Skip to main content
Kodexa enables modern, Git-based deployment workflows that bring the power of version control, code review, and CI/CD to your document processing infrastructure.

​
Deployment Approaches

GitOps with GitHub Actions

Recommended for teamsAutomated deployments with GitHub Actions, code review workflows, and multi-environment promotion

CLI for Development

Best for local developmentDirect CLI access for rapid iteration and local testing before committing changes

​
Why GitOps for Kodexa?

​
Traditional Deployment Challenges

Before GitOps, managing Kodexa configurations across environments involved:
  • ❌ Manual changes prone to human error
  • ❌ No audit trail of who changed what
  • ❌ Difficult to rollback problematic changes
  • ❌ Hard to maintain consistency across environments
  • ❌ No code review for infrastructure changes

​
GitOps Benefits

With Git-based workflows, you get:
  • ✅ Version Control - Full history of all changes
  • ✅ Code Review - Pull requests for infrastructure changes
  • ✅ Rollback - Easy revert to any previous state
  • ✅ Multi-Environment - Promote changes dev → staging → production
  • ✅ Automation - CI/CD pipelines for deployment
  • ✅ Collaboration - Team can review and approve changes

​
Quick Comparison

AspectGitHub ActionsCLI
Best ForProduction deploymentsLocal development
AutomationFully automatedManual
Code ReviewBuilt-in via PRsN/A
Multi-EnvironmentEasy with workflowsManual switching
Audit TrailGit historyLocal only
Team CollaborationExcellentLimited
Setup ComplexityModerateMinimal

​
Common Use Cases

​
Multi-Environment Deployment

Deploy configurations across development, staging, and production with automated promotion: 
# .github/workflows/deploy.yml
on:
  push:
    branches:
      - main        # → Production
      - staging     # → Staging
      - develop     # → Development

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kodexa-ai/kdx-sync-action@v1
        with:
          kodexa-url: ${{ secrets.KODEXA_URL }}
          kodexa-token: ${{ secrets.KODEXA_TOKEN }}

​
Pull Request Validation

Validate changes before they reach production: 
# Dry-run on PRs
on: pull_request

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kodexa-ai/kdx-sync-action@v1
        with:
          kodexa-url: ${{ secrets.KODEXA_URL }}
          kodexa-token: ${{ secrets.KODEXA_TOKEN }}
          dry-run: true  # Preview only, no changes

​
Local Development

Use the CLI for rapid development iteration: 
# Pull latest configuration
kdx sync pull --target dev --env local

# Make changes
vim kodexa-metadata/my-org/taxonomies/new-classification.yaml

# Test locally with dry-run
kdx sync deploy --target dev --env local --dry-run

# Deploy when ready
kdx sync deploy --target dev --env local

​
Repository Structure

Both approaches use the same repository structure: 
my-project/
├── .github/
│   └── workflows/
│       ├── deploy.yml           # Main deployment workflow
│       └── pr-validation.yml    # PR validation
├── kodexa-metadata/
│   ├── sync-config.yaml         # Sync configuration (v2)
│   ├── my-org/
│   │   ├── organization.yaml
│   │   ├── taxonomies/
│   │   ├── stores/
│   │   ├── feature-types/
│   │   └── models/
│   └── README.md
├── manifests/                   # Resource manifests (v2)
│   ├── my-org/
│   │   ├── taxonomies/
│   │   ├── stores/
│   │   ├── feature-types/
│   │   └── models/
└── README.md

​
Getting Started

1

Choose Your Approach

For teams: Start with GitOps with GitHub ActionsFor solo development: Start with CLI
2

Initialize Repository

Pull existing configuration or create new structure
3

Configure Workflows

Set up deployment workflows for your needs
4

Deploy

Push changes and let automation handle deployment

​
Next Steps

GitOps with GitHub Actions

Complete guide to automated deployments

Resource Deployments

Managing specific Kodexa resources

CLI Metadata Sync

Local CLI development workflows

KDX CLI Overview

Learn about the kdx CLI tool