Table of Contents

Installing, upgrading, and configuring Deployment Manager 4.5.x

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.

You should make changes only in your development environment and then move those changes to higher environments. Do not make changes in any other environment.
Each customer virtual private cloud (VPC) on Pega Cloud Services has a dedicated orchestrator instance to use Deployment Manager. If you are upgrading from an earlier release, contact Pegasystems® Global Client Support (GCS) support to request a new version.
This document describes the procedures for the latest version of Deployment Manager 4.5.x.
To use notifications, you must install or upgrade to Pega 8.1.3 on the orchestration server.

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

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

Step 1: Installing or upgrading Deployment Manager

The following procedure applies only to on-premises systems.

Because Pega Cloud Services manages the orchestration server in any Pega Cloud subscription, Pega Cloud Services manages the installation and upgrades of Deployment Manager orchestration servers; therefore, only post-upgrade steps are required if you are upgrading from versions of Deployment Manager earlier than 3.2.1. For more information, see Step 2: Running post-upgrade steps.

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

  1. Install Pega Platform™ 8.1, 8.2, or 8.3 on all systems in the pipeline.
  2. On each system, browse to the Deployment Manager Pega Marketplace page, and then download the DeploymentManager04.05.0x.zip file for your version of Deployment Manager.
  3. Extract the DeploymentManager04.05.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.
  5. On the orchestration server, import the following files:
    • PegaDevOpsFoundation_4.zip
    • PegaDeploymentManager_4.5.zip
  6. On the candidate systems, import the PegaDevOpsFoundation_4.zip file.
  7. Optional: If you are using a distributed development for CI/CD workflows, on the remote development system, import the PegaDevOpsFoundation_4.zip file.
  8. Do one of the following actions:

Step 2: Running post-upgrade steps

If you are upgrading from Deployment Manager versions earlier than 3.2.1, you must run post-upgrade steps to complete the upgrade.

Before you run post-upgrade steps, ensure that no deployments are running, have errors, or are paused. In Pega Cloud Service environments, the orchestration server name is similar to [environmentname]-DevOps.

