Przejdź do treści
Biblioteka skilli
Dane i analityka · Integracja z narzędziem

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.

Repozytorium
metabase-cli ↗
Licencja
AGPL-3.0
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
18
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

Co sprawdzić przed instalacją
  • 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

import the latest changesexport to gitpush my changes to the repoopen a PR with my Metabase changesgit syncdirty checkstash before pullingadd a collection to sync
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

  1. Precondition: read state before mutating
  2. Import (remote → instance)
  3. Export (instance → remote)
  4. Branches
  5. Polling and cancelling
  6. Adding / removing a directory (collection) to sync
  7. Moving content into or out of a synced collection
  8. Published table metadata (Library) and sync scope
  9. Don't (git-sync-specific)
Sekcje z nagłówków SKILL.md, w oryginale · 260 linii, 3 228 słów
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

RepozytoriumWynikLicencja
Ta strona · metabase/metabase-cli100AGPL-3.0
mgiovani/cc-arsenal100MIT
erictechpro/super-board100MIT
Shahat87/ams-mission-kit100MIT

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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.