Cómo conectarse a un repositorio de Git de terceros

En este documento, se muestra cómo conectar un repositorio remoto a un repositorio de Dataform. Después de conectar los repositorios, los cambios que realices en un espacio de trabajo de desarrollo de Dataform se pueden enviar y extraer del repositorio de Git remoto.

Importante: Dataform no puede conectarse directamente a una dirección IP privada de un host de Git local. Para conectarte a un repositorio en una red privada, usa Developer Connect.

Puedes conectar un repositorio remoto a través de HTTPS o SSH.

En la siguiente tabla, se enumeran los proveedores de Git y los métodos de conexión compatibles que están disponibles para sus repositorios:

Proveedor de Git	Método de conexión
Azure DevOps Services	SSH
Bitbucket	Developer Connect (recomendado), SSH
GitHub	Developer Connect (recomendado), SSH o HTTPS
GitLab	Developer Connect (recomendado), SSH o HTTPS

Importante: Para conectar tu repositorio Git remoto a Dataform con HTTPS o SSH, verifica que tu host de Git tenga una dirección IP pública. Si tu host de Git está configurado solo con una dirección IP privada (por ejemplo, 10.x.x.x, 172.16.x.x-172.31.x.x o 192.168.x.x) o si está detrás de un firewall, te recomendamos que te conectes con Developer Connect. Si eliges conectar un repositorio remoto protegido con una dirección IP pública a través de HTTPS o SSH, debes agregar los rangos de direcciones IP de salida de Dataform necesarios a las reglas del firewall para habilitar la conexión.

Antes de comenzar

1. Si tu organización o proyecto restringe los repositorios de Git remotos con la política de organización dataform.restrictGitRemotes, asegúrate de que el repositorio de Git remoto se agregue a la lista de entidades permitidas en la política antes de crear el repositorio de Dataform que deseas conectar a un repositorio remoto. Para obtener más información, consulta Cómo restringir repositorios remotos.

2. Selecciona o crea un repositorio de Dataform. Necesitarás el repositorio más adelante para compartir un secreto con tu agente de servicio de Dataform predeterminado.

   Nota: La lista de repositorios de Dataform solo incluye los repositorios creados para el desarrollo de flujos de trabajo de Dataform. Los repositorios de los recursos de BigQuery Studio, como los notebooks o las consultas guardadas, se administran por separado y no aparecen en esta lista.

3. Asegúrate de tener los permisos necesarios en tu proveedor de Git y de que tu repositorio de Dataform se encuentre en una región admitida.

4. Habilita la API de Developer Connect.

5. Si conectas Developer Connect a un repositorio de Bitbucket, asegúrate de que tu token de acceso de autorización tenga acceso de escritura a tus repositorios para que Dataform pueda enviar cambios. Para obtener más información, consulta Crea tokens de acceso.

Roles obligatorios

Para obtener los permisos que necesitas para conectar un repositorio de Dataform a un repositorio de Git remoto, pídele a tu administrador que te otorgue los siguientes roles de IAM en los repositorios:

• Administrador de Dataform (roles/dataform.admin)
• Administrador de Developer Connect (roles/developerconnect.admin)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Para conectar un repositorio remoto con Developer Connect, otorga los roles de Accesor de tokens de Developer Connect (roles/developerconnect.tokenAccessor) y Usuario del proxy de Git de Developer Connect (roles/developerconnect.gitProxyUser) al agente de servicio predeterminado de Dataform. Tu ID de agente de servicio predeterminado de Dataform tiene el siguiente formato:

[e-mail]

Conecta un repositorio remoto con Developer Connect

Developer Connect optimiza la integración de proveedores externos de Git con repositorios de Dataform, ya que proporciona una interfaz guiada que elimina la necesidad de administrar secretos de forma manual.

Con Developer Connect, puedes conectarte a repositorios remotos en redes alojadas de forma privada, como entornos locales o nubes privadas virtuales (VPC), sin exponerlos a la Internet pública.

