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.

On the orchestration server, release managers use the DevOps landing page to configure CI/CD pipelines for their Pega Platform™ applications. The landing page displays all the running and queued application deployments, branches that are to be merged, and reports that provide information about your DevOps environment such as key performance indicators (KPIs).

See the following topics for more information about using Deployment Manager to configure and use CI/CD pipelines:

• Configuring an application pipeline
• Manually starting a deployment
• Starting a deployment in a branch-based environment
• Starting a deployment in a distributed, branch-based environment
• Completing or rejecting a manual step in a deployment
• Schema changes in application packages
• Pausing a deployment
• Performing actions on a deployment with errors
• Diagnosing a pipeline
• Viewing branch status
• Viewing deployment logs
• Viewing deployment reports
• Viewing reports for all deployments
• Deleting an application pipeline
• Viewing, downloading and deleting application packages in repositories

Configuring an application pipeline

When you add a pipeline, you specify merge criteria and configure stages and steps in the continuous delivery workflow. For example, you can specify that a branch must be peer-reviewed before it can be merged, and you can specify that Pega unit tests must be run after a branch is merged and is in the QA stage of the pipeline.

You can create multiple pipelines for one version of an application. For example, you can use multiple pipelines in the following scenarios:

• To move a deployment to production separately from the rest of the pipeline. You can then create a pipeline that has only a production stage or development and production stages.
• To use parallel development and hotfix life cycles for your application.

Adding a pipeline on Pega Cloud

To add a pipeline on Pega Cloud, perform the following steps:

1. In the Designer Studio footer, click Deployment Manager.
2. Click Add pipeline.
3. Specify the details of the application for which you are creating the pipeline.
   1. Optional: If you want to change the URL of your development system, which is populated by default with your development system URL, in the Development environment field, press the Down Arrow key and select the URL. This is the system on which the product rule that defines the application package that moves through the repository is located.
   2. In the Application field, press the Down Arrow key and select the name of the application.
   3. In the Version field, press the Down Arrow key and select the application version.
   4. In the Access group field, press the Down Arrow key and select the access group for which pipeline tasks are run. This access group must be present on all the candidate systems and have at least the sysadmin4 role.
   5. In the Pipeline name field, enter the name of the pipeline. This name must be unique.
4. Click Create.

The system adds tasks, which you cannot delete, to the pipeline that are required to successfully run a workflow, for example, Deploy and Generate Artifact. For Pega Cloud, the system also adds mandatory tasks that must be run on the pipeline, for example, the Check guardrail compliance task and Verify security checklist task.

5. Optional: Add tasks that you want to perform on your pipeline, such as Pega unit testing. For more information, see Modifying stages and tasks in the pipeline.

Adding a pipeline on premises

To add a pipeline on premises, complete the following steps:

1. In the Designer Studio footer, click Deployment Manager.
2. Click Add pipeline.
3. Specify the details of the application for which you are creating the pipeline.
   1. In the Development environment field, enter the URL of the development system. This is the system on which the product rule that defines the application package that moves through the repository is located.
   2. In the Application field, press the Down Arrow key and select the name of the application.
   3. In the Version field, press the Down Arrow key and select the application version.
   4. In the Access group field, press the Down Arrow key and select the access group for which pipeline tasks are run. This access group must be present on all the candidate systems and have at least the sysadmin4 role.
   5. In the Pipeline name field, enter the name of the pipeline. This name must be unique.
   6. In the Product rule field, enter the name of the product rule that defines the contents of the application.
   7. In the Version field, enter the product rule version.
4. Optional: If the application depends on other applications, in the Dependencies section, add those applications.
   1. Click Add.
   2. In the Application name field, press the Down Arrow key and select the application name.
   3. In the Application version field, press the Down Arrow key and select the application version.
   4. In the Repository name field, press the Down Arrow key and select the repository that contains the production-ready artifact of the dependent application. If you want the latest artifact of the dependent application to be automatically populated, ensure that the repository that contains the production-ready artifact of the dependent application is configured to support file updates.
   5. In the Artifact name field, press the Down Arrow key and select the artifact.

