Release Overview
Release simplifies development by making the creation of environments easy.
Release Environments are created based on a Release Application Template and Environment Variable defaults that define your application and its environments.
Release can automatically generate these templates or you can write them on your own from a library of examples of common frameworks. We generally recommend letting Release analyze your repository and automatically generating them as a starting point.
We currently support the following mechanisms to create your Release Application/Environment Variable defaults:
  • Write your own templates from a library of examples for common frameworks and services.
  • Automatically generated by parsing docker-compose.yaml files found in your repository
  • Automatically generated by parsing package.json files for Javascript applications
  • You can bring your own Kubernetes yaml and environment definitions can be derived from them
  • Helm charts
You can create an infinite number of development, staging, demo and production environments without ever having to deal with the underlying infrastructure. These environments can then be automatically generated and updated whenever you push a code change or create a PR. They can also be manually deployed via the Release user interface.
Developers generally interact with Release by creating a Pull Request in their VCS (version control system) and Release will automatically create an environment with the code changes in the PR.
In addition, organizations can create permanent staging and production environments and automate all of the steps from code push to running in production.

Prerequisites to running an application in Release

Frontend Javascript Applications

  1. 1.
    A package.json file containing a build command in the scripts.

Container Based Applications

  1. 1.
    A working Docker build. See Docker builds.
  2. 2.
    A definition of your application in a docker-compose.yml.
  3. 3.
    Your application's source code is checked into a VCS (i.e. Github/Bitbucket).
  4. 4.
    For OAuth based VCS integrations (Bitbucket) you'll need a user who has admin permissions on the repository to install webhooks and deploy keys. For Github, we use Github Apps and the app authorization handles the management of the repository.
  5. 5.
    Admin access to an AWS account where you'd like your environments to run.

Core Concepts of Release

Static Sites

Release supports standalone static sites running without Docker backends. These sites are pushed into a CDN and hosted on your behalf. See Static Service Deployment for more information.

Docker & docker-compose

Release builds services running in Docker containers derived from your docker-compose.yaml file. Your application can have any combination of one or more services. For more information about creating an application that builds via Docker and docker-compose please see these useful reference guides from Docker.
In order to run Docker based applications in Release, there needs to be a working Docker build and a docker-compose file that will run all of the services needed.

Hybrid Sites (Static Sites + Docker Containers)

Release supports applications with both static frontends with other Dockerized services. Static applications are defined in a package.json while your other services are defined through a docker-compose.yaml file. When both of these are present in a repo, Release will automatically detect and provide you with options to build these services correctly. Release manages all facets of creating environments and connecting frontends and backends together seamlessly.

Connecting to Your Cloud Account

Release supports running environments in your AWS account through the creation of a Kubernetes cluster using AWS Cloud Formation templates. This cluster will be fully and remotely managed by Release, meaning you don't need to know anything about Kubernetes to use Release.
To integrate your cloud provider with Release, you will need to go to your Account Settings > Integrations where you will be walked through a simple setup to connect your AWS account to Release.
*Currently Release only supports AWS.

The Application Template

Release automatically generates an Application Template for your app. This is created from your docker-compose file (and package.json file for your frontend javascript applications). This file defines the following high level concepts (see the Default Environment Configuration Schema for the full schema):
  • The Kubernetes cluster your application is running in
  • The domain where your application will be running
  • Templates used to create ephemeral and permanent environments
  • Hostnames where your application will be publicly accessible
  • Resources allocated to your services
  • Application services
  • Application jobs (i.e. running migrations or other scripts)
  • Application workflows
This configuration is automatically generated when you create your application and contains smart defaults that will allow your application to run. Release has been designed with minimal configuration in mind, but every application is unique and the application template allows developers to customize their application to suit their needs.


Webhooks are calls made from your VCS back to Release when certain events happen. This tells Release there is something of interest to pay attention to in your repository and kick off automated workflows in Release. Release listens to webhooks for the following actions:
  • New pull request
  • Pull request closed
  • Pull Request re-opened
  • Pull Request merge
  • Code pushed to repository
The user account that creates an organization's Release account, must have Admin privileges for the application's repository. See Github permissions and Bitbucket permissions for more information on setting up a repository to allow the proper webhooks for Release.

Ephemeral Environments

Ephemeral environments are environments that live for the life of a Pull Request or are created manually. These environments will automatically track the branch from your Pull Request. An ephemeral environment is given a unique URL for each service. This allows developers to share work-in-progress development with stakeholders easily. Ephemeral environments are designed to be close replicas of production environments.
See the full documentation on Application Templates.

Permanent Environments

Permanent environments are environments that are not destroyed. Typically they are for more traditional staging or production workloads. These environments get static URL's that are based on the domain field in your application template. They can be set to track a branch and deployed automatically on a code push to your source control system, or they can be deployed manually.
See the full documentation on Application Templates.

Differences Between Permanent and Ephemeral Environments

In general, ephemeral environments and permanent environments are basically the same, however there are some slight differences to keep in mind that might affect which one you choose to ues. These are a few of the differences between permanent and ephemeral environments when using Release:
Ephemeral Environments
Permanent Environments
Can be set to expire (automatically) and also can be renewed (during push event or manually) Environment Expiration
Never expire
Can be deleted easily
Require special checks to delete (contact support to find out how to delete them)
Can be automatically created by pull requests
Must be created manually
Are located lower down in the Environment Details page
Are always listed at the top of the Environment Details page
Cannot use a custom name and cannot be renamed
Must specify a custom name (contact support to rename environments)
Does not support Rainbow Deployments
Supports Rainbow Deployments
Covered only by normal support SLAs
Can be included in enhanced support SLAs (contact sales or customer success for more details)
Can specify overrides in the Application Template for ephemeral environments (adding/changing services and default resources) This is the same for both, but there is a specific section for each type
Can specify overrides in the Application Template for permanent environments (adding/changing services and default resources) This is the same for both, but there is a specific section for each type
Typically have fewer resources and extra container services for databases, redis, and so forth
Can be set with more resources and usually require more customisations from the default as well as usually exclude container services in favour of pemanent infrastructure (like databases, redis, queues, buckets, and so forth)
Are created each time from the latest Application Template major versionRelease Environment Versioning
Do not change the major version from which they were created and are not updated when the Application Template changes

Where do the applications and environments run?

Release Starter Account applications are hosted within the Release cloud. Professional and above accounts host applications running on a Kubernetes cluster in your AWS account (optional) and static sites hosted out of Cloudfront. Release remotely manages the cluster and CDN so your teams can focus on building your applications.
Last modified 1mo ago