Configurar a personalização de código do Gemini Code Assist

Observação: a personalização de código do Gemini Code Assist está disponível apenas no Gemini Code Assist Enterprise. Para mais informações, consulte Recursos compatíveis com o Gemini Code Assist.

Neste documento, descrevemos como configurar a personalização de código do Gemini Code Assist no console do Google Cloud , com a Google Cloud CLI ou com o Terraform conectando o Gemini Code Assist aos seus repositórios de código particulares. Com o recurso de personalização de código do Gemini Code Assist, você recebe recomendações de código que usam as bibliotecas internas, APIs particulares e estilo de programação da sua organização.

Para configurar a personalização de código do Gemini Code Assist no console Google Cloud , consulte Configurar a personalização de código do Gemini Code Assist.

Antes de começar

1. Configure o Gemini Code Assist com uma assinatura Enterprise.

2. Verifique se você tem os seguintes papéis do Identity and Access Management (IAM) no projeto proprietário da assinatura:

   • Administrador de índices do repositório de código (roles/cloudaicompanion.codeRepositoryIndexesAdmin)
   • Usuário do Gemini para Google Cloud (roles/cloudaicompanion.user)

3. Crie ou configure contas de usuário. Todos os desenvolvedores na sua organização que usam o Gemini Code Assist precisam ter uma identidade de usuário no Google Cloud com permissão para acessar seu projeto Google Cloud . Para mais informações, consulte Conceder papéis no console do Google Cloud . Verifique se cada usuário tem os seguintes papéis:

   • Usuário do Gemini para Google Cloud
   • Usuário de grupos do repositório

Escolher quais repositórios são indexados

Como prática recomendada, indexe repositórios com as seguintes características:

• Código com estilo ou estrutura semelhante ao que você quer que seus desenvolvedores escrevam.
• Bibliotecas ou APIs particulares que você quer chamar da sua base de código atual.

Opcional: escolha quais arquivos não serão indexados

Por padrão, a personalização de código indexa todos os arquivos de código compatíveis nos repositórios especificados.

Para evitar a exposição de código que você não quer indexar, use padrões de ramificação para controlar o acesso ao seu índice e use uma ramificação estável, como main.

Também é possível excluir arquivos do índice criando um arquivo .aiexclude.

Configurar a personalização de código do Gemini Code Assist

Selecione uma das seguintes opções:

Console

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

   Acessar os produtos do Gemini

   A página Produtos do Gemini é carregada.

2. No menu de navegação, clique em Personalização de código.

   A página Personalização de código é carregada.

3. Criar um índice. A personalização de código usa um índice para analisar e fazer o parsing do seu repositório, oferecendo sugestões e pesquisas de geração de código mais rápidas.

   1. Clique em Criar e configure os detalhes do índice:

      • Selecione a região configurada no Developer Connect no seu projeto Google Cloud .
      • Insira um nome para o índice. Anote o nome do índice. Você vai precisar dele em várias etapas deste documento.

   2. Clique em Criar.

   A criação do índice geralmente leva 30 minutos, mas pode levar até uma hora. Quando a indexação for concluída, você vai receber uma notificação no console Google Cloud .

   O Google limita o número de índices de repositório de código a um para cada projeto e organização.

4. Controle o acesso ao seu índice usando grupos de repositórios.

   Um grupo de repositórios é um contêiner para a configuração de indexação, que inclui repositórios e padrões de ramificação. Os grupos de repositórios são projetados para controle granular do IAM, aos desenvolvedores acesso aos dados indexados desses grupos, em que eles têm a permissão cloudaicompanion.repositoryGroups.use.

   Os grupos de repositórios contêm repositórios ou links do Developer Connect do mesmo projeto e local.

5. Na página Personalização de código para o Gemini Code Assist, clique em Adicionar repositórios e selecione Adicionar repositórios de origem.

   Uma lista mostra os repositórios atuais no Developer Connect para a região que você configurou na etapa anterior para criar o índice.

   Se você precisar adicionar novos repositórios ao grupo, clique em Vincular repositório e siga as etapas no console do Google Cloud .

   Além disso, é possível selecionar e editar um ou mais repositórios para adicionar uma nova ramificação.

