CircleCI: basi, orbs e integrazione continua

Architettura di CircleCI: Orbs, Executors e Contexts

L'architettura di CircleCI si compone di tre livelli: Pipeline, Workflow e Job. Pipeline è il processo principale attivato da un commit. Una Pipeline è costituita da Workflow — un grafo di Job che possono essere eseguiti sequenzialmente o in parallelo. Ogni Job viene eseguito su un Executor — un ambiente con un'immagine specifica. Un Workflow può includere approval gates — conferma manuale prima del deploy.

Gli orbs sono pacchetti di configurazione YAML riutilizzabili distribuiti tramite CircleCI Orb Registry. Un Orb può contenere job, comandi, esecutori ed esempi. Orbs popolari: android, ios, flutter, firebase, slack. Ad esempio, l'aggiunta dell'orb android sostituisce oltre 50 righe di configurazione con una singola riga. CircleCI CLI consente di creare, testare e pubblicare i propri orbs per standardizzare le pipeline all'interno dell'organizzazione.

Tipi di Executors

I Contexts sono insiemi nominati di variabili d'ambiente disponibili a livello di organizzazione. Ad esempio, il contesto app-store-credentials contiene l'Apple ID e la password per la pubblicazione sull'App Store. Ciò semplifica la gestione dei secret tra progetti senza duplicazioni.

Configurare CircleCI per progetti Android e iOS

Per un progetto Android, CircleCI utilizza l'immagine Docker cibuilds/android con Android SDK. Un workflow tipico include: checkout, installazione JDK, caching di Gradle, build ed esecuzione dei test. Per iOS è necessario un executor macOS con Xcode e configurazione del code signing. Al primo collegamento, CircleCI rileva automaticamente il tipo di progetto e genera una configurazione di base con le impostazioni consigliate.

Per i progetti Flutter, CircleCI fornisce l'orb circleci/flutter, che include esecutori con Flutter SDK preinstallato per Linux e macOS. L'orb supporta la build per entrambe le piattaforme, il caching di pub-cache e l'esecuzione dei test. La configurazione si riduce a specificare la versione di Flutter e i comandi di build. Per versioni personalizzate di Flutter o Dart, è possibile utilizzare un'immagine Docker con l'SDK necessario. L'orb Flutter supporta anche opzioni avanzate — ad esempio, l'analisi del codice tramite dart analyze prima della build.

Android Orb — Avvio rapido

L'orb Android di CircleCI fornisce job pronti: build-and-test, deploy-to-play-store. L'orb configura automaticamente l'ambiente, il caching e la firma. Dopo aver aggiunto l'orb, è sufficiente specificare la versione dell'SDK e i comandi di build.

Build iOS con executor macOS

Per le build iOS, l'executor viene impostato su macos con una versione di Xcode. CircleCI fornisce immagini con Xcode 14, 15 e 16. Dopo il checkout, il codice viene compilato tramite xcodebuild e i test vengono eseguiti sul simulatore. Il code signing viene configurato tramite fastlane match o installazione manuale dei certificati.

Caching ed esecuzione parallela

Il caching è un elemento chiave delle prestazioni in CircleCI. Il meccanismo di cache salva le directory tra le esecuzioni del workflow utilizzando una chiave. Per Gradle, viene cachato ~/.gradle; per CocoaPods — Pods/; per npm/SPM — node_modules/.build. Quando il file di lock cambia, la cache viene aggiornata automaticamente. CircleCI supporta politiche separate: save_cache può essere differito (when: always), mentre restore_cache è obbligatorio.

Il parallelismo combinato con resource class consente di ottimizzare le prestazioni di build. Resource class determina CPU e RAM per un contenitore: small (1 CPU, 2 GB), medium (2 CPU, 4 GB), medium+ (3 CPU, 5 GB) e large (4 CPU, 8 GB). Per le build iOS con Xcode, si consiglia di utilizzare un executor macOS con resource class medium o larger — la compilazione del codice Swift richiede risorse significative.

Il parallelismo suddivide i test su più contenitori, riducendo i tempi di esecuzione. Ad esempio: parallelism: 4 esegue i test in 4 contenitori paralleli. CircleCI distribuisce automaticamente i file di test tra i contenitori. Il comando circleci tests glob raccoglie l'elenco dei test e circleci tests split li distribuisce uniformemente.

