CircleCI: fundamentos, orbs e integração contínua

Arquitetura do CircleCI: Orbs, Executors e Contexts

A arquitetura do CircleCI consiste em três níveis: Pipeline, Workflow e Job. Pipeline é o processo raiz acionado por um commit. Um Pipeline consiste em Workflows — um grafo de Jobs que podem ser executados sequencialmente ou em paralelo. Cada Job é executado em um Executor — um ambiente com uma imagem específica. Um Workflow pode incluir approval gates — confirmação manual antes da implantação.

Orbs são pacotes de configuração YAML reutilizáveis distribuídos através do CircleCI Orb Registry. Um Orb pode conter jobs, commands, executors e exemplos. Orbs populares: android, ios, flutter, firebase, slack. Por exemplo, adicionar o orb android substitui mais de 50 linhas de configuração por uma única linha. O CircleCI CLI permite criar, testar e publicar seus próprios orbs para padronizar pipelines em toda a organização.

Tipos de Executors

Contexts são conjuntos nomeados de variáveis de ambiente disponíveis no nível da organização. Por exemplo, o contexto app-store-credentials contém o Apple ID e senha para publicar na App Store. Isso simplifica o gerenciamento de secrets entre projetos sem duplicação.

Configuração do CircleCI para projetos Android e iOS

Para um projeto Android, o CircleCI usa a imagem Docker cibuilds/android com Android SDK. Um workflow típico inclui: checkout, instalação do JDK, cache do Gradle, build e execução de testes. Para iOS, é necessário um executor macOS com Xcode e configuração de code signing. Ao conectar pela primeira vez, o CircleCI detecta automaticamente o tipo de projeto e gera uma configuração básica com configurações recomendadas.

Para projetos Flutter, o CircleCI fornece o orb circleci/flutter, que inclui executores com Flutter SDK pré-instalado para Linux e macOS. O orb suporta build para ambas as plataformas, cache de pub-cache e execução de testes. A configuração se resume a especificar a versão do Flutter e os comandos de build. Para versões personalizadas de Flutter ou Dart, você pode usar uma imagem Docker com o SDK necessário. O orb Flutter também suporta opções avançadas — por exemplo, análise de código via dart analyze antes do build.

Orb Android — início rápido

O orb Android do CircleCI fornece jobs prontos: build-and-test, deploy-to-play-store. O orb configura automaticamente o ambiente, cache e assinatura. Após adicionar o orb, você só precisa especificar a versão do SDK e os comandos de build.

Build iOS com executor macOS

Para builds iOS, o executor é configurado como macos com uma versão do Xcode. O CircleCI fornece imagens com Xcode 14, 15 e 16. Após o checkout, o código é compilado via xcodebuild e os testes são executados no simulador. O code signing é configurado via fastlane match ou instalação manual de certificados.

Cache e execução paralela

O cache é um elemento-chave de desempenho no CircleCI. O mecanismo de cache salva diretórios entre execuções de workflow usando uma chave. Para Gradle, ~/.gradle é armazenado em cache; para CocoaPods — Pods/; para npm/SPM — node_modules/.build. Quando o arquivo lock muda, o cache é atualizado automaticamente. O CircleCI suporta políticas separadas: save_cache pode ser adiada (when: always), enquanto restore_cache é obrigatória.

O paralelismo combinado com resource class permite ajustar o desempenho do build. Resource class determina a CPU e RAM para um contêiner: small (1 CPU, 2 GB), medium (2 CPU, 4 GB), medium+ (3 CPU, 5 GB) e large (4 CPU, 8 GB). Para builds iOS com Xcode, recomenda-se usar um executor macOS com resource class medium ou larger — a compilação de código Swift requer recursos significativos.

O paralelismo divide os testes em vários contêineres, reduzindo o tempo de execução. Por exemplo: parallelism: 4 executa testes em 4 contêineres paralelos. O CircleCI distribui automaticamente os arquivos de teste entre os contêineres. O comando circleci tests glob coleta a lista de testes e o circleci tests split os distribui uniformemente.

Exemplo de cache do 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

Exemplo de configuração .circleci/config.yml

Vamos ver uma configuração completa do CircleCI para um projeto Android com dois jobs: build e test. A configuração inclui um executor Docker com Android SDK, cache do Gradle e execução paralela de testes. Os artifacts são salvos para download. O workflow build-and-test executa ambos os jobs a cada push no branch 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: soluções CI/CD prontas

Ao escolher entre CircleCI e alternativas — se sua equipe usa GitHub, o GitHub Actions pode ser uma escolha mais simples. O CircleCI é preferível para equipes que precisam de execução paralela flexível de testes, configuração personalizada do ambiente executor e estatísticas detalhadas de builds. CircleCI Insights fornece um painel com métricas de desempenho de pipelines: tempo médio de build, tendências e gargalos. O Insights ajuda a identificar jobs de longa duração e otimizá-los. A API do CircleCI permite gerenciar pipelines programaticamente, acionar builds e obter métricas.

Para gerenciamento seguro de secrets, o CircleCI suporta Contexts — conjuntos nomeados de variáveis de ambiente no nível da organização. Os Contexts são protegidos por acesso baseado em funções: apenas equipes específicas podem usar um determinado contexto. Por exemplo, o contexto production-deploy contém chaves do App Store Connect e está disponível apenas para desenvolvedores líderes. Combinado com approval gates, isso forma um sistema de segurança CI/CD abrangente.

O CircleCI Orb Registry contém centenas de pacotes prontos para várias tarefas de CI/CD. Para desenvolvimento móvel, os orbs principais incluem: circleci/android, circleci/ios, circleci/flutter, laurencerussell/firebase-app-distribution. Cada orb é versionado e documentado. Orbs podem ser públicos (disponíveis para todos) ou privados (apenas para sua organização).

Usar orbs reduz a configuração em 5–10 vezes. Por exemplo, o orb circleci/android fornece o executor android/default com SDK pré-instalado e comandos restore-gradle-cache, save-gradle-cache. O orb circleci/ios inclui um executor com Xcode e comandos para code signing via fastlane. Orbs podem ser facilmente combinados: adicione um orb android para build e um orb slack para notificações.

O CircleCI também oferece suporte integrado a relatórios de teste. Store_test_results analisa e visualiza automaticamente resultados de teste de JUnit, XCTest e outros formatos. Para projetos móveis, isso significa visualização centralizada de testes com falha, tendências de tempo de execução e histórico de estabilidade de builds, simplificando a manutenção da qualidade do código.

Exemplo com 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

Publicação de um orb personalizado está disponível através do CircleCI CLI. Os comandos circleci orb create e circleci orb publish enviam o orb para o registro. Isso é útil para padronizar CI/CD dentro de uma organização — crie uma vez, use em todos os projetos.