Create a Release

In order to start pushing updates, you will need to create a release.

Watch the video: Create a release

shorebird release is a drop-in replacement for flutter build. It builds your app and uploads the compiled Dart artifacts to Shorebird’s servers as a baseline for future patches. After running this command, you still need to upload the generated artifact (.aab for Android, .ipa for iOS) to the respective store.

Android

Create an Android release by running the following command:

shorebird release android

Example output:

$ shorebird release android
✓ Building release (9.6s)
✓ Fetching apps (0.2s)
✓ Detecting release version (0.2s)
✓ Fetching releases (68ms)

🚀 Ready to create a new release!

📱 App: new_flutter_app (7a29188a-9363-426a-9a36-74a5e166373d)
📦 Release Version: 1.0.0+1
🕹️  Platform: android (arm64, arm32, x86_64)

✓ Fetching Flutter revision (30ms)
✓ Updating release status (67ms)
✓ Creating artifacts (2.8s)
✓ Updating release status (62ms)

✅ Published Release!

Your next step is to upload the app bundle to the Play Store.
build/app/outputs/bundle/release/app-release.aab

See the following link for more information:
https://support.google.com/googleplay/android-developer/answer/9859152?hl=en

If your application supports flavors or multiple release targets, you can specify the flavor and target using the --flavor and --target options:

shorebird release android --target ./lib/main_development.dart --flavor development

Note

shorebird release wraps flutter build and can take any argument flutter build can. To pass arguments to the underlying flutter build, you need to put flutter build arguments after a -- separator. For example: shorebird release android -- --dart-define="foo=bar" will define the "foo" environment variable inside Dart as you might have done with flutter build directly. In PowerShell, the -- separator must be quoted: '--'.

By default, shorebird release android builds an AppBundle (.aab). If you would like to also generate an Android Package Kit (.apk), use the following command:

shorebird release android --artifact apk

Build a smaller APK for one architecture

By default, shorebird release android compiles for three Android ABIs: android-arm (32-bit ARM / armeabi-v7a), android-arm64 (arm64-v8a), and android-x64 (x86_64). That produces a larger APK than a Flutter build that only packages arm64-v8a.

To build for a single architecture, pass --target-platform before any -- separator:

shorebird release android --artifact apk --target-platform android-arm64

Allowed values are android-arm, android-arm64, and android-x64. Pass the flag more than once, or as a comma-separated list, to include extra ABIs.

Gradle NDK ABI filters (for example ndk.abiFilters) are not a substitute for --target-platform. If Gradle omits an ABI that is still in --target-platform, Shorebird skips that architecture instead of failing, and the release ships with only the ABIs that actually built. Use --target-platform to declare the architectures you want — a mismatched Gradle filter will not error.

--target-platform is a Shorebird flag. Do not put it after -- — that forwards it to flutter build and is not applied the same way.

shorebird patch android against a single-arch release does not need the flag. The patch command skips architectures that were not part of the release.

Note

By default, shorebird release uses the Flutter version bundled within the Shorebird installation.

That version can be checked by running shorebird doctor.

To release with a different Flutter version, you can specify the version using the --flutter-version flag.

shorebird release android --flutter-version 3.47.7

iOS

Create an iOS release by running the following command:

shorebird release ios

Example output:

$ shorebird release ios
✓ Fetching apps (0.2s)
✓ Building release (59.0s)
✓ Getting release version (40ms)
✓ Fetching releases (0.1s)
🚀 Ready to create a new release!
📱 App: My App (7a29188a-9363-426a-9a36-74a5e166373d)
📦 Release Version: 1.0.0+1
🕹️  Platform: ios

✓ Fetching Flutter revision (40ms)
✓ Creating release (0.1s)
✓ Creating artifacts (5.1s)
✓ Updating release status (57ms)

✅ Published Release!

Your next step is to upload the IPA to App Store Connect.
`build/ios/ipa/new_flutter_app.ipa`

