Introduction to Artifacts, Manifests, Releases and Source Control in Retool

🧑‍💻 Retool Tips & Tricks
1

This article serves as an introduction to multi-instance release concepts in source control - you will find the full Retool documentation here, but if you are new to the subject, then you may find the following useful.

What do all these words mean? Here is a quick Analogy!

While Stranger Things is available on Netflix in the US, UK, and Germany, each region may not show the same seasons at the same time. For example, Germany may only show seasons 1-3 of the series, while the UK shows seasons 1-4 and the US shows seasons 1-5. So each region has a different state of what is shown.

In this example

  • Instances/Spaces = Germany/UK/US
  • Release = "Season 2 of Stranger Things" (the version label)
  • Artifact = The actual packaged season files stored in Netflix's vault
  • Manifest = The rules for each region/ "Germany gets Season 1-2, UK gets Season 1-3"

The release is the version number. Each artifact holds all the information for ONE specific release. The manifest determines which artifact (release) applies to each respective instance.

So what does this have to do with Retool?
Since releases are committed to your source control repo, users will work with two types of branches living in the repository:

  • Feature branches – where you make changes to the app
  • Release branches – where release artifacts are created

The process looks like this in your protected app:

  1. Create a feature branch from main and edit the app as needed
  2. Commit your changes → open a PR → merge the feature branch to main
  3. Once merged, main contains your updated app
  4. Create a release from this version of main (Retool creates a release branch with the artifact)
  5. Merge the release branch to main → the release is now available

Imagine you've built a major update to your "Customer Dashboard" app including new features in release v3.0. You want to test it before deploying it to production right away, that’s why:

  • Your production Instance will use the Manifest that points to Customer Dashboard v2.5.0
  • Your staging Instance will use the Manifest that points to Customer Dashboard v3.0.0

If multi-instance releases aren't set up, you can still use Releases in each instance — but you'll need to create and manage them manually per instance, rather than being able to control them centrally from a single coordinated pipeline across all instances.

Since releases are committed to your source control repo, users will work with two types of branches living in the repository:

  • Feature branches – where you make changes to the app
  • Release branches – where release artifacts are created

The process looks like this in your protected app:

  1. Create a feature branch from main and edit the app as needed
  2. Commit your changes → open a PR → merge the feature branch to main
  3. Once merged, main contains your updated app
  4. Create a release from this version of main (Retool creates a release branch with the artifact)
  5. Merge the release branch to main → the release is now available

How do I see which manifest each instance uses and which releases are deployed?

  1. Ensure the Multi-instance releases: public beta feature is enabled in settings/beta (Required as of Feb 2026, cloud v3.341.0, edge v3.330, stable v3.300 - later versions will have this feature automatically enabled, but users will have the ability to disable it in settings/beta)
    CleanShot 2026-02-20 at 17.57.44
  2. Go to /settings/source-control and click on create a manifest in the Releases section on the bottom right -> PR and merge this to the repo
  3. In the same Release section, under the edit config button, select the manifest you want to use for the current instance. Do the same on each instance that you need to set a manifest on
  4. In the Release tab, you can then set which release version each manifest should point to
    CleanShot 2026-02-20 at 17.58.38
    CleanShot 2026-02-20 at 17.58.381379Ă—690 63.1 KB

Full process in more detail here.

There are great demos of how to create releases or manifests here.

1 Like
3

What will I see on my Source Control provider when I have this set up in Retool?

The following walks through an example on GitHub

You will see new folders in your repo after the above is set up:

  1. dist/apps and
  2. Manifests:

1- Dist/apps folder:

CleanShot 2026-02-20 at 18.00.12
CleanShot 2026-02-20 at 18.00.121314Ă—667 106 KB

The artifacts (so the zipped snapshot of a specific release version of your app) can be found in dist/apps. The UUID represents the actual app (ie, yourInstanceUrl/apps/UUID_of_app)

CleanShot 2026-02-20 at 18.00.42
CleanShot 2026-02-20 at 18.00.421301Ă—469 40.8 KB

When you click into an artifact/ app, you will see all releases linked to the app/the version snapshots:

CleanShot 2026-02-20 at 18.01.10
CleanShot 2026-02-20 at 18.01.101303Ă—318 45.3 KB

When you download the zip files you can see that they contain same structure as the app directory:
Zip
CleanShot 2026-02-20 at 18.01.42
CleanShot 2026-02-20 at 18.01.42749Ă—301 24.6 KB

App
CleanShot 2026-02-20 at 18.01.54
CleanShot 2026-02-20 at 18.01.54520Ă—388 15.8 KB

