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

Este documento descreve como configurar a personalização de código do Gemini Code Assist na Google Cloud consola, com a CLI do Google Cloud ou com o Terraform, associando o Gemini Code Assist aos seus repositórios de código privados. A funcionalidade de personalização de código do Gemini Code Assist permite-lhe receber recomendações de código, que são baseadas nas bibliotecas internas, nas APIs privadas e no estilo de programação da sua organização.

Antes de começar

  1. Configure o Gemini Code Assist com uma subscrição Enterprise.

  2. Verifique se tem as seguintes funções de gestão de identidade e de acesso (IAM) no projeto proprietário da subscrição:

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

  3. Criar ou configurar contas de utilizador. Todos os programadores na sua organização que usam o Gemini Code Assist têm de ter uma identidade de utilizador no Google Cloud que tenha autorização para aceder ao seu projeto Google Cloud . Para mais informações, consulte o artigo Conceda funções na Google Cloud consola. Verifique se cada utilizador tem as seguintes funções:

  4. A funcionalidade de personalização de código usa o Developer Connect para aceder e indexar os seus repositórios privados. Certifique-se de que a região do Developer Connect onde a ligação do repositório do Developer Connect está localizada também é uma localização suportada para a personalização de código. Não é possível usar a funcionalidade de personalização de código se a ligação do Developer Connect estiver numa região não suportada. Para ver a lista de regiões suportadas, consulte as limitações de personalização de código.

Escolha os repositórios que são indexados

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

  • Código com um estilo ou uma estrutura semelhantes ao que quer que os seus programadores escrevam.
  • APIs ou bibliotecas privadas que quer chamar a partir da sua base de código atual.

Opcional: escolha os ficheiros que não são indexados

Por predefinição, a personalização de código indexa todos os ficheiros de código suportados nos repositórios especificados.

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

Em alternativa, também pode excluir ficheiros do índice criando um ficheiro .aiexclude.

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

Selecione uma das seguintes opções:

Consola

  1. Na Google Cloud consola, aceda à página Personalização de código.

    Aceda à personalização de código para o Gemini Code Assist

    A página Personalização de código para o Gemini Code Assist é carregada.

  2. Crie um índice. A personalização do código baseia-se num índice para analisar e processar o seu repositório de modo a apresentar 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 Google Cloud projeto.
      • Introduza um nome para o índice. Tome nota do nome do índice. Precisa dela para vários passos neste documento.

    2. Clique em Criar.

    Geralmente, a criação do índice demora 30 minutos, mas pode demorar até uma hora. Quando a indexação estiver concluída, recebe uma notificação na Google Cloud consola.

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

  3. Controle o acesso ao seu índice através de grupos de repositórios.

    Um grupo de repositórios é um contentor para a configuração de indexação, que inclui repositórios e os respetivos padrões de ramificação. Os grupos de repositórios são concebidos para um controlo de IAM detalhado, dando aos programadores acesso aos dados indexados desses grupos, onde têm a autorização cloudaicompanion.repositoryGroups.use.

    Os grupos de repositórios contêm repositórios do Developer Connect ou links do mesmo projeto e localização.

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

    É apresentada uma lista dos repositórios existentes no Developer Connect para a região que configurou no passo anterior para criar o índice.

    Se precisar de adicionar novos repositórios ao grupo de repositórios, clique em Associar repositório e siga os passos na Google Cloud consola.

    Além disso, pode selecionar e, em seguida, editar um ou mais repositórios para adicionar um novo ramo.

  5. Selecione o grupo de repositórios ao qual quer adicionar novos repositórios. Em alternativa, clique em Criar um novo grupo de repositórios para criar e configurar um novo grupo de repositórios.

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

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

