Vai al contenuto
AdiosDocumentazione
Riferimento dell'API
IT
Apri la dashboard
Esplora la documentazione

Dipendenze private da Git

Usa una chiave di distribuzione SSH riservata alla compilazione quando la tua applicazione dipende da codice in un repository Git privato. Questa guida usa un modulo Go privato su Bitbucket, ma lo stesso flusso build.ssh funziona con GitHub e GitLab.

Se una compilazione si interrompe con un errore come questo, la dipendenza è privata ma la compilazione non dispone di credenziali utilizzabili senza interazione:

fatal: could not read Username for 'https://bitbucket.org': terminal prompts disabled

Non inserire password, token di accesso o chiavi private in adios.yaml, go.mod, o nell’URL del repository. Assegna al repository una chiave pubblica di distribuzione, conserva la chiave privata in Adios e indica il nome del segreto nel manifest.

1. Crea una chiave di distribuzione dedicata

Genera una nuova chiave per le compilazioni invece di caricare la tua chiave SSH personale:

ssh-keygen -t ed25519 \
  -C "adios-build" \
  -f ~/.ssh/adios-build \
  -N ""

Questo crea due file:

  • ~/.ssh/adios-build.pub è la chiave pubblica. Aggiungila al tuo fornitore Git.
  • ~/.ssh/adios-build è la chiave privata. Conservala in Adios e non inserirla mai in un commit.

La chiave non ha una passphrase interattiva perché una compilazione automatica non può rispondere a una richiesta di passphrase. Mantienila dedicata, in sola lettura e limitata ai repository sorgente necessari alla compilazione.

2. Concedi alla chiave pubblica accesso al repository

Mostra la chiave pubblica:

cat ~/.ssh/adios-build.pub

Aggiungi l’intera riga come chiave di accesso al repository o di distribuzione in sola lettura:

  • Bitbucket: aggiungila alle chiavi di accesso del repository privato.
  • GitHub: aggiungila come chiave di distribuzione in sola lettura.
  • GitLab: aggiungila come chiave di distribuzione senza accesso in scrittura.

Per più repository privati, autorizza la chiave ovunque serva accesso in lettura oppure usa un account macchina supportato dal fornitore con l’ambito minimo praticabile. Non incollare mai il file privato nel fornitore Git.

3. Conserva la chiave privata in Adios

Assicurati che la CLI usi il team proprietario dell’applicazione, poi carica il file privato:

adios teams switch <team-id>
adios secrets set BITBUCKET_DEPLOY_KEY \
  --from-file ~/.ssh/adios-build

Puoi invece selezionare esplicitamente un team:

adios secrets set BITBUCKET_DEPLOY_KEY \
  --from-file ~/.ssh/adios-build \
  --team <team-id>

Conferma che il nome del segreto esista senza mostrarne il valore:

adios secrets list

BITBUCKET_DEPLOY_KEY è solo un nome di esempio. Puoi sceglierne un altro, ma il nome dopo secret:// in adios.yaml deve corrispondere esattamente.

4. Configura adios.yaml

Per un modulo Go privato ospitato in uno spazio di lavoro Bitbucket:

build:
  ssh:
    - default=secret://BITBUCKET_DEPLOY_KEY
  env:
    GOPRIVATE: "bitbucket.org/your-workspace/*"

build_cmd: |-
  set -e
  go build -o app ./cmd/api

build.ssh rende la chiave disponibile solo alla compilazione. Adios recupera il segreto all’interno del worker ed elimina il file temporaneo della chiave privata al termine della compilazione. Per le compilazioni native build_cmd, il worker prepara anche SSH per gli host Git supportati. La chiave non viene aggiunta all’ambiente o al filesystem dell’applicazione in esecuzione. Le compilazioni Docker devono usare il mount SSH come mostrato sotto.

GOPRIVATE indica a Go quali percorsi dei moduli devono evitare il proxy pubblico dei moduli e il database dei checksum. Fallo corrispondere al percorso di importazione del modulo, non al nome visualizzato del repository:

Host GitEsempio di modello Go
Bitbucketbitbucket.org/my-workspace/*
GitHubgithub.com/my-organization/*
GitLabgitlab.com/my-group/*

Non devi modificare un’importazione HTTPS esistente di un modulo per includere un nome utente o credenziali. Per gli host supportati, il worker di compilazione Adios usa SSH mentre il repository mantiene il normale percorso canonico di importazione.

5. Distribuisci e verifica

Esegui di nuovo la distribuzione:

adios up

Il download riuscito di una dipendenza dimostra che entrambe le chiavi sono collegate: il manifest ha trovato la chiave privata nel team Adios corretto e il fornitore Git ha accettato la chiave pubblica per il repository richiesto.

Dopo la prima compilazione riuscita, elimina dai computer condivisi le copie temporanee delle chiavi che non servono più. Mantieni registrata la chiave pubblica per le compilazioni future e ruota la coppia quando cambia l’accesso al repository.

Compilazioni Docker

Per una compilazione Docker, build.ssh abilita il mount SSH di BuildKit, ma il Dockerfile deve usarlo nei comandi che scaricano sorgenti private:

# syntax=docker/dockerfile:1
FROM golang:1.25 AS build

ARG GOPRIVATE
ENV GOPRIVATE=$GOPRIVATE

WORKDIR /src
COPY go.mod go.sum ./

RUN mkdir -p -m 0700 /root/.ssh \
    && ssh-keyscan bitbucket.org >> /root/.ssh/known_hosts \
    && git config --global \
      url."ssh://git@bitbucket.org/".insteadOf \
      "https://bitbucket.org/"

RUN --mount=type=ssh go mod download

Mantieni la configurazione corrispondente del manifest sotto build.ssh e build.env. Non usare COPY o un argomento di compilazione per inserire la chiave privata nell’immagine.

Risoluzione dei problemi

terminal prompts disabled

Controlla che build.ssh sia presente, il nome del segreto corrisponda esattamente e il segreto appartenga al team attivo dell’applicazione. Per le compilazioni Docker, controlla anche che il comando delle dipendenze usi RUN --mount=type=ssh.

Permission denied (publickey)

La chiave privata è stata caricata, ma il fornitore Git non l’ha accettata. Conferma di aver registrato il file corrispondente .pub nel repository corretto e che la chiave abbia ancora accesso in lettura.

Go contatta ancora proxy.golang.org o il database di checksum

Correggi il modello GOPRIVATE affinché copra l’intero percorso di importazione del modulo privato. Per più namespace, separa i modelli con virgole.

invalid format o error in libcrypto

Il valore conservato deve essere il file della chiave privata, non il file .pub, un’impronta o la formattazione copiata dal terminale. Caricala di nuovo con --from-file per preservare esattamente la chiave.

repository not found

Verifica prima il percorso del modulo e il nome del repository. Se entrambi sono corretti, la chiave di distribuzione potrebbe essere associata a un altro repository o non avere accesso a una delle dipendenze private transitive.