Gerenciar código com repositórios Git do BigQuery Studio

Os repositórios Git do BigQuery Studio permitem que você controle as versões de scripts SQL, notebooks e outros recursos de código diretamente no navegador de arquivos do BigQuery Studio. É possível clonar repositórios Git remotos, gerenciar ramificações e realizar operações do Git sem sair do console do Google Cloud .

Em comparação com os repositórios clássicos, essa integração oferece uma experiência simplificada baseada em pastas na pasta raiz do usuário no painel esquerdo. É possível interagir com os recursos de código como arquivos e diretórios padrão, mantendo uma conexão com um repositório Git remoto.

Limitações

  • Os repositórios Git do BigQuery Studio são restritos ao contexto da pasta raiz do usuário e são destinados ao uso particular. Não compartilhe esses repositórios com outros usuários. Embora esses repositórios apareçam na pasta raiz do usuário, que é uma representação virtual dos seus recursos no projeto, eles são criados tecnicamente no nível do projeto.
  • As operações do sistema de arquivos no local de montagem consomem a cota do Dataform.
  • Repositórios com um grande número de arquivos, arquivos grandes, muitas ramificações ou um histórico de confirmação profundo e complexo levam mais tempo para serem clonados. A operação de clonagem pode exceder o tempo limite da operação, o que impede que o repositório seja criado. Para reduzir o tempo de clonagem de repositórios com históricos de commit profundos, crie um clone superficial. É possível buscar mais commits depois, se necessário.
  • O tamanho dos arquivos de notebook armazenados em uma montagem de repositório Git do BigQuery Studio não pode exceder 30 MB. Se os arquivos tiverem mais de 30 MB, salve-os no armazenamento local do ambiente de execução do Colab, fora do local montado.

  • Quando você faz alterações em um repositório Git fora da montagem, por exemplo, editando ou renomeando arquivos no painel esquerdo, pode levar até 60 segundos para que essas alterações fiquem visíveis na montagem no ambiente de execução do notebook. É possível ajustar essa duração transmitindo o parâmetro CACHE_TTL_SECONDS para o construtor:

      FuseWidget(CACHE_TTL_SECONDS=NUMBER)

    Substitua NUMBER pelo número de segundos em que o cache permanece válido. Diminuir esse valor aumenta a frequência de sincronização e consome a cota do Dataform mais rapidamente.

Antes de começar

Ative a API Developer Connect no projeto do Google Cloud .

Ativar a API

Funções exigidas

Para receber as permissões necessárias para gerenciar o código com os repositórios Git do BigQuery Studio, peça ao administrador para conceder a você o papel do IAM de Usuário do OAuth do Developer Connect (roles/developerconnect.oauthUser) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para gerenciar código com repositórios Git do BigQuery Studio. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para gerenciar códigos com repositórios Git do BigQuery Studio:

  • resourcemanager.projects.get
  • resourcemanager.projects.list
  • developerconnect.operations.list
  • developerconnect.operations.get
  • developerconnect.locations.list
  • developerconnect.locations.get
  • developerconnect.users.startOAuth
  • developerconnect.users.finishOAuth
  • developerconnect.users.fetchAccessToken
  • developerconnect.users.getSelf
  • developerconnect.users.deleteSelf
  • developerconnect.accountConnectors.get
  • developerconnect.accountConnectors.list
  • developerconnect.accountConnectors.gitProxyUse
  • developerconnect.accountConnectors.httpProxyUse
  • developerconnect.accountConnectors.gitProxyRead
  • developerconnect.accountConnectors.gitProxyWrite
  • developerconnect.accountConnectors.httpProxyRead
  • developerconnect.accountConnectors.httpProxyWrite
  • developerconnect.accountConnectors.fetchUserRepositories

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Considerações de segurança para repositórios