6. Selecione o grupo de repositórios a que você quer adicionar novos repositórios. Ou clique em Criar um grupo de repositórios para criar e configurar um novo grupo.

7. Para começar a indexar os repositórios selecionados, clique em Indexar.

   O tempo de indexação varia de acordo com o tamanho dos repositórios.

CLI

1. Verifique se você configurou o Developer Connect e se conectou ao repositório:
   • GitHub.com
   • GitLab.com
   • Bitbucket.org

2. Em um ambiente shell, execute o comando gcloud components update para verificar se você atualizou todos os componentes instalados da CLI gcloud para a versão mais recente. Para esta etapa, instale e inicialize a CLI gcloud ou use o Editor do Cloud Shell.

   gcloud components update
   

3. Criar um índice. A personalização de código usa um índice para analisar e fazer o parsing do seu repositório, oferecendo sugestões e pesquisas de geração de código mais rápidas.

   1. Para criar o índice, em um ambiente shell, use o comando gemini code-repository-indexes create:

      gcloud gemini code-repository-indexes create INDEX_NAME \
          --project=PROJECT_ID \
          --location=REGION
      

      Substitua:

      • INDEX_NAME: o nome do índice. Importante: Anote o nome do índice. Ele é necessário para várias etapas deste documento.
      • PROJECT_ID: o ID do projeto do Google Cloud .
      • REGION: a região configurada no Developer Connect no seu projeto Google Cloud .

      A criação do índice geralmente leva 30 minutos, mas pode levar até uma hora.

      O Google limita o número de índices de repositório de código a um para cada projeto e organização.

4. Controle o acesso ao seu índice usando grupos de repositórios. Um grupo de repositórios é um contêiner para a configuração de indexação, que inclui repositórios e padrões de ramificação. Os grupos de repositórios são projetados para controle granular do IAM, aos desenvolvedores acesso aos dados indexados desses grupos, em que eles têm a permissão cloudaicompanion.repositoryGroups.use.

   Os grupos de repositórios contêm repositórios ou links do Developer Connect do mesmo projeto e local.

   Os administradores realizam as seguintes ações:

   • Crie o recurso de índice do repositório de código.
   • No mesmo projeto e local, configure uma nova conexão do Developer Connect.
   • Vincule repositórios Git na conexão.
   • Receba os nomes de recursos dos links, escolha o padrão de ramificação para indexar cada link e coloque-o em um ou vários grupos de repositórios.

   Para criar um grupo de repositórios em um ambiente shell, use o comando gemini code-repository-indexes repository-groups create:

   gcloud gemini code-repository-indexes repository-groups create REPOSITORY_GROUP \
       --project=PROJECT_ID \
       --location=REGION \
       --code-repository-index=INDEX_NAME \
       --repositories='[{"resource": "REPOSITORY_RESOURCE_NAME", "branchPattern": "BRANCH_NAMES"}]'
   

   Observação: você pode usar expressões regulares na sintaxe RE2 para especificar nomes de ramificação.

   Substitua:

   • REPOSITORY_GROUP: nome do grupo de repositórios, como default.
   • REPOSITORY_RESOURCE_NAME: nome do repositório na conexão do Developer Connect. Para encontrar o nome do repositório, acesse a página Repositórios Git no console do Google Cloud e, na guia Repositórios, procure o ID da conexão na coluna Conexão da tabela. Para copiar o nome do recurso, clique no menu more_vert para mais opções e selecione Copiar caminho do recurso.
   • BRANCH_NAMES: nome das ramificações que você quer indexar, como main|dev.

   Também é possível criar um grupo com repositórios definidos em um arquivo JSON (ou YAML) formatado da seguinte maneira:

   JSON

   [
     {
         "resource": "REPOSITORY_RESOURCE_NAME", "branchPattern": "main|dev"
     },
     {
         "resource": "REPOSITORY_RESOURCE_NAME", "branchPattern": "dev"
     }
   ]
   

   YAML

   - resource: REPOSITORY_RESOURCE_NAME
     branchPattern: main|dev
   
   - resource: REPOSITORY_RESOURCE_NAME
     branchPattern: dev
   

   Para criar um grupo de repositórios com base em um arquivo JSON ou YAML, em um ambiente de shell, use o comando gemini code-repository-indexes repository-groups create:

   JSON

   gcloud gemini code-repository-indexes repository-groups create REPOSITORY_GROUP \
       --project=PROJECT_ID \
       --location=REGION \
       --code-repository-index=INDEX_NAME \
       --repositories=FILEPATH.json
   

   YAML

   gcloud gemini code-repository-indexes repository-groups create REPOSITORY_GROUP \
       --project=PROJECT_ID \
       --location=REGION \
       --code-repository-index=INDEX_NAME \
       --repositories=FILEPATH.yaml
   

   Se preferir, você pode criptografar e controlar seus dados com uma chave de criptografia gerenciada pelo cliente (CMEK) usando o Cloud Key Management Service. Para saber mais sobre o uso de uma CMEK, consulte Criptografar dados com chaves de criptografia gerenciadas pelo cliente.

