git-sync
/git-sync
Synchronizuje zawartość Metabase (karty, dashboardy, transformacje, snippety, kolekcje, metadane) między instancją a zdalnym git przez mb git-sync: status, import, eksport, gałęzie, stash i zarządzanie kolekcjami.
- Autor
- metabase ↗
- Repozytorium
- metabase-cli ↗
- Licencja
- AGPL-3.0
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 18
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.
AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.
- SKILL.md zawiera komentarze HTML (18). Nie widać ich w podglądzie Markdown, a model je czyta.
Co robi i kiedy
Synchronizuje zawartość Metabase (karty, dashboardy, transformacje, snippety, kolekcje, metadane) między instancją a zdalnym git przez mb git-sync: status, import, eksport, gałęzie, stash i zarządzanie kolekcjami.
Wyzwalacze z opisu
Oryginalny opis (EN)
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 and a preflight preview), 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 …`.
Jak działa
- Precondition: read state before mutating
- Import (remote → instance)
- Export (instance → remote)
- Branches
- Polling and cancelling
- Adding / removing a directory (collection) to sync
- Moving content into or out of a synced collection
- Published table metadata (Library) and sync scope
- Don't (git-sync-specific)
Podgląd SKILL.md
---
name: git-sync
description: 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 and a preflight preview), 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 …`.
allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
requires: [remoteSync]
---
# 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 flagged collections serialize, plus, unflagged: each data app's collection (with its app, `data_apps/<slug>/`), transforms (`remote-sync-transforms`), and snippets, data actions and glossary once the Library is synced. 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 the individual checks below) before `import` or `export`. Importing on a dirty instance silently rejects unless you pass `--force`.
<!-- requires: remoteSyncMerge -->
Exporting after the remote moved on ends in a `conflict` task unless the export merges or forces.
<!-- /requires -->
```bash
mb git-sync status --profile <n> --json # → remote configured, sync type, branch, dirty, current task
mb git-sync is-dirty --profile <n> --json # → {is_dirty: bool}; instance has unexported changes
mb git-sync dirty --profile <n> --json # → list the dirty objects
mb git-sync current-task --profile <n> --json # → in-flight task (or idle)
```
<!-- requires: remoteSyncRemoteChanges -->
```bash
mb git-sync has-remote-changes --profile <n> --json # → {has_changes: bool, remote_version, local_version, cached}; remote has unimported commits
```
<!-- /requires -->
**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 <id>` over delete + create (see the `transform` skill).
## Import (remote → instance)
```bash
mb git-sync import --branch <branch> --profile <n>
# 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 <name>` | 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 <ms>` | Polling deadline. Default 600 000. |
| `--interval <ms>` | Polling cadence. Default 2 000. |
Workflow:
1. Read state (above) — confirm `is_dirty: false` (or `--force` is intended).
2. `git-sync import --branch <branch>` — runs to terminal status by default.
<!-- requires: remoteSyncRemoteChanges -->
Between the two, confirm `has-remote-changes` reports `has_changes: true` (`--force-refresh` after your own push: the answer is cached).
<!-- /requires -->
<!-- requires: remoteSyncMerge -->
### Pull without discarding local work
`mb git-sync import --merge` keeps un-pushed local changes and folds the remote's in by a three-way merge, where a plain import refuses on a dirty instance and `--force` discards the local work. Entities changed on both sides, or no merge base (a remote whose history was rewritten, or an instance that has never synced), end the task in `conflict` without touching local state; the conflicting entities are listed in the task's `conflicts`. It does not combine with `--force`.
<!-- /requires -->
## Export (instance → remote)
```bash
mb git-sync export -m "commit message" --branch <branch> --profile <n>
```
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 <name>` | Defaults to the tracked `remote-sync-branch`. To push elsewhere, `stash` or `create-branch` first. |
| `-m, --message <s>` | 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.
<!-- requires: remoteSyncBranchGuard -->
`--branch` only asserts the branch you believe is tracked: the server rejects any other with a 409 naming the current one. Left out, the CLI reads the tracked branch first and refuses when none is tracked or the caller is not an admin.
<!-- /requires -->
<!-- requires: remoteSyncMerge -->
### Merge when the remote moved on
`mb git-sync export --merge -m "..."` folds the remote's changes in by a three-way merge, pushes the result and reconciles it into Metabase, where a plain export ends in a `conflict` task. Entities changed on both sides, or a remote whose history was rewritten, still end it in `conflict` and write nothing. It does not combine with `--force`.
<!-- /requires -->
<!-- requires: remoteSyncExportPreflight, remoteSyncMerge -->
### Preview the push first
```bash
mb git-sync export-preflight --profile <n> --json # → {has_changes, clean, conflicts, summary, force_push_casualties, reason}
```
A dry run against the live remote branch, writing nothing. Read it between the state check and the export, and decide from the fields:
| Answer | Meaning | Move |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `has_changes: false` | The remote has not moved past the last sync, or nothing has been synced yet — and then `force_push_casualties` is empty whatever the remote holds. | `export -m "..."` applies as-is. Don't read empty casualties on a never-synced instance as leave to `--force`. |
| `has_changes: true`, `reason: null` | The remote moved on. `clean` says whether a three-way merge would apply; `conflicts` names the entities changed on both sides; `summary` counts what a merge would fold in. | `clean: true`: `export --merge -m "..."`. `clean: false`: the conflicts need the user's call between the three options under "After a `conflict` task". A plain `export` ends in a `conflict` task, and so does `stash`: its new branch starts at the moved remote tip. |
| `reason: "history-rewritten"` | The remote was force-pushed or rebased, so there is no merge base. | Only `export --force` can push, and only with the user's explicit go-ahead; `force_push_casualties` is exactly what it would delete or overwrite. |
`force_push_casualties` is reported on every answer: it is the remote content a force push would discard instead of merging, so read it before ever passing `--force`. It is empty when nothing has been synced yet, yet `export --force` then replaces the remote's managed directories wholesale: check the remote before forcing a first export.
Read the preflight before every export: an export that finds the divergence itself ends in `conflict`, and after that these fields can't be trusted (below).
### After a `conflict` task
Never answer a conflict with a retry. A task that ends in `conflict` may make the server count the remote commit it saw as synced; the server version does not say whether it does. If it does, `has-remote-changes` and `export-preflight` report nothing pending, `force_push_casualties` comes back empty, and a retried `export`, `export --merge` or `import --merge` succeeds without bringing the remote's changes into Metabase; a later full or forced export can then overwrite them on the remote. So don't decide from those reads. Take the user's call between:
- **The remote's side:** `import --force`. Discards Metabase's un-pushed work.
- **Metabase's side:** `export --force`. Overwrites the remote, and its casualties can't be previewed after a conflict: show the user the remote's commits since the last export in git first.
- **Both, through a reviewed PR:**
1. Note the tracked branch from `mb git-sync status --json` (`branch`): this is `<original>`.
2. `mb git-sync create-branch <name>`
3. `mb git-sync export -m "..."`
4. `mb git-sync import --force`, which reloads the instance from `<name>`.
5. Open a PR from `<name>` into `<original>` and review its diff before it merges. If the server counted the conflict as synced, `<name>` starts at the remote's tip, so the PR can undo the remote's edits to the conflicting entities without a git conflict: restore any such edit in the PR.
6. Once the PR merges, `mb git-sync import --branch <original>` tracks the original branch again and loads the merged result.
<!-- /requires -->
### 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 <n> --json | jq -r '.branch'`.
If the branch is `main` or `master`, prompt with `AskUserQuestion`:
> "The instance is tracking `<branch>` — exporting commits straight to it. Switch to a feature branch first?"
>
> 1. **Create a feature branch** — agent suggests a name (e.g., `agent/<task>`); run `mb git-sync create-branch <name> --profile <n>`. This creates the branch on the remote from the last synced commit (the tracked branch's tip when nothing has synced yet) and switches the instance's tracked branch to it; the next `git-sync export` pushes the dirty state there.
> 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 <n> --json # list remote branches
mb git-sync create-branch <name> --profile <n> # create + switch sync to it
mb git-sync stash --new-branch <name> --profile <n> # 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 <n> # block on the in-flight task
mb git-sync cancel-task --profile <n> # 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; so do the unflagged ones above (a data app's collection can't be flagged). Everything else is local-only. Toggle one collection at a time:
```bash
mb git-sync add-collection <collection-id> --profile <n> --json
mb git-sync remove-collection <collection-id> --profile <n> --json
```
`<collection-id>` is a **positive integer** (no nano-id, `root` or `trash`). Get the id from `collection list` (see `core`).
Both return `{ success: true }`, plus a `task_id` when the toggle started a follow-up task.
**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.
**Custom collections.** Outside the Library, transforms, snippets and data actions, a flag answers 400 unless the admin setting `remote-sync-custom-collections-enabled` is on (a data app's collection can't be flagged at all).
**Mode prerequisite.** The server rejects toggles while `remote-sync-type` is `:read-only` (the install default; `mb git-sync status --json` reports it as `sync_type`). 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 <n>
```
(`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 <n> --json` lists the flagged collections under `synced_collections`, and `mb collection get <id> --json` shows the per-collection `is_remote_synced` flag.
## Moving content into or out of a synced collection
When remote sync is configured and the content is meant to be versioned, create it in the synced collection from the start. Nothing reaches git until `git-sync export`, and "Clean up before exporting" covers the drafts.
Synced content may only depend on synced content. Creating a card, dashboard, document, or collection in a synced collection, moving one in, or updating one inside it walks its dependencies, and the server refuses with 400 `Uses content that is not remote synced.` if any of them sits outside sync scope. What counts as a dependency:
- **Card:** the cards it is built on (source model, question, or metric), cards referenced as `{{#id}}` in native SQL, the card behind a filter's value source (`values_source_config.card_id`), and snippets — a snippet counts as synced only when the Library is.
- **Dashboard:** every dashcard's card, `series` cards, cards in parameter mappings and parameter value sources, actions, and the cards and dashboards a link card points to.
- Warehouse tables never count: a card on a raw table moves freely.
Three ways through:
1. **Bottom-up.** Move the sources first — models, then metrics, then the questions built on them — and the dashboard last. `card update <id> --body '{"collection_id":<synced-id>}'`, then `dashboard update <id> --body '{"collection_id":<synced-id>}'`.
2. **The whole containing collection.** `mb collection update <id> --parent-id <synced-id>` checks once, after the whole subtree has moved, so references inside the subtree pass.
3. **Dashboard questions.** A card created with `dashboard_id` (and the dashboard's `collection_id`) moves with its dashboard in the same transaction, so it never blocks the move.
The reverse holds too: archiving something, or moving it out of sync scope, is refused with 400 `Used by remote synced content.` while synced content still depends on it. The error names the dependents by model and id (`Used by remote synced content: Card 12, Dashboard 3. …`); move or archive those first, or leave the dependency in place.
Reading the inbound refusal: the error lists the blocking content as bare ids with no model type (`Uses content that is not remote synced: ids 412, 77. …`) — these are the dependencies to move first. Most are cards (`mb card get <id>`); otherwise try `mb dashboard get <id>` or `mb snippet get <id>`, and match the name against the content you meant to move.
<!-- requires: dependencyGraph -->
To plan the order before the first move, `mb dependency graph dashboard <id> --json` (or `card <id>`) lists everything the entity reads from; every card and snippet node outside the synced collection moves first.
<!-- /requires -->
<!-- requires: library -->
## 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/<db>/schemas/<schema>/tables/<table>/…` in the repo. Eligibility is two-gated: the table must be published (`mb library publish`), **and** Library Data must be synced; flag the Library root, as Data alone leaves out Metrics, Dashboards, snippets, data actions and glossary. 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. 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 collection list --profile <n> --json # the "type": "library" entry's id
mb git-sync add-collection <library-id> --profile <n>
mb git-sync stash --new-branch <branch> -m "..." --profile <n> # 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.
<!-- /requires -->
## Don't (git-sync-specific)
- Don't turn instance-side changes into hand-written repo files: export them and PR the exported branch (see the top of this skill). Files pushed behind Metabase's back race its own sync tasks.
- 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 — import, export, has-remote-changes and export-preflight answer `Remote sync is not configured.` To check: `mb git-sync status --profile <n> --json` succeeds and reports `remote_configured: false`.
- 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 move a dashboard or question into a synced collection before what it depends on, and don't retry a `Uses content that is not remote synced.` refusal unchanged. Move the listed dependencies first, move the whole containing collection, or build the content in the synced collection to begin with (see "Moving content into or out of a synced collection").
- Don't omit `-m` on `export` if the user wants a meaningful commit message — the default server-generated message is generic.
- 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 <id>` / `mb git-sync remove-collection <id>` (above), and remember the toggle cascades to descendants.
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · metabase/metabase-cli | 100 | AGPL-3.0 |
| mgiovani/cc-arsenal | 100 | MIT |
| erictechpro/super-board | 100 | MIT |
| Shahat87/ams-mission-kit | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 409f56105b5d (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 91metabase-cli
Obsługuje instancję Metabase z terminala przez CLI mb: profile logowania, bazy, karty, dashboardy, kolekcje, ustawienia, wyszukiwanie i synchronizację z git. - 100metabase-representation-format
Wyjaśnia format reprezentacji Metabase w YAML (kolekcje, karty, dashboardy, segmenty, akcje) i pomaga tworzyć, edytować oraz walidować takie pliki. - 100serdes-workflow
Eksportuje treści z działającej instancji Metabase, waliduje je checkerami, pozwala edytować YAML i importuje z powrotem, w pełnym obiegu serdes. - 100metabase
Tworzy i zarządza pytaniami, dashboardami i publicznymi linkami w Metabase, w tym zapisanymi pytaniami opartymi na zapytaniach SQL. - 100git-workflow
Obsługuje przepływ Git: commity, push, pull requesty, przeglądy kodu, czyszczenie gałęzi, merge, stash i rebase oraz przygotowanie kodu do wydania. - 100metabase-webhooks
Odbiera i uwierzytelnia webhooki alertów Metabase, sprawdza nagłówek Basic Authorization i obsługuje dane wyników z wizualizacją PNG.