Como os recursos de código no BigQuery são alimentados pelo Dataform, considere as seguintes implicações de segurança para usuários com acesso a esses recursos:

  • A visibilidade dos recursos de código é controlada pelas permissões do Dataform no nível do projeto. Os usuários com a permissão dataform.repositories.list, que está incluída nos papéis padrão do BigQuery, como Usuário de jobs do BigQuery, Usuário do BigQuery Studio e Usuário do BigQuery, podem ver todos os recursos de código no painel Explorador do projeto do Google Cloud , independentemente de terem criado esses recursos ou de eles terem sido compartilhados com eles. Para restringir a visibilidade, crie papéis personalizados que excluam a permissão dataform.repositories.list.
  • Todos os secrets compartilhados com o agente de serviço do Dataform podem ser acessados por usuários que podem editar esses recursos. Para proteger suas credenciais, restrinja o acesso de criação e edição a usuários confiáveis e limite os secrets acessíveis ao agente de serviço do Dataform. Para mais informações, consulte Acesso a secrets durante a instalação do pacote.

Para mais informações, consulte Considerações de segurança para permissões do Dataform.

Recomendações de segurança para permissões do Developer Connect

Os repositórios Git do BigQuery Studio usam o Developer Connect para se conectar a repositórios remotos. Além disso, os papéis predefinidos do BigQuery e do Dataform incluem permissões do Developer Connect. Devido a esses recursos de segurança, recomendamos que você faça o seguinte:

  • Use papéis personalizados para aplicar a segregação de funções: se a organização exige uma separação estrita entre as tarefas de análise de dados e o gerenciamento de código-fonte, implante papéis personalizados que omitam as permissões do Developer Connect. Papéis predefinidos, como Usuário do BigQuery (roles/bigquery.user) e Usuário do BigQuery Studio (roles/bigquery.studioUser), incluem permissões do Developer Connect, que permitem que os usuários atribuídos a esses papéis iniciem fluxos do OAuth e façam proxy do tráfego do Git.
  • Aplique proteções com políticas de negação do IAM: aplique políticas de negação no nível da organização para evitar ações sensíveis para grupos de análise amplos. Considere negar a permissão developerconnect.googleapis.com/gitRepositoryLinks.fetchReadWriteToken para evitar a extração de tokens e a permissão developerconnect.googleapis.com/accountConnectors.gitProxyWrite para evitar o acesso de gravação não intencional aos repositórios. Os papéis administrativos, como Administrador do BigQuery (roles/bigquery.admin) e Administrador do BigQuery Studio (roles/bigquery.studioAdmin), incluem permissões de acessador de token que permitem que os participantes recuperem tokens ativos de gerenciamento de código-fonte (SCM) de terceiros em texto simples, como tokens de instalação do app GitHub.
  • Isole projetos de CI/CD sensíveis: mantenha pipelines de CI/CD sensíveis, como o Cloud Build ou a Vertex AI, em projetos dedicados do Google Cloud separados dos ambientes gerais de análise de dados. Como as permissões do Developer Connect têm escopo no nível do projeto, um usuário do BigQuery em um projeto compartilhado de vários locatários pode listar e usar qualquer conexão do Developer Connect nesse projeto para fazer proxy de solicitações do Git, o que pode conceder acesso a repositórios configurados para CI/CD ou automação de infraestrutura.
  • Restringir o acesso a recursos usando as condições do IAM: anexe condições do IAM a vinculações de papéis para restringir as permissões do Developer Connect a recursos específicos. É possível limitar o acesso com base em prefixos de nomes de recursos ou definir o escopo do acesso a recursos específicos do Connection e do GitRepositoryLink. Isso garante que os usuários possam interagir apenas com as conexões do Developer Connect destinadas aos fluxos de trabalho deles.
  • Proteja metadados sensíveis em nomes de recursos: não incorpore credenciais sensíveis, codinomes de projetos ou informações confidenciais em nomes de repositórios, nomes de ramificações ou IDs de conexão. As permissões necessárias para listar esses recursos (developerconnect.connections.list e developerconnect.accountConnectors.list) são concedidas aos papéis padrão do BigQuery. Qualquer pessoa com acesso básico ao projeto pode enumerar esses recursos e descobrir metadados sensíveis.

Criar um repositório Git do BigQuery Studio