For more information about dependent applications, see Product rules: Listing product dependencies for Pega-supplied applications.

5. Click Next.
6. In the Environment details section, in the Stages section, specify the URL of each candidate system and the authentication profile that each system uses to communicate with the orchestration system.
   1. In the Environments field for the system, press the Down Arrow key and select the URL of the system.
   2. Optional: If you are using your own authentication profiles, in the Authentication field for the system, press the Down Arrow key and select the authentication profile that you want to communicate from the orchestration server to the system.

By default, the fields are populated with the DMAppAdmin authentication profile.

7. In theArtifact managementsection, specify the development and production repositories through which the product rule that contains application contents moves through the pipeline.
   1. In the Development repository field, press the Down Arrow key and select the development repository.
   2. In the Production repository field, press the Down Arrow key and select the production repository.
8. Optional: In the External orchestration server section, if you are using a Jenkins step in a pipeline, specify Jenkins details.
   1. In the URLfield, enter the URL of the Jenkins server.
   2. In the Authentication profile field, press the Down Arrow key and select the authentication profile on the orchestration server that specifies the Jenkins credentials to use for Jenkins jobs.
9. Click Next.
10. Optional: If you are using branches in your application, in the Merge policy section, specify merge options.
    1. Do one of the following actions:
       • To merge branches into the highest existing ruleset in the application, click Highest existing ruleset.
       • To merge branches into a new ruleset, click New ruleset.
    2. In the Password field, enter the password that locks the rulesets on the development system.
11. Click Next.

The system adds tasks, which you cannot delete, to the pipeline that are required to successfully run a workflow, for example, Deploy and Generate Artifact. The system also adds other tasks to enforce best practices such as Check guardrail compliance and Verify security checklist.

1. Optional: In the Merge criteria pane, specify tasks that must be completed before a branch can be merged in the pipeline.
   1. Click Add task.
   2. Specify the task that you want to perform.
      • To specify that a branch must meet a compliance score before it can be merged:
        1. From the Task list, select Check guardrail compliance.
        2. In the Weighted compliance score field, enter the minimum required compliance score.
        3. Click Submit.
      • To specify that a branch must be reviewed before it can be merged:
        1. From the Task list, selectCheck review status.
        2. Click Submit.
2. Optional: To start a deployment automatically when a branch is merged, click the Trigger deployment on merge check box.
3. Optional: Clear a check box for a deployment life cycle stage to skip it.
4. Optional: In the Continuous Deployment section pane, specify the tasks to be performed during each stage of the pipeline.
   1. Do one of the following actions:
      • Click a manually added task, click the More
        
        icon, and then click either Add task above or Add task below.
      • Click Add task in the stage.
   2. From the Task list, select the task that you want to perform.
      • To run Pega unit tests either for the pipeline application or for an application that is associated with an access group, select Pega unit testing:
        1. Optional: Perform one of the following actions:
           • To run all the Pega unit tests that are in a Pega unit suite for the pipeline application, in the Test Suite ID field, enter the pxInsName of the suite ID. You can find this value in the XML document that comprises the test suite by clicking Actions > XML on the Edit Test Suite form.  If you do not specify a test suite, all the Pega unit tests for the pipeline application are run.
           • To run all the Pega unit tests for an application that is associated with an access group, in the Access Group field, enter the access group. For more information about creating Pega unit tests, seeCreating PegaUnit test cases.
        2. Click Submit.
      • To run a Jenkins job that you have configured, select Jenkins.
        1. In the Job name field, enter the name of the Jenkins job (which is the name of the Jenkins deployment) that you want to run.
        2. In the Token field, enter the Jenkins authentication token.
        3. In the Parameters field, enter parameters, if any, to send to the Jenkins job. Separate multiple parameters with a comma.
        4. Click Submit.
      • To add a manual step that a user must perform in the pipeline, select Manual.
        1. In the Job name field, enter text that describes the action that you want the user to take.
        2. In the Assigned to field, press the Down Arrow key and select the operator ID to assign the task to.
      • To specify that the application must meet a compliance score, select Check guardrail compliance.
        1. In the Weighted compliance score field, enter the minimum required compliance score.
        2. Click Submit.
      • To specify that all the tasks in the Application Security Checklist must be performed so that the pipeline can comply with security best practices, select Verify security checklist, and then click Submit. You must log in to the system for which this task is configured, and then mark all the tasks in the Application Security checklist as completed for the pipeline application. For more information about completing the checklist, see Preparing your application for secure deployment.
