Removing a Mirror Repository

Step-by-step guide for removing a kernel.org mirror from GitLab

This document provides explicit instructions for removing a kernel.org repository mirror from GitLab. It is designed to be followed by both humans and AI systems with minimal interpretation required.

Automation Note

This document has three phases, each ending with a verification step or merge request. When following as an AI agent:

  • Execute steps within a phase without asking for confirmation
  • STOP at the end of each phase when you see STOP: Human action required
  • Report the MR URL and wait for the user to confirm the merge before continuing
  • Only proceed to the next phase after the user confirms the previous step is complete

Overview

CKI maintains mirrors of kernel.org repositories on GitLab. When a mirror is no longer needed (e.g., upstream repository moved, maintainer tree retired, or consolidation), it should be properly removed. The mirrors are configured at:

The process has three phases:

  1. Phase 1: Update mirrors.yml - Remove the repository URL from the mirror list
  2. Phase 2: Deploy configuration - Apply the updated mirroring configuration
  3. Phase 3: Archive GitLab repository - Archive or delete the mirror repository

Input Parameters

The process requires the following parameters:

  • {googlesource_url}: The googlesource URL of the mirror to remove (e.g., https://kernel.googlesource.com/pub/scm/linux/kernel/git/netdev/net.git)
  • {issue_url}: URL to the GitLab issue or Jira ticket tracking this work
  • {pipeline_data_repo_path}: Path to the pipeline-data repository (e.g., ../pipeline-data)
  • {pipeline_data_fork_remote}: Git remote name for your pipeline-data fork
  • {deployment_all_repo_path}: Path to the deployment-all repository (internal, e.g., ../deployment-all)

Prerequisites

Before starting, verify the following:

1. Issue URL

You must have a GitLab issue or Jira ticket URL to associate with this work.

Verification: Confirm {issue_url} has been provided.

  • If provided: Proceed to next prerequisite.
  • If NOT provided: STOP and ask the user for the issue URL before continuing.

2. Repository is Currently Mirrored

Check that the repository exists in the mirrors list.

Verification command:

grep -F "{googlesource_url}" {pipeline_data_repo_path}/mirrors.yml

Success criteria: Returns the URL (repository is in the list).

  • If output shows URL: Proceed to next prerequisite.
  • If output is empty: STOP - repository is not currently mirrored.

3. Pipeline-data Fork Setup

You need a fork of the pipeline-data repository with remotes configured.

Verification command:

cd {pipeline_data_repo_path} && git remote -v && cd -

Identify your fork remote: Look for a remote pointing to your personal fork. Note this remote name as {pipeline_data_fork_remote}.

4. GitLab Access

You need maintainer access to the mirror group on gitlab.com.

Verification: Confirm you can access https://gitlab.com/redhat/red-hat-ci-tools/kernel/mirror.

5. Confirm Removal is Safe

Before removing a mirror, ensure no active pipelines or webhooks depend on it.

Considerations:

Phase 1: Update mirrors.yml

This phase removes the repository URL from the mirrors list in pipeline-data.

1.1 Remove URL from mirrors.yml

File: {pipeline_data_repo_path}/mirrors.yml

Location: Find the source_urls: list.

Action: Remove the line containing the googlesource URL.

Example removal:

source_urls:
  # ... existing entries ...
  # REMOVE this line:
  # - https://kernel.googlesource.com/pub/scm/linux/kernel/git/example/repo.git
  # ... existing entries ...

1.2 Verify the URL was Removed

Verification command:

grep -F "{googlesource_url}" {pipeline_data_repo_path}/mirrors.yml

Success criteria: Returns no output (URL removed).

1.3 Create and Submit Merge Request

Extract a short repository name from the URL for branch naming (e.g., netdev-net from .../netdev/net.git).

cd {pipeline_data_repo_path}
git checkout main && git pull
git checkout -b remove-mirror-{repo_name}
git add mirrors.yml
git commit -m "mirrors: remove {repo_name} repository

{issue_url}"
git push \
    -o merge_request.create \
    -o merge_request.target=main \
    -o merge_request.title="mirrors: remove {repo_name} repository" \
    -o merge_request.description="Related issue: {issue_url}" \
    {pipeline_data_fork_remote} remove-mirror-{repo_name}
cd -

Success criteria: MR is created.

STOP: Human action required

The pipeline-data MR must be reviewed and merged before proceeding.

Report the MR URL to the user and wait for confirmation that it has been merged.

Phase 2: Deploy Configuration

After the mirrors.yml MR is merged, deploy the gitlab-repo-config to update the mirroring configuration. This disables the pull mirroring for the removed repository.

2.1 Deploy Configuration

cd {deployment_all_repo_path}
git checkout main && git pull
REPOS=cki ./gitlab-repo-config/deploy.sh
cd -

2.2 Verify Mirroring is Disabled

Verification command:

REPO_PATH=$(echo "{googlesource_url}" | sed 's|https://kernel.googlesource.com/pub/scm/||' | sed 's|\.git$||')
curl -s "https://gitlab.com/api/v4/projects/redhat%2Fred-hat-ci-tools%2Fkernel%2Fmirror%2F${REPO_PATH//\//%2F}" | jq -r '.mirror'

Success criteria: Returns false (mirroring disabled).

STOP: Human action required

Verify the mirroring was disabled for the repository.

Report the verification result to the user and wait for confirmation before proceeding to archive.

Phase 3: Archive GitLab Repository

After mirroring is disabled, archive the GitLab repository to indicate it is no longer active. Archiving preserves the repository for historical reference while preventing accidental use.

3.1 Archive the Repository

Option A: Using GitLab Web UI (Recommended)

  1. Navigate to the mirror repository on GitLab
  2. Go to Settings → General → Advanced
  3. Click “Archive project”
  4. Confirm the action

Option B: Using GitLab API

REPO_PATH=$(echo "{googlesource_url}" | sed 's|https://kernel.googlesource.com/pub/scm/||' | sed 's|\.git$||')
PROJECT_ID=$(curl -s "https://gitlab.com/api/v4/projects/redhat%2Fred-hat-ci-tools%2Fkernel%2Fmirror%2F${REPO_PATH//\//%2F}" | jq -r '.id')
curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
    "https://gitlab.com/api/v4/projects/${PROJECT_ID}/archive"

3.2 Verify Repository is Archived

Verification command:

REPO_PATH=$(echo "{googlesource_url}" | sed 's|https://kernel.googlesource.com/pub/scm/||' | sed 's|\.git$||')
curl -s "https://gitlab.com/api/v4/projects/redhat%2Fred-hat-ci-tools%2Fkernel%2Fmirror%2F${REPO_PATH//\//%2F}" | jq -r '.archived'

Success criteria: Returns true (repository is archived).

3.3 (Optional) Delete the Repository

If the repository should be permanently deleted rather than archived:

Warning: This action is irreversible. Only delete if you are certain the repository is not needed for historical reference.

Using GitLab Web UI:

  1. Navigate to the mirror repository on GitLab
  2. Go to Settings → General → Advanced
  3. Click “Delete project”
  4. Type the project name to confirm
  5. Click “Yes, delete project”

Using GitLab API:

REPO_PATH=$(echo "{googlesource_url}" | sed 's|https://kernel.googlesource.com/pub/scm/||' | sed 's|\.git$||')
PROJECT_ID=$(curl -s "https://gitlab.com/api/v4/projects/redhat%2Fred-hat-ci-tools%2Fkernel%2Fmirror%2F${REPO_PATH//\//%2F}" | jq -r '.id')
curl --request DELETE --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
    "https://gitlab.com/api/v4/projects/${PROJECT_ID}"

Complete Example: Removing iommu/linux mirror

Assuming:

  • {googlesource_url} = https://kernel.googlesource.com/pub/scm/linux/kernel/git/iommu/linux.git
  • {issue_url} = https://gitlab.com/cki-project/infrastructure/-/issues/456
  • {pipeline_data_repo_path} = . (current directory is pipeline-data)
  • {pipeline_data_fork_remote} = fork
  • {deployment_all_repo_path} = ../deployment-all

Example: Phase 1

# Verify the mirror exists
grep -F "iommu/linux" mirrors.yml

# Edit mirrors.yml - remove the line:
#   - https://kernel.googlesource.com/pub/scm/linux/kernel/git/iommu/linux.git

git checkout main && git pull
git checkout -b remove-mirror-iommu-linux
git add mirrors.yml
git commit -m "mirrors: remove iommu/linux repository

https://gitlab.com/cki-project/infrastructure/-/issues/456"
git push \
    -o merge_request.create \
    -o merge_request.target=main \
    -o merge_request.title="mirrors: remove iommu/linux repository" \
    -o merge_request.description="Related issue: https://gitlab.com/cki-project/infrastructure/-/issues/456" \
    fork remove-mirror-iommu-linux

# STOP: Get MR reviewed and merged before continuing

Example: Phase 2

# After MR is merged, deploy configuration
cd ../deployment-all
git checkout main && git pull
REPOS=cki ./gitlab-repo-config/deploy.sh
cd -

# Verify mirroring is disabled
curl -s "https://gitlab.com/api/v4/projects/redhat%2Fred-hat-ci-tools%2Fkernel%2Fmirror%2Flinux%2Fkernel%2Fgit%2Fiommu%2Flinux" | jq -r '.mirror'

# STOP: Verify mirroring shows 'false'

Example: Phase 3

# Archive the repository (using API)
PROJECT_ID=$(curl -s "https://gitlab.com/api/v4/projects/redhat%2Fred-hat-ci-tools%2Fkernel%2Fmirror%2Flinux%2Fkernel%2Fgit%2Fiommu%2Flinux" | jq -r '.id')
curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
    "https://gitlab.com/api/v4/projects/${PROJECT_ID}/archive"

# Verify archived
curl -s "https://gitlab.com/api/v4/projects/redhat%2Fred-hat-ci-tools%2Fkernel%2Fmirror%2Flinux%2Fkernel%2Fgit%2Fiommu%2Flinux" | jq -r '.archived'

# Done! Mirror is removed and repository is archived.

Troubleshooting

Mirroring still shows as enabled after deploy

Ensure the deploy was successful and no errors occurred. Re-run the deploy script and verify the mirrors.yml change was merged to the production branch.

Cannot archive repository

Ensure you have maintainer access to the repository. If the repository is already archived, no action is needed.

Repository has dependent pipelines

If pipelines still reference this mirror, they will fail after removal. Ensure all dependent configurations are updated before removing the mirror. Check:

  • baseline.yaml for repository references
  • Any custom pipeline configurations that may use this mirror

Need to restore a removed mirror

If a mirror was removed in error:

  1. Follow the Adding a Mirror Repository guide to re-add it
  2. If the repository was archived, unarchive it via GitLab UI or API before deploying
  3. If the repository was deleted, a new repository must be created