Getting started with Flutter projects

Abstract

Get started on Bitrise by signing up via email or a Git provider, connecting a repository, and running the first build for your Flutter app.

Flutter is a mobile app SDK that allows developers to create native apps for both iOS and Android. Bitrise supports Flutter apps: we have dedicated Steps to help you with all your Flutter needs. This guide walks you through setting up, testing, building and deploying a simple Flutter project on Bitrise.

Adding a Flutter project to Bitrise

Log in to Bitrise and go to the Dashboard.
Click the New CI project button.
Under Project access, select the Workspace that will own the project.
Set the privacy of the project.

Privacy is final

You cannot change this setting later! If you realize you've accidentally added your project as a public project even though you need it to be private, you'll have to delete the project and add it again.
- Private projects are only accessible to you, your Workspace members and those who are invited to work on a project. They require authentication to access the repository of the project.
- Public projects expose their bitrise.yml and their build logs to everyone. If you have a public project’s build URL, you can view its build log, to help with troubleshooting, for example. Public projects do not require authentication and they cannot have SSH keys.
Select one of two options to set your repository URL:
- With the Select remote repository option, you can select a repository from a list of repos from a connected Git provider account. Choose the Git provider from the dropdown menu, then click Select a repository... and select the repository from the list.
- The Enter URL manually option does not require a connected Git provider account: you can simply enter the URL and proceed to the authentication phase. We strongly recommend using an SSH URL, unless you are setting up a public project.
Repository URL

You will be able to change your project's repository URL later. You can also connect or disconnect your account to Git provider services at any time.

If you signed up for Bitrise using a Git provider account, that one is already connected and you can select any of your repositories from it.
If you use an OAuth connection, you need to add an SSH key in the Authorize Bitrise section.

You don't need SSH keys if:
- Your project is a public project.
- You connect to your Git repository via a GitHub project installation.
- Auto-add a generated SSH key to your repository: We recommend using this option. We automatically generate an SSH key pair and register the public key to your repository. Requires your connected Git provider account to have admin rights to the repository.
- Copy a generated SSH key to your Git provider manually: We generate an SSH key pair for you and you can copy the public key and register it manually to your Git provider. It is useful if, for example, you need to access multiple repositories with the same SSH key.
- Add your own SSH key to Bitrise: You can generate your own SSH key and paste the private key here after choosing this option. You also need to add the public key to the repository manually. To generate your SSH key pair: Generating your own SSH keypair.
Configure SSH keys at any time

If you can't set up a valid, working SSH key connection at this time, don't worry: proceed with adding your project. You can set up the SSH connection afterwards: Configuring SSH keys.
Select the default branch of your repository. This branch should contain the configuration of your project.
- If you successfully configured SSH access in the previous step or if you're adding a public project, Bitrise will parse your repository and allow you to select a branch from a dropdown menu.
- If you didn't configure repository access, you need to type the branch name manually.
You can change the default branch of the project later.
In the next step, choose Yes, auto-detect configuration. Bitrise will scan your repository and attempt to set up a stack and default Workflows based on the results of the scan. In most cases, we recommend choosing this option.

Project type

Detecting a project type serves to assist in the initial configuration of your project. But don't worry, you can change every setting, including the project type, at any time after you added the project.
Wait while Bitrise is validating your project.

We look for your configuration files and set up your app based on them. In the case of Flutter apps, you definitely need a pubspec.yaml file in your project.
Type the name of the branch that includes your project’s configuration - master, for example - then click Next.
If you have an iOS project in your Flutter project, you will have to select an .ipa export method.
Register a webhook when prompted so that Bitrise can start a build automatically when code is pushed to your repository, or a pull request is created.
Once you are done, click View Project Page to go to the newly added project's home page. From there, you can start editing your Workflows and run builds.

Testing a Flutter app

You can write and run unit-, widget-, and integration tests with Flutter. For more information, check out Flutter’s official documentation.

You can use our automatically generated primary Workflow to test your Flutter app. It can include the Flutter Test Step that runs Flutter tests and can also generate code coverage reports.

Test reports

The Deploy to Bitrise.io Step exports the results of the Flutter Test Step to the Test Reports add-on by default: to check your Flutter test results in the add-on, you just need to add the Deploy to Bitrise.io Step at the end of the Workflow.

To run tests on a Flutter app:

Open your app’s Workflow Editor and open the primary Workflow, or any of your Workflows that you want to use to run tests.
In the Flutter Install Step, fill in the Flutter SDK Version input.

You can specify either tags or branches of the Flutter SDK’s git repository. The default value is stable. This will use the latest stable branch of Flutter.
- To find the available version tags, check: https://github.com/flutter/flutter/releases.
- To see the the available branches, check: https://github.com/flutter/flutter/branches.
Add the Flutter Test Step. In the Additional parameters input, enter any flags you wish to use to.

The Step runs the flutter test command with the specified flags. To check the available flags, open a command line interface on your own machine and run flutter test --help.
Make sure the Project Location input of the Flutter Test Step is correct.

The default value is the the Environment Variable (Env Var) created for your Flutter project’s location.
If you want to generate code coverage reports, set the Generate code coverage files? input to yes.

This runs the flutter test command with the --coverage flag.
To export the test results to the Test Reports add-on, add the Deploy to Bitrise.io Step to the end of your Workflow.
Run a build!

Once it’s done, you can find your test results on the Artifacts tab of the Build’s page of the app.

Deploying a Flutter app

To build and deploy a Flutter app, a Workflow must contain these Flutter Steps:

Flutter Install
Flutter Build

