Creating a Release Bundle

JFrog Distribution enables creating and distributing release bundles from any Artifactory service to which it is connected through JFrog Mission Control. Each release bundle may only contain artifacts from a single Artifactory service.

To create a release bundle, Distribution runs queries against Artifactory in order to retrieve the required artifact references and properties. Only those artifacts to which the triggering user has access can be collected into the release bundle.

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.

Release bundles can be created using the REST API or through the JFrog Distribution UI. In either case, you define the artefacts to be included in the release bundle through a set of queries you can define.

Creating a release bundle requires Release Bundle write permissions. 

Using the REST API

You can create release bundles using the Create Release Bundle Version REST API call. 

Using the UI

To create a new release bundle:

1. Click Add a Release Bundle from the Release Bundles page.
   
2. Click Create. This will create a draft release bundle that can be edited, signed, 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.
   Note: A signed Release Bundle cannot be edited.
   

The Release Bundle page is divided into three panels: General Details, Spec and Release Notes.

General Details:

Spec:

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. 

Release Notes:

This section specifies release notes for the release bundle. 

Adding a Query

There are two ways to build a query: Using AQL and using a simple query builder.  

To select the way you want to build your query, hover over Create Query.

Using AQL

To add an AQL query, under Create Query, select Add AQL Query.

This will launch a 3-step wizard.

In the Query Details step, give your query a name and provide the AQL expression to use for assembling the artifacts.

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.

To use the query builder, under Create Query, select Add Query

This will launch a 3-step wizard.

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

Note that 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.

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.

Note that 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.

Additional Details

The Additional Details tab lets you specify two more parameters for your release bundle:

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:

Including Docker Images in a Release Bundle

 docker-local
           postgres
                   11.1
                       manifest.json
                       sha256__060245e5c0563270b03cc4af67a284bdce3f58983be3e71eb9d60190861ebcb7
                       sha256__1e967d04951bfd1b483ae316c40058fed4b154a2e84efb54dfc91204e73f6667
                       sha256__2ad14c51497d15dcaf0e6fd47457de1aee3eab7a1170bda4610dc9cd89c34c8a
                       …

items.find({
	"$and": [
		{
			"$or": [
				{
					"repo": {
						"$eq": "docker-local"
					}
				}
			]
		},
		{
			"$or": [
				{
					"@docker.manifest.digest": "sha256:acb7f2b2e9bd560a32c0ba01991870f56f89deeff5f3224bc50aac2a98b7f73e"
				}
			]
		}
	]
})

Viewing Release Bundles

The Release Bundle module allows you to view all release bundles managed by JFrog Distribution in one place.

To view a single release bundle, click on it from the Release Bundle module.

The Release Bundle 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 

Editing a Release Bundle

1. To edit a release bundle, select Edit Version from the Actions list. The state is set to Open.
   
2. Click Save to save the "draft" version of the release bundle. Continue to Save every time you make a change in Edit mode.
   
   Click Save & Sign to sign and finalize the process.
   Note: A signed Release Bundle cannot be edited.

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.

In addition, Distribution will trigger the source Artifactory to clone the contents of the signed release bundle into an isolated release-bundles repository.

1. You can sign a release bundle from the Edit Release Bundle page or from the New Release Bundle page.

2. Click Sign. 
   

   If the release bundle includes any artifacts that have been blocked for download by JFrog Xray, your attempt to sign the release bundle will fail, and Distribution will display an error message. Consequently, you will not be able to distribute this release bundle.

3. Continue to distributing your release bundle when ready.

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.

Properties

When creating a release bundle, the artifact properties are fetched from Artifactory 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.

Distributing a Release Bundle

Once you have created your release bundle, you can distribute it to the Artifactory Edge Nodes that you are privileged to distribute to.

Distribution is responsible for triggering the replication process that happens from the source Artifactory to the Edge Nodes. 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 on it from the Release Bundle module, select on the version you want to distribute, and click "Distribute".

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 from the Actions drop down menu.

There are 2 types of delete options:

1. Remove from JFrog Distribution. This will also remove the release bundle from the release-bundles repository in the source Artifactory.
2. Delete from selected Artifactory Edge destinations.

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 in Artifactory 6.0. For details, please refer to Entities and Fields.