ZERO TO STORES GUIDE

Set Up App Distribution

Tutorial Video

Video recording in progress. Available soon.

Now that your project is initialized, it's time to set up your distribution pipeline.

Codika automates the integration with Codemagic to handle building, testing, signing, and deploying your Flutter app to both the App Store and Google Play. Most of the setup is fully automated — from linking your GitHub repository to generating signing credentials and preparing the deployment workflows.

You'll walk through a few simple CLI commands to set up everything. When manual steps are needed (like registering the app in App Store Connect), we’ll clearly call them out along the way.

Before You Start

Before proceeding, ensure you've completed the previous sections of this guide, and you're authenticated with the required services: gh, gcloud, firebase, and that you have an Apple Developer Account configured in Codika.

1. Codemagic Integration

Codika automates the setup of your Codemagic pipeline, so you can build, test, and deploy your Flutter app with every push to GitHub. Running a single command will:

• Create a Codemagic app linked to your GitHub repo
• Set up an SSH key pair for secure access
• Configure GitHub webhooks to trigger builds
• Upload secret files and environment variables
• Save the Codemagic App ID to your local codika.yaml

Codemagic Setup

Open your terminal and navigate to your Codika project directory. Execute:

codika app config codemagic

The Codika CLI will guide you through the following interactive steps clearly:

✔ Detected GitHub repository linked to your project: softwhale/my-awesome-app
✔ Checking Codemagic integration status...
→ Codemagic integration not detected yet.

? Select your Codemagic Team or create a new one:
❯ ◉  Your Team (Default)
  ◯  Personal Account
  ◯  Create new team

Choose the Codemagic team you want to associate your project with, typically your organization's default team. After your selection, Codika will perform several automated actions with detailed outputs:

✔ Creating your Codemagic application...
✔ Codemagic app successfully created.

✔ Generating SSH keys for secure repository access...
→ Public key registered with Codemagic.
→ Private key securely uploaded to GitHub repository.

✔ Configuring GitHub webhook...
→ Webhook successfully set to trigger Codemagic builds on every push.

✔ Setting environment variables and secret files in Codemagic...
→ Android signing key configured.
→ iOS distribution certificate configured.
→ Google service account credentials uploaded.

✔ Updating your local configuration...
→ Codemagic App ID added to codika.yaml file automatically.

🎉 Codemagic integration successfully completed!

What Exactly Happened?

Let's briefly break down what Codika automated for you in detail:

• Codemagic App Creation

  Codika automatically created a Codemagic project connected to your GitHub repository, ensuring Codemagic can monitor your repo's activity and execute builds when code is pushed.

• SSH Key Generation

  Codika securely generated a unique SSH key pair, ensuring Codemagic can securely clone your private repository.

• SSH Key Registration

  The public key was securely registered in Codemagic, granting access to your repository. The private key was securely stored in GitHub secrets, never leaving your project's secure storage.

• Webhook Configuration

  A webhook was automatically added to your GitHub repository, enabling Codemagic to detect pushes and trigger automatic builds.

• Environment Variables & Secrets

  Essential files like Android signing keys, iOS distribution certificates, and Google service account JSON keys were securely transferred to Codemagic, simplifying the deployment and signing processes.

• Configuration Updates

  The Codemagic App ID was added automatically to your local codika.yaml, ensuring consistency across future CLI interactions and configurations.

Manual Setup

If automatic integration with Codemagic fails, follow these detailed steps to manually configure your Codemagic setup:

Step 1: Create your Codemagic Application

1. Go to Codemagic and log into your account.
2. Click "Add Application" in the Apps tab.
3. Select your team (created during the Configuration Guide) or use your personal account.
4. Connect your repository and choose Flutter workflow.
5. Once the workflow is created, switch to YAML configuration.

Step 2: Configure GitHub Webhook

1. In Codemagic, navigate to your app settings and copy the Webhook URL.
2. Go to your GitHub repository settings → Webhooks.
3. Click Add webhook, paste the URL in the Payload URL field, set the content type to application/json, choose events "Just the push event", and save.

Step 3: Update your codika.yaml

Retrieve your Codemagic App ID from the webhook URL (the numeric value at the end):

https://api.codemagic.io/hooks/<CODEMAGIC_APP_ID>

Provide the Codemagic App ID to Codika:

codika app config codemagic --codemagic-app-id <CODEMAGIC_APP_ID>

Your Codemagic configuration is now manually complete!

2. iOS Setup

In this step, Codika generates unique iOS Bundle IDs for your Production (prod) and Staging (stag) environments. These Bundle IDs are essential to uniquely identify your app within the Apple ecosystem, ensuring that each environment has its own distinct identity, allowing you to run multiple app versions on the same device without conflict.

