CI/CD Integration

Charon’s CLI supports full automation of game data workflows — validation, export, translation, code generation, and backup — making it straightforward to integrate into any continuous integration or deployment pipeline.

Installation in CI 

Install the dotnet-charon tool as part of your pipeline setup step. The tool requires the .NET 8 (or later) runtime to be present.

GitHub Actions

- name: Setup .NET
  uses: actions/setup-dotnet@v4
  with:
    dotnet-version: '8.x'

- name: Install Charon
  run: dotnet tool install -g dotnet-charon

GitLab CI

before_script:
  - apt-get install -y dotnet-sdk-8.0
  - dotnet tool install -g dotnet-charon
  - export PATH="$PATH:$HOME/.dotnet/tools"

Shell script (any runner)

dotnet tool install -g dotnet-charon
export PATH="$PATH:$HOME/.dotnet/tools"
charon VERSION

Authentication 

Provide the API key for remote data sources via the CHARON_API_KEY environment variable. Store it as a CI secret; never hard-code it in pipeline files.

# GitHub Actions — secrets.CHARON_API_KEY defined in repository settings
env:
  CHARON_API_KEY: ${{ secrets.CHARON_API_KEY }}

# Shell — set before running any charon command
export CHARON_API_KEY="your-api-key-here"
charon DATA EXPORT --dataBase "https://charon.live/view/data/MyGame/main/" ...

Alternatively, pass credentials explicitly with --credentials. The environment variable takes precedence when both are supplied.

Exit Codes 

Charon exits with 0 on success. It exits with 1 or any positive code in these cases:

A fatal error occurred (bad parameters, file not found, network failure).
DATA VALIDATE produced errors and --output was set to err.

All other cases — including a validation report that contains errors written to a file — exit with 0. Design your pipeline steps accordingly.

Common Pipeline Recipes 

Validate on every pull request 

# .github/workflows/validate.yml
name: Validate game data

on: [pull_request]

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

      - uses: actions/setup-dotnet@v4
        with: { dotnet-version: '8.x' }

      - run: dotnet tool install -g dotnet-charon

      - name: Validate integrity
        run: |
          charon DATA VALIDATE \
            --dataBase gamedata.json \
            --validationOptions checkRequirements checkReferences checkFormat \
            --output err
        # Exits 1 and fails the workflow if errors are found

Export and publish on tag 

# .github/workflows/publish.yml
name: Publish game data

on:
  push:
    tags: ['v*']

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      CHARON_API_KEY: ${{ secrets.CHARON_API_KEY }}

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with: { dotnet-version: '8.x' }
      - run: dotnet tool install -g dotnet-charon

      - name: Backup before publish
        run: |
          charon DATA BACKUP \
            --dataBase "https://charon.live/view/data/MyGame/main/" \
            --output backup_${{ github.ref_name }}.zip

      - name: Validate
        run: |
          charon DATA VALIDATE \
            --dataBase "https://charon.live/view/data/MyGame/main/" \
            --validationOptions checkRequirements checkReferences \
            --output err

      - name: Export published data (JSON)
        run: |
          charon DATA EXPORT \
            --dataBase "https://charon.live/view/data/MyGame/main/" \
            --mode publication \
            --output StreamingAssets/gamedata.json \
            --outputFormat json

      - name: Generate C# source code
        run: |
          charon GENERATE CSHARPCODE \
            --dataBase "https://charon.live/view/data/MyGame/main/" \
            --namespace MyGame.Parameters \
            --outputDirectory Assets/Scripts/Generated \
            --clearOutputDirectory

      - name: Commit generated files
        run: |
          git config user.name "CI Bot"
          git config user.email "ci@example.com"
          git add Assets/Scripts/Generated StreamingAssets/gamedata.json
          git commit -m "chore: regenerate game data for ${{ github.ref_name }}"
          git push

Apply a patch on merge 

# In a merge script or CI job
charon DATA APPLYPATCH \
    --dataBase gamedata.json \
    --input feature_changes.patch.json \
    --validationOptions repair checkRequirements checkReferences

charon DATA VALIDATE \
    --dataBase gamedata.json \
    --validationOptions checkRequirements checkReferences checkFormat \
    --output err   # Fail CI if post-merge data is invalid

Export translation files for a localization vendor 

for lang in de fr ja ko; do
  charon DATA I18N EXPORT \
    --dataBase gamedata.json \
    --sourceLanguage en \
    --targetLanguage "$lang" \
    --output "translations/en_${lang}.xliff" \
    --outputFormat xliff
done

Import translated files from a vendor 

for file in translations/en_*.xliff; do
  charon DATA I18N IMPORT \
    --dataBase gamedata.json \
    --input "$file" \
    --dryRun   # Preview first

  charon DATA I18N IMPORT \
    --dataBase gamedata.json \
    --input "$file"
done

Recommended Pipeline Structure 

[PR open]
  └─ DATA VALIDATE (checkRequirements + checkReferences + checkFormat → err)

[Merge to main]
  └─ DATA BACKUP
  └─ DATA VALIDATE (as above)
  └─ GENERATE <LANG>CODE --clearOutputDirectory
  └─ commit generated files

[Release tag]
  └─ DATA BACKUP (tagged archive)
  └─ DATA EXPORT --mode publication
  └─ upload to CDN / game build