Preview Environments

The Flightcontrol Preview Environment feature is an alternative to long-lived staging environments. It allows you to create a short-lived environment on each pull request. This is useful for testing and reviewing changes before they are merged into the main branch. Preview environments now support both regular and draft pull requests.

Here’s an example of how it will look in the Flightcontrol dashboard once preview environments are configured and there are opened pull requests:

Preview Environments highlighted in dashboard

Configuration

Underneath the list of deployments on the left hand side of the dashboard, you will see a button to set up Preview Environments for this project.

Set up preview environment button highlighted in dashboard

After clicking on the button, you will see a dialog box to configure your preview environments.

On this screen, you can configure the following:

Region

The AWS region where your preview environments will be deployed. This could be different from your other deployments, in particular to avoid reaching AWS quotas.

Filters

You can configure filters to only deploy preview environments for pull requests that match certain criteria. For example, you can configure it to only deploy preview environments for pull requests that target the main branch and have the deploy-preview label.

From Branches - You can configure the branches that the pull request must be from to trigger a preview environment. For example, you can configure it to only deploy preview environments for pull requests that are from the feature/** branch.
To Branches - You can configure the branches that the pull request must be to to trigger a preview environment. For example, you can configure it to only deploy preview environments for pull requests that are to the main/** branch.
GitHub Labels - You can configure the labels that the pull request must have to trigger a preview environment. For example, you can configure it to only deploy preview environments for pull requests that have the deploy-preview label.
Watch Paths - You can configure the paths that the pull request must have changes in to trigger a preview environment. For example, you can configure it to only deploy preview environments for pull requests that have changes in the src/ folder. This is especially useful for monorepo deployments.

Once you have configured your preview environments, click on the Add Services button to save your configuration.

Now, you can choose which services to use in the preview environment.

You can choose one of the presets, but we recommend duplicating an existing environment (such as production), and then editing the number of instances and instance size to reduce costs.

After configuring your preview environment services, click on the Create environment button to save your configuration and get your project ready for preview environments.

To actually deploy a preview environment, you will need to create a pull request on your GitHub repository that matches the filters you configured.

Add a new environment to your environments array, with the following source object:

Required:
- pr: true
Optional:
- filter.toBranches: string[]
  - Example: "toBranches": ["main"]
  - Supports globs. We use micromatch
  - If set, only pull or merge requests to the specified branch(es) will be deployed as preview environments. If omitted, all to branches will pass the filter.
- filter.fromBranches: string[]
  - Example: "fromBranches": ["feature/**"]
  - Supports globs. We use micromatch
  - If set, only pull or merge requests from the specified branch(es) will be deployed as preview environments. If omitted, all from branches will pass the filter.
- filter.labels: string[]
  - Example: "labels": ["deploy-preview"]
  - If set, only pull or merge requests with at least one of the specified labels will be deployed. It will be deployed when the label is added, whether that’s during PR creation or some time after the PR is opened.

💡 Note: The optional filters work with an AND logic. If both filters are enabled, it will only deploy a PR that matches both the target branch(es) (toBranches) and one of the labels configured (labels).

The service configuration schema is the same as the regular environment.

Flightcontrol.json Examples

Preview Environment Example

flightcontrol.json

    {
      "environments": [
        ...existing environments,
        {
          "id": "preview",
          "name": "Preview",
          "region": "us-west-1",
          "source": {
        // With this configuration, ready-for-review PRs
            // targetting `main` and with the `deploy` label will
            // trigger a deploy in Flightcontrol
            "pr": true,
            "filter": {
              // optional
              "toBranches": ["main"],
              // optional
              "fromBranches": ["feature/**"],
              // optional label filter:
              "labels": ["deploy"]
            }
          },
          "services": [
            ...your supported service config
          ]
          ...rest of env config
        }
      ]
    }

Preview RDS With Web Example

In this example, we’re retrieving the database URL from the preview environment URL.

flightcontrol.json

{
  "environments": [
    ...otherEnvironments,
    {
      // Preview environment (`pr: true`)
      "id": "preview",
      "name": "Preview",
      "region": "us-west-1",
      "source": {
        "pr": true,
        "filter": {
          "toBranches": ["main"]
        }
      },
      "services": [
        {
          "id": "preview-db",
          "name": "Database",
          "type": "rds",
          "engine": "postgres"
          ...restOfConfig
        },
        {
          "id": "backend-api",
          "envVariables": {
            "DATABASE_URL": {
              "fromService": {
                "id": "preview-db",
                "value": "dbConnectionString"
              }
            }
          }
          ...restOfConfig
        }
      ]
    }
  ]
}

Using Database From Another Non-preview Environment Example

flightcontrol.json

{
  "environments": [
    ...existing environments,
  { // This environment will have the database
      "id": "staging",
      "name": "Staging",
      "region": "us-west-2",
      "source": {
        "branch": "main"
      },
      "services": [
        ...other services,
        {
          "id": "database-xuorBu",
          "name": "Database",
          "port": 5432,
          "type": "rds",
          "engine": "postgres",
          "private": false,
          "storage": 20,
          "maxStorage": 100,
          "instanceSize": "db..micro",
          "engineVersion": "12",
          "deletionProtection": false,
          "applyChangesImmediately": false,
          "autoUpgradeMinorVersions": true,
        }
      ]
    },
    { // This is the environment for enabling preview environment
      "id": "preview",
      "name": "Preview",
      "region": "us-west-1",
      "source": {
        "pr": true,
        "filter": {
          "toBranches": ["main"],
        }
      },
      "services": [
         {
          ...your web config
          "envVariables": {
            "DATABASE_URL": {
              "fromParameterStore": "parameter.store.name.for.your.RDS"
            }
          },
         }
      ]
      ...rest of env config
    }
  ]
}

Lifecycle

Creation

A preview environment will be created when:

a pull request matches your configuration (the target branch and labels filters if any)

New Deployment

Each new push to a branch that is currently opened in a Pull Request will trigger a new deployment.

Destroy

Your preview environment will be destroyed when:

the pull request is merged — destroyed immediately
the pull request is closed but not merged — destroyed after 30 mins, in case it was accidentally closed.

Limitations

Preview environments are not intended for production workloads.

To reduce your resource cost and to speed up provisioning, they do not support the following features:

No CDN for web services
No custom domains (every service and PR will have a Flightcontrol subdomain created automatically for it)
No horizontal scaling or load balancing, services with servers will only have a single instance

Good to Know

First Deployment Time

All the preview environments will share AWS resources. What this means in term of deployment time is that the very first time a pull request is created, it will take a bit longer to create the preview environment but subsequent pull requests will skip this step. The time for build and deploy will be the same.

Github Comment

Flightcontrol will keep you updated of the deployment with a Github comment added to the corresponding pull request. This comment will inform you of the progress and once successful, it will display the URL for you preview environment. It should look something like this:

You can also check the Flightcontrol dashboard to see information about the preview environment.

Preview URL

You’ll be able to get the preview URL once a preview environment has been fully deployed. This URL can be retrieved in the Flightcontrol dashboard as well as in the Github comment in your PR.

AWS Costs

Constant
- When you have preview environments enabled, there are a number of AWS resources that are configured all the time, even if you are not making pull requests. We do this (1) to speed up provisioning of an environment for each PR and (2) reduce incremental costs for each preview environment.
- The main long-running AWS resource is a single load balancer (per service configured under your environment) that manages traffic for all your preview environments. This AWS cost is around $20/month.
Variable
- Each service on each preview environment will have an associated cost, same as normal environments.
- AWS only charges you based on the time the services are running. So if the preview environment for a specific PR is only running for 2 days, then you’re only charged for 2 days of usage.

How It Works

VPC

By default, a new, single VPC is used for all preview environments.

Alternatively, you can deploy preview environments to an existing VPC by setting the vpc field in flightcontrol.json.

RDS Preview Environment

To keep costs as low as possible and to decrease deployment time, the RDS service in Preview Environment will only have a single AWS RDS instance per service configured that will be shared. i.e.: if you have 1 RDS service and 10 PRs open, there will only be 1 instance created in AWS.

Then, for each preview environment, a new database within that instance will be created. The connection string for a specific PR can be accessed from the other services via the configured environment variable.

When the PR is merged and the preview environment is cleaned up, that database will be deleted.

Static Websites Preview Environment

The configuration for static websites uses a single Cloudfront distribution, which means that on every deployment of a preview environment, the cache for all environments will be invalidated.

For the content, a single S3 bucket is used, with a folder for each PR.

The Cloudfront Function and Lambda@Edge are responsible for serving the correct content from the S3 bucket.

Limitation

We do not currently support changing the RDS config once it has been deployed and as a way around that we suggest you change the ID for the RDS service type.

This will create a new RDS instance which can have the changed config.

Notifications SSO