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.
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.
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/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.
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 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
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:
- Build and push images to a container registry (opens in a new tab)
- Render a Docker Compose file (opens in a new tab) from the Docker Compose template and the built images
- 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
- 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.