Conectar-se a um repositório Git de terceiros

Neste documento, mostramos como conectar um repositório remoto a um repositório do Dataform. Depois que você conecta os repositórios, as mudanças feitas em um espaço de trabalho de desenvolvimento do Dataform podem ser enviadas e puxadas do repositório Git remoto.

É possível conectar um repositório remoto usando o Developer Connect, HTTPS ou SSH.

A tabela a seguir lista os provedores de Git compatíveis e os métodos de conexão disponíveis para os repositórios deles:

Provedor do git	Método de conexão
Serviços de DevOps do Azure	SSH
Bitbucket	Developer Connect (recomendado), SSH
GitHub	Developer Connect (recomendado), SSH ou HTTPS
GitLab	Developer Connect (recomendado), SSH ou HTTPS
Secure Source Manager (pré-lançamento)	Developer Connect

Antes de começar

1. Se a organização ou o projeto restringir repositórios Git remotos com a política da organização dataform.restrictGitRemotes, adicione o repositório Git remoto à lista de permissões na política antes de criar o repositório do Dataform que você quer conectar a um repositório remoto. Para mais informações, consulte Restringir repositórios remotos.

2. Selecione ou crie um repositório do Dataform. Você vai precisar do repositório mais tarde para compartilhar um secret com seu agente de serviço do Dataform padrão.

   Observação :a lista de repositórios do Dataform inclui apenas repositórios criados para o desenvolvimento de fluxos de trabalho do Dataform. Os repositórios de recursos do BigQuery Studio, como notebooks ou consultas salvas, são gerenciados separadamente e não aparecem nessa lista.

3. Verifique se você tem as permissões necessárias no provedor Git e se o repositório do Dataform está em uma região com disponibilidade.

4. Ative a API Developer Connect.

5. Se você estiver conectando o Developer Connect a um repositório do Bitbucket, verifique se o token de acesso do autorizador tem acesso de gravação aos repositórios para que o Dataform possa enviar mudanças. Para mais informações, consulte Criar tokens de acesso.

6. Se você estiver conectando o Developer Connect a uma instância do Secure Source Manager (prévia), verifique se você tem uma instância operacional do Secure Source Manager e conceda ao agente de serviço do Developer Connect o papel roles/securesourcemanager.developerConnectLinker no projeto da instância do Secure Source Manager. Para mais informações, consulte Conectar ao Secure Source Manager.

Requisitos e limitações de conectividade de rede

Antes de conectar seu repositório Git remoto ao Dataform, verifique se a configuração de rede atende aos requisitos do método de conexão escolhido.

Conexões de rede privada

O Dataform não é compatível com conexões diretas com endereços IP privados (por exemplo, 10.x.x.x, 172.16.x.x-172.31.x.x ou 192.168.x.x) de hosts ou repositórios do Git locais em redes privadas usando HTTPS ou SSH. Isso inclui o acesso usando uma nuvem privada virtual (VPC), VPN ou Cloud Interconnect.

Para se conectar a um repositório em uma rede privada ou se o host do Git estiver protegido por um firewall, use o Developer Connect.

Conexões de rede pública

Para conectar um repositório Git remoto usando HTTPS ou SSH, seu host Git precisa ter um endereço IP público.

Se você se conectar a um repositório remoto protegido que tenha um endereço IP público usando HTTPS ou SSH, adicione os intervalos de endereços IP de saída do Dataform necessários às regras de firewall.

Requisitos do VPC Service Controls

Se o projeto usar o VPC Service Controls, defina a política da organização dataform.restrictGitRemotes para se conectar a qualquer repositório Git de terceiros. Para mais informações, consulte Restringir repositórios remotos.

Funções exigidas

Para receber as permissões necessárias para conectar um repositório do Dataform a um repositório remoto do Git, peça ao administrador para conceder a você os seguintes papéis do IAM nos repositórios:

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

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Para conectar um repositório remoto usando o Developer Connect, conceda os papéis Acessador de token do Developer Connect (roles/developerconnect.tokenAccessor) e Usuário de proxy do Git do Developer Connect (roles/developerconnect.gitProxyUser) ao agente de serviço padrão do Dataform. O ID do agente de serviço padrão do Dataform está no seguinte formato:

[e-mail]

Importante :ao conceder papéis ao agente de serviço padrão do Dataform, conceda apenas os papéis predefinidos específicos necessários (como Acessador de token do Developer Connect e Usuário do proxy do Git). Conceder papéis excessivamente permissivos é um risco à segurança.

Conectar um repositório remoto usando o Developer Connect

O Developer Connect simplifica a integração de provedores Git externos com repositórios do Dataform, oferecendo uma interface guiada que elimina a necessidade de gerenciamento manual de secrets.

Com o Developer Connect, é possível se conectar a repositórios remotos em redes hospedadas de maneira privada, como ambientes locais ou nuvens privadas virtuais (VPCs), sem expô-los à Internet pública.

Importante: o proxy do Developer Connect é necessário para se conectar a repositórios Git em redes particulares e a instâncias do Secure Source Manager (pré-lançamento). Quando você cria uma conexão no console do Google Cloud , o proxy é ativado por padrão. Para conexões com repositórios Git acessíveis publicamente, o proxy é ativado por padrão, mas pode ser desativado. Para conexões do Secure Source Manager, o proxy precisa permanecer ativado. O Dataform não poderá acessar um repositório do Secure Source Manager se o proxy estiver desativado. Para acessar um repositório em uma rede privada ou no Secure Source Manager ao usar uma conexão criada com a CLI gcloud ou a API Developer Connect, verifique se o proxy está ativado.

Observação: se o repositório do Dataform e a conexão do Developer Connect estiverem em regiões diferentes, custos adicionais de transferência de dados entre regiões poderão ser aplicados quando o proxy do Developer Connect estiver ativado. Para mais informações, consulte Preços do Developer Connect.

Preparar para conexões de rede particulares

Se você estiver se conectando a um repositório remoto em uma rede privada, verifique se tem as seguintes informações e recursos prontos antes de iniciar a configuração:

• O namespace e o nome do serviço do Diretório de Serviços que aponta para o host interno do Git.
• Um certificado de autoridade de certificação no formato PEM (com tamanho máximo de 10 KB) se o host usar uma autoridade de certificação particular ou autoassinada.
• Verificação de que o certificado SSL do host Git inclui um nome alternativo do assunto (SAN) que corresponde ao URI do host.

Para mais informações sobre como configurar conexões para redes hospedadas de forma particular, consulte:

• Configurar e usar o proxy do Developer Connect
• Conectar-se ao GitHub Enterprise em uma rede particular
• Conectar-se a repositórios do GitLab Enterprise em uma rede privada
• Conectar-se a repositórios do Bitbucket Data Center hospedados em uma rede privada
• Conectar ao Secure Source Manager (pré-lançamento)

Criar uma conexão do Developer Connect

Para conectar um repositório remoto a uma nova conexão do Developer Connect, selecione uma das seguintes opções:

Bitbucket

1. No Google Cloud console, acesse a página Dataform.

   Acesse o Dataform

2. Selecione seu Repositório.

3. Acesse Configurações e clique em Conectar ao Git.

4. No painel Link para o repositório remoto, na seção Protocolo do repositório Git remoto, selecione Developer Connect.

5. No menu de seleção de repositório, clique em Vincular novo repositório.

6. No painel Vincular repositórios Git via Developer Connect, selecione Criar nova conexão.

7. Selecione Bitbucket como seu provedor.

8. Especifique a região e o nome da conexão.

9. Forneça o nome do espaço de trabalho, o token de acesso do autorizador e o token de acesso de leitura.

10. Clique em Continuar, selecione os repositórios remotos para vincular e clique em Vincular.

11. No Dataform, selecione o repositório remoto e a ramificação padrão.

12. Para concluir a configuração, clique em Vincular.

GitHub

1. No Google Cloud console, acesse a página Dataform.

   Acesse o Dataform

2. Selecione seu Repositório.

3. Acesse Configurações e clique em Conectar ao Git.

4. No painel Link para o repositório remoto, na seção Protocolo do repositório Git remoto, selecione Developer Connect.

5. No menu de seleção de repositório, clique em Vincular novo repositório.

6. No painel Vincular repositórios Git via Developer Connect, selecione Criar nova conexão.

7. Selecione GitHub como seu provedor.

8. Especifique a região e o nome da conexão.