Importante: Se requiere el proxy de Developer Connect para conectarse a repositorios de Git en redes privadas. Cuando creas una conexión nueva en la consola deGoogle Cloud , el proxy se habilita de forma predeterminada. En el caso de las conexiones a repositorios de Git accesibles de forma pública, el proxy está habilitado de forma predeterminada, pero se puede inhabilitar de manera opcional. Si usas una conexión existente creada con la gcloud CLI o la API de Developer Connect, asegúrate de que el proxy esté habilitado si necesitas acceder a un repositorio en una red privada.

Nota: Si el repositorio de Dataform y la conexión de Developer Connect se encuentran en regiones diferentes, es posible que se apliquen costos adicionales por transferencia de datos entre regiones cuando el proxy de Developer Connect esté habilitado. Para obtener más información, consulta los precios de Developer Connect.

Preparación para conexiones de red privadas

Si te conectas a un repositorio remoto en una red privada, asegúrate de tener la siguiente información y recursos listos antes de comenzar la configuración:

• El espacio de nombres y el nombre del servicio de Directorio de servicios que apunta a tu host interno de Git.
• Un certificado de autoridad certificadora en formato PEM (con un tamaño máximo de 10 KB) si tu host usa una autoridad certificadora privada o autofirmada
• Verificación de que el certificado SSL de tu host de Git incluye un nombre alternativo de sujeto (SAN) que coincide con el URI del host.

Para obtener más información sobre cómo configurar conexiones para redes alojadas de forma privada, consulta lo siguiente:

• Configura y usa el proxy de Developer Connect
• Cómo conectarse a GitHub Enterprise en una red privada
• Conéctate a repositorios de GitLab Enterprise en una red privada
• Conéctate a repositorios de Bitbucket Data Center alojados en una red privada

Crea una nueva conexión de Developer Connect

Para conectar un repositorio remoto a una nueva conexión de Developer Connect, selecciona una de las siguientes opciones:

Bitbucket

1. En la consola de Google Cloud , ve a la página Dataform.

   Ir a Dataform

2. Selecciona tu repositorio.

3. Ve a Configuración y, luego, haz clic en Conectar con Git.

4. En el panel Vincular a un repositorio remoto, en la sección Protocolo de repositorio de Git remoto, selecciona Developer Connect.

5. En el menú de selección de repositorios, haz clic en Vincular repositorio nuevo.

6. En el panel Vincula repositorios de Git a través de Developer Connect, selecciona Crear conexión nueva.

7. Selecciona Bitbucket como tu proveedor.

8. Especifica la región y el nombre de la conexión.

9. Proporciona el nombre del espacio de trabajo, el token de acceso del autorizador y el token de acceso de lectura.

10. Haz clic en Continuar, selecciona los repositorios remotos que deseas vincular y haz clic en Vincular.

11. En Dataform, selecciona tu repositorio remoto y la rama predeterminada.

12. Para completar la configuración, haz clic en Vincular.

GitHub

1. En la consola de Google Cloud , ve a la página Dataform.

   Ir a Dataform

2. Selecciona tu repositorio.

3. Ve a Configuración y, luego, haz clic en Conectar con Git.

4. En el panel Vincular a un repositorio remoto, en la sección Protocolo de repositorio de Git remoto, selecciona Developer Connect.

5. En el menú de selección de repositorios, haz clic en Vincular repositorio nuevo.

6. En el panel Vincula repositorios de Git a través de Developer Connect, selecciona Crear conexión nueva.

7. Selecciona GitHub como tu proveedor.

8. Especifica la región y el nombre de la conexión.

9. Para activar el flujo de autenticación de OAuth, haz clic en Continuar y, luego, haz lo siguiente:

   1. Haz clic en Entiendo y continuar.
   2. Selecciona Instala la App de GitHub en otra cuenta de GitHub y sigue las indicaciones para autorizar el acceso a tu cuenta de GitHub y a repositorios específicos.
   3. Selecciona la cuenta en la que deseas instalar la aplicación de GitHub de Dataform.
   4. En la sección Acceso al repositorio, selecciona si quieres otorgar acceso a todos los repositorios o solo a una selección de ellos.
   5. Haz clic en Guardar.

10. Selecciona los repositorios remotos que deseas vincular y haz clic en Vincular.

