Remote sync

Overview

Remote Sync lets you develop analytics content in a collection in a development Metabase and automatically deploy it to a read-only production Metabase through Git.

Remote Sync only syncs your dashboards, questions, and models—not your data or query results. What gets stored in Git are YAML files describing your analytics content. Your actual data stays in your databases and never goes to GitHub.

How Remote Sync works

Here’s a basic remote-sync workflow:

1. Create a dashboard in a Metabase configured in Read-write mode.
2. Push it 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.

We’ll cover setting up Remote Sync, an example dev-to-production workflow, branch management, and some other odds and ends.

Key concepts

Remote sync has two modes for different roles:

• Read-write mode: Create and edit content. You can push and pull changes to and from your repository. Multiple Metabase instances can connect in Read-write mode, each working on different branches.
• Read-only mode: Serves read-only content to users. Read-only instances only pull changes (typically from your main branch) and don’t allow direct editing of synced content. You can set up auto-sync to automatically pull approved changes every five minutes.

Only the synced collection is tracked: Each Metabase connected to Remote Sync has one special collection that syncs with Git. When you connect in Read-write mode, Metabase creates a collection called “Synced Collection” (you can rename it). Everything inside this collection (including sub-collections) is versioned and synchronized with your repository.

The synced collection must be self-contained: Everything a dashboard or question needs must be inside the synced collection. Content outside the synced collection won’t sync to your repository or appear in other Metabase instances.

Content is stored as YAML files: 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: Column types, descriptions, and visibility settings don’t sync. If you need to version table metadata, use serialization instead.

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
2. Create a personal access token for development
3. Connect your development Metabase to your repository
4. Add an item to your synced collection
5. Push your changes to your repository
6. Create a personal access token for production
7. Connect your production Metabase to your repository

1. Set up a repository to store your content

Before you connect Metabase to your Git repository, create a new GitHub repository. Initialize the repo with a README.md.

2. Create a personal access token for development

Create a Github fine-grained personal access token for your repository with these permissions:

• Contents: Read and write
• Metadata: Read-only (required)

Copy the token immediately after generating it.

3. Connect your development Metabase to your repository

You can put any Metabase into Read-write mode. We also offer Development instances that you can use for Remote Sync or any other kind of development.

In the Metabase instance that you use for development:

1. Go to Admin settings > Settings > Remote sync.

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.

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. Metabase encrypts your token before storing it.

5. Save and test the connection:

   • Click “Save changes”. Metabase will check whether it 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.

4. Add an item to your synced collection

When you first connect in Read-write mode, Metabase automatically creates a synced collection called “Synced Collection”—any content you add to it will be tracked in Git and can be pushed to your repository.

You can rename the Synced Collection if you want, and you can add sub-collections within it to organize your content.

1. Navigate to the “Synced Collection” in your Synced Collections section (look for it in the left sidebar).

2. Create or move content into the Synced Collection:

   • Create new content: Click “New” and choose a dashboard, question, or document. Save it to the Synced Collection.
   • Move existing content: Drag and drop items from other collections into the Synced Collection, or use the move option in the item’s menu.

Remember that the synced collection must be self-contained.

5. Push your changes to your repository

Once you’ve added content, you’ll see a yellow dot on your Synced Collection indicating uncommitted changes.

1. Click the up arrow (push) icon next to the Synced Collection in the left sidebar.

2. Enter a commit message describing your changes (e.g., “Added dashboard on mammoth populations”).

3. Click “Continue” to commit and push your changes to your repository.

Check your repository — you should see the collection.

About branches: By default, you’re pushing to your repository’s main branch. However, you can choose which branch to push your development work to, allowing you to open pull requests for review before merging to the branch that your production Metabase pulls from. See Branch management for details on creating and switching branches.

6. Create a personal access token for production

Create a GitHub fine-grained personal access token for your repository with these permissions:

• Contents: Read-only
• Metadata: Read-only (required)

Copy the token immediately after generating it — you’ll need to paste it into your production Metabase.

