CircleCI: основи, orbs и непрекъсната интеграция

Какво е CircleCI?

CircleCI — е облачна CI/CD платформа, основана през 2011 г. Системата позволява описване на пайплайни в YAML файл .circleci/config.yml и тяхното изпълнение в изолирани контейнери или виртуални машини. CircleCI поддържа всички популярни езици и платформи, включително Android, iOS, Flutter и React Native.

За мобилна разработка CircleCI предлага macOS executors за iOS компилации с предварително инсталиран Xcode, Linux executors за Android с Android SDK, както и кеширане на Gradle и CocoaPods. Ключова характеристика — orbs, които позволяват свързване на готови конфигурации с един ред: orb: android, orb: ios, orb: flutter. CircleCI автоматично определя типа на проекта и предлага шаблонна конфигурация при първото свързване на хранилището.

Платформата поддържа SSH достъп до работещи контейнери за отстраняване на грешки — полезна функция при анализ на неуспешни компилации. CircleCI CLI позволява локално валидиране и изпълнение на конфигурации, управление на orbs и преглед на логове. Платформата се интегрира с GitHub, GitHub Enterprise, Bitbucket и GitLab чрез система от webhooks.

Архитектура на CircleCI: Orbs, Executors и Contexts

Архитектурата на CircleCI включва три нива: Pipeline, Workflow и Job. Pipeline — е основният процес, задействан при commit. Pipeline се състои от Workflows — граф от Jobs, които могат да се изпълняват последователно или паралелно. Всеки Job се изпълнява на Executor — среда с определен образ. Workflow може да включва approval gates — ръчно потвърждение преди внедряване.

Orbs — са многократно използваеми пакети от YAML конфигурации, разпространявани чрез CircleCI Orb Registry. Orb може да съдържа jobs, commands, executors и примери. Популярни orbs: android, ios, flutter, firebase, slack. Например, свързването на android orb заменя 50+ реда конфигурация с един ред. CircleCI CLI позволява създаване, тестване и публикуване на собствени orbs за стандартизация на пайплайни в организацията.

Типове Executors

Contexts — са именувани набори от променливи на средата, достъпни на ниво организация. Например, контекстът app-store-credentials съдържа Apple ID и парола за публикуване в App Store. Това опростява управлението на тайни между проекти без дублиране.

Настройка на CircleCI за Android и iOS проекти

За Android проект CircleCI използва Docker образ cibuilds/android с Android SDK. Типичен workflow включва: checkout, инсталиране на JDK, кеширане на Gradle, компилиране, пускане на тестове. За iOS е необходим macOS executor с Xcode и настройка на code signing. При първо свързване CircleCI автоматично определя типа на проекта и генерира базова конфигурация с препоръчителни настройки.

За Flutter проекти CircleCI предоставя orb circleci/flutter, който включва executors с предварително инсталиран Flutter SDK за Linux и macOS. Orb поддържа компилиране за двете платформи, кеширане на pub-cache и пускане на тестове. Настройката се свежда до посочване на версията на Flutter и командите за компилиране. За персонализирани версии на Flutter или Dart може да се използва Docker образ с необходимия SDK. Flutter orb също поддържа разширени опции — например, анализ на код чрез dart analyze преди компилиране.

Android orb — бърз старт

Android orb от CircleCI предоставя готови jobs: build-and-test, deploy-to-play-store. Orb автоматично конфигурира средата, кеширането и подписването. След свързване на orb е достатъчно да посочите версията на SDK и командите за компилиране.

iOS компилация с macOS executor

За iOS компилация се посочва executor: macos с версия на xcode. CircleCI предоставя образи с Xcode 14, 15 и 16. След checkout кодът се компилира чрез xcodebuild, тестовете се пускат на симулатор. Code signing се конфигурира чрез fastlane match или ръчно инсталиране на сертификати.

Кеширане и паралелно изпълнение

