Skip to main content

Ephemeral Environments

Ephemeral environments allow you to deploy a temporary, isolated version of your application for testing changes from a Pull Request before merging to main. This is useful for testing features, bug fixes, or integration scenarios in a production-like environment without affecting the main deployment.

Overview​

When you trigger an ephemeral deployment:

  1. Your application is built and pushed to Azure Container Registry
  2. A new Pull Request is automatically created in your manifest repository with ephemeral-specific configuration
  3. Argo CD creates a temporary deployment of your application
  4. Once testing is complete, closing the PR or removing the label cleans up the environment automatically

Prerequisites​

Before onboarding to ephemeral environments, ensure:

  • Your application is already deployed to the test environment via Argo CD
  • You have access to your team's manifest repository
  • Your application's manifest uses HTTPRoute as the ingress kind

Step 1: Update Manifest Repository​

Your test application manifest must use HTTPRoute as the ingress kind for ephemeral environments to work correctly.

Why HTTPRoute?​

The GAP Application CRD (gap.io/v1) uses the spec.ingress.kind field to determine how traffic is routed to your application. If not specified, it defaults to Ingress. For ephemeral environments to properly route traffic to your temporary deployment, you must set this to HTTPRoute.

Update your application manifest​

Ensure your GAP Application spec includes ingress.kind: HTTPRoute. How you configure this depends on your team's manifest structure, but the resulting application spec should include:

apiVersion: gap.io/v1
kind: Application
spec:
  ingress:
    host: your-app.apps-int.testgjensidige.io
    kind: HTTPRoute  # Required for ephemeral environments

Example using Jsonnet​

If your team uses Jsonnet templates, you typically pass ingress_kind which gets mapped to spec.ingress.kind:

app {
  name:: common.name,
  environment:: 'test',
  // ... other fields ...
  ingress_kind:: 'HTTPRoute',  // Required for ephemeral environments
}
important

The spec.ingress.kind must be set to HTTPRoute for ephemeral environments. If not specified, the GAP Application defaults to Ingress and the ephemeral deployment will not be accessible.

Step 2: Create PR Release Workflow​

Create a new workflow file .github/workflows/pr-release.yaml in your code repository.

Key Configuration​

1. Set up the workflow trigger for PR events:

on:
  pull_request:
    types: [labeled, synchronize]

This ensures the workflow runs when:

  • The ephemeral-deploy label is added to the PR (labeled)
  • New commits are pushed while the label is present (synchronize)

2. Add the label check in your if conditions:

if: (github.event.action == 'labeled' && github.event.label.name == 'ephemeral-deploy') || (github.event.action == 'synchronize' && contains(github.event.pull_request.labels.*.name, 'ephemeral-deploy'))

3. Add ephemeral-name to the dispatch action:

- name: "Release PR (Ephemeral Test)"
  uses: gjensidige/gap-workflow-dispatch-action@main
  with:
    # ... other fields from your existing workflow ...
    ephemeral-name: ${{ github.event.pull_request.number }}

The ephemeral-name parameter uses the PR number to create a unique ephemeral environment for each pull request.

Step 3: Triggering an Ephemeral Deployment​

Once your workflow is in place, triggering an ephemeral deployment is simple:

  1. Create a Pull Request in your code repository with your changes
  2. Add the ephemeral-deploy label to the PR
  3. Wait for the workflow to complete

The workflow will:

  • Build your application
  • Push the Docker image to Azure Container Registry
  • Create a PR in your manifest repository with the ephemeral configuration

What happens in the manifest repository​

A Pull Request is automatically created in your manifest repository with a title like:

feat(<your-app>/test): ephemeral deploy (name=<PR-number>,app=<your-app>)

This PR contains the updated params.json with your container image and metadata:

{
  "container_image": "gjensidige.azurecr.io/<team>/<app>:<tag>@sha256:...",
  "container_image_tag": "<tag>",
  "github": {
    "workflow_actor_username": "<your-username>",
    "repo_name": "<your-app>",
    "repo_commit_sha": "<commit-sha>",
    "manifest_repo_name": "<manifest-repo>",
    "manifest_repo_commit_sha": "<manifest-commit>"
  }
}

Step 4: Accessing Your Ephemeral Environment​

Once Argo CD syncs the changes, your ephemeral application will be available. You can find it in Argo CD with a name pattern:

<your-app>.<pr-number>.apps-int-test

In Argo CD, you'll see two applications:

  • Your main test deployment (e.g., api-commercial-checkout-dk.apps-int-test)
  • Your ephemeral deployment (e.g., api-commercial-checkout-dk.test.33.apps-int-test)

Updating an Ephemeral Environment​

When you push new commits to your PR:

  1. The workflow automatically triggers (due to synchronize event)
  2. A new image is built and pushed
  3. The manifest PR is updated with the new image
  4. Argo CD syncs the changes

As long as the ephemeral-deploy label is present, any new commits will update the ephemeral environment.

Cleaning Up Ephemeral Environments​

Ephemeral environments are cleaned up automatically when you no longer need them. There are several ways to trigger cleanup:

From your Code Repository PR​

ActionResult
Close the PREphemeral environment is deleted, manifest PR label removed
Remove ephemeral-deploy labelEphemeral environment is deleted, manifest PR label removed
Merge the PREphemeral environment is deleted (merged to main triggers normal deploy)

From the Manifest Repository PR​

ActionResult
Close the PREphemeral environment is deleted
Remove the ephemeral labelEphemeral environment is deleted
info

Closing or removing the label from the manifest repository PR will not close your code repository PR—it will only remove the ephemeral-deploy label from it.