Uffizzi CI¶

If you use GitHub Actions or another CI provider, you do not need to use Uffizzi CI.

What is Uffizzi CI?¶

Uffizzi CI is an integrated build and deployment service provided by Uffizzi Cloud free of charge. Choose this solution if you don't already have a CI platform or don't want to use your existing solution to build preview images.

Every time you push a new commit to your repository, Uffizzi CI receives a webhook and builds your application from source. This ensures that the latest changes are always included in your previews. To use Uffizzi CI, your code must be stored in a GitHub repository.

Setting up Uffizzi CI¶

To set up Uffizzi CI, you'll first need to create a project in the Uffizzi Dashboard, then install and authorize the Uffizzi GitHub App. Once you've done that, you'll connect a Compose file in your project settings.

1. Create a Uffizzi CI project¶

If you haven't already done so, create a Uffizzi CI project. Login to the Uffizzi Dashboard, then navigate to Account > Projects. Select New project > Uffizzi CI > Configure GitHub

Click to expand (Screenshots)

2. Install & Authorize the Uffizzi GitHub App¶

After selecting Configure GitHub, you will be redirected to a GitHub login page to install and authorize the Uffizzi Cloud GitHub App. If you have more than one GitHub account, be sure to install the GitHub App on the same account that you used to create your Uffizzi account. To install the Uffizzi Cloud GitHub App on an organizational account, you must have Owner permissions for your GitHub Organization.

Click to expand (Screenshots)

Install Uffizzi Cloud on your GitHub account

---

Next, choose which repositories you wish to preview, then select Install & Authorize. Uffizzi requests only the minimum permissions it needs, which includes read access to your code and write access to pull request issues for posting comments. You can manage the GitHub App permissions from the Developer Settings page in GitHub.

3. Add a Compose file in project settings¶

After installing and authorizing the GitHub App, you will be redirected back to the Uffizzi Dashboard. From there you can select a repository to complete project set up.

1. Select Set up project for your desired repository
2. Add your docker-compose.uffizzi.yml file in Project > Settings > Compose file. Be sure to choose the branch that you merge into, i.e. your target base branch. For example, if your team opens pull requests against main, select this branch.
3. Save and validate your Compose; resolve any errors
4. Check your configuration with a test deployment

Click to expand (Screenshots)

1. Select Set up project for the repository you just forked

2. Add your `docker-compose.uffizzi.yml` file in Project > Settings > Compose. Be sure to choose the branch that you merge into, i.e. your target base branch.

3. Save and validate your Compose; resolve any errors

4. Check your configuration with a test deployment

How to use Uffizzi CI¶

Once everything is configured on both GitHub and Uffizzi, you don't need to do anything special to get Uffizzi CI working. Open pull requests as you normally do. Uffizzi CI will work in the background to build your application every time a PR is opened, closed, reopened, or synchronized (i.e. new commits). Uffizzi will post a comment to your pull request issue with a link to your Preview Environment. You can also login to the Uffizzi Dashboard to see a list of all your previews and your application logs.

Click to expand (Screenshots)

Open a pull request on GitHub:

---

Uffizzi CI will post a comment to your pull request issue:

---

Log in to the Uffizzi Dashboard to see a list of Preview Environments and your application logs:

When are previews triggered?¶

Currently Uffizzi CI will only create previews for pull requests that target the branch you configure in the Uffizzi Dashboard (Project > Settings > Compose file > Branch > Path to Compose).

Click to expand (Screenshots)

Open a pull request on GitHub:

For example, if you configure Uffizzi CI with a Compose file from your main branch, Uffizzi will apply the following logic:

Previews will be triggered for pull requests matching:

• main ← {topic_branch}

Previews will not be triggered for pull requests matching:

• {topic_branch} ← main or
• {topic_branch} ← {topic_branch}

Note that this design may change in a future release of Uffizzi CI, such that all pull requests will be previewed for a given project.