If you are upgrading from Deployment Manager 3.2.1 or later, skip this section.

  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. Modify the current release management application so that it is built on PegaDeploymentManager:4.5.
    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 4.5.
    3. Click Save.
  3. 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.
  4. 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.
  5. On the orchestration server, 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.
    1. 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.

    You do not need to perform any of the required steps in the remainder of this document. If you want to use Jenkins tasks for configure email notifications, see Step 5: Configuring additional settings (optional).

    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. The orchestration server uses this authentication profile to communicate with candidate systems so that it can run tasks in the pipeline. 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. All candidate systems use this authentication profile to communicate with the orchestration server about the status of the tasks in the pipeline. 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.
    The DMReleaseAdmin and DMAppAdmin operator IDs do not have default passwords.

    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 administrator@pega.com/install.
      2. In Dev Studio, click Records > Organization > Operator ID, and then click DMReleaseAdmin.
      3. On the Edit Operator ID rule form, click the Security tab.
      4. Clear the Disable Operator check box.
      5. Click Save.
      6. Click Update password.
      7. In the Change Operator ID Password dialog box, enter a password, reenter it to confirm it, and then click Submit.
      8. Log out of the orchestration server.
    2. 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 administrator@pega.com/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. Log out of each candidate system.
    3. 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 operator ID 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.
    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. >If your target environment is SSL-enabled with private certificates, configure the Deployment Manager connectors so that they can receive and process tokens by doing setting the keystore:
      1. In Dev Studio, create and configure a keystore. For more information, see Creating a keystore.
      2. Configure the Pega-DeploymentManager/TrustStore dynamic system setting to reference the keystore ID:
        1. Click Records > SysAdmin > Dynamic System Settings.
        2. Click the Pega-DeploymentManager/TrustStore dynamic system setting.
        3. On the Settings tab, in the Value field, enter the ID of the keystore that you created in the previous step.
        4. Click Save.

    For more information about dynamic system settings, see Creating a dynamic system setting.

    1. Do one of the following actions:
      1. If you are upgrading to Deployment Manager 4.5.x, resume the post-upgrade procedure from step 2. For more information, see Running post-upgrade steps.
      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 for your target application, test application, or both, other than the default rules that are created by the New Application wizard, on the development system, create product rules that define the test application package and the target 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 for your target application is created that has the same name as your application. Additionally, if you are using a test application, a product rule is created with the same name as the target application, with _Tests appended to the name.

    1. 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 Services, default repositories, named pegacloudcustomerroot for both the development and production repositories, are provided. If you want to use repositories other than the ones provided, you can create your own.

    The defaultstore repository is a file system repository that you cannot use to host artifacts or product archives.

    For more information about creating a supported repository, see Creating a repository.

    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)

    If you are using branches in either a distributed or nondistributed branch-based environment, configure the development system to create a pipeline.

    Complete the following steps:

    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.

    For more information about dynamic system settings, see Creating a dynamic system setting.

    1. 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. Copy the development repository that you configured on the remote development system to the main development system.
      5. Optional: If you are managing test cases separately from the target application, create a test application. For more information, see Managing test cases separately in Deployment Manager.
      6. Optional: If you want to rebase your development application to obtain the most recently committed rulesets after you merge your branches, configure Pega Platform so that you can use rule rebasing. For more information, see Rule rebasing.

    Step 5: Configuring additional settings (optional)

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

    Configuring email accounts on the orchestration server

    Deployment Manager provides the Pega-Pipeline-CD email account and the DMEmailListener email listener. If you are configuring email accounts for the first time, update your email account details in the Deployment Manager portal. For more information, see Configuring email senders and recipients in Using Deployment Manager 4.5.x.

    If you are upgrading to Deployment Manager 4.5.x and using the Pega-Pipeline-CD email account for sending emails, the DMEmailListener email listener always listens to the Pega-Pipeline-CD account. If you have a different listener for the Pega-Pipeline-CD account, delete that listener by doing the following steps:

    1. In Dev Studio, click Configure > Integration > Email > Email listeners.
    2. On the Email: Integration page, on the Email Listeners tab, click the listener that you want to delete.
    3. Click Delete.

    If you are upgrading to Deployment Manager and using the Default email account, after you upgrade to Deployment Manager 4.5.x, do the following actions:

    1. Update the email sender and recipient in Deployment Manager. For more information, see Configuring email senders and recipients in Using Deployment Manager 4.5.x.
    2. If you have an email listener that listens to the same email address that you configured in Deployment Manager in the previous step, delete the listener to ensure that the DMEmailListener is listening to the email account that you configured.

    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.
    • Jenkins job success or failure – If you are using a Jenkins task, an email is sent to the release manager if a Jenkins job either succeeds or fails.

    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. Install the Post build task plug-in.
    3. Install the curl command on the Jenkins server.
    4. Create a new freestyle project.
    5. On the General tab, select the This project is parameterized check box.
    6. 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 then select String parameter.
      4. In the String field, enter CallBackURL.
    7. Optional: To add parameters that you can use in Jenkins tasks in the pipeline, click Add parameter, select String parameter, and enter the string of the parameter. The system automatically populates these values in Jenkins tasks. You can add any of the following strings:
      • PipelineName: Pipeline name on which the Jenkins task is configured.
      • RepositoryName: Repository that the Deploy task uses for the stage (for example, development) on which the Jenkins task is configured.
      • DeploymentID: ID of the current deployment.
      • DeploymentArtifactName: Artifact name that the Deploy task uses on the stage on which the Jenkins task is configured.
      • StartedBy: Operator ID who started the deployment.
      • CurrentStage: Name of the stage on which the Jenkins task is configured.
      • CurrentStageURL: URL of the system on which the Jenkins task is configured.
      • ArtifactPath: Full path to the artifact that the Deploy task uses.
    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 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.
      • 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.

    Have a question? Get answers now.

    Visit the Pega Support Community to ask questions, engage in discussions, and help others.