JFrog Help Center

Our new portal is coming soon!
Documentation + Knowledge Base

JFrog Help Center - A new knowledge experience is coming your way soon!


Release Bundles group together the contents that are part of your release, providing the bill of materials for your software releases. For example, you can group together the different build artifacts, such as Docker images, that make up your software release that can then be pushed to your point of sale devices.

A Release Bundle plays a central role in the distribution flow. It specifies the different files and packages that comprise a release, along with their metadata, and is created and managed in JFrog Distribution. Release Bundles are generally distributed from a source Artifactory instance to an Artifactory Edge node. Since all the files specified in a release bundle are required to keep the release coherent, a release bundle is immutable. Effectively, this means that once a file has been included in a release bundle, it cannot be deleted from the Edge node where it is hosted.

The JFrog Platform provides the Release Bundle experience in the Application module, under Distribution | Release Bundles for the Source and Edge Artifactory instances as follows:

  • Source Artifactory: Includes two dedicated tabs:
    • Distributable: Users with the appropriate permissions can create, distribute and track release bundles.
    • Received: Contains the release bundles received by an Artifactory Edge
  • Artifactory Edge: Displays a single tab displaying containing Release Bundles received by the Artifactory Edge.

Comprehensive Tracking of Your Release Bundle versions

All the information regarding your release bundle version is consolidated and displayed in one central area. This view is intuitive and provides quick access to all the aspects regarding your release bundle including Distribution Tracking, Xray data and Effective Permissions.

Secure and Protected Release Bundles

Xray scanning requires Artifactory Pro X, Enterprise with Xray, or an Enterprise+ license.

JFrog Xray supports indexing and scanning of Release Bundles as well as defining Watches and Policies on Release Bundles. You can apply a policy on a Watch containing a Block Release Bundle Distribution action to prevent distributing a Release Bundle to edge nodes if it meets a security or License policy defined in JFrog Xray. For more information, see Xray Scanning of Release Bundles.

JFrog Subscription Levels


Page Contents

Creating Release Bundles

JFrog Distribution enables creating and distributing Release Bundles from the Artifactory service. Each Release Bundle may only contain artifacts from a single Artifactory service.

To create a release bundle, Distribution runs queries against the JPD in order to retrieve the required artifact references and their properties. Fetching the artifacts is performed according to the security privileges of the user who made the request.

To prevent tampering with the Release Bundle, it is signed by JFrog Distribution using a GPG key. The same GPG key is then used by the Artifactory Edge to validate the Release Bundle before it is accepted.

A Release Bundle version can include up to 3,000 artifacts. This number is not limited in the product, but exceeding it is highly unrecommended. 

Release Bundles can be created using the REST API or through the JFrog UI. In either case, you define the artifacts to be included in the Release Bundle through a set of queries you can define.

In the final stages of creating a Release Bundle in the JFrog UI, you can option to save the Release Bundle in the following modes:

  • Draft version: You can create a draft version that can be edited by clicking Create.
  • Signed version (Unmodifiable): You can skip the draft phase by clicking Create & Sign to sign and finalize the process without a draft phase.


Creating a Release Bundle requires the Release Bundle 'Write' permissions

From Distribution version 2.14.1, the following UI changes have been made to this window:

  • A filter search has been added to enable you to search for a specific release bundle by name or by latest version.
  • The total count for both Distributable  and Received Release Bundles is also displayed in the UI

Creating a New Release Bundle

  1. From the Application module | Distribution | Distributable, click New Release Bundle.

    This displays the New Release Bundle window.
  2. Enter the Release Bundle details according to the sections below, and then click Create Query (see Adding a Query for details).

The Release Bundle page is divided into three panels: General DetailsSpec and Release Notes.

General Details


The Release Bundle name. The Release Bundle name must start with an alphanumeric character followed by an alphanumeric or one of the following characters: - _ : .

The Release Bundle version.
The Release Bundle description.

This section specifies the Artifactory service from which the Release Bundle will be assembled (remember, a Release Bundle can only be assembled from a single Artifactory service), and the different queries that will be used to assemble the artifacts. For more details on how to define the queries, please refer to Adding a Query

The query name.
The query details.
Release Notes

This section specifies release notes for the Release Bundle. 

The release notes format. Supported types include: Markdown, Asciidoc and plain text.
Edit | Preview
Use these links to edit the release notes in your selected format and then preview how they will look once rendered.