5. Conceda papéis do IAM ao grupo de repositórios em um projeto.

   Você só recebe sugestões de repositórios no índice. Cada repositório pertence a um ou vários grupos de repositórios. Para acessar sugestões, conceda ao grupo de repositórios o papel do IAM Usuário dos grupos de repositórios do Cloud AI Companion (roles/cloudaicompanion.repositoryGroupsUser), que contém a permissão cloudaicompanion.repositoryGroups.user do IAM necessária, de uma das seguintes maneiras:

   • Conceder aos principais permissão para acessar todo o índice.

   • Conceder acesso a um subconjunto do índice para os principais.

   Índice inteiro

   1. Para vincular uma política do IAM a um projeto em um ambiente de shell, use o comando projects add-iam-policy-binding:

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member='PRINCIPAL' \
          --role='roles/cloudaicompanion.repositoryGroupsUser'
      

      Substitua:

      • PRINCIPAL: o endereço de e-mail do principal que precisa de acesso. Por exemplo, user:[e-mail] para uma pessoa ou group:[e-mail] para um grupo.

      Para ver mais informações, consulte gcloud projects set-iam-policy.

   2. Quando for preciso especificar uma condição, digite None.

   Subconjunto do índice

   É possível criar vários grupos de repositórios e atribuir papéis do IAM a diferentes principais do IAM.

   Para configurar uma política do IAM, prepare o arquivo JSON ou YAML da política, que vai conter uma lista de grupos e papéis atribuídos do IAM. Exemplo:

     bindings:
     - members:
       - group:[e-mail]
       - user:[e-mail]
       role: roles/cloudaicompanion.repositoryGroupsUser
   

   Para mais detalhes e sintaxe, consulte Noções básicas sobre políticas de permissão.

   Observação: é possível atribuir papéis personalizados aos seus grupos do IAM, mas o papel personalizado precisa conter todas as permissões do papel roles/cloudaicompanion.repositoryGroupsUser.

   Para definir a política do IAM, em um ambiente shell, use o comando gemini code-repository-indexes repository-groups set-iam-policy:

     gcloud gemini code-repository-indexes repository-groups set-iam-policy GROUP_NAMEPOLICY_FILE \
         --project=PROJECT_ID \
         --location=REGION \
         --code-repository-index=INDEX_NAME
   

   Substitua:

   • GROUP_NAME: o nome do grupo de repositórios que você criou em uma etapa anterior para controlar o acesso ao índice usando grupos de repositórios.

   • POLICY_FILE: a política do IAM.

     Para ver mais informações, consulte gcloud gemini code-repository-indexes repository-groups set-iam-policy.

Terraform

