When Metabase serialization fits your promotion workflow
Serialization fits a team that builds dashboards, saved questions and collections in one Metabase and needs the same content in a staging environment, a production instance or a regional copy. It exports that content as readable YAML files and imports them to create or update items in another instance. The feature is available only on Pro and Enterprise plans, so a team on Open Source or Starter should settle that question before designing a promotion process around it. Confirm the plan of both the source and target instances before you commit to the approach.
Metabase lists three use cases. The first is staging environments, where analysts test changes before they reach production users. The second is version control, because the exported YAML is human-readable, so teams can keep it in Git, review changes as diffs and keep a history of content edits. The third is duplicating template content, such as a standard set of dashboards that several instances should share. All three rely on the same export and import mechanism, so the decision is which one your workflow needs. Ask whether reviewers will read YAML diffs and who owns the production instance.
Serialization is not a substitute for planning how your environments differ. Database connections usually point to different hosts, schemas and credentials in each environment, and an imported question that references a database needs a matching connection in the target. Permissions differ too: groups, collection access and any row or column rules configured in staging may not match production. Before the first import, list each database connection, group and permission in both environments. Decide which settings are environment-specific and which should travel with the content, then confirm in the Metabase serialization documentation how references are matched on import.
Run a test import into a non-production copy of your target instance before you use the process for real promotions. Review what was created, what was updated and what was skipped, and check that every question still points to the intended database. Serialization runs through CLI commands or the API, and the API is the only option on Metabase Cloud, so confirm which method your deployment supports. Metabase excludes the license token from exports, so plan to activate the target instance's own token separately. Document the steps so the next promotion follows the same checks.
Metabase serialization CLI versus API options
This table compares the command line interface and the API for running Metabase serialization between environments. Match the interface to where your Metabase is hosted and to who will run each export and import. The API is the only option on Metabase Cloud, while self-hosted instances can use either path.
| Consideration | CLI | API |
|---|---|---|
| Hosting availability | Self-hosted instances only | Self-hosted instances and Metabase Cloud |
| Plan requirement | Pro or Enterprise plan | Pro or Enterprise plan |
| Platform team runs promotions | Suits operators with shell access to the host running Metabase | Suits operators who script calls from a jump host or runbook |
| CI pipeline runs imports | Confirm the runner can reach the CLI and the target instance | Confirm the runner can reach the target's API with a stored credential |
| Developer workstation | Needs the CLI installed and network access to the target instance | Needs network access to the target and a credential it accepts |
| Version control and scripting | Exported YAML files can be committed to Git and reviewed in pull requests | The same YAML content can be committed, with scripts calling endpoints and saving output |
| Access and credentials | Confirm which account the CLI runs under and where its secrets are stored | Confirm the token type, its permissions and its rotation policy for each environment |
| License token | Exports exclude the license token, so confirm each target keeps its own | Exports exclude the license token, so confirm each target keeps its own |
| Exact commands and options | Follow the serialization docs for current commands and flags | Follow the serialization docs for current endpoints and request formats |
How the Metabase serialization export and import cycle works
Serialization is a two-step cycle. An export reads the contents of one Metabase instance and writes them to YAML files. An import reads those files and creates or updates matching items in a target instance. Because the files are the handoff, you can move content between environments, keep it in version control, or copy template content to other instances without rebuilding it by hand. Serialization is available only on the Pro and Enterprise plans, so confirm that both the source and the target run a plan that includes it before you design the workflow around it. Confirm also which content types your Metabase version exports, because coverage has changed across releases.
The YAML is written to be read by people. Each item is stored as a plain text file, so a reviewer can open a pull request and see a changed query, a moved dashboard card or an updated collection name as a line-level diff. That readability is the main reason teams put the export directory under version control. It is still a generated format, though. Treat the files as reviewable output rather than as a place to hand-edit identifiers or cross-references between items, and check how the docs describe references before you change anything by hand. A practical first step is to export twice from an unchanged instance and confirm that the files do not drift between runs.
Metabase excludes the license token from exports, so the target instance needs its own licensing. Plan this before the first import, not during it. Confirm that the target has an active license for the plan it runs, and that the plan supports every feature the exported content depends on. Also review what else leaves the source with the export. Database connection details, credentials and other secrets are sensitive, and you should check how the docs handle them, then decide where the target gets its own values. Keep these settings out of the review diff so reviewers see only the content changes.
A rerun against an existing target updates matching items instead of starting from scratch, so the second import can change content that already exists there. Any edit made directly in the target after the last import may be overwritten. Before you run the import against production, restore a copy of the production application database to a separate instance, run the import there, and check the results. Confirm how the import treats items you deleted from the source, since removal behavior determines whether stale content survives in the target. Record the commands, the export commit and the Metabase version on both sides so the run can be repeated or reverted.
Setting up Metabase serialization between two instances
This sequence takes a first export from a source Metabase, moves the YAML into a non-production target and confirms the imported content matches expectations. Each step ends with a check, so the first run produces a verified baseline for later promotions.
Confirm both instances run Pro or Enterprise
Start by confirming that the source and the target are both on a Pro or Enterprise plan. Serialization is available only on those plans, so an Open Source or Starter instance at either end stops the workflow before any files are created. Check the plan in each instance's admin area and record the Metabase version on both sides, since the two should be run on versions your team has tested together. Done when both plan checks and both versions are written into your run notes.
Choose CLI or API based on hosting
Decide the method before anyone runs an export, because the hosting model determines the options. Self-hosted instances can use either the CLI or the API, while Metabase Cloud supports only the API. Confirm that the account running the export has the access it needs on both the source and the target, and that the network path from your workstation or pipeline reaches both. Done when the chosen method, the account and the network path are recorded in the run notes.
Export from the source into a dedicated directory
Create an empty directory used only for this export so that unrelated files do not mix with the serialized content. Run the export from the source using the method chosen in the previous step, and follow the serialization documentation for the exact syntax. Metabase leaves the license token out of exports, but still check the files for anything unexpected. Done when the directory contains YAML files and the file listing matches the collections, questions and dashboards you expected from the source.
Review the exported YAML before importing
Read the files before they go anywhere else. If the directory is under version control, review the diff against the previous export, or against an empty baseline on the first run. Look for the collections, questions and dashboards you expect, and look for any database connection detail, credential or personal information that should stay in the source environment. Done when you have a short list of items that match the source and every open question has an owner.
Import into a non-production target
Import the reviewed files into a staging or other non-production instance, and keep production out of this step. Use the same method as the export, and confirm in the serialization documentation how the import treats items that already exist on the target and how database references are matched. Save the import output with the run notes. Done when the target reports no import errors and the log shows which items were created or updated.
Verify questions, dashboards and collections
Compare the imported content with the source. Open the collection hierarchy on both sides and confirm the same folders exist. Pick a sample dashboard and compare its cards, filters and layout, then run several saved questions and compare the results, keeping in mind that the target's database connection and data may differ. Check who can see the imported content separately, because access settings need their own confirmation. Done when the sample dashboard and questions match and every difference is recorded.
Record the baseline for later promotions
Store the reviewed YAML in version control or your change management system, along with the Metabase versions, export method and checks you ran. This gives the next promotion a baseline to diff against. Note anything that did not carry across, such as items your team must recreate by hand, so that the gap is planned for before a release. Done when the baseline is committed and the run notes name an owner for the next export.
What is not carried across in Metabase serialization
Serialization moves content, not the whole instance. The items below either sit outside the exported YAML or depend on how the target environment is configured, so each needs a decision before the first import. Treat the license token exclusion as fixed, and verify the other items against the serialization documentation and a test export from your own instance.
License token is excluded
Metabase excludes the license token from serialization exports, so the target instance must be licensed separately before it can use the features that serialization depends on. Serialization itself is available only on Pro and Enterprise plans. Before the first import, confirm the target's license state through your normal activation process, then check the plan in the admin settings once the import completes.
Database connection credentials
Exported content refers to database connections, but the credentials behind those connections are a separate concern. Confirm in the serialization documentation and a test export whether passwords or other secrets appear in the YAML files. Assume the target needs its own credentials, managed through your secret management process, and schedule their entry before anyone runs an import against production data.
Connection identifiers must match
Content that references a database connection depends on the target having a connection with the same identifier or name. If the names differ, imported questions, models or dashboards may fail to resolve their source or attach to the wrong database. Before import, list each source connection's identifier and name on both instances and compare them. Confirm the matching rules for your Metabase version in the docs.
User accounts and permissions
Confirm whether user accounts, group memberships and permission settings are carried across. Content often has owners and collection permissions tied to people and groups, so an import may leave references to users who do not exist on the target. Run a test export, compare the user and group lists on both instances, and document how each owner and group will be mapped before the first promotion.
Instance-level settings
Instance settings such as the site URL, email configuration, authentication and other administrative options may differ by environment. Confirm which of these the serialization format covers, since authentication features like SSO require Pro or Enterprise plans. After a test import, compare settings on both instances and set environment-specific values by hand, so a staging setting does not reach production.
Staging to production promotion with YAML in version control
This section covers whether your promotion process should treat Metabase content like code: export it as YAML, commit the files to Git, review the changes in a pull request, then import them into staging and production. Metabase lists version control of the readable YAML among its serialization use cases, alongside staging environments and duplicating template content to other instances. Serialization is available only on Pro and Enterprise plans, so confirm your plan before you design around it. An export is a snapshot at a point in time, and an import creates or updates items in the target instance. Agree early that the Git history, not the Metabase interface, is the record of what was promoted and when.
Metabase remote sync with Git is a separate sibling workflow that solves a different problem. It links a read-write development instance and a read-only production instance through Git, so production pulls changes that have been reviewed. Serialization is a file-based export and import that your team runs on purpose, through CLI commands or the API, at moments you script and control. The API is the only option on Metabase Cloud, so confirm where each instance is hosted before you pick a method. Read the remote sync topic before deciding, because the two workflows assume different roles for each instance and different ownership of the release steps.
Decide who approves a promotion before the first import. Common options include the analytics owner for the affected content, a platform administrator who runs the import, and a security or data governance reviewer when a change touches collections with sensitive data or permission-related items. Record the approver role in the pull request template so the approval is visible in Git. Environment-specific values need a deliberate plan. Database connections, identifiers and site-specific settings differ between staging and production, and a YAML export refers to the identifiers of its source instance. Choose whether you will maintain one file set with mapping rules, keep per-environment overlays, or adjust values during import. Also note that Metabase excludes the license token from exports, so each target instance needs its own token configured. Confirm with Metabase how the import matches databases in the target before the first production run.
Plan rollback before the first production import, because the rollback guidance in Metabase's upgrade documentation covers upgrades, such as restoring the application database backup or running the migrate down command. It does not describe undoing a serialization import, so do not assume an equivalent path exists. Before each production import, back up the production application database, record the Git commit being imported and rehearse the same import on staging. To roll back, you can revert the commit and re-import the previous YAML, but confirm how updates and removals behave, because an item deleted from the files may not be deleted from the target. Test that sequence on a non-production copy and write the steps into your runbook with a named owner.
Protecting exported YAML and API access during serialization
Serialization moves analytics content between instances through files and API calls, and each step widens who can see or change production content. The cards below cover what exports reveal, how automation authenticates, who may import, and how promotions are reviewed and recorded. Confirm your own logging and access requirements before you choose a design.
Treat exported YAML as sensitive
Serialization files describe dashboard logic, collection names and database structure, so they can disclose more about your business than a dashboard screenshot would. Decide where exports are written, who can read them, and how long copies persist. Restrict the repository or storage location to the people and pipelines that promote content, and confirm your data classification rules before any export leaves the production network.
Scope API tokens for automation
Scripts and pipelines that serialize through the API hold a credential with access to your Metabase instance. On Metabase Cloud the API is the only serialization option, so this credential matters even more there. Create a dedicated service account for exports and imports, and keep personal admin logins out of pipelines. Store the token in your secrets manager, set a rotation schedule that matches your policy, and confirm how your plan handles token lifecycle.
Limit who can run imports
An import creates or updates items in the target instance, so the operator needs write permission there and only there. Give import rights to a small named group, and separate export access from import access where your process allows. Keep day-to-day analysts on standard Metabase roles. Before you grant access, confirm which actions the CLI or API accepts under the role model you use.
Record who promoted what
A promotion changes a production analytics asset, so you need to know who ran which import, from which export, and when. Pro and Enterprise plans include auditing and usage analytics inside Metabase, which supports activity review on those plans. Pair these records with your pipeline run history and your repository commit history for exports. Confirm your logging retention and review requirements with your compliance owner.
Gate production imports with review
Place a review step between an export that has passed checks and the import into production. This can be a pull request approval or a pipeline stage that requires a named approver. Reviewers should inspect the YAML changes to dashboards, collections and database references, not only the commit message. Decide who may approve, whether emergency imports can skip review, and how a rejected change is withdrawn.
Plan for values that do not transfer
Metabase excludes the license token from exports, so each target instance must be licensed through its own setup. Review the Metabase serialization documentation for other items that are not carried across, and list them in your runbook. Test a full import in a staging instance so missing settings or credentials surface before a production cutover.
Metabase serialization questions buyers ask before hiring help
Is Metabase serialization available on the open source plan?
No. Metabase serialization is available only on the Pro and Enterprise plans. Metabase's pricing page lists Open Source as free and Starter at $100 per month, or $90 per month billed yearly, with Starter also excluded from serialization. Pro is listed at $575 per month, or $517.50 per month billed yearly, with the first 10 users included. Enterprise is priced by quote starting at $20,000 per year. Confirm current plan terms on the pricing page before you budget, because the plan you choose determines whether serialization is possible at all. If your analytics team needs to promote content between instances, the plan decision comes before any project planning.
What drives the cost of moving Metabase to a paid plan?
The subscription cost depends on the plan, the number of users and the billing cycle. On Pro, additional users beyond the first 10 cost $12 per month each, according to the pricing page, and Enterprise is quoted individually. Separate from the subscription, you pay for the work to switch plans and validate the result, which covers configuring the new license on the target instance, confirming your identity and permission settings still apply, and testing content in a non-production copy. Ask any implementation partner for a written quote that lists each deliverable, who performs it, which environments are in scope and what is excluded. A quote without an inventory of your instances and content is hard to compare.
How long does a first Metabase promotion between environments take?
No single duration applies, because the time depends on the content and the gap between environments. Content volume matters: the number of collections, dashboards, saved questions and models, and how many depend on each other. Environment differences matter more for a first run. Source and target instances often point at different databases, use different database IDs, or have different permission groups, and each mismatch needs a decision and a test. A team with a complete inventory of content and a documented staging-to-production path can usually plan a smaller first run than a team that has never exported content. Ask for a timeline that is tied to an inventory and a named set of environment differences, and treat any figure given without one as unverified.
What does a Metabase serialization project need from our team?
The project needs access and decisions, not only tooling. Expect to provide admin accounts on the source and target instances, read access to the application database or the ability to run the export and import commands, and database connections for every data source the content uses. You will also need a Git repository for the exported YAML, a named owner who approves changes, and test data or a non-production database that resembles production. Confirm that your Metabase plan is Pro or Enterprise on both sides where required, and that your network allows the CLI or API to reach each instance. Your team should also agree on a change window and a rollback plan, because promotion changes content that business users rely on.
Can our own engineers run Metabase serialization without a partner?
Yes, if you have the plan, the access and engineers with time to learn the tool. Metabase documents serialization through CLI commands and the API, and the API is the only option on Metabase Cloud. Your team can run exports and imports directly, which keeps the work and the knowledge in-house. The main risks are the first run, when mismatched database IDs, missing connections or unexpected overwrites are most likely, and the ongoing review of what changes move between environments. Many teams run a pilot on a small set of dashboards before moving the full catalog. A partner is useful when you want a documented runbook, a fixed scope and an independent check of the first promotion. DeployOpen plans and implements work of this kind in infrastructure you control, under a written scope agreed before work starts.
What does Metabase serialization not carry across between instances?
Metabase excludes the license token from exports, so the target instance must have its own valid license for the plan you are using. Beyond that, confirm exclusions for your Metabase version in the serialization documentation before you plan the work, because the exact scope of what moves matters for planning. Treat database connection details, user accounts, group membership and instance-level settings as items to verify rather than assume. Build a checklist of what each environment must configure separately, and test each item in a non-production copy. Document the checklist in your runbook so that future promotions do not rely on memory.
Is the exported Metabase YAML safe to keep in version control?
The YAML is designed to be readable, which makes it practical for version control and code review. Store it in a private repository with access limited to the people who own analytics content, and require review before merging changes. Before each commit, check the exported files for sensitive values, such as names, filters or query text that reveal regulated data, and for anything that should live in a secrets store instead. Keep the repository history as the audit trail for content changes, and tie each import to a specific commit so you can show what was promoted and when. Test that a fresh environment can import a tagged version, because a repository you cannot restore from is only a backup in name.
How DeployOpen scopes and delivers Metabase serialization work
DeployOpen plans Metabase serialization between environments as a fixed-scope piece of work inside infrastructure you control. We agree in writing which content moves, which instances are involved and how the YAML is reviewed, then build and document the export and import workflow for your team to run. Ongoing support is available as a retainer.
How we scope
- Confirm which Metabase instances are in scope and whether they run the Pro or Enterprise plan, since serialization requires one of those plans.
- Agree which collections, dashboards, questions and settings move between environments, and which stay local to each instance.
- Document in the written scope how credentials, the license token and database connection details are handled, since the token is excluded from exports.
How we build
- Choose the CLI or API path for each environment, noting that the API is the only option on Metabase Cloud.
- Build export and import runs for staging to production promotion, version control of the YAML, or duplicating template content.
- Test imports on a non-production instance and check that items created or updated match the intended content before any promotion.
How we hand over
- Deliver the export and import procedure, the repository layout for the YAML files and the review steps for changes.
- Document the items that do not carry across so your team knows what to recreate or configure by hand in each target instance.
- Walk your team through a full promotion run and record the steps they will repeat for future changes.
How we support
- Offer ongoing support and upgrades as a retainer after handover, covering serialization runs as your Metabase version changes.
- Review how serialization interacts with each Metabase upgrade and plan the order of instance updates with your team.
- Confirm with your Metabase vendor or documentation any behavior that changes between releases before relying on it in production.
