Authenticate with a container registry¶

You can authenticate with the container registries you use in one of two ways, depending on which CI solution you choose:

External CI¶

If you're using an external CI provider, such as GitHub Actions, GitLab CI, or CircleCI, you must add registry credentials as secrets in your provider's interface.

Uffizzi supports the following container registries:
- Amazon ECR
- Azure Container Registry (ACR)
- Docker Hub
- GitHub Container Registry (GHCR)
- Google Container Registry (GCR)
- Docker Registry (generic)

See the following GitHub Actions example (full example available here) that passes a GitHub Container Registry access token to the Uffizzi resuable workflow:

GitHub Actions example

deploy-uffizzi-preview:
  name: Use Remote Workflow to Preview on Uffizzi
  needs: render-compose-file
  uses: UffizziCloud/preview-action/.github/workflows/reusable.yaml@v2.2.0
  if: ${{ github.event_name == 'pull_request' && github.event.action != 'closed' }}
  with:
    compose-file-cache-key: ${{ needs.render-compose-file.outputs.compose-file-cache-key }}
    compose-file-cache-path: docker-compose.rendered.yml
    username: adam+1@idyl.tech
    server: https://app.uffizzi.com
    project: my-application-c2e3
  secrets:
    password: ${{ secrets.UFFIZZI_PASSWORD }}
    url-username: admin
    url-password: ${{ secrets.URL_PASSWORD }}
    personal-access-token: ${{ secrets.GHCR_ACCESS_TOKEN }}
  permissions:
    contents: read
    pull-requests: write

Uffizzi CI¶

If you're using Uffizzi CI, you can choose to add your application components from source code or as pre-built images pulled from a container registry. This guide describes the process of configuring Uffizzi to to pull and deploy images from your container registry. If your container registry provider is not listed below, let us know.

Amazon ECR¶

To configure Uffizzi to pull images from your Amazon ECR, it is recommended that you first create a dedicated IAM user for this purpose. After creating this IAM user, add its credentials in the Uffizzi Dashboard. Finally, configure webhooks to send notifications to Uffizzi when you push new images to ECR.

Create IAM user to authorize Uffizzi to pull images from ECR

To fetch container images from your private ECR repositories, Uffizzi requires an API access key for an IAM User within your AWS Account. It's a best practice to grant this user only the permissions required. This section will walk you through creating a new IAM User, granting it strict permissions, and creating an API access key.

The easiest way to create this user is to use the AWS command-line interface (CLI). Make sure you have installed and configured the `aws` command on your workstation or container, including setting the default region to match your ECR repositories.

Create a new IAM User within your AWS Account. If you get an error that it already exists, that's fine.

aws iam create-user --user-name uffizzi --output table

Attach an Amazon-managed policy to the new User. This grants permission only to list and read images.

aws iam attach-user-policy --user-name uffizzi --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly

Create and obtain an API access key for this user. You'll need the output of this command soon.

aws iam create-access-key --user-name uffizzi --query "[join(' ', ['Access Key ID:', AccessKey.AccessKeyId]), join(' ', ['Secret Access Key:', AccessKey.SecretAccessKey])]" --output table

When you configure ECR within Uffizzi in the next step, you'll need these values.

Add IAM user credentials in the Uffizzi Dashboard

In the Uffizzi Dashboard (UI), navigate to Settings > Integrations. There you will see a list that includes container registries supported by Uffizzi. Select CONFIGURE next to the Amazon ECR option.

When prompted, sign in to ECR with your registry domain, access key ID, and your secret access key. Once authenticated, Uffizzi will now be able to pull images from your registry.

Configure webhooks for Continuous Previews from ECR

After configuring AWS ECR to pull images, you'll probably also want to enable Continuous Previews when you push a new container image. This requires configuring AWS EventBridge to send Uffizzi notifications via webhook HTTP requests. This section will walk you through configuring these webhooks.

