Migración de repositorios desde Bitbucket Server a GitHub Enterprise Cloud

Puedes migrar repositorios de Bitbucket Server a GitHub Enterprise Cloud con la GitHub CLI.

En este artículo

Acerca de las migraciones de repositorios con GitHub Enterprise Importer

Puedes migrar repositorios individuales o todos los repositorios de una instancia de BitBucket Server con la GitHub CLI.

En este momento, no se admite la migración de Bitbucket Server con la API de GitHub.

Requisitos previos

  • Se recomienda encarecidamente realizar una ejecución de prueba de la migración y completar la migración de producción poco después. Para más información sobre las ejecuciones de prueba, consulta "Introducción a una migración de Bitbucket Server a GitHub Enterprise Cloud".
  • Asegúrate de comprender los datos que se migrarán y las limitaciones de compatibilidad conocidas del importador. Para más información, consulta "Información sobre migraciones de Bitbucket Server a GitHub Enterprise Cloud".
  • Aunque no es necesario, se recomienda detener el trabajo durante la migración de producción. Importer no admite migraciones diferenciales, por lo que los cambios que se produzcan durante la migración no se migrarán. Si decides no detener el trabajo durante la migración de producción, tendrás que migrar manualmente estos cambios.
  • Para la organización de destino en GitHub.com, debes ser propietario de la organización o tener el rol de migración. Para obtener más información, vea «Administración del acceso para una migración desde Bitbucket Server».
  • Necesitas el nombre de usuario y la contraseña de una cuenta de Bitbucket Server con permisos de administrador o superadministrador.

Paso 1: Instalación de la BBS2GH extension of the GitHub CLI

Si se trata de la primera migración, tendrás que instalar la BBS2GH extension of the GitHub CLI. Para más información sobre GitHub CLI, consulte "Acerca del CLI de GitHub".

Como alternativa, puede descargar un binario independiente desde la página de versiones del repositorio github/gh-bbs2gh. Puede ejecutar el archivo binario directamente, sin el prefijo gh.

  1. Instala la GitHub CLI. A fin de obtener instrucciones de instalación para GitHub CLI, vea el repositorio de GitHub CLI.

    Nota: Necesitas la versión 2.4.0 o posterior de la GitHub CLI. Puedes comprobar la versión instalada con el comando gh --version.

  2. Instala la BBS2GH extension.

    Shell
    gh extension install github/gh-bbs2gh

Cada vez que necesites ayuda con BBS2GH extension, puedes usar la marca --help con un comando. Por ejemplo, gh bbs2gh --help enumerará todos los comandos disponibles y gh bbs2gh migrate-repo --help todas las opciones disponibles para el comando migrate-repo.

Paso 2: Actualización de la BBS2GH extension of the GitHub CLI

La BBS2GH extension of the GitHub CLI se actualiza semanalmente. Para asegurarte de que usas la versión más reciente, actualiza la extensión.

Shell
gh extension upgrade github/gh-bbs2gh

Paso 3: Establecimiento de variables de entorno

Para poder usar la BBS2GH extension para la migración a GitHub Enterprise Cloud, debes crear un personal access token que puedan acceder a la organización de destino y, luego, establecer el personal access token como una variable de entorno.

También tendrás que establecer variables de entorno para el nombre de usuario y la contraseña de Bitbucket Server y, si la instancia de Bitbucket Server en cuestión se ejecuta en Windows, la contraseña de SMB.

  1. Crea y registra una instancia de personal access token (classic) que se autenticará para la organización de destino en GitHub Enterprise Cloud, y asegúrate de que el token cumple todos los requisitos. Para obtener más información, vea «Administración del acceso para una migración desde Bitbucket Server».

  2. Establece variables de entorno, reemplazando TOKEN por el personal access token que anotaste anteriormente, USERNAME por el nombre de usuario de una cuenta de Bitbucket Server que tenga permisos de administrador o superadministrador, y PASSWORD por la contraseña de la cuenta de Bitbucket Server.

    • Si usas Terminal, utiliza el comando export.

      Shell
      export GH_PAT="TOKEN"