1. Verifique se você configurou o Developer Connect e se conectou ao seu repositório:

   • GitHub.com
   • GitLab.com
   • Bitbucket.org

2. Criar um índice. A personalização de código usa um índice para analisar e fazer o parsing do seu repositório, oferecendo sugestões e pesquisas de geração de código mais rápidas.

   resource "google_gemini_code_repository_index" "example" {
     location = "REGION"
     code_repository_index_id = "INDEX_NAME"
   }
   

   Substitua:

   • INDEX_NAME: o nome do índice. Importante: Anote o nome do índice. Você vai precisar dele em várias etapas deste documento.
   • PROJECT_ID: o ID do projeto do Google Cloud .
   • REGION: a região configurada no Developer Connect no seu projeto Google Cloud .

   A criação do índice geralmente leva 30 minutos, mas pode levar até uma hora.

   O Google limita o número de índices de repositório de código a um para cada projeto e organização.

3. Controle o acesso ao seu índice usando grupos de repositórios. Um grupo de repositórios é um contêiner para a configuração de indexação, que inclui repositórios e padrões de ramificação. Os grupos de repositórios são projetados para controle granular do IAM, aos desenvolvedores acesso aos dados indexados desses grupos, em que eles têm a permissão cloudaicompanion.repositoryGroups.use.

   Os grupos de repositórios contêm repositórios ou links do Developer Connect do mesmo projeto e local.

   Os administradores realizam as seguintes ações:

   • Crie o recurso de índice do repositório de código.
   • No mesmo projeto e local, configure uma nova conexão do Developer Connect.
   • Vincule repositórios Git na conexão.
   • Receba os nomes de recursos dos links, escolha o padrão de ramificação para indexar cada link e coloque em um ou vários grupos de repositórios.

   resource "google_gemini_repository_group" "example" {
     location = "REGION"
     code_repository_index = "INDEX_NAME"
     repository_group_id = "REPOSITORY_GROUP"
     repositories {
       resource = "REPOSITORY_RESOURCE_NAME"
       branch_pattern = "BRANCH_NAMES"
     }
   }
   

   Observação: é possível usar expressões regulares na sintaxe RE2 para especificar nomes de ramificações.

   Substitua:

   • REPOSITORY_GROUP: nome do grupo de repositórios, como default.
   • REPOSITORY_RESOURCE_NAME: nome do repositório na conexão do Developer Connect. Para encontrar o nome do repositório, acesse a página Repositórios Git no console do Google Cloud e, na guia Repositórios, procure o ID da conexão na coluna Conexão da tabela. Para copiar o nome do recurso, clique no menu more_vert para mais opções e selecione Copiar caminho do recurso.
   • BRANCH_NAMES: nome das ramificações que você quer indexar, como main|dev.

   Também é possível criar um grupo com repositórios definidos em um arquivo JSON (ou YAML) formatado da seguinte maneira:

   JSON

   [
     {
         "resource": "REPOSITORY_RESOURCE_NAME", "branchPattern": "main|dev"
     },
     {
         "resource": "REPOSITORY_RESOURCE_NAME", "branchPattern": "dev"
     }
   ]
   

   YAML

   - resource: REPOSITORY_RESOURCE_NAME
     branchPattern: main|dev
   
   - resource: REPOSITORY_RESOURCE_NAME
     branchPattern: dev
   

   Para criar um grupo de repositórios com base em um arquivo JSON ou YAML, em um ambiente de shell, use o comando gemini code-repository-indexes repository-groups create:

   JSON

   gcloud gemini code-repository-indexes repository-groups create REPOSITORY_GROUP \
       --project=PROJECT_ID \
       --location=REGION \
       --code-repository-index=INDEX_NAME \
       --repositories=FILEPATH.json
   

   YAML

   gcloud gemini code-repository-indexes repository-groups create REPOSITORY_GROUP \
       --project=PROJECT_ID \
       --location=REGION \
       --code-repository-index=INDEX_NAME \
       --repositories=FILEPATH.yaml
   

   Se preferir, você pode criptografar e controlar seus dados com uma chave de criptografia gerenciada pelo cliente (CMEK) usando o Cloud Key Management Service. Para saber mais sobre o uso de uma CMEK, consulte Criptografar dados com chaves de criptografia gerenciadas pelo cliente.

