Configurar 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 seus repositórios de código particulares. Com esse recurso, você recebe recomendações de código que usam as bibliotecas internas, APIs privadas e o 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 estilo ou estrutura semelhante ao que você quer que seus desenvolvedores escrevam.
  • Ter bibliotecas ou APIs particulares que você gostaria de chamar da sua base de código atual.

(Opcional) Escolher 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.

Criar um índice

A personalização de código usa um índice para analisar seu repositório e sugerir a geração de código e pesquisas mais rapidamente.

CLI da gcloud

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

Terraform

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: uma região compatível, conforme indicado na seção Antes de começar desta página, que você configurou 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.

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

Um grupo de repositórios é um contêiner para 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.

CLI da gcloud

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"}]'

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órios, como default.
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • REGION: uma região compatível, conforme declarado na seção Antes de começar desta página, que você configurou no Developer Connect no 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 na conexão do Developer Connect. Para encontrar o nome do repositório, acesse a página do Developer Connect 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.

Conceder papel 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 as sugestões, conceda ao grupo de repositórios 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, 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.

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

  1. Para vincular uma política do IAM a um projeto em um ambiente 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 de repositórios 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 for preciso especificar uma condição, digite None.

Conceder acesso a um subconjunto do índice para os principais

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

CLI da gcloud

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: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 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 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 da gcloud

    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 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

  1. Para listar todos os grupos de repositórios do índice atual em um ambiente 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 compatível, conforme indicado na seção Antes de começar desta página, que você configurou no Developer Connect no seu projetoGoogle Cloud .
    • PROJECT_ID: o ID do projeto do 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ó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 a etapa 3 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