Github Actions is the go to CI/CD system for projects on Github. To create ephemeral environments from your GitHub Actions builds, an existing workflow can be extended to use Uffizzi in a few simple steps.
Uffizzi helps developers create and manage ephemeral environments which can be used for testing and previewing your application. It simplifies the process of setting up dynamic ephemeral environments while reducing the time and resources needed to verify and release changes. To learn more about these environments check out Uffizzi’s preview environment guide where we dive deep in one of the most popular use cases Uffizzi’s ephemeral environments.
The most popular and easily accessible CI/CD system: GitHub Actions (GHA), is a continuous integration and delivery system that enables developers to build, test, and deploy code directly from their GitHub repositories. To learn more, check the GitHub Actions documentation. We will see how Uffizzi can be integrated with GHA in a few simple steps.
By integrating Uffizzi with GitHub Actions, teams can seamlessly create ephemeral environments for every code change, ensuring that each modification is tested and validated before being deployed to production.
Uffizzi’s goal is to make ephemeral environments as approachable and easy to use as possible. Integrating with github actions helps cover a majority of the developer user base which would benefit from Uffizzi. The user doesn’t have to login to create an account if they are setting Uffizzi up for their open source project. We have made it as easy as possible for you to set up Uffizzi with your existing github actions pipeline. We will be following along the quickstart repo to aid us in understanding the process.
On our way to ease creation of ephemeral environments, we created the reusable workflow which is provided by the Uffizzi preview-action github action. We will be using this github action which will aid us in extending our workflow for the preview environment.
Uffizzi runs on top of Kubernetes but the end user doesn’t have to bother with all that. If the application has a preconfigured Dockerfile and docker-compose ready to go with it then configuring Uffizzi is going to be straightforward. If your application doesn’t already have a Dockerfile and/or a docker-compose config we will be discussing a little bit about that in this blog, but these two configurations are prerequisites for Uffizzi.
We are going to set up ephemeral environments for a simple voting application which has the following architecture
As you can see above, there are 6 moving parts at play here. Each of the 6 components are containers here and they are communicating via the container networking present in the Pod. Let’s go step by step to understand what each of the components do via the user story we have here.
Now we know how the application works, let’s take a peek at the Uffizzi configuration derived from the docker-compose configuration.
The above Uffizzi configuration has been derived from a docker-compose configuration for the same voting application. All these containers will be created in the same pod and have access to the same pod network. So seeing to it that all of them are exposed on unique ports is important.
The x-uffizzi configuration above is the most important here. A uffizzi configuration is derived from a docker-compose so adding this configuration is important to let Uffizzi know that this configuration is indeed meant to be used with Uffizzi. Here we describe the ingress service and port which would be accessed. The loadbalancer will be taking care of all the requests coming into the ephemeral environment and then routing it as necessary.
In the above configuration we can see that the result, vote and worker images have placeholders. These placeholders will be replaced once the images are built using github actions and are then ready to be consumed. The postgres credentials are populated from github actions when creating the ephemeral environment.
Now that we have set up the configuration for our ephemeral environment, let’s see how we can use this with Uffizzi.
Now that we have finalised our Uffizzi configuration, let’s use it to create ephemeral environments for our application on every pull request. Let’s consider two scenarios:
For each of the two above, the configuration changes based on the access control to the project. Setting up Uffizzi + Github Actions using the reusable workflow is straightforward for internal projects as execution rights are only in the hands of project maintainers and developers. This is a default Github Actions behavior. For us to configure Uffizzi + Github Actions for an open source project, we have to use the two stage workflow. We will briefly talk about how it works and how you can configure it for use in the subsequent sections. First, let’s look at how we can extend Github Actions to use Uffizz for an internal project using the reusable workflow.
The quickstart repo already has github actions set up to use the reusable workflow. To understand the pipeline let’s look at uffizzi-preview.yaml file where the necessary images are being built and then pushed to a container registry. Here we can see 4 images being built and then pushed to the Uffizzi Ephemeral Image registry. As all the build jobs follow the same pattern, let’s look at a single job to understand what is happening in the build job:
In the above build job first we are going to checkout the code base, then create a UUID for the image. The UUID is important as it helps to obfuscate information regarding which repo or project was the image built for. This image will be pushed to the registry and the final step. This job outputs the tag of the image which has been built and pushed. This will be helpful in the deploy stage to identify the image to be used for the preview.
Once the images are built, the placeholders in the configuration are replaced with actual values and then the ephemeral environment deploy job is triggered. The following is what the relevant jobs looks like:
Above you there are two jobs which together help deploy the ephemeral environment:
When setting up this reusable workflow for your own project, you will have to update the docker build based on the location of your dockerfile and adjust the number of jobs based on the number of images you need for your compose file.
The reusable workflow in this setup works great for your internal projects where the only people accessing and/or contributing to the project are the ones who have permissions to execute github workflows and create pull requests. If there are outside contributors on this project they would not be able to trigger creation of ephemeral environments as they would not have the necessary credentials to do so. Hence, using just one workflow would mean that every outside contributor to your project would need a Uffizzi account before they could preview their pull request, or else maintainers would need to share credentials with contributors. A two-stage workflow solves this problem by first building the application in the context of the contributor's head branch, then delegating responsibility to the target base branch in the second stage to authenticate with Uffizzi.
The reusable workflow can be extended to work in a two stage mode to allow contributors to create pull requests and consume ephemeral environments without needing credentials or accounts on Uffizzi if they are new uses on Uffizzi itself.
The workflow in this case is divided between the build and deploy part where the build part is executed in context of the pull request branch to build the relevant image. The deploy part of the repo runs in context of the main repo. It is triggered when the build is completed. If you are interested in the motivation and working of the two stage workflow, this blog post dives deeper in the same. Let’s look at the triggers for each to understand their relationship, let’s take meilisearch as an example where this has been implemented:
In the above excerpts from the two stage workflow files we can see that there is a natural trigger for the uffizzi-build.yml. The build workflow is triggered when a pull request is opened or updated. In the uffizzi-preview-deploy.yml we can see that the workflow is triggered only when the first workflow completes.
Uffizzi has been used in multiple open source projects across github with Github Actions. These projects are all listed here.
Once you know how to set up a github actions workflow to trigger ephemeral environments, you can now start evolving them as per your needs. The following are a few ways you can start getting creative with your Ephemeral Environments.
If you have a project for which you would like to build ephemeral environments for and discuss the different ways you can use them to better fit your needs, we look forward to speaking with you. You can get in touch with us by going to https://www.uffizzi.com/contact and we will reach out to you !