Alibaba Cloud DevOps:Migrate a Self-Hosted GitLab Instance to an Apsara DevOps Region Site

Migration Preparation

Before you begin, ensure that the Codeup CLI tool is installed and running correctly. The tool supports the migration of the following data:

• Git repository data: source code, branches, commits, and tags.

• Basic repository settings: only the repository description and default branch setting.

• Protected branch rules: only the branch name, roles allowed to push, and roles allowed to merge.

• Ongoing merge requests: Only ongoing merge requests are migrated. Closed historical records are not migrated.

• Repository member permissions: GitLab users are mapped to Codeup repository users based on your configured user mapping rules. These users are then added as members to the corresponding Codeup repository.

• Configured webhooks: GitLab project webhooks are synchronized to the corresponding Codeup repository.

After you install and verify the tool, follow the migration plan below:

1. Before you migrate production repositories, run a trial migration on non-production repositories. Verify that your configuration is correct before you start the production migration.

2. Pause all write operations to your self-hosted GitLab instance during the migration. If you repeat the migration, new content is not synchronized after the repository migration succeeds.

Step 1: Define the Migration Configuration File

1. Run the following command to initialize the configuration file:

   ./codeup-cli init

   If the command is successful, the output is similar to the following:

   demo:workspace my$ ./codeup-cli init
   【Success】 Initialized config.yaml at /Users/my/config.yaml. Fill in the configuration as described in the help documentation.

2. Open the config.yaml file from the path shown in the output. Configure the following parameters. You can choose either HTTP or SSH cloning and delete the fields that you do not need.

   source — Source Platform Parameters

   Parameter	Required	Description
   platform	Required	Enter "gitlab".
   apiEndpoint	Required	The API root URL of your self-hosted GitLab instance, such as https://gitlab.example.com. If the API returns 404, try adding /api/v4, for example https://gitlab.example.com/api/v4.
   accessToken	Required	Your GitLab personal access token. Select the read_user, read_repository, and read_api scopes. To map users by email, also enable admin_mode.
   username	Required for HTTP cloning	Your GitLab username for HTTP cloning.
   password	Required for HTTP cloning	Your GitLab password or token for HTTP cloning.
   localSSHKeyPath	Required for SSH cloning	The full local path to the private key that matches your GitLab SSH public key, such as /Users/my/.ssh/id_rsa.

version: "v2"

import:
  source:
    platform: "gitlab"
    apiEndpoint: "https://gitlab.example.com"
    accessToken: "glpat-xxxxxxxx"
    localSSHKeyPath: "/Users/my/.ssh/id_rsa"
  target:
    # Region site URL format: https://{orgIdentifier}-{regionId}.devops.aliyuncs.com
    host: "https://myorg-cn-shanghai.devops.aliyuncs.com"
    accessKey: "pt-xxxxxxxx"
    localSSHKeyPath: "/Users/my/.ssh/id_rsa"
  # projectListPath points to the projects.csv file generated in Step 4
  projectListPath: "/Users/my/workspace/projects.csv"
  # workDir specifies the working directory for migration. The tool cleans it up after migration.
  workDir: "/Users/my/workspace"
  # User mapping configuration (optional; defaults shown)
  memberMapping:
    enable: true
    registerIfNotFound: true
    mappingPriority: ["email", "username"]

Step 2: Define the Migration Repository Scope

Run the following command to analyze all repositories in GitLab and generate the scope configuration file:

./codeup-cli import --gen project --config=./config.yaml

After you run the command, the tool creates a projects.csv file at the path specified in projectListPath. The file uses the following format, with one record per line:

# GitLab repository path (without domain), Codeup repository path, Codeup repository visibility
groupname/demo,groupname/demo,10
group/subgroup/repo,group/subgroup/repo,0

Repository visibility:

• 0 means private.

• 10 specifies internal visibility, which means the repository is visible to members of your organization. Any non-zero value that you enter is automatically converted to 10.

You can manually edit this file to add or remove repositories for the migration.

Step 3: Configure User Mapping

The tool maps users automatically. You do not need to prepare a mapping file. For more information about the parameters, see memberMapping Configuration.

import:
  # ... other settings
  
  # Disable member migration
  memberMapping:
    enable: false
  
  # Or: Enable member migration but skip unmatched users
  memberMapping:
    enable: true
    registerIfNotFound: false
  
  # Or: Map only by username
  memberMapping:
    mappingPriority: ["username"]
  
  # Or: Try username first, then email
  memberMapping:
    mappingPriority: ["username", "email"]

Step 4: Run the Migration

Ensure that your configuration file and working directory (such as the custom workDir) are ready. Then, run the following command:

./codeup-cli import --run true --config=./config.yaml
# The tool shows migration details. Errors appear if issues occur.

Note:

• If the Git data migration fails, the repository status is marked as failed. Failures for related items, such as member permissions, protected branches, or webhooks, generate only warnings and do not block the import process.

• If you run the import again, successfully imported repositories are skipped. You can retry the migration for failed repositories.

After the migration is complete, go to the Codeup organization to confirm the migration by viewing the migrated repositories and member information.

Regions Supported by Region Sites

FAQ