4. Conceda papéis do IAM ao grupo de repositórios em um projeto.

   Você só recebe sugestões de repositórios no índice. Cada repositório pertence a um ou vários grupos de repositórios. Para acessar sugestões, conceda ao grupo de repositórios o papel do IAM Usuário dos grupos de repositórios do Cloud AI Companion (roles/cloudaicompanion.repositoryGroupsUser), que contém a permissão cloudaicompanion.repositoryGroups.user do IAM necessária, de uma das seguintes maneiras:

   • Conceder aos principais permissão para acessar todo o índice.

   • Conceder acesso a um subconjunto do índice para os principais.

   Índice inteiro

   1. Para vincular uma política do IAM a um projeto em um ambiente de shell, use o comando projects add-iam-policy-binding:

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member='PRINCIPAL' \
          --role='roles/cloudaicompanion.repositoryGroupsUser'
      

      Substitua:

      • PRINCIPAL: o endereço de e-mail do principal que precisa de acesso. Por exemplo, user:[e-mail] para uma pessoa ou group:[e-mail] para um grupo.

        Para ver mais informações, consulte gcloud projects set-iam-policy.

   2. Quando for preciso especificar uma condição, digite None.

   Subconjunto do índice

   É possível criar vários grupos de repositórios e atribuir papéis do IAM a diferentes principais do IAM.

     data "google_iam_policy" "foo" {
       binding {
         role = "roles/cloudaicompanion.repositoryGroupsUser"
         members = ["[e-mail]"]
       }
     }
   
     resource "google_gemini_repository_group_iam_policy" "foo" {
       project = "PROJECT_ID"
       location = "REGION"
       code_repository_index_id = "INDEX_NAME"
       repository_group_id = "GROUP_NAME"
       policy_data = data.google_iam_policy.foo.policy_data
     }
   
     data "google_gemini_repository_group_iam_policy" "foo" {
       project = "PROJECT_ID"
       location = "REGION"
       code_repository_index_id = "INDEX_NAME"
       repository_group_id = "GROUP_NAME"
       depends_on = [
         google_gemini_repository_group_iam_policy.foo
       ]
     }
   

   Também é possível criar uma vinculação:

     resource "google_gemini_repository_group_iam_binding" "foo" {
       project = "PROJECT_ID"
       location = "REGION"
       code_repository_index_id = "INDEX_NAME"
       repository_group_id = "GROUP_NAME"
       role = "roles/cloudaicompanion.repositoryGroupsUser"
       members = ["[e-mail]"]
     }
   

   Substitua:

   • GROUP_NAME: o nome do grupo de repositórios que você criou em uma etapa anterior para controlar o acesso ao índice usando grupos de repositórios.

Verificar o status da indexação

Dependendo do número de repositórios que você quer indexar e do tamanho deles, a indexação do conteúdo pode levar até 24 horas. Para repositórios grandes, a indexação pode levar mais tempo. A indexação ocorre uma vez a cada 24 horas, capturando as mudanças feitas no repositório.

1. Pesquise os registros indexing. Para mais informações, consulte Linguagem de consulta do Logging.

   Console

   1. No console Google Cloud , acesse o Explorador de registros.

      Acessar o Explorador de registros

   2. Use o filtro de nomes de registros para ver os registros indexing.

   CLI

   Para pesquisar os registros de indexação, em um ambiente shell, use o comando logging read:

   gcloud logging read "logName="projects/PROJECT_ID/logs/indexing""
   

   Substitua PROJECT_ID pelo ID do projeto em que o grupo de repositórios está localizado.

   Por exemplo, para ver erros nos registros de indexing, execute o seguinte comando:

   gcloud logging read "logName="projects/PROJECT_ID/logs/indexing" AND severity>=ERROR"
   

