The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
docs - remote sync providers (#70969)
Jeff Bruemmere8bc1db48757
diff --git a/docs/installation-and-operation/remote-sync.md b/docs/installation-and-operation/remote-sync.mdindex 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 worksHere'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 SyncYou'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 thaContent 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 levelSometimes 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 syncsRemote 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**.