Skip to content

Quickstart (GitLab CI)

Important

This quickstart guide uses GitLab CI 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.

Go from merge request to Uffizzi ephemeral environment in less than one minute...

1. Fork the quickstart repo

Fork the quickstart repository on GitLab. From the project home page, select Fork, then choose a namespace and project slug. Select Fork project.

Click to expand

2. Ensure GitLab CI/CD is enabled for your project

If you don't see the Build > Pipelines option in left sidebar, following these steps to enable it.

Click to expand

3. Open a merge request (MR) for try-uffizzi branch against master in your fork

⚠ Be sure that you’re opening the MR on the branches of your fork (i.e. your-account/master ← your-account/try-uffizzi).

If you try to open a MR for uffizzi/quickstart/~/tree/master ← your-account/~/tree/try-uffizzi, the pipeline will not run in this example.

Click to expand

That’s it! This will kick off a GitLab pipeline and the ephemeral environment URL will be dumped to stdout of the pipeline job.

What to expect

The MR will trigger a pipeline defined in .gitlab-ci.yml that creates a Uffizzi ephemeral environment for the microservices application defined by the quickstart repo. The ephemeral environment URL will be echoed to stdout of the deploy_environment Job. Look for the following line in the job logs:

$ echo "Uffizzi Environment deployment details at URI:${UFFIZZI_CONTAINERS_URI}"
Uffizzi Environment deployment details at URI:https://app.uffizzi.com//projects/8526/deployments/27720/containers

This link will take you to the Uffizzi Dashboard where you can view application logs and manage your environments and team. The environment will be deleted when the MR is merged/closed or after 1 hour (configurable).

You might also want configure a new job to post the URL as a comment to your MR issue or send a notification to Slack or Microsoft Teams, etc. See our Slack notification example here.

How it works

Configuration

Ephemeral environments are configured with a Docker Compose template that describes the application components and a GitLab CI pipeline that includes a series of jobs triggered by a merge_request_event:

  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 to a Uffizzi ephemeral environment and echo the environment URL to the Job logs
  4. Delete the environment

Tip

Each ephemeral environment is available at a predictable URL which consists of https://app.uffizzi.com/ appended with the GitLab merge request domain. For example:
https://app.uffizzi.com/gitlab.com/{account}/{repo}/merge_requests/{merge-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/gitlab.com/acme/example-app/pull/661/api/health

Uffizzi Cloud

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

Our Starter Plan is free for up to two concurrent ephemeral environments. The Pro Plan gives your team access to unlimited environments. If you'd like to self-host Uffizzi on your own Kubernetes cluster, check out our Enterprise Plan. See our pricing for all plan details.

Set up Uffizzi for your application

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