7. Connect your production Metabase to your repository

In your production Metabase instance:

1. Go to Admin settings > 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.

3. Select Read-only mode.

4. Add your access token:

   • Paste the read-only personal access token you created for this production Metabase.

5. Save and test the connection:

   • Click “Save changes”. Metabase will verify it can reach your repository. If the connection fails, verify your token has the appropriate permissions and hasn’t expired.

6. Sync your content:

   • Click “Pull changes” 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, the synced collection appears in the regular collections list with a special icon to indicate it’s versioned and read-only.

At this point, you should be all set up. Exit Admin settings, then reload your browser. You should see your synced collection in your production Metabase.

An example dev-to-production workflow

Let’s say your team wants to build a new analytics dashboard. Here’s a workflow that ensures that all production content goes through a review process.

Step 1: Create a new branch

In your development Metabase, click the branch dropdown in the synced collections section and create a new branch for your work, like feature/megafauna-dashboard.

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 the synced collection. Save the dashboard to the synced collection.

Step 3: Push to your development branch

1. You should see a yellow dot on your synced collection (indicating local changes).
2. Click the up arrow (push) icon next to your synced collection.
3. Enter a commit message: “Add Megafauna Analytics dashboard”.
4. Metabase commits your changes to the branch you’re working on and pushes them to your repo.

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.
3. Someone who knows what they’re doing approves and merges the PR.

Step 5: Production automatically updates

On your production Metabase instance:

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.
3. The content is read-only for users (they can view and use it, but can’t edit it).

How the synced collection works in Read-write mode

• The synced collection in the UI
• Moving and deleting content in the synced collection
• Items in the synced collection can’t depend on items outside of it

The synced collection in the UI

When you first connect in Read-write mode, Metabase creates a synced collection called “Synced Collection”. You can add items and sub-collections to it. The synced collection shows its current state with visual indicators: a yellow dot indicates unsynced local changes that need to be committed, and up/down arrows provide sync controls for pulling and pushing changes.

In Read-only mode, the synced collection appears in the regular collections list (not in a separate “Synced Collections” section) with a special icon to indicate it’s versioned and read-only.

Moving and deleting content in the synced collection

Deletions sync to production: When you remove content from the 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 the 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 the synced collection.

Items in the synced collection can’t depend on items outside of it

For Remote Sync to work properly, the synced collection must be self-contained. Everything a dashboard or question needs must be inside the synced collection. This includes:

• Questions that reference models
• Dashboards with questions
• Click behaviors linking to other content
• Filters that pick values from other questions or models
• @ mentions in documents

Exception: questions that reference snippets can’t be synced, since snippets live outside collections.

If you try to add a question that references a model, make sure the model is also in the synced collection.

Making sub-collections appear at the top level

If you’re using Metabase for embedding, you might want synced content to appear at the top level of your navigation rather than nested under the Synced Collection. Since all synced content must be in sub-collections of the Synced Collection, you can use permissions to control how the collection hierarchy appears to different groups.

1. In your development Metabase, Organize content in sub-collections of your Synced Collection. For example, you might have Synced Collection/Mammoth Statistics and Synced Collection/Giant Sloth Statistics.

2. In your production Metabase, Set up permissions for embedded groups: Groups should have:

   • No view access to the Synced Collection itself
   • View access to specific sub-collections within the Synced Collection

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.

What you see in Read-write mode:

Collections
└── Synced Collection
    ├── Mammoth Statistics
    ├── Giant Sloth Statistics

What embedding groups see in Read-only mode (with no access to Synced Collection, but access to Mammoth Statistics and Giant Sloth Statistics):

Collections
├── Mammoth Statistics
└── Giant Sloth Statistics

What Metabase syncs

Remote Sync uses the same serialization format as the Metabase CLI serialization feature, storing your content as YAML files in your Git repository.

What syncs:

• Dashboards and their cards
• Questions (saved queries and models)
• Model metadata (column descriptions, display settings, etc.)
• Documents
• Timelines and events
• Collection structure and metadata