Esempio di caching di Gradle

- restore_cache:
    keys:
      - v1-gradle-{{ checksum "build.gradle" }}
      - v1-gradle-

- run: ./gradlew assembleDebug

- save_cache:
    key: v1-gradle-{{ checksum "build.gradle" }}
    paths:
      - ~/.gradle/caches
      - ~/.gradle/wrapper

Esempio di configurazione .circleci/config.yml

Esaminiamo una configurazione completa di CircleCI per un progetto Android con due job: build e test. La configurazione include un executor Docker con Android SDK, caching di Gradle ed esecuzione parallela dei test. Gli artifact vengono salvati per il download. Il workflow build-and-test esegue entrambi i job a ogni push sul branch principale.

version: 2.1

orbs:
  android: circleci/android@2.5.0

jobs:
  build:
    executor: android/default
    steps:
      - checkout
      - android/restore-gradle-cache
      - run: ./gradlew assembleRelease
      - android/save-gradle-cache
      - store_artifacts:
          path: app/build/outputs/apk/release
      - store_test_results:
          path: app/build/reports/tests

  test:
    executor: android/default
    parallelism: 4
    steps:
      - checkout
      - android/restore-gradle-cache
      - run:
          command: |
            cd app
            ./gradlew test

workflows:
  version: 2
  build-and-test:
    jobs:
      - build
      - test

Orbs: soluzioni CI/CD pronte

Quando si sceglie tra CircleCI e le alternative — se il tuo team utilizza GitHub, GitHub Actions potrebbe essere una scelta più semplice. CircleCI è preferibile per i team che necessitano di esecuzione parallela flessibile dei test, configurazione personalizzata dell'ambiente executor e statistiche di build dettagliate. CircleCI Insights fornisce una dashboard con metriche delle prestazioni delle pipeline: tempo medio di build, tendenze e colli di bottiglia. Insights aiuta a identificare i job di lunga durata e ottimizzarli. L'API CircleCI consente di gestire le pipeline a livello di programmazione, attivare build e ottenere metriche.

Per la gestione sicura dei secret, CircleCI supporta i Contexts — insiemi nominati di variabili d'ambiente a livello di organizzazione. I Contexts sono protetti da accesso basato sui ruoli: solo team specifici possono utilizzare un determinato contesto. Ad esempio, il contesto production-deploy contiene le chiavi di App Store Connect ed è accessibile solo agli sviluppatori lead. Combinato con gli approval gates, ciò forma un sistema di sicurezza CI/CD completo.

CircleCI Orb Registry contiene centinaia di pacchetti pronti per varie attività CI/CD. Per lo sviluppo mobile, gli orbs principali includono: circleci/android, circleci/ios, circleci/flutter, laurencerussell/firebase-app-distribution. Ogni orb è versionato e documentato. Gli orbs possono essere pubblici (disponibili a tutti) o privati (solo per la tua organizzazione).

L'uso degli orbs riduce la configurazione di 5–10 volte. Ad esempio, l'orb circleci/android fornisce l'executor android/default con SDK preinstallato e i comandi restore-gradle-cache, save-gradle-cache. L'orb circleci/ios include un executor con Xcode e comandi per il code signing tramite fastlane. Gli orbs possono essere facilmente combinati: aggiungi un orb android per la build e un orb slack per le notifiche.

CircleCI offre anche il supporto integrato per i report di test. Store_test_results analizza e visualizza automaticamente i risultati dei test da JUnit, XCTest e altri formati. Per i progetti mobili, ciò significa visualizzazione centralizzata dei test falliti, tendenze dei tempi di esecuzione e cronologia della stabilità delle build, semplificando la manutenzione della qualità del codice.

Esempio con l'orb iOS

orbs:
  ios: circleci/ios@2.0.0

jobs:
  build-and-test:
    executor: ios/default
    steps:
      - checkout
      - ios/install-dependencies
      - ios/build-and-test

Pubblicazione di un orb personalizzato è disponibile tramite CircleCI CLI. I comandi circleci orb create e circleci orb publish caricano l'orb nel registro. Ciò è utile per standardizzare il CI/CD all'interno di un'organizzazione — crea una volta, usa in tutti i progetti.