Uso de GraphQL para migrar repositorios de GitLab a GitHub Enterprise Cloud

Nota:

También puede usar GL2GH extension of the GitHub CLI para realizar la migración. Consulte Descripción de las migraciones de GitLab a GitHub.

Paso 0: Preparación para usar GitHub GraphQL API

Para realizar consultas de GraphQL, tendrás que escribir scripts propios, o bien usar un cliente HTTP como Insomnia.

Para más información sobre cómo empezar a trabajar con GraphQL API de GitHub, incluido cómo autenticarse, consulta Formar llamados con GraphQl.

Enviarás todas las consultas de GraphQL al destino de tu migración. Si vas a migrar a Nube de GitHub Enterprise con residencia de datos, asegúrate de enviar consultas al punto de conexión del subdominio de la empresa de GHE.com.

Paso 1: Obtención de `ownerId` para el destino de la migración

Como propietario de la organización en GitHub Enterprise Cloud, usa la consulta GetOrgInfo para devolver ownerId, también denomino id. de organización, para la organización que quieras que posea los repositorios migrados. Necesitarás el valor ownerId para identificar el destino de la migración.

Consulta `GetOrgInfo`

query(
  $login: String!
){
  organization (login: $login)
  {
    login
    id
    name
    databaseId
  }
}

Variable de consulta	Descripción
`login`	El nombre de la organización.

Respuesta `GetOrgInfo`

{
  "data": {
    "organization": {
      "login": "Octo",
      "id": "MDEyOk9yZ2FuaXphdGlvbjU2MTA=",
      "name": "Octo-org",
      "databaseId": 5610
    }
  }
}

En este ejemplo, MDEyOk9yZ2FuaXphdGlvbjU2MTA= es el id. de la organización o ownerId, que se usará en el paso siguiente.

Paso 2: Identificación del origen de la migración

Puedes configurar un origen de migración mediante la consulta createMigrationSource. Tendrás que proporcionar el valor ownerId, o id. de organización, recopilado de la consulta GetOrgInfo.

El origen de la migración es la instancia de GitLab.

Mutación de `createMigrationSource`

mutation createMigrationSource($name: String!, $url: String!, $ownerId: ID!) {
  createMigrationSource(input: {name: $name, url: $url, ownerId: $ownerId, type: GITLAB}) {
    migrationSource {
      id
      name
      url
      type
    }
  }
}

Establezca url en la dirección URL completa de la instancia de GitLab, como https://gitlab.com o https://gitlab.example.com. Asegúrate de usar GITLAB para type.

Variable de consulta	Descripción
`name`	Nombre para el origen de la migración. Este nombre es para referencia propia, por lo que puedes usar cualquier cadena.
`ownerId`	El id. de la organización en GitHub Enterprise Cloud.

Respuesta `createMigrationSource`

{
  "data": {
    "createMigrationSource": {
      "migrationSource": {
        "id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA",
        "name": "GitLab Source",
        "url": "https://gitlab.com",
        "type": "GITLAB"
      }
    }
  }
}

En este ejemplo, MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA es el identificador de origen de la migración, que se usará en un paso posterior.

Paso 3: Generar y hospedar el archivo de migración

Las migraciones de GitLab se basan en el archivo. En lugar de conectarse a la instancia de GitLab durante la migración, GitHub Enterprise Importer importa un archivo de migración que se genera desde el proyecto de GitLab. Un archivo de GitLab es un único archivo que contiene tanto el origen de Git como los metadatos del repositorio.

Antes de iniciar la migración, debe:

Genere un archivo de migración para el proyecto de GitLab que desea migrar.
Hospede el archivo en una dirección URL a la que GitHub Enterprise Cloud pueda acceder.

Proporcionará esta dirección URL como valor gitArchiveUrl en el paso siguiente.

Generar un archivo de migración

Use la API de exportación de proyectos de GitLab para exportar el proyecto que desea migrar. El token que use debe tener el api ámbito y un rol con permiso para exportar el proyecto. Para obtener más información, vea Administración del acceso de una migración desde GitLab a GitHub.

En las siguientes solicitudes, establezca la GITLAB_PAT variable de entorno en el token que creó en Administración del acceso de una migración desde GitLab a GitHub. Reemplace GITLAB-SERVER por el host de la instancia de GitLab, como gitlab.com, y reemplace por GROUP%2FPROJECT la ruta de acceso codificada por url del proyecto. Por ejemplo, el proyecto acme-group/my-project se codifica como acme-group%2Fmy-project. En el caso de los subgrupos anidados, incluya la ruta de acceso completa, como parent-group%2Fsubgroup%2Fmy-project.

Programe la exportación.

curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_PAT" \
  "https://GITLAB-SERVER/api/v4/projects/GROUP%2FPROJECT/export"

Compruebe el estado de la exportación. Repita esta solicitud hasta export_status que sea finished.

curl --header "PRIVATE-TOKEN: $GITLAB_PAT" \
  "https://GITLAB-SERVER/api/v4/projects/GROUP%2FPROJECT/export"

Descargue el archivo.

curl --location \
  --header "PRIVATE-TOKEN: $GITLAB_PAT" \
  --output archive.tar.gz \
  "https://GITLAB-SERVER/api/v4/projects/GROUP%2FPROJECT/export/download"

Hospedaje del archivo

Debe hospedar el archivo en una dirección URL a la que GitHub Enterprise Cloud pueda acceder. Puede cargar el archivo en GitHub-owned blob storage o usar un proveedor de almacenamiento de blobs externo. Para obtener información sobre los proveedores externos, consulte Configuración de Blob Storage.

Para cargar el archivo en GitHub-owned blob storage, necesitará el identificador de base de datos de la organización en GitHub Enterprise Cloud. Reemplace por ORGANIZATION el nombre de la organización para obtener este identificador del id campo en la respuesta.

curl --header "Authorization: Bearer YOUR-TOKEN" \
  "https://api.github.com/orgs/ORGANIZATION"

Nota:

Si va a migrar a GHE.com, reemplace por https://api.github.com la dirección URL de API base del subdominio de la empresa, como https://api.octocorp.ghe.com.

Cargue el archivo con una POST solicitud y reemplace ORGANIZATION-ID por el identificador de base de datos de la organización. Esta solicitud funciona para archivos de hasta 100 MiB. Para archivos más grandes, use un proveedor de almacenamiento de blobs externo.

curl --request POST \
  --header "Authorization: Bearer YOUR-TOKEN" \
  --header "Content-Type: application/octet-stream" \
  --data-binary @archive.tar.gz \
  "https://uploads.github.com/organizations/ORGANIZATION-ID/gei/archive?name=archive.tar.gz"

Nota:

Si va a migrar a GHE.com, reemplace por uploads.github.com el host de cargas para el subdominio de la empresa, como uploads.octocorp.ghe.com.

La respuesta incluye un uri en el formato gei://archive/GUID. Use este valor como en gitArchiveUrl el paso siguiente.

{
  "guid": "ff7b1a25-aa10-41a9-8e42-f170304b1c0d",
  "node_id": "MA_kgDaACRmZjdiMWEyNS1hYTEwLTQxYTktOGU0Mi1mMTcwMzA0YjFjMGQ",
  "name": "archive.tar.gz",
  "size": 7103,
  "uri": "gei://archive/ff7b1a25-aa10-41a9-8e42-f170304b1c0d",
  "created_at": "2024-11-13T12:35:45.761-08:00"
}

Paso 4: Iniciar la migración del repositorio

Al iniciar una migración, un único repositorio y sus datos adjuntos se migran a un repositorio nuevo de GitHub que identifiques.

Si quieres mover varios repositorios a la vez desde la misma organización de origen, puedes poner en cola varias migraciones. Puedes ejecutar hasta cinco migraciones de repositorio a la vez.

Mutación de `startRepositoryMigration`

mutation startRepositoryMigration (
  $sourceId: ID!,
  $ownerId: ID!,
  $sourceRepositoryUrl: URI!,
  $repositoryName: String!,
  $continueOnError: Boolean!,
  $accessToken: String!,
  $githubPat: String!,
  $gitArchiveUrl: String!,
  $targetRepoVisibility: String!
){
  startRepositoryMigration( input: {
    sourceId: $sourceId,
    ownerId: $ownerId,
    repositoryName: $repositoryName,
    continueOnError: $continueOnError,
    accessToken: $accessToken,
    githubPat: $githubPat,
    targetRepoVisibility: $targetRepoVisibility,
    gitArchiveUrl: $gitArchiveUrl,
    sourceRepositoryUrl: $sourceRepositoryUrl,
  }) {
    repositoryMigration {
      id
      migrationSource {
        id
        name
        type
      }
      sourceUrl
    }
  }
}

Variable de consulta	Descripción
`sourceId`	El origen de migración `id` devuelto por la mutación `createMigrationSource`.
`ownerId`	El id. de la organización en GitHub Enterprise Cloud.
`repositoryName`	Un nombre de repositorio único personalizado que actualmente no se use en ninguno de los repositorios propiedad de la organización en GitHub Enterprise Cloud. Se creará una incidencia de registro de errores en este repositorio cuando se complete la migración o se haya detenido.
`continueOnError`	Valor de migración que permite que continúe al encontrar errores que no hacen que se produzca un error en la migración. Debe ser `true` o `false`. Se recomienda encarecidamente establecer `continueOnError` en `true` para que la migración continúe a menos que Importer no pueda mover el origen de Git o Importer haya perdido la conexión y no se pueda volver a conectar para completar la migración.
`githubPat`	El valor personal access token de la organización de destino en GitHub Enterprise Cloud.
`accessToken`	El valor personal access token para el origen.
`targetRepoVisibility`	La visibilidad del nuevo repositorio. Debe ser `private`, `public` o `internal`. Si no se establece, el repositorio se migra como privado.

| gitArchiveUrl | Dirección GitHub Enterprise CloudURL accesible para el archivo de migración que generó en el paso anterior. Las migraciones de GitLab usan un único archivo que contiene tanto el origen de Git como los metadatos, por lo que no es necesario proporcionar un archivo independiente metadataArchiveUrl.

| sourceRepositoryUrl | La dirección URL del repositorio de origen en GitLab, con el formato https://GITLAB-SERVER/{group}/{project}. En el caso de los subgrupos anidados, incluya la ruta de acceso completa, como https://GITLAB-SERVER/{parent-group}/{subgroup}/{project}. GitHub Enterprise Cloud no se conecta a esta dirección URL durante la migración; se registra como referencia.

Dado que las migraciones de GitLab están basadas en archivos, GitHub Enterprise Cloud no se conecta a GitLab durante la migración. La accessToken variable es necesaria para la mutación, pero no se usa, por lo que puede establecerla en cualquier valor de marcador de posición, como not-used.

Para ver los requisitos de personal access token, consulte Administración del acceso de una migración desde GitLab a GitHub.

En el paso siguiente, usarás el id. de migración devuelto por la mutación startRepositoryMigration para comprobar el estado de la migración.

Paso 5: Comprobar el estado de la migración

Para detectar errores de migración y asegurarse de que la migración funciona, puedes comprobar el estado de la migración mediante la consulta getMigration. También puedes comprobar el estado de varias migraciones con getMigrations.

La consulta getMigration devolverá con un estado para que sepas si la migración es queued, in progress, failed o completed. Si se ha producido un error en la migración, en Importer se proporcionará un motivo para el error.

Consulta `getMigration`

query (
  $id: ID!
){
  node( id: $id ) {
    ... on Migration {
      id
      sourceUrl
      migrationSource {
        name
      }
      state
      failureReason
    }
  }
}

Variable de consulta	Descripción
`id`	El valor `id` de la migración que ha devuelto la mutación `startRepositoryMigration`.

Paso 6: Validación de la migración y comprobación del registro de errores

Para finalizar la migración, se recomienda comprobar la incidencia "Registro de migración". Esta incidencia se crea en GitHub en el repositorio de destino.

Captura de pantalla de una incidencia con el título "Registro de migración". El segundo comentario de la incidencia incluye registros para una migración.

Por último, se recomienda revisar los repositorios migrados para obtener una comprobación de solidez.

Lectura adicional

Tareas de seguimiento

Uso de GraphQL para migrar repositorios de GitLab a GitHub Enterprise Cloud

En este artículo