export BBS_USERNAME="USERNAME"
export BBS_PASSWORD="PASSWORD"
# If your Bitbucket Server instance runs on Windows
export SMB_PASSWORD="PASSWORD"

    • Si usas PowerShell, utiliza el comando $env.

      Shell
      $env:GH_PAT="TOKEN"
$env:BBS_USERNAME="USERNAME"
$env:BBS_PASSWORD="PASSWORD"
# If your Bitbucket Server instance runs on Windows
$env:SMB_PASSWORD="PASSWORD"

Paso 4: Configuración del almacenamiento de blobs

Como muchas instancias de Bitbucket Server se encuentran detrás de firewalls, la GitHub CLI usa el almacenamiento de blobs como una ubicación intermedia para almacenar los datos accesibles desde Internet.

En primer lugar, generarás un archivo de los datos que quieres migrar y los insertarás en el almacenamiento de blobs desde detrás del firewall.

La GitHub CLI admite los siguientes proveedores de almacenamiento de blobs:

  • Amazon Web Services (AWS) S3
  • Azure Blob Storage

Para ejecutar una migración, necesitas configurar un contenedor de almacenamiento con el proveedor de servicios en la nube que prefieras para almacenar los datos.

Configuración de un cubo de almacenamiento de AWS S3

En AWS, configura un cubo S3. Para más información, consulta Creación de un cubo en la documentación de AWS.

También necesitará una clave de acceso de AWS y una clave secreta con los siguientes permisos:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucketMultipartUploads",
                "s3:AbortMultipartUpload",
                "s3:ListBucket",
                "s3:DeleteObject",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::github-migration-bucket",
                "arn:aws:s3:::github-migration-bucket/*"
            ]
        }
    ]
}

Nota: GitHub Enterprise Importer no elimina el archivo de AWS una vez que finaliza la migración. Para reducir los costos de almacenamiento, se recomienda configurar la eliminación automática del archivo después de un período de tiempo. Para más información, consulta Establecimiento de la configuración del ciclo de vida en un cubo en la documentación de AWS.

Cuando estés listo para ejecutar la migración, deberás proporcionar tus credenciales de AWS a GitHub CLI: región, clave de acceso, clave secreta y token de sesión (si es necesario). Puedes pasarlas como argumentos o establecer variables de entorno denominadas AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY y AWS_SESSION_TOKEN.

También deberás pasar el nombre del cubo S3 con el argumento --aws-bucket-name.

Configuración de una cuenta de almacenamiento de Azure Blob Storage

En Azure, crea una cuenta de almacenamiento y anota la cadena de conexión. Para más información, consulta Administración de las claves de acceso de la cuenta de almacenamiento en Microsoft Docs.

Nota: GitHub Enterprise Importer no elimina el archivo de Azure Blob Storage una vez que finaliza la migración. Para reducir los costos de almacenamiento, se recomienda configurar la eliminación automática del archivo después de un período de tiempo. Para más información, consulta Optimización de los costes mediante la administración automática del ciclo de vida de los datos en Microsoft Docs.

Cuando estés listo para ejecutar la migración, puedes pasar la cadena de conexión a la GitHub CLI como argumento, o bien pasarla mediante una variable de entorno denominada AZURE_STORAGE_CONNECTION_STRING.

Paso 5: Migración de un repositorio

Puede migrar repositorios con el comando gh bbs2gh migrate-repo.

Al migrar repositorios y de manera predeterminada, BBS2GH extension of the GitHub CLI llevara cabo estos pasos:

  1. Te conecta a la instancia de Bitbucket Server y genera un archivo de migración por repositorio.
  2. Descarga el archivo de migración de la instancia de Bitbucket Server en la máquina en la que ejecutas la BBS2GH extension of the GitHub CLI, mediante SFTP (Linux) o SMB (Windows)
  3. Carga los archivos de migración en el proveedor de almacenamiento de blobs que prefieras
  4. Inicia la migración en GitHub Enterprise Cloud, con las direcciones URL de los archivos almacenados con el proveedor de almacenamiento de blobs
  5. Elimina el archivo de migración de la máquina local (cuando finalice la migración, tendrás que eliminar manualmente el archivo del proveedor de Blob Storage).

