Use Deployment Manager to create continuous integration and delivery (CI/CD) pipelines, which automate tasks and allow you to quickly deploy high-quality software to production.

See the following topics for more information about installing and configuring Deployment Manager:

• Step 1: Installing Deployment Manager
• Step 2: Upgrading to Deployment Manager 4.2.x (optional)
• Step 3: Configuring systems in the pipeline
• Step 4: Configuring the development system for branch-based development (optional)
• Step 5: Configuring additional settings

For information about using Deployment Manager, see Using Deployment Manager 4.2.x.

Step 1: Installing Deployment Manager

Each customer virtual private cloud (VPC) on Pega Cloud has a dedicated orchestrator instance to use Deployment Manager. You do not need to install Deployment Manager to use it with your Pega Cloud application. If you are upgrading from an earlier release to Deployment Manager 4.2.x, contact Pegasystems^® Global Customer Support (GCS) support to request a new version.

To install Deployment Manager 4.2.x on premises, complete the following steps:

1. Install Pega 8.1 on all systems in the CI/CD pipeline.
2. Browse to the Deployment Manager Pega Exchange page, and then download the DeploymentManager04.02.0x.zip file for your version of Deployment Manager to your local disk on each system.
3. Extract the DeploymentManager04.02.0x.zip file.
4. Use the Import wizard to import files into the appropriate systems. For more information about the Import wizard, see Import wizard landing page.
5. On the orchestration server, import the following files:
   • PegaDevOpsFoundation_4.zip
   • PegaDeploymentManager_4.2.zip
6. On the development, QA, staging, and production systems, import the PegaDevOpsFoundation_4.zip file.
7. Optional: If you are using a distributed development, on the remote development system, import the PegaDevOpsFoundation_4.zip file.
8. Do one of the following actions:
   1. If you are upgrading to Deployment Manager 4.2.x, perform the upgrade. For more information, see Upgrading to Deployment Manager 4.2.x.
   2. If you are not upgrading Deployment Manager 4.2.x, continue the installation procedure. For more information, see Step 3a: Configuring authentication profiles on the orchestration server and candidate systems.

Step 2: Upgrading to Deployment Manager 4.2.x

Before you upgrade, ensure that no deployments are running, have errors, or are paused.

To upgrade to Deployment Manager 4.2.x either on Pega Cloud or on premises, perform the following steps:

1. On each candidate system, update the PegaDevOpsFoundation application version to the version of Deployment Manager that you are using.
   1. In the Dev Studio header, click the name of your application, and then click Definition.
   2. In the Built on application section for the PegaDevOpsFoundation application, in the Version field, press the Down Arrow key and select the version of Deployment Manager that you are using.
   3. Click Save.
2. If you do not see the pipelines that you created in earlier releases, run the pxMigrateOldPipelinesTo42 activity:
   1. In Dev Studio, search for pxMigrateOldPipelinesTo42, and then click the activity in the dialog box that displays the results.
   2. Click Actions > Run.
   3. In the dialog box that is displayed, click Run.
3. On the orchestration server, run the pxUpdateDescription activity.
   1. In Dev Studio, search for pxUpdateDescription, and then click the activity in the dialog box that displays the results.
   2. Click Actions > Run.
   3. In the dialog box that is displayed, click Run.

4. On the orchestration server, log in to the release management application.
5. Run the pxUpdatePipeline activity.
   1. In Dev Studio, search for pxUpdatePipeline, and then click the activity in the dialog box that displays the results.
   2. Click Actions > Run.
   3. In the dialog box that is displayed, click Run.
6. Modify the current release management application so that it is built on PegaDeploymentManager:04-02-01.
   1. In the Dev Studio header, click the name of your application, and then click Definition.
   2. In the Edit Application rule form, on the Definition tab, in the Built on application section, for the PegaDeploymentManager application, press the Down Arrow key and select 04.02.01.
   3. Click Save.
