GitHub Actions

GitHub Actions Compose Example

Follow the example guide below to see what how the Uffizzi Compose 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

Create a Compose environment using the Preview Environments Action (opens in a new tab). This action creates/updates/deletes an ephemeral Docker Compose environment every time a pull request is opened, updated, closed, or reopened.

Fork the quickstart repo

Start by forking the quickstart-compose (opens in a new tab) repository on GitHub.


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

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

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 creates a Uffizzi Ephemeral Environment for the microservices application (opens in a new tab) defined by the repo. The environment URL will be posted as a comment in your PR issue when the workflow completes, along with a link to the Uffizzi Dashboard where you can view application logs. The environment and comment is deleted when the PR is merged/closed or after 1 hour (configurable).


Each ephemeral environment is available at a predictable URL which consists 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:

How It Works

Previews are configured with a Docker Compose template (opens in a new tab) that describes the application configuration and a GitHub Actions workflow (opens in a new tab) that includes a series of jobs triggered by a pull_request event and subsequent push events:

  1. Build and push images to a container registry (opens in a new tab)
  2. Render a Docker Compose file (opens in a new tab) from the Docker Compose template and the built images
  3. Deploy the application (per the Docker Compose file) to a Uffizzi Preview Environment (opens in a new tab) and post a comment to the PR issue
  4. Delete the Preview Environment (opens in a new tab) when the PR is merged/closed or after 1h

Running this workflow will create a Uffizzi Cloud (opens in a new tab) account and project from your GitHub user and repo information, respectively, if they do not already exits. If you sign in to the Uffizzi Dashboard (opens in a new tab) you can view logs, password protect your previews, manage projects and team members, set role-based access controls, and configure single-sign on (SSO).

Next Steps

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