If you have platforms specified in your repository, a deployment Workflow will be automatically generated when adding the project on Bitrise. The content of this Workflow depends on the platforms: for example, if your Flutter project contains only an iOS project, the Workflow will contain the Certificate and profile installer Step.

You can build both iOS and Android projects at the same time or you can build them separately, each using their own Workflow. You can set this in the Platform input of the Flutter Build Step any time. By default, the Step is configured according to the platform or platforms that the scanner detected when adding the app on Bitrise.

Here’s an example Workflow we’ll use in this configuration, with all the necessary Steps:

Pipelines for parallelization

In these examples, we're assuming that you are building and deploying both the iOS and Android versions of your app in the same Workflow, performing the necessary operations serially. However, you can do both versions in parallel with a single build trigger by using Pipelines:

Packages and libraries

We also support building Flutter packages and libraries. Unlike in the case of apps, there is no artifact to build so there is no need for a Flutter Build Step in your Workflow.

Deploying a cross-platform app to bitrise.io

The Deploy to bitrise.io Step uploads all the artifacts related to your build into the Artifacts tab on your Build’s page.

You can share the generated binary file (APK for Android or an IPA file for iOS) with your team members using the public install page. The public install page is a URL you can share with others who can install the generated app binary on their device. You can also notify user groups or individual users that your APK or IPA file has been built.

Log in to Bitrise and select Bitrise CI on the left, then select your project.
Click the Workflows button on the main page.
Make sure you have the Deploy to bitrise.io Step in your Workflow.
In the Notify: User Roles, add the role so that only those get notified who have been granted with this role. Or fill out the Notify: Emails field with email addresses of the users you want to notify.

Make sure you set those email addresses as Secrets! These details can be also modified under Notifications if you click the eye icon next to your generated binary in the Artifacts tab.
If you want the Step to generate a public install page for you, set the Enable public page for the App? input to true.

Deploying a Flutter app to App Store Connect

To deploy your iOS Flutter project to the App Store, you’ll need to build the app, export an IPA file and submit it to the App Store.

Unlike testing, this requires code signing files:

An iOS Distribution Certificate (a .p12 file).
An App Store Provisioning Profile.

For Flutter applications, code signing requires setting a Team ID in the project settings in Xcode.

Configuring Team ID for Flutter apps

Once you created your iOS project locally, you will need to review the project settings for it in Xcode. More specifically, you need to set a valid Team ID: without that, your build will fail on Bitrise.

In Xcode, open Runner.xcworkspace in your app’s ios folder.
To view your app’s settings, select the Runner project in the Xcode project navigator. Then, in the main view sidebar, select the Runner target.
Select the General tab.
In the Signing section, find the Team menu and set it to the team associated with your registered Apple Developer account.
Commit the change to your repository!

Don't forget to commit your changes!

If you only set the Team ID locally, your build will still FAIL on Bitrise!

Configuring Flutter deployment to the App Store on Bitrise

To deploy your app to the App Store, you need to upload the code signing files. You have two options:

Upload the code signing certificate(s) to Bitrise and use automatic code signing with the Manage iOS Code signing Step.
Upload the provisioning profile(s) and the code signing certificate(s) to Bitrise and use manual code signing with the Certificate and profile installer Step.

In this guide, we will focus on the second option, manual code signing:

Make sure you have the Certificate and profile installer Step in your Workflow.
Upload the required code signing files to Bitrise.
Open the Flutter Build Step and find the iOS Platform Configs input group.
Make sure the Additional parameters input has the value --release.
Check the Platform input of the Step: make sure it’s set to either iOS or both.
Set the iOS output artifact type input to archive.
Add the Export iOS and tvOS Xcode archive Step to your Workflow.

It should be after the Flutter Build Step.
Set the Distribution method input of the Step to app-store.
Add the Deploy to App Store Connect Step to the end of the Workflow.
Provide your Apple credentials in the respective input fields.
- Apple ID.
- password or, if you use two-factor authentication on App Store Connect, your application password.
Don’t worry, the password will not be visible in the logs or exposed .
Start a build!

If all goes well, the Step will submit the app to App Store Connect. You can, from the App Store Connect page, distribute the app to external testers via Testflight, or release it to the App Store itself.

Deploying a Flutter app to Google Play

To deploy your app to Google Play, you need to export an App Bundle file and sign it. You have two options:

You can configure code signing in the app’s build.gradle file and then Flutter will sign your app during the build phase.
Sign your AAB or APK file on Bitrise with our dedicated Step.

The scope of this guide is the second option: signing your AAB/APK file with the Android Sign Step.

Generate a keystore file.

The keystore file is required for code signing.
Open an app on Bitrise and go to Workflow > Code signing > Android Code Signing.
Drag and drop the keystore file, and fill out the metadata.
Configure Google Play access.

You only need to do this for your very first Google Play deployment of the app.
In the Flutter Build Step, find the Android Platform Configs input group and make sure the Additional parameters input has the value --release.
In the Android output artifact type input field, select either APK or appbundle depending on your deployment requirements.
In the Output (.apk, .aab) pattern input, set the path where the Deploy to Google Play Step will be able to access the generated binary.

The path should be relative to the project source directory, stored in the BITRISE_SOURCE_DIR Environment Variable.
Make sure you have the Deploy to Google Play Step after the Android Sign Step in your Workflow.
Fill out the required input fields as follows:
- Service Account JSON key file path: This field can accept a remote URL so you have to provide the Env Var which contains your uploaded service account JSON key. For example: $BITRISEIO_SERVICE_ACCOUNT_JSON_KEY_URL.
- Package name: The package name of your Android app.
- Track: The track where you want to deploy your APK (for example, alpha/beta/rollout/production or any custom track you set).

Additional Flutter content

In this section: