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

See the following topics for more information:

• Step 1: Installing Deployment Manager
• Step 2: Configuring systems in the pipeline
• Step 3: Configuring systems for branch-based development (optional and in addition to Step 2: Configuring systems in the pipeline, if you are using branches in a distributed or nondistributed environment)
• Step 4: Configuring additional settings

Installing Deployment Manager

To install Deployment Manager, you must first install Pega^® Platform on all systems in the pipeline, and then import certain files into Pega Platform.

1. Install Pega Platform 7.3 or Pega 7.3.1 on all systems in the CI/CD pipeline.
2. Browse to the Deployment Manager Pega Exchange page, and then download one of the following files to your local disk on each system:
   • DeploymentManager_01.0x.0x.zip if you are installing Deployment Manager on Pega 7.3.
   • DeploymentManager_02.0x.0x.zip if you are installing Deployment Manager on Pega 7.3.1.
3. Use the Import wizard to import files into the appropriate systems. For more information about the Import wizard, see Importing a file by using the Import wizard.
4. Do one of the following actions:

• If you are installing Deployment Manager on Pega 7.3, complete the following tasks:

1. On the orchestration server, import the following files:
   • PegaDevOpsFoundation_01.x.x.zip
   • PegaDeploymentManager_01.x.x.zip
   • PegaDevOpsSupport_7.3.zip

In addition, import the following hotfixes, which are not provided in the DeploymentManager_01.0x.0x.zip file.

• HFIX-38491
• HFIX-36965
• HFIX-36674

3. On the development, QA, staging, and production systems, and on the remote development system (if you are using branches in a distributed environment), import the following files:
   • PegaDevOpsFoundation_01.x.x.zip
   • PegaDevOpsSupport_7.3.zip

In addition, import the HFIX-38491 hotfix, which is not provided in the DeploymentManager_01.0x.0x.zip file.

• If you are installing Deployment Manager on Pega 7.3.1, do the following tasks:

  1. On the development, QA, staging, and production systems, import the PegaDevOpsFoundation02xx.zip file.
  2. On the orchestration server, import the following files:
  • PegaDevOpsFoundation02xx.zip
  • PegaDeploymentManager02xx.zip

Step2: 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 2a: Configuring the orchestration server
2. Step 2b: Configuring candidate systems
3. Step 2c: Creating repositories on the orchestration and candidate systems

Step 2a: Configuring the orchestration server

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

1. Create an application that the release manager uses for creating, managing, and running pipelines, by using the New Application wizard. For more information, see Creating an application with the New Application wizard.
2. Add the PegaDeploymentManager application to your application stack.
   1. In the Designer 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 PegaDeploymentManager.
   4. In the Version field, press the Down Arrow key and select the version of Deployment Manager that you are using.
   5. Click Save.

Ensure that this application remains unlocked and has at least one unlocked ruleset.

3. 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.
4. Add the PegaRULES:RepositoryAdministrator, PegaRULES:PegaAPI, and PegaRULES:SecurityAdministrator roles to the Administrator access groups that were generated by the New Application wizard:
   1. Click Designer Studio > Org & Security > Groups & Roles > Access Groups.
   2. Click an access group to open it.
   3. In the Available roles section, click Add role.
   4. In the field that is displayed, press the Down Arrow key and select PegaRULES:RepositoryAdministrator.
   5. Click Add role.
   6. In the field that is displayed, press the Down Arrow key and select PegaRULES:PegaAPI.
   7. Click Add role.
   8. In the field that is displayed, press the Down Arrow key and select PegaRULES:SecurityAdministrator.
   9. Save the Edit Access Group rule form.
5. If you are using Deployment Manager for Pega 7.3, configure the api service package to use the PegaDevOpsFoundation:Administrators access group:
   1. Click Records > Integration-Resources > Service Package.
   2. Click api.
   3. On the Context tab, in the Service access group field, enter PegaDevOpsFoundation:Administrators. This access group is used during rule resolution to find the correct service rule at run time.
   4. Click Save.
   5. In the Methods section, select Rule-Service-REST from the Service type list and verify that the following methods are listed:

5. Create an authentication profile on the orchestration server that references an operator ID whose access group points to the target application on each candidate system. For example, if the operator that is on the candidate systems has the credentials janedoe/rules, you must create an authentication profile on the orchestration server that is also configured with the janedoe/rules credentials. For more information about configuring authentication profiles, see Authentication Profile data instances - Completing the New or Save As forms.

If the operator IDs and passwords are different on the candidate systems, you must create multiple authentication profiles.

6. Configure the candidate systems in your pipeline. For more information, see Step 2b: Configuring candidate systems.

Step 2b: Configuring candidate systems

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

1. Use the Import wizard to import your target application into each candidate system. For more information about the Import wizard, see Importing a file by using the Import wizard.

2. On each candidate system, add the PegaDevOpsFoundation application to your application stack:
   1. In the Designer 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.
3. On each candidate system, add the PegaRULES:RepositoryAdministrator, PegaRULES:PegaAPI, and PegaRULES:SecurityAdministrator roles to the operator that you use to access your application on each system.
   1. Log in to each Pega Platform server with an operator whose default access group points to your application. This is the same operator that you configured on the orchestration server whose authentication profile points to this system from the orchestration server.
   2. Click your user profile and select Access group.
   3. In the Available roles section, click Add role.
   4. In the field that is displayed, press the Down Arrow key and select PegaRULES:RepositoryAdministrator.
   5. Click Add role.
   6. In the field that is displayed, press the Down Arrow key and select PegaRULES:PegaAPI.
   7. Click Add role.
   8. In the field that is displayed, press the Down Arrow key and select PegaRULES:SecurityAdministrator.
   9. Click Save.