9. Para acionar o fluxo de autenticação OAuth, clique em Continuar e faça o seguinte:

   1. Clique em Entendi e continuar.
   2. Selecione Instalar o app GitHub em outra conta do GitHub e siga as instruções para autorizar o acesso à sua conta do GitHub e a repositórios específicos.
   3. Selecione a conta em que você quer instalar o aplicativo do Dataform no GitHub.
   4. Na seção Acesso ao repositório, selecione se você quer dar acesso a todos os repositórios ou apenas a uma seleção deles.
   5. Clique em Salvar.

10. Selecione os repositórios remotos que você quer vincular e clique em Vincular.

11. No Dataform, selecione o repositório remoto e a ramificação padrão.

12. Para concluir a configuração, clique em Vincular.

GitLab

1. No Google Cloud console, acesse a página Dataform.

   Acesse o Dataform

2. Selecione seu Repositório.

3. Acesse Configurações e clique em Conectar ao Git.

4. No painel Link para o repositório remoto, na seção Protocolo do repositório Git remoto, selecione Developer Connect.

5. No menu de seleção de repositório, clique em Vincular novo repositório.

6. No painel Vincular repositórios Git pelo Developer Connect, selecione Criar nova conexão.

7. Selecione GitLab como seu provedor.

8. Especifique a região e o nome da conexão.

9. Informe o token de acesso à API e o token de acesso à API de leitura. Para informações sobre como fazer isso, consulte Criar tokens de acesso.

10. Clique em Continuar, selecione os repositórios remotos para vincular e clique em Vincular.

11. No Dataform, selecione o repositório remoto e a ramificação padrão.

12. Para concluir a configuração, clique em Vincular.

Secure Source Manager

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

1. No Google Cloud console, acesse a página Dataform.

   Acesse o Dataform

2. Selecione seu Repositório.

3. Acesse Configurações e clique em Conectar ao Git.

4. No painel Link para o repositório remoto, na seção Protocolo do repositório Git remoto, selecione Developer Connect.

5. No menu de seleção de repositório, clique em Vincular novo repositório.

6. No painel Vincular repositórios Git pelo Developer Connect, selecione Criar nova conexão.

7. Selecione Secure Source Manager como seu provedor.

8. Especifique a região e o nome da conexão. A região da conexão precisa ser a mesma da instância do Secure Source Manager.

9. Na lista Instância, selecione sua instância do Secure Source Manager.

10. Verifique se o proxy do Developer Connect está ativado. O proxy é ativado por padrão em Mostrar mais e é necessário para que o Dataform acesse repositórios do Secure Source Manager.

11. Clique em Continuar, selecione os repositórios remotos para vincular e clique em Vincular.

12. No Dataform, selecione o repositório remoto e a ramificação padrão.

13. Para concluir a configuração, clique em Vincular.

Usar uma conexão atual do Developer Connect

Para conectar um repositório remoto a uma conexão atual do Developer Connect, faça o seguinte:

1. No Google Cloud console, acesse a página Dataform.

   Acesse o Dataform

2. Selecione seu Repositório.

3. Acesse Configurações e clique em Conectar ao Git.

4. No painel Vincular ao repositório remoto, na seção Protocolo do repositório Git remoto, selecione Developer Connect.

5. No menu de seleção de repositório, selecione um repositório conectado por uma conexão atual do Developer Connect.

   Observação: se você selecionar um repositório conectado por uma conexão do Secure Source Manager (pré-lançamento), ela precisará ter o proxy do Developer Connect ativado. Se o proxy estiver desativado na conexão, o Dataform vai exibir um erro e não poderá acessar o repositório.

6. No Dataform, selecione o repositório remoto e a ramificação padrão.

7. Para concluir a configuração, clique em Vincular.

Conectar um repositório remoto por SSH

Para conectar um repositório remoto por SSH, você precisa gerar uma chave SSH e um secret do Secret Manager. A chave SSH consiste em uma chave SSH pública e uma chave SSH privada. É necessário compartilhar a chave SSH pública com o provedor do Git e criar um secret do Secret Manager com a chave SSH privada. Em seguida, compartilhe o secret com seu agente de serviço padrão do Dataform.

O Dataform usa o secret com a chave SSH privada para fazer login no provedor do Git e confirmar as mudanças em nome dos desenvolvedores. O Dataform faz esses commits usando o endereço de e-mail Google Cloud do desenvolvedor para que você saiba quem fez cada commit.

