Mapping Guide

Mapping Guide

The mapping.json file defines which GitHub organizations and repositories are synced to which GitLab groups and projects. hub2lab supports two modes: explicit mapping (list every repo) and auto-sync (sync all repos).

File Location

By default, hub2lab looks for mapping.json in the current working directory. Override with the MAPPING_FILE environment variable.

{
  "mappings": [
    {
      "github_org": "my-org",
      "gitlab_group": "my-group",
      "repos": {
        "repo-a": "repo-a-mirror",
        "repo-b": "repo-b"
      }
    }
  ]
}

Mode 1: Explicit Mapping

Use this when repo names differ between sides, or you only want a subset of repos synced.

{
  "mappings": [
    {
      "github_org": "acme-corp",
      "gitlab_group": "acme-mirrors",
      "repos": {
        "frontend": "frontend-app",
        "backend": "backend-service",
        "docs": "documentation"
      }
    }
  ]
}

Each key under repos is a GitHub repo name; the value is the corresponding GitLab project name. Only repos listed in repos will be synced.

Mode 2: Auto-Sync

Omit repos entirely. Any repo in the GitHub org is synced to a same-named GitLab project (and vice versa).

{
  "mappings": [
    {
      "github_org": "oss-town",
      "gitlab_group": "oss-mirrors"
    }
  ]
}

Useful when you have many repos and names match on both sides.

Mixing Modes

You can have multiple mapping entries in a single file, mixing both modes:

{
  "mappings": [
    {
      "github_org": "acme-corp",
      "gitlab_group": "acme",
      "repos": {
        "backend": "backend-service"
      }
    },
    {
      "github_org": "oss-town",
      "gitlab_group": "oss-mirrors"
    }
  ]
}

How Resolution Works

When a webhook arrives from GitHub, hub2lab:

1. Extracts the organization and repo name from the payload
2. Scans all mappings for a matching github_org
3. If the mapping has a repos dict, looks up the GitHub repo name as a key
4. If the key exists (or repos is absent), uses the corresponding GitLab project name
5. Performs the sync action

The same process runs in reverse for GitLab webhooks.

Resolution Logic

Source: src/config/mapper.ts

• resolveGitHubToGitLab() — finds the GitLab project name for a given GitHub org + repo
• resolveGitLabToGitHub() — finds the GitHub org + repo for a given GitLab group + project
• findGroupByOrg() — returns the GitLab group for a GitHub org
• findOrgByGroup() — returns the GitHub org for a GitLab group

Edge Cases

Repo not in mapping: If a GitHub repo doesn't match any mapping entry (and auto-sync isn't active for that org), the event is silently skipped with a log message.

Mapping not found from GitLab: If a GitLab project doesn't reverse-map to any GitHub repo, the event is skipped. Note: hub2lab only maps group-level GitLab projects; personal namespace projects are not supported.

Multiple orgs per instance: You can list multiple org→group pairs in mappings[]. Each pair is independent.