Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Domain Migration

Migrate Code Ocean user accounts and capsule Git integrations from one email domain or Git organization to another.

Overview

When an organization changes its name, it often needs to change the email domain used by its identity provider and, in some cases, the organization hosting its external Git repositories. Because Code Ocean user accounts are keyed by email address and capsules reference external Git repositories by URL, these changes require a coordinated data migration on the Code Ocean VPC deployment.

Code Ocean ships two co-admin subcommands to perform this migration safely from an SSM session on the services instance:

  • co-admin migrate-user-emails — rewrites user email addresses in the Code Ocean database and resets their SSO identity bindings.

  • co-admin migrate-git-repos — rewrites the external Git repository URL on capsules that are linked to external Git.

Both commands accept a CSV mapping file and support a -d (dry-run) flag so you can validate the change set before applying it.

Domain migration directly modifies Code Ocean's persistent data. Coordinate with Code Ocean support before running it in a production deployment, take a manual backup beforehand, and schedule a maintenance window — users will be signed out when their emails are migrated.

When to Use

Run the user email migration when users' email addresses are moving to a new domain (for example, after a company rename) and the existing accounts must be preserved along with their owned capsules, data assets, pipelines, and computation history. Run the git repository if, additionally, external Git repositories referenced by existing capsules are moving to a new Git organization and must be relinked without losing per-capsule Git history.

What the Migration Changes

Email migration

For every user matched by the source email in the mapping file, migrate-user-emails:

  • Updates the user's email field to the target address.

  • Resets the user's SSO identity binding, including their list of assumable roles.

  • Invalidates all active login sessions.

After the migration, migrated users must sign in again. Once they do, their SSO identity is re-established and their assumable-role mappings are re-populated.

Git migration

For every capsule whose cloned_from_url matches a source URL in the mapping file, migrate-git-repos:

  • Rewrites cloned_from_url to the target URL.

  • Enforces https:// as the URL scheme. Target URLs with any other scheme (for example, ssh:// or git@…) are rejected and the migration aborts.

Only capsules linked to external Git are updated.

Prerequisites

1

Ensure a password-based admin sign-in is available

If Code Ocean's SAML SSO or OIDC configuration will need to be reconfigured during or after the migration (for example, to point at a new Identity Provider tenant), at least one administrator must be able to sign in with a username and password while SSO is disabled.

2

Prepare the CSV mapping files

Prepare a comma-delimited file for each migration you plan to run. Each row maps one source value to one target value. No header row.

Both addresses must be syntactically valid email addresses. The migration will abort on any invalid row.

Example (email-mapping.csv):

URLs may be specified with or without an https:// scheme and with or without a trailing .git; the tool normalizes both. Prepare the target repositories in the new Git organization in advance so the rewritten URLs resolve successfully after the migration.

Example (git-mapping.csv):

3

Pause SCIM provisioning

If your deployment uses SCIM provisioning — see Azure AD or Okta — pause the sync before starting the migration and leave it paused until after the migration has been verified. This prevents the IdP from re-creating users under their old emails or reverting group-to-role mappings while the migration is in progress.

Resume SCIM provisioning against the new IdP groups after verification.

4

Take a manual backup

Follow Backup and restore → Manual backup to generate on-demand EBS and RDS snapshots before starting. This gives you a clean rollback point if any step needs to be reversed.

Procedure

1

Switch to built-in authentication only

From the Admin Panel, switch the authentication method to Built-in authentication. This blocks the SSO sign-in path while the migration is in progress and preserves a username-and-password sign-in path for administrators, which is required after the migration because migrate-user-emails clears SSO identity bindings. See Authentication → Reverting to Built-in Authentication.

This operation clears the current SSO configuration. If you intend to reuse the existing SSO configuration after the migration, record its values (Single Sign-on URL, Entity ID, X.509 certificate, or OAuth client ID and secret) before switching.

2

Enable maintenance mode

From the Admin Panel, click System Maintenance and then Enable Maintenance Mode. This blocks user activity, stops running computations, drains AWS Batch jobs, and terminates worker instances, ensuring no capsule is actively syncing with an external Git repository while URLs are being rewritten. See Enable Maintenance Mode.

Wait for the maintenance-mode steps to complete before proceeding.

While maintenance mode is enabled, the Admin Panel is not available for the verification checks later in this procedure. Maintenance mode is therefore disabled again after the CLI steps and before verification.

3

Connect to the services instance

Start an AWS Systems Manager (SSM) session into the Code Ocean services EC2 instance and switch to the root user:

4

Upload the CSV mapping files

Copy email-mapping.csv and git-mapping.csv to /tmp on the services instance.

5

Dry-run the email migration

Review the output to confirm that every expected user is listed and that the target email addresses are correct. The dry run does not modify the database.

6

Apply the email migration

The tool reports the number of users that were updated. Any active sessions and personal access tokens for those users are invalidated as part of the update.

7

Dry-run the Git repository migration

Skip this and the next step if no capsules are linked to external Git repositories that are moving.

Review the output to confirm the set of capsules whose Git URLs will change.

8

Apply the Git repository migration

9

Disable maintenance mode

Click Disable Maintenance Mode in the web application to take the system out of maintenance mode so the Admin Panel is reachable again for verification.

Alternatively, on the services instance, run:

10

Verify the migration

  1. Sign in as an administrator using the new email address and a password (built-in authentication).

  2. In the Admin Panel, open User Management and confirm the list of users reflects the new email addresses.

  3. If Git migration was performed, open a capsule that was linked to a migrated external Git repository.

    • The Git provider icon next to the capsule's title points to the new repository.

    • Clicking Check for Updates in the capsule timeline completes without an error.

11

Reconfigure and re-enable SSO

Re-enable SAML SSO or OIDC from the Admin Panel, updating the Identity Provider configuration if the IdP tenant has also changed. See Authentication → Configuring SAML SSO or Configuring OpenID Connect (OIDC).

Ask each migrated user to sign in once. The first SSO sign-in re-binds their Code Ocean account to their new IdP identity.

12

Resume SCIM provisioning

Resume SCIM sync, pointed at the new IdP groups. On the next sync, assumable-role mappings are re-populated for migrated users.

Related Pages

PreviousCloud-Init Extension PointsNextTroubleshooting Guide

Last updated

Was this helpful?