italiadatacenter/st2idc/README-clone-transform.md

Clone and Transform Script

Script bash per clonare un repository GitLab usando API e token privato, con sostituzione automatica di stringhe nei file.

Prerequisiti

• bash (4.0+)
• git
• curl (opzionale, per verificare l'accesso)
• Token privato GitLab con almeno scope api o read_repository

Preparazione

1. Creare il file transform.txt

Crea un file transform.txt nella stessa directory dello script con il formato:

<old_string>=<new_string>
<old_string>=<new_string>
...

Esempio di transform.txt:

# Configurazioni di sviluppo verso produzione
DATABASE_HOST=localhost=DATABASE_HOST=prod.example.com
DATABASE_PORT=5432=DATABASE_PORT=5432
API_ENDPOINT=http://localhost:8080=API_ENDPOINT=https://api.prod.com
ENVIRONMENT=development=ENVIRONMENT=production
LOG_LEVEL=debug=LOG_LEVEL=info
SECRET_KEY=dev-secret=SECRET_KEY=prod-secret-key-xyz

2. Ottenere un token GitLab

1. Accedi a GitLab
2. Vai a Profile → Access Tokens
3. Crea un nuovo token con scopes:
   • api - accesso completo
   • oppure read_repository - solo lettura
4. Copia il token (non sarà più visibile dopo)

3. Rendere eseguibile lo script

chmod +x clone-and-transform.sh

Utilizzo

Sintassi base

./clone-and-transform.sh -u <URL> -t <TOKEN> -r <REPO-PATH> -d <DEST-DIR>

Parametri

Parametro	Breve	Descrizione	Esempio
--url	-u	URL base di GitLab	https://gitlab.com
--token	-t	Token di accesso privato	glpat-xxxxx
--repo	-r	Percorso del repository	mygroup/myproject
--dest	-d	Directory di destinazione	./cloned-repo
--transform	-f	Path del file transform.txt	./transform.txt (default)
--help	-h	Mostra l'aiuto	-

Esempi di utilizzo

Esempio 1: Clone con trasformazioni usando file default

./clone-and-transform.sh \
    -u https://gitlab.com \
    -t glpat-xxxxxxxxxxxx \
    -r mygroup/myproject \
    -d ./my-cloned-repo

Esempio 2: Clone con file transform.txt personalizzato

./clone-and-transform.sh \
    -u https://gitlab.internal.com \
    -t glpat-xxxxxxxxxxxx \
    -r company/backend \
    -d ./backend-clone \
    -f ./custom-transform.txt

Esempio 3: Clone da GitLab Enterprise

./clone-and-transform.sh \
    -u https://gitlab.mycompany.com \
    -t glpat-xxxxxxxxxxxx \
    -r products/idcidp \
    -d ./idcidp-prod

Come funziona lo script

1. Validazione: Verifica i parametri e l'esistenza di transform.txt
2. Clone: Clona il repository usando autenticazione OAuth2
3. Scoperta directory: Identifica directory kubernetes, containers, conf
4. Trasformazione: Per ogni file trovato applica le sostituzioni definite in transform.txt
5. Report: Mostra il number di file modificati e suggerisce i prossimi passi

Directory elaborate

Lo script elabora automaticamente questi percorsi:

• kubernetes/
• containers/
• conf/

Se una directory non esiste, viene saltata con un avvertimento.

File binari

I file binari (immagini, archivi, ecc.) vengono automaticamente saltati per evitare corruzioni.

Output esempio

[INFO] Starting GitLab repository clone and transformation...
[INFO] GitLab URL: https://gitlab.com
[INFO] Repository: mygroup/myproject
[INFO] Destination: ./my-cloned-repo
[INFO] Transform file: ./transform.txt
[INFO] Cloning repository...
[INFO] Repository cloned successfully
[INFO] Found directory: kubernetes
[INFO] Found directory: containers
[INFO] Applying transformations from ./transform.txt...
[INFO] Processing directory: kubernetes
[INFO]   Modified: ./my-cloned-repo/kubernetes/deployment.yaml
[INFO]   Modified: ./my-cloned-repo/kubernetes/service.yaml
[INFO] Processing directory: containers
[INFO] ========== TRANSFORMATION SUMMARY ==========
Total files processed: 12
Files modified: 5
[INFO] ==========================================
[INFO] Transformation completed successfully!

Next steps:
  1. Review changes: cd my-cloned-repo && git diff
  2. Commit changes: git add . && git commit -m 'Apply transformations'
  3. Push changes: git push

Verifica delle modifiche

Dopo l'esecuzione, è consigliato verificare le modifiche:

cd ./my-cloned-repo
git diff

Per vedere solo i file modificati:

git status

Commit e Push

Se le modifiche sono corrette:

git add .
git commit -m "Apply environment transformations"
git push

Troubleshooting

Errore: "Failed to clone repository"

Causa: Token non valido o senza permessi

Soluzione:

1. Verifica il token nel profilo GitLab
2. Assicurati che il token abbia scope api
3. Verifica che il repository sia accessibile con il token

Errore: "Transform file not found"

Causa: Il file transform.txt non esiste

Soluzione:

1. Crea il file transform.txt nella directory dove esegui lo script
2. Usa l'opzione -f per specificare un percorso personalizzato

Nessun file modificato

Causa: Le stringhe in transform.txt non corrispondono ai file

Soluzione:

1. Verifica il contenuto dei file nella directory clonata
2. Assicurati che le stringhe in transform.txt siano corrette
3. Usa pattern più generici se necessario

Errore di escaping in stringhe complesse

Se le stringhe contengono caratteri speciali (barre, ampersand, etc.):

Lo script gestisce automaticamente l'escaping, ma se riscontri problemi:

1. Usa sequenze di escape nel file transform.txt
2. Ad esempio, per una barra inversa: path\\old=path\\new

Sicurezza

Best practices

1. Non commettere il token nel repository

2. Usa variabili d'ambiente per il token:

   ./clone-and-transform.sh \
       -u https://gitlab.com \
       -t $GITLAB_TOKEN \
       -r mygroup/myproject \
       -d ./clone
   

3. Usa file .gitignore per transform.txt se contiene dati sensibili:

   echo "transform.txt" >> .gitignore
   

4. Revoca il token dopo l'uso se è ad uso singolo

Opzioni avanzate

Usare con script di automazione

#!/bin/bash
export GITLAB_TOKEN="glpat-xxxxx"
export GITLAB_URL="https://gitlab.internal.com"

./clone-and-transform.sh \
    -u $GITLAB_URL \
    -t $GITLAB_TOKEN \
    -r company/backend \
    -d ./backend-clone

Variazione per ambienti multipli

Crea diversi file di trasformazione:

• transform-dev.txt
• transform-qa.txt
• transform-prod.txt

# Per development
./clone-and-transform.sh \
    -u https://gitlab.com \
    -t $GITLAB_TOKEN \
    -r mygroup/myproject \
    -d ./clone-dev \
    -f transform-dev.txt

# Per production
./clone-and-transform.sh \
    -u https://gitlab.com \
    -t $GITLAB_TOKEN \
    -r mygroup/myproject \
    -d ./clone-prod \
    -f transform-prod.txt

Changelog

v1.0 (Initial Release)

• Clone repository con token privato
• Applicazione di trasformazioni su directory specifiche
• Supporto per file UTF-8
• Skip automatico file binari
• Output colorato e dettagliato

Licenza

MIT