Ao criar um repositório Git, considere estes requisitos:

  • A conexão de um repositório Git remoto a um repositório Git pode falhar se o repositório remoto não estiver aberto para a Internet pública, por exemplo, se estiver atrás de um firewall. Nesse caso, adicione os intervalos de endereços IP de saída do Dataform necessários às regras de firewall para permitir conexões com repositórios remotos protegidos.
  • Para criar um repositório Git conectado a um repositório Git remoto que não esteja na lista de permissões da política da organização dataform.restrictGitRemotes, primeiro adicione o repositório Git remoto à lista allowedValues na política e, em seguida, crie o repositório Git. Para mais informações, consulte Restringir repositórios remotos.

Para criar um repositório Git, faça o seguinte:

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

    Acessar o BigQuery

  2. No painel à esquerda, clique em Arquivos para abrir o navegador de arquivos.

    Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

  3. Ao lado do nó raiz do usuário, clique em Ver ações > Criar > Repositório do Git.

  4. Insira o URL do repositório Git remoto.

  5. O BigQuery Studio detecta se um conector de conta do Developer Connect está disponível. Siga uma destas instruções:

    • Se um conector de conta for encontrado, o nome de exibição do repositório Git será preenchido automaticamente. É possível editar esses valores.
    • Se não houver um conector de conta, clique em Criar conector de conta para criar um novo.
    • Se você preferir não usar um conector de conta do Developer Connect, clique em Usar um tipo de conexão diferente para se conectar usando HTTPS ou SSH.

  6. Opcional: para criar um repositório de clone superficial com histórico de commit limitado, clique em Opções avançadas e marque a caixa de seleção Clone superficial.

    1. No campo Profundidade, insira o número de commits a serem recuperados no histórico limitado.

  7. Clique em Conectar.

Editar um arquivo

Para editar um arquivo, clique em um nó de arquivo, como um script SQL ou um notebook, para abrir o arquivo em uma nova guia do editor.

Todas as mudanças feitas são salvas automaticamente.

Gerenciar arquivos

É possível realizar tarefas de gerenciamento padrão usando o menu de ações associado a cada item. Para acessar essas opções, clique em Ver ações ao lado de qualquer diretório ou arquivo.

No nível do diretório, é possível realizar as seguintes tarefas:

  • Criar no repositório: crie novos recursos de código, incluindo consultas SQL, notebooks, telas de dados, preparações de dados, arquivos ou subdiretórios.
  • Fazer upload para o repositório: importe arquivos da sua máquina local para o diretório selecionado.
  • Renomear: mude o nome do diretório.
  • Mover: realoca o diretório. Só é possível mover um diretório para outro local no mesmo repositório Git. Para mais informações, consulte Mover um diretório ou arquivo.
  • Excluir: remova permanentemente o diretório e todo o conteúdo dele do seu espaço de trabalho local. Para mais informações, consulte Excluir um diretório ou arquivo.

No nível do arquivo, é possível realizar as seguintes tarefas:

  • Abrir ou Abrir em: visualize o arquivo no editor padrão ou em um aplicativo específico, por exemplo, um ambiente de notebook específico.
  • Renomear: mude o nome do arquivo.
  • Copiar: cria uma cópia do arquivo. Só é possível copiar arquivos para diretórios no mesmo repositório Git. Para mais informações, consulte Copiar um arquivo.
  • Mover: realoque o arquivo para outro diretório no mesmo repositório Git. Para mais informações, consulte Mover um diretório ou arquivo.
  • Fazer o download: salve uma cópia do arquivo na sua máquina local.
  • Excluir: remova o arquivo do espaço de trabalho. Para mais informações, consulte Excluir um diretório ou arquivo.

Mover um diretório ou arquivo

Para mover um diretório ou arquivo em um repositório Git do BigQuery Studio, faça o seguinte:

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

    Acessar o BigQuery

  2. No painel à esquerda, clique em Arquivos para abrir o navegador de arquivos.

  3. Dependendo de quantos recursos você quer mover, siga um destes procedimentos:

    • Para mover um único recurso, no navegador de arquivos, selecione o diretório ou arquivo que você quer mover e clique em Ver ações > Mover.
    • Para mover vários recursos, na visualização de pastas, marque a caixa de seleção ao lado de cada recurso que você quer mover e clique em Mover.

  4. Na caixa de diálogo de movimentação de recursos, selecione o diretório de destino no mesmo repositório Git. Só é possível mover recursos para locais no mesmo repositório Git.

  5. Clique em Mover.