7. Merge rulesets to the PipelineData ruleset.
   1. Click Configure > System > Refactor > Rulesets.
   2. Click Copy/Merge RuleSet.
   3. Click the Merge Source RuleSet(s) to Target RuleSet radio button.
   4. Click the RuleSet Versions radio button.
   5. In the Available Source Ruleset(s) section, select the first open ruleset version that appears in the list, and then click the Move icon.
   6. All your current pipelines are stored in the first open ruleset. If you modified this ruleset after you created the application, select all the ruleset versions that contain pipeline data.
      1. In the target RuleSet/Information section, in the Name field, press the Down Arrow key and select Pipeline Data.
      2. In the Version field, enter 01-01-01.
      3. For the Delete Source RuleSet(s) upon completion of merge? option, click No.
      4. Click Next.
      5. Click Merge to merge your pipelines to the PipelineData:01-01-01 rulset.
      6. Click Done.
      7. Your pipelines are migrated to the Pega Deployment Manager application. Log out of the orchestration server and log back in to it with the DMReleaseAdmin operator ID and the password that you specified for it.

For backup purposes, pipelines are still visible in your previous release management application. However, you should not create deployments with this application, because deployments might not work correctly.

Step 3: Configuring systems in the pipeline

Complete the following steps to set up a pipeline for all supported CI/CD workflows. If you are using branches, you must configure additional settings after you perform the required steps.

1. Step 3a: Configuring authentication profiles on the orchestration server and candidate systems
2. Step 3b: Configuring the orchestration server
3. Step 3c: Configuring candidate systems
4. Step 3d: Creating repositories on the orchestration server and candidate systems

Step 3a: Configuring authentication profiles on the orchestration server and candidate systems

When you install Deployment Manager on all the systems in your pipeline, default applications, operator IDs, and authentication profiles that communicate between the orchestration server and candidate systems are also installed.

On the orchestration server, the following items are installed:

• The Pega Deployment Manager application.
• The DMReleaseAdmin operator ID, which release managers use to log in to the Pega Deployment Manager application. You must enable this operator ID and specify its password.
• The DMAppAdmin authentication profile. You must update this authentication profile to use the password that you specified for the DMAppAdmin operator ID, which is configured on all the candidate systems.

On all the candidate systems, the following items are installed:

• The PegaDevOpsFoundation application.
• The DMAppAdmin operator ID, which points to the PegaDevOpsFoundation aplication. You must enable this operator ID and specify its password.
• The DMReleaseAdmin authentication profile. You must update this authentication profile to use the password that you specified for the DMReleaseAdmin operator ID, which is configured on the orchestration server.

Configure the default authentication profile by following these steps:

1. On the orchestration server, enable the DMReleaseAdmin operator ID and specify its password.
   1. Log in to the orchestration server with [email protected]/install.
   2. In Dev Studio, click Records > Organization > Operator ID, and then click DMReleaseAdmin.
   3. In the Explorer panel, click the operator ID initials, and then click Operator.
   4. On the Edit Operator ID rule form, click the Securitytab.
   5. Clear the Disable Operator check box.
   6. Click Save.
   7. Click Update password.
   8. In the Change Operator ID Password dialog box, enter a password, reenter it to confirm it, and then click Submit.
   9. Optional: Clear the Force password change on next login check box if you do not want to change the password for the DMReleaseAdmin operator ID the next time that you log in.
   10. Log out of the orchestration server.
2. On each candidate system, update the DMReleaseAdmin authentication profile to use the new password. All candidate systems use this authentication profile to communicate with the orchestration server about the status of the tasks in the pipeline.
   1. Log in to each candidate system with the DMAppAdmin user name and the password that you specified.
   2. In Dev Studio, click Records > Security > Authentication Profile.
   3. Click DMReleaseAdmin.
   4. On the Edit Authentication Profile rule form, click Set password.
   5. In the Password dialog box, enter the password, and then click Submit.
   6. Save the rule form.
3. On each candidate system, which includes the development, QA, staging, and production systems, enable the DMAppAdmin operator ID. If you want to create your own operator IDs, ensure that they point to the PegaDevOpsFoundation application.
   1. Log in to each candidate system with [email protected]/install.
   2. In Dev Studio, click Records > Organization > Operator ID, and then click DMAppAdmin.
   3. In the Explorer panel, click the operator ID initials, and then click Operator.
   4. On the Edit Operator ID rule form, click the Security tab.
   5. Clear the Disable Operator check box.
   6. Click Save.
   7. Click Update password.
   8. In the Change Operator ID Password dialog box, enter a password, reenter it to confirm it, and then click Submit.
   9. Optional: Clear the Force password change on next login check box if you do not want to change the password for the DMAppAdmin operator ID the next time that you log in.
   10. Log out of each candidate system.
4. On the orchestration server, modify the DMAppAdmin authentication profile to use the new password. The orchestration server uses this authentication profile to communicate with candidate systems so that it can run tasks in the pipeline.
   1. Log in to the orchestration server with the DMAppAdmin user name and the password that you specified.
   2. In Dev Studio, click Records > Security > Authentication Profile.
   3. Click DMAppAdmin.
   4. On the Edit Authentication Profile rule form, click Set password.
   5. In the Password dialog box, enter the password, and then click Submit.
   6. Save the rule form.
5. Do one of the following actions:
   1. If you are upgrading to Deployment Manager 4.2.x, resume the upgrade procedure from step 2. For more information, see Upgrading to Deployment Manager 4.2.x.
   2. If you are not upgrading, continue the installation procedure. For more information, see Step 3b: Configuring the orchestration server.

Step 3b: Configuring the orchestration server

The orchestration server is the system on which release managers configure and manage CI/CD pipelines.

1. Optional: If your system is not configured for HTTPS, verify that TLS/SSL settings are not enabled on the api and cicd service packages.
   1. Click Records > Integration-Resources > Service Package.
   2. Click api.
   3. On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is cleared.
   4. Click Records > Integration-Resources > Service Package.
   5. Click cicd.
   6. On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is cleared.
2. Configure the candidate systems in your pipeline. For more information, see Step 3c: Configuring candidate systems.

Step 3c: Configuring candidate systems

Configure each system system that is used for the development, QA, staging, and production stage in the pipeline.

1. On each candidate system, add the PegaDevOpsFoundation application to your application stack.
   1. In the Dev Studio header, click the name of your application, and then click Definition.
   2. In the Built on application section, click Add application.
   3. In the Name field, press the Down Arrow key and select PegaDevOpsFoundation.
   4. In the Version field, press the Down Arrow key and select the version of Deployment Manager that you are using.
   5. Click Save.
2. Optional: If your system is not configured for HTTPS, verify that TLS/SSL settings are not enabled on the api and cicd service packages.
   1. Click Records > Integration-Resources > Service Package.
   2. Click api.
   3. On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is cleared.
   4. Click Records > Integration-Resources > Service Package.
   5. Click cicd.
   6. On the Context tab, verify that the Require TLS/SSL for REST services in this package check box is cleared.
3. Optional: If you want to use a product rule other than the default product rule that is created by the New Application wizard, on the development system, create a productrule that defines the application package that will be moved through repositories in the pipeline. For more information, see Creating a product rule by using the create menu.

When you use the New Application wizard, a default product rule is created that has the same name as your application.

4. Configure repositories through which to move artifacts in your pipeline. For more information, see Step 3d: Creating repositories on the orchestration server and candidate systems.

Step 3d: Creating repositories on the orchestration server and candidate systems

If you are using Deployment Manager on premises, create repositories on the orchestration server and all candidate systems to move your application between all the systems in the pipeline. You can use a supported repository type that is provided in Pega Platform™, or you can create a custom repository type.

If you are using Deployment Manager on Pega Cloud, default repositories are provided. If you want to use repositories other than the ones provided, you can create your own.

For more information about creating a supported repository, see the following Creating a repository for file storage and knowledge management.

For more information about creating a custom repository type, see Creating custom repository types for Deployment Manager.

When you create repositories, note the following information:

• The Pega repository type is not supported.
• Ensure that each repository has the same name on all systems.
• When you create JFrog Artifactory repositories, ensure that you create a Generic package type in JFrog Artifactory. Also, when you create the authentication profile for the repository on Pega Platform, you must select the Preemptive authentication check box.

After you configure a pipeline, you can verify that the repository connects to the URL of the development and production repositories by clicking Test Connectivity on the Repository rule form.

Step 4: Configuring the development system for branch-based development (optional)

After you configure the orchestration server and all your candidate systems, configure additional settings so that you can use pipelines if you are using branches in a distributed or non-distributed branch-based environment.

You must configure the development system to create a pipeline in a branch-based environment.

1. On the development system (in nondistributed environment) or the main development system (in a distributed environment), create a Dynamic System Setting to define the URL of the orchestration server, even if the orchestration server and the development system are the same system.
   1. Click Create > Records > SysAdmin > Dynamic System Settings.
   2. In the Owning Ruleset field, enter Pega-DevOps-Foundation.
   3. In the Setting Purpose field, enter RMURL.
   4. Click Create and open.
   5. On the Settings tab, in the Value field, enter the URL of the orchestration server. Use this format: http://hostname:port/prweb/PRRestService.
   6. Click Save.
2. Complete the following steps on either the development system (in a non-distributed environment) or the remote development system (in a distributed environment).
   1. Use the New Application wizard to create a new development application that developers will log in to. This application allows development teams to maintain a list of development branches without modifying the definition of the target application.
   2. Add the target application of the pipeline as a built-on application layer of the development application.
      1. Log in to the application.
      2. In the Dev Studio header, click the name of your application, and then click Definition.
      3. In the Built-on application section, click Add application.
      4. In the Name field, press the Down Arrow key and select the name of the target application.
      5. In the Version field, press the Down Arrow key and select the target application version.
      6. Click Save.
   3. Lock the application rulesets to prevent developers from making changes to rules after branches have been merged.
      1. In the Dev Studio header, click the name of your application, and then click Definition.
      2. In the Application rulesets section, click the Open icon for each ruleset that you want to lock.
      3. Click Lock and Save.
   4. Optional: It is recommended that you merge branches by using the Merge Branch wizard. However, you can publish a branch to the remote development system to start a deployment. Publishing a branch when you have multiple pipelines per application is not supported.
      1. In Dev Studio, enable Pega repository types. For more information, see Enabling the Pega repository type.
      2. Create a new Pega repository type. For more information, see Creating a repository connection for file storage and knowledge management. Ensure that you do the following tasks:
         • In the Host ID field, enter the URL of the development system.
         • The default access group of the operator that is configured for the authentication profile of this repository should point to the pipeline application on the development system (in a nondistributed environment) or main development system (in a distributed environment).

Step 5: Configuring additional settings

As part of your pipeline, you can optionally send email notifications to users, configure Jenkins if you are using a Jenkins task, and upgrade to the latest version of Deployment Manager if you are using a previous version. See the following topics for more information:

• Configuring email notifications on the orchestration server
• Configuring Jenkins

Configuring email notifications on the orchestration server

You can optionally configure email notifications on the orchestration server. For example, users can receive emails when pre-merge criteria are not met and the system cannot create a deployment.

To configure the orchestration server to send emails, complete the following steps:

