Skip to main content

Getting started with Flutter apps


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

Adding a Flutter app to Bitrise

Do you have a Bitrise account?

Make sure you have signed up to 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 Add New App on web UI, which takes you to the Create New App page.

    Alternatively, you can add your app using a CLI. For more details, check out Adding a new app from a CLI.

  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.

    Private vs public apps

    The most important difference between public and private apps is that if your app is public, everyone who has the build URL can see your build logs: Public apps. With a private app, you have full control over who has any access to the app.

  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 you have an iOS project in your Flutter project, you will have to select an .ipa export method.

    Getting started with Flutter apps
  11. 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. It can include the Flutter Test Step that runs Flutter tests and can also generate code coverage reports.

Test reports

The Deploy to 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 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. 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
  4. 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.

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

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

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

Getting started with Flutter apps

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

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

You can share the generated app 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.

  1. Open your app on Bitrise.

  2. Click the Workflows button on the main page.

  3. Select a Workflow from the WORKFLOW dropdown menu.

  4. Make sure you have the Deploy to 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 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!

    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

  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. Set the iOS output artifact type input to archive.

  7. Add the Export iOS and tvOS Xcode archive Step to your Workflow.

    It should be after the Flutter Build Step.

  8. Set the Distribution method input of the Step to app-store.

  9. Add the Deploy to App Store Connect Step to the end of the Workflow.

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

  11. 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. In the Flutter Build Step, 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 Sign 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).

Additional Flutter content