Copiar um arquivo

Para copiar um arquivo em um repositório Git do BigQuery Studio, faça o seguinte:

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

    Acessar o BigQuery

  2. No painel à esquerda, clique em Arquivos para abrir o navegador de arquivos.

  3. Selecione o arquivo que você quer copiar.

  4. Clique em Conferir ações > Copiar.

  5. Na caixa de diálogo de cópia de recurso, selecione o diretório de destino no mesmo repositório Git. Só é possível copiar arquivos para locais no mesmo repositório Git.

  6. Clique em Copiar.

Excluir um diretório ou arquivo

Para excluir um diretório ou arquivo em um repositório Git do BigQuery Studio, faça o seguinte:

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

    Acessar o BigQuery

  2. No painel à esquerda, clique em Arquivos para abrir o navegador de arquivos.

  3. Dependendo de quantos recursos você quer excluir, siga um destes procedimentos:

    • Para excluir um único recurso, no navegador de arquivos, selecione o diretório ou arquivo que você quer excluir e clique em Ver ações > Excluir.
    • Para excluir vários recursos, na visualização de pastas, marque a caixa de seleção ao lado de cada recurso que você quer excluir e clique em Excluir.

  4. Na caixa de diálogo de confirmação, clique em Excluir.

Confirmar e enviar mudanças

Para sincronizar as edições locais com o repositório remoto, faça o seguinte:

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

    Acessar o BigQuery

  2. No painel à esquerda, clique em Controle de origem para abrir o painel Controle de origem.

  3. Opcional: passe o cursor sobre um arquivo modificado e clique em Mostrar diferença para ver uma comparação linha por linha entre a versão local e a última versão confirmada.

  4. No campo Mensagem de commit, insira uma descrição das mudanças.

  5. Clique em Fazer commit. As mudanças são salvas no histórico do Git da ramificação local.

  6. Clique em Push to remote. As mudanças são sincronizadas com o repositório remoto.

Fazer checkout de uma nova ramificação

É possível gerenciar ramificações locais e criar uma nova com base em uma ramificação de rastreamento local ou remota.

No painel Controle de origem, na seção Ramificações, é possível ver as ramificações locais que foram extraídas. O rótulo CURRENT indica a ramificação ativa, e o rótulo DEFAULT indica a ramificação padrão do repositório.

Para verificar uma nova ramificação, faça o seguinte:

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

    Acessar o BigQuery

  2. Abra o painel Controle de origem.

  3. Na seção Ramificações, ao lado de Ramificações, clique em Ações > Confira a nova ramificação.

  4. No menu Ramificação de origem, selecione a ramificação em que você quer basear sua nova ramificação, por exemplo, origin/main.

  5. No campo Nome da ramificação, insira um nome para a nova ramificação.

  6. Clique em Trocar ramificação. O BigQuery Studio verifica primeiro a ramificação de origem. Se o nome da ramificação fornecido indicar uma nova ramificação, ela será criada com base nessa origem. A nova ramificação se torna a ativa, e o conteúdo do repositório Git é atualizado automaticamente para refletir o estado da ramificação de check-out.

Para mudar para uma ramificação atual, faça o seguinte:

  1. No painel Controle de origem, abra a seção Ramificações.
  2. Ao lado da ramificação que você quer usar, clique em Ações > Mudar para BRANCH_NAME.

Conferir histórico de confirmação

É possível ver o histórico de commits da ramificação ativa. Se o repositório foi criado como um clone superficial, o painel Histórico de commits da ramificação vai mostrar um banner informativo indicando que o repositório tem um histórico de commits limitado. Você pode expandir o histórico local buscando mais confirmações.

