--- component: ROOT version: "2026.1" slug: ROOT/operations/index canonical_url: "https://docs.gradle.com/develocity/2026.1/operations/migrations/" title: "Migrations" description: "Procedures for migrating Develocity data, storage backends, and deployment environments." keywords: [] status: current --- # Migrations Migrations involve moving Develocity data or services between different environments or storage architectures. Unlike routine administration, migrations are point-in-time events that often require downtime and careful data validation. * * * **Build Cache Access Control Migration** — Migrate Build Cache access control to Develocity. [Build Cache Access Control Migration](https://docs.gradle.com/develocity/2026.1/operations/migrations/build-cache-access-control-migration/) **User-Managed Database Migration** — Migrate from an embedded database to a user-managed database. [User-Managed Database Migration](https://docs.gradle.com/develocity/2026.1/operations/migrations/user-managed-database-migration/) * * * ## Migrating from Embedded to User-Managed Database If your Develocity instance uses the embedded database and you want to move to a user-managed PostgreSQL database (for example, Amazon RDS, Azure Database for PostgreSQL, or a self-managed instance), follow the [User-Managed Database Migration Guide](https://docs.gradle.com/develocity/2026.1/operations/migrations/user-managed-database-migration/). That guide presents several strategies with different trade-offs for downtime and data retention. For installations with a small database, the simplest approach is the [Migrate All Data Up-Front](https://docs.gradle.com/develocity/2026.1/operations/migrations/user-managed-database-migration/#strategy_migrate_all_up_front) strategy, which copies everything in a single step. ## Migrating to Build Scan Object Storage Develocity can store Build Scan data in an external object store (Amazon S3, Google Cloud Storage, or Azure Blob Storage) instead of the database. This is configured through the Helm chart and the Develocity administration interface. For configuration details, see the [Kubernetes Helm Chart Configuration Guide](https://docs.gradle.com/develocity/2026.1/reference/helm-charts/cluster/#helm_config_object_storage) or [Standalone Helm Chart Configuration Guide](https://docs.gradle.com/develocity/2026.1/reference/helm-charts/standalone/#helm_config_object_storage). For guidance on enabling object storage and understanding the trade-offs, see [Build Scan Object Storage](https://docs.gradle.com/develocity/2026.1/administration/build-scan/build-scan-storage/#build_scan_object_storage). > [!NOTE] > Built-in Build Cache entries are stored separately and don’t need to be migrated when changing Build Scan storage backends. Cache entries will be repopulated by running the relevant builds again. ## Migrating from Standalone to Kubernetes If you are moving from a single-host (Standalone) installation to a Kubernetes cluster: 1. **Export Configuration:** Download your current Develocity configuration from the Standalone UI via **Administration**  **Import/Export**  **Export**. This exports your Develocity settings as a declarative YAML file that can be used with [unattended configuration](https://docs.gradle.com/develocity/2026.1/administration/unattended-configuration/). 2. **Plan Your Architecture:** Before setting up the cluster, decide whether to use a [user-managed database](https://docs.gradle.com/develocity/2026.1/installation/kubernetes-installation/#database) and [external object storage](https://docs.gradle.com/develocity/2026.1/administration/build-scan/build-scan-storage/#build_scan_object_storage). These choices affect how you provision the cluster and what storage is required. 3. **Prepare the Cluster:** Set up your Kubernetes cluster following the [Kubernetes Installation Guide](https://docs.gradle.com/develocity/2026.1/installation/kubernetes-installation/). The Helm chart can optionally create the namespace during installation. 4. **Transfer Data:** Migrate your database using the [User-Managed Database Migration Guide](https://docs.gradle.com/develocity/2026.1/operations/migrations/user-managed-database-migration/). 5. **Deploy via Helm:** Use the exported configuration file with your Helm values to deploy Develocity. See [Managing Settings via Unattended Configuration](https://docs.gradle.com/develocity/2026.1/administration/unattended-configuration/) for details on applying exported configuration. ## Technical Considerations * **Downtime:** Most migrations require the application to be stopped (`develocityctl system stop`) to ensure data consistency during the transfer. * **Version Matching:** Ensure the target Develocity instance is running the **exact same version** as the source instance before attempting a data migration. * **Network Latency:** When migrating data between regions or cloud providers, account for transfer time and potential egress costs. > [!TIP] > If you are performing a complex migration involving multiple architectural changes, contact Develocity support to review your migration plan before execution. ## Related * [User-Managed Database Migration](https://docs.gradle.com/develocity/2026.1/operations/migrations/user-managed-database-migration/) * [Migrating Build Scan Data](https://docs.gradle.com/develocity/2026.1/operations/migrations/migrating-build-scan-data/) * [Build Cache Access Control Migration](https://docs.gradle.com/develocity/2026.1/operations/migrations/build-cache-access-control-migration/) * [Restoring from Backup](https://docs.gradle.com/develocity/2026.1/operations/recovery/) * [Managing Settings via GitOps](https://docs.gradle.com/develocity/2026.1/administration/unattended-configuration/) * [Configuring Backup Schedules](https://docs.gradle.com/develocity/2026.1/administration/data-management/database-backups/)