Кеширането — ключов елемент от производителността на CircleCI. Механизмът cache запазва директории между изпълненията на workflow въз основа на ключ. За Gradle се кешира ~/.gradle, за CocoaPods — Pods/, за npm/SPM — node_modules/.build. При промяна на lock файла cache се актуализира автоматично. CircleCI поддържа отделни политики: save_cache може да бъде отложен (when: always), а restore_cache е задължителен.

Parallelism в комбинация с resource class позволява прецизно настройване на производителността на компилиране. Resource class определя количеството CPU и RAM за контейнера: small (1 CPU, 2 GB), medium (2 CPU, 4 GB), medium+ (3 CPU, 5 GB) и large (4 CPU, 8 GB). За iOS компилации с Xcode се препоръчва използване на macOS executor с resource class medium или larger — компилирането на Swift код изисква значителни ресурси.

Parallelism разделя тестовете в няколко контейнера, намалявайки времето за изпълнение. Например: parallelism: 4 пуска тестовете в 4 паралелни контейнера. CircleCI автоматично разпределя тестовите файлове между контейнерите. Командата circleci tests glob събира списък с тестове, а circleci tests split ги разпределя равномерно.

Пример за кеширане на 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

Пример за конфигурация .circleci/config.yml

Нека разгледаме пълна конфигурация на CircleCI за Android проект с два jobs: build и test. Конфигурацията включва Docker executor с Android SDK, кеширане на Gradle и паралелно пускане на тестове. Artifacts се запазват за изтегляне. Workflow-ът build-and-test пуска и двата jobs при всяко push в основния клон.

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: готови решения за CI/CD

При избор между CircleCI и алтернативи — ако екипът използва GitHub, GitHub Actions може да бъде по-прост избор. CircleCI е за предпочитане за екипи, които се нуждаят от гъвкаво parallel test execution, персонализиране на executor среда и детайлна статистика на компилациите. CircleCI Insights предоставя табло с метрики за производителност на пайплайни: средно време за компилиране, тенденции и тесни места. Insights помага за идентифициране на jobs с дълго изпълнение и тяхното оптимизиране. CircleCI API позволява програмно управление на пайплайни, пускане на компилации и получаване на метрики.

За безопасна работа с тайни CircleCI поддържа Contexts — именувани набори от променливи на средата на ниво организация. Contexts са защитени с контрол на достъпа на база роли: само определени екипи могат да използват конкретен context. Например, context production-deploy съдържа ключове за App Store Connect и е достъпен само за водещи разработчици. В комбинация с approval gates това формира пълноценна система за сигурност на CI/CD.

CircleCI Orb Registry съдържа стотици готови пакети за различни CI/CD задачи. За мобилна разработка ключовите orbs включват: circleci/android, circleci/ios, circleci/flutter, laurencerussell/firebase-app-distribution. Всеки orb е версиониран и документиран. Orbs могат да бъдат публични (достъпни за всички) и частни (само за вашата организация).

Използването на orbs намалява конфигурацията 5–10 пъти. Например, orb circleci/android предоставя executor android/default с предварително инсталиран SDK и командите restore-gradle-cache, save-gradle-cache. Orb circleci/ios включва executor с Xcode и команди за code signing чрез fastlane. Orbs могат лесно да се комбинират: свържете android orb за компилиране и slack orb за уведомления.

CircleCI също предлага вградена поддръжка за тестови отчети. Store_test_results автоматично анализира и визуализира резултатите от тестове JUnit, XCTest и други формати. За мобилни проекти това означава централизиран преглед на неуспешни тестове, тенденции на времето за изпълнение и история на стабилността на компилациите, което опростява поддържането на качеството на кода.

Пример с 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

Публикуване на персонализиран orb е достъпно чрез CircleCI CLI. Командите circleci orb create и circleci orb publish зареждат orb в регистъра. Това е полезно за стандартизация на CI/CD в рамките на организацията — създава се веднъж, използва се във всички проекти.