Connettiti a un repository Git di terze parti

Questo documento mostra come connettere un repository remoto a un repository Dataform. Dopo aver collegato i repository, le modifiche apportate in un workspace di sviluppo Dataform possono essere inviate al repository Git remoto ed estratte da questo.

Importante: Dataform non può connettersi direttamente a un indirizzo IP privato di un host Git on-premise. Per connetterti a un repository in una rete privata, utilizza Developer Connect.

Puoi connettere un repository remoto tramite HTTPS o SSH.

La tabella seguente elenca i provider Git supportati e i metodi di connessione disponibili per i relativi repository:

Provider Git	Metodo di connessione
Azure DevOps Services	SSH
Bitbucket	Developer Connect (consigliato), SSH
GitHub	Developer Connect (consigliato), SSH o HTTPS
GitLab	Developer Connect (consigliato), SSH o HTTPS

Importante: per connettere il repository Git remoto a Dataform utilizzando HTTPS o SSH, verifica che l'host Git abbia un indirizzo IP pubblico. Se l'host Git è configurato solo con un indirizzo IP privato (ad esempio, 10.x.x.x, 172.16.x.x-172.31.x.x o 192.168.x.x) o se si trova dietro un firewall, ti consigliamo di connetterti utilizzando Developer Connect. Se scegli di connettere un repository remoto protetto con un indirizzo IP pubblico utilizzando HTTPS o SSH, devi aggiungere gli intervalli di indirizzi IP di uscita di Dataform alle regole firewall per abilitare la connessione.

Prima di iniziare

1. Se la tua organizzazione o il tuo progetto limita i repository Git remoti con la policy dell'organizzazione dataform.restrictGitRemotes, assicurati che il repository Git remoto sia aggiunto alla lista consentita nella policy prima di creare il repository Dataform che vuoi connettere a un repository remoto. Per saperne di più, consulta Limitare i repository remoti.

2. Seleziona o crea un repository Dataform. Ti servirà in un secondo momento per condividere un secret con l'agente di servizio Dataform predefinito.

   Nota: l'elenco dei repository Dataform include solo i repository creati per lo sviluppo del flusso di lavoro Dataform. I repository per gli asset di BigQuery Studio, come i notebook o le query salvate, vengono gestiti separatamente e non vengono visualizzati in questo elenco.

3. Assicurati di disporre delle autorizzazioni necessarie nel tuo provider Git e che il repository Dataform si trovi in una regione supportata.

4. Abilita l'API Developer Connect.

5. Se colleghi Developer Connect a un repository Bitbucket, assicurati che il token di accesso dell'autorizzatore abbia accesso in scrittura ai tuoi repository in modo che Dataform possa eseguire il push delle modifiche. Per saperne di più, consulta Creare token di accesso.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per connettere un repository Dataform a un repository Git remoto, chiedi all'amministratore di concederti i seguenti ruoli IAM sui repository:

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

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Per connettere un repository remoto utilizzando Developer Connect, concedi i ruoli Developer Connect Token Accessor (roles/developerconnect.tokenAccessor) e Developer Connect Git Proxy User (roles/developerconnect.gitProxyUser) all'agente di servizio Dataform predefinito. L'ID service agent Dataform predefinito ha il seguente formato:

[e-mail]

Connetti un repository remoto utilizzando Developer Connect

Developer Connect semplifica l'integrazione di provider Git esterni con i repository Dataform fornendo un'interfaccia guidata che elimina la necessità di una gestione manuale dei secret.

Utilizzando Developer Connect, puoi connetterti a repository remoti in reti ospitate privatamente, ad esempio ambienti on-premise o virtual private cloud (VPC), senza esporli alla rete internet pubblica.

Importante: il proxy Developer Connect è necessario per connettersi ai repository Git nelle reti private. Quando crei una nuova connessione nella consoleGoogle Cloud , il proxy è abilitato per impostazione predefinita. Per le connessioni ai repository Git accessibili pubblicamente, il proxy è abilitato per impostazione predefinita, ma può essere disattivato facoltativamente. Se utilizzi una connessione esistente creata con gcloud CLI o l'API Developer Connect, assicurati che il proxy sia abilitato se devi accedere a un repository in una rete privata.

Nota: se il repository Dataform e la connessione Developer Connect si trovano in regioni diverse, potrebbero essere applicati costi aggiuntivi per il trasferimento di dati tra regioni quando il proxy Developer Connect è abilitato. Per saperne di più, consulta i prezzi di Developer Connect.

Prepararsi alle connessioni di rete private

Se ti connetti a un repository remoto in una rete privata, assicurati di avere a disposizione le seguenti informazioni e risorse prima di iniziare la configurazione:

