Skip to content

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

docs - remote sync providers (#70969)

Jeff Bruemmere8bc1db48757
diff --git a/docs/installation-and-operation/remote-sync.md b/docs/installation-and-operation/remote-sync.md
index 193b18a32fd..3c9af96c30f 100644
--- a/docs/installation-and-operation/remote-sync.md
+++ b/docs/installation-and-operation/remote-sync.md
@@ -7,8 +7,6 @@ description: Version control your dashboards, questions, and transforms. Sync yo
{% include plans-blockquote.html feature="Remote sync" %}
-## Overview
-
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:
- Top-level collections (dashboards, questions, models, metrics)
@@ -16,9 +14,9 @@ Remote Sync lets you develop analytics content in your Metabase and automaticall
- Snippets
- Transforms
-Metabase doesn't sync any of your data. What it stores in Git are [YAML files](./serialization.md#example-of-a-serialized-question) describing your analytics content. Your actual data stays in your databases and never goes to GitHub.
+Metabase doesn't sync any of your data. What it stores in Git are [YAML files](./serialization.md#example-of-a-serialized-question) describing your analytics content. Your actual data stays in your databases and never leaves your Metabase.
-### How Remote Sync works
+## How Remote Sync works
Here's a basic remote-sync workflow:
@@ -30,46 +28,74 @@ Here's a basic remote-sync workflow:
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.
-### Key concepts
+## Key concepts
-**Remote Sync has two modes for different roles**:
+### 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. In Read-only mode, you also can't edit transforms (even if transforms syncing wasn't enabled in read-write mode), can't edit Library content, and can't create segments or measures on published tables. You can set up [auto-sync](#pulling-changes-automatically) to automatically pull approved changes every five minutes.
+- **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. 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)), can't edit Library content, and can't create segments or measures on published tables. You can set up [auto-sync](#pulling-changes-automatically) to automatically pull approved changes every five minutes.
+
+### You choose what to sync
+
+You can sync:
+
+- Your [Library](../data-studio/library.md)
+- [Transforms](../data-studio/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
+
+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:
-**You choose what to sync**: You can sync the Library, any top-level collections, and transforms. Everything inside selected collections (including sub-collections) is versioned and synchronized with your repository. If you use [Tenants](../embedding/tenants.md), you can also sync shared collections.
+- 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
+
+### Content is stored as YAML files
-**Items in synced collections must be self-contained**: Everything a dashboard or question needs must be [inside a synced collection](#items-in-synced-collections-cant-depend-on-items-outside-of-synced-collections).
+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.
-**Content is stored as [YAML files](./serialization.md#example-of-a-serialized-question)**: Remote Sync stores your content as YAML files 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 excludes table metadata
-**Remote Sync excludes table metadata**: Column types, descriptions, and visibility settings don't sync. 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](./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
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 personal access token for development](#2-create-a-personal-access-token-for-development)
+2. [Create a token for your read-and-write Metabase](#2-create-a-token-for-your-read-and-write-metabase)
3. [Connect your development Metabase to your repository](#3-connect-your-development-metabase-to-your-repository)
-4. [Select collections to sync](#4-select-collections-to-sync)
+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 personal access token for production](#6-create-a-personal-access-token-for-production)
+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)
### 1. Set up a repository to store your content
-Before you connect Metabase to your Git repository, create a [new GitHub repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository). Initialize the repo with a README.md.
+Before you connect Metabase to your Git repository, create a new repository. Supported providers include:
+
+- [GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository)
+- [GitLab](https://docs.gitlab.com/user/project/index.html#create-a-blank-project)
+- [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/create-a-repository/)
-### 2. Create a personal access token for development
+Initialize the repo with a README.md.
-Create a [GitHub fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for your repository with these permissions:
+### 2. Create a token for your read-and-write Metabase
-- **Contents:** Read and write
-- **Metadata:** Read-only (required)
+Create a personal access token with read and write repository access. Copy the token immediately; you won't be able to see the token again.
-Copy the token immediately after generating it.
+- **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 [Atlassian account settings](https://id.atlassian.com/manage-profile/security) under **Security**, click **Create API token with scopes**. Select Bitbucket, search for "repos", and grant `read:repository:bitbucket` and `write:repository:bitbucket` (write does not include read). Tokens expire and can't be modified after creation.
### 3. Connect your development Metabase to your repository
@@ -83,13 +109,13 @@ In the Metabase instance that you use for development:
2. Enter your repository URL:
- - For example, `https://github.com/your-org/your-repo`. The repository must already exist and be initialized with at least one commit.
+ - 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-personal-access-token-for-development). 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-read-and-write-metabase). Metabase encrypts your token before storing it.
5. Save and test the connection:
@@ -97,13 +123,9 @@ In the Metabase instance that you use for development:
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.
-### 4. Select collections to sync
+### 4. Select what to sync
-You can select any top-level collection under Our Analytics to sync with Git. In the Remote Sync settings, choose which collections you want to track.
-
-Collections you select for syncing must pass referential integrity checks—they need to be self-contained, meaning all dependencies (like models referenced by questions) must also be in synced collections.
-
-If you use [tenants](../embedding/tenants.md), you can also choose to sync [shared collections](../embedding/tenants.md#collection-types).
+Select what you [want to sync](#you-choose-what-to-sync).
### 5. Push your changes to your repository
@@ -121,14 +143,13 @@ Check your repository; you should see the collection.
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.
-### 6. Create a personal access token for production
+### 6. Create a token for your read-only Metabase
-Create a [GitHub fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for your repository with these permissions:
+Create a personal access token with read-only repository access. Copy the token immediately; you won't be able to see the token again.
-- **Contents:** Read-only
-- **Metadata:** Read-only (required)
-
-Copy the token immediately after generating it — you'll need to paste it into your production Metabase.
+- **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 [Atlassian account settings](https://id.atlassian.com/manage-profile/security) under **Security**, click **Create API token with scopes**. Select Bitbucket and grant `read:repository:bitbucket` only.
### 7. Connect your production Metabase to your repository
@@ -140,7 +161,7 @@ In your production Metabase instance:
2. Enter your repository URL:
- - Use the same repository as your development Metabase, for example, `https://github.com/your-org/your-repo`.
+ - 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**.
@@ -164,7 +185,12 @@ At this point, you should be all set up. Exit Admin, then reload your browser. Y
### 8. Configure transforms syncing (optional)
-To version control your data transformation logic, you can sync your [Transforms](../data-studio/transforms/transforms-overview.md) including all your tags and jobs. Transform syncing is all or nothing: Metabase will sync your entire transforms namespace. You can't selectively sync specific transform folders.
+To version your data transformation logic, you can sync your [Transforms](../data-studio/transforms/transforms-overview.md), including all your tags and jobs. Some things to keep in mind:
+
+- **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.
## An example dev-to-production workflow
@@ -205,7 +231,7 @@ On your production Metabase instance:
- [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 can't depend on items outside of synced collections](#items-in-synced-collections-cant-depend-on-items-outside-of-synced-collections)
+- [Items in synced collections must be self-contained](#items-in-synced-collections-must-be-self-contained)
### Synced collections in the UI
@@ -223,16 +249,6 @@ When you remove content from a synced collection in Read-write mode and push tha
Content in other Metabases that depended on this item may break since the dependency will no longer be in a synced collection.
-### Items in synced collections can't depend on items outside of synced collections
-
-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 models
-- Dashboards with questions
-- Click behaviors linking to other items
-- Filters that pick values from other questions
-- @ mentions in documents
-
### 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.
@@ -264,10 +280,6 @@ Collections
└── Giant Sloth Statistics
```
-## Remote Sync uses serialization
-
-Remote Sync serializes your Metabase content as YAML files in your repo. YAML files use Metabase [serialization format](./serialization.md). See [Serialization docs](./serialization.md) for more information on the format.
-
## 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.
@@ -289,7 +301,7 @@ Remote Sync uses the same serialization format as the [Metabase CLI serializatio
- Alerts and subscriptions
- Database connections
- Personal collections
-- Table metadata (column types, descriptions, visibility settings, etc.)
+- Table metadata (table names, column types, descriptions, visibility settings, etc.)
## Branch management
@@ -393,8 +405,6 @@ By default, Metabase will check for and pull changes from the branch you specify
## Disabling Remote Sync
-To disable Remote Sync, go to the Remote Sync settings page in Admin.
-
To disable Remote Sync:
1. Go to **Admin** > **Settings** > **Remote sync**.