Release definition

The release process is defined in the release definition, which consists of

The underlying pipeline.
The release timeframe, including planned start and end dates and times for releases.
Notes entered team members, task assignees, and approvers.
The applications to deploy (the payload).
The environments to which the applications are deployed.
Any runtime configuration the application requires, such as input parameters.
Any sub releases attached to the release.

CloudBees CD/RO includes the ability to use Argo Rollouts to provide advanced deployment capabilities to Kubernetes, such as:

Blue-green
Canary
Canary analysis
Experimentation
Progressive delivery features

For more information, refer to Deploy with Argo Rollouts.

This section has examples of release definitions and shows how to define a release.

Example: Release definition

Here is a typical release definition.

Figure 1. Sample release definition

1	It is called `October release`.
2	Use the Release Pipeline control to set up and control pipeline details, parameters, properties, access control, and view change history.
3	Select Timeframe to view and edit the release’s start and end dates and times.
4	Use the Notes control to view add attach notes. One note is attached to this release. Notes can contain plain text and URLs.
5	Use the Apps control to control release applications.
6	Envs & Configs defines environments into which the application is deployed and configures inputs to the application to be entered at runtime.
7	Use the Sub release control to attach new sub releases or delete existing attachments.

Example: Attaching a pipeline run to a traditional release train

This example shows how to attach a pipeline run to a parent release. This is useful in environments with a release train model: one or more subordinate pipeline runs would like to independently join a parent release. Attach a pipeline run to a release via the release portfolio list.

To attach a pipeline run to a parent release:

From the CloudBees CD/RO main menu, select Release Orchestration Releases.

You cannot attach pipeline runs to completed releases.
Select the Views icon for the release, then select Release portfolio list. The release’s portfolio list displays.

Figure 2. Select the Release portfolio list
Select the Attach Pipeline icon near the upper right corner. The Attach Pipeline Run dialog displays with a list of pipeline runs eligible to be attached. Note that only top-level pipeline runs and triggered pipeline runs are eligible for attaching. Release runs are not eligible and won’t appear in the list.

Figure 3. Select attach pipeline
Use the project and run status filters to narrow down the list of pipeline runs, select the one you wish to attach, and select OK. In the example below, pipelineA_3_20221021213123 is selected.

Figure 4. Select the pipeline run
The Release Portfolio List displays again, this time showing the newly attached pipeline.

Figure 5. Release portfolio list
Select Portfolio views, then select Portfolio basic to open the basic portfolio view. Select 1 Attached Run to view information about it.

Figure 6. View information about the release portfolio

Detaching pipeline runs

Navigate to the release portfolio list view for the release. Select Portfolio views, then select Portfolio list to open basic portfolio list view. Select the three dots menu, then select Detach from the pipeline run actions menu.

You cannot detach pipeline runs after a release is complete.

Figure 7. Detach a pipeline run

Example: Traditional multiple application release

This example shows how to define a multiple application release. You can create a new release or copy an existing release.

A copy of a release is the same as the existing release with the following exceptions:

The status in the copy is set to Release in planning.
For start and end dates in the past, the start date and end date in the copy are set to the current date and two weeks later, respectively.
The actual start date and actual end date fields in the copy are cleared. This is because the release is in planning and has not started, and hence there is no end date.

The example in this section shows how to create a new release.

To create a new release:

From the CloudBees CD/RO main menu, select Release Orchestration Releases. The Release dashboard opens.
Select New+. The New Release dialog displays.
Select Create new.
Enter a release Name.
From the Select project list, select the project.
(Optional) Enter a Description.

You can include hyperlinks as part of an object description for any CloudBees CD/RO object.

(Optional) Select start and end dates and times.

CloudBees added start and end times with v.2023.02.0. This information is not backward compatible in DSL. You cannot import generated DSL of release objects from v2023.02.0 to earlier versions without manual changes.

(Optional) Add Tags.
Select Next.
Select Quarterly Online Banking Release Pipeline. Next is enabled because the applications in this pipeline have required inputs, as indicated by . This means that there are two required inputs to deploy the applications through this pipeline. If any input is a credential parameter, you can enter the path to the credential, browse to it, select the Parameter Credential or Credential binding, or select a user-defined credential that is attached to the project associated with the pipeline.
Enter the required inputs, and select OK.

If the applications did not have any required inputs, OK is enabled instead.
The new release definition displays. Note that the hierarchy menu on the left side shows the pipeline that you selected. If the applications in the selected pipeline have inputs, a dialog showing the inputs to the pipeline displays.
- If any input is a credential parameter, you can enter the path to the credential, browse to it, select the Parameter Credential or Credential binding, or select a user-defined credential that is attached to the project associated with the pipeline.
- If any of required parameters do not have values, enter the appropriate values, and select OK.
  
  The Application field is now enabled in the Release Definition page.
