CircleCI: conceptos básicos, orbs e integración continua

Arquitectura de CircleCI: Orbs, Executors y Contexts

La arquitectura de CircleCI consta de tres niveles: Pipeline, Workflow y Job. Pipeline es el proceso raíz que se activa con un commit. Un Pipeline consta de Workflows, un grafo de Jobs que pueden ejecutarse secuencialmente o en paralelo. Cada Job se ejecuta en un Executor, un entorno con una imagen específica. Un Workflow puede incluir approval gates, confirmación manual antes del despliegue.

Los orbs son paquetes de configuración YAML reutilizables distribuidos a través de CircleCI Orb Registry. Un Orb puede contener jobs, commands, executors y ejemplos. Orbs populares: android, ios, flutter, firebase, slack. Por ejemplo, agregar el orb android reemplaza más de 50 líneas de configuración por una sola línea. CircleCI CLI permite crear, probar y publicar orbs propios para estandarizar pipelines en toda la organización.

Tipos de Executors

Los Contexts son conjuntos nombrados de variables de entorno disponibles a nivel de organización. Por ejemplo, el contexto app-store-credentials contiene el Apple ID y la contraseña para publicar en App Store. Esto simplifica la gestión de secrets entre proyectos sin duplicación.

Configuración de CircleCI para proyectos Android e iOS

Para un proyecto Android, CircleCI utiliza la imagen Docker cibuilds/android con Android SDK. Un workflow típico incluye: checkout, instalación de JDK, almacenamiento en caché de Gradle, compilación y ejecución de pruebas. Para iOS, se requiere un executor macOS con Xcode y configuración de code signing. Al conectarse por primera vez, CircleCI detecta automáticamente el tipo de proyecto y genera una configuración básica con ajustes recomendados.

Para proyectos Flutter, CircleCI proporciona el orb circleci/flutter, que incluye ejecutores con Flutter SDK preinstalado para Linux y macOS. El orb admite compilación para ambas plataformas, almacenamiento en caché de pub-cache y ejecución de pruebas. La configuración se reduce a especificar la versión de Flutter y los comandos de compilación. Para versiones personalizadas de Flutter o Dart, se puede usar una imagen Docker con el SDK necesario. El orb Flutter también admite opciones avanzadas, como análisis de código mediante dart analyze antes de compilar.

Orb Android — inicio rápido

El orb Android de CircleCI proporciona jobs prediseñados: build-and-test, deploy-to-play-store. El orb configura automáticamente el entorno, el almacenamiento en caché y la firma. Después de agregar el orb, solo necesita especificar la versión del SDK y los comandos de compilación.

Compilación iOS con executor macOS

Para compilaciones iOS, el executor se configura como macos con una versión de Xcode. CircleCI proporciona imágenes con Xcode 14, 15 y 16. Después del checkout, el código se compila mediante xcodebuild y las pruebas se ejecutan en el simulador. El code signing se configura mediante fastlane match o instalación manual de certificados.

Almacenamiento en caché y ejecución paralela

El almacenamiento en caché es un elemento clave del rendimiento en CircleCI. El mecanismo de cache guarda directorios entre ejecuciones de workflow mediante una clave. Para Gradle, se almacena en caché ~/.gradle; para CocoaPods — Pods/; para npm/SPM — node_modules/.build. Cuando el archivo lock cambia, la caché se actualiza automáticamente. CircleCI admite políticas separadas: save_cache puede ser diferida (when: always), mientras que restore_cache es obligatoria.

El paralelismo combinado con resource class permite ajustar el rendimiento de la compilación. Resource class determina la CPU y RAM para un contenedor: small (1 CPU, 2 GB), medium (2 CPU, 4 GB), medium+ (3 CPU, 5 GB) y large (4 CPU, 8 GB). Para compilaciones iOS con Xcode, se recomienda usar un executor macOS con resource class medium o larger, ya que la compilación de código Swift requiere recursos significativos.

El paralelismo divide las pruebas en múltiples contenedores, reduciendo el tiempo de ejecución. Por ejemplo: parallelism: 4 ejecuta pruebas en 4 contenedores paralelos. CircleCI distribuye automáticamente los archivos de prueba entre los contenedores. El comando circleci tests glob recopila la lista de pruebas, y circleci tests split las distribuye uniformemente.

Ejemplo de almacenamiento en caché de 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

Ejemplo de configuración .circleci/config.yml

Veamos una configuración completa de CircleCI para un proyecto Android con dos jobs: build y test. La configuración incluye un executor Docker con Android SDK, almacenamiento en caché de Gradle y ejecución paralela de pruebas. Los artifacts se guardan para su descarga. El workflow build-and-test ejecuta ambos jobs en cada push a la rama principal.

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: soluciones CI/CD prediseñadas

Al elegir entre CircleCI y alternativas — si su equipo usa GitHub, GitHub Actions puede ser una opción más sencilla. CircleCI es preferible para equipos que necesitan ejecución paralela flexible de pruebas, configuración personalizada del entorno executor y estadísticas detalladas de compilaciones. CircleCI Insights proporciona un panel con métricas de rendimiento de pipelines: tiempo promedio de compilación, tendencias y cuellos de botella. Insights ayuda a identificar jobs de larga duración y optimizarlos. CircleCI API permite gestionar pipelines mediante programación, ejecutar compilaciones y obtener métricas.

Para la gestión segura de secrets, CircleCI admite Contexts — conjuntos nombrados de variables de entorno a nivel de organización. Los Contexts están protegidos mediante acceso basado en roles: solo equipos específicos pueden usar un contexto determinado. Por ejemplo, el contexto production-deploy contiene claves de App Store Connect y solo está disponible para desarrolladores principales. Combinado con approval gates, esto forma un sistema de seguridad CI/CD completo.

CircleCI Orb Registry contiene cientos de paquetes prediseñados para diversas tareas de CI/CD. Para desarrollo móvil, los orbs clave incluyen: circleci/android, circleci/ios, circleci/flutter, laurencerussell/firebase-app-distribution. Cada orb tiene versión y documentación. Los orbs pueden ser públicos (disponibles para todos) o privados (solo para su organización).

El uso de orbs reduce la configuración de 5 a 10 veces. Por ejemplo, el orb circleci/android proporciona el executor android/default con SDK preinstalado y comandos restore-gradle-cache, save-gradle-cache. El orb circleci/ios incluye un executor con Xcode y comandos para code signing mediante fastlane. Los orbs se pueden combinar fácilmente: agregue un orb android para compilación y un orb slack para notificaciones.

CircleCI también ofrece soporte integrado para informes de pruebas. Store_test_results analiza y visualiza automáticamente los resultados de pruebas en formatos JUnit, XCTest y otros. Para proyectos móviles, esto significa visualización centralizada de pruebas fallidas, tendencias de tiempo de ejecución e historial de estabilidad de compilaciones, simplificando el mantenimiento de la calidad del código.

Ejemplo con 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

Publicación de un orb personalizado está disponible mediante CircleCI CLI. Los comandos circleci orb create y circleci orb publish suben el orb al registro. Esto es útil para estandarizar CI/CD dentro de una organización — crear una vez, usar en todos los proyectos.