Ephemeral environments

What is an ephemeral environment?

If you wish to automatically generate preview environments for your Application, you may set up so-called “ephemeral environments”.

An “ephemeral environment” is a temporary, on-the-fly instance of an application. It exists solely for the duration of a specific task, such as testing a feature or bug fix via a pull request. Once the task is done, the environment is torn down.

Ephemeral environments are sometimes called “dynamic previews”.

Ephemeral environments are not technically different from other Environments in the Platform Orchestrator. There is no technical flag marking an Environment as “ephemeral”. Their ephemeral nature is a human notion, signifying the limited time span of their existence.

The diagram below shows an overview of the ephemeral environment interactions. Note that much of the process is automated and the developer continues to exercise the familiar flow:

  • Create a new (feature) branch
  • Repeatedly commit to that branch
  • (NEW) Perform testing, as required, against the updated ephemeral environment tied to the branch
  • When finished, merge and delete the branch
  • Perform testing, as required, againt the updated baseline Environment (named “Development” in the diagram)
sequenceDiagram
    actor Developer
    participant Development env
    participant main branch
    Developer->>main branch: create branch
    create participant my-branch
    main branch->>my-branch: create branch
    create participant Ephemeral env
    my-branch->>Ephemeral env: create Environment
    my-branch->>Ephemeral env: humctl score deploy
    loop
        Developer->>my-branch: commit
        my-branch->>Ephemeral env: humctl score deploy
        Developer->>Ephemeral env: perform testing
    end
    Developer->>my-branch: merge
    my-branch-->>main branch: merge
    destroy Ephemeral env
    my-branch-xEphemeral env: delete Environment
    destroy my-branch
    main branch-xmy-branch: delete branch
    main branch->>Development env: humctl score deploy
    Developer->>Development env: perform testing

The tutorial Deploy ephemeral Environments guides you through a hands-on setup using GitHub as the sample platform and a largely tooling-independent implementation.

For users of GitHub, this page presents an equivalent approach using the GitHub action preview-envs-action which is available on GitHub’s marketplace. Refer to the tooling documentation on the marketplace for usage details and available inputs.

Prerequisites

Before starting, ensure that you have a GitHub and a Humanitec account. If not, sign up for both.

Now, get started by generating a Humanitec API token.

Generate Humanitec API token

Create an API token for the Platform Orchestrator. GitHub will need this token to perform deployments via the Orchestrator. Save the token in a secure place.

Set environment variables

Configure required secrets in your GitHub repository.

  1. Navigate to your GitHub repository
  2. Choose Settings and navigate to the “Secrets and variables” section
  3. Choose Actions
  4. Select New repository secret
  5. Add the following repository secrets and their corresponding values:
    • HUMANITEC_TOKEN: The API token you generated earlier
    • HUMANITEC_ORG: The id of your Humanitec Organization
    • HUMANITEC_APP: The id of your Humanitec Application
  6. Select on Add secret to save each one

Create GitHub workflow

To use Dynamic Preview Environment, you’ll need to create a GitHub workflow that uses the humanitec/preview-envs-action@v2 action. Follow the steps below:

  1. Navigate to the Actions tab in your GitHub repository
  2. Select New Workflow
  3. Select Set up a workflow yourself
  4. Enter the file name pull_request.yaml into the breadcrumb
  5. Paste the following YAML code in the editor:
name: Create Preview environment

on:
  pull_request_target:
    types: [opened, reopened, synchronize]

jobs:
  create-preview-env:
    runs-on: ubuntu-latest

    steps:
      - uses: humanitec/preview-envs-action@v2
        with:
          humanitec-token: ${{ secrets.HUMANITEC_TOKEN }}
          humanitec-org: ${{ secrets.HUMANITEC_ORG }}
          humanitec-app: ${{ secrets.HUMANITEC_APP }}
          action: create
          github-token: ${{ secrets.GITHUB_TOKEN }}
  1. Choose Commit changes… and then again Commit changes to save the workflow

Delete preview environment on pull request closure

To delete the preview environment when a pull request is closed, you’ll need to create another GitHub Action. Repeat the previous step, but name the file close_pr.yaml and replace the YAML code with the following:

name: Delete Preview environment

on:
  pull_request_target:
    types: [closed]

jobs:
  delete-preview-env:
    runs-on: ubuntu-latest

    steps:
      - uses: humanitec/preview-envs-action@v2
        with:
          humanitec-token: ${{ secrets.HUMANITEC_TOKEN }}
          humanitec-org: ${{ secrets.HUMANITEC_ORG }}
          humanitec-app: ${{ secrets.HUMANITEC_APP }}
          action: delete
          github-token: ${{ secrets.GITHUB_TOKEN }}

Notify GitHub environment

Add the following snipped after your CI step (commonly the build-push-to-humanitec step) to notify the underlying GitHub Environment about the newly pushed image. When the environment-url-template parameter is provided, GitHub will display a “View Deployment” button for convenient access to the preview environment using the generated URL.

- uses: humanitec/preview-envs-action@v2
  with:
    humanitec-org: ${{ secrets.HUMANITEC_ORG }}
    humanitec-app: ${{ secrets.HUMANITEC_APP }}
    action: notify
    github-token: ${{ secrets.GITHUB_TOKEN }}
    environment-url-template: https://dev-{{envId}}.my-domain.app

Troubleshooting

If you encounter an error message saying Error Environment development has never been deployed, it means that you haven’t deployed an application to the base Environment named in the base-env parameter if the action: create step. It defaults to development.

To resolve this, perform a deployment into that Environment first.

Results

Congratulations! You’ve successfully set up dynamic preview environments in your GitHub actions with the Humanitec Platform Orchestrator.

Workload artefacts