CircleCI: podstawy, orbs i ciągła integracja

Czym jest CircleCI?

CircleCI — to chmurowa platforma CI/CD, założona w 2011 roku. System pozwala opisywać pipeline'y w pliku YAML .circleci/config.yml i uruchamiać je w izolowanych kontenerach lub maszynach wirtualnych. CircleCI obsługuje wszystkie popularne języki i platformy, w tym Android, iOS, Flutter i React Native.

Dla programowania mobilnego CircleCI oferuje macOS executory do kompilacji iOS z preinstalowanym Xcode, Linux executory dla Android z Android SDK, a także cache'owanie Gradle i CocoaPods. Kluczową cechą są orbs, które pozwalają podłączyć gotowe konfiguracje jedną linią: orb: android, orb: ios, orb: flutter. CircleCI automatycznie określa typ projektu i proponuje domyślną konfigurację przy pierwszym podłączeniu repozytorium.

Platforma obsługuje dostęp SSH do uruchomionych kontenerów w celach debugowania — przydatna funkcja przy analizie nieudanych kompilacji. CircleCI CLI pozwala lokalnie walidować i uruchamiać konfiguracje, zarządzać orbs i przeglądać logi. Platforma integruje się z GitHub, GitHub Enterprise, Bitbucket i GitLab przez system webhooks.

Architektura CircleCI: Orbs, Executory i Contexts

Architektura CircleCI obejmuje trzy poziomy: Pipeline, Workflow i Job. Pipeline — to proces główny, uruchamiany przy commicie. Pipeline składa się z Workflows — grafu Jobs, które mogą być wykonywane sekwencyjnie lub równolegle. Każdy Job jest wykonywany na Executor — środowisku z określonym obrazem. Workflow może zawierać approval gates — ręczne potwierdzenie przed wdrożeniem.

Orbs — to wielokrotnie używane pakiety konfiguracji YAML, rozpowszechniane przez CircleCI Orb Registry. Orb może zawierać jobs, commands, executory i przykłady. Popularne orbs: android, ios, flutter, firebase, slack. Na przykład, podłączenie android orb zastępuje 50+ linii konfiguracji jedną linią. CircleCI CLI pozwala tworzyć, testować i publikować własne orbs w celu standaryzacji pipeline'ów w organizacji.

Typy Executorów

Contexts — to nazwane zbiory zmiennych środowiskowych, dostępne na poziomie organizacji. Na przykład, kontekst app-store-credentials zawiera Apple ID i hasło do publikacji w App Store. Upraszcza to zarządzanie secretami między projektami bez powielania.

Konfiguracja CircleCI dla projektów Android i iOS

Dla projektu Android CircleCI używa obrazu Docker cibuilds/android z Android SDK. Typowy workflow obejmuje: checkout, instalację JDK, cache'owanie Gradle, kompilację, uruchomienie testów. Dla iOS wymagany jest macOS executor z Xcode i konfiguracją code signing. Przy pierwszym podłączeniu CircleCI automatycznie określa typ projektu i generuje podstawową konfigurację z zalecanymi ustawieniami.

Dla projektów Flutter CircleCI udostępnia orb circleci/flutter, który zawiera executory z preinstalowanym Flutter SDK dla Linux i macOS. Orb obsługuje kompilację dla obu platform, cache'owanie pub-cache i uruchamianie testów. Konfiguracja sprowadza się do wskazania wersji Flutter i poleceń kompilacji. Dla niestandardowych wersji Flutter lub Dart można użyć obrazu Docker z odpowiednim SDK. Flutter orb obsługuje również advanced options — na przykład analizę kodu przez dart analyze przed kompilacją.

Android orb — szybki start

Android orb od CircleCI udostępnia gotowe jobs: build-and-test, deploy-to-play-store. Orb automatycznie konfiguruje środowisko, cache'owanie i podpis. Po podłączeniu orb wystarczy wskazać wersję SDK i polecenia kompilacji.

iOS kompilacja z macOS executor

Do kompilacji iOS wskazywany jest executor: macos z wersją xcode. CircleCI udostępnia obrazy z Xcode 14, 15 i 16. Po checkout kod jest kompilowany przez xcodebuild, testy uruchamiane na symulatorze. Code signing konfiguruje się przez fastlane match lub ręczną instalację certyfikatów.

Cache'owanie i wykonywanie równoległe