5. Optional: To modify the Approve for production task, which is added to the stage before production and which you use so that a user must approve application changes before they are sent to production, do the following actions:
   1. Click the Info icon.
   2. In the Job name field, enter a name for the task.
   3. In the Assign to field, press the Down Arrow key and select the user who approves the application for production. An email is sent to this user, who can approve or reject application changes from within the email.
   4. Click Submit.
6. Click Finish.

Modifying application details

You can modify application details, such as the product rule that defines the content of the application that moves through the pipeline.

1. Click Actions > Application details.
2. Optional: In the Development environment field, enter the URL of the development system, which is the system on which the product rule that defines the application package that moves through the repository is located.
3. Optional: In the Version field, press the Down Arrow key and select the application version.
4. Optional: In the Product rule field, press the Down Arrow key and select the product rule that defines the contents of the application.
5. Optional: In the Version field, press the Down Arrow key and select the product rule version.
6. Optional: If the application depends on other applications, in the Dependenciessection, add those applications.
   1. Click Add.
   2. In the Application name field, press the Down Arrow key and select the application name.
   3. In the Application version field, press the Down Arrow key and select the application version.
   4. In the Repository name field, press the Down Arrow key and select the repository that contains the production-ready artifact of the dependent application. If you want the latest artifact of the dependent application to be automatically populated, ensure that the repository that contains the production-ready artifact of the dependent application is configured to support file updates.
   5. In the Artifact name field, press the Down Arrow key and select the artifact.

For more information about dependent applications, see Product rules: Listing product dependencies for Pega-supplied applications.

7. Click Save.

Modifying URLs and authentication profiles

You can modify the URLs of your development and candidate systems and the authentication profiles that are used to communicate between those systems and the orchestration server.

1. Click Actions > Environment details.
2. Click Stages.
3. In the Environments field for the system, press the Down Arrow key and select the URL of the system.
4. In the Authentication field for the system, press the Down Arrow key and select the authentication profile that you want to communicate from the orchestration server to the system.
5. Click Save.

Modifying development and production repositories

You can modify the development and production repositories through which the product rule that contains application contents moves through the pipeline. All the generated artifacts are archived in the Development repository, and all the production-ready artifacts are archived in the Production repository.

You do not need to configure repositories if you are using Pega Cloud but can use different repositories other than the default ones that are provided.

4. Click Actions > Environment details.
5. Click Artifact Management.
6. Do one of the following actions to select a repository:
   • If you are using Deployment Manager on premises, or on Pega Cloud with default repositories, complete the following tasks:
     1. In the Application repository section, in the Development repository field, press the Down Arrow key and select the development repository
     2. In the Production repository field, press the Down Arrow key and select the production repository.
   • If you are using Deployment Manager on Pega Cloud and want to use different repositories other than the default repositories, complete the following tasks:
     1. In the Artifact repository section, click Yes.
     2. In the Development repository field, press the Down Arrow key and select the development repository.
     3. In the Production repository field, press the Down Arrow key and select the production repository.
7. Click Save.

Specifying Jenkins server information

If you are using a Jenkins step, specify details about the Jenkins server such as its URL.

