Configurare e utilizzare la personalizzazione del codice di Gemini Code Assist

Questo documento descrive come configurare la personalizzazione del codice di Gemini Code Assist collegando Gemini Code Assist ai tuoi repository di codice privato. Questa funzionalità ti consente di ricevere consigli sul codice, che si basano sulle librerie interne, sulle API private e sullo stile di programmazione della tua organizzazione.

Prima di iniziare

Scegli quali repository privati sono collegati

Come best practice, assicurati di collegare i repository che:

  • Il codice deve avere uno stile o una struttura simile a quello che vuoi che scrivano gli sviluppatori.
  • Avere API o librerie private che vuoi chiamare dal tuo codebase attuale.

(Facoltativo) Scegli i file che non devono essere indicizzati

Per impostazione predefinita, la personalizzazione del codice indicizza tutti i file di codice supportati nei repository specificati.

In molti casi, potresti avere file o sottoalberi specifici che non vuoi indicizzare. Ad esempio:

  • Informazioni altamente sensibili con accesso limitato all'interno dell'organizzazione
  • Codice obsoleto o non più supportato
  • Codice generato automaticamente o temporaneo

Per impedire l'esposizione del codice che non vuoi indicizzare, puoi utilizzare i pattern di branch per controllare l'accesso all'indice e utilizzare un branch stabile, ad esempio main.

In alternativa, puoi anche escludere i file dall'indice creando un file .aiexclude.

Creare un indice

La personalizzazione del codice si basa su un indice per analizzare ed esaminare il tuo repository al fine di eseguire ricerche e suggerire la generazione di codice più rapidamente.

Per creare l'indice, in un ambiente shell, utilizza il comando gemini code-repository-indexes create:

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

Sostituisci quanto segue:

  • INDEX_NAME: il nome dell'indice. Importante: annota il nome dell'indice. Ti servirà per diversi passaggi di questo documento.
  • PROJECT_ID: il tuo ID progetto Google Cloud.
  • REGION: una regione supportata, come indicato nella sezione Prima di iniziare di questa pagina, che hai configurato in Developer Connect nel tuo progetto Google Cloud.

In genere, la creazione dell'indice richiede 30 minuti, ma potrebbe essere necessaria fino a un'ora.

Google limita il numero di indici dei repository di codice a uno per ogni progetto e organizzazione.

Controllare l'accesso all'indice utilizzando i gruppi di repository

Un gruppo di repository è un contenitore per la configurazione dell'indicizzazione, che include i repository e i relativi pattern di branch. I gruppi di repository sono progettati per un controllo IAM granulare, che consente agli sviluppatori di accedere ai dati indicizzati di questi gruppi, se dispongono dell'autorizzazione cloudaicompanion.repositoryGroups.use.

I gruppi di repository contengono repository o link di Developer Connect della stessa località e dello stesso progetto.

Gli amministratori eseguono le seguenti azioni:

  • Crea la risorsa Indice del repository di codice.
  • Nella stessa posizione e nello stesso progetto, configura una nuova connessione Developer Connect.
  • Collega i repository Git nella connessione.
  • Ottieni i nomi delle risorse dei link, scegli il pattern di ramo da indicizzare per ogni link e inseriscilo in uno o più gruppi di repository.

Per creare un gruppo di repository, in un ambiente shell, utilizza il 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"}]'

Sostituisci quanto segue:

  • REPOSITORY_GROUP: il nome del gruppo di repository, ad esempio default.
  • PROJECT_ID: il tuo ID progetto Google Cloud.
  • REGION: una regione supportata, come indicato nella sezione Prima di iniziare di questa pagina, che hai configurato in Developer Connect nel tuo progetto Google Cloud.
  • INDEX_NAME: il nome dell'indice creato in un passaggio precedente per creare un indice.
  • REPOSITORY_RESOURCE_NAME: il nome del repository all'interno della connessione Developer Connect. Per trovare il nome del repository, vai alla pagina Developer Connect nella console Google Cloud e nella scheda Repository cerca l'ID connessione nella colonna Connessione della tabella. Per copiare il nome della risorsa, fai clic sul menu more_vert per visualizzare altre opzioni e seleziona Copia percorso risorsa.
  • BRANCH_NAMES: il nome dei rami da indicizzare, ad esempio main|dev.

Puoi anche creare un gruppo di repository con i repository definiti in un file JSON (o YAML), nel seguente formato:

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

Per creare un gruppo di repository in base a un file JSON o YAML, in un ambiente shell, utilizza il 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

Concedi il ruolo IAM al gruppo del repository in un progetto