4. On each candidate system, create an authentication profile and configure it with the operator ID and password of the release manager operator.Use the operator ID and password of the administrative operator that was generated when you created a new application on the orchestration server. All candidate systems use this authentication profile to communicate with the orchestration server about the status of the tasks in the pipeline.
   1. Click Create > Security > Authentication Profile.
   2. In the name field, enter ReleaseManager.
   3. Configure the authentication profile to use the release manager operator ID and password, and configure other information, as appropriate. For example, if the credentials of the release manager are rmanager/rules, configure each authentication profile on the candidate systems with the rmanager/rules credentials.

For more information about creating authentication profiles, see Authentication Profile data instances - Completing the New or Save As forms.

5. 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.

6. On the development system, create a product rule that defines the application package that will be moved through repositories in the pipeline. For more information, see Product rules: Completing the Create, Save As, or Specialization form.

7. Configure repositories through which to move artifacts in your pipeline. For more information, see Step 2c: Creating repositories on the orchestration and candidate systems.

Step 2c: Creating repositories on the orchestration server and candidate systems

Create repositories on the orchestration server and all candidate systems to move your application between all the systems in the pipeline.

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

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 in Pega Platform, you must select the Preemptive authentication check box.

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

Step 3: Configuring systems for branch-based development

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 nondistributed environment.

1. Step 3a: Configuring the development system for branch-based development
2. Step 3b: Configuring the orchestration server for branch-based development

Configuring the development system for branch-based development

Configure the development system if you are using branches either in a nondistributed environment or in a distributed environment in which you use both a main and remote development system.

1. Perform the following steps on either the development system (in a nondistributed environment) or the main development system (in a distributed environment).
   1. Create a Dynamic System Setting that defines the rulesets that are hosted on the main development system:
      1. Click Records > SysAdmin > Dynamic System Settings.
      2. In the Owning Ruleset field, enter Pega-ImportExport.
      3. In the Setting Purpose field, enter HostedRulesetsList.
      4. Click Create and open.
      5. On the Settings tab, in the Value field, enter a comma-separated list of the rulesets on the remote development system. Enclose each ruleset value within double quotation marks, for example, “HRApp”.
      6. Click Save.
   2. 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-ReleaseManager.
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 in the following format: http://hostname:port/prweb/PRRestService.
6. Click Save.

2. Perform the following steps on either the development system (in a nondistributed environment) or the remote development system (in a distributed environment)
   1. Use the New Application wizard to create a 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. For more information, see Creating an application with the New Application wizard.
   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 Designer 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. Log in to the application that you created in the previous step and create an authentication profile that uses the operator ID and password of an operator whose default access group points to the target application on the development system. For more information, see Authentication Profile data instances: Completing the New or Save As form.
   4. Lock the application rulesets to prevent developers from making changes to rules after branches have been merged:
      1. In the Designer 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.
   5. Enable Pega repository types. For more information, see Enabling the Pega repository type.
   6. Create a new Pega repository type. For more information, see Creating a repository connection. Ensure that you do the following tasks:
      • In the Host ID field, enter the URL of the development system.
      • Use the authentication profile that you created by clicking the Use authentication check box, pressing the Down Arrow key in the Authentication profile field, and selecting the authentication profile that you created in step 3-c.

3. Configure the orchestration server. For more information, see Step 3b: Configuring the orchestration server for branch-based development.

Step 3b: Configuring the orchestration server for branch-based development

Configure the orchestration server so that you can use pipelines in a branch-based environment.

1. Create a Dynamic System Setting to define the operator who can start queued builds. The build will be started using the operator that you define in this Dynamic System Setting.
2. Click Create > Sysadmin > Dynamic System Settings.
3. In the Owning Ruleset field, enter Pega-DevOps-ReleaseManager.
4. In the Setting Purpose field, enter ReleaseManager.
5. Click Create and open.
6. On the Settings tab, in the Value field, enter the operator ID whose default access group points to the release manager application.
7. Click Save.
8. Save the Pega-DeploymentManager agent to your ruleset and set its access group to the release manager application access group:

1. Click Records > SysAdmin > Agents.
2. Click the Pega-DeploymentManager agent in the Pega-Deployment Manager ruleset and save it to your application ruleset.
3. Click the Security tab.
4. In the Access Group field, press the Down Arrow key and select the access group of the release manager application.
5. Click Save.

Step 4: Configuring additional settings

You can optionally configure email notifications on the orchestration server to notify users when an event occurs, such as a merge failure. You must also configure Jenkins if you are using a Jenkins step in a pipeline. See the following topics for more information:

• Configuring email notifications on the orchestration server (if you want to notify users when an event, such as a merge failure, occurs)
• Configuring Jenkins (if you are using a Jenkins step in a pipeline)

Configuring email notifications on the orchestration server

Optionally, you can 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 build.

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

1. ​​Configure an email account and listener by clicking Designer 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 Next to 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 Password field, 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. For more information, see Starting a listener.

Email notifications

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

Preconfigured emails are sent in the following scenarios:

• Build start – When a build starts, an email is sent to the release manager and, if you are using branches, to the operator who started a build.
• Build failure – If any step in the build process is unsuccessful, the build pauses. An email is sent to the release manager and, if you are using branches, to the operator who started the branch merge.
• Build step completion – When a step in a build process is 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 – When a stage in a build process is completed, an email is sent to the release manager and, if you are using branches, to the operator who started the branch merge.
• Build completion – When a build 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.
• 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 build – When a build is stopped, an email is sent to the release manager and, if you are using branches, to the operator who started the branch merge.
• PegaUnit testing failure – If a PegaUnit test cannot successfully run on a step in the build, 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 them on application packages that require those changes, an email is sent to the operator who started the build.

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 ($) to access the environment variables instead of the percent sign (%):
  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.