1. Click Actions > Environment details.
2. Click External orchestration server.
3. Click the Jenkins icon.
4. Click OK.
5. In the URL field, enter the URL of the Jenkins server.
6. In the Authentication profile field, press the Down Arrow key and select the authentication profile on the orchestration server that specifies the Jenkins credentials to use for Jenkins jobs.
7. Click Save.

Specifying merge options for branches

If you are using branches in your application, specify options for merging branches into the base application.

1. Click Actions > Merge policy.
2. Do one of the following actions:
   • To merge branches into a new ruleset, click New ruleset.
   • To merge branches into the highest existing ruleset in the application, click Highest existing ruleset.
3. In the Password field, enter the password that locks the rulesets on the development system.
4. Click Save.

Modifying stages and tasks in the pipeline

You can modify the stages and the tasks that are performed in each stage of the pipeline. For example, you can skip a stage or add tasks such as Pega unit testing to be done on the QA stage.

1. Click Actions > Pipeline model.
2. Optional: In the Merge criteria pane, specify tasks that must be completed before a branch can be merged in the pipeline.
   1. Click Add task.
   2. Specify the task that you want to perform.
      1. To specify that a branch must meet a compliance score before it can be merged:
         • From the Task list, select Check guardrail compliance.
         • In the Weighted compliance score field, enter the minimum required compliance score.
         • Click Submit.
      2. To specify that a branch must be reviewed before it can be merged:
         1. From the Task list, selectCheck review status.
         2. Click Submit.
3. Optional: To start a deployment automatically when a branch is merged, click the Trigger deployment on merge check box.
4. Optional: Clear a check box for a deployment life cycle stage to skip it.
5. Optional: In the Continuous Deployment section pane, specify the tasks to be performed during each stage of the pipeline.
   1. Do one of the following actions:
      • Click a manually added task, click the More icon, and then click either Add task above or Add task below to add the task above or below the existing task.
      • Click Add task in the stage.
   2. From the Task list, select the task that you want to perform.
      • To run Pega unit tests either for the pipeline application or for an application that is associated with an access group, select Pega unit testing.
        1. Optional: Perform one of the following actions:
           • To run all the Pega unit tests that are in a Pega unit suite for the pipeline application, in the Test Suite ID field, enter the pxInsName of the suite ID. You can find this value in the XML document that comprises the test suite by clicking Actions > XML on the Edit Test Suite form.  If you do not specify a test suite, all the Pega unit tests for the pipeline application are run.
           • To run all the Pega unit tests for an application that is associated with an access group, in the Access Group field, enter the access group. For more information about creating Pega unit tests, seeCreating PegaUnit test cases.
        2. Click Submit.
      • To run a Jenkins job that you have configured, select Jenkins.
        1. In the Job name field, enter the name of the Jenkins job (which is the name of the Jenkins deployment) that you want to run.
        2. In the Token field, enter the Jenkins authentication token.
        3. In the Parameters field, enter parameters, if any, to send to the Jenkins job. Separate multiple parameters with a comma.
        4. Click Submit.
      • To add a manual step that a user must perform in the pipeline, select Manual.
        1. In the Job name field, enter text that describes the action that you want the user to take.
        2. In the Assigned to field, press the Down Arrow key and select the operator ID to assign the task to.
        3. Click Submit.
      • To specify that the application must meet a compliance score, select Check guardrail compliance.
        1. In the Weighted compliance score field, enter the minimum required compliance score.
        2. Click Submit.
      • To specify that all the tasks in the Application Security Checklist must be performed so that the pipeline can comply with security best practices, select Verify security checklist, and then click Submit. You must log in to the system for which this task is configured, and then mark all the tasks in the Application Security checklist as completed for the pipeline application. For more information about completing the checklist, see Preparing your application for secure deployment.
6. Optional: To modify the Approve for production task, which is added to the stage before production and which you use so that a user must approve application changes before they are sent to production, do the following actions:
   1. Click the Info icon.
   2. In the Job name field, enter a name for the task.
   3. In the Assign to field, press the Down Arrow key and select the user who approves the application for production. An email is sent to this user, who can approve or reject application changes from within the email.
   4. Click Submit.
