CircleCI: Basics, Orbs and Continuous Integration

CircleCI Architecture: Orbs, Executors and Contexts

CircleCI architecture consists of three levels: Pipeline, Workflow, and Job. Pipeline is the root process triggered on commit. A Pipeline consists of Workflows — a graph of Jobs that can run sequentially or in parallel. Each Job runs on an Executor — an environment with a specific image. A Workflow can include approval gates — manual confirmation before deployment.

Orbs are reusable YAML configuration packages distributed through the CircleCI Orb Registry. An Orb can contain jobs, commands, executors, and examples. Popular orbs: android, ios, flutter, firebase, slack. For example, adding the android orb replaces 50+ lines of configuration with a single line. CircleCI CLI allows you to create, test, and publish your own orbs to standardize pipelines across your organization.

Executor Types

Contexts are named sets of environment variables available at the organization level. For example, the app-store-credentials context contains the Apple ID and password for publishing to the App Store. This simplifies managing secrets across projects without duplication.

Setting Up CircleCI for Android and iOS Projects

For an Android project, CircleCI uses the cibuilds/android Docker image with Android SDK. A typical workflow includes: checkout, JDK installation, Gradle caching, build, and test execution. For iOS, a macOS executor with Xcode and code signing setup is required. When first connected, CircleCI automatically detects the project type and generates a basic configuration with recommended settings.

For Flutter projects, CircleCI provides the circleci/flutter orb, which includes executors with pre-installed Flutter SDK for Linux and macOS. The orb supports building for both platforms, caching pub-cache, and running tests. Setup comes down to specifying the Flutter version and build commands. For custom Flutter or Dart versions, you can use a Docker image with the required SDK. The Flutter orb also supports advanced options — for example, code analysis via dart analyze before building.

Android Orb — Quick Start

The Android orb from CircleCI provides ready-made jobs: build-and-test, deploy-to-play-store. The orb automatically configures the environment, caching, and signing. After adding the orb, you just need to specify the SDK version and build commands.

iOS Build with macOS Executor

For iOS builds, the executor is set to macos with an Xcode version. CircleCI provides images with Xcode 14, 15, and 16. After checkout, the code is compiled via xcodebuild, and tests run on the simulator. Code signing is configured via fastlane match or manual certificate installation.

Caching and Parallel Execution

Caching is a key performance element in CircleCI. The cache mechanism saves directories between workflow runs using a key. For Gradle, ~/.gradle is cached; for CocoaPods — Pods/; for npm/SPM — node_modules/.build. When the lock file changes, the cache is automatically updated. CircleCI supports separate policies: save_cache can be deferred (when: always), while restore_cache is mandatory.

Parallelism combined with resource class allows fine-tuning build performance. Resource class determines the CPU and RAM for a container: small (1 CPU, 2 GB), medium (2 CPU, 4 GB), medium+ (3 CPU, 5 GB), and large (4 CPU, 8 GB). For iOS builds with Xcode, it is recommended to use a macOS executor with medium or larger resource class — Swift code compilation requires significant resources.

Parallelism splits tests across multiple containers, reducing run time. For example: parallelism: 4 runs tests in 4 parallel containers. CircleCI automatically distributes test files across containers. The circleci tests glob command collects the test list, and circleci tests split distributes them evenly.

Gradle Caching Example

- 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

Example .circleci/config.yml Configuration

Let’s look at a full CircleCI configuration for an Android project with two jobs: build and test. The configuration includes a Docker executor with Android SDK, Gradle caching, and parallel test execution. Artifacts are saved for download. The build-and-test workflow runs both jobs on every push to the main branch.

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: Ready-made CI/CD Solutions

When choosing between CircleCI and alternatives — if your team uses GitHub, GitHub Actions might be a simpler choice. CircleCI is preferable for teams that need flexible parallel test execution, custom executor environment configuration, and detailed build statistics. CircleCI Insights provides a dashboard with pipeline performance metrics: average build time, trends, and bottlenecks. Insights helps identify long-running jobs and optimize them. CircleCI API allows you to programmatically manage pipelines, trigger builds, and retrieve metrics.

For secure secrets management, CircleCI supports Contexts — named sets of environment variables at the organization level. Contexts are protected by role-based access: only specific teams can use a particular context. For example, the production-deploy context contains App Store Connect keys and is accessible only to lead developers. Combined with approval gates, this forms a comprehensive CI/CD security system.

The CircleCI Orb Registry contains hundreds of ready-made packages for various CI/CD tasks. For mobile development, key orbs include: circleci/android, circleci/ios, circleci/flutter, laurencerussell/firebase-app-distribution. Each orb is versioned and documented. Orbs can be public (available to everyone) or private (for your organization only).

Using orbs reduces configuration by 5–10 times. For example, the circleci/android orb provides the android/default executor with pre-installed SDK and restore-gradle-cache, save-gradle-cache commands. The circleci/ios orb includes an executor with Xcode and commands for code signing via fastlane. Orbs can be easily combined: add an android orb for building and a slack orb for notifications.

CircleCI also offers built-in test report support. Store_test_results automatically parses and visualizes test results from JUnit, XCTest, and other formats. For mobile projects, this means centralized viewing of failed tests, runtime trends, and build stability history, simplifying code quality maintenance.

Example with 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

Publishing a custom orb is available through CircleCI CLI. The circleci orb create and circleci orb publish commands upload the orb to the registry. This is useful for standardizing CI/CD within an organization — create once, use across all projects.