Adding a Query 

There are two ways to build a query: Using a simple query builder or using AQL (Artifactory Query Language) for advanced users.

To select the way you want to build your query, hover over Create Query and select either Add Query or Add AQL Query.

Using the Query Builder

The query builder lets you build your query by filling a simple form. The parameters you enter are eventually translated into an AQL query which you can view by setting the Show AQL checkbox at the end of the form.

  1. To use the query builder, under Create Query, select Add Query
    This will launch a 3-step wizard.
  2. In the Query Details step, start by giving your query a name. You can then specify different search criteria including:
    • Repository names
    • Build names and numbers
    • Properties with specific values
    • Include and Exclude patterns
You can specify multiple values for each of these parameters by clicking the '+' button to the right of the parameter. 
Using the And | Or options, you can add multiple properties in a single click of a button.

Using AQL

  1. To add an AQL query, under Create Query, select Add AQL Query.
    This will launch a 3-step wizard.
  2. In the Query Details step, name your query and provide the AQL expression that will be used for assembling the artifacts, for example:

Preview Artifacts

After specifying your query details (whether using an AQL query or the query builder), you can view the artifacts that will be included in your Release Bundle under the Preview Artifacts tab.

If the source or target Artifactory service specified for the Release Bundle does not have a correct and valid license, Distribution will display an error that it cannot create the Release Bundle.

Additional Details

The Additional Details tab lets you specify two more parameters for your Release Bundle:

Additional Properties
Specify a list of properties that will be attached to all artifacts in your Release Bundle during the distribution process, in addition to those that they already have.
Path Mappings
Specify a list of mappings to govern where artifacts will be placed in your target Artifactory service according to their location in your source Artifactory service. You may use any of the Path Mapping Templates provided, or set up custom mappings of your own.

Path Mapping Templates

As a convenience, JFrog Distribution provides a set of commonly used templates you can use to set up your path mappings. Simply select one of the templates listed under Use Template, and then modify the placeholders to correspond with your setup.

The templates provided are:

Change Repository
All files in a specific repository on the source Artifactory service are mapped to a different repository on the target.
Change Folder
All files are moved to a specific folder in the target.
Rename Folder
All files in a specific folder on the source Artifactory service are mapped to a different folder on the target.

Click Save and then click Create. This will create a draft Release Bundle that can be editedsigned, and then finally distributed.

Alternatively, you can skip the draft phase by clicking Create & Sign to sign and finalize the process without a draft phase (continue to Signing a Release Bundle).

Including Docker Images in a Release Bundle

In order to include Docker image in the Release Bundle, it is sufficient to specify query criteria that will match the manifest.json of the desired docker image. Distribution will include all the Docker layers of the Docker image associated with that manifest.json file.

For example, we have a Docker image of a PostgreSql version 11.1 in a Docker repository called docker-local.
The content of the repository has the following hierarchy:


The manifest.json file includes the following property: 

docker.manifest.digest sha256:acb7f2b2e9bd560a32c0ba01991870f56f89deeff5f3224bc50aac2a98b7f73e

All the other files under docker-local/postgres/11.1 are the layers composing this specific image.

Docker digest

The “digest” parameter is designed as an opaque parameter to support verification of a successful transfer. For example, an HTTP URI parameter might be as follows:


Given this parameter, the registry will verify that the provided content does match this digest.

To include all the artifacts in the image (manifest and layers) it is sufficient to specify a query criteria that will match the manifest.json of the desired Docker image:

