Come eseguire GitHub Actions e GitLab CI localmente prima del push

Puoi eseguire GitHub Actions sul tuo computer con `act` e GitLab CI con gitlab-ci-local: entrambi leggono il file della pipeline e avviano ogni lavoro in un contenitore Docker. Installa Docker, installa il runner, quindi esegui act -j test o gitlab-ci-local test dalla cartella del repository. Un lavoro non riuscito ora fallisce in pochi secondi sulla tua macchina invece che dopo un push e un'attesa per un corridore ospitato.

Questa guida illustra cosa installare su macOS, Windows e Linux, i comandi per entrambi i corridori, un flusso di lavoro di esempio che puoi copiare, i limiti delle esecuzioni locali e gli errori che le persone riscontrano per primi. La procedura dettagliata utilizza GitTree, il client Git che creiamo: la sua pagina Condutture locali controlla ciò che hai installato, scrive un file di esempio e prepara il comando esatto per te. Le pipeline locali fanno parte del piano gratuito di GitTree e non necessitano di un account di hosting.

Perché eseguire pipeline CI localmente?

Ogni modifica a un file del flusso di lavoro è un codice che non puoi testare finché non viene eseguito. Senza un runner locale il ciclo è: modifica YAML, commit, push, attesa di un runner, lettura del log, ripetizione. Ogni round costa minuti e lascia una scia di commit come "riprova". Un'esecuzione locale riduce il ciclo a pochi secondi e mantiene pulita la cronologia.

Cosa ti serve: Docker più un corridore

Entrambi i corridori avviano ogni lavoro in un contenitore, quindi un motore Docker deve essere installato e in esecuzione: Docker Desktop, OrbStack o Colima su macOS, Docker Desktop su Windows, Docker Engine o Docker Desktop su Linux. Quindi installa il runner per il tuo file.

gitlab-ci-local richiede Node.js 18 o versione successiva quando lo installi con npm. Controlla la configurazione con docker info, act --version e gitlab-ci-local --version: se docker info fallisce, avvia il motore prima di ogni altra cosa.

Esegui GitHub Actions localmente con act

Esegui act dalla cartella principale del repository. Elenca prima i lavori, quindi esegui quello su cui stai lavorando. Per impostazione predefinita, act simula un evento push, quindi i lavori che vengono eseguiti solo su altri eventi necessitano del nome dell'evento.

# list workflows and jobs
act -l

# run one job from one workflow file
act -W .github/workflows/ci.yml -j test

# simulate a pull request instead of a push
act pull_request -j test

# pass a secret the job needs
act -j deploy -s NPM_TOKEN="$NPM_TOKEN"

# Apple silicon: run x86_64 images
act -j test --container-architecture linux/amd64

La prima esecuzione chiede quale immagine del corridore utilizzare. Medio si adatta alla maggior parte dei progetti; alle immagini piccole mancano gli strumenti inclusi nei corridori ospitati e l'immagine completa è molto grande. Se un passaggio fallisce con "comando non trovato", scegli un'immagine più grande con -P ubuntu-latest=<image> o installa lo strumento in un passaggio.

Esegui GitLab CI localmente con gitlab-ci-local

gitlab-ci-local legge .gitlab-ci.yml dalla cartella corrente. Senza argomenti esegue l'intera pipeline; assegnargli un nome di lavoro per eseguire un lavoro. --list mostra i lavori senza eseguirli, un modo rapido per verificare che YAML analizzi.

# list jobs and stages
gitlab-ci-local --list

# run one job
gitlab-ci-local test

# pass a CI/CD variable
gitlab-ci-local test --variable API_URL=http://localhost:8080

Un flusso di lavoro di esempio da cui iniziare

Questa è la forma dell'esempio GitHub Actions di GitTree: due lavori, build e poi test, che funzionano allo stesso modo con act e su GitHub. Sostituisci i comandi con i tuoi.

name: GitTree local check

on:
  push:
  pull_request:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm ci && npm run build

  test:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v4
      - name: Test
        run: npm test

Differenza tra un'esecuzione locale e un CI ospitato

• Segreti e variabili configurati su GitHub o GitLab non sono disponibili; passare quelli di cui un lavoro ha bisogno.
• Contenitori, non macchine virtuali: i servizi che necessitano di systemd o di una macchina virtuale completa non vengono eseguiti allo stesso modo.
• Le immagini differiscono dai corridori ospitati; uno strumento mancante è un pacchetto mancante, non un flusso di lavoro interrotto.
• Gli eventi sono simulati: act predefinito è push; i flussi di lavoro, le inclusioni e i modelli riutilizzabili vengono risolti dal runner, non dal tuo editor.
• Un'esecuzione locale di passaggio non è un risultato ospitato: accorcia il ciclo; il tuo host ha ancora l'ultima parola.

Errori comuni e correzioni

Prima di eseguire il push: prevedere i conflitti, verificare la presenza di segreti, visualizzare in anteprima il push

L'esecuzione di una pipeline locale risponde a una domanda: i lavori passeranno. Altri tre controlli rilevano ciò che CI segnala in ritardo o non lo segnala affatto, e ognuno di essi viene eseguito anche sul tuo computer prima che venga inviato qualsiasi cosa.

1. Prevedi l'unione. git merge-tree --write-tree --name-only HEAD origin/main si unisce in memoria ed elenca i file in conflitto, senza toccare l'albero di lavoro. GitTree effettua lo stesso tipo di controllo e avvisa prima di un'unione che potrebbe creare conflitto; vedi come risolvere i conflitti di unione Git.
2. Verifica la presenza di segreti. Prima di un commit o un push, GitTree esegue la scansione locale della modifica alla ricerca di probabili token, password e chiavi private e si ferma con una finestra di dialogo se ne trova uno. Un segreto che raggiunge il remoto deve essere ruotato, quindi il momento più economico per catturarne uno è prima del push. Un avviso non è una garanzia, quindi controlla comunque ciò che invii.
3. Visualizza l'anteprima del push. Anteprima di spedizione elenca i commit e i file che il push invierebbe e, per ogni file del flusso di lavoro che può leggere, se una pipeline Verrà eseguita, Può essere eseguita o Non verrà eseguita su questo push, con il motivo.

Quindi esegui il lavoro localmente ed esegui il push una volta. La guida agli avvisi segreti e la guida all'anteprima della spedizione trattano entrambe le finestre di dialogo in dettaglio.

E che dire di Bitbucket Pipelines e Azure Pipelines?

Non esiste alcun corridore locale gestito per bitbucket-pipelines.yml o azure-pipelines.yml che corrisponda a act o gitlab-ci-local. Un approccio pratico consiste nel mantenere i comandi di creazione e test negli script, chiamarli dalla pipeline ospitata e aggiungere un piccolo file GitHub Actions o GitLab CI solo per le esecuzioni locali. GitTree contrassegna questi file Nessun corridore locale e offre gli esempi esattamente per questo.

Passaggi successivi: la Guida all'esecuzione delle pipeline in locale documenta ogni pulsante, le Esecuzioni CI/CD coprono le esecuzioni ospitate, le ripetizioni e le approvazioni e l'Avvio strumenti elenca gli altri strumenti integrati di GitTree.