CLI

  1. Confirme se configurou o Developer Connect e se tem ligação ao seu repositório:

  2. Num ambiente de shell, execute o comando gcloud components update para verificar se atualizou todos os componentes instalados da CLI gcloud para a versão mais recente. Para este passo, pode instalar e inicializar a CLI gcloud ou usar o Editor do Cloud Shell.

    gcloud components update

  3. Crie um índice. A personalização do código baseia-se num índice para analisar e processar o seu repositório de modo a apresentar sugestões e pesquisas de geração de código mais rápidas.

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

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

      Substitua o seguinte:

      • INDEX_NAME: o nome do índice. Importante: Tome nota do nome do índice. Precisa dele para vários passos neste documento.
      • PROJECT_ID: o ID do seu Google Cloud projeto.
      • REGION: a região configurada no Developer Connect no seu Google Cloud projeto.

      Geralmente, a criação do índice demora 30 minutos, mas pode demorar até uma hora.

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

  4. Controle o acesso ao seu índice através de grupos de repositórios. Um grupo de repositórios é um contentor para a configuração de indexação, que inclui repositórios e os respetivos padrões de ramificações. Os grupos de repositórios são concebidos para um controlo detalhado da IAM, dando aos programadores acesso aos dados indexados desses grupos, onde têm a autorização cloudaicompanion.repositoryGroups.use.

    Os grupos de repositórios contêm repositórios do Developer Connect ou links do mesmo projeto e localização.

    Os administradores realizam as seguintes ações:

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

    Para criar um grupo de repositórios, num ambiente de 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"}]'

    Substitua o seguinte:

    • REPOSITORY_GROUP: nome do grupo do repositório, como default.
    • REPOSITORY_RESOURCE_NAME: nome do repositório na ligação do Developer Connect. Para encontrar o nome do repositório, aceda à página Repositórios Git na consola e, no separador Repositórios, procure o ID da associação na coluna Associação na tabela. Google Cloud Para copiar o nome do recurso, clique no menu more_vert para ver mais opções e selecione Copiar caminho do recurso.
    • BRANCH_NAMES: nome das filiais que quer indexar, como main|dev.

    Também pode criar um grupo de repositórios com repositórios definidos num ficheiro JSON (ou YAML), formatado da seguinte forma:

    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 num ficheiro JSON ou YAML, num 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, pode encriptar e controlar os seus dados com uma chave de encriptação gerida pelo cliente (CMEK) através do Cloud Key Management Service. Para saber mais sobre a utilização de uma CMEK, consulte o artigo Encriptar dados com chaves de encriptação geridas pelo cliente.

  5. Conceda funções de IAM ao grupo de repositórios num projeto.

    Só recebe sugestões de repositórios no índice. Cada repositório pertence a um ou vários grupos de repositórios. Para aceder às sugestões, tem de conceder a função de IAM de utilizador dos grupos de repositórios do Cloud AI Companion (roles/cloudaicompanion.repositoryGroupsUser), que contém a autorização de IAM cloudaicompanion.repositoryGroups.user necessária, ao grupo de repositórios de uma das seguintes formas:

    • Conceder autorização aos responsáveis para acederem ao índice completo.

    • Conceder aos principais acesso a um subconjunto do índice.

    Índice completo

    1. Para associar uma política IAM a um projeto, num 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 o seguinte:

      • PRINCIPAL: o endereço de email do diretor que precisa de acesso, por exemplo, user:test-user@gmail.com para um indivíduo ou group:admins@example.com para um grupo.

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

    2. Quando lhe for pedido para especificar uma condição, introduza None.

    Subconjunto do índice

    Pode criar vários grupos de repositórios e atribuir funções do IAM a diferentes responsáveis do IAM.

    Para configurar uma política de IAM, tem de preparar o ficheiro JSON ou YAML da política de IAM, que vai conter uma lista de grupos de IAM e funções atribuídas. Por exemplo:

      bindings:
  - members:
    - group:my-group@example.com
    - user:test-user@example.com
    role: roles/cloudaicompanion.repositoryGroupsUser

    Para ver mais detalhes e sintaxe, consulte o artigo Compreender as políticas de autorização.

    Para definir a política IAM, num ambiente de 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 o seguinte:

Terraform

  1. Confirme se configurou o Developer Connect e se tem ligação ao seu repositório:

  2. Crie um índice. A personalização do código baseia-se num índice para analisar e processar o seu repositório de modo a apresentar 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 o seguinte:

    • INDEX_NAME: o nome do índice. Importante: Tome nota do nome do índice. Precisa dele para vários passos neste documento.
    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • REGION: a região configurada no Developer Connect no seu Google Cloud projeto.

    Geralmente, a criação do índice demora 30 minutos, mas pode demorar até uma hora.

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

  3. Controle o acesso ao seu índice através de grupos de repositórios. Um grupo de repositórios é um contentor para a configuração de indexação, que inclui repositórios e os respetivos padrões de ramificação. Os grupos de repositórios são concebidos para um controlo detalhado da IAM, dando aos programadores acesso aos dados indexados desses grupos, onde têm a autorização cloudaicompanion.repositoryGroups.use.

    Os grupos de repositórios contêm repositórios do Developer Connect ou links do mesmo projeto e localização.

    Os administradores realizam as seguintes ações:

    • Crie o recurso de índice do repositório de código.
    • No mesmo projeto e localização, configure uma nova ligação do Developer Connect.
    • Associe repositórios Git na ligação.
    • Obtenha os nomes dos recursos dos links, escolha o padrão de ramificação a indexar para cada link e coloque-o num ou em 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"
  }
}

    Substitua o seguinte:

    • REPOSITORY_GROUP: nome do grupo de repositórios, como default.
    • REPOSITORY_RESOURCE_NAME: nome do repositório na ligação do Developer Connect. Para encontrar o nome do repositório, aceda à página Repositórios Git na consola e, no separador Repositórios, procure o ID da associação na coluna Associação da tabela. Google Cloud Para copiar o nome do recurso, clique no menu more_vert para ver mais opções e selecione Copiar caminho do recurso.
    • BRANCH_NAMES: nome das ramificações que quer indexar, como main|dev.

    Também pode criar um grupo de repositórios com repositórios definidos num ficheiro JSON (ou YAML), formatado da seguinte forma:

    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 num ficheiro JSON ou YAML, num 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, pode encriptar e controlar os seus dados com uma chave de encriptação gerida pelo cliente (CMEK) através do Cloud Key Management Service. Para saber mais sobre a utilização de uma CMEK, consulte o artigo Encriptar dados com chaves de encriptação geridas pelo cliente.

  4. Conceda funções de IAM ao grupo de repositórios num projeto.

    Só recebe sugestões de repositórios no índice. Cada repositório pertence a um ou vários grupos de repositórios. Para aceder às sugestões, tem de conceder a função de IAM de utilizador dos grupos de repositórios do Cloud AI Companion (roles/cloudaicompanion.repositoryGroupsUser), que contém a autorização de IAM cloudaicompanion.repositoryGroups.user necessária, ao grupo de repositórios de uma das seguintes formas:

    • Conceder autorização aos responsáveis para acederem ao índice completo.

    • Conceder aos principais acesso a um subconjunto do índice.

    Índice completo

    1. Para associar uma política IAM a um projeto, num 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 o seguinte:

      • PRINCIPAL: o endereço de email do diretor que precisa de acesso, por exemplo, user:test-user@gmail.com para um indivíduo ou group:admins@example.com para um grupo.

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

    2. Quando lhe for pedido para especificar uma condição, introduza None.

    Subconjunto do índice

    Pode criar vários grupos de repositórios e atribuir funções do IAM a diferentes responsáveis do IAM.

      data "google_iam_policy" "foo" {
    binding {
      role = "roles/cloudaicompanion.repositoryGroupsUser"
      members = ["test-user@example.com"]
    }
  }

  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 pode criar uma associaçã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 = ["test-user@example.com"]
  }

    Substitua o seguinte:

    • GROUP_NAME: o nome do grupo de repositórios que criou num passo anterior para controlar o acesso ao seu índice através de grupos de repositórios.

Verifique o estado da indexação

Consoante o número de repositórios que quer indexar e o respetivo tamanho, a indexação de conteúdo pode demorar até 24 horas. Para repositórios grandes, a indexação pode demorar mais tempo. A indexação ocorre uma vez a cada 24 horas, recolhendo todas as alterações feitas no repositório.

  1. Pesquise os registos indexing. Para mais informações, consulte o artigo Registo do idioma da consulta.

    Consola

    1. Na Google Cloud consola, aceda ao Explorador de registos.

      Aceda ao Explorador de registos

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

    CLI

    Para pesquisar os registos de indexação, num ambiente de shell, use o comando logging read:

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

    Substitua PROJECT_ID pelo ID do projeto onde se encontra o grupo de repositórios.

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

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

  2. Reveja os estados de indexação associados, como os seguintes:

    • 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:
      • Concluído com êxito: 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:
      • Concluído com êxito: 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 estados do índice, REPOSITORY_NAME é o repositório que quer rever.

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

    • Falha ao obter o repositório.
    • Não foi possível listar os ficheiros do repositório.
    • Não foi possível obter as informações do repositório a partir do índice.
    • Não foi possível obter os ficheiros do índice.
    • Erro interno.

Use a personalização de código

Depois de configurar a personalização de código, começa a ver sugestões de conclusão de código e geração de código que podem basear-se no código privado que indexou, além dos resultados da análise completa da base de código.

Para saber mais sobre a utilização da personalização de código e as práticas recomendadas, consulte o artigo Use a personalização de código.

Desative a personalização de código

Selecione uma das seguintes opções:

Consola

  1. Na Google Cloud consola, aceda à página Produtos Gemini.

    Aceder aos produtos Gemini

    A página Produtos 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 eliminar o índice, clique em Eliminar.

    É apresentada uma mensagem de aviso. Se quiser continuar e eliminar o índice, introduza o nome do índice e, de seguida, clique em Eliminar.

CLI

  1. Para apresentar uma lista de todos os grupos de repositórios para o índice atual, num 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 o seguinte:

    • REGION: a região configurada no Developer Connect no seu Google Cloud projeto. Tenha em atenção que os comandos falham se especificar uma região não suportada. Consulte as limitações de personalização de código para ver uma lista de regiões suportadas.
    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • INDEX_NAME: o nome do índice que criou num passo anterior para criar um índice.

  2. Para eliminar 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 os passos anteriores para cada grupo de repositórios até eliminar todos os grupos de repositórios do índice.

  4. Opcional: para eliminar o índice, num ambiente de shell, use o comando gemini code-repository-indexes delete:

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

O que se segue?