Como alternativa, puede usar GitHub CLI para generar el archivo, descargar ese archivo manualmente y, a continuación, usar GitHub CLI para continuar con la migración.

Permitir que GitHub CLI descargue el archivo de migración

Para migrar un único repositorio, usa el comando gh bbs2gh migrate-repo.

Completa este paso en un equipo que tenga acceso a:

  • La instancia de Bitbucket Server a través de HTTPS
  • La instancia de Bitbucket Server a través de SFTP, si la instancia de Bitbucket Server se ejecuta en Linux. En general, si puedes acceder al servidor a través de SSH, también puedes usar SFTP.
  • La instancia de Bitbucket Server a través de SMB, si la instancia de Bitbucket Server se ejecuta en Windows
  • El proveedor de almacenamiento de blobs que prefieras
Shell
gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT --bbs-repo CURRENT-NAME \
  --github-org DESTINATION --github-repo NEW-NAME \
  # Use the following options if your Bitbucket Server instance runs on Linux
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # Use the following options if your Bitbucket Server instance runs on Windows
  --smb-user SMB-USER
  # Use the following option if you're using AWS S3 as your blob storage provider
  --aws-bucket-name AWS-BUCKET-NAME
  # Use the following option if you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

Reemplaza los marcadores de posición del comando anterior por los valores siguientes.

Marcador de posiciónValue
BBS-SERVER-URLURL de la instancia de Bitbucket Server
PROJECTClave del proyecto de Bitbucket Server del repositorio que quieres migrar
CURRENT-NAMENombre del repositorio que quieres migrar
DESTINATIONNombre de la organización de destino
NEW-NAMENombre que quieres que tenga el repositorio migrado
SSH-USERSi la instancia de Bitbucket Server se ejecuta en Linux, el nombre de usuario que se usará al conectarse a Bitbucket Server mediante SFTP
PATH-TO-KEYSi la instancia de Bitbucket Server se ejecuta en Linux, la ruta de acceso a la clave privada SSH, como ~/.ssh/id_rsa. Para obtener los requisitos de clave SSH, consulta "Administración del acceso para una migración desde Bitbucket Server".
SMB-USERSi la instancia de Bitbucket Server se ejecuta en Windows, el nombre de usuario que se usará al conectarse a la instancia de Bitbucket Server mediante SMB
AWS-BUCKET-NAMENombre del depósito de AWS S3
ARCHIVE-DOWNLOAD-HOSTHost que se va a usar para conectarse a la instancia del Centro de datos de Bitbucket o de Bitbucket Server mediante SSH o SMB. Solo tienes que especificar esta información si vas a ejecutar un clúster del Centro de datos de Bitbucket o si tu instancia de Bitbucket Server está detrás de un equilibrador de carga.

Nota: Si recibes un error en el que se menciona Renci.SshNet, significa que la CLI tiene problemas para establecer una conexión SFTP con el servidor para descargar el archivo de migración. Para más información sobre cómo solucionar estos problemas, consulta "Solución de problemas de la migración con GitHub Enterprise Importer".

Descargar el archivo de migración de forma manual

De manera predeterminada, BBS2GH extension of the GitHub CLI realiza toda la migración, incluida la descarga del archivo de migración de la instancia de Bitbucket Server mediante SFTP o SMB.

Sin embargo, algunos clientes prefieren descargar manualmente el archivo de migración, ya que su servidor no ofrece acceso SFTP, por ejemplo. En ese caso, puede usar GitHub CLI para generar el archivo, descargar ese archivo manualmente y, a continuación, usar GitHub CLI para continuar con la migración.

Completa este paso en un equipo que tenga acceso a:

  • La instancia de Bitbucket Server a través de HTTPS
  • El proveedor de almacenamiento de blobs que prefieras

En primer lugar, use el comando gh bbs2gh migrate-repo solo con los argumentos siguientes:

Shell
gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-NAME

Reemplaza los marcadores de posición del comando anterior por los valores siguientes.

