Configurar e usar 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 conectando o Gemini Code Assist aos repositórios de código particulares. Esse recurso permite receber recomendações de código, que são extraídas das bibliotecas internas, APIs privadas e estilo de programação da sua organização.

Antes de começar

Escolher quais repositórios particulares estão conectados

Como prática recomendada, conecte repositórios que:

  • Ter um código com um estilo ou estrutura semelhante ao que você quer que os desenvolvedores escrevam.
  • Ter bibliotecas ou APIs particulares que você gostaria de chamar do seu repositório de código atual.

(Opcional) Escolher quais arquivos não são indexados

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

Em muitos casos, você pode ter arquivos ou subárvores específicos que não quer indexar. Exemplo:

  • Informações altamente sensíveis com acesso limitado dentro da sua organização
  • Código antigo ou descontinuado
  • Código temporário ou gerado automaticamente

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.

Como alternativa, você também pode excluir arquivos do índice criando um arquivo .aiexclude.

Criar um índice

A personalização do código depende de um índice para analisar e analisar seu repositório em busca de sugestões e pesquisas de geração de código mais rápidas.

CLI da gcloud

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

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

Terraform

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

Substitua:

  • INDEX_NAME: o nome do índice. Importante: registre o nome do índice. Você vai precisar dele em várias etapas deste documento.
  • PROJECT_ID: é seu ID do projeto no Google Cloud.
  • REGION: uma região com suporte, conforme declarado na seção Antes de começar desta página, que você configurou no Developer Connect no seu projeto Google Cloud.

A criação de índices geralmente leva 30 minutos para ser concluída, 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.

Controlar o acesso ao índice usando grupos de repositório

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

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

Os administradores realizam as seguintes ações:

  • Crie um recurso de índice do repositório de código.
  • No mesmo projeto e local, configure uma nova conexão do Developer Connect.
  • Vincular repositórios Git na conexão.

  • Receba os nomes de recursos dos links, escolha o padrão de ramificação a ser indexado para cada link e coloque em um ou vários grupos de repositórios.

CLI da gcloud

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

Terraform

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:

  • REPOSITORY_GROUP: nome do grupo de repositório, como default.
  • PROJECT_ID: é seu ID do projeto no Google Cloud.
  • REGION: uma região com suporte, conforme declarado na seção Antes de começar desta página, que você configurou no Developer Connect no seu projeto Google Cloud.
  • INDEX_NAME: nome do índice que você criou em uma etapa anterior para criar um índice.
  • REPOSITORY_RESOURCE_NAME: nome do repositório dentro da conexão do Developer Connect. Para encontrar o nome do repositório, acesse a página Developer Connect no console Google Cloud e, na guia Repositories, procure o ID da conexão na coluna Connection da tabela. 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 você quer indexar, como main|dev.

Também é possível criar um grupo de repositórios 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) pelo Cloud Key Management Service. Para saber mais sobre o uso de uma CMEK, consulte Criptografar dados com chaves de criptografia gerenciadas pelo cliente.

Conceder o papel do IAM ao grupo de repositório 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 as sugestões, é necessário conceder o papel do IAM de usuário de grupos de repositórios do Cloud AI Companion (roles/cloudaicompanion.repositoryGroupsUser), que contém a permissão cloudaicompanion.repositoryGroups.user do IAM necessária, ao grupo de repositórios de uma destas formas:

  • Conceder permissão aos principais para acessar todo o índice.
  • Conceda aos participantes acesso a um subconjunto do índice.

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

  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:

    • PROJECT_ID: o ID do projeto em que o grupo do repositório está localizado.
    • PRINCIPAL: o endereço de e-mail do principal que precisa de acesso. Por exemplo, user:test-user@gmail.com para uma pessoa ou group:admins@example.com para um grupo.

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

  2. Quando solicitado a especificar uma condição, digite None.

Conceder acesso a um subconjunto do índice para os participantes

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

CLI da gcloud

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

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

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

Para definir a política do IAM em um 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:

Terraform

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 é 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 = ["test-user@example.com"]
}

Substitua:

Verificar o status da indexação

Dependendo do número de repositórios que você quer indexar e do tamanho deles, a indexação de 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, detectando todas 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 do Google Cloud, acesse o Explorador de registros.

      Acessar o Explorador de registros

    2. Use o filtro de nomes de registro para conferir os registros indexing.

    CLI da gcloud

    Para pesquisar os registros de indexação, em um ambiente de 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ório está localizado.

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

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

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

    • 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ório individual, 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 de índice, REPOSITORY_NAME é o repositório que você quer analisar.

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

    • Falha ao buscar o repositório.
    • Falha ao listar os arquivos do repositório.
    • Falha ao extrair informações do repositório do índice.
    • Falha ao recuperar arquivos do índice.
    • Erro interno.

Usar a personalização de código

Depois de configurar a personalização de código, os usuários vão começar a receber sugestões de preenchimento e geração de código que podem ser baseadas em código privado que você indexou, além dos resultados da detecção completa da base de código.

Desativar a personalização do código

  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: uma região com suporte, conforme declarado na seção Antes de começar desta página, que você configurou no Developer Connect no seu Google Cloud projeto.
    • PROJECT_ID: é seu ID do projeto no Google Cloud.
    • INDEX_NAME: nome do índice que você criou em uma etapa anterior para criar um índice.

  2. Para excluir um grupo de repositório 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 a etapa 3 para cada grupo de repositório até excluir todos os grupos do índice.

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

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

A seguir