Configure container registries

Connect container registries to CloudBees Unify to cache Docker images locally and enable security scanning of artifacts. You can configure registry mirrors to avoid Docker Hub rate limits and improve build reliability, or integrate with JFrog Artifactory to enable automated binary scans of container images.

To create and manage integrations, you must have administrative rights at the organization level.

Container registry integration types

CloudBees Unify supports three types of container registry integrations:

Registry mirror: Cache Docker images locally to reduce reliance on external registries and avoid rate limits
JFrog Artifactory: Enable security scanning of artifacts published to JFrog container registries
AWS ECR: Connect to Amazon Web Services Elastic Container Registry using OIDC authentication

Each section covers how to configure that integration and how to use it in your workflows.

Registry mirror

A registry mirror allows users to cache Docker images locally, reducing reliance on external registries like Docker Hub and avoiding rate limits that can disrupt workflows.

Prerequisites

Before configuring a registry mirror, ensure the following:

Existing Docker registry: You must have an existing Docker registry that can act as a mirror, or the ability to set one up within your infrastructure.
Network configuration: Ensure your network allows communication between CloudBees Unify and the custom registry mirror, including necessary ports and firewall rules.
Registry prefixes: Understand the registry prefixes (for example, docker.io/library) used in your Docker images for correctly routing image pulls through the mirror.
Authentication: If your custom registry mirror requires authentication, ensure you have the necessary credentials ready.
Monitoring tools: Set up monitoring tools to track performance and usage of your registry mirror.
Backup plan: Have a backup plan in case the registry mirror fails to ensure builds can continue without disruption.

Configuration considerations

Review these important considerations before configuring a registry mirror:

Unique prefixes: Ensure each prefix is unique across all configured rules, as this determines how CloudBees Unify selects the appropriate mirror.
Suffix appending: When rewriting an image reference based on a matching mapping rule, the suffix (the string after the matched prefix) of the container image reference is appended to the registry mirror URL.
Mirror fallback: If the image is not found on the mirror, CloudBees Unify pulls from the original docker.io registry depending on configuration and fallback settings.

Create registry mirror integration

To configure a registry mirror in CloudBees Unify:

Navigate to Configurations Integrations.

Select Create integration. The list of available integration types is displayed.

You can locate an integration type three different ways: scroll through the alphabetical list grouped by category, use the search bar to search by name, or use the options to filter by category. If the integration type is not listed, hover over the Category menu to redisplay the integration category list and select another category.

Select Container Registry Mirror integration from the list of available integration types.
Enter a Name. For example, docker-hub.
(Optional) Enter a Description.

Enter the Prefix, such as the registry server or path, to specify where images are routed through the mirror. For example, docker.io.

If docker.io is entered for the Prefix, CloudBees Unify first attempts to pull the image reference from registry.example.com/mirror/dockerhub/library/ubuntu:latest. If the image is not found within the mirror, or the mirror is unavailable, CloudBees Unify falls back to using the original path: docker.io/library/ubuntu:latest.

Enter the URLs of your custom registry Mirrors, using Enter as a delimiter. For example, https://registry.example.com/mirror/dockerhub.

The registry mirror integration is created accordingly.

To verify the integration, navigate to Configurations Integrations and confirm the registry mirror is listed. When configured correctly, Docker image pulls are routed through your specified registry mirror, helping to avoid rate limits and improve build reliability.

Use registry mirrors in workflows

CloudBees Unify applies the configured registry mirror to all workflows that require Docker images by automatically using the specified mirror for image pulls and pushes.

Automatic image reference rewriting

Image references are automatically rewritten based on your organization’s global registry mirror configuration. This ensures all Docker image requests within your workflows are directed to the configured mirror without additional manual intervention.

Authentication requirements

Despite the registry mirror’s automatic application, users must explicitly authenticate with each mirror used within their workflows. This is necessary to ensure secure and authorized access to the images stored in these mirrors.

To handle authentication, use actions such as configure-oci-credentials or configure-ecr-credentials, depending on the type of registry mirror you are using.

Advanced usage

If you create a custom action, you must use the context variable provided by CloudBees Unify (cloudbees.registries) to access and programmatically use the registry configuration.

JFrog Artifactory

Create a JFrog Artifactory integration to connect CloudBees Unify to your JFrog container registries and enable automated security scanning of artifacts.

Configure JFrog Artifactory integration

To integrate with JFrog Artifactory:

