At the Flutter Live 2018 conference in London, Nevercode partnered with Google and launched dedicated CI/CD solution for Flutter apps - a solution called Codemagic. With Codemagic, you can get your Flutter apps tested and released with zero configuration and no pain.
We’re the Flutter experts, but we are also so much more. If you want to treat your native apps to the same quality of service, you can now use
codemagic.yaml file for configuring and building your native Android and iOS apps, as well as React Native apps. If you want to have more control over the scripts, Codemagic allows developers to run custom scripts and create custom workflows for their apps. Developing high-quality apps fast just got even better!
Now we will go through the steps to show how easy it is to set up CI/CD for your Flutter, native Android, native iOS, React Native apps using Codemagic CI/CD.
In order to set up your Flutter, native iOS, native Android or React Native app on Codemagic, you need a couple of things.
- Obviously, your Flutter, React Native or native Android or iOS app with some tests. Keep in mind that the app should be hosted on GitHub, GitLab or Bitbucket.
- Optional code signing details, like certificates and provisioning profiles, if you want to publish to App Store or Play Store.
- Optional Slack workspace for sending build reports and artifacts.
That's it. You are now ready to add CI/CD for your 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.
Once you sign in, you will see the Codemagic dashboard with the app repositories. You can filter or search the list to find your app that you want to build. As this is your first visit, you will see something like this:
You can click on the Set up build button for configuring your build workflow.
If you have an app that is already configured, but you have not started a build yet, then you will see like this:
You can click on Finish build setup to modify your configuration and then start your build.
P.S. If you have a previously built application on Codemagic, it will look like this:
You can click on Start new build to start a build with the previous configuration, or click on Settings (the gear icon) to modify it.
Configure your build
As you click on the Set up build button, you will arrive on this page. Here you can select the type of your project.
Just choose suitable option from the list. On selecting an option, you will be taken to the workflow configuration screen.
Now, on this page you can configure the build workflow for your Flutter app using the UI.
If you want more precise control over your build workflow, you can use the
codemagic.yaml file by clicking on the Download configuration button.
You can make any modifications to your workflow using this file. Just commit it to your VCS by placing it in the root directory of the project. Codemagic will automatically detect the file if it is present in the repository.
You can click on Set up build button for starting a quick build of your Flutter app. If you have not modified the workflow, it will use a default workflow 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.
If you are building any other project other than Flutter (native Android, iOS, React Native, or using a Flutter Module), then you you need to use the
codemagic.yaml file for configuring the workflow. You will get a template according to the type of project you have selected.
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.
We have just covered a happy path scenario where everything was working perfectly, 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, no matter if the step passes or fails. These logs are extremely 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.
Read more about the top 12 configuration mistakes that will fail your mobile CI build
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, you 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, you 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.
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
- Flutter version;
- build configuration for building apps, e.g debug or release;
- platforms like iOS or Android or both;
- Xcode version;
- custom build arguments.
The default workflow selects the following settings as part of the build.
However, you can always customize the build process by changing the default behavior in accordance with the project's needs. You can build the app with a different Xcode version or with a different release configuration by changing these options and using a custom workflow.
Another great feature of Codemagic is the ability to 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, you 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 you can put before the build phase.
You can add any commands in the Pre-build script, e.g. installing some project-specific dependencies.
In the test phase of Codemagic, developers can enable or disable the test execution. You can select the type of Flutter tests to run on your project. Also, you can provide any additional arguments to use during testing. If you are using Flutter Driver tests in your project, you can specify the type of emulator to use, or you can benefit from AWS Device Farm.
You can find detailed information about the Flutter Tests here.
However, you can use custom test commands by disabling the default behavior. For example, if you want to run just UI tests from command line, you 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.
In the publish phase of Codemagic, there are various things that 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.
You will have to explicitly configure any other aspects of the Publishing phase, including:
- Uploading the code signing assets for both iOS and Android
- Setting up Slack webhook
- Entering Google Play and/or App Store Connect details for publishing.
On top of these, you can also write some custom scripts to deploy the artifacts to third-party services like Fabric.
With the great power of scripting, you can configure custom workflows in Codemagic to define a stronger build process for your apps.
Codemagic allows you to create multiple workflows to meet the requirements of different configurations and versions of softwares. In Codemagic, you can create a new workflow by duplicating the existing workflow and renaming it. In order to do this, follow these steps:
- Go to your app settings.
- 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.
In the screen above, I have renamed the default workflow as “Custom WorkFlow”. You can create many workflows for testing Flutter apps with different versions of Xcode, debug vs release configuration, and so on.
Although Codemagic started as an official CI/CD solution dedicated just for Flutter apps, it now welcomes all mobile projects to the fastest CI/CD. With the magic of Codemagic, you can build, test, and publish Flutter apps with zero configuration and run builds in controlled environments using custom workflows. If you have a native Android, iOS, or React Native app, Codemagic has got your back, just use the
codemagic.yaml file and you are ready to lift off!