2- Manifests
Here you can see the manifests you have set up

CleanShot 2026-02-20 at 18.02.25
CleanShot 2026-02-20 at 18.02.25862Ă—426 24.1 KB

When you click through to Prod.yaml, for instance, you can see that the Prod manifest points to release 2.0.1 of the app with UUID ca9aa65……

CleanShot 2026-02-20 at 18.02.51
CleanShot 2026-02-20 at 18.02.51917Ă—456 40.6 KB

While QA points to latest
CleanShot 2026-02-20 at 18.03.13
CleanShot 2026-02-20 at 18.03.13763Ă—400 32.8 KB

Just like you can see in the UI in settings/source-control as well
CleanShot 2026-02-20 at 18.03.36
CleanShot 2026-02-20 at 18.03.361268Ă—279 23.2 KB

2 Likes
4

Hi @Alice

We’ve been using this for a few months now, and it works ok.

But given that we use lots of modules we find that the release process now takes much longer and is less straight forward.

For example, I just made an update which touched 5 modules. Now I have to create a pull request to create an artifact for each of those modules, plus the release PR. Whereas before I could quickly create the new release and set it live.

Any new modules now need 3 PRs (one to protect, one to create the artifact, and one to release).

I get that this could be pretty powerful, but for us any advantage is far outweighed by the extra time it takes (like 20-30mins for a feature).

Just noticed that it’s in beta, and that’s been automatically switched on (not sure why).

image

Wondering 2 things:

  1. Given we’ve been using this for a couple of months, would it be safe to switch this off and revert to the old way.
  2. Once this comes out of beta, will we have the option to keep doing it the old way.

Thanks,
Ben

5

Hi Ben,
It is save to switch this feature off, yes. One thing to flag: any release manifests and artifact files you've created over the past couple of weeks will stay in your source control repo, you may want to tidy those up separately if you'd like a clean repo.

You will be able to keep working without multi-instance releases in the long term, yes. You're free to keep running the old flow indefinitely.

One thing worth flagging in case it's useful: there's a middle ground that gets you most of the old behaviour without disabling the feature. Any element not listed in your manifest, or listed with version "latest", will just pull the current state from main, no artifact PR needed. So if you set your modules to "latest" you basically get the old workflow back while keeping the option to use version pinning later if you ever want it.

1 Like
6

Hi @Alice , thanks for getting back to me - appreciate the intel!

1 Like
7

Are manifests now a requirement for doing multi-instance releases? We are self hosted, and until today, were using Retool version 3.X. On 3.X, we could cut a new release version on multi-instance via the UI. After now migrating to 4.X, both our source control and ability to do release via the UI have broken. It seems like creating a manifest is the only way to fix.

8

Hi @Scott_Rice :waving_hand:
Yes, manifests are now required to publish releases in 4.x - this is an intentional behaviour change, not a bug.

Here's what's happening:
In 4.x, once the multi-instance releases feature is enabled (which it is by default), you can no longer publish a release without:

  1. A manifest created in Settings → Source Control
  2. The manifest configured in Settings → Source Control → Releases → Edit Config

Only after both are in place can you publish from the Releases & History modal.

The following should unblock you here:

  1. Go to Settings → Source Control and create a manifest
  2. Go to Settings → Source Control → Releases → Edit Config and select that manifest
  3. You should then be able to publish your release from the app's Releases & History modal

One thing to keep in mind if you're considering toggling the feature off instead: if you've already created any releases under 4.x, disabling the feature flag won't fully revert things and attempting to publish those versions will throw an error: "This version is managed by source control. Please update your release manifest instead." So at that point, setting up the manifest is the cleanest path forward.

9

Thanks Alice for confirming that the multi-instance release feature is now on by default when moving to 4. And explaining how manifests are created.

One suggestion for the team: consider renaming the “Beta” window in Setting to be “Features” or “Feature Flags”. Beta infers not yet stable. However, if features are on by default when migrating to 4, I assume they are stable / no longer Beta. Or, if multi-instance releases should still be considered Beta / not stable, then don’t ship them on by default.

Also, I’m now understanding that multi-instance releases is a specific way of releasing - being able to release from one instance, and then propagating that same release to all instances. Our previous preferred workflow is to separate dev, staging, and production instances, where dev and staging always uses latest, while the production instance only requires the release step. This process continues to be preferred by us for using Retool for internal admin tooling. So, we are going to flip off multi-instance releases.

10

Thanks for the feedback, that's a great shout! Have passed this on to Engineering.