11. En Dataform, selecciona tu repositorio remoto y la rama predeterminada.

12. Para completar la configuración, haz clic en Vincular.

GitLab

1. En la consola de Google Cloud , ve a la página Dataform.

   Ir a Dataform

2. Selecciona tu repositorio.

3. Ve a Configuración y, luego, haz clic en Conectar con Git.

4. En el panel Vincular a un repositorio remoto, en la sección Protocolo de repositorio de Git remoto, selecciona Developer Connect.

5. En el menú de selección de repositorios, haz clic en Vincular repositorio nuevo.

6. En el panel Vincula repositorios de Git a través de Developer Connect, selecciona Crear conexión nueva.

7. Selecciona GitLab como tu proveedor.

8. Especifica la región y el nombre de la conexión.

9. Proporciona el token de acceso a la API y el token de acceso a la API de lectura. Para obtener información sobre cómo hacerlo, consulta Crea tokens de acceso.

10. Haz clic en Continuar, selecciona los repositorios remotos que deseas vincular y haz clic en Vincular.

11. En Dataform, selecciona tu repositorio remoto y la rama predeterminada.

12. Para completar la configuración, haz clic en Vincular.

Usar una conexión existente de Developer Connect

Para conectar un repositorio remoto a una conexión existente de Developer Connect, haz lo siguiente:

1. En la consola de Google Cloud , ve a la página Dataform.

   Ir a Dataform

2. Selecciona tu repositorio.

3. Ve a Configuración y, luego, haz clic en Conectar con Git.

4. En el panel Vincular a un repositorio remoto, en la sección Protocolo de repositorio de Git remoto, selecciona Developer Connect.

5. En el menú de selección de repositorios, elige uno que pertenezca a una conexión existente de Developer Connect.

6. En Dataform, selecciona tu repositorio remoto y la rama predeterminada.

7. Para completar la configuración, haz clic en Vincular.

Conecta un repositorio remoto a través de SSH

Para conectar un repositorio remoto a través de SSH, debes generar una clave SSH y un secreto de Secret Manager. La clave SSH consta de una clave SSH pública y una clave SSH privada. Debes compartir la clave SSH pública con tu proveedor de Git y crear un secreto de Secret Manager con la clave SSH privada. Luego, comparte el secreto con tu agente de servicio predeterminado de Dataform.

Dataform usa el secreto con la clave SSH privada para acceder a tu proveedor de Git y confirmar los cambios en nombre de los desarrolladores. Dataform realiza estas confirmaciones con la dirección de correo electrónico del desarrollador Google Cloud para que puedas saber quién realizó cada confirmación.

Advertencia: La clave SSH privada se comparte entre todos los usuarios de Dataform que usan el agente de servicio o la cuenta de servicio correspondientes. Te recomendamos que crees un usuario de máquina con tu proveedor de Git y que limites su acceso a los repositorios de Git remotos que planeas usar con Dataform. Solo los Google Cloud propietarios de proyectos y los usuarios de Dataform con el rol de administrador de Dataform pueden usar la clave para conectar repositorios. Los usuarios de Dataform no pueden ver la clave en sí.

Para conectar un repositorio remoto a un repositorio de Dataform a través de SSH, sigue estos pasos:

1. En tu proveedor de Git, realiza una de las siguientes acciones:

   Azure DevOps Services

   1. En Azure DevOps Services, crea una clave SSH privada.
   2. Sube la clave SSH pública a tu repositorio de Azure DevOps Services.

   Bitbucket

   1. En Bitbucket, crea una clave SSH privada.
   2. Sube la clave SSH pública a tu repositorio de Bitbucket.

   GitHub

   1. En GitHub, crea una clave SSH privada.
   2. Sube la clave pública SSH de GitHub a tu repositorio de GitHub.

   GitLab

   1. En GitLab, crea una clave SSH privada.
   2. Sube la clave SSH pública de GitLab a tu repositorio de GitLab.

2. En Secret Manager, crea un secreto y establece tu clave SSH privada como el valor del secreto.

   1. Otorga acceso al secreto a tu agente de servicio predeterminado de Dataform.

      Tu agente de servicio de Dataform predeterminado tiene el siguiente formato:

      [e-mail]
      

   2. Otorga el rol de roles/secretmanager.secretAccessor al agente de servicio o a la cuenta de servicio.