The easiest way to configure these webhooks is to use the AWS CLI. Make sure you have installed and configured the aws command on your workstation or container, including setting the default region to match your ECR repositories.

Download the following shell script to configure these webhooks for you:

wget https://raw.githubusercontent.com/UffizziCloud/docs/main/docs/assets/scripts/uffizzi_ecr_webhook_configure.bash

Review the contents so you understand what you're executing. Then execute the script:

bash ./uffizzi_ecr_webhook_configure.bash

You should see output about the resource you've just created. If you see errors about resources already existing that's fine; that means someone else has already configured them.

You should also see the EventBridge Rule and other resources within the AWS Console:

Removing webhook configuration

We've also provided a script to remove all of this configuration. Use this when you want to reconfigure the webhooks or when you no longer require automatic deployment to Uffizzi.

Download the removal script:

wget https://raw.githubusercontent.com/UffizziCloud/docs/main/docs/assets/scripts/uffizzi_ecr_webhook_remove.bash

Review the contents so you understand what you're executing. Then execute the removal script:

bash ./uffizzi_ecr_webhook_remove.bash

Removing IAM User

You can revoke Uffizzi's access to your ECR repositories by detaching the policy from the IAM User:

aws iam detach-user-policy --user-name uffizzi --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly

If no longer needed, you can then delete the IAM User. You must first delete all of the user's API Access Keys.

Azure Container Registry (ACR)¶

To configure Uffizzi to pull images from your ACR, it is recommended that you first create a dedicated service principal for this purpose, along with an Application and Subscription. After creating these resources, add the service principal's credentials in the Uffizzi Dashboard. Finally, configure webhooks to send notifications to Uffizzi when new images or tags are pushed to ACR.

Create Azure service principal to authorize Uffizzi to pull images from ACR

To access your container images directly, Uffizzi requires access to your Azure Container Registry. The easiest way to accomplish this is to create a service principal and grant it the `ACRPull` role.

You may need to create an Application with a Subscription.

Once you have an active Subscription and a Container Registry, you can use the create-for-rbac command to create a service principal and simultaneously grant it the ACRPull role:

az ad sp create-for-rbac --name uffizzi-example-acrpull --scopes /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/uffizzi-example/providers/Microsoft.ContainerRegistry/registries/uffizziexample --role acrpull

This command will output a JSON object with some values you will need later: appId and password. See the Azure CLI documentation for details about this command.

Add your Azure service principal in the Uffizzi Dashboard

To grant Uffizzi access to pull images from your ACR, you will need:

Your registry domain (registry-name.azurecr.io)
Application ID
Password

The Application ID and Password are provided in the output from the create-for-rbac command above, or they can be obtained within the Azure web portal.

Log in to the Uffizzi Dashboard (UI) and navigate to Settings > Integrations then select CONFIGURE next to the ACR option.

Enter your credentials when prompted, then click Sign in to Azure Container Registry. Uffizzi should now have access to pull images from your ACR.

Configure webhooks for Continuous Previews from ACR

If you've added images from ACR to a template or compose file, you'll probably also want to enable continuous previews when you push a new container image. This requires adding a webhook to send Uffizzi notifications. This section will walk you through configuring this webhook.

The easiest way to configure these webhooks is to use the Azure command-line interface (CLI). Make sure you have installed and configured the az command on your workstation or container.

First identify which ACR Registry you want to use for automatic deployments.

az acr list --output table

Use the name of that registry when you add the webhook:

az acr webhook create --registry <registry name> --name uffizzi --actions push --uri https://app.uffizzi.com/api/v1/webhooks/azure

Removing webhook configuration

To stop sending notifications to Uffizzi, you can remove the webhook you configured above:

 az acr webhook delete --registry <registry name> --name uffizzi

GitHub Container Registry (GHCR)¶