Para ver o histórico de commits, faça o seguinte:

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

    Acessar o BigQuery

  2. Abra o painel Controle de origem.

  3. Ao lado do botão de ação principal do controle de versões, clique na seta suspensa e em Ver histórico de commits.

    O painel Histórico de commit da ramificação é aberto, mostrando o histórico de commit da sua ramificação ativa.

  4. Opcional: para buscar commits do repositório remoto, siga um destes procedimentos:

    • Ao lado do botão de ação principal do controle de versões, clique na seta suspensa e em Buscar do remoto.
    • No painel Histórico de commits da ramificação, clique em Buscar.

    Para repositórios de clone superficial, na caixa de diálogo Buscar (clone superficial), no campo Mais commits para buscar, insira o número de commits adicionais a serem recuperados do histórico do repositório.

    Se você inserir 0, nenhum commit histórico adicional será recuperado, mas o BigQuery Studio vai realizar uma busca padrão para sincronizar referências e metadados remotos.

  5. Clique em Buscar.

    Você pode repetir a busca conforme necessário até que todos os commits sejam recuperados.

Excluir um repositório Git

A exclusão de um repositório Git do BigQuery Studio remove o repositório e todo o conteúdo dele do ambiente do BigQuery Studio.

Para excluir um repositório Git, faça o seguinte:

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

    Acessar o BigQuery

  2. Exclua o repositório usando um dos seguintes métodos:

    • Para excluir o repositório do navegador de arquivos, no painel à esquerda, clique em Arquivos. Ao lado do repositório Git que você quer excluir, clique em Ver ações > Excluir.
    • Para excluir o repositório do painel de controle, no cabeçalho do painel Controle de origem, clique em Opções de controle de origem > Excluir REPOSITORY_NAME.

  3. Na caixa de diálogo de confirmação, clique em Excluir.

Acessar arquivos de notebook em uma montagem de repositório Git

Ao acessar um notebook em um repositório Git do BigQuery Studio, é possível montar o repositório Git do host no ambiente de execução do notebook. Uma montagem é uma conexão que faz com que o repositório Git remoto apareça como se fosse um repositório local no ambiente de execução do notebook. Isso permite que o notebook acesse, leia e grave diretamente em outros arquivos e scripts de consulta no mesmo repositório.

Montar o repositório Git

Para montar o repositório Git, execute o seguinte código Python no notebook:

from google_dataform_fuse_widget import FuseWidget
FuseWidget()

Quando o notebook é conectado à montagem, as seguintes mudanças ocorrem:

  • O diretório de trabalho atual da sessão do notebook é atualizado para refletir o caminho relativo no repositório Git. Isso garante que o acesso a arquivos baseado em caminho funcione automaticamente.
  • O caminho do repositório Git no ambiente de execução do notebook é adicionado ao caminho do sistema Python, o que permite usar instruções de importação padrão do Python para carregar scripts e arquivos de consulta do repositório Git diretamente no notebook.

Gerenciar a montagem e a conexão

Use os seguintes controles para gerenciar seu espaço de trabalho:

  • Montar espaço de trabalho: inicia o processo de montagem do repositório Git. A montagem é um recurso compartilhado. Portanto, se vários notebooks no mesmo ambiente de execução do Colab usarem o mesmo repositório Git, eles usarão a mesma montagem.
  • Desmontar espaço de trabalho: interrompe o processo de montagem do repositório Git. Ao desmontar o espaço de trabalho, a montagem fica indisponível para todos os notebooks no ambiente de execução do Colab que o estavam usando.
  • Conectar espaço de trabalho: inicia a conexão com uma montagem ativa para a sessão atual do notebook. A conexão atualiza o diretório de trabalho e o caminho do sistema do notebook para incluir o repositório Git, o que permite acessar e importar arquivos.
  • Desconectar espaço de trabalho: encerra a conexão de montagem da sessão atual do notebook e a redefine para o estado padrão. A desconexão não afeta o status da conexão de montagem de outras sessões de notebook ativas. Para encerrar a conexão da sessão, recomendamos usar o botão Desconectar espaço de trabalho.
  • Reparo: restaura uma montagem ou conexão para um estado íntegro se ela se tornar inutilizável.

Depois de inicializar a montagem, consulte a barra de Status para ver a integridade em tempo real e o caminho ativo da montagem. Os estados de integridade possíveis são Conectado, Montado, Interrompido e Não íntegro.

A seguir