GitLab: cos'è e come usarlo con Git — clone, push, merge request, CI/CD

GitLab: cos'è

GitLab è la piattaforma su cui si conservano i repository Git e si costruisce il lavoro di squadra: revisione del codice, merge request (richieste di unione), attività, wiki, registro dei container e CI/CD integrato. In breve, GitLab è «GitHub con una pipeline di build propria e la possibilità di installarlo sul proprio server». Molte aziende, anche in Italia, tengono il codice proprio in GitLab installato sulla rete interna.

Il progetto è nato nel 2011 come applicazione open source per l'hosting di codice, poi attorno ad esso si è sviluppata l'azienda GitLab Inc. La piattaforma esiste in due versioni: la Community Edition, open source, installabile gratuitamente sul proprio server, e la Enterprise Edition con funzioni a pagamento. Sul servizio cloud gitlab.com i piani si chiamano Free, Premium e Ultimate.

È importante non confondere i concetti. Git è il sistema di controllo di versione, un programma sul vostro computer. GitLab è un servizio che ospita una copia remota del repository e aggiunge un'interfaccia e strumenti per il team. Senza Git non si lavora con GitLab, mentre Git funziona benissimo anche senza GitLab.

Git e GitLab: qual è la differenza

Chi cerca «git e gitlab cos'è» di solito si imbatte nei due termini in un annuncio di lavoro o nel primo giorno in azienda. La differenza è come quella tra un documento e un servizio di archiviazione in cloud: Git tiene traccia delle modifiche ai file, della cronologia dei commit e dei branch in locale. GitLab riceve questa cronologia attraverso la rete e la mostra nel browser.

Tutte le operazioni sul codice — commit, branch, merge — si fanno ancora con Git. GitLab riceve il risultato con git push e permette di discuterlo con i colleghi.

GitLab e GitHub: in cosa si differenziano

Entrambi i servizi conservano repository Git e supportano la revisione del codice, quindi le competenze di base si trasferiscono quasi senza cambiamenti. Le differenze stanno negli accenti e nel modo di installazione.

In pratica uno sviluppatore usa spesso entrambi: progetti personali e portfolio su GitHub, codice di lavoro sul GitLab aziendale. I comandi Git sono gli stessi, cambia solo l'indirizzo del repository remoto.

gitlab.com o server proprio (self-hosted)

Il servizio cloud gitlab.com va bene per progetti personali e piccoli team: vi registrate e create subito i repository. Aggiornamenti, backup e disponibilità sono a carico di GitLab. I limiti del piano gratuito (numero di partecipanti, minuti di CI, spazio di archiviazione) cambiano di tanto in tanto, quindi verificate le condizioni aggiornate sulla pagina dei piani.

Il GitLab self-hosted viene installato dall'azienda sul proprio server, da pacchetto per Linux, con Docker o con Kubernetes. Il codice non esce dalla rete interna, si può collegare l'accesso aziendale tramite LDAP e configurare runner propri per le build. In cambio, gli amministratori si occupano di aggiornamenti e backup. Per lo sviluppatore la differenza è quasi invisibile: l'indirizzo non sarà gitlab.com, ma per esempio gitlab.azienda.it.

Configurare Git per lavorare con GitLab

Prima del primo commit impostate nome ed e-mail: finiscono nella cronologia, e GitLab collega i commit al vostro profilo tramite l'e-mail.

git config --global user.name "Mario Rossi"
git config --global user.email "mario@example.com"

Su Windows conviene lavorare in Git Bash: si installa insieme a Git per Windows e contiene ssh-keygen, quindi tutti i comandi di questo articolo funzionano senza modifiche. Poi scegliete il modo di accesso: HTTPS con token oppure chiave SSH.

Accesso via HTTPS: personal access token

Per le operazioni Git via HTTPS non conviene usare la password dell'account, e con l'autenticazione a due fattori attiva non funzionerebbe comunque. Create invece un personal access token nelle impostazioni del profilo GitLab (sezione Access tokens). Per lavorare con il codice bastano i permessi read_repository e write_repository; impostate una scadenza e salvate subito il token, perché non viene mostrato di nuovo.

Al primo push o clone Git chiede login e password: inserite il nome utente GitLab e, al posto della password, il token. Il gestore delle credenziali (in Git per Windows è incluso) lo ricorda, e non dovrete reinserirlo.

Accesso con chiave SSH

SSH è più comodo nell'uso quotidiano: aggiungete la chiave una volta e non dovete più digitare nulla.

ssh-keygen -t ed25519 -C "mario@example.com"
cat ~/.ssh/id_ed25519.pub

Il contenuto del file .pub (la chiave pubblica) va incollato nelle impostazioni del profilo GitLab, nella sezione SSH Keys. Verifica della connessione:

ssh -T git@gitlab.com
Welcome to GitLab, @mario.rossi!

Git clone GitLab: come clonare un repository

Nella pagina del progetto c'è il pulsante Code con due indirizzi, per SSH e per HTTPS. Copiate quello che vi serve ed eseguite git clone:

# via HTTPS
git clone https://gitlab.com/my-group/my-project.git

# via SSH
git clone git@gitlab.com:my-group/my-project.git

Su GitLab il percorso del progetto può includere sottogruppi, per esempio gitlab.com/company/backend/api.git: è normale, copiate l'indirizzo per intero.

Git clone GitLab con token