Marcador de posiciónValue
BBS-SERVER-URLURL de la instancia de Bitbucket Server
PROJECTClave del proyecto de Bitbucket Server del repositorio que quieres migrar
CURRENT-NAMENombre del repositorio que quieres migrar

Se generará el archivo de migración y se imprimirá su ruta de acceso en la salida del comando:

[12:14] [INFO] Export completed. Your migration archive should be ready on your
instance at $BITBUCKET_SHARED_HOME/data/migration/export/Bitbucket_export_9.tar

En general, $BITBUCKET_SHARED_HOME se establecerá en /var/atlassian/application-data/bitbucket/shared en Linux y en C:\Atlassian\ApplicationData\Bitbucket\Shared en Windows, pero esto puede diferir en función de la configuración del servidor. Para ayudarle a identificar el directorio principal compartido, consulte "Solución de problemas de la migración con GitHub Enterprise Importer".

Descargue el archivo de migración desde la instancia de Bitbucket Server y almacene el archivo en el equipo donde se ejecuta GitHub CLI.

Para importar el archivo de migración en GitHub, use de nuevo el comando gh bbs2gh migrate-repo, con un conjunto diferente de argumentos:

Shell
gh bbs2gh migrate-repo --archive-path ARCHIVE-PATH \
  --github-org DESTINATION --github-repo NEW-NAME \
  --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-NAME \
  # Use the following option if you're using AWS S3 as your blob storage provider
  --aws-bucket-name AWS-BUCKET-NAME

Reemplaza los marcadores de posición del comando anterior por los valores siguientes.

Marcador de posiciónValue
ARCHIVE-PATHRuta de acceso al archivo de migración de Bitbucket Server que descargó de la instancia
DESTINATIONNombre de la organización de destino
NEW-NAMENombre que quieres que tenga el repositorio migrado
BBS-SERVER-URLURL de la instancia de Bitbucket Server
PROJECTClave del proyecto de Bitbucket Server del repositorio que quieres migrar
CURRENT-NAMENombre del repositorio que quieres migrar
AWS-BUCKET-NAMENombre del depósito de AWS S3

Cancelar una migración

Si deseas cancelar una migración, usa el comando abort-migration, reemplazando MIGRATION-ID por el identificador devuelto de migrate-repo.

Shell
gh bb2gh abort-migration --migration-id MIGRATION-ID

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

Una vez que se complete la migración, se recomienda revisar el registro de migración. Para obtener más información, vea «Acceso a los registros de migración para GitHub Enterprise Importer».

Se recomienda revisar los repositorios migrados para obtener una comprobación de solidez.

Paso 7: Migración de varios repositorios

Si quieres migrar varios repositorios a GitHub Enterprise Cloud a la vez, usa la GitHub CLI para generar un script de migración. El script resultante contendrá una lista de comandos de migración, uno por cada repositorio.

Nota: La generación de un script genera un script de PowerShell. Si usas Terminal, tendrás que generar el script con la extensión de archivo .ps1 e instalar PowerShell para Mac o Linux para ejecutarlo.

Generación de un script de migración

Sigue este paso en un equipo en el que puedas acceder a tu instancia de Bitbucket Server a través de HTTPS.

Para generar un script de migración, ejecuta el comando gh bbs2gh generate-script.

Shell
gh bbs2gh generate-script --bbs-server-url BBS-SERVER-URL \
  --github-org DESTINATION \
  --output FILENAME \
  # Use the following options if your Bitbucket Server instance runs on Linux
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # Use the following options if your Bitbucket Server instance runs on Windows
  --smb-user SMB-USER
  # Use the following option if you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

Si quieres que el script descargue el registro de migración para cada repositorio migrado, agrega la marca --download-migration-logs. Para más información sobre los registros de migración, consulta "Acceso a los registros de migración para GitHub Enterprise Importer".

Reemplaza los marcadores de posición del comando anterior por los valores siguientes.

Marcador de posiciónValue
BBS-SERVER-URLURL de la instancia de Bitbucket Server
DESTINATIONNombre de la organización de destino
FILENAMENombre de archivo para el script de migración resultante