7. Click Finish.

Manually starting a deployment

Start a deployment manually if you are not using branches and are working directly in rulesets.

You can also start a deployment manually if you do not want deployments to start automatically when branches are merged. You must also clear the Trigger deployment on merge check box in the pipeline configuration.

1. Click Deployment Manager in the Designer Studio footer.
2. Click the pipeline for which you want to start a deployment.
3. Click Start deployment.
4. Start a new deployment or deploy an existing application by completing one of the following actions:

• To start a deployment and deploy a new application package, do the following steps:
  1. Click Generate new artifact.
  2. In the Deployment name field, enter the name of the deployment.
  3. Click Deploy.
• To deploy an application package that is on a cloud repository, do the following steps:

1. Click Deploy an existing artifact.
2. In the Deployment name field, enter the name of the deployment.
3. In the Select a repository field, press the Down Arrow key and select the repository.
4. In the Select an artifact field, press the Down Arrow key and select the application package.
5. Click Deploy.

Starting a deployment in a branch-based environment

In non-distributed, branch-based environments, you can immediately start a deployment by submitting a branch into a pipeline in the Merge Branches wizard. For more information, see Submitting a branch into a pipeline.

Starting a deployment in a distributed branch-based environment

If you are using Deployment Manager in a distributed, branch-based environment and using multiple pipelines per application, first export the branch to the main development system, and then merge it.

1. On the remote development system, package the branch. For more information, see Packaging a branch.
2. Export the branch.
3. On the main development system, import the branch by using the Import wizard. For more information, see Importing a file by using the Import wizard.
4. On the main development system, start a deployment by using the Merge Branches wizard. For more information, see Submitting a branch into a pipeline.

If you are using one pipeline per application, you can publish a branch to start the merge. For more information, see Publishing a branch to a repository.

Completing or rejecting a manual step in a deployment

If a manual step is configured on a deployment, the deployment pauses when it reaches the step, and you can either complete it or reject it. For example, if a user was assigned a task and completed it, you can complete the task to continue the deployment. Deployment Manager also sends you an email when there is a manual step in the pipeline. You can complete or reject a step either within the pipeline or through email.

Deployment Manager also generates a manual step if there are schema changes in the application package that the release manager must apply. For more information, see Schema changes in application packages.

To complete or reject a manual step within the deployment, do the following steps:

1. Click Deployment Manager in the Designer Studio footer.
2. Click a pipeline.
3. Right-click the manual step and select one of the following options:
   • Complete task: Resolve the task so that the deployment continues through the pipeline.
   • Reject task: Reject the task so that the deployment does not proceed.

To complete or reject a manual step from within an email, click either Accept or Reject.

Schema changes in application packages

If an application package that is to be deployed on candidate systems contains schema changes, the Pega Platform orchestration server checks the candidate system to verify that you have the required privileges to deploy the schema changes. One of the following results occurs:

• If you have the appropriate privileges, schema changes are automatically applied to the candidate system, the application package is deployed to the candidate system, and the pipeline continues.
• If you do not have the appropriate privileges, Deployment Manager generates an SQL file that lists the schema changes and sends it to your email address. It also creates a manual step, pausing the pipeline, so that you can apply the schema changes. After you complete the step, the pipeline continues. For more information about completing a step, see Completing or rejecting a manual step.

You can also configure settings to automatically deploy schema changes so that you do not have to manually apply them if you do not have the required privileges. For more information, see Configuring settings to automatically deploy schema changes.

Configuring settings to automatically deploy schema changes

You can configure settings to automatically deploy schema changes that are in an application package that is to be deployed on candidate systems. Configure these settings so that you do not have to apply schema changes if you do not have the privileges to deploy them.

1. On the orchestration server, in Pega Platform, set the AutoDBSchemaChanges Dynamic System Setting to true to enable schema changes at the system level.
   1. In Designer Studio, search for AutoDBSchemaChanges.
   2. On the Settings tab, in the Value field, enter true.
   3. Click Save.
