# GitHub Sync

> Push your ontology to GitHub as a structured markdown bundle for AI agents and programmatic consumption.

**Category:** GitHub Sync | **Tab:** integrations

---

## Overview

Black Ice's GitHub Sync feature pushes your entire approved ontology to a GitHub repository as a structured bundle of Markdown files. This is the primary integration path — no REST API required.

Your AI localization pipeline, Claude Code project, or any system with access to the repo can read the ontology directly from the file system or via the GitHub API.

## What gets exported

When you sync, Black Ice generates an `ontology/` directory in your repository containing:

```
ontology/
├── CLAUDE.md              # Agent instructions and ontology overview
├── classes/               # One file per concept class
│   ├── feature.md
│   ├── plan.md
│   └── platform.md
├── markets/               # One file per target market
│   ├── de-DE.md
│   ├── fr-FR.md
│   └── ja-JP.md
├── terminology/           # Term definitions per locale
│   ├── en-US/
│   ├── de-DE/
│   └── fr-FR/
└── relationships/         # Semantic relationships between concepts
    └── relationships.md
```

**CLAUDE.md** is the entry point. It tells your AI agent what the ontology contains, how it's structured, and how to use it.

**Classes** define the taxonomy — what types of concepts exist (Feature, Plan, Platform, etc.) and their translation policies.

**Markets** contain the Culture DNA for each locale — tone of voice, cultural pragmatics, grammar rules, brand identity, and golden examples that guide how content should sound in that market.

**Terminology** holds the actual term definitions — source terms, target translations, allowed/forbidden variants, usage context, and approval status.

**Relationships** maps how concepts connect to each other semantically (e.g., a Plan *hasFeature* relationships).

## Setting up GitHub Sync

1. Go to **Settings** in your workspace
2. Open the **GitHub Sync** section
3. Enter your GitHub personal access token (with `repo` scope)
4. Specify the repository owner, name, branch, and target path
5. Choose an approval filter — sync all terms, only approved terms, or approved + pending
6. Enable **Auto-sync** to push changes automatically whenever terms are updated

## How AI agents consume the ontology

### Direct file access (Claude Code, Cursor, etc.)

If your AI agent runs inside the repo (e.g., Claude Code with a `CLAUDE.md` file), it reads the ontology files directly from disk. No API calls needed.

```
# The agent reads CLAUDE.md first, then navigates the ontology structure
# to find the relevant class, market, and terminology files.
```

### GitHub API consumption

External systems can fetch ontology files programmatically via the GitHub API:

```bash
# Fetch the agent instructions
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/contents/ontology/CLAUDE.md

# Fetch a specific market profile
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/contents/ontology/markets/de-DE.md

# Fetch all terminology for a locale
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/contents/ontology/terminology/de-DE/
```

### GitHub Actions integration

Trigger downstream workflows whenever the ontology is updated:

```yaml
# .github/workflows/on-ontology-update.yml
on:
  push:
    paths:
      - 'ontology/**'

jobs:
  process-ontology:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Process updated ontology
        run: |
          echo "Ontology updated — trigger localization pipeline"
          # Your pipeline logic here
```

## Why files, not an API

Black Ice deliberately exports Markdown files instead of exposing a REST API because:

- **LLMs work better with Markdown** — structured prose is the native input format for language models, not JSON payloads
- **GitHub provides the infrastructure** — versioning, access control, branch-based workflows, and webhooks are already solved
- **No auth complexity** — your agent reads files from disk or uses an existing GitHub token. No API keys to manage, no rate limits to hit
- **Diff-friendly** — every ontology change creates a readable Git diff, making reviews and rollbacks trivial
- **Offline-capable** — the ontology works without network access once cloned

## Availability

GitHub Sync is available on the **Builder** tier. See [Plans and Pricing](/docs/getting-started/plans) for details.