AQL example
	"$and": [
			"$or": [
					"repo": {
						"$eq": "docker-local"
			"$or": [
					"@docker.manifest.digest": "sha256:acb7f2b2e9bd560a32c0ba01991870f56f89deeff5f3224bc50aac2a98b7f73e"

Signing a Release Bundle

Signing a Release Bundle finalizes the process of creating a Release Bundle. This sets the Release Bundle status to Signed and the Release Bundle can no longer be edited.

Signing a Release Bundle will trigger the Artifactory to clone the contents of the signed Release Bundle into an isolated Release Bundle Repository.

  1. You can sign a Release Bundle from the Edit Release Bundle page or from the New Release Bundle page.
  2. Click Sign Version. 

    From Distribution release 2.14.1, the signing process has been updated as follows: If you are using multiple GPG signing keys in Distribution, you can now select which signing key to use in the Platform UI (this was previously available only from the REST API). Note that if no key is selected, the default/primary key will be used to sign the Release Bundle.

  3. In the Sign Version window, you will see the name of the Release Bundle and its version. From the Select Signing Key dropdown, select the signing key.

  4. If the signing key was created with a passphrase, JFrog Distribution will prompt you to enter the passphrase.

    Once you sign a version, you will not be able to edit it.

  5. Click Sign to sign your version.
  6. Next, continue to distributing your Release Bundle when ready.

Creating a Dynamic Release Bundle

You can distribute a dynamic Release Bundle, which is a Release Bundle you can create, sign, and distribute on the fly using the Dynamic Release Bundle REST API. The Release Bundle version is created instantly and distributed to the selected Distribution Nodes. The distribution process for a Dynamic Release Bundle is the same as a regular Release Bundle.

Distributing a Release Bundle

Once you have created your Release Bundle, you can distribute it to the Distribution Edges that you are privileged to distribute to.

Circle of Trust

Distribution can only distribute Release Bundles from an Artifactory service to a Distribution Edge if they are both within the same "circle of trust". To learn how to establish a circle of trust, see Access Tokens.

The workflow for distributing Release Bundles contains the following steps:

  1. On the Artifactory source node, users with the appropriate permissions can create and manage the Release Bundle distribution process in the Release Bundles Distributable tab.
  2. Artifacts that have been created and signed are automatically copied and saved into this separate repository where their contents cannot be edited or removed. The Release Bundle Repository protects your artifacts as part of the distribution flow.
  3. On the Distribution Edge, users can track Release Bundles received by a Distribution Edge

Distribution is responsible for triggering the replication process that happens from the source Artifactory to the Distribution Edges. First, it replicates the Release Bundle info to each Edge Node, and then initiates the replication process in the source Artifactory.

To distribute your Release Bundle, click Distribute from the Release Bundle module, or use the Distribute Release Bundle REST API. 

Distribution fetches the available Edge Nodes from Mission Control, and displays a list of the available Edge Nodes according to the specific user permissions.

To distribute an older version of your Release Bundle, click it from the Release Bundle module, select the version you want to distribute, and click Distribute.

Automatically Create Missing Repositories

With the introduction of the Private Distribution Network (PDN), instead of using the Target Repository Auto-Creation checkbox, Distribution enables you to automatically create missing repositories while setting up your PDN distribution using the Auto create missing repositories checkbox.

Versions Requirements

This feature requires JFrog Artifactory version 7.38.8 or higher and Distribution 2.12.3 or higher.

This feature works according to the path mapping that exists from the source to the target. If advanced path mapping was detected, the target repository cannot be auto-created.

To enable this feature, set the distribute.auto-create-target-repo-advance flag to true in the Distribution Application Config YAML File

RepositoriesWithout Path MappingWith Advanced Path Mapping
One RepositoryIf the target repository name and type are the same as the source repository, the repository is created automatically.If there is a one-to-one path mapping between the source repository and target repository, the target repository type is the same as the source repository type.
Multiple RepositoriesIf the target repositories names and types are the same as the source repositories, the repositories are created automatically.
  • If all repositories are the same repository type in the source and are mapped to one target repository, the target repository created will be the same type as the source with the name specified by the user.
  • If all repositories in the source are different repository types and are mapped to one target repository, the target repository created will be a generic repository.


Example 1: From source to target repository without path mapping

A Docker image from a Docker repository in the source, the Docker image will be mapped to the Docker repository in the target. 

Example 2From source to target repository with path mapping

A Docker image from a Docker repository named docker-local in the source will be mapped to Docker repository named mapped-docker-local in the target.

Example 3Multiple repositories on the source to one target repository with path mapping

Multiple Docker images from multiple Docker repositories in the source, the Docker images are mapped to a single Docker repository in the target.

Example 4Multiple repository types on the source to one target repository with path mapping

A Docker image from Docker repository and Helm chart from Help repository in the source will be mapped to one generic repository.

From JFrog Distribution version 2.14.1, the checkbox Auto create missing repositories is displayed for all Release Bundle distributions (not only PDN), replacing the Target Repository Auto-Creation checkbox (the functionality remains the same).

Target Repository Auto-Creation

The Target Repository Auto-Creation checkbox has been deprecated with the release of Distribution version 2.14.1, and has been replaced by the Auto create missing repositories checkbox detailed above.

Versions Requirements

This feature requires JFrog Artifactory version 7.21.0 or higher

From JFrog Distribution version 2.8.1, this feature enables you to automatically create missing target repositories on the target edges or Artifactory when distributing Release Bundles. When the target edge or Artifactory does not contain any repositories, the distribution fails, and the creation is required to be done manually. If this feature is enabled, the target repositories are automatically created expediting the Distribution flow.

To enable this feature, select the Target Repository Auto-Creation checkbox:

Distributing Versions to Targets

From Distribution version 2.14.1, you can distribute Release Bundle versions to targets as follows.

  1. The targets are displayed as a tree (this replaces the UI that required you to select and drag targets to the right pane):
    1. To distribute to a specific target, select it in the tree
    2. To distribute to all targets, select the Select All checkbox. 
  2. When you select targets, your selections will appear at the bottom of the window, so that you can see which targets the version will be distributed to.
  3. You can also search for specific targets in the search field.
  4. To ensure that you are not distributing to missing repositories, which can cause your distribution to fail, you may want to select the Auto create missing repositories checkbox  (the functionality remains the same as the Target Repository Auto-Creation checkbox).
  5. When done, click Distribute to distribute the version.

Managing Release Bundles

You can perform the following tasks on Release Bundles.

Viewing Release Bundles

The UI provides Release Bundle information is displayed across multiple views providing users information depending on their needs and tasks.

Viewing Release Bundles on the Source Node

The Release Bundle name.
Latest Version
The Release Bundle latest version.
Distribution ID
The sequential number of the distribution job. Only the last 3 distribution jobs are displayed.
The time the distribution began
The distribution job status.
The distribution progress percentage.

Viewing Release Bundle Version Details

To view a version of a Release Bundle, select a Release Bundle and select the required version.

The Release Bundle versions page displays three panels of information:

Versions: The list of versions of this Release Bundle. Select any version to view its details.
General Info: The panel along the top of the screen displays general information such as the version, description, creation date, status and size of the Release Bundle 

Details: This panel displays details about the selected Release Bundle version in a series of tabs: Actions Tracking, ContentRelease Notes, Xray Data, Pipelines, Spec and Effective Permissions.

Viewing Release Bundle Properties

When creating a Release Bundle, the artifact properties are fetched from the Properties in Deployment and Resolution into the Release Bundle. Additional custom properties can be added during the initial Release Bundle version creation using the Create Release Bundle REST API. These properties are transferred over to the Edge Node as part of the distribution process.

The Distribution page contains these information tabs:

Content Tab

The Content tab displays the artifacts, builds and metadata that comprise the Release Bundle.

Click on any artifact or build to view details about it in the right panel in the tab. 

Click for direct access

Click an artifact's source path to be redirected to the right location in the tree browser of the corresponding Artifactory service.

If the artifact has been blocked for download by JFrog Xray (in which case, you will not be able to distribute the Release Bundle), this will be indicated in the Xray Status field for the selected artifact in the Content tab.

Release Notes Tab

The Release Notes tab displays release notes for the bundle. These can be written in markdown, ascii doc or plain text.

Actions Tracking Tab

The Actions Tracking tab provides a history for this Release Bundle version.


The ID of the distribution action.

Multiple rows with the same ID

You may see multiple rows in this table with the same ID because a single distribution action may distribute a Release Bundle to several target nodes.

The action that was performed
The date and time at which the action started

The distribution target

Click for direct access

Click on the distribution target name to be redirected directly to its UI.


The status of the action

The percent completion of the action and number of attempts at completion

Summary of some details about the action.

Click for details

Click on this field to get full details of the action. This is where you can get more details in case of an error.

Redistributing a Release Bundle

Distributing a Release Bundle may fail for different reasons such as network issues or outage of a target Artifactory service. Once you have remediated the problem preventing distribution, you can redistribute the Release Bundles to the services where distribution failed. To redistribute release bundles, first select them. Distribution presents a Redistribute icon for each distribution selected. You can now click that icon to redistribute each Release Bundle individually to the specified target service, or select the Redistribute button at the top of the list to redistribute the Release Bundle to all target services selected in a batch process.


Use the Filter to display only those distributions that have failed.

Pipelines Tab

The Pipelines tab is a verification system that determines which pipelines/steps generated a specific artifact. It provides users with a way to ensure that their artifacts have not been tampered with before these artifacts are promoted through the CI/CD workflow.

For more information, see Signed Pipelines.

Spec Tab

The Spec tab displays the source Artifactory service from which the artifacts of this Release Bundle were assembled as well as the list of queries that assembled the artifacts.

Click the Artifactory service

 Clicking the Artifactory service opens a new tab on the home screen of that service

Clicking on any of the queries expands it displaying the details of the query that governed the assembly of the Release Bundle artifacts.

You can even check the AQL checkbox to see the final AQL query that was used to assemble the artifacts.

Effective Permissions Tab

The Effective Permissions tab displays the effective permissions assigned for the selected Release Bundle. For more information, see Permissions.

Editing a Release Bundle

You can edit Release Bundles that have been saved with 'Create' as a draft and have not yet been signed.

From the Application module under Distribution, go to Distributable | [Bundle_Name] | [Bundle_Version], click Actions and select Edit Version.

Searching for Release Bundles

The Platform supports searching for Release Bundles using the:

  • Dedicated Platform Release Bundle SearchYou can search for distributable and received Release Bundles within a specified time page. For more information, see the Application Search.

  • AQL Search for Release Bundles: To search for release bundles in an Artifactory Edge node, you can use the release and release_artifact domains introduced to AQL. For details, please refer to Entities and Fields.

Cloning a Release Bundle

To clone an existing release bundle version, select Clone Version from the Actions drop down menu.

This will copy the release bundle spec, including its name and queries, into a new release bundle page. Details on the page can then be adjusted and saved accordingly.

Deleting a Release Bundle

You can delete release bundles using the Distribution UI or the Delete Release Bundle REST API call. Available for users with Release Bundle delete permissions.

To delete an existing release bundle version, select Delete Version from the Actions drop down menu.

There are 2 types of delete options:

From Artifactory release 7.39.1, you can verify that the empty folders of a Release Bundle are deleted as part of its deletion from both target Repositories and Release Bundles Repository. This is done through a parameter in the Artifactory system.yaml file called releasebundle.cleanup.deleteEmptyFolder, which is set to true by default. 

Xray Scanning of Release Bundles 

Xray scanning requires Pro X, Enterprise with Xray, or an Enterprise+ license. 

JFrog Xray supports scanning of Release Bundles as well as setting Policies and Watches on Release Bundles.

Prior to scanning your Release Bundles, you will need to:

  1. Add the Release Bundles to the Xray indexed resources. For more information, see  Configuring Indexing Resources.
  2. Create a Policy containing a Block Release Bundle Distribution action to prevent distributing a Release Bundle to Edge nodes. For more information, see Creating Xray Policies and Rules.
  3. Configure a Watch containing the Release Bundles and apply the relevant Policy. For more information, see Configuring Xray Watches.

The Release Bundle scanning results are displayed in Xray data tab of the Release Bundle. 

Viewing Xray Data

In the Release Bundles version list, you can view the status of your scanned Release Bundle versions in the Xray Status column.

Click the Release Bundle version to view detailed information in the Xray Data tab. This tab displays any violations, security issues, license that may have been detected on the distributed version. You can run the following Xray related actions on the version: Scan for Violations, Assign Custom issues, Assign Custom License or Export Data. For detailed information on each tab, see Analyzing Scan Results.

Blocking Distribution of Signed Release Bundles

You can set the Block Release Bundle Distribution action in an Xray Policy to prevent signed Release Bundles containing security vulnerabilities from being distributed. For more information, see Creating Xray Policies and Rules.

The blocked Release Bundle appears with status failed. 


Distribution in Projects

Because Distribution is not currently included in JFrog Projects, Distribution will work with all projects, so that all workflows assume that they are seeing all projects.

Viewing Received Release Bundles

The Release Bundles Received tab allows you to view all the received release bundles in one place.

From Distribution release 2.15.0, the Received Bundles table in the JFrog Platform has been updated to support easier search and filtering for Release Bundles. These updates include:

  • Search that enables you to find any Release Bundle by name or by using a wildcard together with other Release Bundle details
  • All Release Bundles are pulled using the REST API, ensuring that you can search for any Release Bundle regardless of when it was released
  • Release Bundles can be sorted according to name, latest version or creation date


These are the main Release Bundle REST APIs:

For the full list of Release Bundle commands, see the Distribution REST API.

Watch the Screencast

  • No labels
Copyright © 2023 JFrog Ltd.