GitHub

Sync your context files with GitHub for version control and automation interoperability

GitHub Sync enables bidirectional synchronization between Dot's context files and a GitHub repository.

Why GitHub Sync Matters

The real power lies in interoperability. By storing context in GitHub using open formats (Markdown with YAML frontmatter), you enable:

• Coding agents (Claude Code, Cursor, GitHub Copilot) to read and contribute to the same context Dot uses

• CI/CD pipelines to validate or transform documentation automatically

• Team collaboration through pull requests and code review

Your data documentation becomes a shared asset that multiple AI assistants can leverage.

What Gets Synced

notes/
├── active/          # Active notes
└── inactive/        # Archived notes

data_sources/
├── active/          # Active table documentation
└── inactive/        # Archived table documentation

apps/                # Dashboards as code
├── _shared/         # Org-wide dashboards (.app sources + .app.lock compiled sidecars)
└── <email>/         # Per-user dashboards

skills/              # Custom skills (skills/<name>/SKILL.md plus supporting files)

evaluations/         # Saved evaluation definitions (<evaluation-id>.yaml)

relationships.yaml   # Table relationships

Context files use Markdown (.md) with YAML frontmatter, or plain YAML. Dashboards sync as .app sources plus their .app.lock compiled sidecars, and custom skills as their SKILL.md and supporting text files.

Context files, dashboards (apps), custom skills, and evaluation definitions are synced. Evaluation runs and results remain in Dot. Database connections, user settings, and chat history remain in Dot.

Setting Up GitHub Sync

Prerequisites

• Admin access to your Dot organization

• A GitHub account with permission to install GitHub Apps

Step 1: Connect with GitHub

1. Go to Settings > Version Control > GitHub

2. Click Connect with GitHub

Click Connect with GitHub to start the setup

1. Install the Dot Context Sync GitHub App

2. Choose repository access — either All repositories or Selected repositories

Choose repository access during installation

Both "All repositories" and "Selected repositories" work. If you choose "Selected repositories", you'll need to create your sync repository manually on GitHub first (see Step 2).

Step 2: Configure Your Repository

Select existing repository (recommended): Select a repository and branch from the list. This works with both "All repositories" and "Selected repositories" access.

Tip: If you use "Selected repositories" access, create an empty private repository on GitHub first. When you install or update the GitHub App, make sure the repository is included in the App's access list. It will then appear in Dot's repository dropdown.

Create new repository: Enter a name, choose a branch, and Dot will create a private repo with all your existing context. This option requires the GitHub App to be installed with "All repositories" access.

If your repository already has files (like a README), Dot will preserve them. Dot only manages files in the notes/, data_sources/, apps/, skills/, and evaluations/ paths, plus relationships.yaml.

Step 3: Enable Auto-Sync

Toggle Auto-sync enabled to automatically push changes when you update context in Dot's UI.

Evaluation files

Evaluations sync as evaluations/<id>.yaml and follow the same environment and merge workflow as other context. Preserve IDs and metadata when editing. For a portable CLI suite, use dot eval export; see Evaluations in CI.

How Sync Works

Push (Dot → GitHub): Changes in Dot automatically commit to GitHub when auto-sync is enabled. When you first configure a repository, Dot pushes all existing context files immediately.

Pull (GitHub → Dot): Changes in GitHub (commits, merged PRs) automatically sync to Dot via webhooks.

Collaboration workflow: Team members or AI coding assistants can submit pull requests. Once merged, changes automatically appear in Dot.

Manual sync: Force push or pull all files from Settings if needed.

Limitations

• One repository per workspace. Dot syncs your production branch. If you use environments and leave environment mirroring on, Dot also pushes a branch for each environment, named dot/env-<slug>, so you can review changes as pull requests

• Text files only in the managed paths — Markdown/YAML context, .app dashboard sources with their .app.lock sidecars, and skill files (binary or non-UTF-8 assets are skipped)

• Last write wins for simultaneous edits (no conflict resolution UI)

Not synced: Database credentials, user accounts, chat history, scheduled reports, organization settings.

Troubleshooting

Issue	Solution
Sync not working	Check Settings > GitHub for connection status and auto-sync toggle
Permission errors	Verify the GitHub App has access to your repo in GitHub Settings > Applications
Files not appearing	Ensure files are in notes/, data_sources/, apps/, skills/, or relationships.yaml with correct extensions
Can't create repository	This requires "All repositories" access. Create the repo manually on GitHub and select it instead
Sync disabled unexpectedly	If you remove a repository from the GitHub App's access, Dot automatically disables sync. Re-add the repo and re-enable sync in Settings

Security

Repositories created by Dot are private. Uses secure GitHub App tokens with scoped access. All webhook payloads are cryptographically verified.