Getting started with Flutter apps

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 app on Bitrise.

Adding a Flutter app to Bitrise

Do you have a Bitrise account?

Make sure you have signed up to bitrise.io and can access your Bitrise account. There are multiple ways of registering an account:

  1. Go to your Bitrise Dashboard.

  2. Click the + sign on the top menu bar and select , which takes you to the Create New App page.

  3. Choose the account you wish to add the app to.

  4. Set the privacy of the app to either Private or Public and click Next.

  5. Select the Git hosting service that hosts your repository, then find and select your own repository that hosts the project.

  6. When prompted to set up repository access, click No, auto-add SSH key.

  7. Type the name of the branch that includes your project’s configuration - main, for example, - then click Next.

  8. 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.

  9. Type the name of the branch that includes your project’s configuration - master, for example - then click Next.

  10. If your app has tests in the repository, you will be prompted to decide if you want to run them.

    Getting started with Flutter apps
  11. If you have an iOS project in your Flutter project, you will have to select an .ipa export method.

    Getting started with Flutter apps
  12. Register a webhook when prompted.

    With a webhook, Bitrise can start a build automatically when code is pushed to your repository, or a pull request is created. This also kicks off your first build - click the message and it will take you to the build page.

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. By default, it will include the Flutter Analyze Step which runs static code tests. It can also include the Flutter Test Step that runs Flutter tests and can also generate code coverage reports.

Flutter tests

If you have tests in your repository, and selected yes when prompted, during app creation, whether you want to run these tests, the primary Workflow will include the Flutter Test Step by default. If you add tests to your app later, add the Flutter Test Step to your Workflow manually.

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:

  1. Open your app’s Workflow Editor and open the primary Workflow, or any of your Workflows that you want to use to run tests.

  2. 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.

  3. To the Flutter Analyze Step, add any flags you wish to use to the Additional parameters input.

    The Step runs the flutter analyze command with the specified flags. To check the available flags, open a command line interface on your own machine and run flutter analyze --help.

  4. 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.

    Getting started with Flutter apps
  5. 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.

  6. 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.

  7. To export the test results to the Test Reports add-on, add the Deploy to Bitrise.io Step to the end of your Workflow.

  8. Run a build!

Once it’s done, you can find your test results on the APPS & 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 deploy Workflow will be automatically generated when adding the app on Bitrise. The content of this Workflow depends on the platforms: for example, if your app contains only an iOS project, the Workflow will contain the Certificate and profile installer and the Xcode Archive & Export for iOS Steps.

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:

Getting started with Flutter apps

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 APPS & ARTIFACTS tab on your Build’s page.

You can share the generated app file (AAB 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 AAB/APK or IPA file has been built.

Publishing to expo.io

The Deploy to Bitrise.io Step does not use Expo commands and doesn’t publish to expo.io. This Step publishes artifacts to Bitrise and is not specific to a particular platform.

If you need to publish to expo.io, set the Run expo publish after eject? input of the Eject Expo Step to yes. Be aware that in that case you have to provide your username and password for your Expo account to publish to expo.io.

  1. Open your app on Bitrise.

  2. Go to the Workflow tab.

  3. Select a Workflow from the WORKFLOW dropdown menu.

    Installing any additional tools
  4. Make sure you have the Deploy to bitrise.io Step in your Workflow.

  5. 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 APPS & ARTIFACTS tab.

  6. 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.

  1. In Xcode, open Runner.xcworkspace in your app’s ios folder.

  2. 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.

  3. Select the General tab.

  4. In the Signing section, find the Team menu and set it to the team associated with your registered Apple Developer account.

  5. Commit the change to your repository!

    This is very important: if you only set the Team ID locally, your build will still FAIL on Bitrise!

Configuring Flutter deployment to the App Store on Bitrise

  1. Make sure you have the Certificate and profile installer Step in your Workflow.

  2. Upload the required code signing files to Bitrise.

  3. Open the Flutter Build Step and find the iOS Platform Configs input group.

  4. Make sure the Additional parameters input has the value --release.

  5. Check the Platform input of the Step: make sure it’s set to either iOS or both.

  6. Make sure you have the Xcode Archive & Export for iOS Step in your Workflow.

    It should be after the Flutter Build Step.

  7. Set the Select method for export input of the Step to app-store.

  8. Add the Deploy to iTunes Connect Step to the end of the Workflow.

  9. Provide your Apple credentials in the respective input fields.

    • Apple ID.

    • password or, if you use two-factor authentication on iTunes Connect, your application password.

    Don’t worry, the password will not be visible in the logs or exposed .

  10. 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.

  1. Generate a keystore file.

    The keystore file is required for code signing.

  2. Open an app on Bitrise and go to Workflow > Code signing > Android Code Signing.

  3. Drag and drop the keystore file, and fill out the metadata.

  4. Configure Google Play access.

    You only need to do this for your very first Google Play deployment of the app.

  5. Find the Android Platform Configs input group and Make sure the Additional parameters input has the value --release.

  6. In the Android output artifact type input field, select either APK or appbundle depending on your deployment requirements.

  7. 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.

  8. Make sure you have the Deploy to Google Play Step after the Android SignCordova Archive or Ionic Archive Step in your Workflow.

  9. 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).