Aviso: a chave SSH privada é compartilhada entre todos os usuários do Dataform que têm permissões de atuação na conta de serviço personalizada. Recomendamos que você crie um usuário de máquina com seu provedor Git e limite o acesso dele aos repositórios Git remotos que você planeja usar com o Dataform. Somente os proprietários de projetos Google Cloud e os usuários do Dataform com a função deadministrador do Dataform(roles/dataform.admin) podem usar a chave SSH para conectar repositórios. Os usuários do Dataform não podem ver a chave SSH.

Para conectar um repositório remoto a um repositório do Dataform por SSH, siga estas etapas:

1. No seu provedor Git, siga um destes procedimentos:

   Serviços de DevOps do Azure

   1. No Azure DevOps Services, crie uma chave SSH privada.
   2. Faça upload da chave SSH pública para o repositório do Azure DevOps Services.

   Bitbucket

   1. No Bitbucket, crie uma chave SSH privada.
   2. Faça upload da chave SSH pública para o repositório do Bitbucket.

   GitHub

   1. No GitHub, crie uma chave SSH privada.
   2. Faça upload da chave SSH pública do GitHub para seu repositório do GitHub.

   GitLab

   1. No GitLab, crie uma chave SSH privada.
   2. Faça upload da chave SSH pública do GitLab para o repositório do GitLab.

2. No Secret Manager, crie um secret e defina sua chave SSH privada como o valor do secret.

   1. Conceda acesso ao secret ao agente de serviço padrão do Dataform.

      O agente de serviço padrão do Dataform está no seguinte formato:

      [e-mail]
      

   2. Conceda o papel roles/secretmanager.secretAccessor à conta de serviço.

3. No Google Cloud console, acesse a página Dataform.

   Acesse o Dataform

4. Selecione o repositório do Dataform que você quer conectar ao repositório remoto.

5. Na página do repositório, clique em Configurações > Conectar com o Git.

6. No painel Vincular ao repositório remoto, no campo URL do repositório Git remoto, insira o URL do repositório Git remoto, terminando com .git.

   O URL do repositório Git remoto precisa estar em um dos seguintes formatos:

   • URL absoluto: ssh://git@{host_name}[:{port}]/{repository_path}, port é opcional.
   • URL semelhante ao SCP: git@{host_name}:{repository_path}.

7. No campo Nome da ramificação remota padrão, insira o nome da ramificação principal de desenvolvimento do repositório Git remoto.

8. No menu suspenso Secret, selecione o secret do repositório Git remoto.

9. No campo Valor da chave pública do host SSH, insira a chave pública do host do seu provedor Git.

   Serviços de DevOps do Azure

   1. Para recuperar a chave de host pública do Azure DevOps Services, execute o seguinte comando no terminal:

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

   2. Copie uma das chaves geradas, omitindo ssh.dev.azure.com do início da linha. O valor copiado precisa estar no seguinte formato:

      ALGORITHM BASE64_KEY_VALUE
      

      Exemplo:

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

      Verifique se essa chave ainda está atualizada com o Azure DevOps Services.

   Bitbucket

   1. Para recuperar a chave pública do host do Bitbucket, execute o seguinte comando no terminal:

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

   2. O comando retorna uma lista de chaves públicas de host. Escolha uma das chaves da lista e copie-a, omitindo bitbucket.org do início da linha. O valor copiado precisa estar no seguinte formato:

      ALGORITHM BASE64_KEY_VALUE
      

      Exemplo:

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIazEu89wgQZ4bqs3d63QSMzYVa0MuJ2e2gKTKqu+UUO
      

      Verifique se essa chave ainda está atualizada com o Bitbucket.

   GitHub

   1. Para recuperar a chave de host pública do GitHub, consulte as impressões digitais da chave SSH do GitHub.

   2. A página contém uma lista de chaves de host públicas. Escolha um deles e copie-o, omitindo github.com do início da linha. O valor copiado precisa estar no seguinte formato:

      ALGORITHM BASE64_KEY_VALUE
      

      Exemplo:

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
      

      Verifique se essa chave ainda está atualizada com o GitHub.

   GitLab

   1. Para recuperar a chave pública do host do GitLab, consulte Entradas SSH known_hosts.

   2. A página contém uma lista de chaves de host públicas. Escolha um deles e copie-o, omitindo gitlab.com do início da linha. O valor copiado precisa estar no seguinte formato:

      ALGORITHM BASE64_KEY_VALUE
      

      Exemplo:

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf
      

      Verifique se essa chave ainda está atualizada com o GitLab.