• Il namespace e il nome del servizio Service Directory che punta al tuo host Git interno.
• Un certificato dell'autorità di certificazione in formato PEM (con una dimensione massima di 10 KB) se l'host utilizza un'autorità di certificazione privata o autofirmata.
• Verifica che il certificato SSL dell'host Git includa un nome alternativo del soggetto (SAN) che corrisponda all'URI dell'host.

Per maggiori informazioni sulla configurazione delle connessioni per le reti ospitate privatamente, consulta quanto segue:

• Configurare e utilizzare il proxy Developer Connect
• Connettiti a GitHub Enterprise in una rete privata
• Connettiti ai repository GitLab Enterprise in una rete privata
• Connettersi ai repository Bitbucket Data Center ospitati in una rete privata

Crea una nuova connessione Developer Connect

Per connettere un repository remoto a una nuova connessione Developer Connect, seleziona una delle seguenti opzioni:

Bitbucket

1. Nella console Google Cloud , vai alla pagina Dataform.

   Vai a Dataform

2. Seleziona il repository.

3. Vai a Impostazioni e poi fai clic su Connetti con Git.

4. Nel riquadro Link al repository remoto, nella sezione Protocollo repository Git remoto, seleziona Developer Connect.

5. Nel menu di selezione del repository, fai clic su Collega nuovo repository.

6. Nel riquadro Collega repository Git tramite Developer Connect, seleziona Crea nuova connessione.

7. Seleziona Bitbucket come provider.

8. Specifica la regione e il nome della connessione.

9. Fornisci il nome dello spazio di lavoro, il token di accesso dell'Authorizer e il token di accesso in lettura.

10. Fai clic su Continua, poi seleziona i repository remoti da collegare e fai clic su Collega.

11. In Dataform, seleziona il repository remoto e il ramo predefinito.

12. Per completare la configurazione, fai clic su Collega.

GitHub

1. Nella console Google Cloud , vai alla pagina Dataform.

   Vai a Dataform

2. Seleziona il repository.

3. Vai a Impostazioni e poi fai clic su Connetti con Git.

4. Nel riquadro Link al repository remoto, nella sezione Protocollo repository Git remoto, seleziona Developer Connect.

5. Nel menu di selezione del repository, fai clic su Collega nuovo repository.

6. Nel riquadro Collega repository Git tramite Developer Connect, seleziona Crea nuova connessione.

7. Seleziona GitHub come provider.

8. Specifica la regione e il nome della connessione.

9. Per attivare il flusso di autenticazione OAuth, fai clic su Continua e poi procedi nel seguente modo:

   1. Fai clic su Ho capito e continua.
   2. Seleziona Installa l'app GitHub su un altro account GitHub e segui le istruzioni per autorizzare l'accesso al tuo account GitHub e a repository specifici.
   3. Seleziona l'account su cui vuoi installare l'applicazione GitHub Dataform.
   4. Nella sezione Accesso al repository, seleziona se vuoi concedere l'accesso a tutti i repository o solo a una selezione.
   5. Fai clic su Salva.

10. Seleziona i repository remoti da collegare e fai clic su Collega.

11. In Dataform, seleziona il repository remoto e il ramo predefinito.

12. Per completare la configurazione, fai clic su Collega.

GitLab

1. Nella console Google Cloud , vai alla pagina Dataform.

   Vai a Dataform

2. Seleziona il repository.

3. Vai a Impostazioni e poi fai clic su Connetti con Git.

4. Nel riquadro Link al repository remoto, nella sezione Protocollo repository Git remoto, seleziona Developer Connect.

5. Nel menu di selezione del repository, fai clic su Collega nuovo repository.

6. Nel riquadro Collega repository Git tramite Developer Connect, seleziona Crea nuova connessione.

7. Seleziona GitLab come provider.

8. Specifica la regione e il nome della connessione.

9. Fornisci il token di accesso all'API e il token di accesso all'API in lettura. Per informazioni su come farlo, consulta Crea token di accesso.

10. Fai clic su Continua, poi seleziona i repository remoti da collegare e fai clic su Collega.

11. In Dataform, seleziona il repository remoto e il ramo predefinito.

12. Per completare la configurazione, fai clic su Collega.

Utilizza una connessione Developer Connect esistente

Per connettere un repository remoto a una connessione Developer Connect esistente:

1. Nella console Google Cloud , vai alla pagina Dataform.

   Vai a Dataform

2. Seleziona il repository.

3. Vai a Impostazioni, quindi fai clic su Connetti con Git.

4. Nel riquadro Link al repository remoto, nella sezione Protocollo repository Git remoto, seleziona Developer Connect.

5. Nel menu di selezione del repository, seleziona un repository appartenente a una connessione Developer Connect esistente.

6. In Dataform, seleziona il repository remoto e il ramo predefinito.

7. Per completare la configurazione, fai clic su Collega.

