Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

docs: reframe Remote sync around the Library, move to semantic-layer (#85727)

Michael Eby10f27cdeb11e
diff --git a/README.md b/README.md
index 44b64f422ab..a8ac5ad7e1b 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ You get expert support, backups, upgrades, an SMTP server, SSL certificate, SoC2
- Use [documents](https://www.metabase.com/docs/latest/documents/introduction) for long-form data analysis, and invite people to comment.
- [Transform](https://www.metabase.com/docs/latest/data-modeling/transforms/transforms-overview) raw data into analytics-ready tables, track down broken dependencies, and define canonical metrics in Metabase's [Data Studio](https://www.metabase.com/docs/latest/data-modeling/data-studio).
- Set up [alerts on your data](https://www.metabase.com/docs/latest/questions/alerts), or schedule [dashboard subscriptions](https://www.metabase.com/docs/latest/dashboards/subscriptions) to email, Slack, or even a webhook.
-- Curate content in a [Library](https://www.metabase.com/docs/latest/data-modeling/semantic-layer/library), and [version your work with Git](https://www.metabase.com/docs/latest/installation-and-operation/remote-sync).
+- Curate content in a [Library](https://www.metabase.com/docs/latest/data-modeling/semantic-layer/library), and [version your work with Git](https://www.metabase.com/docs/latest/data-modeling/semantic-layer/remote-sync).
- [Embed Metabase in your app](https://www.metabase.com/docs/latest/embedding/introduction), with components for charts, dashboards, data browser, AI chat, and more. You can even put [an entire Metabase](https://www.metabase.com/docs/latest/embedding/full-app-embedding) in your app.
- Set granular [permissions](https://www.metabase.com/docs/latest/permissions/introduction) that work for both internal teams and embedded analytics, whether you co-locate your customer data, or give each customer their own database.
- Dark mode, content translations, and way more stuff than we can list here.
diff --git a/docs/README.md b/docs/README.md
index ee6225a805b..9196ec3fa31 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -50,7 +50,7 @@ Metabase's reference documentation.
- [Migrating to a production application database](./installation-and-operation/migrating-from-h2.md)
- [Development instances](./installation-and-operation/development-instance.md)
- [Serialization](./installation-and-operation/serialization.md)
-- [Remote sync](./installation-and-operation/remote-sync.md)
+- [Remote sync](./data-modeling/semantic-layer/remote-sync.md)
- [Metabase CLI](./installation-and-operation/metabase-cli.md)
- [Metabase JAR commands](./installation-and-operation/commands.md)
- [Supported browsers](./installation-and-operation/supported-browsers.md)
diff --git a/docs/ai/agent-driven-development.md b/docs/ai/agent-driven-development.md
index 229cabc29ad..0f86d3a03c7 100644
--- a/docs/ai/agent-driven-development.md
+++ b/docs/ai/agent-driven-development.md
@@ -11,7 +11,7 @@ redirect_from:
Now that we have actual genies, you can just ask the genies to create the content for you (call it "lamp-rubbing development").
-Give an agent the [Metabase CLI](../installation-and-operation/metabase-cli.md), and it can create content for you. But since LLMs can be unpredictable, we recommend developing content in a dev instance of Metabase, then using [Remote Sync](../installation-and-operation/remote-sync.md) to get your changes into production.
+Give an agent the [Metabase CLI](../installation-and-operation/metabase-cli.md), and it can create content for you. But since LLMs can be unpredictable, we recommend developing content in a dev instance of Metabase, then using [Remote Sync](../data-modeling/semantic-layer/remote-sync.md) to get your changes into production.
With this set up, a typical workflow using an agent with a development instance of Metabase would be:
@@ -31,7 +31,7 @@ To develop your Metabase content with an agent, we've put together a set of tool
- A Metabase instance to use for development.
- [**Metabase CLI**](../installation-and-operation/metabase-cli.md): a command-line client (`mb`) your agent uses to create content directly in your Metabase. Use the CLI with the [`/metabase-cli` skill](https://github.com/metabase/agent-skills/tree/main/skills/metabase-cli).
- [**Metabase Representation Format**](https://github.com/metabase/representations): the YAML schema and spec for every Metabase entity (questions, dashboards, collections, transforms, and so on). This is the format your content takes once you version it as files.
-- [**Remote Sync**](../installation-and-operation/remote-sync.md): push content from a Read-write Metabase into a git repo, and pull it into a Read-only Metabase in production.
+- [**Remote Sync**](../data-modeling/semantic-layer/remote-sync.md): push content from a Read-write Metabase into a git repo, and pull it into a Read-only Metabase in production.
## Initial setup
@@ -107,13 +107,13 @@ The agent writes the CLI commands and creates the questions and dashboard for yo
### 1. Configure Remote Sync on both Metabase instances
-In your development Metabase, configure [Remote Sync in Read-write mode](../installation-and-operation/remote-sync.md#setting-up-remote-sync) pointed at your repo.
+In your development Metabase, configure [Remote Sync in Read-write mode](../data-modeling/semantic-layer/remote-sync.md#setting-up-remote-sync) pointed at your repo.
Set up Remote Sync in your production Metabase in Read-only mode pointed at the same repo.
### 2. Create a branch from the Metabase UI
-In your development Metabase, [create a new branch](../installation-and-operation/remote-sync.md#creating-a-branch) for your work, like `feature/support-dashboard`. Metabase switches to the new branch. Your local Git checkout doesn't change which branch Metabase pushes to and pulls from.
+In your development Metabase, [create a new branch](../data-modeling/semantic-layer/remote-sync.md#creating-a-branch) for your work, like `feature/support-dashboard`. Metabase switches to the new branch. Your local Git checkout doesn't change which branch Metabase pushes to and pulls from.
### 3. Ask the agent to create content
@@ -125,7 +125,7 @@ Open your development Metabase and confirm the dashboard renders correctly and t
### 5. If you make any changes in your Metabase, push the new content to the branch
-To commit the work, [push the change from your Metabase](../installation-and-operation/remote-sync.md#committing-and-pushing-your-changes). If you don't push your changes from your Metabase to your repo, you could lose work the next time you pull changes into that Metabase.
+To commit the work, [push the change from your Metabase](../data-modeling/semantic-layer/remote-sync.md#committing-and-pushing-your-changes). If you don't push your changes from your Metabase to your repo, you could lose work the next time you pull changes into that Metabase.
### 6. Open a pull request
@@ -133,7 +133,7 @@ Open a pull request so your team can review the YAML diff. They can also use Rem
### 7. Merge the PR so production picks up the changes
-If you've enabled [auto-sync](../installation-and-operation/remote-sync.md#pulling-changes-automatically), your production Metabase (in Read-only mode) will pull the new main branch automatically on its next interval.
+If you've enabled [auto-sync](../data-modeling/semantic-layer/remote-sync.md#pulling-changes-automatically), your production Metabase (in Read-only mode) will pull the new main branch automatically on its next interval.
## Undoing the agent's changes
@@ -144,7 +144,7 @@ Since the agent uses the CLI to create content directly in Metabase, to undo cha
## Further reading
-- [Remote Sync](../installation-and-operation/remote-sync.md)
+- [Remote Sync](../data-modeling/semantic-layer/remote-sync.md)
- [Metabase CLI](../installation-and-operation/metabase-cli.md)
- [Metabase Representation Format](https://github.com/metabase/representations)
- [Agent skills](https://github.com/metabase/agent-skills)
diff --git a/docs/data-apps/build.md b/docs/data-apps/build.md
index ad3f7b19ede..2c70279c15b 100644
--- a/docs/data-apps/build.md
+++ b/docs/data-apps/build.md
@@ -21,7 +21,7 @@ You build and change data apps on your computer, with an AI coding agent and a d
Your agent does most of the work, but here's an overview of the end-to-end process:
-1. On your development Metabase, create a [Remote Sync](../installation-and-operation/remote-sync.md) branch for the app, and clone your Remote Sync repository to your computer.
+1. On your development Metabase, create a [Remote Sync](../data-modeling/semantic-layer/remote-sync.md) branch for the app, and clone your Remote Sync repository to your computer.
2. Describe the app to an AI coding agent, like Claude Code or Codex, on your computer. For example: "Create a Metabase data app to add, update, and delete products from the products table."
3. The agent uses the [Metabase CLI](../installation-and-operation/metabase-cli.md) to create the app on your development Metabase. The agent saves the questions and actions that the app runs to the [app's collection](#what-a-data-app-can-read-and-write).
4. The agent writes the app's code in your local clone of your Remote Sync repository. While the agent works, you [preview the app](#preview-the-app-on-your-computer) in your browser.
@@ -38,7 +38,7 @@ Your agent does most of the work, but here's an overview of the end-to-end proce
- The [Metabase CLI](../installation-and-operation/metabase-cli.md) (`mb`).
- Node.js 22.12 or later on your computer.
- A development Metabase, connected to your data warehouse, where you build and change your apps.
-- [Remote Sync](../installation-and-operation/remote-sync.md), to ship your apps from your development Metabase to production. Your Remote Sync repository also keeps each app's source code.
+- [Remote Sync](../data-modeling/semantic-layer/remote-sync.md), to ship your apps from your development Metabase to production. Your Remote Sync repository also keeps each app's source code.
- A [semantic layer](../data-modeling/semantic-layer/library.md) with the [published tables](../data-modeling/semantic-layer/published-tables.md) and metrics that your apps read. Your agent can publish tables and create metrics while it builds an app. But for apps that people rely on, use tables and metrics that you trust.
- If your apps write data, [actions enabled](../data-modeling/models/actions/introduction.md#enabling-actions-for-a-database) on the databases that your apps write to. An app that only shows data doesn't need actions, so the app can read from any database that Metabase connects to, even a database that doesn't support actions.
@@ -66,7 +66,7 @@ Only admins can edit an app's collection. You can't move the app's collection, m
1. [Install the Metabase CLI](../installation-and-operation/metabase-cli.md#install-the-cli), and [log the CLI in](../installation-and-operation/metabase-cli.md#authenticate-the-cli) as an admin to your development Metabase.
2. Install the [metabase-cli skill](../installation-and-operation/metabase-cli.md#the-metabase-cli-skill) for your agent. The CLI comes with its own skills for building data apps, and the metabase-cli skill tells your agent to load them.
-3. On your development Metabase, [create a Remote Sync branch](../installation-and-operation/remote-sync.md#creating-a-branch) for the app.
+3. On your development Metabase, [create a Remote Sync branch](../data-modeling/semantic-layer/remote-sync.md#creating-a-branch) for the app.
4. Start your agent in a local clone of your Remote Sync repository, so that the app's source code goes in the repository with the app. See [what syncs with a data app](#what-syncs-with-a-data-app).
5. Ask your agent to create a Metabase data app, and follow its instructions. For example:
@@ -99,21 +99,21 @@ Delete the key when you no longer need the preview.
## Ship the app to production with Remote Sync
-When [Remote Sync](../installation-and-operation/remote-sync.md) is on, it always syncs your data apps, so an app ships to production like the rest of your synced content. Use the same steps for a new app and for each change to an app:
+When [Remote Sync](../data-modeling/semantic-layer/remote-sync.md) is on, it always syncs your data apps, so an app ships to production like the rest of your synced content. Use the same steps for a new app and for each change to an app:
-1. On your development Metabase (in Read-write mode), [push your changes](../installation-and-operation/remote-sync.md#pushing-changes-to-git) to your branch. The push adds the app's manifest, bundle, and collection to the branch.
+1. On your development Metabase (in Read-write mode), [push your changes](../data-modeling/semantic-layer/remote-sync.md#pushing-changes-to-git) to your branch. The push adds the app's manifest, bundle, and collection to the branch.
2. In your local clone, switch to the branch, and pull it.
3. Commit the app's directory, `data_apps/<slug>/`, and push the commit. The commit adds the app's source code to the branch.
-4. On your development Metabase, [pull the changes](../installation-and-operation/remote-sync.md#pulling-changes-from-git). If you skip this step, the next push from Metabase has a conflict.
-5. Merge your branch into the branch that your production Metabase pulls from, for example with a [pull request](../installation-and-operation/remote-sync.md#step-4-create-a-pull-request).
-6. On your production Metabase (in Read-only mode), [pull the changes](../installation-and-operation/remote-sync.md#pulling-changes-from-git). If your production Metabase uses [auto-sync](../installation-and-operation/remote-sync.md#pulling-changes-automatically), it pulls the changes on its own within five minutes.
+4. On your development Metabase, [pull the changes](../data-modeling/semantic-layer/remote-sync.md#pulling-changes-from-git). If you skip this step, the next push from Metabase has a conflict.
+5. Merge your branch into the branch that your production Metabase pulls from, for example with a [pull request](../data-modeling/semantic-layer/remote-sync.md#step-4-create-a-pull-request).
+6. On your production Metabase (in Read-only mode), [pull the changes](../data-modeling/semantic-layer/remote-sync.md#pulling-changes-from-git). If your production Metabase uses [auto-sync](../data-modeling/semantic-layer/remote-sync.md#pulling-changes-automatically), it pulls the changes on its own within five minutes.
7. The first time that you ship an app, [add the groups](./manage.md#choose-who-can-open-an-app) that can open the app on your production Metabase.
If you let your agent use Git, the agent can do these steps for you.
Remote Sync doesn't sync an app's group access or its [status](./manage.md#make-an-app-live-or-a-draft) (live or draft), so each Metabase keeps its own. The first pull creates the app on your production Metabase as live, and only admins can open it until you add groups there. Later pulls keep the app's status on production, so you can make the app a draft on production without changing it on development.
-Your production Metabase also needs the published tables and metrics that the app reads. A pull doesn't check that the tables are published, but the pull fails if the app's questions use metrics that aren't in your production Library. So add your [Library](../installation-and-operation/remote-sync.md#you-choose-what-to-sync), which holds your semantic layer, to Remote Sync too. If your app uses actions, [enable actions](../data-modeling/models/actions/introduction.md#enabling-actions-for-a-database) on the production databases that the app writes to.
+Your production Metabase also needs the published tables and metrics that the app reads. A pull doesn't check that the tables are published, but the pull fails if the app's questions use metrics that aren't in your production Library. So add your [Library](../data-modeling/semantic-layer/library.md), which holds your semantic layer, to Remote Sync too. If your app uses actions, [enable actions](../data-modeling/models/actions/introduction.md#enabling-actions-for-a-database) on the production databases that the app writes to.
### What syncs with a data app
@@ -128,7 +128,7 @@ When your agent builds the app, it writes the bundle to `build/index.js` and upl
## Change a data app
-1. On your development Metabase, [create a Remote Sync branch](../installation-and-operation/remote-sync.md#creating-a-branch) for the change.
+1. On your development Metabase, [create a Remote Sync branch](../data-modeling/semantic-layer/remote-sync.md#creating-a-branch) for the change.
2. In your local clone of your Remote Sync repository, pull the latest source code, so that you start from the latest version of the app.
3. Start your agent in the clone, and ask for the change. The agent updates the code, builds the app again, and uploads the new version to your development Metabase.
4. [Ship the change to production](#ship-the-app-to-production-with-remote-sync).
diff --git a/docs/data-modeling/data-actions.md b/docs/data-modeling/data-actions.md
index 947126b931c..62b0ff56e4f 100644
--- a/docs/data-modeling/data-actions.md
+++ b/docs/data-modeling/data-actions.md
@@ -18,7 +18,7 @@ You can run data actions in two ways:
Unlike [model actions](./models/actions/introduction.md), data actions don't belong to a [model](./models/models.md). You don't need to create a model first, and data actions stay put when someone moves a model to the trash. But you can't add data actions to [dashboard buttons](../dashboards/actions.md). For a dashboard button, use a model action.
-If you [sync the Library](./semantic-layer/library.md#versioning-the-library) with [Remote Sync](../installation-and-operation/remote-sync.md), your data actions sync with it.
+If you [sync the Library](./semantic-layer/library.md#versioning-the-library) with [Remote Sync](semantic-layer/remote-sync.md), your data actions sync with it.
## Create a data action
diff --git a/docs/data-modeling/data-studio.md b/docs/data-modeling/data-studio.md
index 7f59a689d42..a7394907e76 100644
--- a/docs/data-modeling/data-studio.md
+++ b/docs/data-modeling/data-studio.md
@@ -42,7 +42,7 @@ The first time you open Data Studio, you'll land on the **Guide**: a quick tour
### Remote sync and settings
-- **[Remote sync](../installation-and-operation/remote-sync.md)**\*: Click **Set up remote sync** to connect a Git repository and sync your Library and transforms.
+- **[Remote sync](./semantic-layer/remote-sync.md)**\*: Click **Set up remote sync** to connect a Git repository and sync your Library and transforms.
- **Settings**: Turn [transforms](./transforms/transforms-overview.md) on or off for your Metabase. Settings only appear once you've [enabled transforms](./transforms/transforms-overview.md#enable-transforms).
\* Available on [Pro and Enterprise plans](https://www.metabase.com/pricing).
diff --git a/docs/data-modeling/semantic-layer/glossary.md b/docs/data-modeling/semantic-layer/glossary.md
index 186d296c943..c6a0fd8a688 100644
--- a/docs/data-modeling/semantic-layer/glossary.md
+++ b/docs/data-modeling/semantic-layer/glossary.md
@@ -45,7 +45,7 @@ Metabot will start using glossary terms automatically.
## Glossary terms sync with the Library
-If you [sync the Library to Git](./library.md#versioning-the-library) with [Remote sync](../../installation-and-operation/remote-sync.md), Metabase syncs your glossary terms along with the rest of the Library.
+If you [sync the Library to Git](./library.md#versioning-the-library) with [Remote sync](./remote-sync.md), Metabase syncs your glossary terms along with the rest of the Library.
## Glossary outside Data Studio
diff --git a/docs/installation-and-operation/images/read-only-settings.png b/docs/data-modeling/semantic-layer/images/read-only-settings.png
similarity index 100%
rename from docs/installation-and-operation/images/read-only-settings.png
rename to docs/data-modeling/semantic-layer/images/read-only-settings.png
diff --git a/docs/data-modeling/semantic-layer/images/read-write-settings.png b/docs/data-modeling/semantic-layer/images/read-write-settings.png
new file mode 100644
index 00000000000..35310c442bb
Binary files /dev/null and b/docs/data-modeling/semantic-layer/images/read-write-settings.png differ
diff --git a/docs/data-modeling/semantic-layer/library.md b/docs/data-modeling/semantic-layer/library.md
index 6aceab67a44..ad74fbaf3a2 100644
--- a/docs/data-modeling/semantic-layer/library.md
+++ b/docs/data-modeling/semantic-layer/library.md
@@ -129,7 +129,7 @@ Use **Library > Dashboards** for curated, official dashboards, like your company
**Library > Dashboards** holds only dashboards and their [dashboard questions](../../questions/introduction.md#saving-questions-to-dashboards). To save a question there, you save it to one of its dashboards.
-A Library dashboard can also use questions saved in other collections. But if you [sync the Library to Git](#versioning-the-library), everything the dashboard uses must be in a synced collection. See [Items in synced collections must be self-contained](../../installation-and-operation/remote-sync.md#items-in-synced-collections-must-be-self-contained).
+A Library dashboard can also use questions saved in other collections. But if you [sync the Library to Git](#versioning-the-library), everything the dashboard uses must be in a synced collection. See [Library content must be self-contained](./remote-sync.md#library-content-must-be-self-contained).
![Dashboards section of the semantic layer in Data Studio](./images/library-dashboards-section.png)
@@ -154,7 +154,7 @@ If you [duplicate a dashboard](../../dashboards/introduction.md#duplicating-a-da
## Versioning the Library
-You can [sync Library content to version control](../../installation-and-operation/remote-sync.md), giving you change history and the ability to publish content across environments. When you sync the Library, Metabase also syncs your SQL snippets, [data actions](../data-actions.md), and [glossary](glossary.md) terms.
+You can [sync Library content to version control](./remote-sync.md), giving you change history and the ability to publish content across environments. When you sync the Library, Metabase also syncs your SQL snippets, [data actions](../data-actions.md), and [glossary](glossary.md) terms.
## Library permissions
@@ -249,6 +249,6 @@ People who have View or Curate collection permissions to the **Library** subcoll
- [Published tables](./published-tables.md)
- [Glossary](./glossary.md)
- [Dependency graph](../tools/graph.md)
-- [Remote sync](../../installation-and-operation/remote-sync.md)
+- [Remote sync](./remote-sync.md)
- [Metrics](./metrics.md)
- [Snippets](../../questions/native-editor/snippets.md).
diff --git a/docs/data-modeling/semantic-layer/measures.md b/docs/data-modeling/semantic-layer/measures.md
index 3821e373080..b14c48f7ad4 100644
--- a/docs/data-modeling/semantic-layer/measures.md
+++ b/docs/data-modeling/semantic-layer/measures.md
@@ -17,7 +17,7 @@ You can define measures on any table. Measures on [published tables](published-t
## Create measures
-> If your instance is in read-only [remote sync](../../installation-and-operation/remote-sync.md) mode, and you enabled sync of the [Library](./library.md), you will not be able to create measures on tables published in the Library while in read-only mode.
+> If your instance is in read-only [remote sync](./remote-sync.md) mode, you will not be able to create measures on tables published in the Library while in read-only mode.
Measures are created in [Data Studio](../data-studio.md).
@@ -84,14 +84,13 @@ To **use** a measure, people need to:
## Only measures on published tables are synced to Git
-When using [Remote Sync](../../installation-and-operation/remote-sync.md):
+When using [Remote Sync](./remote-sync.md):
- Measures on tables that are _not_ published to the [Library](./library.md) are _not_ synced;
-- Measures on published tables are only synced if [_Library sync is enabled_](./library.md#versioning-the-library).
+- Measures on published tables sync with the Library.
-If your instance is in read-only Remote Sync mode, and the Library sync is enabled, you won't be able to create measures on published tables.
-You can, however, sync [Metrics](./metrics.md) on any tables by syncing their collection.
+Metrics in the Library sync with it, whether or not their tables are published.
## Limitations
diff --git a/docs/installation-and-operation/remote-sync.md b/docs/data-modeling/semantic-layer/remote-sync.md
similarity index 53%
rename from docs/installation-and-operation/remote-sync.md
rename to docs/data-modeling/semantic-layer/remote-sync.md
index 721c0569726..2f89a57ac68 100644
--- a/docs/installation-and-operation/remote-sync.md
+++ b/docs/data-modeling/semantic-layer/remote-sync.md
@@ -1,93 +1,72 @@
---
title: Remote sync
-description: Version control your dashboards, questions, and transforms. Sync your Library and other collections between development and production.
+description: Version control your Library and transforms in Git, and publish them from a development Metabase to a read-only production Metabase.
+redirect_from:
+ - /docs/latest/installation-and-operation/remote-sync
---
# Remote sync
{% include plans-blockquote.html feature="Remote sync" %}
-Remote Sync lets you develop analytics content in your Metabase and automatically deploy it to a read-only production Metabase through Git. Remote Sync can sync:
+Remote sync stores your [Library](./library.md) and [transforms](../transforms/transforms-overview.md) in a Git repository. You develop the Library in a development Metabase, push it to Git, review it in a pull request, and a read-only production Metabase pulls in the merged result.
-- Top-level collections (dashboards, questions, models, metrics)
-- Library content (published tables with their segments and measures, plus metrics, dashboards, snippets, data actions, and the glossary)
-- Transforms
-- [Data apps](../data-apps/build.md#what-syncs-with-a-data-app), with their bundles and collections
+Remote sync syncs:
-Metabase doesn't sync any of your data. All Metabase stores in Git are [YAML files](./serialization.md#example-of-a-serialized-question) that describe your analytics content. Your actual data stays in your databases and never leaves your Metabase.
+- The Library: published tables with their segments and measures, metrics, dashboards, documents, [data apps](../../data-apps/build.md#what-syncs-with-a-data-app), SQL snippets, [data actions](../data-actions.md), and the glossary.
+- Transforms: their tags, tests, folders, and Python libraries.
-## How Remote Sync works
+Metabase doesn't sync any of your data. All Metabase stores in Git are [YAML files](../../installation-and-operation/serialization.md#example-of-a-serialized-question) that describe your analytics content. Your actual data stays in your databases and never leaves your Metabase.
-Here's a basic remote-sync workflow:
+> **Metabase 65 and later syncs the Library and transforms.** Earlier versions let you pick which top-level collections to sync. Starting in Metabase 65, Remote sync syncs the Library and transforms, and there is no list of collections to choose from. If you already synced other collections before upgrading, your setup keeps working. See [Syncing other collections](#syncing-other-collections).
-1. Create a dashboard in a **Metabase configured in Read-write mode**.
-2. Push it to a Git branch.
+## How Remote sync works
+
+Here's a basic Remote sync workflow:
+
+1. In your development Metabase (Read-write mode), publish a table, create a metric, or build a dashboard in the Library.
+2. From the development Metabase, push the change to a Git branch.
3. Open a pull request for review.
-4. Merge the PR to production.
-5. Your **Metabase configured in Read-only mode** automatically pulls in the changes.
+4. Merge the pull request to your main branch.
+5. Your production Metabase (Read-only mode) pulls in the change.
-We'll cover [setting up Remote Sync](#setting-up-remote-sync), an [example dev-to-production workflow](#an-example-dev-to-production-workflow), [branch management](#branch-management), and some other odds and ends.
+Two Metabases that point at the same branch share the same Library. A new Metabase has nothing to push, so its first pull doesn’t conflict.
## Treat write access to your repository like admin access
When a Metabase pulls from your repository, it loads the YAML files on its branch _without_ checking who wrote them. Anyone who can push to that branch can change that Metabase's synced content. If you turn on [auto-sync](#pulling-changes-automatically), changes merged to the branch show up in your Metabase within minutes, and no one in Metabase approves them first.
-Your repository can't change users, groups, or permissions, because those [don't sync](#what-metabase-syncs). But when a pull creates a new collection, that collection gets the same permissions as its parent. A new top-level collection gets the same permissions as **Our analytics**.
+Your repository can't change users, groups, or permissions, because those [don't sync](#what-metabase-syncs). But when a pull creates a new collection, that collection gets the same permissions as its parent.
## Key concepts
-### Remote Sync has two modes for different roles
-
-- **Read-write mode**: Create and edit content. You can [push](#pushing-changes-to-git) and [pull](#pulling-changes-from-git) changes to and from your repository. Multiple Metabase instances can connect in Read-write mode, each working on [different branches](#branch-management).
-- **Read-only mode**: Read-only instances only [pull](#pulling-changes-from-git) changes (typically from your main branch) and don't allow direct editing of synced content. You can set up [auto-sync](#pulling-changes-automatically) to automatically pull approved changes every five minutes. In Read-only mode, you also can't:
- - Edit transforms. Transforms are always read-only in this mode. See [Configure transforms syncing](#8-configure-transforms-syncing-optional).
- - Edit Library content.
- - Create segments or measures on published tables.
- - Create, edit, or delete [data apps](../data-apps/build.md#ship-the-app-to-production-with-remote-sync).
-
-### You choose what to sync
-
-You can sync:
-
-- Your [Library](../data-modeling/semantic-layer/library.md)
-- [Transforms](../data-modeling/transforms/transforms-overview.md)
-- Any top-level collection under Our Analytics.
-- If you use [tenants](../embedding/tenants.md), you can also sync [shared collections](../embedding/tenants.md#collection-types).
-
-### Items in synced collections must be self-contained
+### Remote sync has two modes for different roles
-For Remote Sync to work properly, synced collections must be self-contained. Everything a dashboard or question needs must be inside one of the synced collections. This includes:
-
-- Questions that reference other questions
-- Dashboards with questions
-- Click behaviors linking to other items
-- Filters that pick values from other questions
-- @ mention of other items in documents
+- **Read-write mode for your development Metabase**: Create and edit Library content and transforms. You can [push](#pushing-changes-to-git) and [pull](#pulling-changes-from-git) changes to and from your repository. Multiple Metabases can connect in Read-write mode, each working on [different branches](#branch-management).
+- **Read-only mode for your production Metabase**: Read-only Metabases only [pull](#pulling-changes-from-git) changes, typically from your main branch. In Read-only mode, you can't edit Library content, create segments or measures on published tables, edit transforms, or create, edit, or delete [data apps](../../data-apps/build.md#ship-the-app-to-production-with-remote-sync). You can set up [auto-sync](#pulling-changes-automatically) to pull approved changes every five minutes. Keep your production Metabase in Read-only mode so that every change goes through Git.
### Content is stored as YAML files
-Remote Sync stores your content as [YAML files](./serialization.md#example-of-a-serialized-question) in your Git repository. Each dashboard, question, model, and document becomes a YAML file that can be reviewed in pull requests and versioned like code.
+Remote sync stores your content as [YAML files](../../installation-and-operation/serialization.md#example-of-a-serialized-question) in your Git repository. Each published table, metric, dashboard, document, and transform becomes a YAML file that can be reviewed in pull requests and versioned like code.
-### Remote Sync excludes table metadata
+### Remote sync excludes table metadata
-Table metadata doesn't sync. Table metadata includes things like table names, column types, descriptions, and visibility settings. If you need to version table metadata, use [serialization](./serialization.md) instead.
+Table metadata doesn't sync. Table metadata includes things like table names, column types, descriptions, and visibility settings. If you need to version table metadata, use [serialization](../../installation-and-operation/serialization.md) instead.
### One branch at a time per Metabase
You can only have [one branch at a time per Metabase](#branching-limitations).
-## Setting up Remote Sync
+## Setting up Remote sync
-You'll need to be an admin to set up Remote Sync.
+You'll need to be an admin to set up Remote sync.
1. [Set up a repository to store your content](#1-set-up-a-repository-to-store-your-content)
-2. [Create a token for your read-and-write Metabase](#2-create-a-token-for-your-read-and-write-metabase)
+2. [Create a token for your development Metabase](#2-create-a-token-for-your-development-metabase)
3. [Connect your development Metabase to your repository](#3-connect-your-development-metabase-to-your-repository)
-4. [Select what to sync](#4-select-what-to-sync)
-5. [Push your changes to your repository](#5-push-your-changes-to-your-repository)
-6. [Create a token for your read-only Metabase](#6-create-a-token-for-your-read-only-metabase)
-7. [Connect your production Metabase to your repository](#7-connect-your-production-metabase-to-your-repository)
-8. [Configure transforms syncing (optional)](#8-configure-transforms-syncing-optional)
+4. [Push your changes to your repository](#4-push-your-changes-to-your-repository)
+5. [Create a token for your production Metabase](#5-create-a-token-for-your-production-metabase)
+6. [Connect your production Metabase to your repository](#6-connect-your-production-metabase-to-your-repository)
### 1. Set up a repository to store your content
@@ -102,7 +81,7 @@ Initialize the repo with a README.md.
Anyone who can push to this repository can change content in your synced Metabases, so [limit who has write access](#treat-write-access-to-your-repository-like-admin-access).
-### 2. Create a token for your read-and-write Metabase
+### 2. Create a token for your development Metabase
> Skip this step if you're using a [local repo](#local-file-repositories).
@@ -111,14 +90,12 @@ Create a personal access token with read and write repository access. Copy the t
- **GitHub**: Create a [fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with **Contents: Read and write** and **Metadata: Read-only** permissions.
- **GitLab**: In **User Settings** > **Personal access tokens**, [create a token](https://docs.gitlab.com/user/profile/personal_access_tokens/) with **read_repository** and **write_repository** scopes. Tokens have an expiration date (your admin may set a maximum lifetime).
- **Bitbucket**: In your Bitbucket repository, go to **Repository settings** > **Security** > **Access tokens** and click **Create access token**. Give it a name and, under **Scopes**, select:
-
- **Repositories**: **Read** and **Write**
- **Pull requests**: **Read** and **Write**
Click **Create** and copy the token immediately, you can't view the token again after closing the dialog.
The created token must have these scopes (visible in the **View access token** dialog after creation):
-
- `repository`
- `repository:write`
- `pullrequest`
@@ -128,114 +105,99 @@ Create a personal access token with read and write repository access. Copy the t
![Development settings](./images/read-write-settings.png)
-You can put any Metabase into Read-write mode. We also offer [Development instances](./development-instance.md) that you can use for Remote Sync or any other kind of development.
+You can put any Metabase into Read-write mode. We also offer [Development instances](../../installation-and-operation/development-instance.md) that you can use for Remote sync or any other kind of development.
-In the Metabase instance that you use for development:
+In the Metabase that you use for development:
-1. Go to **Admin** > **Settings** > **Remote sync**.
+1. Go to **Admin** > **Settings** > **Remote sync**. You can also click **Set up remote sync** at the bottom of the Data Studio sidebar.
2. Enter your repository URL:
-
- For example, `https://github.com/your-org/your-repo` or `https://bitbucket.org/your-workspace/your-repo` (note the `https`). The repository must already exist and be initialized with at least one commit.
3. Select **Read-write mode**.
4. Add your access token:
-
- - Paste the personal access token (PAT) you created earlier. Make sure the token has [read and write permissions](#2-create-a-token-for-your-read-and-write-metabase). Metabase encrypts your token before storing it.
+ - Paste the personal access token (PAT) you created earlier. Make sure the token has [read and write permissions](#2-create-a-token-for-your-development-metabase). Metabase encrypts your token before storing it.
5. Test the connection:
-
- Click **Test connection** to check whether Metabase can reach your repository. If the connection fails, make sure your token has the appropriate permissions and hasn't expired. If you copied the token incorrectly, generate a new one.
- Metabase also checks the connection when you save your settings.
-6. (Optional) If you have [multi-tenant user strategy enabled](../embedding/tenants.md#enable-multi-tenant-strategy), you can also choose which [shared collection](../embedding/tenants.md#changing-tenant-strategy) to sync.
-
-> If you only want to sync your Library and transforms, you can set up remote sync from Data Studio instead: click **Set up remote sync** at the bottom of the Data Studio sidebar.
-
-### 4. Select what to sync
+6. Save your settings.
-Select what you [want to sync](#you-choose-what-to-sync).
+When you save, Metabase creates the Library if it doesn’t exist yet and turns on syncing for the Library and transforms. There are no collections to choose.
-### 5. Push your changes to your repository
+### 4. Push your changes to your repository
-Once you've added content, you'll see a yellow dot on the synced collections indicating uncommitted changes.
+Once you've added content to your Library, a yellow dot appears next to the Library section that changed (for example, **Semantic layer**), indicating uncommitted changes.
-1. At the top of the screen, click the branch name and select **Push changes**.
+1. At the top of the Data Studio sidebar, click the branch name and select **Push changes**.
-2. (Optional) Describe your changes (e.g., "Added dashboard on mammoth populations").
+2. (Optional) Describe your changes (e.g., "Published the Mammoth Populations table").
3. Click **Push changes** to commit and push your changes to your repository.
-Check your repository; you should see the collection.
+Check your repository. You should see a `collections` folder with the Library and a `databases` folder with your published tables.
-By default, you're pushing to your repository's main branch. However, you can choose (or create) a different branch so you can open pull requests for review. See [Branch management](#branch-management) for details on creating and switching branches.
+By default, you push to your repository's main branch. You can choose (or create) a different branch so you can open pull requests for review. See [Branch management](#branch-management) for details on creating and switching branches.
-### 6. Create a token for your read-only Metabase
+### 5. Create a token for your production Metabase
Create a personal access token with read-only repository access. Copy the token immediately; you won't be able to see the token again.
- **GitHub**: Create a [fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with **Contents: Read-only** and **Metadata: Read-only** permissions.
- **GitLab**: In **User Settings** > **Personal access tokens**, [create a token](https://docs.gitlab.com/user/profile/personal_access_tokens/) with **read_repository** scope only.
- **Bitbucket**: In your Bitbucket repository, go to **Repository settings** > **Security** > **Access tokens** and click **Create access token**. Under **Scopes**, select:
-
- **Repositories**: **Read**
- **Pull requests**: **Read**
Leave Write and all other scope groups unchecked. Click **Create** and copy the token immediately.
The created token must have these scopes (visible in the **View access token** dialog after creation):
-
- `repository`
- `pullrequest`
-### 7. Connect your production Metabase to your repository
+### 6. Connect your production Metabase to your repository
![Production settings](./images/read-only-settings.png)
-In your production Metabase instance:
+In your production Metabase:
1. Go to **Admin** > **Settings** > **Remote sync**.
2. Enter your repository URL:
-
- Use the same repository as your development Metabase, for example, `https://github.com/your-org/your-repo` (note the `https`).
3. Select **Read-only mode**.
4. Add your access token:
-
- Paste the read-only personal access token you created for this production Metabase.
5. Test the connection:
-
- Click **Test connection** to check whether Metabase can reach your repository. If the connection fails, verify your token has the appropriate permissions and hasn't expired.
- Metabase also checks the connection when you save your settings.
6. Sync your content:
- - Click "Pull changes now" to immediately sync content from your repository.
- - To keep your production instance automatically updated, toggle on "Auto-sync with git". Metabase will pull changes from your main branch every five minutes.
-
-In Read-only mode, synced collections appear in the regular collections list with a special icon to indicate that they're versioned and read-only.
+ - Click **Pull changes now** to immediately sync content from your repository.
+ - To keep your production Metabase automatically updated, toggle on **Auto-sync with git**. Metabase pulls changes from your main branch every five minutes.
-![Production Metabase](./images/read-only-view.png)
+A Read-only Metabase doesn’t create a Library of its own. It gets the Library from the pull.
-At this point, you should be all set up. Exit Admin, then reload your browser. You should see your synced collections in your production Metabase.
+At this point, you should be all set up. Exit Admin, then reload your browser. You should see the Library in your production Metabase.
-### 8. Configure transforms syncing (optional)
+## Syncing transforms
-To version your data transformation logic, you can sync your [Transforms](../data-modeling/transforms/transforms-overview.md), including their tags and tests. Some things to keep in mind:
+Remote sync versions your [transforms](../transforms/transforms-overview.md), including their tags, tests, folders, and Python libraries. Some things to keep in mind:
- **Jobs don't sync.** Each Metabase keeps its own jobs. Tag your transforms with the built-in hourly, daily, weekly, or monthly tags so the matching built-in jobs run them on every Metabase, or create the jobs you need on each Metabase.
-
-- **Transform syncing is all or nothing**: Metabase will sync your entire transforms namespace. You can't selectively sync specific transform folders.
-- **This setting only determines whether Metabase pushes transforms from Read-write mode.** When you _pull_ from a repository, all content present in the repo is loaded—including any transforms—regardless of this setting. Think of it like pulling a repo that has a new collection you hadn't previously synced: the setting doesn't filter what comes in, only what goes out.
-- **You can't edit transforms in read-only mode**, even if you haven't explicitly turned on transform syncing. Keeping transforms read-only prevents unintended overwrites on subsequent pulls.
-- **Use different databases for dev and production**. If you use transforms with Remote Sync, your development and production Metabases should connect to separate databases that share _identical_ schemas. If you use the same database for both, dev transforms would also change production data.
+- **Built-in tags and the default `common.py` don't sync.** Only custom tags and Python libraries you've changed are tracked.
+- **Transform syncing is all or nothing.** Metabase syncs your entire transforms namespace. You can't selectively sync specific transform folders.
+- **You can't edit transforms in Read-only mode.** Keeping transforms read-only prevents unintended overwrites on subsequent pulls.
+- **Use different databases for dev and production.** If you use transforms with Remote sync, your development and production Metabases should connect to separate databases that share _identical_ schemas. If you use the same database for both, dev transforms would also change production data.
## Local file repositories
-Remote Sync can point at a bare git repo on the same filesystem as your Metabase process, via a `file://` URL. Local repos come in handy for local development, especially alongside the [agent-driven development workflow](../ai/agent-driven-development.md).
+Remote sync can point at a bare git repo on the same filesystem as your Metabase process, via a `file://` URL. Local repos come in handy for local development, especially alongside the [agent-driven development workflow](../../ai/agent-driven-development.md).
Create a bare git repo on the same filesystem as your Metabase process:
@@ -243,7 +205,14 @@ Create a bare git repo on the same filesystem as your Metabase process:
git init --bare /path/to/your-repo.git
```
-A bare repo is required because Remote Sync pushes into it the same way it would push to a hosted remote. Non-bare repos refuse pushes to a checked-out branch.
+Remote sync needs at least one commit on the repository. To add one, clone the bare repo, make an empty commit, and push it:
+
+```sh
+git clone /path/to/your-repo.git seed && cd seed
+git commit --allow-empty -m "init" && git push origin HEAD:main
+```
+
+A bare repo is required because Remote sync pushes into it the same way it would push to a hosted remote. Non-bare repos refuse pushes to a checked-out branch.
### Point Metabase to your local repo
@@ -279,7 +248,7 @@ file:///Users/you/local-repo
## An example dev-to-production workflow
-Let's say your team wants to build a new analytics dashboard. Here's a workflow that ensures all production content goes through a review process.
+Let's say your team wants to publish a new table and build a dashboard with it. Here's a workflow that ensures all production content goes through a review process.
### Step 1: Create a new branch
@@ -287,94 +256,69 @@ In your development Metabase, go to **Admin** > **Settings** > **Remote sync** a
### Step 2: Create content in your development Metabase
-Create a dashboard called "Megafauna Analytics" and add some questions. Save the questions either to the dashboard itself or to a synced collection. Save the dashboard to a synced collection.
+In Data Studio, publish the `Megafauna` table to the Library and add a measure to it. Create a dashboard called "Megafauna Analytics" in the Library and add some questions to it.
### Step 3: Push to your development branch
-[Push your changes](#committing-and-pushing-your-changes) to `feature/megafauna-dashboard` with a commit message like "Add Megafauna Analytics dashboard".
+[Push your changes](#committing-and-pushing-your-changes) to `feature/megafauna-dashboard` with a commit message like "Add a Megafauna table and dashboard".
### Step 4: Create a pull request
In your Git repository:
1. Create a pull request from your branch, `feature/megafauna-dashboard`, to the main branch `main`.
-2. Review the changes to the YAML files representing your dashboards and questions.
+2. Review the changes to the YAML files representing your published table, measure, dashboard, and questions.
3. Someone who knows what they're doing approves and merges the PR.
### Step 5: Production automatically updates
-On your production Metabase instance:
+On your production Metabase:
-1. Within five minutes, Auto-sync detects the new commits on `main` (you can also manually import the changes).
-2. The "Megafauna Analytics" dashboard appears in production with all its questions.
+1. Within five minutes, Auto-sync detects the new commits on `main` (you can also manually pull the changes).
+2. The published table and the "Megafauna Analytics" dashboard appear in the Library with all their questions.
3. The content is read-only (people can view and use it, but can't edit it).
-## How synced collections work in Read-write mode
-
-- [Synced collections in the UI](#synced-collections-in-the-ui)
-- [Moving and deleting content in synced collections](#moving-and-deleting-content-in-synced-collections)
-- [Items in synced collections must be self-contained](#items-in-synced-collections-must-be-self-contained)
-
-### Synced collections in the UI
-
-You can select any top-level collection under Our Analytics to sync with Git. Synced collections show their current state with visual indicators: a yellow dot indicates unsynced local changes that need to be committed. At the top of the screen (in Data Studio, at the top of the sidebar), click the branch name to push or pull changes.
-
-If you are using [tenants](../embedding/tenants.md), you can also sync shared collections. You'll see the same yellow dot indicator for shared collections.
-
-In Read-only mode, synced collections appear in the regular collections list (not in a separate "Synced Collections" section) with a special icon to indicate they're versioned and read-only.
-
-### Moving and deleting content in synced collections
-
-When you remove content from a synced collection in Read-write mode and push that change, the content will also be removed from your production instance when it syncs. This applies to moving content out of a synced collection or deleting it entirely.
-
-Content in other Metabases that depended on this item may break since the dependency will no longer be in a synced collection.
-
-### Making sub-collections appear at the top level
+## How the Library works in Read-write mode
-Sometimes you might want synced content to appear at the top level of your navigation rather than nested under a synced collection. If you use [Tenants](../embedding/tenants.md), you can accomplish that with synced shared collections.
+### The Library in the UI
-If you aren't using tenants, you can use permissions to control how the collection hierarchy appears to different groups.
+When the Library has unsynced changes, a yellow dot appears next to the Library section that changed (for example, **Semantic layer**). At the top of the Data Studio sidebar, click the branch name to push or pull changes.
-1. **Organize content in sub-collections of your synced collection**. For example, you might have `Analytics/Mammoth Statistics` and `Analytics/Giant Sloth Statistics`.
+In the main Metabase sidebar, the Library sections (Data, Metrics, and Dashboards) show a sync icon to indicate that they are versioned.
-2. In your production Metabase, **set up permissions for embedded groups:** Groups should have:
- - **No view access** to the top-level synced collection itself
- - **View access** to specific sub-collections within the synced collection
+### Moving and deleting Library content
-For groups with these permissions, the sub-collections they can access will appear at the top level of navigation, as if they were root-level collections. They won't see the top-level synced collection that you have in your development Metabase.
+When you remove content from the Library in Read-write mode and push that change, Metabase also removes the content from your production Metabase when it syncs. This applies to moving content out of the Library or deleting it entirely.
-What you see in Read-write mode:
+Content in other Metabases that depended on this item may break, because the dependency is no longer in the Library.
-```
-Collections
-└── Analytics
- ├── Mammoth Statistics
- ├── Giant Sloth Statistics
-```
+### Library content must be self-contained
-What embedding groups see in Read-only mode (with no access to Analytics, but access to Mammoth Statistics and Giant Sloth Statistics):
+Everything a Library dashboard or question needs must be in the Library. This includes:
-```
-Collections
-├── Mammoth Statistics
-└── Giant Sloth Statistics
-```
+- Questions that reference other questions
+- Dashboards with questions
+- Click behaviors linking to other items
+- Filters that pick values from other questions
+- @ mentions of other items in documents
## What Metabase syncs
-Remote Sync uses the same serialization format as the [Metabase CLI serialization feature](./serialization.md), storing your content as YAML files in your Git repository.
+Remote sync uses the same serialization format as the [Metabase CLI serialization feature](../../installation-and-operation/serialization.md), storing your content as YAML files in your Git repository.
**What syncs:**
+- The Library's collection structure
+- Published tables with their segments and measures
+- Metrics
- Dashboards and their cards
-- Questions (saved queries and models)
-- Model metadata (column descriptions, display settings, etc.)
- Documents
+- [Data apps](../../data-apps/build.md#what-syncs-with-a-data-app). Metabase syncs the app's bundle and the Metabase items the app needs to run, not the app's source code. Keep the source code in your own repository so you can edit the app.
+- SQL snippets
+- [Data actions](../data-actions.md)
+- The glossary
- Timelines and events
-- Collection structure and metadata
-- Library content (published tables, metrics, dashboards, snippets, data actions, segments, measures, glossary)
-- Transforms (including tags, tests, and folders)
-- [Data apps](../data-apps/build.md#what-syncs-with-a-data-app), with their bundles and collections
+- Transforms, including tags, tests, folders, and Python libraries
**What doesn't sync:**
@@ -382,7 +326,8 @@ Remote Sync uses the same serialization format as the [Metabase CLI serializatio
- Alerts and subscriptions
- Database connections (see [Synced content that uses a database your Metabase doesn't have](#synced-content-that-uses-a-database-your-metabase-doesnt-have))
- Transform jobs
-- Personal collections
+- Built-in transform tags and the default `common.py`
+- Collections outside the Library, including personal collections (see [Syncing other collections](#syncing-other-collections))
- Table metadata (table names, column types, descriptions, visibility settings, etc.)
- A data app's live or draft status, and its group access
@@ -396,7 +341,7 @@ Branching is only available in Read-write mode.
### Creating a branch
-You can create branches in Metabase or directly in your Git repository. Branches created in Git will appear in Metabase once Metabase syncs with your repository.
+You can create branches in Metabase or directly in your Git repository. Branches created in Git appear in Metabase once Metabase syncs with your repository.
Before creating branches, push an initial commit to your main branch.
@@ -434,13 +379,13 @@ These limits only apply in Metabase. In your Git repository, anyone with write a
## Pushing changes to Git
-You can only push changes in a Metabase with Remote Sync set to Read-write mode.
+You can only push changes in a Metabase with Remote sync set to Read-write mode.
### Committing and pushing your changes
-When you make changes to items in a synced collection, a yellow dot appears on your synced collection (indicating uncommitted changes). To commit and push your changes:
+When you make changes to the Library or to transforms, a yellow dot appears next to the section that changed (indicating uncommitted changes). To commit and push your changes:
-1. At the top of the screen, click the branch name and select **Push changes**.
+1. At the top of the Data Studio sidebar, click the branch name and select **Push changes**.
2. (Optional) Describe your changes.
3. Click **Push changes** to push your changes to Git.
@@ -450,7 +395,7 @@ If the branch has new commits since you last pulled, Metabase asks how to handle
You can pull changes when in Read-write or Read-only mode.
-In Read-write mode, click the branch name at the top of the screen and select **Pull changes**. Metabase imports the latest content from Git.
+In Read-write mode, click the branch name at the top of the Data Studio sidebar and select **Pull changes**. Metabase imports the latest content from Git.
In Read-only mode, go to **Admin** > **Settings** > **Remote sync** and click **Pull changes now**.
@@ -475,44 +420,105 @@ When in doubt, create a new branch and push changes to that branch. That way you
In Read-only mode, you can set Metabase to auto-sync changes from your main branch.
-1. Navigate to **Admin** > **Settings** > **Remote sync**.
-2. Enable **Auto-sync with git**.
+1. Go to **Admin** > **Settings** > **Remote sync**.
+2. Turn on **Auto-sync with git**.
+
+By default, Metabase pulls changes from the branch you specify every five minutes. You can also manually sync as needed.
+
+## Syncing other collections
+
+Remote sync is built around the Library. Syncing other collections (also called custom collections) is off by default. To sync a collection outside the Library, including [shared tenant collections](../../embedding/tenants.md#collection-types), set the environment variable `MB_REMOTE_SYNC_CUSTOM_COLLECTIONS_ENABLED=true` and restart Metabase. There's no toggle for this setting in the UI.
+
+With custom collections turned on, **Admin** > **Settings** > **Remote sync** lists the Library, Transforms, and the top-level collections under Our Analytics so you can choose which to sync.
+
+With custom collections turned off:
+
+- Metabase refuses to mark a collection outside the Library as synced.
+- A pull or a serialization import that contains a synced collection outside the Library fails. To pull a branch that contains custom collections, you need to set `MB_REMOTE_SYNC_CUSTOM_COLLECTIONS_ENABLED=true`.
+
+### If you synced other collections before Metabase 65
+
+Your setup keeps working. On the first startup after you upgrade, if your Metabase already syncs a collection outside the Library, Metabase turns on custom collections for you. Metabase Cloud sets the environment variable for you.
+
+You can't turn custom collections off while any collection outside the Library is synced. Metabase refuses to start with `MB_REMOTE_SYNC_CUSTOM_COLLECTIONS_ENABLED=false` while a custom collection is synced. To turn custom collections off, first stop syncing those collections.
+
+If you can, move the content you want to version into the Library instead. Remote sync is built around the Library, and syncing other collections is a legacy path.
+
+### Items in synced collections must be self-contained
+
+The same rule that applies to the Library applies to any synced collection. Everything a dashboard or question needs must be inside one of the synced collections. See [Library content must be self-contained](#library-content-must-be-self-contained) for the list of dependencies.
+
+### Moving and deleting content in synced collections
+
+When you remove content from a synced collection in Read-write mode and push that change, Metabase also removes the content from your production Metabase when it syncs. This applies to moving content out of a synced collection or deleting it entirely.
+
+Content in other Metabases that depended on this item may break, because the dependency is no longer in a synced collection.
+
+### Making sub-collections appear at the top level
+
+Sometimes you might want synced content to appear at the top level of your navigation rather than nested under a synced collection. If you use [Tenants](../../embedding/tenants.md), you can accomplish that with synced shared collections.
+
+If you aren't using tenants, you can use permissions to control how the collection hierarchy appears to different groups.
+
+1. **Organize content in sub-collections of your synced collection**. For example, you might have `Analytics/Mammoth Statistics` and `Analytics/Giant Sloth Statistics`.
+
+2. In your production Metabase, **set up permissions for embedded groups:** Groups should have:
+ - **No view access** to the top-level synced collection itself
+ - **View access** to specific sub-collections within the synced collection
+
+For groups with these permissions, the sub-collections they can access appear at the top level of navigation, as if they were root-level collections. They won't see the top-level synced collection that you have in your development Metabase.
+
+What you see in Read-write mode:
+
+```
+Collections
+└── Analytics
+ ├── Mammoth Statistics
+ ├── Giant Sloth Statistics
+```
+
+What embedding groups see in Read-only mode (with no access to Analytics, but access to Mammoth Statistics and Giant Sloth Statistics):
-By default, Metabase will check for and pull changes from the branch you specify every five minutes. You can also manually sync as needed.
+```
+Collections
+├── Mammoth Statistics
+└── Giant Sloth Statistics
+```
-## Disabling Remote Sync
+## Disabling Remote sync
-To disable Remote Sync:
+To disable Remote sync:
1. Go to **Admin** > **Settings** > **Remote sync**.
-2. Click **Disable Remote Sync**.
+2. Click **Disable remote sync**.
3. In the confirmation dialog, click **Disable**.
-- All remote sync settings are cleared, including the repository URL, access token, and branch information.
-- Your synced collections and their content remain in your Metabase (they're not deleted).
+- Metabase clears all Remote sync settings, including the repository URL, access token, and branch information.
+- Your Library, transforms, and any other synced content remain in your Metabase (they're not deleted).
- Synced collections become regular collections that you can edit like any other collection.
-- You can re-enable Remote Sync later by reconnecting to a repository, but any changes you made to the collection after disabling can be overwritten if you enable sync again.
-
-## Migrating existing content to Remote Sync
+- You can re-enable Remote sync later by reconnecting to a repository, but any changes you made after disabling can be overwritten when you enable sync again.
-If you already have content in your Metabase, you can gradually adopt Remote Sync. Content that lives outside synced collections remains unaffected—you can continue working with it normally while you migrate content into a synced collection over time.
+## Migrating existing content to Remote sync
-Make sure you move any dependencies (like models referenced by questions) into synced collections, since [synced content must be self-contained](#key-concepts).
+If you already have content in your Metabase, you can adopt Remote sync gradually. Content that lives outside the Library remains unaffected. You can keep working with it normally while you move content into the Library over time.
+
+Make sure you move any dependencies (like models referenced by questions) into the Library, since [Library content must be self-contained](#library-content-must-be-self-contained).
### If you already have a repo with serialized Metabase data
Keep doing what you're doing.
-If you want to switch fully to Remote Sync, we recommend starting with a new repo:
+If you want to switch fully to Remote sync, we recommend starting with a new repo:
-1. Check out a new branch in your Metabase instance in Read-write mode.
-2. Import your data to your Metabase instance with the serialization command as you normally would.
-3. Move the content you want to sync into a synced collection.
+1. Check out a new branch in your Metabase in Read-write mode.
+2. Import your data to your Metabase with the serialization command as you normally would.
+3. Move the content you want to sync into the Library.
4. Push up your changes to the new repo.
-Remote Sync does NOT sync table metadata, so if you're importing and exporting your [table metadata](../data-modeling/metadata/metadata-editing.md), you should stick with serialization.
+Remote sync does NOT sync table metadata, so if you're importing and exporting your [table metadata](../metadata/metadata-editing.md), you should stick with serialization.
## Further reading
-- [Library](../data-modeling/semantic-layer/library.md)
-- [Serialization](./serialization.md)
+- [Library](./library.md)
+- [Transforms](../transforms/transforms-overview.md)
+- [Serialization](../../installation-and-operation/serialization.md)
diff --git a/docs/data-modeling/semantic-layer/segments.md b/docs/data-modeling/semantic-layer/segments.md
index 4234ac38755..e043e127f8b 100644
--- a/docs/data-modeling/semantic-layer/segments.md
+++ b/docs/data-modeling/semantic-layer/segments.md
@@ -24,7 +24,7 @@ To see all segments on a table, select the table in **Data Studio > Connected da
## Create segments
-> If your instance is in read-only [remote sync](../../installation-and-operation/remote-sync.md) mode, and you enabled sync of the [Library](./library.md), you will not be able to create segments on tables published in the Library while in read-only mode.
+> If your instance is in read-only [remote sync](./remote-sync.md) mode, you will not be able to create segments on tables published in the Library while in read-only mode.
Segments are created in [Data Studio](../data-studio.md).
@@ -73,12 +73,11 @@ To **use** a segment, people need to:
## Only segments on published tables are synced to Git
-When using [Remote Sync](../../installation-and-operation/remote-sync.md):
+When using [Remote Sync](./remote-sync.md):
- Segments on tables that are _not_ published to the [Library](./library.md) are _not_ synced;
-- Segments on published tables are only synced if [_Library sync is enabled_](./library.md#versioning-the-library).
+- Segments on published tables sync with the Library.
-If your instance is in read-only Remote Sync mode, and the Library sync is enabled, you won't be able to create segments on published tables.
## Limitations
diff --git a/docs/data-modeling/transforms/transforms-overview.md b/docs/data-modeling/transforms/transforms-overview.md
index b23dc37e5bc..845d728c91f 100644
--- a/docs/data-modeling/transforms/transforms-overview.md
+++ b/docs/data-modeling/transforms/transforms-overview.md
@@ -92,7 +92,7 @@ If you've set [`MB_TRANSFORMS_ENABLED`](../../configuring-metabase/environment-v
_Data Studio > Data transformation_
-> If you're using remote sync, you won't be able to create transforms if your instance is in ["read-only" sync mode](../../installation-and-operation/remote-sync.md).
+> If you're using remote sync, you won't be able to create transforms if your instance is in ["read-only" sync mode](../semantic-layer/remote-sync.md).
See [permissions needed to create transforms](#permissions-for-transforms).
@@ -135,7 +135,7 @@ _Data Studio > Data transformation_
You can edit the transform's name and description, query/script, target table, and incremental settings. You can edit the transform even if it already ran or is scheduled to run.
-If you're using remote sync, you won't be able to edit transforms if your instance is in ["read-only" sync mode](../../installation-and-operation/remote-sync.md).
+If you're using remote sync, you won't be able to edit transforms if your instance is in ["read-only" sync mode](../semantic-layer/remote-sync.md).
![Edit transform settings](../images/transform-edit-settings.png)
@@ -287,15 +287,9 @@ _Admin > Settings > Remote sync_
{% include plans-blockquote.html feature="Versioning transforms" %}
-You can check your transforms into git with [Remote Sync](../../installation-and-operation/remote-sync.md). If you enable transform sync, Metabase will serialize transforms as YAML files and push them to your specified GitHub repo branch.
+You can version your transforms with [Remote sync](../semantic-layer/remote-sync.md). Metabase serializes transforms as YAML files and pushes them to your repository along with the Library.
-To enable git sync of transforms:
-
-1. Go to Admin settings by clicking the **grid** icon in top right and select **Admin**.
-2. On the **Settings** tab, pick **Remote sync** in the left sidebar.
-3. Follow the steps to [Set up Remote Sync](../../installation-and-operation/remote-sync.md), and toggle **Transforms** sync on.
-
-Keep in mind that this setting only controls whether transforms are checked _into_ the git repo. The transform sync setting does _not_ affect how the instance behaves in read-only mode. If your instance is in read-only mode, you will not be able to create or edit transforms.
+If your Metabase is in Read-only mode, you can't create or edit transforms. See [Syncing transforms](../semantic-layer/remote-sync.md#syncing-transforms).
## Transforms vs models
diff --git a/docs/embedding/tenants.md b/docs/embedding/tenants.md
index 5840eb5f462..399823eff4d 100644
--- a/docs/embedding/tenants.md
+++ b/docs/embedding/tenants.md
@@ -183,7 +183,7 @@ You can have multiple shared collections and nested shared collections. You can
_Admin settings > Remote Sync_
-You can set up [Remote sync](../installation-and-operation/remote-sync.md) for shared collections. This means you'll be able to develop shared content in one Metabase, push it to a GitHub repo, and then have the shared content in your production Metabase always synced with that repo. See [Remote sync docs](../installation-and-operation/remote-sync.md) for more details.
+You can set up [Remote sync](../data-modeling/semantic-layer/remote-sync.md) for shared collections. This means you'll be able to develop shared content in one Metabase, push it to a GitHub repo, and then have the shared content in your production Metabase always synced with that repo. See [Remote sync docs](../data-modeling/semantic-layer/remote-sync.md) for more details.
## Tenant attributes
diff --git a/docs/exploration-and-organization/history.md b/docs/exploration-and-organization/history.md
index 84424b329f4..ea84c3366f0 100644
--- a/docs/exploration-and-organization/history.md
+++ b/docs/exploration-and-organization/history.md
@@ -6,7 +6,7 @@ title: History
Metabase keeps a version history for the previous fifteen versions for an entity. You can view changes, and revert to previous versions.
-On Metabase Pro and Enterprise plans, you can also version control most entities in Metabase, see [Remote Sync](../installation-and-operation/remote-sync.md).
+On Metabase Pro and Enterprise plans, you can also version control most entities in Metabase, see [Remote Sync](../data-modeling/semantic-layer/remote-sync.md).
## History for questions, dashboards, metrics, and models
diff --git a/docs/installation-and-operation/images/read-only-view.png b/docs/installation-and-operation/images/read-only-view.png
deleted file mode 100644
index 34f5ecf7b29..00000000000
Binary files a/docs/installation-and-operation/images/read-only-view.png and /dev/null differ
diff --git a/docs/installation-and-operation/images/read-write-settings.png b/docs/installation-and-operation/images/read-write-settings.png
deleted file mode 100644
index 437052515f9..00000000000
Binary files a/docs/installation-and-operation/images/read-write-settings.png and /dev/null differ
diff --git a/docs/installation-and-operation/metabase-cli.md b/docs/installation-and-operation/metabase-cli.md
index 4cce1de77c6..67a0c6a5409 100644
--- a/docs/installation-and-operation/metabase-cli.md
+++ b/docs/installation-and-operation/metabase-cli.md
@@ -13,7 +13,7 @@ The Metabase CLI (`mb`) is a command-line client for Metabase. `mb` logs in to a
- Node.js 20.6 or later, to install the CLI from npm.
- A Metabase instance on version 58 or later. Some command groups need a newer Metabase (for example, browser login needs version 63). The CLI tells you when that's the case.
-- A Pro or Enterprise plan for some command groups. For example, `git-sync` needs the premium [Remote sync](./remote-sync.md) feature.
+- A Pro or Enterprise plan for some command groups. For example, `git-sync` needs the premium [Remote sync](../data-modeling/semantic-layer/remote-sync.md) feature.
## Install the CLI
@@ -118,6 +118,6 @@ Pair the CLI with version control to build content with an agent in a developmen
- [@metabase/cli on npm](https://www.npmjs.com/package/@metabase/cli)
- [Agent-driven development](../ai/agent-driven-development.md)
- [Agent skills](https://github.com/metabase/agent-skills)
-- [Remote sync](./remote-sync.md)
+- [Remote sync](../data-modeling/semantic-layer/remote-sync.md)
- [Serialization](./serialization.md)
- [Metabase JAR commands](./commands.md)
diff --git a/docs/installation-and-operation/serialization.md b/docs/installation-and-operation/serialization.md
index 0ac02def46e..4a7f3664ba7 100644
--- a/docs/installation-and-operation/serialization.md
+++ b/docs/installation-and-operation/serialization.md
@@ -21,7 +21,7 @@ The [Metabase Representation Format](https://github.com/metabase/representations
## Serialization use cases
- **Staging environments**. Enable a staging-to-production workflow for important dashboards by exporting from a staging instance of Metabase and then importing them into your production instance(s).
-- **Version control**. Check the exported files into version control and audit changes to them, as the YAML files contained within the export are pretty readable. For a built-in Git workflow with push/pull from the Metabase UI, see [Remote Sync](./remote-sync.md).
+- **Version control**. Check the exported files into version control and audit changes to them, as the YAML files contained within the export are pretty readable. For a built-in Git workflow with push/pull from the Metabase UI, see [Remote Sync](../data-modeling/semantic-layer/remote-sync.md).
- **Duplicating assets to other Metabases**. Export the "template" data from a source Metabase and import them to one or more target instances.
Check out our guides for:
@@ -636,7 +636,7 @@ We're interested in how we can improve serialization to suit your workflow. [Upv
## Further reading
-- [Remote Sync](./remote-sync.md)
+- [Remote Sync](../data-modeling/semantic-layer/remote-sync.md)
- [Serialization tutorial](https://www.metabase.com/learn/metabase-basics/administration/administration-and-operation/serialization)
- [Database routing](../permissions/database-routing.md)
- [Multiple environments](https://www.metabase.com/learn/metabase-basics/administration/administration-and-operation/multi-env)
diff --git a/docs/util/data/nav.yml b/docs/util/data/nav.yml
index a3d9f0a3737..1746086a4ab 100644
--- a/docs/util/data/nav.yml
+++ b/docs/util/data/nav.yml
@@ -235,6 +235,8 @@ categories:
url: "data-modeling/semantic-layer/segments"
- name: "Glossary"
url: "data-modeling/semantic-layer/glossary"
+ - name: "Remote sync"
+ url: "data-modeling/semantic-layer/remote-sync"
- name: "Tools"
pages:
- name: "Schema viewer"
@@ -490,8 +492,6 @@ categories:
url: "installation-and-operation/observability-with-prometheus"
- name: "Serialization"
url: "installation-and-operation/serialization"
- - name: "Remote Sync"
- url: "installation-and-operation/remote-sync"
- name: "Commands"
url: "installation-and-operation/commands"
- name: "Metabase CLI"
diff --git a/enterprise/frontend/src/metabase-enterprise/remote_sync/components/RemoteSyncAdminSettings/RemoteSyncSettingsForm.tsx b/enterprise/frontend/src/metabase-enterprise/remote_sync/components/RemoteSyncAdminSettings/RemoteSyncSettingsForm.tsx
index 76ead6fc507..36b8c5e9a35 100644
--- a/enterprise/frontend/src/metabase-enterprise/remote_sync/components/RemoteSyncAdminSettings/RemoteSyncSettingsForm.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/remote_sync/components/RemoteSyncAdminSettings/RemoteSyncSettingsForm.tsx
@@ -169,7 +169,7 @@ export const RemoteSyncSettingsForm = ({
const SetupGuideLink = () => {
// eslint-disable-next-line metabase/no-unconditional-metabase-links-render -- This links only shows for admins.
const { url: docsUrl } = useDocsUrl(
- "installation-and-operation/remote-sync",
+ "data-modeling/semantic-layer/remote-sync",
{
anchor: "remote-sync",
},
diff --git a/frontend/src/metabase/admin/upsells/UpsellRemoteSync.tsx b/frontend/src/metabase/admin/upsells/UpsellRemoteSync.tsx
index d1c6f5674e4..5322d7f463b 100644
--- a/frontend/src/metabase/admin/upsells/UpsellRemoteSync.tsx
+++ b/frontend/src/metabase/admin/upsells/UpsellRemoteSync.tsx
@@ -22,7 +22,7 @@ export const UpsellRemoteSync = ({ source }: { source: string }) => {
location: source,
});
const { url: remoteSyncDocsUrl } = useDocsUrl(
- "installation-and-operation/remote-sync",
+ "data-modeling/semantic-layer/remote-sync",
);
if (hasRemoteSync || isPro) {