🐦Codemagic Yaml + SHOREBIRD

Documentação do Codemagic.yaml para Workflows Flutter

Introdução

Este documento descreve a estrutura do arquivo codemagic.yaml para configurar workflows de build e publicação de aplicativos Flutter no Codemagic CI/CD. O YAML fornecido abrange dois workflows: um para construir e publicar no Android e outro para construir e publicar no iOS.

Estrutura do Arquivo

O arquivo codemagic.yaml possui a seguinte estrutura geral:

workflows:
  android-workflow:
      name: Android Workflow
      instance_type: mac_mini_m1
      environment:
        groups:
          - env  # Expõe as variáveis definidas do grupo env no codemagic
        android_signing:
          - keystore-token  # Adicione a referência para a keystore do app no codemagic
        flutter: 3.19.5  # Versão do flutter para rodar a build
      scripts:
        - name: Set up local.properties
          script: |
            echo "flutter.sdk=$HOME/programs/flutter" > "$CM_BUILD_DIR/android/local.properties"
        - name: Pre-build script  # Passo de configuração pre build, onde os envs serão atribuídos e as dependências serão obtidas
          script: |
            echo $ENV | base64 --decode > .env.staging &&
            echo $ENV | base64 --decode > .env.production &&
            flutter clean &&
            flutter pub get
        - name: Build Release  # Comando para gerar o .aab do app
          script: |
            flutter build appbundle --release --flavor staging
      artifacts: # Define quais artefatos serão expostos após o final da build
        - build/**/outputs/**/*.aab
        - build/**/outputs/**/*.apk
        - build/**/outputs/**/mapping.txt
        - flutter_drive.log
      publishing:
        email: # Define quais email receberão notificações do sucesso ou falha da build
          recipients:
            - [e-mail]
          notify:
            success: true  # Define se deve notificar no sucesso da build
            failure: false  # Define se deve notificar na falha da build

    
    ios-workflow:
      name: iOS Workflow
      instance_type: mac_mini_m1
      integrations:
        app_store_connect: Reference  # Adiciona a referência para a API key do projeto do Apple Developer Portal
      environment:
        groups:
          - env  # Expõe as variáveis definidas do grupo env no codemagic
        ios_signing:
          distribution_type: app_store  # Define o tipo de distribuição do app
          bundle_identifier: br.com.loomi.example  # Bundle ID do app
        flutter: 3.19.5  # Versão do flutter para rodar a build
        xcode: latest  # Versão do xcode para rodar a build
        cocoapods: default  # Versão dos cocoapods
      scripts:
        - name: Set up code signing settings on Xcode project
          script: |
            xcode-project use-profiles
        - name: Pre-build script  # Passo de configuração pre build, onde os envs serão atribuídos e as dependências serão obtidas
          script: |
            echo $ENV | base64 --decode > .env.staging &&
            echo $ENV | base64 --decode > .env.production &&
            flutter clean &&
            flutter pub upgrade &&
            flutter pub get && cd ios &&
            flutter precache --ios &&
            pod update && pod install --repo-update
        - name: Build Release  # Comando para gerar o .ipa do app
          script: |
            flutter build ipa --release --flavor staging --export-options-plist=/Users/builder/export_options.plist
      artifacts:
        - build/ios/ipa/*.ipa
        - tmp/xcodebuild_logs/*.log
        - flutter_drive.log
      publishing:
        email: # Define quais email receberão notificações do sucesso ou falha da build
          recipients:
            - [e-mail]
          notify:
            success: true  # Define se deve notificar no sucesso da build
            failure: false  # Define se deve notificar na falha da build
        app_store_connect:
          auth: integration
          # Configuração relacionada ao TestFlight (opcional)
          # Obs: Essa ação é executada durante o pós processamento.
          submit_to_testflight: true  # Define se o app deve ser publicado no TestFlight

          # Configuração relacionada à AppStore (opcional)
          # Obs: Essa ação é executada durante o pós processamento.
          submit_to_app_store: false  # Define se o app deve ser submetido para revisão na AppStore

Android Workflow

Nome: Android Workflow

• instance_type: Tipo da instância de build (no exemplo: mac_mini_m1).

• environment:

  • groups: Grupos de variáveis do ambiente expostas para o Codemagic. Para definir essas variáveis você pode ir até as configurações de build do app > Environment variables no Codemagic. (CODEMAGIC_ENV_VAR)

  • android_signing: Configurações de assinatura para o Android.

    • Adicione a keystore do app em Teams > Personal Account > Code Signing Identities > Android keystores. O nome definido para a chave nesse passo será a referência a ser utilizada no yaml. (CODEMAGIC_KEYSTORE)

    • No build.gradle do app, em signingConfigs, adicione as informações da chave que serão utilizadas no processo de CI.

      if (System.getenv()["CI"]) { // CI=true is exported by Codemagic
      	storeFile file(System.getenv()["CM_KEYSTORE_PATH"])
      	storePassword System.getenv()["CM_KEYSTORE_PASSWORD"]
      	keyAlias System.getenv()["CM_KEY_ALIAS"]
      	keyPassword System.getenv()["CM_KEY_PASSWORD"]
      } else {
      	keyAlias keystoreProperties['keyAlias']
      	keyPassword keystoreProperties['keyPassword']
      	storeFile keystoreProperties['storeFile'] ? file(keystoreProperties['storeFile']) : null
      	storePassword keystoreProperties['storePassword']
      }

  • flutter: Versão do Flutter para executar a build.

• scripts:

  • Set up local.properties: Configuração do arquivo local.properties.

  • Pre-build script: Configurações pré-build, decodificação de variáveis de ambiente e obtenção de dependências.

  • Build Release: Comando para gerar o arquivo .aab do aplicativo.

• artifacts: Artefatos a serem expostos após a conclusão da build.

• publishing: Configurações para notificação por e-mail.

iOS Workflow

Nome: iOS Dev

• instance_type: Tipo da instância de build (no exemplo: mac_mini_m1).

• integrations: Configurações específicas da integração, como a chave da API do Apple Developer Portal.

  • A chave pode ser adicionada em Teams > Personal Account > Integrations > Manage keys (Developer Portal) > Add another key. O nome definido para a chave nesse passo será a referência a ser utilizada no yaml. (CODEMAGIC_ADP_API_KEY)

  • Após a adição da chave, para que o app seja publicado no TestFlight é necessário adicionar também os iOS certificates e iOS provisioning profiles no codemagic. Acesse Teams > Personal Account > Code signing identities, e faça um fetch do certificado e dos profiles a partir da chave adicionada. (CODEMAGIC_CERT) (CODEMAGIC_PROV_PROF)

• environment:

  • groups: Grupos de variáveis do ambiente expostas para o Codemagic.

  • ios_signing: Configurações de assinatura para o iOS.

  • flutter: Versão do Flutter para executar a build.

  • xcode: Versão do Xcode para executar a build.

  • cocoapods: Versão do CocoaPods para executar a build.

• scripts:

  • Set up code signing settings on Xcode project: Configurações de assinatura no projeto Xcode.

  • Pre-build script: Configurações pré-build, decodificação de variáveis de ambiente e obtenção de dependências.

  • Build Release: Comando para gerar o arquivo .ipa do aplicativo.

• artifacts: Artefatos a serem expostos após a conclusão da build.

• publishing: Configurações para notificação por e-mail e publicação no App Store Connect.

Integração ao Code Push Shorebird

A documentação fornecida pelo Shorebird já é suficientemente robusta para configurar a integração contínua do serviço. No entanto, existem algumas observações a serem notadas no passo a passo desse processo.

Em versões mais recentes do shorebird, durante a build do iOS pode ocorrer o seguinte erro:

  
Exception: Export options plist /Users/builder/export_options.plist does not set manageAppVersionAndBuildNumber to false. This is required for shorebird to work.

  

  

Build failed :|

Step 7 script `🚀 Shorebird Release` exited with status code 64

Para resolvê-lo, basta modificar o passo Set up code signing settings on Xcode project para que fique da seguinte maneira:

- name: Set up code signing settings on Xcode project
	script: |
		xcode-project use-profiles
		/usr/libexec/PlistBuddy -c 'Add :manageAppVersionAndBuildNumber bool false' /Users/builder/export_options.plist

É importante notar também que o Shorebird não usa a versão do flutter definida no codemagic.yaml para gerar a build do app. Para definir uma versão específica para executar a build adicione --flutter-version <VERSÃO> ao comando shorebird release. As versões suportadas podem ser encontradas aqui.

> Para o Android, é necessário o Flutter 3.10.0 ou posterior.
> Para o iOS, é necessário o Flutter 3.19.5 ou posterior.

Abaixo segue um exemplo de codemagic.yaml com a adição do Shorebird aos workflows.

workflows:
  android-workflow:
    name: Android Workflow
    instance_type: mac_mini_m1
    environment:
      groups:
        - shorebird # Expõe o SHOREBIRD_TOKEN
        - env  # Expõe as variáveis definidas do grupo env no codemagic
      android_signing:
        - keystore-token  # Adicione a referência para a keystore do app no codemagic
      flutter: 3.19.5  # Versão do flutter para rodar a build
    scripts:
      - name: Set up local.properties
        script: |
          echo "flutter.sdk=$HOME/programs/flutter" > "$CM_BUILD_DIR/android/local.properties"
      - name: Pre-build script  # Passo de configuração pre build, onde os envs serão atribuídos e as dependências serão obtidas
        script: |
          echo $ENV | base64 --decode > .env.staging &&
          echo $ENV | base64 --decode > .env.production &&
          flutter clean &&
          flutter pub get
      - name: 🐦 Setup Shorebird # Instalação do Shorebird
        script: |
          # Install Shorebird
          curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash
          # Add Shorebird to PATH
          echo PATH="$HOME/.shorebird/bin:$PATH" >> $CM_ENV
      - name: 🚀 Shorebird Release  # Comando para gerar o .aab do app
        script: |
          shorebird release android --flavor staging --flutter-version 3.16.9
    artifacts: # Define quais artefatos serão expostos após o final da build
      - build/**/outputs/**/*.aab
      - build/**/outputs/**/*.apk
      - build/**/outputs/**/mapping.txt
      - flutter_drive.log
    publishing:
      email: # Define quais email receberão notificações do sucesso ou falha da build
        recipients:
          - [e-mail]
        notify:
          success: true  # Define se deve notificar no sucesso da build
          failure: false  # Define se deve notificar na falha da build

  
  ios-workflow:
    name: iOS Workflow
    instance_type: mac_mini_m1
    integrations:
      app_store_connect: Reference  # Adiciona a referência para a API key do projeto do Apple Developer Portal
    environment:
      groups:
        - shorebird # Expõe o SHOREBIRD_TOKEN
        - env  # Expõe as variáveis definidas do grupo env no codemagic
      ios_signing:
        distribution_type: app_store  # Define o tipo de distribuição do app
        bundle_identifier: br.com.loomi.example  # Bundle ID do app
      flutter: 3.19.5  # Versão do flutter para rodar a build
      xcode: latest  # Versão do xcode para rodar a build
      cocoapods: default  # Versão dos cocoapods
    scripts:
      - name: Set up code signing settings on Xcode project
        script: |
          xcode-project use-profiles
          /usr/libexec/PlistBuddy -c 'Add :manageAppVersionAndBuildNumber bool false' /Users/builder/export_options.plist
      - name: Pre-build script  # Passo de configuração pre build, onde os envs serão atribuídos e as dependências serão obtidas
        script: |
          echo $ENV | base64 --decode > .env.staging &&
          echo $ENV | base64 --decode > .env.production &&
          flutter clean &&
          flutter pub upgrade &&
          flutter pub get && cd ios &&
          flutter precache --ios &&
          pod update && pod install --repo-update
      - name: 🐦 Setup Shorebird # Instalação do Shorebird
        script: |
          # Install Shorebird
          curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash
          # Add Shorebird to PATH
          echo PATH="$HOME/.shorebird/bin:$PATH" >> $CM_ENV
      - name: 🚀 Shorebird Release  # Comando para gerar o .ipa do app
        script: |
          shorebird release ios --flavor staging --export-options-plist=/Users/builder/export_options.plist --flutter-version 3.16.9
    artifacts:
      - build/ios/ipa/*.ipa
      - tmp/xcodebuild_logs/*.log
      - flutter_drive.log
    publishing:
      email: # Define quais email receberão notificações do sucesso ou falha da build
        recipients:
          - [e-mail]
        notify:
          success: true  # Define se deve notificar no sucesso da build
          failure: false  # Define se deve notificar na falha da build
      app_store_connect:
        auth: integration
        # Configuração relacionada ao TestFlight (opcional)
        # Obs: Essa ação é executada durante o pós processamento.
        submit_to_testflight: true  # Define se o app deve ser publicado no TestFlight

        # Configuração relacionada à AppStore (opcional)
        # Obs: Essa ação é executada durante o pós processamento.
        submit_to_app_store: false  # Define se o app deve ser submetido para revisão na AppStore

Conclusão

Este é um exemplo básico do arquivo codemagic.yaml para workflows Flutter no Codemagic. Certifique-se de adaptar as configurações de acordo com as necessidades específicas do seu projeto e dos ambientes de build.