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 four 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 (ECR) using OIDC authentication.
Nexus integration: Connect to Nexus container registry to store, manage and retrieve container images. This is integrated with binary security scanning of container images through release workflow.

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.

Sonatype Nexus integration

Sonatype Nexus integration enables you to connect CloudBees Unify to a Nexus container registry to store, manage, and retrieve container images. This is integrated with binary security scanning of container images through release workflow. After the integration is configured, binary scans trigger automatically whenever a continuous visibility into image vulnerabilities without requiring manual scan invocation.

This configuration currently only supports image repositories.

Configure Sonatype Nexus integration

To integrate CloudBees Unify with your Sonatype Nexus instance:

Navigate to Configurations Integrations.
Select Create integration. The list of available integration types is displayed.

Locate an integration type by scrolling through the alphabetical list grouped by category, using the search bar, or filtering by category.
Select Sonatype Nexus from the list under Container Registries and provide the following details:
- Name: A unique name for the Nexus integration.
- Description: (Optional) A short description.
- Hostname/IP: The Nexus instance IP address.
- IP Port: The port number of your Nexus instance (by default, 8081 for HTTP and 8443 for HTTPS).
Select an Authentication type:
- Username/Password: Enter your Nexus service account username and password.
- Personal access token: Enter the secure authentication credential to access the instance.
Select Submit.

Your Sonatype Nexus instance is now connected to CloudBees Unify and listed under Integrations.

To verify the integration, navigate to Configurations Integrations and confirm the Sonatype Nexus integration is listed.

When configured correctly, binary scans are triggered automatically for container images published to your Nexus container registries.

Trigger binary scans with Sonatype Nexus integration

Once the Nexus integration is created, a binary scan is triggered automatically when a container image artifact is registered with CloudBees Unify and its URL points to your configured Nexus registry.

Currently, binary scanning for Sonatype Nexus only supports container registry artifacts.

Binary scans triggered through the Sonatype Nexus integration are supported for the following workflows:

CloudBees CI
Jenkins
CloudBees Unify

Configure scan triggers using Jenkins

Configure automated binary scans by adding the registerBuildArtifactMetadata and registerDeployedArtifactMetadata steps in your Jenkins file. These steps register artifact metadata in CloudBees Unify and automatically trigger a binary scan to identify security vulnerabilities in the container image.

Each step does the following:

Creates an artifact record in CloudBees Unify, including the artifact version and build information.
Triggers an automated binary scan to check the container image for security vulnerabilities.

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

Configure automated binary scans in your CloudBees Unify workflow by using the cloudbees-io or register-build-artifact action. Specify the artifact URL for the artifact stored in your Sonatype Nexus repository to register the artifact and trigger the scan.

Example

artifact-url: https://nexus.example.com/repository/my-repo/my-artifact:1.0.0▼

The following example workflow demonstrates registering a container image from Sonatype Nexus:

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

on:
    workflow_dispatch:

jobs:
  build:
    steps:
    - name: Checkout
      uses: cloudbees-io/checkout@v2
      id: checkout
    - name: Register an artifact with {PRODUCT}
      uses: cloudbees-io/register-build-artifact@v2
      id: register
      with:
        name: myApp
        url: <nexus-hostname>:<port>/repository/<repo-name>/<image>:<tag>
        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 the artifact registration executes successfully, CloudBees Unify:

Registers the build artifact metadata.
Initiates a binary scan of the container image in Sonatype Nexus.
Reports scan results in the component-level Security Overview and Security Center dashboards.

After the container image is deployed to an application environment, results are also available in the application-level dashboards.

Review scan results

After the binary scan completes, security findings appear in the component security center, attributed to the component branch associated with the published image.

Binary findings relate to the most recently produced binary for each asset profile. Each produced image becomes a separate asset profile with its own findings set.

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

Sonatype Nexus integration

Configure Sonatype Nexus integration

Trigger binary scans with Sonatype Nexus integration

Configure scan triggers using Jenkins

Configure scan triggers using CloudBees Unify workflows

Review scan results

Related pages