Codika automatically generates and configures these Bundle IDs using your previously registered Apple Developer Account.

Executing Bundle ID Setup

Run this command within your Codika project directory:

codika app config bundle-id

Codika prompts you to select your Apple Developer Team:

? Select an Apple Developer Team for Bundle ID creation:
❯ ◉ SoftWhale Apps Ltd. (ABCDE12345)
  ◯ Another Team (XYZ67890)

Codika then performs the automatic creation:

✔ Creating Bundle IDs...

→ Created Bundle IDs:
  - Production: com.softwhale.my-awesome-app.prod
  - Staging: com.softwhale.my-awesome-app.stag

🎉 Bundle ID creation completed successfully!

What Exactly Happened?

Codika created explicit Bundle IDs for your app’s Production and Staging environments using your configured organization identifier (com.softwhale) and project name (my-awesome-app). These identifiers were automatically added to your local codika.yaml file for consistency and future reference.

Manual Setup

1. Visit the Apple Developer Portal.
2. Navigate to Certificates, Identifiers & Profiles → Identifiers.
3. Click "+" to add a new App ID:
   • Choose App IDs → Continue.
   • Select Explicit type.
   • Enter Bundle IDs clearly:
     • com.softwhale.my-awesome-app.prod (Production)
     • com.softwhale.my-awesome-app.stag (Staging)
   • Click Continue, then Register.
4. Manually update your codika.yaml with these IDs:

params:
  app_id_ios:
    prod: com.softwhale.my-awesome-app.prod
    stag: com.softwhale.my-awesome-app.stag

Then continue with the provisioning profile setup explained below.

Now that your Bundle IDs are created, you must manually register them in App Store Connect and create provisioning profiles.

Register Bundle IDs in App Store Connect

1. Log into your App Store Connect account.
2. Navigate to My Apps → + → New App.
3. Provide the details clearly, selecting the corresponding Bundle ID (com.softwhale.my-awesome-app.prod and com.softwhale.my-awesome-app.stag) from the dropdown.
4. Complete registration for both environments.

Create Provisioning Profiles and Upload to Codemagic

Provisioning profiles link your newly created Bundle IDs with your distribution certificate. This step must be performed manually. Let us start by creating the profiles in the Apple Developer Portal.

• Log in to the Apple Developer Portal.
• Go to Profiles → "+" → App Store under Distribution.
• Select your newly created Bundle IDs from the dropdown.
• Select your distribution certificate (created previously).
• Clearly name profiles:
  • Distribution Profile Production (MyAwesomeApp)
  • Distribution Profile Staging (MyAwesomeApp)
• Click Generate, then download the .mobileprovision files.

Next, register these provisioning profiles inside Codemagic:

• Open your Codemagic Dashboard.
• Select your app → Settings → Signing identities → iOS Provisioning Profiles.
• Click "Upload profile", upload each downloaded profile, ensuring they're correctly matched to their environments.

3. Android Setup

In this step, Codika automates the setup of a Google Service Account (GSA). This account securely enables Codemagic to deploy your Flutter app directly to the Google Play Store. Automating this typically complex and error-prone process helps ensure consistency and reduces the possibility of misconfigurations.

When executed, Codika performs the following actions automatically:

• Creates a dedicated Google Service Account for your app deployment.
• Assigns the necessary permissions required for publishing your app to Google Play.
• Securely downloads the service account credentials as a JSON file to your project.
• Clearly provides the service account email for you to invite it into your Google Play Console.

Executing Google Service Account Setup

Run the following command in your Codika project directory:

codika app config google-service-account

Codika first checks if your Google Cloud Project (configured during codika create) permits automatic creation of service accounts:

✔ Checking Google Cloud permissions...
→ Permission check passed!

✔ Creating Google Service Account...
✔ Assigning roles and permissions...
✔ Generating JSON key file...

🎉 Google Service Account setup complete!

Service Account Email:
your-app-deployer@my-awesome-app.iam.gserviceaccount.com

Next steps:
1. Invite this service account email to your Google Play Console.
2. Grant admin-level permissions to allow app publishing.

What Exactly Happened?

Codika performed these actions automatically behind the scenes:

• Service Account Creation: Generated a dedicated Google Service Account in your Google Cloud Project (my-awesome-app) for your application deployment tasks.
• Permission Assignment: Automatically assigned the appropriate IAM roles (Service Account User) to the service account, ensuring it has the necessary privileges to interact with Google Play services.
• Credential Management: Securely downloaded the generated JSON key file (google-service-account.json) directly into your project's root directory for use by Codemagic during deployment.
• Configuration Updates: Clearly displayed the email address of the created service account, simplifying your next steps in the Google Play Console.

Grant Permissions in Google Play Console

