GitHub Actions
Virtual Cluster

GitHub Actions Virtual Cluster Example

Follow the example guide below to see how the Uffizzi virtual cluster integration with GitHub Actions works end-to-end. Or you can skip ahead to the recipe if you'd rather get started integrating Uffizzi with your project.

Get Started

Fork the quickstart repo

Start by forking the quickstart (opens in a new tab) repository on GitHub, if you haven't already.


Be sure to uncheck the option Copy the main branch only. This ensures that the try-uffizzi branch will be included in your fork.

Fork quickstart repo

Enable GitHub Actions workflows

Enable GitHub Actions workflows for your fork by selecting Actions, then select I understand my workflows, go ahead and enable them.

Enable GitHub Actions

Open a PR

Open a pull request for try-uffizzi branch against main in your fork.


Be sure that you're opening a PR on the branches of your fork (i.e. your-account/mainyour-account/try-uffizzi). If you try to open a PR for UffizziCloud/mainyour-account/try-uffizzi, the Actions workflow will not run in this example.

Open a pull request

What to expect

The PR will trigger a GitHub Actions workflow (opens in a new tab) that uses the Uffizzi CLI and Kubernetes manifests to create a Uffizzi ephemeral environment for the microservices application defined by the repo. When the workflow completes, the ephemeral environment URL will be posted as a comment in your PR issue.


This virtual cluster is configured with a Uffizzi Ingress, which makes the web service available at a predictable URL, consisting of appended with the GitHub pull request domain. For example:{account}/{repo}/pull/{pull-request-number}.

You can make requests to specific endpoints by appending a route to the end of the URL. For example:

To learn how to enable predicable URLs for your ephemeral environments, see the [Uffizzi Ingress(/docs/ingress) documentation].

How it works

Ephemeral environments are configured with a Kubernetes manifest (opens in a new tab) that describes the application components and a GitHub Actions workflow (opens in a new tab) that includes a series of jobs triggered by pull_request events.

When a pull request is open/closed/reopened/updated, the workflow will run the following jobs:

  1. Build and Push the Image
  2. Create a virtual cluster using the Uffizzi CLI in a GitHub Actions runner
  3. Apply a kustomization to deploy the application on the virtual cluster
  4. Post a new comment or update an existing comment with the ephemeral environment URL and instructions for accessing the environment
  5. Delete the virtual cluster when the PR is closed or merged

Connecting to the Cluster

To run kubectl commands on this cluster, first update your kubeconfig by running:

uffizzi cluster update-kubeconfig [CLUSTER_NAME]

Tip: We recommend using the pull request number for cluster names to make it easy to connect to your clusters, e.g.: uffizzi cluster update-kubeconfig pr-281

To find the ingress of this deployment, run:

kubectl get ingress web --kubeconfig ~/.kube/config -o json | jq '.spec.rules[0].host' | tr -d '"'

Next Steps

Now that you've seen the process from start to finish, add Uffizzi to your own project on GitHub.