> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kodexa GitOps Deployment Workflows

> Deploy Kodexa metadata, modules, and resources using modern Git-based workflows with version control, code review, and CI/CD pipeline integration.

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

<CardGroup cols={2}>
  <Card title="GitOps with GitHub Actions" icon="github" href="/guides/deployment/gitops-github-actions">
    **Recommended for teams**

    Automated deployments with GitHub Actions, code review workflows, and multi-environment promotion
  </Card>

  <Card title="CLI for Development" icon="terminal" href="/guides/kdx-cli/sync/overview">
    **Best for local development**

    Direct CLI access for rapid iteration and local testing before committing changes
  </Card>
</CardGroup>

## 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:

```yaml theme={null}
# .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:

```yaml theme={null}
# 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:

```bash theme={null}
# 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:

```text theme={null}
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

<Steps>
  <Step title="Choose Your Approach">
    For teams: Start with [GitOps with GitHub Actions](/guides/deployment/gitops-github-actions)

    For solo development: Start with [CLI](/guides/kdx-cli/sync/overview)
  </Step>

  <Step title="Initialize Repository">
    Pull existing configuration or create new structure
  </Step>

  <Step title="Configure Workflows">
    Set up deployment workflows for your needs
  </Step>

  <Step title="Deploy">
    Push changes and let automation handle deployment
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="GitOps with GitHub Actions" icon="github" href="/guides/deployment/gitops-github-actions">
    Complete guide to automated deployments
  </Card>

  <Card title="Resource Deployments" icon="box" href="/guides/deployment/resource-deployments">
    Managing specific Kodexa resources
  </Card>

  <Card title="CLI Metadata Sync" icon="terminal" href="/guides/kdx-cli/sync/overview">
    Local CLI development workflows
  </Card>

  <Card title="KDX CLI Overview" icon="command-line" href="/guides/kdx-cli/overview">
    Learn about the kdx CLI tool
  </Card>
</CardGroup>