1. ​​Use the Email wizard to configure an email account and listener by clicking Dev Studio > Integration > Email > Email Wizard. This email account sends notifications to users when events occur, for example, if there are merge conflicts. For detailed information, see the procedure for “Configuring an email account that receives email and creates or manages work” in Entering email information in the Email wizard.
2. From the What would you like to do? list, select Receive an email and create/manage a work object.
3. From the What is the class of your work type? list, select Pega-Pipeline-CD.
4. From the What is your starting flow name? list, select NewWork.
5. From the What is your organization? list, select the organization that is associated with the work item.
6. In the What Ruleset? field, select the ruleset that contains the generated email service rule. This ruleset applies to the work class.
7. In the What RuleSet Version? field, select the version of the ruleset for the generated email service rule.
8. Click Nextto configure the email listener.
9. In theEmail Account Name field, enter Pega-Pipeline-CD, which is the name of the email account that the listener references for incoming and outgoing email.
10. In the Email Listener Name field, enter the name of the email listener. Begin the name with a letter, and use only letters, numbers, the ampersand character (&), and hyphens.
11. In the Folder Name field, enter the name of the email folder that the listener monitors. Typically, this folder is INBOX.
12. In the Service Package field, enter the name of the service package to be deployed. Begin the name with a letter, and use only letters, numbers, and hyphens to form an identifier.
13. In the Service Class field, enter the service class name.
14. In the Requestor User ID field, press the Down Arrow Key, and select the operator ID of the release manager operator.
15. In the Requestor Password field, enter the password for the release manager operator.
16. In the Requestor User ID field, enter the operator ID that the email service uses when it runs.
17. In the Passwordfield, enter the password for the operator ID.
18. Click Next to continue the wizard and configure the service package. For more information, see Configuring the service package in the Email wizard.
19. After you complete the wizard, enable the listener that you created in the Email Wizard.

Email notifications

Emails are also preconfigured with information about each notification type. For example, when a deployment failure occurs, the email that is sent provides information, such as the pipeline name and URL of the system on which the deployment failure occurred.

Preconfigured emails are sent in the following scenarios:

• Deployment start – When a deployment starts, an email is sent to the release manager and, if you are using branches, to the operator who started a deployment.
• Deployment step completion or failure – When a step either completes or fails, an email is sent to the release manager and, if you are using branches, to the operator who started the branch merge. The deployment pauses if there are any errors.
• Deployment completion – When a deployment is successfully completed, an email is sent to the release manager and, if you are using branches, to the operator who started the branch merge.
• Stage completion or failure – When a stage in a deployment process either succeeds or fails, an email is sent to the release manager and, if you are using branches, to the operator who started the branch merge.
• Manual tasks requiring approval – When a manual task requires email approval from a user, an email is sent to the user, who can approve or reject the task from the email.
• Stopped deployment – When a deployment is stopped, an email is sent to the release manager and, if you are using branches, to the operator who started the branch merge.
• Pega unit testing success or failure – If you are using the Run Pega unit tests task, and the task either succeeds or fails, an email is sent to the release manager and, if you are using branches, to the operator who started the branch merge.
• Schema changes required – If you do not have the required schema privileges to deploy schema changes on application packages that require those changes, an email is sent to the operator who started the deployment.
• Guardrail compliance score success or failure – If you are using the Check guardrail compliance task, an email is sent to the release manager if the task either succeeds or fails.
• Approve for production – If you are using the Approve for production task, which requires approval from a user before application changes are deployed to production, an email is sent to the user. The user can reject or approve the changes.
• Verify security checklist success or failure – If you are using the Verify security checklist task, which requires that all tasks be completed in the Application Security Checklist to ensure that the pipeline complies with security best practices, an email is sent to the release manager if the test either succeeds or fails.
• Pega scenario testing success or failure – If you are using the Run Pega scenario tests task, an email is sent to the release manager and, if you are using branches, to the operator who started the branch merge, if Pega scenario testing either succeeds or fails.
• Start test coverage success or failure – If you are using the Enable test coverage task to generate a test coverage report, an email is sent to the release manager if the task either fails or succeeds.
• Verify test coverage success or failure – If you are using the Verify test coverage task, an email is sent to the release manager if the task either fails or succeeds.
• Application quality statistics refreshed – If you are using the Refresh application quality statistics task, an email is sent to the release manager when the task is run.

Configuring Jenkins

If you are using a Jenkins task in your pipeline, configure Jenkins so that it can communicate with the orchestration server.

1. On the orchestration server, create an authentication profile that uses Jenkins credentials.
   1. Click Create > Security > Authentication Profile.
   2. Enter a name, and then click Create and open.
   3. In the User name field, enter the user name of the Jenkins user.
   4. Click Set password, enter the Jenkins password, and then click Submit.
   5. Click the Preemptive authentication check box.
   6. Click Save.