After Codika creates the Google Service Account, you must manually invite it to your Google Play Console and grant it necessary permissions to publish your app.

Follow these steps clearly:

• Visit Google Play Console and log in.
• Navigate to Users and permissions → Invite new user.
• Paste the service account email provided by Codika:
  • e.g., your-app-deployer@my-awesome-app.iam.gserviceaccount.com
• Set the permissions explicitly:
  • Select the specific app(s) the service account should manage or select All apps if managing multiple.
  • Grant the service account the Admin role to ensure it can fully manage publishing workflows.
• Click Send invitation.

Your Google Service Account is now fully configured and authorized to automate app publishing via Codemagic.

GCP Organization Permissions Requirement

For Codika to automatically create Google Service Accounts, your Google Cloud Project must permit account creation. By default, some organizations restrict this action for security reasons.

If automatic creation fails due to permissions, you'll need to either:

• Request elevated permissions from your GCP administrator.
• Follow the manual fallback steps below.

Codika performs a permissions check at execution and clearly informs you of your GCP project's status.

Manual Google Service Account Creation

If automation fails due to permission issues or other factors, here's the detailed manual fallback clearly explained:

Manual Google Service Account Creation (Fallback)

Follow these detailed steps to create and configure the Google Service Account manually:

Step 1: Create the Service Account

• Visit Google Cloud Console and select your project.
• Enable required APIs (if not already enabled):
  • Google Play Developer Reporting API
  • Google Play Android Developer API
• Navigate to APIs & Services → Credentials.
• Click Create credentials → Service account.
• Enter clear details:
  • Service account name: e.g., your-app-deployer
  • Service account ID auto-generated or explicitly set: your-app-deployer
• Click Create.

Step 2: Assign Permissions to the Service Account

• After creation, select your service account.
• Navigate to the Permissions tab.
• Click Grant Access, then:
  • Add the service account email in the New Principals field.
  • Assign the role: Service Account User.
• Click Save.

Step 3: Generate and Download JSON Key

• Go to IAM & Admin → Service Accounts.
• Find your service account, then click Actions → Manage keys.
• Click Add key → Create new key and select JSON.
• Download and securely store the key file as google-service-account.json in your project's root directory.

Step 4: Invite Service Account to Google Play Console

• Log into Google Play Console.
• Navigate to Users and permissions → Invite new user.
• Paste your service account email.
• Assign permissions clearly (preferably Admin permissions).
• Click Send invitation.

Your manual setup is now complete and your Google Service Account is ready for Codemagic deployments.

4. Generate Codemagic YAML Workflow

In this final configuration step, Codika generates your codemagic.yaml workflow file. This file is essential for Codemagic to understand how to build, sign, and deploy your Flutter app automatically. Codika creates this workflow file based on the configurations previously set during the Codemagic integration, iOS Bundle ID setup, and Google Service Account setup.

When executed, Codika ensures:

• All previous configurations (Codemagic App ID, iOS Bundle IDs, and Google Service Account credentials) are correctly configured.
• The generated codemagic.yaml reflects these values accurately, preparing your app for seamless automated builds and deployment processes.

Executing Workflow Generation

Run the following command in your Codika project directory:

codika app config ci-cd-workflows

Codika will first validate your configurations and then generate the workflow file:

✔ Verifying configurations...
→ Codemagic App ID detected: [123456789]
→ Bundle IDs detected:
    - prod: com.softwhale.my-awesome-app.prod
    - stag: com.softwhale.my-awesome-app.stag
→ Google Service Account credentials found: google-service-account.json

✔ Generating codemagic.yaml workflow file...
✔ Workflow file successfully created at ./codemagic.yaml

🎉 Codemagic YAML workflow setup complete!

What Exactly Happened?

Here's precisely what Codika automated for you in this step:

• Configuration Validation: Codika verified the existence and correctness of crucial configurations from previous steps, including your Codemagic App ID, Bundle IDs, provisioning profiles, and Google Service Account credentials.
• Workflow File Generation: It then generated the codemagic.yaml file, incorporating your specific project settings, including signing configurations, build steps, and environment-specific deployment settings.
• File Placement: The resulting codemagic.yaml file is placed directly in your project's root directory, clearly ready for Codemagic integration.

Your generated workflow file typically includes:

• Flutter version configuration
• Environment variables setup
• Platform-specific build instructions (Android and iOS)
• Steps for uploading and distributing your app to the respective app stores automatically

What's Next?

Congratulations! With this step complete, your automated distribution pipeline setup is fully configured and ready to use. You've successfully:

• Set up Codemagic and configured webhooks.
• Added provisioning profiles and iOS signing.
• Generated a CI/CD workflow.

Next, we'll build your app on both platforms and deploy it to the stores. Let's continue! 🚀