Negli script e sui server dove non c'è nessuno che possa inserire una password, il token si passa direttamente nell'indirizzo. Come nome utente potete usare il vostro login oppure il nome di servizio oauth2:

git clone https://oauth2:IL_TUO_TOKEN@gitlab.com/my-group/my-project.git

Attenzione: un indirizzo così viene salvato in .git/config e può finire nella cronologia dei comandi della shell. Per l'automazione è meglio usare un deploy token o un project access token con permessi minimi e scadenza limitata, e nella CI la variabile integrata CI_JOB_TOKEN.

Git push su GitLab: inviare il codice

Se il progetto esiste già in locale, create un progetto vuoto su GitLab (senza README, per non avere un commit in più) e collegate il repository remoto:

git remote add origin git@gitlab.com:my-group/my-project.git
git branch -M main
git push -u origin main

Il flag -u collega il branch locale a quello remoto: in seguito bastano git push e git pull. Il ciclo di lavoro è identico a quello di qualsiasi altro servizio:

git switch -c feature/login
git add .
git commit -m "Aggiungi il modulo di accesso"
git push -u origin feature/login
git pull

I tag si inviano separatamente: git push origin v1.2.0, oppure tutti insieme con git push --tags. In GitLab i tag sono visibili nella sezione Tags e spesso avviano la pipeline di rilascio.

Errori tipici di git push su GitLab

• HTTP Basic: Access denied — login errato oppure è stata inserita la password invece del token. Create un token con il permesso write_repository ed eliminate la vecchia voce dal gestore delle credenziali.
• Permission denied (publickey) — GitLab non riconosce la chiave SSH. Verificate che la chiave pubblica sia nel profilo ed eseguite ssh -T git@gitlab.com.
• You are not allowed to push code to protected branches — il branch (di solito main) è protetto. Inviate le modifiche al vostro branch e aprite una merge request.
• rejected ... (fetch first) — sul server ci sono commit che voi non avete. Eseguite git pull --rebase e ripetete il push.
• remote: Project not found — errore nell'indirizzo oppure non avete accesso al progetto; chiedete il ruolo al proprietario.

Merge request in GitLab

La merge request è l'equivalente della pull request di GitHub: una richiesta di unire il vostro branch in quello principale. È nella MR che i colleghi lasciano commenti sulle righe di codice, partono i controlli CI e si decide l'unione. Dopo il push di un nuovo branch GitLab mostra nel terminale il link per creare la MR, e nell'interfaccia web compare la proposta di crearla.

La MR si può creare anche direttamente dalla riga di comando con le push option:

git push -o merge_request.create -o merge_request.target=main origin feature/login

Il flusso tipico è questo: branch per l'attività → commit → push → MR → revisione e pipeline verde → merge. Al merge GitLab può unire i commit in uno solo (squash) ed eliminare il branch di partenza. Se nella MR c'è un conflitto, la soluzione più semplice è aggiornare il branch in locale con git pull --rebase origin main oppure git merge main, risolvere i conflitti e fare di nuovo il push.

Contrassegnate il lavoro non finito come Draft: una MR di questo tipo non può essere unita per errore, ma i colleghi possono già vedere le modifiche e discuterle.

CI/CD in GitLab: .gitlab-ci.yml

La caratteristica principale di GitLab è il CI/CD integrato. Basta mettere nella radice del repository un file .gitlab-ci.yml: a ogni push GitLab avvia una pipeline composta da fasi (stages) e job. I job sono eseguiti dai runner: su gitlab.com ce ne sono di condivisi, sul proprio server vanno installati separatamente.

stages:
  - test
  - deploy

test:
  stage: test
  image: python:3.12
  script:
    - pip install -r requirements.txt
    - pytest

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  rules:
    - if: $CI_COMMIT_TAG

In questo esempio i test vengono eseguiti a ogni push, mentre il job deploy parte solo quando viene inviato un tag: git tag v1.0.0 e git push origin v1.0.0. I risultati della pipeline si vedono direttamente nella merge request, e si può impedire l'unione finché i controlli non sono superati.

Come eliminare un repository in GitLab

I comandi Git non sanno eliminare un progetto sul server: git push modifica solo branch e tag. Il progetto si elimina dall'interfaccia web: impostazioni del progetto, sezione General, blocco Advanced, pulsante di eliminazione con conferma del nome. Serve il ruolo Owner. La copia locale resta: è solo una cartella con .git.

Se volete scollegare il repository locale da GitLab senza eliminare nulla sul server, basta git remote remove origin.

Quando scegliere GitLab

• Il codice non può stare in un servizio esterno: serve un server proprio.
• Serve un CI/CD integrato senza servizi di terze parti.
• Siete in una grande organizzazione con una gerarchia di team: utili i gruppi annidati e i ruoli flessibili.
• State entrando in un'azienda che già usa GitLab: in quel caso la scelta è già fatta, ma le competenze Git si trasferiscono integralmente.

Per il portfolio e l'open source si preferisce di solito GitHub, che ha una comunità più ampia e maggiore visibilità dei progetti. Nulla vieta di tenere lo stesso progetto su entrambi i servizi: un repository può avere più remote.

Conclusioni

GitLab è una piattaforma per repository Git con revisione tramite merge request, attività e CI/CD integrato, disponibile sia nel cloud sia su un server proprio. Il lavoro con essa si riduce ai comandi noti: configurate l'accesso con token o chiave SSH, poi clone, commit, push e merge request. Repository remoti e processi di team sono trattati nella pratica nel corso su Git.