JetBrains Space Help

Mirror a GitLab Repository

This page will guide you through the process of creating a synchronized copy of a repository hosted on GitLab.

You can also use it as an example when mirroring a Git repository hosted elsewhere. If your source repository is hosted on GitHub, please see the specific GitHub repository mirroring instruction.

Step 1. Create a repository in Space

To set up a mirror of a remote GitLab repository, you need to create a new Space repository of the type External mirror.

  1. Navigate to the project in which you want to create a repository.

  2. On the project sidebar, choose Repositories.

  3. On the repositories page, click New repository:

    clickNewRepository.png
  4. Select the External mirror tab:

    gitlabExternalMirror.png
  5. Repository name in Space

    Give your Space mirror repository a distinctive name and optional description. The name may not necessarily match your source GitLab repository name.

    In our setup example, let's name it gitlab-mirror:

    gitlabSpaceRepoName.png

Step 2. Set up the connection to your remote GitLab repository

Now, you need to provide Space with your GitLab repository address and configure authentication, so Space can access it.

  1. Remote repository URL

    In GitLab terms, repository is a project. Enter the URL of your GitLab project. In our example it is:

    https://gitlab.com/mygroup1292815/MyProject

    where MyProject is the project (repository) we want to mirror.

    gitlabURL.png
  2. Authentication

    Here you need to specify the authentication method and credentials required to access your GitLab repository. Depending on your GitLab project configuration and access rules, you may need to provide either an SSH key or your username/password. Normally, you can provide the same credentials you use in your Git client to access your GitLab repository from your local machine.

    • Anonymous

      Can be only selected if no credentials are required.

    • Password

      If your GitLab account has two-factor authentication enabled, or you log in to GitLab with third-party credentials (e.g. Google), enter your GitLab personal access token instead of a password.

      For the instructions on how to create and obtain a personal access token, please refer to the GitLab documentation.

    • SSH

      To connect to your GitLab project via SSH, you need to have an SSH key pair generated and stored on your local machine in the .ssh\ subdirectory. Also, the public key should be added to your GitLab account. Then you need to provide the private key to Space by uploading it to the corresponding field and enter the passphrase if your key is protected with one:

      gitlabSSH.png

Step 3. Synchronize your Space mirror with the GitLab repository

In this step we'll make sure our repositories are synced in both directions, so your Space mirror is updated when a change is pushed to the source GitLab repo and vice versa.

gitlabSync.png

Space gives you the following built-in options to sync with a remote repo:

  • Sync periodically — the mirror will be synced with the remote repository and updated approximately once an hour. Actual update frequency may vary as it depends on server load.

  • Sync on git fetch — the mirror will be synced with the remote repository every time someone runs the git fetch command.

  • Remote supports atomic pushes. The git push --atomic option is used when pushing multiple branches to a remote Git server, to ensure that either all the reference updates are accepted, or none of them are. GitLab supports atomic pushes, hence you can keep this option selected.

Set up a webhook for instant updates

While a periodic sync will keep your mirror repository updated, a delay is unavoidable. To have your mirror updated instantly when a change is pushed to the source GitLab repo, you need to set up a webhook on the GitLab side.

  1. In Space, copy the endpoint URL that you'll need to provide to the GitLab webhook later on:

    gitlabWebhookURLSpace.png
  2. In a separate browser tab, log in to GitLab and navigate to your project.

    gitlabWebhookSetup.png
  3. On the project sidebar, choose Settings → Webhooks.

  4. Paste the endpoint address into the URL field.

  5. Select Push events for a Trigger.

  6. These configuration is sufficient for syncing your mirror on a git push. For more specific options refer to the GitLab webhook documentation.

  7. Scroll down the page and click Add webhook.

    Now your Space mirror will be instantly updated each time someone pushes changes to the source GitLab repository.

Mirror selected branches

Tracked branches and tags (Git refspecs) lets you mirror specific branches of the source GitLab repo, while leaving all other branches ignored.

You can do that to fork your Gitlab repository. For example, you mirror your Gitlab repository's main and create local branches off of it in Space:

+refs/heads/main:refs/remotes/origin/main

Then you can push to your branches and keep them updated by rebasing them onto main, all without affecting the source GitLab repository.

To mirror and sync all branches, leave this field blank!

Step 4. Finish the setup

Check that all the information you entered is correct and test the connection to your GitLab repository by clicking the Test connection button.

If the connection is successful, click Create.

A synchronized copy of your GitLab repository will be created and added to your project in Space.

Last modified: 15 May 2023