Create Project-mirroring.md

Project-mirroring.md

@@ -0,0 +1,84 @@
+# How to Transfer GitLab Projects from One GitLab Instance to Another
+
+## Step 1: Preparation
+1. **Access Rights**:
+   - Ensure you have sufficient access rights (Owner or Maintainer) to the project in the source GitLab instance.
+   - Ensure you have access to create repositories in the destination GitLab instance.
+
+2. **GitLab Versions**:
+   - Confirm both GitLab instances are compatible. Ideally, they should be on the same or a close version to avoid issues during import/export.
+
+3. **Check for Features**:
+   - Identify features that won't transfer, such as CI/CD configurations, runners, or container registry content. Plan to recreate these in the destination.
+
+4. **Install Git**:
+   - Ensure Git is installed on your local machine.
+
+---
+
+## Step 2: Export the Project from Source GitLab
+1. **Go to the Source GitLab Instance**:
+   - Navigate to the project you want to transfer.
+
+2. **Export the Project**:
+   - In the project’s settings, go to **Settings > General > Advanced**.
+   - Scroll to the **Export project** section and click **Export project**.
+   - GitLab will create a downloadable `.tar.gz` file containing all the project data (code, issues, merge requests, and more).
+
+3. **Download the Export File**:
+   - Once the export is complete, download the file from the provided link.
+
+---
+
+## Step 3: Import the Project to Destination GitLab
+1. **Go to the Destination GitLab Instance**:
+   - Log in to the destination GitLab instance.
+
+2. **Create a New Project**:
+   - Go to **Projects > New project**.
+   - Select **Import project** and choose **GitLab Export**.
+
+3. **Upload the Export File**:
+   - Upload the `.tar.gz` file you downloaded from the source GitLab instance.
+
+4. **Verify the Imported Project**:
+   - Check if all the contents, issues, and merge requests are present in the destination project.
+
+---
+
+## Step 4: Manually Handle Non-Exportable Items
+- Some items may not transfer and need manual setup:
+  - **CI/CD Configurations**: Copy `.gitlab-ci.yml` and validate pipelines on the destination.
+  - **Runners**: Configure runners in the destination GitLab.
+  - **Container Registry**: If using a container registry, push images manually:
+    1. Pull images from the source using `docker pull`.
+    2. Tag and push images to the destination registry using `docker tag` and `docker push`.
+
+---
+
+## Step 5: Validate and Test
+1. Clone the new project from the destination GitLab to your local machine:
+   ```bash
+   git clone https://destination-gitlab-instance.com/username/project-name.git
+2. Verify that the codebase, issues, and pipelines are intact.
+
+## Step 6: Update Remote Repository on Local Clones
+- If you or other team members have cloned the project locally, update the remote URL:
+```bash
+git remote set-url origin https://destination-gitlab-instance.com/username/project-name.git
+```
+
+## Optional: Using Command Line for Repository Transfer
+If you only need the Git repository without issues or CI/CD:
+1. Clone the repository from the source:
+```bash
+git clone --mirror https://source-gitlab-instance.com/username/project-name.git
+```
+2. Push it to the destination:
+```bash
+cd project-name.git
+git push --mirror https://destination-gitlab-instance.com/username/project-name.git
+```
+
+## For Gitlab admins:
+The previous steps can be followed, additionally the namespace of the project can be changed here: **Settings > General > Advanced**.