Import pipelines and projects from one ZIP
TLDR
Import one pipeline, multiple pipelines, or a full Mage project from one ZIP, then handle protected files, credentials, environment settings, schedules, and run history separately before cutover.
Moving a Mage project is more than getting a ZIP to upload. The archive can carry the project repository, but it does not carry every credential, workspace setting, or piece of operational history around that repository.
Move more pipeline work in one upload
Mage Pro 0.9.63 or later accepts exactly one ZIP at a time. That ZIP can contain one pipeline, multiple pipelines, bundled exported pipeline folders, or one full Mage project.
Before importing, read this list like a packing slip: every expected pipeline should be present, and conflicts or failures should be zero unless you deliberately added one.
What moves with the ZIP
| Category | What the importer does | What remains for you |
|---|---|---|
| Imported: pipeline definitions | Imports each pipeline's metadata.yaml and supported block source files. Multi-pipeline archives report validation and import status per pipeline. | Compare the source and target pipeline inventories and confirm the expected files arrived. |
| Imported: full project repository | Can upload project files such as the root metadata.yaml, pipelines/, io_config.yaml, requirements.txt, dbt/, plugins/, utils/, and other repository assets. | Review new, conflicting, identical, and protected files before choosing what to write. |
| Protected | Reports but does not upload .env, .env.* variants, .envrc, or workspace variable folders. | Recreate approved values through the target environment's secret and configuration process. |
| Excluded | Git metadata and generated caches are also omitted from project writes. The importer classifies them as protected; for migration planning, treat them as excluded repository state. | Let the target workspace and source-control process create their own metadata and caches. |
| Separate migration work | The ZIP import does not establish that credentials, OAuth connections, workspace compute settings, deployment settings, schedules, run history, backups, or infrastructure moved. | Inventory, restore, reconfigure, and verify each item separately before cutover. |
These boundaries reflect the Mage Pro 0.9.63 or later implementation and the September 17, 2026 release. The import flow was verified with synthetic fixtures, including an eight-pipeline archive and a full-project archive. That evidence covers import behavior, not a production cutover or full-server restore.
That last row is the boundary worth remembering. A protected file is not a migrated file, and a successful upload is not a server restore.
The full-project result should be read the same way. It separates the files that were uploaded from conflicts, protected items, and configuration that still belongs on the target environment.
Resolve conflicts before files are written
Mage Pro detects pipeline-name and file conflicts before applying changes. Pipeline imports can overwrite, rename, skip, or cancel where appropriate. Full project imports can overwrite conflicting files, skip them, or cancel for review; project files are not renamed.
Protect the project you already have
Each pipeline import rolls back if writing one of its files fails, while successfully imported sibling pipelines can remain available. A full project upload is atomic: if a project file write fails, Mage restores every file changed by that upload.
Verify the target before cutover
- Compare the source and target pipeline and file inventories.
- Re-establish credentials, environment variables, secrets, OAuth connections, compute settings, and deployment settings through the approved target process.
- Confirm the target has the required packages and access to every external service.
- Recreate or verify schedules and decide how run history and other server state will be retained.
- Run one representative imported pipeline and compare its output with the source before moving production work.
The importer tells you what it validated and wrote. The test run tells you whether the new environment can actually do the work.
Bring existing pipeline work into Mage Pro
Learn more
- Read the pipeline import documentation
- See the September 2026 Mage Pro release notes for expanded ZIP import behavior
The import guide covers the established pipeline import flow. The September release notes are the source for multi-pipeline and full-project ZIP imports.
