Getting Started with Codemagic

There is another shakeup in the world of cross-platform mobile application development with the rise of Flutter. Flutter is Google’s mobile app SDK which allows developers to write apps for iOS and Android using the same language and source code. As big companies have already started to build apps with Flutter and Google recently announced a stable version of Flutter, the popularity of Flutter is increasing day by day. The key benefit of Flutter is that the apps look like native apps on both Android and iOS without having two different tech stacks of two different teams. As the number of Flutter apps grows and more developers are working on Flutter, there is an increasing need for Continuous Integration and Continuous Delivery (CI/CD) for Flutter apps so that they can be tested at regular intervals and released smoothly. Luckily, Google partnered with Nevercode who built the Codemagic CI/CD solution dedicated to Flutter apps. In this post, we will cover how to set up Codemagic for existing Flutter apps that you are developing or have already developed.

Codemagic - CI for Flutter

At the Flutter Live 2018 conference in London, Nevercode launched their dedicated CI/CD solution for Flutter apps which is known as Codemagic. With Codemagic, you can get your Flutter apps tested and released with zero configuration and without any pain. If you want to have more control over the scripts, Codemagic allows developers to run custom scripts and create custom workflows for their Flutter apps. Now, we will go through the steps to show how easy it is to set up CI/CD for your Flutter apps using Codemagic.

Requirements

In order to set up your Flutter app on Codemagic, you need a couple of things.

  1. Obviously, your Flutter app with some tests.
  2. The Flutter app should be hosted on GitHub, GitLab or Bitbucket.
  3. Optional code signing details, like certificates and provisioning profiles, if you want to publish to App Store or Play Store.
  4. Optional Slack workspace for sending build reports and artifacts.

That’s it. You are now ready to add CI/CD for your Flutter app. Now, let’s go over the basics with examples from real apps. We will not cover code signing and publishing in this tutorial as these topics will be covered separately.

Register for Codemagic

The first step is to visit the codemagic.io website and register yourself with your GitHub, GitLab or Bitbucket account. Note that you can integrate all these repositories with one Codemagic account to have all your apps in one place.

Start your first build

Once you sign in, you will see the Codemagic dashboard with the app repositories. You can filter the list or search apps to find your Flutter app.

You can then immediately start a build. Just go ahead and click that Start your first build button.

Default build workflow

As soon as you kick off a build, Codemagic will magically create a workflow for your Flutter project. This is the default workflow without any configuration, but you can customize the workflow if needed. The default workflow will start the build with the following steps:

The steps include preparing the build machine, checking out the source code, installing Flutter dependencies, running tests, building the apps and publishing the artifacts. That’s what you need for a basic CI/CD workflow. Codemagic reports the log of each step when you expand the steps.

Build report

At the end of the build, you will see a build overview with all the details, like build time, build status and commit, on Codemagic dashboard. It looks like this:

On top of this, you will also get an email with the status of the build and artifacts for both iOS and Android apps by default. The email will look like this:

You can even configure Slack if you want to have build reports in your Slack channel.

That’s it! You have just added CI/CD support for your Flutter apps without any configuration. This is the magic of Codemagic.

Build failures

We have just covered a happy path scenario where everything was green, but in real world, that’s not always the case. We get build failures, test failures or some other problems that need investigation. Codemagic provides detailed logs of each step regardless whether it passes or fails, which are useful for debugging build failures. In my case, I have a failing unit test, and the build failure is logged with all the details.

As can be seen, my integration tests and widget tests are passing, but the unit test is failing in the above screen. I can then fix the problem to fix the build. When tests fail, you will also get an email about the test failure with link to the build logs.

Default workflow vs custom workflow

The default build workflow covers the basic things needed for the CI/CD workflow, but most of the time, we need to add some custom things as part of the build process. For example, we may want to send the build status to Slack or other third-party communication channel, or publish the build artifacts on other services, like Fabric or HockeyApp, etc. In these scenarios, we can create a custom workflow and run custom scripts to achieve this. Now, we will see how we can customize a workflow as per the project’s needs.

Build phase

The Codemagic build phase of Flutter apps has various options to define the build process. You can start by selecting which branches to build and how to trigger builds.

Next, Codemagic allows us to go into more details and select

  1. version of Flutter;
  2. build configuration for building apps, e.g debug or release;
  3. platforms like iOS or Android or both;
  4. version of Xcode;
  5. custom build arguments.

The default workflow selects the following settings as part of the build.

However, we can always customize the build process by changing the default behavior as per the project’s needs. We can build the app with a different Xcode version or with release configuration by changing these options using a custom workflow.

Another great feature of Codemagic is that we can add a custom script before every phase. This allows developers to run arbitrary commands before and after each phase. In order to set up the custom scripts, we just need to click on the + sign on top of each phase, e.g build, test or publish. Here is an example of the script that we can put before the build phase.

Add custom scripts
Add custom scripts

We can add any commands in the pre-build script, e.g installing some project-specific dependencies.

Test phase

In the test phase of Codemagic, developers can enable or disable the test execution. The test phase has two sections, one for the unit and widget tests and the other for the integration tests. You can find detailed information on the layers of testing Flutter apps here. Codemagic automatically detects the unit, widget and integration tests and enables them by default. In our case, we have unit tests, widget tests and integration (UI) tests. Codemagic has enabled both the Flutter Test and the Flutter Drive phase as can be seen below.

Test section in Codemagic
Test section in Codemagic

However, we can use custom test commands by disabling the default behaviour. For example, if I want to run just UI tests from command line, I can add a pre-test phase with the command

$flutter drive --target=test_driver/main.dart

This will execute this command instead of using the default test workflow.

Publish phase

In the publish phase of Codemagic, there are various things which need to be configured for publishing the build reports and artifacts. By default, only email is configured if you have provided it with GitHub/Bitbucket/GitLab.

We have to explicitly configure any other aspects of the Publishing phase, including:

  1. uploading the code signing assets for both iOS and Android;
  2. setting up Slack webhook;
  3. entering Google Play and App Store Connect details for publishing.
Publish section in Codemagic
Publish section in Codemagic

On top of these, we can also write some custom scripts to deploy the artifacts to third-party services like Fabric or HockeyApp.

With the great power of scripting, we can configure custom workflows in Codemagic to define a stronger build process for Flutter apps.

Multiple workflows

Codemagic allows us to create multiple workflows to meet the requirements of different configurations and versions of softwares. In Codemagic, we can create a new workflow by duplicating the existing workflow and renaming it. In order to do this, follow these steps:

  1. Go to your app settings.
  2. In the Workflow settings section, click Duplicate workflow. The duplicated workflow will appear in the list below the app name as “Default Workflow (Copy)”. Select the workflow and rename it.
Duplicating workflows
Duplicating workflows

In the screen above, we have renamed the default workflow as “Custom WorkFlow”. We can create many workflows for testing Flutter apps with different versions of Xcode, debug vs release configuration, and so on.

Conclusion

Codemagic is the official CI/CD solution dedicated just for Flutter apps. With the magic of Codemagic, we can build, test and publish Flutter apps with zero configuration. We can also run builds in controlled environments using custom workflows. Hope you like this brief getting started with Codemagic guide. We will have detailed documentation available soon!


This article is written by Shashikant Jagtap and updated by Helina Ariva

Shashikant is DevOps practitioner for mobile apps and Director at XCTEQ Limited. He has automated release pipelines, implemented CI/CD and enabled DevOps cum Test Automation practices for many apps.

He blogs about mobile DevOps and CI/CD. Check-out XCTEQ for more: https://www.xcteq.co.uk/

Codemagic CI for Flutter