3. En la consola de Google Cloud , ve a la página Dataform.

   Ir a Dataform

4. Selecciona el repositorio de Dataform que deseas conectar al repositorio remoto.

5. En la página del repositorio, haz clic en Configuración > Conectar con Git.

6. En el panel Vincular a repositorio remoto, en el campo URL del repositorio de Git remoto, ingresa la URL del repositorio de Git remoto, que termina con .git.

   La URL del repositorio de Git remoto debe tener uno de los siguientes formatos:

   • URL absoluta: ssh://git@{host_name}[:{port}]/{repository_path}. port es opcional.
   • URL similar a SCP: git@{host_name}:{repository_path}.

7. En el campo Default remote branch name, ingresa el nombre de la rama de desarrollo principal del repositorio Git remoto.

8. En el menú desplegable Secreto, selecciona tu secreto para el repositorio Git remoto.

9. En el campo Valor de clave de host público de SSH, ingresa la clave de host público de tu proveedor de Git.

   Azure DevOps Services

   1. Para recuperar la clave de host pública de Azure DevOps Services, ejecuta el siguiente comando en la terminal:

      ssh-keyscan -t rsa ssh.dev.azure.com
      

   2. Copia una de las claves generadas y omite ssh.dev.azure.com del comienzo de la línea. El valor que copies debe tener el siguiente formato:

      ALGORITHM BASE64_KEY_VALUE
      

      Por ejemplo:

      ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7Hr1oTWqNqOlzGJOfGJ4NakVyIzf1rXYd4d7wo6jBlkLvCA4odBlL0mDUyZ0/QUfTTqeu+tm22gOsv+VrVTMk6vwRU75gY/y9ut5Mb3bR5BV58dKXyq9A9UeB5Cakehn5Zgm6x1mKoVyf+FFn26iYqXJRgzIZZcZ5V6hrE0Qg39kZm4az48o0AUbf6Sp4SLdvnuMa2sVNwHBboS7EJkm57XQPVU3/QpyNLHbWDdzwtrlS+ez30S3AdYhLKEOxAG8weOnyrtLJAUen9mTkol8oII1edf7mWWbWVf0nBmly21+nZcmCTISQBtdcyPaEno7fFQMDD26/s0lfKob4Kw8H
      

      Verifica que esta clave siga actualizada con Azure DevOps Services.

   Bitbucket

   1. Para recuperar la clave de host pública de Bitbucket, ejecuta el siguiente comando en la terminal:

      curl https://bitbucket.org/site/ssh
      

   2. El comando devuelve una lista de claves de host públicas. Elige una de las claves de la lista y cópiala, omitiendo bitbucket.org del comienzo de la línea. El valor que copies debe tener el siguiente formato:

      ALGORITHM BASE64_KEY_VALUE
      

      Por ejemplo:

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIazEu89wgQZ4bqs3d63QSMzYVa0MuJ2e2gKTKqu+UUO
      

      Verifica que esta clave siga actualizada con Bitbucket.

   GitHub

   1. Para recuperar la clave de host pública de GitHub, consulta Huellas digitales de la clave SSH de GitHub.

   2. La página contiene una lista de claves de host públicas. Elige uno de ellos y cópialo, omitiendo github.com del principio de la línea. El valor que copies debe tener el siguiente formato:

      ALGORITHM BASE64_KEY_VALUE
      

      Por ejemplo:

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
      

      Verifica que esta clave siga actualizada con GitHub.

   GitLab

   1. Para recuperar la clave de host pública de GitLab, consulta Entradas de known_hosts SSH.

   2. La página contiene una lista de claves de host públicas. Elige uno de ellos y cópialo, omitiendo gitlab.com del principio de la línea. El valor que copies debe tener el siguiente formato:

      ALGORITHM BASE64_KEY_VALUE
      

      Por ejemplo:

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf
      

      Verifica que esta clave siga actualizada con GitLab.

10. Haz clic en Vincular.

Conecta un repositorio remoto a través de HTTPS

