Dynamic previews

How to integrate Dynamic Previews in your CI/CD Pipeline with the Humanitec Platform Orchestrator

To use dynamic preview Environment, you must create a GitHub Action and notify Humanitec about the newly pushed image in the CI step. For more information, see preview-envs-action on GitHub’s marketplace. For information on using ephemeral Environments with your pipeline, see Deploy ephemeral Environments

Inputs

The preview environment is cloned from the base-env specified in the action inputs (defaults to development if not specified). Ensure the source environment id, base-env, is up-to-date before creating preview environments, otherwise they may be cloned from an old version.

input	Required	Description
`humanitec-token`	Yes	The Humanitec API token.
`humanitec-org`	Yes	The name of the Humanitec Organization.
`humanitec-app`	Yes	The name of the Humanitec Application.
`action`	Yes	The action to be performed. Valid values: `create` \| `delete`
`base-env`	No	The source Environment Id. Defaults: `development`
`image`	No	The image of the Workload that should be deployed. Default: `registry.humanitec.io/${humanitec-org}/${GITHUB_REPOSITORY}`
`environment-url-template`	No	Provides a custom mustache template for the Environment URL. Default: `https://app.humanitec.io/orgs/{{orgId}}/apps/{{appId}}/envs/{{envId}}`
`humanitec-api`	No	Uses a different Humanitec API host.
`github-token`	No	GitHub token used for commenting inside the Pull Request.

Example

The following are examples on how to use Dynamic Preview Environments in your GitHub actions.

Create

The following example demonstrates how to create a preview when the Pull Request is opened or reopened.

name: Create Preview environment

on:
  pull_request_target:
    types: [opened, reopened]

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

    steps:
      - uses: humanitec/preview-envs-action@v1
        with:
          humanitec-token: ${{ secrets.HUMANITEC_TOKEN }}
          humanitec-org: my-org
          humanitec-app: my-app
          action: create
          github-token: ${{ secrets.GITHUB_TOKEN }}

Delete

The following example demonstrates how to delete a preview when the Pull Request is closed.

name: Delete Preview environment

on:
  pull_request_target:
    types: [closed]

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

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

Notify CI pipeline

Add the following code to your CI pipeline. This should be added after the snip which notifies Humanitec about the newly pushed image.

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

Configure Environment variables

Configure the following environment variables to run the Action with Humanitec.

HUMANITEC_ORG
HUMANITEC_TOKEN
HUMANITEC_APP

You must deploy an Application to the environment before you can create a preview environment. Otherwise, you will receive the following error message:

Error Environment development has never been deployed

Step by Step Guide on Using Dynamic Preview Environment with GitHub Actions

This guide will walk you through the steps to use Dynamic Preview Environment with GitHub Actions and Humanitec.

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.

Step 1: Generate Humanitec API Token

The first step is to generate your Humanitec API token. To do this, follow these steps:

Sign in to your Humanitec account.
From the left navigation menu, select API Tokens.
Enter a Token ID, and select Generate new token.

Now that your API token is generated, set up the environment variables.

Step 2: Set environment variables

In your GitHub repository, configure your secrets, which are environment variables that are encrypted and can only be accessed by steps in the same job.

Navigate to your GitHub repository.
Choose Settings and navigate to the Secrets section.
Select New repository secret.
Add the following secrets and their corresponding values:
- HUMANITEC_TOKEN: The token you generated from Humanitec.
- HUMANITEC_ORG: The name of your Humanitec organization.
- HUMANITEC_APP: The name of your Humanitec application.
Select on Add secret to save each one.

Step 3: Create GitHub Action

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

Navigate to the Actions tab in your GitHub repository.
Select New Workflow.
Select Set up a workflow yourself.
Paste the following YAML code in the editor:

name: Create Preview environment

on:
  pull_request_target:
    types: [opened, reopened]

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

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

Choose Start commit and then Commit new file to save the workflow.

Step 4: 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 Step 3, but 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@v1
        with:
          humanitec-token: ${{ secrets.HUMANITEC_TOKEN }}
          humanitec-org: ${{ secrets.HUMANITEC_ORG }}
          humanitec-app: ${{ secrets.HUMANITEC_APP }}
          action: delete
          github-token: ${{ secrets.GITHUB_TOKEN }}

Step 5: Notifying CI pipeline about the New Image

Add the following code to your existing CI pipeline. This code notifies the Humanitec Platform Orchestrator about the newly pushed image.

- uses: humanitec/preview-envs-action@v1
  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 environment. To resolve this, deploy an application to the environment in your Humanitec account.

Results

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

Dynamic previews

Inputs #

Example #

Create #

Delete #

Notify CI pipeline #

Configure Environment variables #

Step by Step Guide on Using Dynamic Preview Environment with GitHub Actions #

Step 1: Generate Humanitec API Token #

Step 2: Set environment variables #

Step 3: Create GitHub Action #

Step 4: Delete Preview Environment on Pull Request Closure #

Step 5: Notifying CI pipeline about the New Image #

Troubleshooting #