To upload to the App Store either:
    1. Drag and drop the "build/ios/ipa/new_flutter_app.ipa" bundle into the Apple Transporter macOS app (https://apps.apple.com/us/app/transporter/id1450874784)
    2. Run xcrun altool --upload-app --type ios -f build/ios/ipa/new_flutter_app.ipa --apiKey your_api_key --apiIssuer your_issuer_id.
       See "man altool" for details about how to authenticate with the App Store Connect API key.

If your application supports flavors or multiple release targets, you can specify the flavor and target using the --flavor and --target options:

shorebird release ios --target ./lib/main_development.dart --flavor development

Note

shorebird release wraps flutter build and can take any argument flutter build can. To pass arguments to the underlying flutter build, you need to put flutter build arguments after a -- separator. For example: shorebird release android -- --dart-define="foo=bar" will define the "foo" environment variable inside Dart as you might have done with flutter build directly.

Note

By default, shorebird release uses the Flutter version bundled within the Shorebird installation.

That version can be checked by running shorebird doctor.

To release with a different Flutter version, you can specify the version using the --flutter-version flag.

shorebird release ios --flutter-version 3.47.7

Signing issues

Depending on how you normally sign your iOS app, you may see an error at the end of the build saying something like: Runner.app requires a provisioning profile with ___ feature or that no signing certificate was found. This can be addressed in a few ways:

Setting up automatic signing in Xcode

If you are releasing on your local machine (i.e., not in a CI environment), this option is easier than the following options, but does not always work well in CI environments.

In Xcode, open your project and navigate to the “Signing & Capabilities” tab. Ensure that “Automatically manage signing” is checked.

Create an ExportOptions.plist file.

You may need to provide an ExportOptions.plist file to the shorebird release ios command. This file is used by Xcode to determine which certificate and provisioning profile should be used to sign the .ipa. An example of this file is:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>method</key>
	<string>app-store</string>
	<key>provisioningProfiles</key>
	<dict>
		<key>com.example.your_bundle_id</key>
		<string>Your App's App Store Provisioning Profile Name</string>
	</dict>
	<key>signingCertificate</key>
	<string>Apple Distribution</string>
	<key>signingStyle</key>
	<string>manual</string>
	<key>teamID</key>
	<string>*****</string> <!-- From https://developer.apple.com/account -->
</dict>
</plist>

To use this file, pass it to the shorebird release ios command:

shorebird release ios --export-options-plist=path/to/ExportOptions.plist

Linux

Create a Linux release by running the following command:

shorebird release linux

Example output:

$ shorebird release linux
✓ Fetching apps (0.3s)
✓ Building app bundle with Flutter 3.41.4 (1e0e5760ee) (18.3s)
✓ Fetching releases (0.1s)

🚀 Ready to create a new release!

📱 App: sample (d0cf1d8f-e741-4f5d-b280-b794000df1cd)
📦 Release Version: 1.0.0+1
🕹️  Platform: linux
🐦 Flutter Version: 3.41.4 (1e0e5760ee)

✓ Fetching releases (0.1s)
✓ Creating release (0.3s)
✓ Updating release status (0.1s)
✓ Uploading artifacts (3.5s)
✓ Updating release status (1.7s)

✅ Published Release 1.0.0+1!

macOS

Create a macOS release by running the following command:

shorebird release macos

Example output:

$ shorebird release macos
✓ Fetching apps (0.3s)
✓ Building app bundle with Flutter 3.41.4 (1e0e5760ee) (18.3s)
✓ Fetching releases (0.1s)

🚀 Ready to create a new release!

📱 App: sample (d0cf1d8f-e741-4f5d-b280-b794000df1cd)
📦 Release Version: 1.0.0+1
🕹️  Platform: macos
🐦 Flutter Version: 3.41.4 (1e0e5760ee)

✓ Fetching releases (0.1s)
✓ Creating release (0.3s)
✓ Updating release status (0.1s)
✓ Uploading artifacts (3.5s)
✓ Updating release status (1.7s)

✅ Published Release 1.0.0+1!

macOS app created at build/macos/Build/Products/Release/new_flutter_app.app.

To create a patch for this release, run shorebird patch --platforms=macos --release-version=1.0.0+1

If your application supports flavors or multiple release targets, you can specify the flavor and target using the --flavor and --target options:

shorebird release macos --target ./lib/main_development.dart --flavor development

Note

shorebird release wraps flutter build and can take any argument flutter build can. To pass arguments to the underlying flutter build, you need to put flutter build arguments after a -- separator. For example: shorebird release android -- --dart-define="foo=bar" will define the "foo" environment variable inside Dart as you might have done with flutter build directly. In PowerShell, the -- separator must be quoted: '--'.

Note

By default, shorebird release uses the Flutter version bundled within the Shorebird installation.

That version can be checked by running shorebird doctor.

To release with a different Flutter version, you can specify the version using the --flutter-version flag.

shorebird release macos --flutter-version 3.47.7

Windows

Create a Windows release by running the following command:

shorebird release windows

Example output:

$ shorebird release windows
✓ Fetching apps (0.3s)
✓ Building Windows app with Flutter 3.41.4 (1e0e5760ee) (18.3s)
✓ Fetching releases (0.1s)

🚀 Ready to create a new release!

📱 App: sample (d0cf1d8f-e741-4f5d-b280-b794000df1cd)
📦 Release Version: 1.0.0+1
🕹️  Platform: windows
🐦 Flutter Version: 3.41.4 (1e0e5760ee)

✓ Fetching releases (0.1s)
✓ Creating release (0.3s)
✓ Updating release status (0.1s)
✓ Uploading artifacts (3.5s)
✓ Updating release status (1.7s)

✅ Published Release 1.0.0+1!

Windows executable created at build/windows/x64/runner/Release

To create a patch for this release, run shorebird patch --platforms=windows --release-version=1.0.0+1

If your application supports flavors or multiple release targets, you can specify the flavor and target using the --flavor and --target options:

shorebird release windows --target ./lib/main_development.dart --flavor development

Note

shorebird release wraps flutter build and can take any argument flutter build can. To pass arguments to the underlying flutter build, you need to put flutter build arguments after a -- separator. For example: shorebird release android -- --dart-define="foo=bar" will define the "foo" environment variable inside Dart as you might have done with flutter build directly. In PowerShell, the -- separator must be quoted: '--'.

Note

By default, shorebird release uses the Flutter version bundled within the Shorebird installation.

That version can be checked by running shorebird doctor.

To release with a different Flutter version, you can specify the version using the --flutter-version flag.

shorebird release windows --flutter-version 3.47.7

To package this build for the Microsoft Store, set build_windows: false in the msix_config section of pubspec.yaml so package:msix does not rebuild with stock Flutter. See Releasing for Windows, which also covers other installers such as Inno Setup, WiX and NSIS.

Options

Option	Abbreviation	Description
--platforms	-p	Comma-separated list of platforms to release simultaneously (e.g., android,ios).
--flavor		The product flavor to use when building.
--target	-t	The main entrypoint file of the application.
--flutter-version		The Flutter version to build with (e.g., 3.47.5). Defaults to the version bundled with Shorebird.
--build-name		Override the version name (e.g., 1.2.3).
--build-number		Override the version code / build number (e.g., 42).
--artifact		Android artifact type: aab (default) or apk.
--target-platform		Android ABIs to compile: android-arm, android-arm64, android-x64. Defaults to all three.
--dry-run	-n	Build and validate the release but do not upload it. Ideal for CI validation.
--obfuscate		Obfuscate Dart code. Without --split-debug-info, symbols are written to build/shorebird/symbols.
--split-debug-info		Output Dart debug symbol files to the specified directory. See Uploading Symbols.

iOS-specific options

Option	Description
--no-codesign	Skip code signing for the iOS build.
--export-options-plist	Path to a custom ExportOptions.plist for the iOS archive export step.
--export-method	Distribution method: app-store, ad-hoc, development, or enterprise.

Releasing for multiple platforms simultaneously

If your app supports multiple platforms, you can build and publish releases for them in a single command using the --platforms (or -p) option:

shorebird release --platforms=android,ios

This will compile the binaries for the specified platforms and register them as a single version release in your Shorebird console. Note that to release for iOS or macOS, you must run this command on macOS hardware.

Release versions

Shorebird identifies a release by your app’s version and build number, joined with a +, such as 1.0.0+1. shorebird release reads them from the app it builds: versionName and versionCode on Android, CFBundleShortVersionString and CFBundleVersion on iOS and macOS, the executable’s product version on Windows, and version.json in the app bundle on Linux. By default those come from the version in your pubspec.yaml, or from --build-name and --build-number if you pass them. Anything that sets them in the native project overrides that: values written directly in Info.plist or build.gradle, a flavor’s versionNameSuffix or versionCode, or a tool such as fastlane that bumps the build number. The version that counts is the one in the build you publish to the store.

For add-to-app, shorebird release aar and shorebird release ios-framework don’t read a version from the build. They use --release-version, which must match the version and build number of the host app you publish.

A patch is made for one release version. An installed app asks for patches using the version it was built with, and gets only patches made for a release with exactly that version on the same platform. 1.0.0+1 and 1.0.0+2 are different releases, and a patch for one doesn’t install on the other.

This means:

• Every build you publish to a store needs its own shorebird release. A build with a new version or build number doesn’t receive patches made for an earlier release. When a device updates to it, the updater discards patches it downloaded for the previous version.
• Platforms with the same version share a release. Releasing Android and iOS as 1.0.0+1 adds both platforms to one release. Every platform in a release must use the same Flutter version. If they don’t, shorebird release stops and asks you to pass that release’s --flutter-version or bump the version.
• You can’t release a version twice on the same platform. If that version is already released for the platform, shorebird release stops and asks you to bump the version number. If an earlier run for that version stopped before it finished, running shorebird release again replaces what the earlier run uploaded, so publish the build from the last run. See Patches can’t install because the app isn’t the build Shorebird released.

To patch a specific release, see Create a Patch.

Manage releases

In addition to using the Shorebird console, you can manage your app’s releases directly from the command line using the shorebird releases commands.

List releases

Watch the video: View releases from the CLI and console

Via the Shorebird CLI

To list all releases associated with your app:

shorebird releases list

This will output a list of all releases, showing their version number, target platform, Flutter version, and active patch number.

Via the console

You can view all of your releases for your current app (as defined by your shorebird.yaml) on the Shorebird console.

View release details

To view detailed information for a specific release version:

shorebird releases info --release-version 1.0.0+1

This command displays metadata for the release, including which platforms are active and details of any patches created for it.

Get APKs from a Release (Android only)

If you created an Android release using an App Bundle (.aab) and want to generate local APKs from it for testing or side-loading, you can download them using:

shorebird releases get-apks --release-version 1.0.0+1

This downloads the release AAB and builds APK files locally. By default that produces a universal APK (every ABI in the AAB). Pass --no-universal to extract one APK per ABI instead:

shorebird releases get-apks --release-version 1.0.0+1 --no-universal

If you want a small APK at build time rather than splitting a fat AAB afterwards, use --target-platform as described in Build a smaller APK for one architecture.

Delete releases

Watch the video: Delete a release

Deleting a release is permanent

Deleting a release removes the release, its artifacts, and every patch associated with it, and it can’t be restored afterwards. The console asks you to confirm before anything is removed.

If you only want to stop serving a bad patch, you can roll it back instead. You can undo a rollback later.

You can delete a release for your app (as defined by your shorebird.yaml) on the Shorebird console.

1. Navigate to the application.
2. Click on the release you wish to delete.
3. Go to the “Settings” tab at the top of the page.
4. In the “Danger Zone” there will be a “Delete” button.

In order to complete the delete request, you do need to confirm which binaries you would like to be deleted. You can easily delete all releases or pick by platform. The list of platforms shown is based on the binaries that are uploaded for that release.

The deletion takes effect as soon as you confirm. See Delete Apps, Releases, and Patches for what is removed and for alternatives to deleting.

You can also delete a release from the command line, which is useful in scripts that clean up test releases. Deleting a release deletes its patches, and devices on that release get no new patches. Pass --platform to delete only one platform’s release artifacts and patch files and keep the release. The command asks you to confirm; pass --yes in scripts. It needs Shorebird 1.6.129 or newer:

shorebird releases delete --release-version 1.0.0+1

Run shorebird releases delete --help for all options.

Side-loading and MDM

A common question is: Does Shorebird require publishing to the App Store or Play Store?

No. Shorebird works fine with side-loading and mobile device management (MDM) on Android. No one has yet reported trying Shorebird with the iOS Developer Enterprise program, but it’s expected to work just as well.

To build Shorebird for distribution via APK (e.g., side-loading), use the --artifact flag with the shorebird release command. For example:

shorebird release android --artifact=apk

That will produce both .apk and .aab files. You can distribute either or both as needed.

What’s next

Create a PatchPush over-the-air updates to your published release.

Releasing for AndroidLearn how to build, sign, and submit your release to the Google Play Store.

Releasing for iOSLearn how to configure Xcode signing and submit your release to the Apple App Store.

Releasing for WindowsPackage a Shorebird Windows release as an MSIX without rebuilding on stock Flutter.