Riceverai suggerimenti solo dai repository nell'indice. Ogni repository appartiene a uno o più gruppi di repository. Per accedere ai suggerimenti, devi concedere al gruppo di repository il ruolo IAM Utente dei gruppi di repository Cloud AI Companion (roles/cloudaicompanion.repositoryGroupsUser), che contiene l'autorizzazione IAM cloudaicompanion.repositoryGroups.user richiesta, in uno dei seguenti modi:

  • Concedi alle entità l'autorizzazione ad accedere all'intero indice.
  • Concedi alle entità l'accesso a un sottoinsieme dell'indice.

Concedi ai principali l'autorizzazione ad accedere all'intero indice

  1. Per associare un criterio IAM a un progetto, in un ambiente shell, utilizza il comando projects add-iam-policy-binding:

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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto in cui si trova il gruppo di repository.
    • PRINCIPAL: l'indirizzo email del principale che ha bisogno di accedere, ad esempio user:test-user@gmail.com per una persona fisica o group:admins@example.com per un gruppo.

    Per ulteriori informazioni, consulta gcloud projects set-iam-policy.

  2. Quando ti viene chiesto di specificare una condizione, inserisci None.

Concedi alle entità l'accesso a un sottoinsieme dell'indice

Puoi creare più gruppi di repository e assegnare ruoli IAM a diversi entità IAM.

Per configurare un criterio IAM, devi preparare il file JSON o YAML del criterio IAM, che conterrà un elenco di gruppi IAM e ruoli assegnati. Ad esempio:

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

Per ulteriori dettagli e sintassi, consulta Informazioni sui criteri di autorizzazione.

Per impostare il criterio IAM, in un ambiente shell, utilizza il 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

Sostituisci quanto segue:

Controllare lo stato dell'indicizzazione

A seconda del numero di repository da indicizzare e delle relative dimensioni, l'indicizzazione dei contenuti può richiedere fino a 24 ore. Per i repository di grandi dimensioni, l'indicizzazione può richiedere più tempo. L'indicizzazione viene eseguita una volta ogni 24 ore e rileva eventuali modifiche apportate al repository.

  1. Cerca i log indexing. Per ulteriori informazioni, consulta Linguaggio delle query di Logging.

    Console

    1. Nella console Google Cloud, vai a Esplora log.

      Vai a Esplora log

    2. Utilizza il filtro dei nomi dei log per visualizzare i log indexing.

    gcloud

    Per cercare i log di indicizzazione, in un ambiente shell, utilizza il comando logging read:

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

    Sostituisci PROJECT_ID con l'ID progetto in cui si trova il gruppo di repository.

    Ad esempio, per visualizzare gli errori nei log di indexing, esegui il seguente comando:

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

  2. Esamina gli stati di indicizzazione associati, ad esempio:

    • Inizio dell'indicizzazione del repository, ad esempio Indexing repository REPOSITORY_NAME. Total number of repositories: 10, succeeded: 6, failed: 0.
    • Fine dell'indicizzazione dei singoli repository, ad esempio:
      • Operazione riuscita: Successfully finished indexing repository REPOSITORY_NAME. Total number of repositories: 10, succeeded: 7, failed: 0.
      • Errore: Failed to index repository REPOSITORY_NAME. Error: [<error message>]. Total number of repositories: 10, succeeded: 7, failed: 1.
    • Fine dell'indicizzazione del repository, ad esempio:
      • Operazione riuscita: Finished indexing process. Repositories attempted: 10. Repositories successfully indexed: 9. Repositories unsuccessfully fetched: 0.
      • Errore: 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.

    Negli stati dell'indice, REPOSITORY_NAME è il repository che vuoi esaminare.

  3. Esamina gli errori di indicizzazione associati, ad esempio:

    • Impossibile recuperare il repository.
    • Impossibile elencare i file del repository.
    • Impossibile recuperare le informazioni del repository dall'indice.
    • Impossibile recuperare i file dall'indice.
    • Errore interno.

Utilizzare la personalizzazione del codice

Una volta configurata la personalizzazione del codice, gli utenti inizieranno a vedere suggerimenti di completamento e generazione del codice che possono essere basati sul codice privato che hai indicizzato, oltre ai risultati della consapevolezza completa del codebase.

Disattivare la personalizzazione del codice

  1. Per elencare tutti i gruppi di repository per l'indice corrente, in un ambiente shell, utilizza il 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

    Sostituisci quanto segue:

    • REGION: una regione supportata, come indicato nella sezione Prima di iniziare di questa pagina, che hai configurato in Developer Connect nel tuo progetto Google Cloud.
    • PROJECT_ID: il tuo ID progetto Google Cloud.
    • INDEX_NAME: il nome dell'indice creato in un passaggio precedente per creare un indice.

  2. Per eliminare un gruppo di repository dall'indice corrente, utilizza il 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. Ripeti il passaggio 3 per ogni gruppo di repository finché non avrai eliminato tutti i gruppi di repository dall'indice.

  4. (Facoltativo) Per eliminare l'indice, in un ambiente shell, utilizza il comando gemini code-repository-indexes delete:

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

Passaggi successivi