Kodexa GitOps Deployment Workflows

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

Aspect	GitHub Actions	CLI
Best For	Production deployments	Local development
Automation	Fully automated	Manual
Code Review	Built-in via PRs	N/A
Multi-Environment	Easy with workflows	Manual switching
Audit Trail	Git history	Local only
Team Collaboration	Excellent	Limited
Setup Complexity	Moderate	Minimal

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

Choose Your Approach

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

Initialize Repository

Pull existing configuration or create new structure

Configure Workflows

Set up deployment workflows for your needs

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

Introduction

Activity

Knowledge System

Organization & Projects

Resources

Modules

Deployment Approaches

GitOps with GitHub Actions

CLI for Development

Why GitOps for Kodexa?

Traditional Deployment Challenges

GitOps Benefits

Quick Comparison

Common Use Cases

Multi-Environment Deployment

Pull Request Validation

Local Development

Repository Structure

Getting Started

Next Steps

GitOps with GitHub Actions

Resource Deployments

CLI Metadata Sync

KDX CLI Overview

​Deployment Approaches

GitOps with GitHub Actions

CLI for Development

​Why GitOps for Kodexa?

​Traditional Deployment Challenges

​GitOps Benefits

​Quick Comparison

​Common Use Cases

​Multi-Environment Deployment

​Pull Request Validation

​Local Development

​Repository Structure

​Getting Started

​Next Steps

GitOps with GitHub Actions

Resource Deployments

CLI Metadata Sync

KDX CLI Overview

Deployment Approaches

Why GitOps for Kodexa?

Traditional Deployment Challenges

GitOps Benefits

Quick Comparison

Common Use Cases

Multi-Environment Deployment

Pull Request Validation

Local Development

Repository Structure

Getting Started

Next Steps