Connetti un repository remoto tramite SSH

Per connettere un repository remoto tramite SSH, devi generare una chiave SSH e un secret di Secret Manager. La chiave SSH è composta da una chiave SSH pubblica e una chiave SSH privata. Devi condividere la chiave SSH pubblica con il tuo provider Git e creare un secret di Secret Manager con la chiave SSH privata. Quindi, condividi il secret con il service agent Dataform predefinito.

Dataform utilizza il secret con la chiave SSH privata per accedere al tuo provider Git per eseguire il commit delle modifiche per conto degli sviluppatori. Dataform esegue questi commit utilizzando l'indirizzo email Google Cloud dello sviluppatore, in modo che tu possa sapere chi ha eseguito ogni commit.

Avviso :la chiave SSH privata è condivisa tra tutti gli utenti Dataform che utilizzano l'agente di servizio o il account di servizio corrispondente. Ti consigliamo di creare un utente della macchina con il tuo provider Git e limitarne l'accesso ai repository Git remoti che prevedi di utilizzare con Dataform. Solo i Google Cloud proprietari del progetto e gli utenti Dataform con il ruolo Amministratore Dataform possono utilizzare la chiave per connettere i repository. Gli utenti Dataform non possono visualizzare la chiave stessa.

Per connettere un repository remoto a un repository Dataform tramite SSH, segui questi passaggi:

1. Nel tuo provider Git, esegui una delle seguenti operazioni:

   Azure DevOps Services

   1. In Azure DevOps Services, crea una chiave SSH privata.
   2. Carica la chiave SSH pubblica nel repository Azure DevOps Services.

   Bitbucket

   1. In Bitbucket, crea una chiave SSH privata.
   2. Carica la chiave SSH pubblica nel repository Bitbucket.

   GitHub

   1. In GitHub, crea una chiave SSH privata.
   2. Carica la chiave SSH pubblica di GitHub nel tuo repository GitHub.

   GitLab

   1. In GitLab, crea una chiave SSH privata.
   2. Carica la chiave SSH pubblica di GitLab nel tuo repository GitLab.

2. In Secret Manager, crea un secret e imposta la chiave SSH privata come valore del secret.

   1. Concedi l'accesso al secret all'agente di servizio Dataform predefinito.

      L'agente di servizio Dataform predefinito ha il seguente formato:

      [e-mail]
      

   2. Concedi il ruolo roles/secretmanager.secretAccessor all'agente di servizio o all'account di servizio.

3. Nella console Google Cloud , vai alla pagina Dataform.

   Vai a Dataform

4. Seleziona il repository Dataform che vuoi connettere al repository remoto.

5. Nella pagina del repository, fai clic su Impostazioni > Connetti a Git.

6. Nel riquadro Link al repository remoto, nel campo URL repository Git remoto, inserisci l'URL del repository Git remoto, che termina con .git.

   L'URL del repository Git remoto deve essere in uno dei seguenti formati:

   • URL assoluto: ssh://git@{host_name}[:{port}]/{repository_path}, port è facoltativo.
   • URL simile a SCP: git@{host_name}:{repository_path}.

7. Nel campo Nome ramo remoto predefinito, inserisci il nome del ramo di sviluppo principale del repository Git remoto.

8. Nel menu a discesa Secret, seleziona il secret per il repository Git remoto.

9. Nel campo Valore chiave host pubblica SSH, inserisci la chiave host pubblica del tuo provider Git.

   Azure DevOps Services

   1. Per recuperare la chiave host pubblica di Azure DevOps Services, esegui questo comando nel terminale:

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

   2. Copia una delle chiavi generate, omettendo ssh.dev.azure.com dall'inizio della riga. Il valore che copi deve essere nel seguente formato:

      ALGORITHM BASE64_KEY_VALUE
      

      Ad esempio:

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

      Verifica che questa chiave sia ancora aggiornata con Azure DevOps Services.

   Bitbucket

   1. Per recuperare la chiave host pubblica di Bitbucket, esegui questo comando nel terminale:

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

   2. Il comando restituisce un elenco di chiavi host pubbliche. Scegli una delle chiavi dall'elenco e copiala, omettendo bitbucket.org dall'inizio della riga. Il valore che copi deve avere il seguente formato:

      ALGORITHM BASE64_KEY_VALUE
      

      Ad esempio:

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIazEu89wgQZ4bqs3d63QSMzYVa0MuJ2e2gKTKqu+UUO
      

      Verifica che questa chiave sia ancora aggiornata con Bitbucket.

   GitHub

   1. Per recuperare la chiave host pubblica di GitHub, vedi Impronte delle chiavi SSH di GitHub.

   2. La pagina contiene un elenco di chiavi host pubbliche. Scegli uno dei valori e copialo, omettendo github.com dall'inizio della riga. Il valore che copi deve avere il seguente formato:

      ALGORITHM BASE64_KEY_VALUE
      

      Ad esempio:

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
      

      Verifica che questa chiave sia ancora aggiornata con GitHub.

   GitLab

   1. Per recuperare la chiave host pubblica di GitLab, consulta le voci SSH known_hosts.

   2. La pagina contiene un elenco di chiavi host pubbliche. Scegli uno dei valori e copialo, omettendo gitlab.com dall'inizio della riga. Il valore che copi deve avere il seguente formato:

      ALGORITHM BASE64_KEY_VALUE
      

      Ad esempio:

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf
      

      Verifica che questa chiave sia ancora aggiornata con GitLab.