What doesn’t sync:

• Users, groups, and permissions
• Alerts and subscriptions
• Snippets
• Database connections
• Personal collections
• Table metadata (column types, descriptions, visibility settings, etc.)

Branch management

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 the Metabase branch dropdown once Metabase syncs with your repository.

Before creating branches, push an initial commit to your main branch.

To create a new branch in Metabase:

1. Click the branch dropdown in the synced collections section.
2. Type a name for the new branch in the search box.
3. Press Enter to create the branch.

The new branch is created from your current commit (not the latest commit from the remote).

Switching branches

In the left sidebar under “SYNCED COLLECTIONS”, you’ll see a branch dropdown next to the synced collection name:

1. Click the branch dropdown to see available branches.
2. Select a different branch to switch to it.

If the branch doesn’t appear, ensure it exists in your Git repository and that the name matches exactly (branch names are case-sensitive).

If you have unsynced changes, Metabase will show a dialog asking what you want to do:

• Push changes to the current branch: Commits your changes to the current branch before switching.
• Create a new branch and push changes there: Saves your work to a new branch, keeping the original branch clean.
• Discard these changes: Throws away your uncommitted changes (can’t be undone).

The dialog shows you exactly which items have changed, so you can make an informed decision.

If you switch modes (from Read-write to Read-only or vice versa) with unpushed changes, you’ll be prompted to save or discard them. You cannot switch to Read-only mode with uncommitted changes.

If changes don’t appear after switching modes: Hard refresh your browser (Cmd/Ctrl + Shift + R).

Pushing changes to Git

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 the synced collection, a yellow dot appears on your synced collection (indicating uncommitted changes). To commit and push your changes:

1. Click the up arrow (push) icon next to the synced collection name in the left sidebar.
2. Enter a descriptive commit message explaining your changes.
3. Click “Continue” to push your changes to Git.

If you see a message that “Remote is ahead of local”, that means someone else pushed to the branch from another Metabase in Read-write mode. Pull the latest changes before pushing again.

Pulling changes from Git

You can pull changes when in Read-write or Read-only mode.

In Read-write mode, you can get the latest changes from your Git repository:

1. Click the down arrow (pull) icon next to your synced collection in the left sidebar.
2. Review any summary of incoming changes if shown.
3. Confirm the import.
4. Metabase updates your collections with the latest content from Git.

If changes don’t appear after pulling:

• Verify you’re on the correct branch.
• Hard refresh your browser (Cmd/Ctrl + Shift + R).
• If you encounter sync errors, review error messages in the sync dialog, manually resolve conflicts in your Git repository, then pull again.

In Read-only mode, go to Admin settings > Settings > Remote sync and click Pull changes.

Handling unsynced changes

If you have local uncommitted changes when trying to pull or switch branches, Metabase will prompt you with options:

• Push changes to the current branch: Commit your changes first, then proceed.
• Create a new branch and push changes there: Preserve your work on a new branch.
• Discard these changes: Throw away your uncommitted changes to accept what’s in Git.

When in doubt, create a new branch and push changes to that branch. That way you won’t lose any work.

Pulling changes automatically

In Read-only mode, you can set Metabase to auto-sync changes from your main branch.

1. Navigate to Admin settings > Settings > Remote sync.
2. Enable Auto-sync with Git.

By default, Metabase will pull any changes (if any) from the branch you specify every five minutes. You can also manually sync as needed.

Disabling Remote Sync

To disable Remote Sync, go to the Remote Sync settings page in Admin settings.

To disable Remote Sync:

1. Go to Admin settings > Settings > 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 collection and its content remain in your Metabase (they’re not deleted).
• The synced collection becomes a regular collection 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

If you already have content in your Metabase, you can gradually adopt Remote Sync. Content that lives outside the synced collection remains unaffected—you can continue working with it normally while you migrate content into the synced collection over time.

Make sure you move any dependencies (like models referenced by questions) into the synced collection, since synced 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:

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 the synced collection.
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, you should stick with serialization.