clone_repo

La clonazione di un repository Git è un passaggio cruciale nelle pipeline, in quanto garantisce che il codice sorgente venga prelevato in modo sicuro e affidabile. Il processo di clonazione può comportare il controllo di rami specifici, la gestione di sottomoduli e persino il ripristino di particolari commit. Questo documento illustra le due versioni della funzione clone_repo:

clone_repo v1
clone_repo v2

L'operazione di clonazione svolge un ruolo cruciale nelle pipeline PR (Pull Request), CI (Continuous Integration), CC (Code Commit) e CD (Continuous Deployment), dove il repository deve essere clonato come parte del flusso di lavoro. Il metodo di clonazione può essere configurato utilizzando la proprietà dell'ambiente git-clone-version, che per impostazione predefinita è v1. Questa proprietà consente agli utenti di scegliere tra i metodi di clonazione v1 e v2, fornendo flessibilità nel modo in cui il repository viene recuperato in base ai requisiti specifici della pipeline.

clone_repo v1( ) funzione

La funzione clone_repo() è progettata per clonare un repository Git, includendo facoltativamente i sottomoduli, con il supporto per la selezione del ramo e dell'ID di commit, oltre a meccanismi di riprova per gestire i timeout di connessione. Inoltre, sanifica i messaggi di errore per motivi di sicurezza.

Parametri:

Parametro	Descrizione
`repository`	L'indirizzo URL del repository Git da clonare.
`git_branch`	Il ramo da controllare. Se non viene fornito, viene utilizzato il ramo predefinito.
`directory_name`	Il nome della directory in cui verrà clonato il repository.
`token_path`	Il percorso del file contenente il token di autenticazione Git.
`use_submodules`	(Facoltativo) Impostare su "1" per clonare i sottomoduli; l'impostazione predefinita è "0".
`commit_id`	(Facoltativo) L'ID di commit specifico da ripristinare dopo la clonazione.
`force-exit`	(Facoltativo) Forza l'uscita in caso di fallimento.

Implementazione della funzione:

Initialize Variables : Impostare le variabili d'ambiente e le impostazioni predefinite.
Token and User Validation : Assicurarsi che i dettagli di autenticazione siano disponibili.
Clone Repository : Clona il repository con un meccanismo di riprova opzionale.
Submodule Handling : se i sottomoduli sono abilitati, impostare l'ambiente necessario e clonare i sottomoduli.
Checkout Branch or Commit : Controlla il ramo o il commit specificato.
Finalize and Export : imposta le variabili d'ambiente e stampa i messaggi di stato.

Valore di ritorno:

La funzione clone_repo imposta diverse variabili/proprietà d'ambiente al suo completamento:

git_branch : Il ramo che è stato controllato.
git_commit : L'ID del commit a cui è stato ripristinato il repository.
directory_name : La directory in cui è stato clonato il repository.
submodules_status : Stato dei sottomoduli, se presenti.

Chiamata di funzione:

clone_repo <repo url e.g. https://github.ibm.com/owner/repo.git> <branch e.g. master> <repo directory e.g. repo_directory> <token path e.g. /path/to/token> <if submodules to be used e.g. 1> <commit id e.g. abcd1234>

Clonazione di sottomoduli:

Se USE_SUBMODULES è impostato su 1, lo script controlla le variabili d'ambiente della pipeline per determinare se i sottomoduli devono essere clonati e come devono essere configurati.
La clonazione dei sottomoduli supporta solo i sottomoduli dichiarati con il protocollo HTTP(S) nel file .gitmodules. Lo script si basa sul token di autenticazione Git fornito, utilizzato negli URL HTTP(S). I sottomoduli dichiarati con altri protocolli, come SSH, non funzioneranno senza problemi perché lo script non è configurato per gestire le chiavi SSH o altri metodi di autenticazione.
Le variabili opt-in-clone-submodules e opt-in-clone-remote-submodules giocano un ruolo fondamentale nel determinare come lo script gestisce la clonazione dei sottomoduli.
opt-in-clone-submodules: Controlla se i sottomoduli devono essere clonati durante il processo di clonazione del repository.
- Se opt-in-clone-submodules è impostato su 1, lo script include il parametro --recurse-submodules nel comando Git clone, che istruisce Git a inizializzare e aggiornare ogni sottomodulo del repository.
- Se non viene impostato o se viene impostato un valore diverso, i sottomoduli non verranno clonati e lo script procederà alla clonazione del solo repository principale.
opt-in-clone-remote-submodules: estende il comportamento di opt-in-clone-submodules, consentendo ai sottomoduli di essere clonati dai loro repository remoti, invece di usare i percorsi locali specificati nel repository padre.
- Se opt-in-clone-remote-submodules è impostato su 1, lo script aggiunge il parametro --remote-submodules accanto a --recurse-submodules. Questo fa sì che Git recuperi e cloni i sottomoduli dalle loro origini remote, invece di basarsi solo sui percorsi specificati nel repository padre.
- Se non viene impostato o se viene impostato un valore diverso, i sottomoduli saranno clonati usando i percorsi locali predefiniti forniti nel file .gitmodules del repository padre.

Note importanti:

Retry Mechanism : lo script riprova il comando clone fino a 5 volte con un ritardo di 2 secondi tra i tentativi se si verifica un errore "Connessione interrotta".
Error Handling : se si verificano errori di autenticazione o altri errori critici, lo script esce con uno stato non nullo e fornisce indicazioni sulla risoluzione dei problemi più comuni.
Error Message Sanitisation: Lo script sanifica i messaggi di errore per garantire che le informazioni sensibili, come i token di autenticazione, non siano esposte nell'output. Questo viene fatto usando sed per sostituire le parti sensibili degli URL con dei segnaposto.

clone_repo v2( ) funzione

La funzione clone_repo v2 è una versione migliorata di v1, che supporta la clonazione superficiale e una migliore gestione degli errori.

Parametri

Parametro	Descrizione
`repository`	Git url del repository.
`token-path`	(Facoltativo) Percorso del file dei token di Git.
`directory`	(Facoltativo) Directory di destinazione per clonare il repository.
`commit-id`	(Facoltativo) ID di commit specifico per il checkout.
`clone-submodules`	(Facoltativo) Clonare e inizializzare i sottomoduli.
`depth`	(Opzionale) Profondità per cloni poco profondi.
`use-lfs`	(Facoltativo) <true\false> Abilita/disabilita Git LFS per il repository.
`force-exit`	(Facoltativo) Forza l'uscita in caso di fallimento.
`git-clone-options`	(Opzionale) Opzioni aggiuntive per Git fetch.

Richiamo funzione

clone_repo_v2 --repository <e.g. https://github.ibm.com/owner/repo.git> --branch <e.g. master> --directory <e.g. repo_directory> --token-path <e.g. /path/to/token> --clone-submodules <if submodules to be used e.g. 1> --force-exit <false/true> --use-lfs <false/true> --depth ''

Clonazione di sottomoduli

Sia v1 che v2 supportano la clonazione di sottomoduli.

Proprietà ambiente

Le seguenti proprietà dell'ambiente consentono di personalizzare il processo di clonazione di Git, garantendo prestazioni ottimali e flessibilità in base ai requisiti della pipeline. Queste proprietà devono essere impostate in CI (Continuous Integration), PR (Pull Request) o altre pipeline, a seconda delle necessità.

Proprietà	Descrizione
`git-depth`	Specifica la profondità per la clonazione superficiale. Se viene lasciato vuoto, viene eseguito un clone completo. Impostando un valore numerico (ad esempio, 1) si abilita la clonazione superficiale, recuperando solo l'ultimo commit per ottenere prestazioni più veloci.
`git-use-lfs`	Determina se utilizzare Git Large File Storage (LFS). `true/false`.
`git-options`	Permette di passare ulteriori opzioni personalizzate di Git, ad esempio: `--verbose --quiet`.

La funzione clone_repo v2 introduce un approccio più efficiente e flessibile alla clonazione dei repository, ottimizzando le prestazioni con caratteristiche come la clonazione superficiale, il supporto di Git LFS e le opzioni di Git personalizzabili.