2. Add the SchemaImport privilege to your access role to enable schema changes at the user level. For more information, see Specifying privileges for an Access or Role to Object rule.

These settings are applied sequentially. If the AutoDBSchemaChanges Dynamic System Setting is set to false, you cannot deploy schema changes, even if you have the SchemaImport privilege.

Pausing a deployment

When you pause a deployment, the pipeline completes the task that it is running, and stops the deployment at the next step.

To pause a deployment, click Pause.

Performing actions on a deployment that has errors

If a deployment has errors, the pipeline stops processing on it. You can do one of the following actions:

• Ignore the current step and run the next step by clicking Start.
• Restart the deployment at the current step, after fixing the errors, by clicking Start.
• Roll back to an earlier deployment by clicking Roll back deployment
  
  .

Diagnosing a pipeline

You can diagnose your pipeline to verify that your pipeline is configured properly such as whether the target application and product rule are in the development environment, connectivity between systems and repositories is working, and premerge settings are correctly configured.

1. In the Designer Studio footer, click Deployment Manager.
2. Click a pipeline.
3. Click Actions > Diagnose pipeline.
4. In the Diagnose application pipeline dialog box, review the errors, if any.
5. Optional: To view troubleshooting tips about errors, hover your mouse over the Troubleshooting tips link.

Viewing branch status

You can view the status of all the branches that are in your pipeline. For example, you can see whether a branch was merged in a deployment and when it was merged.

1. Click Deployment Manager in the Designer Studio footer.
2. Click a pipeline.
3. Click Actions > View branches.

Viewing deployment logs

View logs for a deployment to see the completion status of operations, for example, when a deployment is moved to a new stage. You can change the logging level to control which events are displayed in the log. For example, you can change logging levels of your deployment from INFO to DEBUG for troubleshooting purposes. For more information, see Logging Level Settings tool.

1. Click Deployment Manager in the Designer Studio footer.
2. Click a pipeline.
3. Click the Gear icon for the deployment for which you want to view the log file.
4. Click View log.

Viewing deployment reports

Deployment reports provide information about a specific deployment. You can view information such as the number of tasks that you configured on a deployment that have been completed and when each task started and ended.

1. Click Deployment Manager in the Designer Studio footer.
2. Click a pipeline.
3. Click the Gear icon for the deployment for which you want to view the deployment report.
4. Click View report.

Viewing reports for all deployments

Reports provide a variety of information about all the deployments in your pipeline. You can view the following key performance indicators (KPI):

• Deployment Success - Percentage of deployments that are successfully deployed to production
• Deployment Frequency – Frequency of new deployments to production
• Deployment Speed - Average time taken to deploy to production
• Start frequency - Frequency at which new deployments are triggered
• Failure rate - Average number of failures per deployment
• Merges per day - Average number of branches that are successfully merged per day

To view reports, do the following tasks:

1. Click Deployment Manager in the Designer Studio footer.
2. Click a pipeline.
3. Click Actions > View reports.

Deleting an application pipeline

When you delete a pipeline, its associated application packages are not removed from the repositories that the pipeline is configured to use.

1. In the Designer Studio footer, click Deployment Manager.
2. Click the Delete icon for the pipeline that you want to delete.
3. Click Submit.

Viewing, downloading, and deleting application packages in repositories

You can view, download, and delete application packages in repositories that are on the orchestration server.

If you are using Deployment Manager on Pega Cloud, application packages that you have deployed to cloud repositories are stored on Pega Cloud. To manage your cloud storage space, you can download and permanently delete the packages.

1. In the Designer Studio footer, click Deployment Manager.
2. Click the pipeline for which you want to download or delete packages.
3. Click either Development Repository or Production Repository.
4. Click Actions > Browse artifacts.
5. To download an application package, click the package, and then save it to the appropriate location.
6. To delete a package, select the check boxes for the packages that you want to delete and click Delete.