Connector versions and zip transfers

The connector code editor keeps the connector's files versioned and moves them between environments as a zip. This page covers the History version list and the zip round-trip; the file tree and editing are on The connector code editor.

Open the editor from the connector's Build step: click Open code editor on the connector template card.

Track versions

The connector's files are versioned. History in the editor header (tooltip Version history - view and restore previous versions) opens the version history. In the editor's messages, a version is called a checkpoint.

• A version is saved every time the connector agent changes the files.
• Restoring applies the whole version. Individual files are never restored on their own.
• A restore point is also recorded before a zip upload, so an upload can be reverted.
• Nothing new to record: No changes since last checkpoint. A version that cannot be found is refused with Checkpoint not found: <sha>; with no history at all, No checkpoints found for this tap. The earliest version cannot be reverted.
• The empty state reads No versions yet; a failed load reads Could not load the version history.

Duplicating a connector takes its latest saved state; files you have not saved are not copied.

Move the connector as a zip

The zip is the way to move a connector between environments: download it from one, upload it to another.

Download as zip in the tree header (tooltip Download connector files as zip) packs the connector's files into a zip.

• Sensitive settings are stripped of their values. The zip carries a config file that lists what to re-enter.
• Caches, virtual environments, protected files and secret files such as .env are left out.

Upload zip (tooltip Upload connector files from a zip) applies a downloaded or edited zip to the connector:

1. Click Upload zip and pick the zip.
2. Check the dialog Apply this zip to the connector? and click Apply zip. It explains the consequences: files in the zip replace connector files at the same path, paths missing from the zip are removed, protected files are never overwritten, and the connector is reinstalled as soon as the files are applied. A restore point is saved first, so the upload can be reverted. If you have unsaved files open, it warns that applying the zip discards those edits.
3. On success, the connector starts installing. If something needs your attention, a result dialog lists what was applied ({added} added, {replaced} replaced, {removed} removed), any renamed files, and any warnings.

A zip must pass these checks before it is applied:

• It is a .zip file that is not empty and at most 20 MB (Only .zip files are accepted., This zip is empty., or The zip must be 20MB or smaller (this one is {size}MB).).
• It holds at most 2,000 files and at most 200 MB uncompressed. Encrypted entries and symlinks are refused.
• It holds exactly one pyproject.toml at the connector root, next to meltano.yml, and one package folder with a tap.py. If the zip wraps the connector in an extra folder, the editor says: The zip must have pyproject.toml at the connector root (next to meltano.yml). Zip the files inside the folder, not the folder itself.
• The Python files parse. Files whose names differ only by case are refused.
• Protected files keep the server copy; the warning reads {file} is protected - the uploaded copy was ignored and the server copy kept.

If an upload fails, nothing is applied and the message Upload failed stays until you dismiss it; downloads can fail with Download failed. Fix the zip and upload again. For other messages, see Lake troubleshooting.

Questions, answered

What is a version, and how do I restore one?

A version is a saved state of the connector's files, listed in History. Restoring applies the whole version to the connector; individual files are never restored on their own. A version is recorded every time the connector agent changes the files.

Can I download the connector's code and upload it again later?

Yes. Download as zip saves the connector's files, and Upload zip applies them to the same or another connector. Sensitive values are not included, so re-enter what the zip lists after uploading.

Are secrets included in the downloaded zip?

No, not with their values. Sensitive settings are stripped and listed so you can re-enter them. When you upload, any value the connector already has is kept.

Why did an upload ignore a file I had changed?

The file is protected, so the server keeps its own copy. The warning says: {file} is protected - the uploaded copy was ignored and the server copy kept. Protected files cannot be overwritten by uploads.

How big can a connector zip be?

At most 20 MB compressed, 2,000 files, and 200 MB uncompressed. Keep the connector under these limits before downloading or uploading.

Are my unsaved files copied when I duplicate the connector?

No. Duplicating a connector takes its latest saved state, so files you have not saved are not copied.

Can I undo a zip upload?

Yes. A restore point is recorded before a zip upload, so an upload can be reverted.