Skip to content

Quickstart (GitHub Actions)

Important

This quickstart guide uses GitHub Actions as a fast way to demonstrate Uffizzi capabilities, but Uffizzi will work with any CI platform. If you don't have a CI provider, you can use Uffizzi CI, a free build service that integrates with your GitHub repository.

Get started using Uffizzi Preview Environments in 3 simple steps...

1. Fork the quickstart repository

Fork the quickstart 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.

Click to expand

2. Enable GitHub Actions workflows for your fork

Select Actions, then select I understand my workflows, go ahead and enable them. GitHub Actions is free for public repositories.

Click to expand

3. 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/main ← your-account/try-uffizzi). If you try to open a PR for UffizziCloud/main ← your-account/try-uffizzi, the Actions workflow will not run in this example.

That's it! This will kick off a GitHub Actions workflow and post the Preview Environment URL as a comment to your PR issue.

uffizzi-bot

What to expect

The PR will trigger a GitHub Actions workflow that creates a Uffizzi Preview Environment for the microservices application defined by the repo. The Preview 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 Preview Environment and comment is deleted when the PR is merged/closed or after 1 hour (configurable).

Tip

Each Preview Environment is available at a predictable URL which consists of https://app.uffizzi.com/ appended with the GitHub pull request domain. For example:
https://app.uffizzi.com/github.com/{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:
https://app.uffizzi.com/github.com/boxyhq/jackson/pull/661/api/health

How it works

Configuration

Previews are configured with a Docker Compose template that describes the application configuration and a GitHub Actions workflow 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
  2. Render a Docker Compose file from the Docker Compose template and the built images
  3. Deploy the application (per the Docker Compose file) to a Uffizzi Preview Environment and post a comment to the PR issue
  4. Delete the Preview Environment when the PR is merged/closed or after 1h

Uffizzi Cloud

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

The Starter Plan is free includes up to two concurrent preview environments. See our pricing for plan details. Alternatively, you can install open-source Uffizzi if you have your own Kubernetes cluster.

Set up Uffizzi for your application

Now that you know how Uffizzi works, set up Uffizzi for your application or service ➡️.