# Git Sync > Round-trip Metabase content (cards, dashboards, transforms, snippets, collections, Library-published table/field metadata) between an instance and a git remote via `mb git-sync …` — status, dirty / has-remote-changes checks, import, export (with branch guard), branches, stash, add/remove a collection from sync. Load when the user wants to "import the latest changes", "export to git", "push my changes to the repo", "open a PR with my Metabase changes", "git sync", "dirty check", "stash before pulling", "add a collection to sync", or anything `mb git-sync …`. - Skill: `metabase/git-sync` (Agent Skill) - Install (CLI): `npx skillmds@latest add metabase/git-sync` - Raw SKILL.md: https://api.skillmd.com/api/skills/metabase/git-sync/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: metabase (https://skillmd.com/u/metabase) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/metabase/git-sync --- # git-sync (representations ↔ instance) Metabase content (cards, dashboards, transforms, snippets, collections, …) can live in a git repo as YAML and round-trip in and out of a Metabase instance via the `git-sync` verbs. The instance is configured with a `remote-sync-*` settings block (URL, branch, token, type read-only/read-write); the CLI drives the sync tasks against `/api/ee/remote-sync/*`. Only collections flagged for sync serialize; everything else is local-only. Table and field metadata round-trips too, for Library-published tables in a flagged collection — see "Published table metadata" below. The repo and the instance are two ends of the same state; what "push my changes" means depends on where the changes were made. If they were made **in the instance** (CLI verbs against a read-write instance — cards edited, transforms created, tables published, metadata written), "push my changes" / "save this to the repo" / "open a PR with these changes" means driving the instance's export to a branch (`stash` or `create-branch` + `export`) and opening the PR from that branch — not reconstructing the changes as files. If the workflow is **repo-first** (content YAML edited in the repo, the instance imports it), plain `git` against the repo is the way — but only in the serialized layout already there: files in paths or formats the serializer doesn't own are invisible to Metabase and never apply on import. This skill covers the import/export workflow. Flag conventions and auth setup live in `core` (`mb skills get core`). To author content YAML by hand: the per-resource clause and settings shapes mirror the API form — query bodies follow the `mbql` skill, `visualization_settings` follow the `visualization` skill — except the portable YAML uses **name-based** references (e.g. `[Sample Database, PUBLIC, ORDERS, TOTAL]`, and entity-ids for cross-entity FKs) where the API form uses numeric ids. For the on-disk folder layout, model new files on what the synced repo already contains. ## Precondition: read state before mutating Always run `status` (or `is-dirty` + `has-remote-changes`) before `import` or `export`. Importing on a dirty instance silently rejects unless you pass `--force`; exporting when the instance is behind the remote pushes a stale state. ```bash mb git-sync status --profile --json # → branch, dirty, current task mb git-sync is-dirty --profile --json # → {is_dirty: bool}; instance has unexported changes mb git-sync has-remote-changes --profile --json # → {has_changes: bool, remote_version, local_version, cached}; remote has unimported commits mb git-sync dirty --profile --json # → list the dirty objects mb git-sync current-task --profile --json # → in-flight task (or idle) ``` **Clean up before exporting.** If you've created entities you intend to delete (a failed transform you're going to retry, a card you authored to test a body shape, a draft dashboard) — do the deletes _before_ the first `git-sync export`. Once committed, the cleanup needs a second commit, and the failed entity stays visible in `git log` forever. For transforms, prefer `transform update ` over delete + create (see the `transform` skill). ## Import (remote → instance) ```bash mb git-sync import --branch --profile # Default flags: --wait, polling --interval 2000 --timeout 600000 ``` Pulls the configured branch and applies it to the instance. Polls until the task reaches a terminal state (`succeeded` / `failed`). | Flag | Purpose | | ----------------- | ------------------------------------------------------------------------------------ | | `--branch ` | Defaults to the `remote-sync-branch` setting; override per-call. | | `--no-wait` | Return as soon as the task is queued; combine with `mb git-sync wait` later. | | `--force` | **Discards local Metabase-side dirty changes** (lossy). Confirm with the user first. | | `--timeout ` | Polling deadline. Default 600 000. | | `--interval ` | Polling cadence. Default 2 000. | Workflow: 1. Read state (above) — confirm `is_dirty: false` (or `--force` is intended). 2. Confirm `has-remote-changes` reports `has_changes: true` — there's actually something to import. 3. `git-sync import --branch ` — runs to terminal status by default. ## Export (instance → remote) ```bash mb git-sync export -m "commit message" --branch --profile ``` Pushes Metabase-side changes back to the configured remote. `-m` is the commit message; without it the server picks a default. Defaults to `--wait`. | Flag | Purpose | | ------------------- | -------------------------------------------------------- | | `--branch ` | Push to a specific branch instead of the configured one. | | `-m, --message ` | Commit message. | | `--force` | Force-push / overwrite remote. Confirm with the user. | | `--no-wait` | Don't poll. | Workflow: 1. **Branch guard** (below) — confirm the instance isn't tracking `main`/`master`, or that the user has explicitly accepted exporting to it. 2. Read state (above) — confirm `is-dirty` reports there's something to export. 3. `git-sync export -m "..."` — pushes and polls. 4. (Optional) `git-sync status` — verify `is_dirty: false` after. ### Branch guard: don't export to main/master without confirmation Sync work is conventionally done on a feature branch — exporting to `main` (or `master`) commits team-shared content directly. Before `git-sync export`, check the tracked branch and if it's `main`/`master`, ask the user whether to switch first. Read the current branch with `mb git-sync status --profile --json | jq -r '.branch'`. If the branch is `main` or `master`, prompt with `AskUserQuestion`: > "The instance is tracking `` — exporting commits straight to it. Switch to a feature branch first?" > > 1. **Create a feature branch** — agent suggests a name (e.g., `agent/`); run `mb git-sync create-branch --profile `. This exports current dirty state to the new branch and switches the instance's tracked branch to it; subsequent `git-sync export` calls go to that branch. > 2. **Proceed on `main`/`master`** — explicitly accepted. Skip the prompt only if the user's instructions already specified the branch (e.g., they explicitly said "export to main" or named a feature branch). Don't silently default to whatever `remote-sync-branch` happens to point at. ## Branches ```bash mb git-sync branches --profile --json # list remote branches mb git-sync create-branch --profile # create + switch sync to it mb git-sync stash --profile # export current state to a NEW branch ``` `stash` is the safe move when the instance has team work you don't want to lose, but you need to pivot to a different branch (`import` would discard, `export --force` would overwrite). It exports current state to a fresh branch first. ## Polling and cancelling ```bash mb git-sync wait --profile # block on the in-flight task mb git-sync cancel-task --profile # cancel the in-flight task ``` Use `wait` after `import --no-wait` / `export --no-wait`. Use `cancel-task` if a git-sync task hangs and you want to abandon it. ## Adding / removing a directory (collection) to sync The set of directories under sync is governed by which **collections** carry `is_remote_synced: true`. Every collection so flagged serializes to its own folder under `collections/` in the repo; everything outside that set is local-only. The CLI exposes per-collection toggles that route to the underlying bulk endpoint (`PUT /api/ee/remote-sync/settings`): ```bash mb git-sync add-collection --profile --json mb git-sync remove-collection --profile --json ``` `` is a **positive integer** (the bulk endpoint's schema is `pos-int? → boolean`; nano-id / `root` / `trash` refs are not supported). Get the id from `collection list` (see `core`). Both verbs return `{ success: true, task_id?: }`. The optional `task_id` only appears when the toggle triggered a follow-up task (e.g., a finalization import after switching to read-only mode); for a normal add/remove in read-write, expect `{ success: true }` and nothing else. **Cascade.** A toggle on a parent cascades to every descendant by `location` prefix — `add-collection 4` flips `4` plus every collection nested under it. `remove-collection 4` is the symmetric inverse. There is no per-leaf-only mode. **Mode prerequisite.** The server rejects toggles while `remote-sync-type` is `:read-only` (the install default). If `mb git-sync add-collection 12` returns `Metabase returned 400 … Cannot change synced collections when remote-sync-type is read-only.`, switch first with: ```bash mb setting set remote-sync-type '"read-write"' --profile ``` (`setting set` parses the value as strict JSON — mind the inner double quotes; see `core`.) The server also rejects switching to `:read-only` while the Remote Sync collection is dirty; export or `--force` import first if you're going the other way. **Verifying the result.** `mb git-sync status --profile --json` lists the flagged collections under `synced_collections`, and `mb collection get --json` shows the per-collection `is_remote_synced` flag. ## Published table metadata (Library) and sync scope Table and field metadata — table/field descriptions, semantic types (`type/PK`, `type/FK`), FK targets, plus segments and measures on the table — serializes for **Library-published tables only**, under `databases//schemas//tables//…` in the repo. Eligibility is two-gated: the table must be published (`mb library publish`), **and** the Library collection holding it must itself carry `is_remote_synced: true`. An ordinary warehouse table, or a transform's target table that isn't published, never serializes — a transform's YAML carries only the transform definition (query, target, description), not the output table's field metadata. The classic trap: publish tables, write field metadata, then `git-sync dirty` comes back empty and nothing lands in the repo. That does not mean git-sync can't carry table metadata — it means the Library collection isn't in the sync scope, so nothing was eligible for dirty-tracking when the writes happened. Check the scope (`synced_collections` in `status`), then: ```bash mb library get --profile --json # Library Data collection id mb git-sync add-collection --profile mb git-sync stash --new-branch -m "..." --profile # or create-branch + export ``` Flagging the collection records it for the next export, which serializes its current content — including already-published tables and their field metadata. `mb library publish` prints a reminder when the target collection is outside the sync scope on an instance with a configured remote. ## Don't (git-sync-specific) - Don't turn instance-side changes into hand-written repo files. When the changes were made against the instance, export them (`stash` / `create-branch` + `export`) and PR the exported branch; reconstructing them as YAML by hand — or pushing files in paths/formats the serializer doesn't own — produces content that never applies on import, and pushing behind Metabase's back races its own sync tasks. Hand-editing YAML belongs to the repo-first workflow, in the serialized layout the repo already uses. - Don't conclude from an empty `dirty` list that a change type isn't tracked. Dirty-tracking only records changes to _eligible_ objects; the usual cause is scope (the collection isn't flagged — see "Published table metadata"), not capability. Check `synced_collections` in `status` before concluding. - Don't run `git-sync import --force` or `git-sync export --force` without explicit user confirmation. Both are lossy — `--force` import discards instance-side work, `--force` export overwrites the remote branch. - Don't drive `git-sync` against a Metabase instance that doesn't have remote-sync configured — every verb returns an error pointing at the missing `remote-sync-*` settings. To check: `mb setting get remote-sync-url --profile --json`. - Don't author content directly via `card create` / `transform create` and then assume `git-sync export` will commit it cleanly — the instance and repo can drift if you mix direct API writes with sync-tracked changes. If you do, follow direct writes immediately with `git-sync export -m "..."` to keep them in step. - Don't omit `-m` on `export` if the user wants a meaningful commit message — the default server-generated message is generic. - Don't `git-sync export` to `main`/`master` without explicit user confirmation — sync work is conventionally on a feature branch. See "Branch guard" above. - Don't reach for `mb setting set` to mark a collection as remote-synced — that endpoint writes single-key settings, not the bulk `collections` map. Use `mb git-sync add-collection ` / `mb git-sync remove-collection ` (above), and remember the toggle cascades to descendants.