CI/CD server migration playbook: moving platforms without losing control

Moving to a new CI/CD platform means rebuilding the most privileged system in software delivery, and the risk sits less in the pipelines themselves than in the secrets, deploy credentials, runners and approval rules that have to be recreated on the other side. Organisations change CI/CD server when a self-hosted build server reaches end of support, when they consolidate onto the CI built into their source control platform, after a merger, or when they move from self-hosted to a hosted service. This playbook covers the migration itself: what has to move, how to translate pipelines without carrying old weaknesses across, how to rebuild credentials as short-lived federated identities, how to run the old and new platforms side by side, and how to decommission the old server so nothing it held stays usable. It is vendor-neutral and draws on NIST SP 800-204D, the CISA and NSA guidance on defending CI/CD environments, the OWASP Top 10 CI/CD Security Risks and SLSA. Day-to-day hardening is in the CI/CD Security Guide; this page is about the move.

Key takeaways

• Inventory credentials before pipelines. Every secret, deploy key and cloud credential stored in the old server is in scope; list them with their owners and targets before any job is translated.
• Do not copy secrets, reissue them. Treat the migration as the moment to replace static credentials with federated, short-lived ones, and rotate whatever must stay static as it moves.
• Translate by intent, not syntax. Automated converters move job steps but not branch filters, approval gates, fork protections or runner isolation, which are where the security lives.
• Run in parallel with one deployer. Both platforms can build during the overlap, but only one should hold production deploy rights for a given application at any time.
• Decommission is a security task. The old server's disk, backups, plugin stores and logs contain credentials; revoke at the target systems, archive what you must keep, then sanitise.

What a CI/CD migration actually moves

NIST SP 800-218 (SSDF) task PS.3.1 asks organisations to securely archive the files and supporting data, including integrity verification and provenance data, for each software release. If the old server is the only place that records which commit produced which release, archive that before anything is switched off.

Credentials: inventory, reissue, revoke

The CISA and NSA information sheet on defending CI/CD environments recommends minimising long-term credentials, using temporary and ephemeral credentials for software, and referencing secrets indirectly through the CI/CD tool's secrets manager rather than embedding them. A migration is the cheapest moment to apply that, because every credential has to be touched anyway.

1. Extract the inventory: list every secret, credential and connection object in the old server with the jobs that reference it. Unreferenced secrets are candidates for revocation, not migration.
2. Find secrets outside the vault: scan job definitions, build scripts, logs and archived artefacts for embedded credentials. See How to find secrets in CI logs and build artefacts.
3. Reissue at the target system: for each credential, create a new one at the cloud, registry or service it grants access to, and store it in the new platform. Do not export the old value.
4. Scope by environment: production deploy credentials should be available only to jobs running from protected branches through an approval gate. See How to Audit CI/CD Secrets Scope.
5. Revoke the old credential at its source: after the application has deployed successfully from the new platform, revoke the old key at the cloud or service, not just in the old server.

The CircleCI breach showed why this matters: when the platform holding customers' CI secrets was compromised, every stored secret had to be treated as exposed and rotated. A migration that copies static secrets across leaves the same blast radius in two places.

Translating pipelines without carrying weaknesses across

Automated converters translate step syntax, but the controls OWASP lists in its CI/CD Top 10 live mostly outside the steps: flow control (CICD-SEC-1), identity and access (CICD-SEC-2), pipeline-based access controls (CICD-SEC-5), credential hygiene (CICD-SEC-6) and system configuration (CICD-SEC-7). Review each translated pipeline for these, not only for whether it builds.

• Untrusted contributions: NIST SP 800-204D recommends preventing untrusted forks from running privileged CI, by sandboxing those workflows or requiring maintainer approval for outside contributors, set to the strictest level. Check that the target's equivalent setting is on before importing public repositories.
• Pipeline definition changes: whoever can edit a pipeline file can run code with its credentials (poisoned pipeline execution, OWASP CICD-SEC-4 and MITRE ATT&CK T1677). Protect pipeline files with code owner review in the target.
• Third-party steps: pin plugins, actions and shared templates to a commit or digest. See the guide to pinning third-party CI steps to commit SHAs for the pattern on one platform.
• Job token permissions: set the default per-job token to read-only and grant write per job. See the guide to restricting per-job token permissions.
• Separation of duties: CISA and NSA advise that developers should not update build environments and build engineers should not have read-write source access. Recreate that split in the target's roles.
• Two-person rule: require a second reviewer for changes to protected branches and pipeline definitions; NIST SP 800-204D adds that approvers should not approve their own merges.

Runners and build agents

Old build agents are often the most neglected part of a CI estate: persistent machines with tools installed by hand, cached credentials in home directories, and network routes to production. Do not re-register them with the new platform.

• Ephemeral by default: CISA and NSA recommend destroying temporary test resources after each pipeline run. Use runners that start clean for each job and are destroyed after it.
• Separate trust levels: keep runners for untrusted pull request builds apart from runners that hold deploy credentials, with no shared cache between them. SLSA Build L3 requires that build runs cannot influence one another and that provenance signing secrets are not accessible to user-defined build steps.
• Network egress: restrict runner egress to the registries, package mirrors and deployment targets they need.
• Hardened image: build the runner image in a pipeline, scan it, and version it, so the build environment itself is reproducible.

Detail is in the Self-hosted CI/CD Runners and Build Agents guide.

Signing and provenance continuity

Consumers verify releases against keys and provenance produced by the old platform. If the new platform signs differently, verification breaks or, worse, gets switched off.