2. Because the Jenkins task does not support Cross-Site Request Forgery (CSRF), disable it by completing the following steps:
   1. In Jenkins, click Manage Jenkins.
   2. Click Configure Global Security.
   3. In the CRSF Protection section, clear the Prevent Cross Site Request Forgery exploits check box.
   4. Click Save.
3. Install the Post build task plug-in.
4. Install the curl command on the Jenkins server.
5. Create a new freestyle project.
6. On the General tab, select the This project is parameterized check box.
7. Add the BuildID and CallBackURL parameters.
   1. Click Add parameter, and then select String parameter.
   2. In the String field, enter BuildID.
   3. Click Add parameter, and thenselect String parameter.
   4. In the String field, enter CallBackURL.
8. In the Build Triggers section, select the Trigger builds remotely check box.
9. In the Authentication Token field, select the token that you want to use when you start Jenkins jobs remotely.
10. In the Build Environment section, select the Use Secret text(s) or file(s)check box.
11. In the Bindings section, do the following actions:
    1. Click Add, and then select User name and password (conjoined).
    2. In the Variable field, enter RMCREDENTIALS
    3. .In the Credentials field, click Specific credentials.
    4. Click Add, and then select Jenkins.
    5. In the Add credentials dialog box, in the Username field, enter the operator ID of the release manager operator that is configured on the orchestration server.
    6. In the Password field, enter the password.
    7. Click Save.
12. In the Post-Build Actions section, do one of the following actions, depending on your operating system:
    • If Jenkins is running on Microsoft Windows, add the following post-build tasks:
      1. Click Add post-build action, and then select Post build task.
      2. In the Log text field, enter a unique string that for the message that is displayed in the build console output when a build fails, for example BUILD FAILURE.
      3. In the Script field, enter curl --user %RMCREDENTIALS% -H "Content-Type: application/json" -X POST --data "{\"jobName\":\"%JOB_NAME%\",\"buildNumber\":\"%BUILD_NUMBER%\",\"pyStatusValue\":\"FAIL\",\"pyID\":\"%BuildID%\"}" "%CallBackURL%".
      4. Click Add another task.
      5. In the Log text field, enter a unique string that for the message that is displayed in the build console output when a build is successful, for example BUILD SUCCESS.
      6. In theScript field, entercurl --user %RMCREDENTIALS% -H "Content-Type: application/json" -X POST --data "{\"jobName\":\"%JOB_NAME%\",\"buildNumber\":\"%BUILD_NUMBER%\",\"pyStatusValue\":\"SUCCESS\",\"pyID\":\"%BuildID%\"}" "%CallBackURL%"
      7. Click Save.
    • If Jenkins is running on UNIX or Linux, add the following post-build tasks. Use the dollar sign ($) instead of the percent sign (%) to access the environment variables.
      1. Click Add post-build action, and then select Post build task.
      2. In the Log text field, enter a unique string that for the message that is displayed in the build console output when a build fails, for example BUILD FAILURE.
      3. In the Script field, enter curl --user $RMCREDENTIALS -H "Content-Type: application/json" -X POST --data "{\"jobName\":\"$JOB_NAME\",\"buildNumber\":\"$BUILD_NUMBER\",\"pyStatusValue\":\"FAIL\",\"pyID\":\"$BuildID\"}" "$CallBackURL"
      4. Click Add another task.
      5. In the Log text field, enter a unique string that for the message that is displayed in the build console output when a build is successful, for example BUILD SUCCESS.
      6. In the Script field, enter curl --user $RMCREDENTIALS -H "Content-Type: application/json" -X POST --data "{\"jobName\":\"$JOB_NAME\",\"buildNumber\":\"$BUILD_NUMBER\",\"pyStatusValue\":\"SUCCESS\",\"pyID\":\"$BuildID\"}" "$CallBackURL"
      7. Click Save.