Si usas Terminal, utiliza una extensión de archivo .ps1, ya que el script generado necesita que se ejecute PowerShell. Puedes instalar PowerShell para Mac o Linux.
SSH-USERSi la instancia de Bitbucket Server se ejecuta en Linux, el nombre de usuario que se usará al conectarse a Bitbucket Server mediante SFTP
PATH-TO-KEYSi la instancia de Bitbucket Server se ejecuta en Linux, la ruta de acceso a la clave privada SSH, como ~/.ssh/id_rsa. Para obtener los requisitos de clave SSH, consulta "Administración del acceso para una migración desde Bitbucket Server".
SMB-USERSi la instancia de Bitbucket Server se ejecuta en Windows, el nombre de usuario que se usará al conectarse a la instancia de Bitbucket Server mediante SMB
ARCHIVE-DOWNLOAD-HOSTHost que se va a usar para conectarse a la instancia del Centro de datos de Bitbucket o de Bitbucket Server mediante SSH o SMB. Solo tienes que especificar esta información si vas a ejecutar un clúster del Centro de datos de Bitbucket o si tu instancia de Bitbucket Server está detrás de un equilibrador de carga.

Revisión del script de migración

Después de generar el script, revisa el archivo y, opcionalmente, edita el script.

  • Si hay repositorios que no quieras migrar, elimina o convierte en comentario las líneas correspondientes.
  • De manera predeterminada, los nombres de repositorio de GitHub seguirán una convención projectKey-repositoryName. Por ejemplo, un repositorio de Bitbucket Server denominado airports que forma parte del proyecto open-source, que tiene la clave OS, tendrá el nombre OS-airports en GitHub. Si quieres que los repositorios tengan otro nombre en GitHub, actualiza el valor de la marca --github-repo correspondiente.

Si descargó BBS2GH como un binario independiente en lugar de como una extensión para los GitHub CLI, deberá actualizar el script generado para ejecutar el binario en lugar de gh bbs2gh.

Ejecución del script de migración

Para migrar los repositorios, ejecute el script generado.

Completa este paso en un equipo que tenga acceso a:

  • La instancia de Bitbucket Server a través de HTTPS
  • La instancia de Bitbucket Server a través de SFTP, si la instancia de Bitbucket Server se ejecuta en Linux. En general, si puedes acceder al servidor a través de SSH, también puedes usar SFTP.
  • La instancia de Bitbucket Server a través de SMB, si la instancia de Bitbucket Server se ejecuta en Windows
  • El proveedor de almacenamiento de blobs que prefieras

Antes de ejecutar el script, debe establecer variables de entorno adicionales para autenticarse en el proveedor de almacenamiento de blobs.

  • Pra AWS S3, establece las siguientes variables de entorno.
    • AWS_ACCESS_KEY_ID: el id. de clave de acceso del cubo
    • AWS_SECRET_ACCESS_KEY: la clave secreta del cubo
    • AWS_REGION: la región de AWS en la que se ubica el cubo
    • AWS_SESSION_TOKEN: el token de la sesión, si usas credenciales temporales de AWS (consulta Uso de credenciales temporales con recursos de AWS en la documentación de AWS)
  • Para Azure Blob Storage, establece AZURE_STORAGE_CONNECTION_STRING en la cadena de conexión de la cuenta de almacenamiento de Azure.

Solo se admiten cadenas de conexión que usan claves de acceso de cuenta de almacenamiento. No se admiten las cadenas de conexión que usan firmas de acceso compartido (SAS). Para más información sobre las claves de acceso de cuentas de almacenamiento, consulta Administración de claves de acceso de cuentas de almacenamiento en la documentación de Azure.

Para migrar varios repositorios, ejecuta el script que has generado antes. Reemplaza FILENAME en los comandos siguientes por el nombre de archivo que has proporcionado al generar el script.

  • Si usas Terminal, utiliza ./.

    Shell
    ./FILENAME

  • Si usas PowerShell, utiliza .\.

    Shell
    .\FILENAME