Skip to main content


What is a Stage?โ€‹

A Stage is a runtime environment for your application within your Pergola Project.

On a Stage, you can:

  • Deploy new Builds
  • Manage configurations (e.g. environment settings)
  • Publish and share links to your application
  • Access monitoring

You deploy your application always to a Stage. There can be max one Release of your application running on one Stage at a time. Once deployed, you can see each component deployed, their state, health, shareable links, etc.

Example of an application on Stage:

Multiple Stagesโ€‹

You can have as many Stages as needed per Project. It highly depends on your needs and the maturity of your Project. In most cases, you'll start with one (DEV) Stage first, then scale to multiple, differently configured Stages, when needed.

Examples for different scenariosโ€‹

A Project with classic dev / qa / prod Stages

A Project which does not require a live environment yet

Still under heavy development, but needs two separate DEV environments (maybe for A/B-Testing ๐Ÿค”)

A more complex setup, with two separate Stages to serve different markets

Separate Stages for different test cases (e.g. integration vs. acceptance), and multiple Stages live with dedicated environment configuration per factory

Stage typesโ€‹

While you can have as many Stages as needed, each Stage is classified by a type:

  • DEV (e.g. for proving that tech and build/deploy process works)
  • QA (e.g. for testing and verifying business requirements and quality expectations are met)
  • PROD (e.g. hosting the final, proven product, typically accessed by clients / end users)

Based on the Stage type Pergola might apply different rules when it comes to prioritizing platform resources and ensuring availability.

Future releases will also support applying dedicated policies for security and service-level objectives. These policies can then be configured by Pergola administrators on a per Stage type basis.


In general, you are free to deploy any Release to any Stage at any time. Though, we recommend following the DEV -> QA -> PROD approach to maintain a stable, reproducible release process.

Suspending and resuming a Stageโ€‹

If you do not need a Stage up and running for some time, you can suspend it. This saves resources (CPU and memory) while keeping your Stage and its last state ready for future use.

Suspending a Stage will shutdown all running Components, stop incoming traffic and disable scheduled jobs. Data on storage will be retained, though any temporary data will get lost. During shutdown, each Component receives a graceful shutdown (SIGTERM) first. After a grace period (usually 60secs) they are forcibly killed. Already started jobs are not affected and will run till completion.


If a Component stores data outside of a storage attached or an external storage service (e.g. S3), this data will be lost once its Stage is suspended. Always make sure to keep data on storage if you require reliable persistence.

You can resume a suspended Stage anytime. This will restore its last state (services, storage, scheduled jobs...) and start serving your application as soon as it's up and running.

How to create a Stageโ€‹

Example for Web UIโ€‹

Press the '+ NEW STAGE' button on your Project's page. This will open a popup:

  • Name is a user friendly display name for your Stage, as visible on the UI
  • Type is the Stage type for classification
  • Stage ID is a unique identifier for your Stage within your Project

The Stage ID must be unique within the scope of a Project as it will be used for links (URLs) to resources available on that Stage. Usually this is automatically derived from the display name provided, though you can override it with a more pleasing ID if you prefer. Pergola will complain if the ID is already taken.

Example for CLIโ€‹

pergola create stage my-new-stage --type dev -p my-new-project

You can retrieve existing Stages, including the new one just created, via:

$ pergola list stage -p my-new-project

stages (my-new-project)
โ”ƒ stage โ”ƒ type โ”ƒ state โ”ƒ
โ”‚ my-new-stage โ”‚ dev โ”‚ running โ”‚
โ”‚ uat โ”‚ qa โ”‚ running โ”‚
โ”‚ integration-tests โ”‚ qa โ”‚ suspended โ”‚