Para conectar un repositorio remoto a través de HTTPS, debes crear un secreto de Secret Manager con un token de acceso personal y compartirlo con tu agente de servicio predeterminado de Dataform.

Luego, Dataform usa el token de acceso para acceder a tu proveedor de Git y confirmar los cambios en nombre de los desarrolladores. Dataform realiza estas confirmaciones con la dirección de correo electrónico del desarrollador de Google Cloud para que puedas saber quién realizó cada confirmación.

Advertencia: El token de acceso se comparte entre todos los usuarios de Dataform que usan el agente de servicio o la cuenta de servicio correspondientes. Te recomendamos que crees un usuario de máquina con tu proveedor de Git y que limites su acceso a los repositorios de Git remotos que planeas usar con Dataform. Solo los Google Cloud propietarios de proyectos y los usuarios de Dataform con el rol deadministrador de Dataform pueden usar el token para conectar repositorios. Los usuarios de Dataform no pueden ver el token en sí.

Para conectar un repositorio remoto a un repositorio de Dataform a través de HTTPS, sigue estos pasos:

1. En tu proveedor de Git, haz lo siguiente:

   GitHub

   1. En GitHub, crea un token de acceso personal detallado o un token de acceso personal clásico.

      • Para obtener un token de acceso personal de GitHub detallado, haz lo siguiente:

      1. Selecciona el acceso al repositorio solo para los repositorios seleccionados y, luego, selecciona el repositorio al que deseas conectarte.

      2. Otorga acceso de lectura y escritura al contenido del repositorio.

      3. Establece un tiempo de vencimiento del token adecuado para tus necesidades.

      • Para obtener un token de acceso personal clásico de GitHub, haz lo siguiente:

      1. Otorga a Dataform el permiso repo.

      2. Establece un tiempo de vencimiento del token adecuado para tus necesidades.

   2. Si tu organización usa el inicio de sesión único (SSO) de SAML, autoriza el token.

   GitLab

   1. En GitLab, crea un token de acceso personal de GitLab.

   2. Asigna el nombre dataform al token.

      El token de acceso personal de GitLab debe llamarse dataform.

   3. Otorga a Dataform los permisos api, read_repository y write_repository.

   4. Establece un tiempo de vencimiento del token adecuado para tus necesidades.

2. En Secret Manager, crea un secreto que contenga el token de acceso personal de tu repositorio remoto.

3. Otorga acceso al secreto a tu agente de servicio predeterminado de Dataform.

   Tu agente de servicio de Dataform predeterminado tiene el siguiente formato:

   [e-mail]
   

   1. Otorga el rol roles/secretmanager.secretAccessor al agente de servicio.

4. En la consola de Google Cloud , ve a la página Dataform.

   Ir a Dataform

5. Selecciona el repositorio de Dataform que deseas conectar al repositorio remoto.

6. En la página del repositorio, haz clic en Configuración > Conectar con Git.

7. En el panel Vincular a repositorio remoto, en el campo URL del repositorio de Git remoto, ingresa la URL del repositorio de Git remoto, que termina con .git.

   La URL del repositorio de Git remoto no puede contener nombres de usuario ni contraseñas.

8. En el campo Default remote branch name, ingresa el nombre de la rama de desarrollo principal del repositorio Git remoto.

9. En el menú desplegable Secreto, selecciona tu secreto para el repositorio Git remoto.

10. Haz clic en Vincular.

Edita la conexión del repositorio remoto

Para editar una conexión entre un repositorio de Dataform y un repositorio de Git remoto, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página Dataform.

   Ir a Dataform

2. Haz clic en el repositorio que deseas editar.

3. En la página del repositorio, haz clic en Configuración > Editar conexión de Git.

4. En el panel Link to remote repository, edita la configuración de conexión.

5. Haz clic en Actualizar.

¿Qué sigue?

• Para obtener más información sobre los repositorios de Dataform, consulta Crea un repositorio.

• Para crear un lugar de trabajo de desarrollo, consulta Crea un lugar de trabajo.

• Para obtener información sobre cómo solucionar problemas con las conexiones de repositorios remotos, consulta Soluciona problemas de Dataform.