Shipping Pega applications reliably is less about heroic deploys and more about disciplined branching, automated quality gates, and a repeatable promotion path. Pega's model-driven rules live in a database, not flat files, so the Git-style instincts many developers bring need adapting. This guide explains how branch rulesets, merge-conflict resolution, and Pega Deployment Manager fit together into a modern CI/CD pipeline.
Branches and branch rulesets
In Pega, a branch is an isolated container of rule changes layered on top of one or more base rulesets. When you create a branch, Pega generates a branch ruleset — a special ruleset whose name encodes the branch (for example, MyApp_BranchFeatureX). Any rule you save while a branch is set in your context is created or overridden inside that branch ruleset rather than the base ruleset.
This gives you the two properties you want from a feature branch:
- Isolation — your in-progress changes do not affect other developers working on the base application.
- A clear delta — the branch ruleset is exactly the set of rules you touched, which is what gets reviewed and merged.
You associate one or more branches with your application definition, and you set your active branch in the developer toolbar. Saving a rule then resolves to the branch ruleset automatically.
The branch-based development workflow
A healthy team workflow looks like this:
- Create a branch off the current application for a feature or fix.
- Develop in the branch — every new or modified rule lands in the branch ruleset.
- Lock the branch when development is complete to freeze its contents.
- Run quality gates — branch review, Guardrail compliance, and PegaUnit tests.
- Merge the branch into the target base ruleset and increment the ruleset version.
- Delete the branch once merged so stale branches do not accumulate.
Branch locking
Branch locking prevents further edits to a branch's rules once it is ready for review or merge. Locking is important because a merge operates on a snapshot — if developers keep editing during review, the reviewed delta and the merged delta diverge. Lock the branch, run the gates against the locked snapshot, then merge that exact snapshot.
Pre-merge quality gates
Never merge on faith. Pega supports several gates you should run — ideally automatically — before any branch reaches a base ruleset:
- Branch reviews — a peer (or automated review rule) inspects the branch delta. You can schedule reviews and capture findings against severity thresholds.
- Guardrail compliance — Pega scores rules against best practices and assigns a compliance score. Treat a drop below your team's threshold (commonly the high 90s) as a failing gate. Warnings about unoptimized rules, direct SQL, or excessive Java should be triaged before merge.
- PegaUnit tests — your unit test suite must pass against the branch. A merge that breaks existing tests should be blocked, not merged-then-fixed.
The point of gating before merge is that the base ruleset stays continuously green. A broken base ruleset blocks every other developer, so the cost of a bad merge is collective.
Merging branches and resolving merge conflicts
When you merge, Pega copies the branch's rules into the target ruleset and version. Most merges are clean. A merge conflict arises when the same rule was changed both in the branch and in the base ruleset since the branch was created — Pega cannot silently decide which version wins.
Pega surfaces these in a conflict view during the merge wizard. For each conflicting rule you choose a resolution:
- Keep the branch version — overwrite the base with your branch change.
- Keep the base version — discard the branch change for that rule (you accept the base as-is).
- Skip / resolve manually — exclude the rule and reconcile it in a follow-up.
The safest habit is to rebase early and often: merge the latest base into your branch (or re-create the branch from current base) before the final merge, so conflicts surface while context is fresh rather than at release time. Communicate with teammates about who owns frequently-touched rules (flows, data transforms on shared classes) to minimize collisions in the first place.
Merge wizard — conflict summary (illustrative)
-----------------------------------------------
Branch: MyApp_BranchAddressValidation -> Target: MyApp:01-03-05
Rule Status Resolution
-------------------------------- ---------- -----------------
ValidateAddress (Validate) CONFLICT Keep branch
CustomerRoutingDT (Decision Tbl) CONFLICT Keep base
pyDefault (Data Transform) CLEAN Merge
GetCreditScore (Connect-REST) CLEAN Merge
After resolving, Pega writes the merged rules into the target version and (per your configuration) can delete the branch.
Pega Deployment Manager architecture
Pega Deployment Manager is Pega's CI/CD orchestration product. It coordinates the movement of an application package across environments using a pipeline you define once and run repeatedly. Its core pieces:
- Orchestrator system — the environment where Deployment Manager runs, hosts your pipeline definitions, and drives each stage. It does not host your running application; it commands the others.
- Candidate systems — the actual environments the pipeline promotes through (development, QA, staging, production). The orchestrator triggers builds, tests, and imports on these.
- Repositories — storage locations where the application package (the artifact) is published and retrieved between stages.
- Pipelines — the ordered set of stages, each with its tasks and quality gates, that an artifact flows through from build to production.
This separation means the orchestrator holds the process while candidate systems hold the runtime. You change the pipeline in one place and every environment follows it.
Product rules (RAP) and the application package
The artifact that moves through the pipeline is produced from a product rule — a Rule-Admin-Product, commonly called a RAP (Rule-Admin-Product) or "product file." A product rule declares exactly what to package: which application(s), which rulesets and versions, which data instances (operators, access groups, configuration data), and which classes.
<!-- Conceptual shape of a Rule-Admin-Product (RAP) definition -->
<Product name="MyApp_Deployment" version="01-03-05">
<Applications>
<Application name="MyApp" version="01.03.05"/>
</Applications>
<Rulesets>
<Ruleset name="MyApp" version="01-03-05"/>
<Ruleset name="MyAppInt" version="01-03-01"/>
<Ruleset name="MyAppData" version="01-02-00"/>
</Rulesets>
<DataInstances>
<Instance class="Data-Admin-Operator-ID" filter="pyUserIdentifier like 'svc_%'"/>
<Instance class="Data-Admin-DB-Table"/>
</DataInstances>
</Product>
Getting the RAP right is the difference between a clean deploy and a "works on staging, missing data in production" incident. Be explicit and version-pinned: list ruleset versions exactly, and include the data instances the application needs to run. Keep a single product rule as the source of truth for what ships.
Repository types
Deployment Manager moves artifacts through repositories. Pega supports several backends so you can fit existing infrastructure:
| Repository type | Typical use |
|---|---|
| Pega Platform | Pega-hosted repository on a candidate or dedicated system; simplest to start with |
| File system | A shared filesystem path mounted to the systems; common in locked-down on-prem setups |
| Amazon S3 | Cloud object storage for artifacts; durable and widely used in cloud deployments |
| JFrog Artifactory | Enterprise artifact management when you already standardize on JFrog |
The repository decouples build from deploy: a stage publishes the application package to the repository, and the next stage pulls that exact artifact. This guarantees the binary tested in QA is the same one promoted to production — no rebuild drift.
Pipeline stages and gates
A typical Deployment Manager pipeline promotes one immutable artifact through ordered stages, each enforcing gates. Below is a representative shape — adjust to your governance:
| Stage | Primary tasks | Gates that must pass |
|---|---|---|
| Build | Generate the application package from the RAP; publish to the repository | Branch merged and locked; RAP resolves all rulesets |
| QA | Import artifact to QA; run PegaUnit + scenario tests | All unit/scenario tests green; Guardrail compliance ≥ threshold |
| Staging | Import to a production-like environment; run smoke and integration tests | Smoke tests pass; manual or automated approval; performance check |
| Production | Import artifact to production | Final approval/change-window check; post-deploy health check |
Key principles for the pipeline:
- Fail fast — put the cheapest, most diagnostic gates (compile/RAP resolution, unit tests) earliest so failures surface in seconds, not after a staging import.
- Automate the gates — Guardrail compliance checks and PegaUnit suites should run as pipeline tasks, not as a human remembering to click them.
- Immutable artifact — build once in the Build stage; every later stage imports that same package. Rebuilding per environment reintroduces drift.
- Approvals where they add value — gate production behind an explicit approval or change window, while keeping QA fully automated.
For the branch-level mechanics that feed this pipeline — branch reviews and locking before the Build stage even starts — revisit the workflow earlier in this article, and pair it with disciplined case design and testing so the PegaUnit and scenario suites your pipeline runs are actually meaningful.
Version and ruleset management
Clean CI/CD depends on disciplined versioning. Pega ruleset versions use a three-part NN-NN-NN (major-minor-patch) scheme. Practical rules:
- Lock ruleset versions that have shipped. A locked version is immutable; new work goes into a new minor or patch version. This is what makes "the artifact in production matches the RAP" verifiable.
- Increment deliberately — a feature merge typically bumps the patch or minor version; align the RAP and application version to match.
- Keep integration and data rulesets versioned too, not just the implementation ruleset, so the product rule pins every moving part.
- Avoid skipping versions across environments — promote the same version straight through; do not hand-edit rules directly in staging or production.
Rollback strategy
Even with green gates, plan for rollback. Because Deployment Manager promotes immutable, versioned artifacts, your rollback options are concrete:
- Re-deploy the prior artifact — keep the previous application package in the repository and re-import it to restore the last known-good state quickly. This is the cleanest rollback when the new version is broadly broken.
- Roll forward with a fix — for a small, well-understood defect, a hotfix branch through an expedited pipeline can be faster and safer than reverting an entire release.
- Operator/access fallback — keep the prior access group or application version available so you can repoint users while you remediate.
Whatever the mechanism, rehearse it. A rollback path that has never been executed is a hypothesis, not a safety net. Run a rollback drill in staging as part of onboarding a new pipeline.
Key takeaways
- A branch ruleset isolates your changes and defines the exact delta you will review and merge.
- Follow a disciplined workflow: develop in a branch, lock it, run gates, then merge — and delete stale branches.
- Enforce pre-merge gates: branch reviews, Guardrail compliance, and PegaUnit tests, so the base ruleset stays continuously green.
- Resolve merge conflicts in the conflict view; rebase early to surface collisions while context is fresh.
- Deployment Manager separates the orchestrator from candidate systems, moving an immutable artifact through repositories.
- The product rule (RAP) must explicitly pin rulesets, versions, and required data instances.
- Build a fail-fast, automated pipeline (Build → QA → Staging → Production) with gates at every stage and approvals only where they add value.
- Pin and lock ruleset versions, and rehearse a concrete rollback (re-deploy prior artifact or roll forward with a hotfix).
Want help standing up a Deployment Manager pipeline or untangling a recurring merge-conflict mess on your team? Our Pega mentorship program pairs you with engineers who have built these pipelines end to end — reach out to get started, or explore our certification preparation if you are targeting the CSSA or CLSA credentials.