10. Fai clic su Collega.

Connettere un repository remoto tramite HTTPS

Per connettere un repository remoto tramite HTTPS, devi creare un secret di Secret Manager con un token di accesso personale e condividere il secret con l'agente di servizio Dataform predefinito.

Dataform utilizza quindi il token di accesso per accedere al provider Git e commitare le modifiche per conto degli sviluppatori. Dataform esegue questi commit utilizzando l'indirizzo email Google Cloud dello sviluppatore, in modo da poter sapere chi ha eseguito ogni commit.

Avviso :il token di accesso è condiviso tra tutti gli utenti Dataform che utilizzano il service agent o account di servizio corrispondente. Ti consigliamo di creare un utente della macchina con il tuo provider Git e limitarne l'accesso ai repository Git remoti che prevedi di utilizzare con Dataform. Solo i proprietari dei progetti e gli utenti Dataform con il ruolo Amministratore Dataform possono utilizzare il token per connettere i repository. Google Cloud Gli utenti Dataform non possono vedere il token stesso.

Per connettere un repository remoto a un repository Dataform tramite HTTPS, segui questi passaggi:

1. Nel tuo provider Git:

   GitHub

   1. In GitHub, crea un token di accesso personale granulare o un token di accesso personale classico.

      • Per un token di accesso personale GitHub granulare:

      1. Seleziona l'accesso al repository solo ai repository selezionati, quindi seleziona il repository a cui vuoi connetterti.

      2. Concedi l'accesso in lettura e scrittura ai contenuti del repository.

      3. Imposta un tempo di scadenza del token appropriato alle tue esigenze.

      • Per un token di accesso personale GitHub classico:

      1. Concedi a Dataform l'autorizzazione repo.

      2. Imposta un tempo di scadenza del token appropriato alle tue esigenze.

   2. Se la tua organizzazione utilizza il Single Sign-On (SSO) SAML, autorizza il token.

   GitLab

   1. In GitLab, crea un token di accesso personale GitLab.

   2. Assegna al token il nome dataform.

      Il token di accesso personale di GitLab deve essere denominato dataform.

   3. Concedi a Dataform le autorizzazioni api, read_repository e write_repository.

   4. Imposta un tempo di scadenza del token appropriato alle tue esigenze.

2. In Secret Manager, crea un secret contenente il token di accesso personale del repository remoto.

3. Concedi l'accesso al secret all'agente di servizio Dataform predefinito.

   L'agente di servizio Dataform predefinito ha il seguente formato:

   [e-mail]
   

   1. Concedi il ruolo roles/secretmanager.secretAccessor al service agent.

4. Nella console Google Cloud , vai alla pagina Dataform.

   Vai a Dataform

5. Seleziona il repository Dataform che vuoi connettere al repository remoto.

6. Nella pagina del repository, fai clic su Impostazioni > Connetti a Git.

7. Nel riquadro Link al repository remoto, nel campo URL repository Git remoto, inserisci l'URL del repository Git remoto, che termina con .git.

   L'URL del repository Git remoto non può contenere nomi utente o password.

8. Nel campo Nome ramo remoto predefinito, inserisci il nome del ramo di sviluppo principale del repository Git remoto.

9. Nel menu a discesa Secret, seleziona il secret per il repository Git remoto.

10. Fai clic su Collega.

Modificare la connessione al repository remoto

Per modificare una connessione tra un repository Dataform e un repository Git remoto, segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina Dataform.

   Vai a Dataform

2. Fai clic sul repository che vuoi modificare.

3. Nella pagina del repository, fai clic su Impostazioni > Modifica connessione Git.

4. Nel riquadro Link al repository remoto, modifica le impostazioni di connessione.

5. Fai clic su Aggiorna.

Passaggi successivi

• Per scoprire di più sui repository Dataform, vedi Creare un repository.

• Per creare un workspace di sviluppo, consulta Crea un workspace.

• Per scoprire come risolvere i problemi relativi alle connessioni ai repository remoti, consulta la sezione Risolvere i problemi di Dataform.