2. Revise os status de indexação associados, como:

   • Início da indexação do repositório. Por exemplo, Indexing repository REPOSITORY_NAME. Total number of repositories: 10, succeeded: 6, failed: 0.
   • Fim da indexação de repositórios individuais. Por exemplo:
     • Problema resolvido: Successfully finished indexing repository REPOSITORY_NAME. Total number of repositories: 10, succeeded: 7, failed: 0.
     • Falha: Failed to index repository REPOSITORY_NAME. Error: [<error message>]. Total number of repositories: 10, succeeded: 7, failed: 1.
   • Fim da indexação do repositório. Por exemplo:
     • Problema resolvido: Finished indexing process. Repositories attempted: 10. Repositories successfully indexed: 9. Repositories unsuccessfully fetched: 0.
     • Falha: Finished indexing process. Repositories attempted: 10. Repositories successfully indexed: 9. Repositories unsuccessfully fetched: 1. Repositories that were not successfully fetched will be retried in the next run.

   Nos status do índice, REPOSITORY_NAME é o repositório que você quer analisar.

3. Analise os erros de indexação associados, como:

   • Falha ao buscar o repositório.
   • Falha ao listar arquivos do repositório.
   • Falha ao recuperar informações do repositório do índice.
   • Não foi possível recuperar os arquivos do índice.
   • Erro interno.

Usar a personalização de código

Depois de configurar a personalização de código, você vai começar a receber sugestões de conclusão e geração de código que podem ser baseadas em código particular indexado, além de resultados da percepção completa da base de código.

Para saber mais sobre como usar a personalização de código e as práticas recomendadas, consulte Usar a personalização de código.

Desativar a personalização de código

Selecione uma das seguintes opções:

Console

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

   Acessar os produtos do Gemini

   A página Produtos do Gemini é carregada.

2. No menu de navegação, clique em Personalização de código.

   A página Personalização de código é carregada.

3. Para excluir o índice, clique em Excluir índice.

   Uma mensagem de aviso é exibida. Se quiser continuar e excluir o índice, insira o nome dele e clique em Excluir.

CLI

1. Para listar todos os grupos de repositórios do índice atual em um ambiente de shell, use o comando gemini code-repository-indexes repository-groups list:

   gcloud gemini code-repository-indexes repository-groups list --location=REGION \
       --project=PROJECT_ID \
       --code-repository-index=INDEX_NAME --uri
   

   Substitua:

   • REGION: a região configurada no Developer Connect no seu projeto Google Cloud .
   • PROJECT_ID: o ID do projeto do Google Cloud .
   • INDEX_NAME: nome do índice criado em uma etapa anterior.

2. Para excluir um grupo de repositórios do índice atual, use o comando gemini code-repository-indexes repository-groups delete:

   gcloud gemini code-repository-indexes repository-groups delete REPOSITORY_GROUP \
       --location=REGION \
       --project=PROJECT_ID \
       --code-repository-index=INDEX_NAME
   

3. Repita as etapas anteriores para cada grupo de repositórios até excluir todos os grupos do índice.

4. Opcional: para excluir o índice, em um ambiente shell, use o comando gemini code-repository-indexes delete:

   gcloud gemini code-repository-indexes delete INDEX_NAME \
       --location=REGION \
       --project=PROJECT_ID
   

A seguir

• Comece a usar o Gemini Code Assist:
  • VS Code, IntelliJ e outros ambientes de desenvolvimento integrado do JetBrains com suporte: Programar com o Gemini Code Assist
  • Editor do Cloud Shell: Programar com o Gemini Code Assist
  • Cloud Workstations: Programar com o Gemini Code Assist
• Saiba como usar a personalização de código e as práticas recomendadas.
• Saiba como criptografar dados com chaves de criptografia gerenciadas pelo cliente (CMEK).
• Saiba mais sobre o Developer Connect.
• Saiba como e quando o Gemini para Google Cloud usa seus dados.