• Publish before you switch: add the new signing identity or public key to every verifier and admission policy before the first release from the new platform.
• Keep old verification material: releases signed by the old platform must stay verifiable. NIST SP 800-218 PS.2.1 asks producers to make integrity verification information available to acquirers.
• Raise the provenance level, do not lower it: SLSA Build L2 requires a hosted build platform and signed provenance; Build L3 adds isolated runs and signing secrets kept from build steps. Record the level each pipeline reaches on the old and new platforms, and do not accept a regression.
• Signing keys stay in the key service: NIST SP 800-204D recommends HSMs for online signing keys and signing only artefacts that pass policy. Point the new pipeline at the same key service, or issue a new key, rather than exporting key files.

See the Code Signing Security Guide.

Where identity fits

A CI/CD platform is a concentration of non-human identities: job tokens, deploy roles, registry credentials, app installations on source control and API keys for every integrated tool. The migration creates new ones and should end with fewer.

• Federate deploy identities: each pipeline gets a cloud role with trust conditions on repository, branch and environment. See the OIDC federation hardening guide for CI pipelines for the pattern.
• Integration identity for the platform: the new platform's connection to source control is a privileged app identity; scope it to the repositories it builds.
• Migration operator accounts: people running the migration often get platform administrator rights; time-box them and remove them at sign-off.
• Owners for every credential: reissued credentials get a named owner and an expiry in the inventory.

The wider model is in the CI/CD Pipeline Identity Security Guide.

The phased playbook

1. Inventory: pipelines, shared libraries, plugins, runners, secrets, deploy targets, webhooks, approval gates and integrations, each with an owner. Mark which pipelines deploy to production.
2. Design the target baseline: organisation-level defaults for job token permissions, fork protections, protected branches, environments with approvals, runner groups by trust level, and federation for cloud access. Write it as configuration so it can be checked.
3. Pilot: migrate one low-risk application end to end, including a production deployment through an approval gate, a deliberate failed approval, and a rollback deployment.
4. Migrate in waves: lowest-risk repositories first, production-critical and widely shared pipelines last. For each application: translate, review, build in parallel, compare artefacts, then switch deploy rights.
5. Compare outputs: during the parallel period, compare artefact digests or test results from both platforms for the same commit. Differences show missing steps or environment drift.
6. Cut over deploy rights: for each application, enable deployment from the new platform and disable it in the old one in the same change. Revoke the old deploy credential at the target.
7. Freeze the old server: make it read-only, disable triggers and remove its webhooks from source control. Keep it available for reference until the retention decision is made.
8. Decommission: archive build history and audit logs, revoke every credential it held at the source, delete its source control app or service accounts, then sanitise disks and backups following NIST SP 800-88.

Rollback: until the old server is frozen, rollback for an application means re-enabling its old pipeline and deploy credential. Keep that path for each wave until the new platform has made at least one production release and one rollback deployment for the application (our recommendation). After revocation, rollback means reissuing credentials, so do not revoke until the wave is signed off.

Small and large estates: a team with a few dozen pipelines can often translate and cut over in a single planned window per application. Large estates need the wave model, a tracking sheet per pipeline, and a platform team that owns shared templates so that fixes land once.

Detection and measurement

Monitor the cloud and registry audit logs for the old credentials as well as the CI logs: the signal that matters is use of a credential at its target, wherever it came from. NIST SP 800-204D recommends real-time monitoring of CI/CD servers for exfiltration or build tampering; keep logs from both platforms in one place until decommission. See OWASP CI/CD Top 10 CICD-SEC-10 Insufficient Logging and Visibility Guide.

Common failure patterns

• Bulk secret export: a script dumps every secret from the old server into the new one, unchanged and unreviewed, and a plaintext export file is left on a laptop.
• Converter-only migration: pipelines build in the target, but fork protections, approval gates and branch filters were never recreated, so pull requests from outside contributors run with deploy credentials.
• Old agents re-registered: persistent build machines with cached cloud credentials join the new platform and keep their old access.
• Revoked in the vault, not at the source: the secret is deleted from the old server but the key remains valid at the cloud provider. Leaked CI scripts and credentials can then still be used, as the Codecov breach showed for secrets harvested from CI environments.
• Two deployers: both platforms can deploy the same application, so a compromise of the forgotten one still reaches production.
• Server left running: the old CI server is "kept just in case", unpatched, with all its credentials and plugins still loaded.

Framework mapping

Practitioner checklist

• Inventory pipelines, plugins, runners, secrets, deploy targets and webhooks with owners.
• Archive release history, provenance and audit logs before anything is switched off.
• Reissue credentials at their source; replace cloud keys with workload identity federation.
• Set target defaults: read-only job tokens, fork protections, protected pipeline files, approval gates.
• Build new ephemeral runners separated by trust level; never re-register old agents.
• Pin third-party plugins and steps to commits or digests after re-evaluating each one.
• Publish new signing identities to verifiers before the first release from the new platform.
• Allow only one platform to deploy each application at any time.
• Revoke old credentials at the cloud, registry or service, and alert on any later use.
• Freeze, archive and sanitise the old server on a dated plan.

Standards and references

• NIST: SP 800-204D, Strategies for the Integration of Software Supply Chain Security in DevSecOps CI/CD Pipelines
• CISA and NSA: Defending Continuous Integration/Continuous Delivery (CI/CD) Environments
• NIST: SP 800-218, Secure Software Development Framework (SSDF) Version 1.1
• OWASP: Top 10 CI/CD Security Risks
• OpenSSF: SLSA v1.0 Security Levels
• MITRE ATT&CK: Poisoned Pipeline Execution
• NIST: SP 800-53 Rev. 5, Security and Privacy Controls
• NIST: Cybersecurity Framework 2.0

Related NHI Mgmt Group resources: CI/CD Security Guide · CI/CD Pipeline Compromise Playbook · AI Coding Agents Security Guide · Source control platform migration playbook · Artefact and container registry migration playbook