Select Applications. The dialog where you specify the applications to be deployed through the pipeline opens.

Select the applications that you want to deploy in the release, and then select Arrow icon button to move them to the right side of the dialog, which is the list of applications to be deployed through the pipeline.

Selecting Arrow icon button moves the selected applications to the right side and displays the number of required parameters at run time and the application process to be deployed.

It shows the list of available applications. The default is to show the applications for all projects.

If you want to see only the applications for a specific project, select the down arrow in the All projects field to select one or more projects one of these ways:

Select the name of one or more projects.
Enter the search criteria in the Search field. The projects that match the criteria appear in the list.

You can also search for one or more applications by entering the search criteria in the Search field next to the All projects field. If there are no matches, a message appears stating that there are no applications in the selected projects.

Select < to set how you want the applications to be deployed during the release run.

For each application, you can select these settings:

Stop on Error: Select this error handling setting to abort the release run when the deployer task fails. The default is Stop on Error. If the application fails, the release pipeline aborts.

When this setting is not selected (continue on error, which is similar to the Continue running option in a pipeline stage or gate), the deployer continues to the next application with a known error if the current application fails. This allows the release to continue running when an application run has errors and fails. For example, in a release with multiple applications, some applications can fail and not be deployed with other that were successfully deployed as delivered in the release.
Smart Deploy: Select this setting if you want the release to deploy the application only with artifacts that have not been deployed to a resource or with selected versions of the artifact have not been deployed to new resources since a previous run.

Stage Artifacts: Select this setting if you want the release to retrieve artifacts that will be deployed in an application run before the deployment starts.

In this example, all the settings are selected for the selected applications. The release stops if any of the applications fail.

Figure 8. Stop application

The default is that CloudBees CD/RO uses smart deploy to deploy the applications in the pipeline. If you want to use smart deploy for all the applications, you do not need to change the settings.

If the applications have snapshots, select the down arrow next to , select a specific snapshot for each application, and then select OK.

Using a snapshot as part of the release definition is a best practice. Using snapshots, you can lock the exact versions of the artifacts to be deployed, which provides consistency and predictability. But you do not have to select a specific snapshot for an application.

If a snapshot is not selected for an application here, the exact artifact versions to use would be based on how that application is modeled. That is, if the application model uses the latest artifact version for a component, the latest version would be used every time the release runs when a snapshot is not selected.

When the release runs, this list of applications (the payload) is passed to the deployer task in the pipeline, and the applications are deployed through the pipeline sequentially. You can change the order in which the applications will be deployed by reordering the application input in the payload.
Click Environments to select the where the applications in each stage will be deployed. The Environment selection dialog opens.

Each cell in the table represents an environment where an application in a stage is deployed.

Figure 9. Environments where an application in a stage is deployed

When you mouse over the filter icons, the tool tip text displays, from left to right:
- View only cells with missing environments.
- View only cells with missing tier maps.
- View only cells marked "N/A".
- View only empty cells.
Select one or more cells in the table one of these ways:
- For one cell (one application-stage combination): You can select one cell by clicking in it. This allows you to select the environment for a specific application-stage combination.
- For multiple cells (all the applications in a stage): If the environment in a stage is the same for all the applications, you can select all the cells in a column (stage) by clicking in the header cell with the stage name.
  
  After one or more cells is selected, the Fill button in the upper right corner is enabled.
Select the > button in the upper left corner of the dialog. The Fill Environment Names section opens on the left side of the dialog.

Select an environment using one of these options:

Select Environment: Select the down arrow to select an environment or environment template.
- Clicking Select Environment opens the list of available environments in the Environments tab. These are static environments that are authored before deploying the application in the stage.
- Selecting Templates opens a list of environment templates. These are dynamic environments with provisioned cloud resources that can be spun up during the application deployment. For more information about dynamic environments, refer to Model dynamic environments.
Name Pattern: Select ? for tips on how to specify environment names. The tips describe how to specify environment names using static text or a fill pattern.

N/A: Select this to not run the application in the stage. You should set environment mapping to N/A for stages where you do not want an active deployment even though the deployer is attached to a stage.

In this example, the hc-store dev environment is selected from the Environments list.

Figure 10. Environment list selection

It shows the list of available environments. The default is to show the environments for all projects.

If you want to see only the environments for a specific project, select the down arrow in the All projects field to select one or more projects one of these ways:

Select the name of one or more projects.
Enter the search criteria in the Search field. The projects that match the criteria appear in the list.

You can also search for one or more environments by entering the search criteria in the Search field next to the All projects field. If there are no matches, a message appears stating that there are no environments in the selected projects.

Select OK to close the Fill Environment Names section.
Select OK to save the settings.
Select Configurations to enter the inputs (parameters) for the applications in a stage.

