One-step import

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

Use the one-step import method if you regularly run offline garbage collection. This method is a simpler operation compared to the three-step import method.

One-step import

Warning

The registry must be shut down or remain in read-only mode during the import. Otherwise, data written during the import becomes inaccessible or leads to inconsistencies.

GitLab 18.7 and later

Ensure the database is disabled in the registry['database'] section of your /etc/gitlab/gitlab.rb file:
```
registry['database'] = {
  'enabled' => false, # Must be false!
}
```

Ensure the registry is set to read-only mode.

Edit your /etc/gitlab/gitlab.rb and add the maintenance section to the registry['storage'] configuration. For example, for a gcs backend registry using a gs://my-company-container-registry bucket, the configuration could be:

## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => true # Must be set to true.
    }
  }
}

Save the file and reconfigure GitLab.
Apply database migrations.

Run the following command:

sudo gitlab-ctl registry-database import --log-to-stdout

If the command completed successfully, the registry is fully imported. You can enable the database, turn off read-only mode in the configuration, and start the registry service:

registry['database'] = {
  'enabled' => true, # Must be enabled now!
}

## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => false
    }
  }
}

Save the file and reconfigure GitLab.

GitLab 18.3 to 18.6

Ensure the database is disabled in the registry['database'] section of your /etc/gitlab/gitlab.rb file:
```
registry['database'] = {
  'enabled' => false, # Must be false!
}
```

Ensure the registry is set to read-only mode.

## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => true # Must be set to true.
    }
  }
}

Save the file and reconfigure GitLab.
Apply database migrations.

Run the following command:

sudo -u registry gitlab-ctl registry-database import --log-to-stdout

If the command completed successfully, the registry is fully imported. You can enable the database, turn off read-only mode in the configuration, and start the registry service:

registry['database'] = {
  'enabled' => true, # Must be enabled now!
}

## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => false
    }
  }
}

Save the file and reconfigure GitLab.

GitLab 17.5 to 18.2

Prerequisites:

Create an external database.

Add the database section to your /etc/gitlab/gitlab.rb file, but start with the metadata database disabled:

registry['database'] = {
  'enabled' => false, # Must be false!
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # Default, but set to the port of your database instance if it differs.
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # See the PostgreSQL documentation for additional information https://www.postgresql.org/docs/16/libpq-ssl.html.
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}

Ensure the registry is set to read-only mode.

Edit your /etc/gitlab/gitlab.rb and add the maintenance section to the registry['storage'] configuration. For example, for a gcs backed registry using a gs://my-company-container-registry bucket, the configuration could be:

## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => true # Must be set to true.
    }
  }
}

Save the file and reconfigure GitLab.
Apply database migrations if you have not done so.

Run the following command:

sudo gitlab-ctl registry-database import

If the command completed successfully, the registry is now fully imported. You can now enable the database, turn off read-only mode in the configuration, and start the registry service:

registry['database'] = {
  'enabled' => true, # Must be enabled now!
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # Default, but set to the port of your database instance if it differs.
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # See the PostgreSQL documentation for additional information https://www.postgresql.org/docs/16/libpq-ssl.html.
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}

## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => false
    }
  }
}

Save the file and reconfigure GitLab.

You can now use the metadata database for all operations!

After import

Large registries can have hundreds of thousands or even millions of blobs queued for garbage collection review after an import. This is expected, and at default worker intervals it takes time to process.

For guidance on what to expect and how to speed up processing, see:

Post import for an overview of expected behavior after completing an import.
Check the health of online garbage collection to monitor the garbage collection review queues.
Adjust the garbage collector worker interval to temporarily speed up processing for large backlogs.