Release Environments

Use Release Environments to test and deploy new integrations and integration updates.

Release Environments are environments that your team can use to control the development lifecycle of integrations:

  • Development: Make updates to your integrations and workflows in a development project that can be modified by any member of your team.

  • Staging: Preview and test integrations in a read-only environment before deploying to Production.

  • Production: Deploy integrations and updates to live users.

Each Release Environment is a separate project, with separate IDs, Signing Keys, Environment Secrets, and Connected Users.

Getting Started

To get started with Release Environments, navigate to the Manage Projects page and click "Get started" in the Release Environments prompt.

You will be prompted to select the project that represents your Production Environment. Once you make this selection:

  • The selected project will become read-only (meaning that Integrations, Workflows, and App Events cannot be modified directly). To update a Production Environment, you will need to create a Versioned Release.

  • Development and Staging environments will be automatically created. If you have existing projects used for Staging or Development, these projects will still be available and unchanged, but they will not participate in the release pipeline.

Usage

With Release Environments, your team's integration development will start in the Development environment. Workflows and integrations in the Development environment can be added and modified directly.

Once your team is ready to start testing the changes made in Development, you can create a Release from Development -> Staging to validate your changes. Staging can be used for code review and QA, prior to releasing changes to users in your Production environment.

Finally, once your changes have been finalized in the Staging environment, you can create a Release from Staging -> Production to deploy your changes to live users.

Working with a large team?

Multiple team members can work together in the Development environment, or they can opt to create an isolated Development Project to start working on new changes.

Creating a Release

To start a new Release, you can visit the Manage Projects screen (open the Projects dropdown in the global navigation and click "Manage projects").

Creating a Release brings you to an undeployed Release Preview. An undeployed Release will show the following banner:

In a Release Preview, you will see two columns:

  • Change Summary: A summary of changes made to Integrations, Workflows, and App Events since the last deploy that occurred. Each change will have a type: Add, Modify, or Remove.

  • Messages: Warning and informational messages about potential issues with or effects of the Release.

    • For example, if there are new Environment Secrets being used in the downstream environment (Development) that are not present in the upstream environment (Staging), a prompt will appear to provide a value for the new Environment Secret.

    • Learn more about Messages in Reviewing Messages.

Your engineering team can use the Release Preview screen to verify the changes that will be deployed to the next stage of your development pipeline.

If there are unexpected changes present in the Release Preview, you can make changes in the downstream project to prevent unintended updates.

Reviewing Messages

Messages appear when Paragon detects potential issues or side effects of deploying the set of changes associated with a Release.

Documentation for each type of Message can be found below:

Deploying a Release

When you are ready to deploy a Release, click Deploy in the Release Preview screen. A prompt will appear to specify:

  • Version Number: Using semantic versioning, provide a version number to represent this Release. The new version number must be higher than the currently deployed version number.

  • Description: Describe the Release with a message summarizing changes, for internal reference.

Click Deploy in the Release confirmation dialog to start the deployment process. The deployment process may take several minutes to complete, depending on the size of the changes.

Once the deployment has completed, the Release screen will update with the Live tag, and the version number will update in the Manage Projects screen.

Viewing Release History

You can review past Releases in the Staging and Production environments, by clicking the Releases tab in the left sidebar.

Click into any row in the Releases table to view the Release Summary screen, which provides the Change Summary and Messages that were associated with that Release.

Last updated