10. Clique em Vincular.

Conectar um repositório remoto por HTTPS

Para conectar um repositório remoto por HTTPS, crie um secret do Secret Manager com um token de acesso pessoal e compartilhe o secret com o agente de serviço padrão do Dataform.

Em seguida, o Dataform usa o token de acesso para fazer login no seu provedor Git e fazer commit das mudanças em nome dos desenvolvedores. O Dataform faz esses commits usando o endereço de e-mail do desenvolvedor Google Cloud para que você possa saber quem fez cada commit.

Aviso: o token de acesso particular é compartilhado entre todos os usuários do Dataform que têm permissões de atuação na conta de serviço personalizada. Recomendamos que você crie um usuário de máquina com seu provedor Git e limite o acesso dele aos repositórios Git remotos que você planeja usar com o Dataform. Somente os proprietários de projetos Google Cloud e os usuários do Dataform com o papel de administrador do Dataform (roles/dataform.admin) podem usar o token de acesso para conectar repositórios. Os usuários do Dataform não conseguem ver o token de acesso.

Para conectar um repositório remoto a um repositório do Dataform por HTTPS, siga estas etapas:

1. No seu provedor Git, faça o seguinte:

   GitHub

   1. No GitHub, crie um token de acesso pessoal refinado ou um token de acesso pessoal clássico.

      • Para um token de acesso pessoal refinado do GitHub, faça o seguinte:

      1. Selecione o acesso ao repositório apenas para os repositórios selecionados e, em seguida, selecione o repositório ao qual você quer se conectar.

      2. Conceder acesso de leitura e gravação ao conteúdo do repositório.

      3. Defina um prazo de validade do token adequado às suas necessidades.

      • Para um token de acesso pessoal clássico do GitHub, faça o seguinte:

      1. Conceda ao Dataform a permissão repo.

      2. Defina um prazo de validade do token adequado às suas necessidades.

   2. Se a organização usa o Logon único (SSO) via SAML, autorize o token.

   GitLab

   1. No GitLab, crie um token de acesso pessoal do GitLab.

   2. Nomeie o token dataform.

      O token de acesso pessoal do GitLab precisa ser chamado de dataform.

   3. Conceda ao Dataform as permissões api, read_repository e write_repository.

   4. Defina um prazo de validade do token adequado às suas necessidades.

2. No Secret Manager, crie um secret com o token de acesso pessoal do repositório remoto.

3. Conceda acesso ao secret ao seu agente de serviço padrão do Dataform.

   O agente de serviço padrão do Dataform está no seguinte formato:

   [e-mail]
   

   1. Conceda o papel roles/secretmanager.secretAccessor ao agente de serviço.

4. No Google Cloud console, acesse a página Dataform.

   Acesse o Dataform

5. Selecione o repositório do Dataform que você quer conectar ao repositório remoto.

6. Na página do repositório, clique em Configurações > Conectar com o Git.

7. No painel Vincular ao repositório remoto, no campo URL do repositório Git remoto, insira o URL do repositório Git remoto, terminando com .git.

   O URL do repositório Git remoto não pode conter nomes de usuário ou senhas.

8. No campo Nome da ramificação remota padrão, insira o nome da ramificação de desenvolvimento principal do repositório remoto do Git.

9. No menu suspenso Secret, selecione o secret do repositório Git remoto.

10. Clique em Vincular.

Editar a conexão do repositório remoto

Para editar uma conexão entre um repositório do Dataform e um repositório Git remoto, siga estas etapas:

1. No Google Cloud console, acesse a página Dataform.

   Acesse o Dataform

2. Clique no repositório que você quer editar.

3. Na página do repositório, clique em Configurações > Editar conexão do Git.

4. No painel Link para o repositório remoto, edite as configurações de conexão.

5. Clique em Atualizar.

A seguir

• Para saber mais sobre os repositórios do Dataform, consulte Criar um repositório.

• Para criar um espaço de trabalho de desenvolvimento, consulte Criar um espaço de trabalho.

• Para saber como resolver problemas com conexões de repositório remoto, consulte Resolver problemas do Dataform.