If you have not entered any of the required parameters on one of the cells for an application in a stage, this displays: . You can enter the value for it now or at runtime.
Select OK.

The next step is to run the release. Refer to Run and end releases to learn more about running and completing the release.

Example: Continuous delivery style releases for one application

This example shows that when you define a release, you do not have to enter all the details. However, any configuration issues have to be resolved before the release run. After a release is added, the release definition opens.

Click in the Pipeline field. A dialog opens, where you can select a pipeline:

Figure 11. Select pipeline

When you select the button (number 1 above), a description of the deployPipeline displays. The icon on the right (number 2 above) means that two required parameters are attached to the pipeline.

It shows the list of available pipelines. The default is to show the pipelines for all projects.

To view only the pipelines for a specific project, select the down arrow in the All projects field to select one or more projects in one of these ways:

Select the name of one or more projects.
Enter the search criteria in the Search field. The projects that match the criteria appear in the list.

You can also search for one or more pipelines by entering the search criteria in the Search field next to the All projects field. If there are no matches, a message appears stating that there are no pipelines in the selected projects.

Select the deployPipeline application, and select Next.

Figure 12. Deploy pipeline application
- If the pipeline does not have a deployer task, a message displays reminding you that you need to define a deployer task to run the release. Close the message to continue, and select Next.
- If the pipeline has a deployer task, the message does not appear, and you only need to select Next.
  
  In the example, the pipeline has four required parameters. Some of them have default values that you can keep or change. Others do not, and you have to enter a value for them.
After you enter the values, select OK.

Click in the Applications field. The dialog to select one or more applications opens.

It shows the list of available applications. The default is to show the applications for all projects.

If you want to see only the applications for a specific project, select the down arrow in the All projects field to select one or more projects one of these ways:

Select the name of one or more projects.
Enter the search criteria in the Search field. The projects that match the criteria appear in the list.

Select one or more applications, select the button to add them to the pipeline, select OK, and then select <:

Figure 13. Add applications to the pipeline

Click in the Environments field. The dialog to select an environment where the applications in each stage will be deployed opens.

It shows the list of available environments. The default is to show the environments for all projects.

If you want to see only the environments for a specific project, select the down arrow in the All projects field to select one or more projects one of these ways:

Select the name of one or more projects.
Enter the search criteria in the Search field. The projects that match the criteria appear in the list.

When you mouse over the filter icons, the tool tip text displays, from left to right:

Figure 14. Environment selection

View only cells with missing environments.
View only cells with missing tier maps.
View only cells marked "N/A".
View only empty cells.

For detailed instructions about how to select the environments in which the applications in each stage will be deployed, go here.

In this example, the environments are selected as follows:

ShoppingCart application in the QA stage:

In the ShoppingCart row, select the cell in the QA column and double-click in it. Notice that the Fill button is now enabled.

A panel opens to the left where you can select the environment where the ShoppingCart application will be deployed.

Select the environment to which the ShoppingCart application is deployed: QA.

Select OK to save your selection.

Figure 15. Save selection
jpetstore2 application in the QA stage:

In the jpetstore2 row, select the cell in the QA column, and click in it. Notice that the Fill button is now enabled.

A panel opens to the left where you can select the environment where the jpetstore2 application will be deployed.

Select the environment to which the jpetstore2 application is deployed: jpetstore-qe.

Figure 16. Select environment

Select OK.
All the applications in the PROD stage. Click in the header cell for the PROD stage.

A panel opens to the left where you can select the environment where the applications will be deployed.

Select the environment to which the applications will be deployed: PROD.

Select OK.

Now click in the Configurations field. The dialog to enter the required parameters for the pipeline to run opens:

Figure 17. Required parameters

If any of the required parameters have not been entered in a cell (an application to be deployed in a stage) with Red X in it, you can click in the cell to enter the inputs (parameters) for the application in a specific stage. You can enter the value for it now or at runtime. Then select OK to save your entries.

The release definition now looks like this:

Figure 18. Release definition

The next step is to run the release. Refer to Run and end releases to learn more about running and completing the release.

Attaching and removing sub releases

You can attach sub releases and remove existing attachments in the Release editor.

To attach a new sub release:

Select Sub release.
Select Attach new. The Create sub release dialog opens.
Choose Select existing, Create new, or Copy existing.
1. To select an existing sub release, search for the sub release or select the Project and Release from the lists, and then select OK.
  
  Figure 19. Attach a new sub-release
2. To create a new sub release:
  - Enter the Release name.
  - Select the Project.
  - (Optional) Enter a Description.
  - (Optional) Select the Start date and time and End date and time.
  - Add Tags using the list.
  - Select a pipeline.
  - Select Create.
    
    Figure 20. Select an existing sub-release

To remove an existing attachment:

Select Sub release.
Select Existing attachments.
Select the trash can icon. A confirmation displays.
Select OK.