# Come abbiamo ridotto il tempo di attesa della nostra CI da 30 minuti a 5 minuti

Published: 2026-01-01 · Author: keith-williams

Canonical: https://cal.com/blog/how-we-cut-our-ci-wall-time-from-30-minutes-to-5-minutes

## Le fondamenta: migrare a Blacksmith

Avevamo già provato a migrare a Blacksmith, ma avevamo incontrato problemi. Con un branch `main` attivo come il nostro, non volevamo avere a che fare con l’instabilità della CI. Questa volta la migrazione è stata lineare ([#26247](https://github.com/calcom/cal.com/pull/26247)): sostituire i runner `buildjet-*vcpu-ubuntu-2204` con `blacksmith-*vcpu-ubuntu-2404` in 28 file di workflow, sostituire le azioni `cache` e `setup-node` e regolare le allocazioni vCPU. L’unico vero problema che abbiamo incontrato è stato quello della cache corrotta con i file `.next` (ne parlo meglio nella sezione sul caching).

Dopo l’upgrade, abbiamo notato subito un miglioramento di velocità 2x nel recupero della cache. Con `yarn install` che pesa 1,2 GB, questo fa risparmiare circa 22 secondi su ogni job che deve eseguire `yarn install`, cioè sulla maggior parte. Stiamo anche sfruttando il [container caching di Blacksmith](https://docs.blacksmith.sh/blacksmith-caching/docker-container-caching) per i servizi usati in molti job (Postgres, Redis, Mailhog). Il job `Initialize containers` ora è migliorato di oltre il 50%, da 20 secondi a 9 secondi.

```
jobs:
  build:
    name: Build Web App
    runs-on: blacksmith-4vcpu-ubuntu-2404
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/yarn-install
      - uses: ./.github/actions/cache-build
```

#### Cosa abbiamo dovuto correggere

I runner di Blacksmith espongono il numero di CPU della macchina host invece delle vCPU assegnate (di solito 4). Playwright, volendo essere d’aiuto, avrebbe avviato worker per corrispondere a quel numero, causando contesa delle risorse e test flaky. Ci è bastato limitare esplicitamente i worker con `--workers=4` per farli combaciare con l’allocazione reale.

Abbiamo anche scoperto che un parallelismo più alto metteva in evidenza race condition nella logica di pulizia dei test. I test di integrazione che andavano bene in sequenza si scontravano quando venivano eseguiti in parallelo, producendo errori `idempotencyKey`. La soluzione ha richiesto di ripensare a come i test puliscono i propri dati: interrogare le booking tramite `eventTypeId` invece di tenere traccia dei singoli booking ID, che saltavano le booking create indirettamente dal codice sotto test ([#26269](https://github.com/calcom/cal.com/pull/26269), [#26278](https://github.com/calcom/cal.com/pull/26278), [#26283](https://github.com/calcom/cal.com/pull/26283)).

Anche i nostri test sugli screenshot hanno richiesto un aggiustamento ([#26247](https://github.com/calcom/cal.com/pull/26247)). Runner diversi hanno leggere differenze nel rendering dei font, quindi abbiamo aggiunto `deviceScaleFactor: 1` per avere un rendering coerente e aumentato leggermente la soglia di diff da `0.05` a `0.07` per tenere conto delle variazioni di antialiasing senza nascondere regressioni reali.

Andare più veloci spesso fa emergere il coupling nascosto nel tuo sistema. Il coupling c’era sempre stato; semplicemente non lo vedevi a velocità più basse. Risolvere questi problemi è ciò che rende possibili miglioramenti di velocità sostenibili.

## Principio 1: accorcia il percorso critico con una progettazione delle dipendenze

Per noi, un grosso problema era che il lint bloccava cose che non avrebbe dovuto bloccare. Quando i tuoi test E2E richiedono 7-10 minuti, bloccarli per 2-3 minuti di lint e controlli dei tipi non fa che allungare l’intero workflow. Il lint finisce molto prima degli E2E, quindi perché non farli girare in parallelo?

#### Disaccoppia le suite di test non correlate

I nostri test di integrazione e la suite E2E principale non hanno bisogno del build di API v2, quindi abbiamo rimosso quella dipendenza ([#26170](https://github.com/calcom/cal.com/pull/26170)). Al contrario, i test E2E di API v2 non hanno bisogno del build web principale. Ogni suite di test ora dipende solo da ciò che le serve davvero, permettendo il massimo parallelismo.

#### Consolida i job di preflight

Avevamo job separati per il rilevamento delle modifiche ai file (`changes`) e per il controllo dell’etichetta E2E (`check-label`). Ogni job ha un costo iniziale: avviare un runner, fare il checkout del codice, ripristinare il contesto. Unendoli in un unico job `prepare`, abbiamo eliminato overhead ridondanti ([#26101](https://github.com/calcom/cal.com/pull/26101)). Siamo andati oltre e abbiamo spostato anche i passaggi di installazione delle dipendenze nel job `prepare`, risparmiando altri 20 secondi per workflow eliminando un altro confine tra job ([#26320](https://github.com/calcom/cal.com/pull/26320)).

#### Rendi il reporting non bloccante

I report dei test E2E sono utili, ma non dovrebbero stare sul percorso critico. Abbiamo spostato i job `merge-reports`, `publish-report` e `cleanup-report` in un workflow separato attivato da `workflow_run` ([#26157](https://github.com/calcom/cal.com/pull/26157)). Ora gli engineer possono rieseguire subito i job falliti senza aspettare che la generazione del report finisca.

```
name: E2E Report

on:
  workflow_run:
    workflows: ["PR Update"]
    types:
      - completed
```

La regola è semplice: sii flessibile nel far partire prima possibile i job E2E. Non bloccare i job lunghi su prerequisiti brevi, a meno che non ci sia una dipendenza reale. Il tempo di esecuzione della tua CI è determinato dal percorso critico, e ogni dipendenza inutile allunga quel percorso.

## Principio 2: il caching è re, ma solo se fa hit

Un caching efficace richiede chiavi che si invalidano quando devono, restano stabili quando devono e un archivio cache che rimane sano nel tempo.

#### Usa `lookup-only`

Il nostro miglioramento più drastico nel caching è venuto da una semplice osservazione: stavamo scaricando circa 1,2 GB di dati in cache anche quando non dovevamo installare nulla. La cache esisteva, l’hit andava a buon fine, ma stavamo comunque pagando il costo del download prima di scoprire che potevamo saltare il passaggio di installazione.

La soluzione è stata usare controlli cache `lookup-only` ([#26314](https://github.com/calcom/cal.com/pull/26314)). Abbiamo passaggi dedicati che girano prima di tutti i job per assicurarci che le dipendenze siano installate, quindi quando i singoli job partono sappiamo che la cache esiste. Prima di tentare di ripristinare la cache completa, controlliamo prima se esiste senza scaricarla. Se tutte le cache fanno hit, saltiamo l’intero flusso di ripristino e installazione. Niente download, niente installazioni, si passa direttamente al lavoro vero. Da solo, questo ha fatto risparmiare molto tempo in ogni scenario con cache hit, che, con una progettazione corretta delle chiavi cache, dovrebbe essere la maggior parte delle esecuzioni.

```
- name: Check yarn cache (lookup-only)
  if: ${{ inputs.skip-install-if-cache-hit == 'true' }}
  uses: actions/cache/restore@v4
  id: yarn-download-cache-check
  with:
    path: ${{ steps.yarn-config.outputs.CACHE_FOLDER }}
    key: yarn-download-cache-${{ hashFiles('yarn.lock') }}
    lookup-only: true
```

Abbiamo applicato la stessa logica anche all’installazione del browser Playwright ([#26060](https://github.com/calcom/cal.com/pull/26060)). Siccome abbiamo un passaggio dedicato che garantisce che i browser di Playwright siano in cache prima che partano i job di test, possiamo usare lo stesso approccio `lookup-only`. Se la cache di Playwright fa hit, saltiamo del tutto l’installazione. Ora controlliamo prima, poi decidiamo se scaricare oppure no.

Abbiamo esteso questo pattern anche alla cache del database ([#26344](https://github.com/calcom/cal.com/pull/26344)). Usando controlli `lookup-only`, possiamo saltare la ricostruzione della cache DB quando esiste già. Abbiamo anche semplificato la chiave della cache rimuovendo il numero della PR e lo SHA, rendendola molto più riutilizzabile tra le esecuzioni.

#### Correttezza della cache

La correttezza della cache conta tanto quanto la velocità della cache. Abbiamo scoperto che il nostro pattern glob `**/node_modules/` stava includendo `apps/web/.next/node_modules/`, che è un output di build di Next.js contenente symlink e file generati che cambiano durante le build. Questo ha portato ad archivi di cache corrotti con errori di estrazione tar ([#26268](https://github.com/calcom/cal.com/pull/26268)). La correzione è stata un semplice pattern di esclusione, ma trovarla ha richiesto di capire esattamente cosa veniva messo in cache e perché.

Abbiamo anche implementato la pulizia automatica della cache ([#26312](https://github.com/calcom/cal.com/pull/26312)). Quando una PR viene unita o chiusa, ora eliminiamo le cache di build associate. Questo mantiene leggero il nostro archivio cache e previene l’accumulo di voci obsolete che non verrebbero mai più usate. Nel processo abbiamo semplificato anche il formato della chiave della cache, rimuovendo segmenti inutili come `runner.os` e `node_version` che aggiungevano complessità senza migliorare i tassi di hit.

```
delete-cache-build-on-pr-close:
  if: github.event_name == 'pull_request' && github.event.action == 'closed'
  runs-on: blacksmith-2vcpu-ubuntu-2404
  env:
    CACHE_NAME: prod-build
  steps:
    - name: Delete cache-build cache
      uses: useblacksmith/cache-delete@v1
      with:
        key: ${{ env.CACHE_NAME }}-${{ github.event.pull_request.head.ref }}
        prefix: "true"
```

#### Turbo Remote Caching

Siamo passati a Next.js 16 ([#26093](https://github.com/calcom/cal.com/pull/26093)), che ha ridotto i nostri build da 6+ minuti a ~1 minuto (un grande grazie al team di Next.js per i miglioramenti enormi). Con Turbo Remote Caching attivo, i build successivi richiedono solo 7 secondi per essere recuperati dalla cache, rispetto a ~1 minuto per un build completo.

Abbiamo anche abilitato Turbo Remote Caching per i nostri test E2E di API v2 ([#26331](https://github.com/calcom/cal.com/pull/26331)). Prima, ogni shard E2E ricostruiva da zero i pacchetti della piattaforma. Ora ogni shard beneficia della cache remota di Turbo, e abbiamo ottimizzato la compilazione TypeScript di Jest abilitando `isolatedModules` e disattivando la diagnostica in CI, cosa che velocizza in modo significativo l’avvio dei test.

## Principio 3: scala i test con lo sharding

Quando hai 1.100+ casi di test distribuiti su 82 file di test E2E, eseguirli in sequenza significa lasciare performance sul tavolo. Lo sharding dei test, che divide la tua suite tra più runner paralleli, è il modo più diretto per ridurre il tempo di wall-clock nelle suite di test grandi. Avevamo già lo sharding per la nostra suite E2E principale, ma l’abbiamo aumentato da 4 a 8 shard ([#26342](https://github.com/calcom/cal.com/pull/26342)), riducendo il tempo totale della suite E2E di un altro minuto. I nostri test E2E di API v2 continuavano a girare come un singolo job.

Abbiamo suddiviso i nostri test E2E di API v2 in 4 job paralleli usando l’opzione `--shard` integrata di Jest ([#26183](https://github.com/calcom/cal.com/pull/26183)). Ogni shard gira in modo indipendente con i propri servizi Postgres e Redis, e gli artifact hanno nomi univoci per shard. Quello che prima richiedeva 10+ minuti come singolo job ora termina molto più velocemente con il lavoro distribuito su quattro runner.

```
- name: Run Tests
  working-directory: apps/api/v2
  run: |
    yarn test:e2e:ci --shard=${{ matrix.shard }}/${{ strategy.job-total }}
    EXIT_CODE=$?
    echo "yarn test:e2e:ci --shard=${{ matrix.shard }}/${{ strategy.job-total }} command exit code: $EXIT_CODE"
    exit $EXIT_CODE
```

Lo sharding su larga scala fa emergere anche problemi di infrastruttura che potresti non notare con un’esecuzione sequenziale. Quando più job cercano di popolare contemporaneamente la stessa cache del database, si verificano race condition. Abbiamo risolto il problema creando un job dedicato `setup-db` che gira prima di tutti i job di test E2E e di integrazione ([#26171](https://github.com/calcom/cal.com/pull/26171)). Questo singolo job popola la cache del database una sola volta, e tutti i job a valle la ripristinano da lì. Niente race, niente lavoro duplicato.

Abbiamo anche creato un workflow dedicato per i test unitari di API v2, separandoli dalla suite di test principale ([#26189](https://github.com/calcom/cal.com/pull/26189)). Questo permette loro di girare in parallelo con altri controlli invece di competere per le risorse in un job di test monolitico.

## L’effetto cumulativo

Nessuno di questi cambiamenti, preso da solo, avrebbe ridotto il nostro tempo CI dell’83%. I guadagni arrivano dalla loro combinazione.

Dipendenze intelligenti fanno partire i job prima. Un caching efficace significa che quei job spendono meno tempo nella configurazione. Lo sharding significa che l’esecuzione vera dei test avviene in parallelo. Insieme, comprimono il percorso critico da ogni direzione.

L’investimento si compone nel tempo. Ogni PR ora riceve feedback più velocemente. Gli engineer restano più a lungo nel flow. La tentazione di accumulare le modifiche diminuisce, e questo significa diff più piccoli e più facili da revisionare. La qualità del codice migliora perché il ciclo di feedback è più stretto.

Continueremo a investire nelle prestazioni della CI perché i ritorni sono reali e misurabili. L’obiettivo non è la velocità fine a se stessa; è permettere agli engineer di rilasciare software di qualità più velocemente. Quando la CI è veloce, muoversi rapidamente e mantenere standard elevati lavorano insieme invece di ostacolarsi.

### Pull request citate

**Fondamenta: migrazione da Buildjet a Blacksmith**

-   [#26247](https://github.com/calcom/cal.com/pull/26247) - Migrare i workflow di GitHub da Buildjet a Blacksmith

**Stabilità dei test**

-   [#26269](https://github.com/calcom/cal.com/pull/26269) - Correggere i test e2e flaky con sessioni utente isolate

-   [#26278](https://github.com/calcom/cal.com/pull/26278) - Stabilizzare i test e2e con locator con scope e schedulazioni deterministiche

-   [#26283](https://github.com/calcom/cal.com/pull/26283) - Migliorare l’isolamento dei test per i test e2e dei managed scheduling links

**Turbo Remote Caching**

-   [#26093](https://github.com/calcom/cal.com/pull/26093) - Aggiornare a Next 16 (build ridotti da 6+ minuti a ~1 minuto)

-   [#26331](https://github.com/calcom/cal.com/pull/26331) - Abilitare Turbo Remote Caching (i build successivi richiedono 7 s)

**Dipendenze dei job e ottimizzazione dei workflow**

-   [#26101](https://github.com/calcom/cal.com/pull/26101) - Consolidare i job changes e check-label in prepare

-   [#26170](https://github.com/calcom/cal.com/pull/26170) - Disaccoppiare i test non API v2 dal build API v2

-   [#26157](https://github.com/calcom/cal.com/pull/26157) - Rendere non bloccanti i job dei report E2E spostandoli in un workflow separato

-   [#26320](https://github.com/calcom/cal.com/pull/26320) - Spostare il job deps nel job prepare per risparmiare ~20 s per workflow

**Usa `lookup-only`**

-   [#26314](https://github.com/calcom/cal.com/pull/26314) - Usare il controllo cache `lookup-only` per saltare i download del job deps

-   [#26060](https://github.com/calcom/cal.com/pull/26060) - Saltare l’installazione di Playwright quando la cache fa hit

-   [#26344](https://github.com/calcom/cal.com/pull/26344) - Usare `lookup-only` per la cache DB e semplificare la chiave della cache

**Correttezza della cache**

-   [#26268](https://github.com/calcom/cal.com/pull/26268) - Escludere .next/node\_modules dalla cache yarn per prevenire la corruzione

-   [#26312](https://github.com/calcom/cal.com/pull/26312) - Eliminare le voci della cache-build alla chiusura della PR

**Sharding dei test e infrastruttura**

-   [#26342](https://github.com/calcom/cal.com/pull/26342) - Aumentare gli shard E2E principali da 4 a 8 (fa risparmiare 1 minuto)

-   [#26183](https://github.com/calcom/cal.com/pull/26183) - Suddividere i test E2E di API v2 in 4 job paralleli

-   [#26171](https://github.com/calcom/cal.com/pull/26171) - Aggiungere un job dedicato setup-db per eliminare la race condition della cache

-   [#26189](https://github.com/calcom/cal.com/pull/26189) - Creare un nuovo workflow per i test unitari di API v2
