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
.
-
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
. -
Instala la BBS2GH extension.
Shell gh extension install github/gh-bbs2gh
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.
gh extension upgrade github/gh-bbs2gh
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.
-
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».
-
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"
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"
$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:
- Te conecta a la instancia de Bitbucket Server y genera un archivo de migración por repositorio.
- 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)
- Carga los archivos de migración en el proveedor de almacenamiento de blobs que prefieras
- Inicia la migración en GitHub Enterprise Cloud, con las direcciones URL de los archivos almacenados con el proveedor de almacenamiento de blobs
- 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"
- "Descargar el archivo de migración de forma manual"
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
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
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ón | Value |
---|---|
BBS-SERVER-URL | URL de la instancia de Bitbucket Server |
PROJECT | Clave del proyecto de Bitbucket Server del repositorio que quieres migrar |
CURRENT-NAME | Nombre del repositorio que quieres migrar |
DESTINATION | Nombre de la organización de destino |
NEW-NAME | Nombre que quieres que tenga el repositorio migrado |
SSH-USER | Si 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-KEY | Si 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-USER | Si 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-NAME | Nombre del depósito de AWS S3 |
ARCHIVE-DOWNLOAD-HOST | Host 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:
gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \ --bbs-project PROJECT \ --bbs-repo CURRENT-NAME
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ón | Value |
---|---|
BBS-SERVER-URL | URL de la instancia de Bitbucket Server |
PROJECT | Clave del proyecto de Bitbucket Server del repositorio que quieres migrar |
CURRENT-NAME | Nombre 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:
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
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ón | Value |
---|---|
ARCHIVE-PATH | Ruta de acceso al archivo de migración de Bitbucket Server que descargó de la instancia |
DESTINATION | Nombre de la organización de destino |
NEW-NAME | Nombre que quieres que tenga el repositorio migrado |
BBS-SERVER-URL | URL de la instancia de Bitbucket Server |
PROJECT | Clave del proyecto de Bitbucket Server del repositorio que quieres migrar |
CURRENT-NAME | Nombre del repositorio que quieres migrar |
AWS-BUCKET-NAME | Nombre 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
.
gh bb2gh abort-migration --migration-id MIGRATION-ID
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
.
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
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ón | Value |
---|---|
BBS-SERVER-URL | URL de la instancia de Bitbucket Server |
DESTINATION | Nombre de la organización de destino |
FILENAME | Nombre 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-USER | Si 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-KEY | Si 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-USER | Si 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-HOST | Host 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 denominadoairports
que forma parte del proyectoopen-source
, que tiene la claveOS
, tendrá el nombreOS-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 cuboAWS_SECRET_ACCESS_KEY
: la clave secreta del cuboAWS_REGION
: la región de AWS en la que se ubica el cuboAWS_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
./FILENAME
-
Si usas PowerShell, utiliza
.\
.Shell .\FILENAME
.\FILENAME