Migrating from Copado to Serpent: a step-by-step playbook

Short answer: you do not need a code freeze, and you are not migrating data. Your metadata already lives in Git, so switching from Copado to Serpent is a control-plane swap: you rebuild the pipeline definition, run both tools side by side for one full release cycle, then let the new pipeline take the production promotion while the old one stays installed as your rollback. Plan around release cycles, not calendar days.

What actually moves, and what does not?

Being precise about this removes most of the fear in the room:

• Nothing has to be migrated. Your source of truth is your Git repository, and it stays exactly where it is, with its history intact.
• What stays behind are the records that only exist inside a managed package: user stories, promotions, deployment records and any automation built on those objects. Copado is installed in your org, so those objects leave when the package does.
• What you rebuild is the pipeline definition: environments and their credentials, stage order, approval rules, quality gates, scheduled jobs and the ticketing integration.

That last list is the entire project. It is configuration work, and it is why this reads as a mapping exercise rather than a migration.

How do Copado concepts map to a Git-native pipeline?

Copado models the release inside Salesforce records. A Git-native pipeline models it in the repository. The translation is close to one-for-one:

• User Story becomes a work item linked to a branch.
• The feature branch per user story stays a feature branch. You can keep the naming convention so history reads continuously.
• Promotion and its promotion branch become a pull request into the next environment branch.
• Deployment record becomes a pipeline run, with its own log, result and rollback point.
• Environment or stage becomes an environment mapped to a branch.
• Back-promotion becomes a merge back down from the higher branch.
• Compliance and quality gates become pull request checks: tests, static analysis, AI code review.

What is the step-by-step runbook?

1. Inventory, one to two days. List every environment, branch, stage, approver, scheduled job, quality gate and integration, with an owner against each. If nobody owns a stage, that is your first finding.
2. Mirror the pipeline, read only. Connect the same orgs and the same repository to Serpent without deploying anything. Connecting takes minutes. Then compare: do both tools agree on what is currently in each environment? Any disagreement is drift you were carrying before the migration.
3. Shadow one release. Every change goes through Copado as usual, and also through the new pipeline into a spare sandbox. Compare the deploy plans. The differences become your findings list, and they are usually about profiles, permission sets and flows.
4. Parallel-run a real release. The new pipeline promotes to UAT, the existing one still takes production. This is the risk-controlled midpoint, and it is where approvers get comfortable.
5. Cut over. The new pipeline runs the production promotion. Leave Copado installed and untouched, because that is your rollback: if the promotion fails, the next release goes back through it.
6. Decommission after two clean releases. Export the history, disable the old scheduled jobs first, then uninstall the managed package in a sandbox before you touch production.

What do you do with user story history?

This is the question that stalls migrations, and the honest answer is: do not try to import it.

• Historical records are only meaningful in the tool that created them. Imported user stories with no live pipeline behind them are decoration, and they will mislead someone in a year.
• Export instead. User stories, promotions and deployments to CSV, with the commit reference wherever one exists. Store it where your other release evidence lives.
• The durable history is Git. Commits, pull requests, merges and tags are the record auditors actually accept, and everything after cutover lands there by default.
• For audit continuity, keep the export plus the commit links. A dated archive and a traceable branch beat screenshots from a decommissioned system.

How do you handle the branch strategy?

Change one thing at a time. The tool changes first, the process later.

Keep your existing branch model for at least the first two releases, even if you intend to simplify it. Long-lived environment branches keep working, promotion branches are replaced by pull requests one for one, and if you want to move toward trunk-based development, do that as a separate exercise after cutover. The one thing to watch during the parallel run is automation collision: disable the old tool's scheduled jobs and auto-merges before the new pipeline starts writing to the same branches.

How do you avoid downtime and a code freeze?

• Freeze the pipeline configuration, not the work. During the parallel run, nobody edits stages, approvals or branch rules in either tool.
• Time the cutover to the start of a sprint, never to the end of one, and never into a release weekend.
• Write the rollback down before you need it. One sentence: if the production promotion fails on the new pipeline, the next one goes through the old tool and both stay connected for one more release.
• Keep both tools connected only for a couple of releases. Two systems writing to the same branches indefinitely is not a safety net, it is a merge conflict with a schedule.

Elapsed time is dominated by release cycles, not by setup. Connecting orgs and repositories is a same-day task, and Serpent onboarding includes a hands-on session for the whole team at no cost, so the pipeline mapping is done with you rather than handed to you as a task. More Salesforce DevOps guides.

FAQ

Do we need a code freeze to switch?

No. The existing tool stays installed and authoritative until the cutover release, so development continues throughout.

Can we keep our Git repository and branch names?

Yes. The repository is untouched, and keeping the existing branch naming makes the history read continuously across the switch.

What happens to our user stories when we uninstall the package?

They go with it, which is why you export them to CSV first. The commits, pull requests and tags in Git remain, and those are the durable audit trail.

How long does the whole migration take?

Think in release cycles: one shadow cycle, one parallel cycle, one cutover cycle. For a standard org-to-org pipeline that is a matter of weeks, most of it waiting for your own releases.

Can we migrate a package or ISV pipeline the same way?

Yes, with one extra cycle. Package versioning, ancestry and subscriber tracking need their own shadow release before you trust the cutover.