Configure Self Hosted GitLab Repository Mirroring

Introduction

Self hosted GitLab Repository Mirroring is a powerful feature that automatically synchronizes repositories between GitLab and external Git providers. When the destination is AWS services such as AWS CodeCommit, authentication is commonly performed using an AWS IAM user’s Git credentials over SSH.

In this guide, we’ll walk through the process of configuring repository mirroring by generating an SSH key, associating it with an AWS IAM user, and updating GitLab’s mirror credentials through the Rails console.

Prerequisites

Before starting, ensure you have:

• A self-managed GitLab instance
• An AWS account
• An IAM user with permission to access the target Git repository
• SSH access to the GitLab server
• Administrator access to GitLab

Step 1: Generate an SSH Key

Log in to your Linux server and generate a new SSH key pair.

1ssh-keygen -t rsa -b 4096 -C "gitlab-mirror"

This command creates:

• Private key
• Public key

The public key will be uploaded to AWS.

Step 2: Upload the Public Key to the AWS IAM User

• 1
  Open the AWS Management Console.
• 2
  Navigate to IAM.
• 3
  Select the IAM user used for repository access.
• 4
  Open the Security credentials tab.
• 5
  Scroll to AWS CodeCommit SSH keys.
• 6
  Upload the generated public key.

AWS assigns an SSH Key ID similar to:

1APKAEIBAERJR2EXAMPLE

Keep this SSH Key ID. You’ll need it later.

Step 3: Configure Repository Mirroring in GitLab

Create the repository mirror from the GitLab project as usual.

If the mirror was configured with an incorrect SSH Key ID or needs updating, you can modify it directly from the GitLab Rails console.

Step 4: Access the GitLab Rails Console

Locate the GitLab Rails executable:

1which gitlab-rails

Start the Rails console:

1sudo gitlab-rails console

Step 5: Find the Project

Replace the project number with your GitLab project ID.

1project = Project.find(PROJECT_ID)

Example:

1project = Project.find(25)

Retrieve the repository mirror:

1mirror = project.remote_mirrors.first

Step 6: Inspect Mirror Credentials

To understand which methods are available:

1mirror.methods.grep(/credential|user|password|update|save/)

You can also inspect the credentials object:

1mirror.credentials

Step 7: Update the SSH Key ID

The username used for AWS CodeCommit over SSH is the SSH Key ID assigned by AWS, not the IAM username.

Update the mirror with the correct SSH Key ID.

1mirror.credentials.user = "YOUR_AWS_SSH_KEY_ID"

Example:

1mirror.credentials.user = "APKAEIBAERJR2EXAMPLE"

Save the changes:

1mirror.save!

If no errors are returned, the mirror configuration has been updated successfully.

Verify Repository Mirroring

After saving the new SSH Key ID:

• 1
  Open your GitLab project.
• 2
  Navigate to Settings → Repository → Mirroring repositories.
• 3
  Trigger a manual update or push a commit.
• 4
  Verify that synchronization completes successfully.

Common Issues

Authentication Failed

• Verify that the SSH Key ID is correct.
• Ensure the corresponding private key exists on the GitLab server.
• Confirm that the public key uploaded to AWS matches the private key.

Mirror Doesn’t Sync

• Verify the remote repository URL.
• Check GitLab Sidekiq logs.
• Confirm the IAM user has the required AWS CodeCommit permissions.

Permission Denied (publickey)

This usually indicates:

• Incorrect private key
• Incorrect SSH Key ID
• Public key mismatch
• Missing IAM permissions

Best Practices

• Use a dedicated IAM user for Git repository access.
• Rotate SSH keys periodically.
• Grant only the minimum permissions required.
• Test the SSH connection before enabling mirroring.
• Regularly monitor mirror synchronization status in GitLab.

Conclusion

GitLab Repository Mirroring combined with AWS IAM authentication provides a secure and automated way to keep repositories synchronized. By generating an SSH key, uploading the public key to AWS, obtaining the AWS-assigned SSH Key ID, and updating the mirror credentials through the GitLab Rails console, you can quickly resolve authentication issues and maintain reliable repository synchronization.

This approach is especially useful when an SSH Key ID changes or an existing mirror needs to be updated without recreating the entire mirror configuration.