To configure Uffizzi to pull images from GHCR, you must first create an personal access token to provide to Uffizzi. Once authorized, Uffizzi will automatically configure webhooks on your registry to be notified when you push new images.

Create a personal access token for GHCR

To create a GitHub personal access token follow these instructions. Your token needs read:packages scope.

Authorize Uffizzi to pull container images from GHCR

Log in to the Uffizzi Dashboard and navigate to Settings > Integrations, then select CONFIGURE next to the GitHub Container Registry option.

Enter your GitHub username and the personal access token you created, then select Sign in to GitHub Container Registry. Uffizzi should now have access to pull images from your GHCR registry. Uffizzi will automatically configure a webhook to be notified when you push new images.

Deleting the personal access token for GHCR

Log in to your GitHub account, then navigate to Settings > Developer settings > Personal access tokens. Then select Delete for the token you want to delete. This will revoke Uffizzi's access to your GHCR registry.

Google Container Registry (GCR)¶

To configure Uffizzi to pull images from your GCR, you need to add your GCR key file in the Uffizzi Dashboard (UI). Once added, configure a webhook to send notifications to Uffizzi when you push new images to GCR.

Authorize Uffizzi to pull container images from GCR

To grant Uffizzi access to pull images from your GCR, you will need a JSON key file.

Log in to the Uffizzi Dashboard and navigate to Settings > Integrations, then select CONFIGURE next to the GCR option.

Upload or copy and paste your key file when prompted, then click Add GCR Key File. Uffizzi should now have access to pull images from your GCR.

Configure webhooks for continuous previews from GCR

If you've added images from GCR to a template or compose file, you'll probably also want to enable continuous previews when you push a new container image. This requires adding a webhook to send Uffizzi notifications. This section will walk you through configuring this webhook.

The easiest way to configure these webhooks is to use the Google Cloud command-line interface (CLI). Make sure you have installed and configured the gcloud command on your workstation or container.

First, create a Topic on Google's Pub/Sub API:

gcloud pubsub topics create gcr

Then configure a Subscription to notify Uffizzi:

gcloud pubsub subscriptions create uffizzi-gcr-webhook --topic=gcr --push-endpoint=https://app.uffizzi.com/api/v1/webhooks/google --expiration-period=never --message-retention-duration=10m

If these commands fail, make sure you have enabled the Pub/Sub API for your Google Cloud Project. You may also need to specify --project if you have multiple Google Cloud Projects.

Learn more about configuring notifications from GCR.

Removing Webhook Configuration

To stop sending notifications to Uffizzi, you can remove the webhook you configured above:

gcloud pubsub subscriptions delete uffizzi-gcr-webhook

If this was your only Subscription to the GCR Topic, you could also delete that Topic.

If that was your only Topic, you could also disable the Pub/Sub API.

Docker Hub¶

To configure Uffizzi to pull images from your private Docker Hub registry, it is recommended that you first create an Access Token to provide to Uffizzi. Once authorized, Uffizzi will automatically configure webhooks on your registry to be notified when you push new images.

Create an access token for Docker Hub

Log in to Docker Hub, then navigate to Account Settings > Security and select the New Access Token button. In the Access Token Description field, enter "uffizzi" or a similar description. For Access permissions choose Read-only, then select Generate to create your Access Token.

On the next screen, you should see your Accesss Token. Save this value, as you will need it in the next step.

Authorize Uffizzi to pull container images from Docker Hub

Log in to the Uffizzi Dashboard and navigate to Settings > Integrations, then select CONFIGURE next to the Docker Hub option.

Enter your Docker ID and the access token you created, then select Sign in to Docker Hub. Uffizzi should now have access to pull images from your Docker Hub registry. Uffizzi will automatically configure a webhook to be notified when you push new images.

Deleting the access token for Docker Hub

Log in to Docker Hub, then navigate to Account Settings > Security. Select the the checkbox next the access token you added in the Uffizzi Dashboard, then select Delete and Delete Forever to confirm.