Navigate to Configurations Integrations.
Select Create integration. The list of available integration types is displayed.
Select JFrog Artifactory from the list of available integration types.
Enter the following information:
- An integration Name (no spaces are allowed).
- (Optional) A Description.
- The Hostname/IP of your JFrog Artifactory instance.
- Enter the Port number for your JFrog Artifactory instance.
Select an Authentication type:
- Username/Password: Enter your JFrog username and password.
- Personal access token: Enter your JFrog personal access token.
Select Submit.

Your JFrog Artifactory instance is now connected to CloudBees Unify, and the integration is listed under Integrations.

To verify the integration, navigate to Configurations Integrations and confirm the JFrog Artifactory integration is listed. When configured correctly, binary scans can be triggered for artifacts published to your JFrog package management system.

Trigger binary scans with JFrog integration

Once the JFrog integration is created, you can start scanning artifacts published to your JFrog package management system.

Binary scanning for JFrog Artifactory currently supports container registry artifacts only. The Kaniko build step does not automatically report artifact data to CloudBees Unify.

Binary scans triggered through JFrog Artifactory integration are supported for:

CloudBees CI
Jenkins
CloudBees Unify workflows

Configure scan triggers using Jenkins

Use the registerBuildArtifactMetadata and registerDeployedArtifactMetadata steps in your Jenkinsfile. Each step creates an artifact record and triggers an automated binary scan.

For detailed information on configuring these steps, refer to Publish CI build artifacts and Publish CI deployed artifacts.

Configure scan triggers using CloudBees Unify workflows

Use the cloudbees-io/register-build-artifact action in your workflow, pointing the artifact URL to your JFrog Artifactory location. This action registers the artifact metadata and triggers an automated binary scan.

The following example workflow demonstrates registering an artifact from JFrog Artifactory:

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: My workflow

on:
  workflow_dispatch:

jobs:
  build:
    steps:
    - name: Checkout
      uses: cloudbees-io/checkout@v1
      id: checkout
    - name: Register an artifact with {PRODUCT}
      uses: cloudbees-io/register-build-artifact@v2
      id: register
      with:
        name: myApp
        url: cb.jfrog.io/myrepo/myimg:1.0.0
        version: 1.0.0
    - name: Print output parameter artifact ID
      uses: docker://alpine:latest
      shell: sh
      run: |
        echo "artifact ID for myApp:${{ cloudbees.version }} is: ${{ steps.register.outputs.artifact-id }}"▼

When artifact registration executes successfully, CloudBees Unify:

Registers the build artifact metadata.
Initiates a binary scan of the artifact in JFrog Artifactory.
Reports scan results in CloudBees Unify analytics.

AWS ECR

Connect CloudBees Unify to Amazon Web Services (AWS) Elastic Container Registry (ECR) to enable workflow access to private container images hosted in AWS.

Configure AWS ECR integration

Before you begin, you must establish an OIDC identity trust relationship between AWS and CloudBees Unify and create an AWS IAM role with the required permissions. Refer to Set up OIDC for more information.

To integrate with AWS ECR:

Navigate to Configurations Integrations.
Select Create integration. The list of available integrations displays.
Select Amazon ECR from the list of available integration types.
Enter an integration Name (no spaces are allowed).
(Optional) Enter a Description.
Enter the ECR Hostname in the following format:
```
<AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com (1)(2)▼
```
1 <AWS_ACCOUNT_ID> is your AWS account ID.

2 <REGION> is the AWS region you are using.
Enter the Role ARN in the following format:
```
arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ROLE_NAME> (1)(2)▼
```
1 <AWS_ACCOUNT_ID> is your AWS account ID.

2 <ROLE_NAME> is the role name you are assuming.
Enter the AWS region you are using.
Select Submit.

Your AWS ECR account is connected to CloudBees Unify and listed under Integrations.

1	`<AWS_ACCOUNT_ID>` is your AWS account ID.
2	`<REGION>` is the AWS region you are using.

1	`<AWS_ACCOUNT_ID>` is your AWS account ID.
2	`<ROLE_NAME>` is the role name you are assuming.

Configure container registries

Container registry integration types

Registry mirror

Prerequisites

Configuration considerations

Create registry mirror integration

Use registry mirrors in workflows

Automatic image reference rewriting

Authentication requirements

Advanced usage

JFrog Artifactory

Configure JFrog Artifactory integration

Trigger binary scans with JFrog integration

Configure scan triggers using Jenkins

Configure scan triggers using CloudBees Unify workflows

AWS ECR

Configure AWS ECR integration

Related pages