Cache'owanie — kluczowy element wydajności CircleCI. Mechanizm cache zachowuje katalogi między uruchomieniami workflow według klucza. Dla Gradle cache'owany jest ~/.gradle, dla CocoaPods — Pods/, dla npm/SPM — node_modules/.build. Przy zmianie pliku lock cache jest automatycznie aktualizowany. CircleCI obsługuje oddzielne polityki: save_cache może być opóźnione (when: always), a restore_cache — obowiązkowe.

Parallelism w połączeniu z resource class pozwala precyzyjnie dostrajać wydajność kompilacji. Resource class określa liczbę CPU i RAM dla kontenera: small (1 CPU, 2 GB), medium (2 CPU, 4 GB), medium+ (3 CPU, 5 GB) i large (4 CPU, 8 GB). Dla kompilacji iOS z Xcode zaleca się używanie macOS executor z resource class medium lub larger — kompilacja kodu Swift wymaga znacznych zasobów.

Parallelism dzieli testy na wiele kontenerów, skracając czas wykonania. Na przykład: parallelism: 4 uruchamia testy w 4 równoległych kontenerach. CircleCI automatycznie rozdziela pliki testowe między kontenery. Polecenie circleci tests glob zbiera listę testów, a circleci tests split rozdziela je równomiernie.

Przykład cache'owania 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

Przykład konfiguracji .circleci/config.yml

Rozpatrzmy pełną konfigurację CircleCI dla projektu Android z dwoma job: build i test. Konfiguracja obejmuje Docker executor z Android SDK, cache'owanie Gradle i równoległe uruchamianie testów. Artifacts są zachowywane do pobrania. Workflow build-and-test uruchamia oba job przy każdym push do głównej gałęzi.

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: gotowe rozwiązania dla CI/CD

Przy wyborze między CircleCI a alternatywami — jeśli zespół używa GitHub, GitHub Actions może być prostszym wyborem. CircleCI jest preferowany dla zespołów, które wymagają elastycznego parallel test execution, personalizacji executor environment i szczegółowych statystyk kompilacji. CircleCI Insights udostępnia dashboard z metrykami wydajności pipeline'ów: średni czas kompilacji, trendy i wąskie gardła. Insights pomaga identyfikować długotrwałe jobs i optymalizować je. CircleCI API pozwala programowo zarządzać pipeline'ami, uruchamiać kompilacje i pobierać metryki.

Do bezpiecznej pracy z secretami CircleCI obsługuje Contexts — nazwane zbiory zmiennych środowiskowych na poziomie organizacji. Contexts są chronione dostępem rolą: tylko określone zespoły mogą używać konkretnego context. Na przykład, context production-deploy zawiera klucze App Store Connect i jest dostępny tylko dla lead developerów. W połączeniu z approval gates tworzy to pełnoprawny system bezpieczeństwa CI/CD.

CircleCI Orb Registry zawiera setki gotowych pakietów do różnych zadań CI/CD. Dla programowania mobilnego kluczowe orbs obejmują: circleci/android, circleci/ios, circleci/flutter, laurencerussell/firebase-app-distribution. Każdy orb jest wersjonowany i dokumentowany. Orbs mogą być publiczne (dostępne dla wszystkich) i prywatne (tylko dla twojej organizacji).

Używanie orbs skraca konfigurację w 5–10 razy. Na przykład, orb circleci/android udostępnia executor android/default z preinstalowanym SDK i polecenia restore-gradle-cache, save-gradle-cache. Orb circleci/ios zawiera executor z Xcode i polecenia do code signing przez fastlane. Orbs można łatwo łączyć: podłączyć android orb do kompilacji i slack orb do powiadomień.

CircleCI oferuje również wbudowaną obsługę raportów testowych. Store_test_results automatycznie parsuje i wizualizuje wyniki testów JUnit, XCTest i innych formatów. Dla projektów mobilnych oznacza to scentralizowany podgląd nieudanych testów, trendów czasu wykonania i historii stabilności kompilacji, co ułatwia utrzymanie jakości kodu.

Przykład z iOS orb

orbs:
  ios: circleci/ios@2.0.0

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

Publikacja niestandardowego orb jest dostępna przez CircleCI CLI. Polecenie circleci orb create i circleci orb publish ładuje orb do rejestru. Jest to przydatne do standaryzacji CI/CD w organizacji — tworzy się raz, używa we wszystkich projektach.