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

Version Pinning and Compatibility 

dotnet tool install without a version always fetches the latest release. For reproducible builds, pin the tool version.

Local tools manifest (recommended). Create a manifest once and commit .config/dotnet-tools.json to the repository:

dotnet new tool-manifest
dotnet tool install dotnet-charon --version 2026.3.4

CI then restores the exact pinned version and invokes the tool through dotnet:

dotnet tool restore
dotnet charon DATA VALIDATE --dataBase gamedata.json ...

On-demand with a pinned version (.NET 10 SDK):

dnx dotnet-charon@2026.3.4 -- DATA VALIDATE --dataBase gamedata.json ...

Global install with a pinned version:

dotnet tool install -g dotnet-charon --version 2026.3.4

Tool version vs. format version 

Two versions matter for compatibility:

Tool version (e.g. 2026.3.4) - the actual release version of dotnet-charon. It changes with every release: bug fixes, new features, UI updates.
Format version - the version of the game data file format. It changes only when the system schemas are updated or system fields are added or changed, which is rare. Tool releases overwhelmingly ship with an unchanged format version.

Game data files are auto-migrated to the newest format version on save. Read-only operations - DATA VALIDATE, DATA EXPORT, GENERATE ... - never mutate the file, so running a newer tool against an older-format file in CI is safe and leaves the file untouched.

If you want to deliberately migrate a file to the current format version, apply any change and save - for example, update the Copyright field in Project Settings from the editor UI. The save rewrites the file in the newest format.

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