CI Integration
Building with Shorebird in CI should be a very small change from your existing Flutter CI builds. Changes required:
- Installing Shorebird on the builder.
- Getting Shorebird credentials onto the builder.
- Replacing
flutter build --releasewithshorebird releaseorshorebird patch.
We have detailed instructions for integrating into these providers:
If you do not use these providers, we’ve also provided generic instructions below:
Installing Shorebird
Section titled “Installing Shorebird”Installing Shorebird is identical to how you install it locally. Most builders use Linux or Mac, which means running:
for more details, see Getting Started.
Getting Shorebird credentials onto the builder
Section titled “Getting Shorebird credentials onto the builder”Most Shorebird functionality, like creating releases and patches, requires authentication. To authenticate in your CI, create an API key from the Shorebird Console:
- Go to Account → API Keys.
- Click Create API Key.
- Give the key a name (e.g., “GitHub Actions — my-app”), choose an expiration, and select a permission level.
- Copy the key value — it is only shown once.
Use this key as your SHOREBIRD_TOKEN in CI. The environment variable name is
unchanged from previous versions.
See API Keys for details on permission levels and other key management options.
Now that you have a token, it is important to keep that token secure. We
recommend using a secrets manager for the token, or secure environment
variables, depending on your CI setup. shorebird commands will look for the
token to be in a SHOREBIRD_TOKEN environment variable.
Replacing flutter build --release with shorebird.
Section titled “Replacing flutter build --release with shorebird.”Releasing
Section titled “Releasing”If you’re already building with Flutter in CI, you should see a line similar to
flutter build aab or flutter build ipa in your CI config.
To move to Shorebird, you need only replace the flutter build line with
shorebird release. For example:
Would become:
shorebird release supports almost all of the same arguments that
flutter build does. If you ever see an error with shorebird release not
supporting an argument that flutter build does, you can use -- to tell
shorebird to pass any argument after -- down to flutter build separately,
e.g.
Would become:
shorebird can support building with different versions of Flutter. By default
shorebird will use whatever the most recent Flutter stable is, which can
change. If you’d like to pin your CI to a specific Flutter version you can do
this by adding --flutter-version to your command, e.g.
Patching
Section titled “Patching”Patching is identical to releasing, just use shorebird patch instead of
shorebird release.
Patches with Shorebird can only ever apply to an existing Release. By definition a patch is a set of changes to apply to a Release.
shorebird patch does not take a --flutter-version argument, instead takes a
--release-version argument, to specify which release version of your app
you’re trying to patch. shorebird will look up the exact version of Flutter
used to build the release and use that exact version to build the patch.
CI Best Practices
Section titled “CI Best Practices”When integrating Shorebird into a continuous integration pipeline, we recommend following these best practices to ensure reliable and efficient builds:
Pin the Flutter version for releases
Section titled “Pin the Flutter version for releases”By default, shorebird release builds with the latest stable version of
Flutter. Because the stable version of Flutter is periodically updated, your CI
builds could use a different version of Flutter than what you developed and
tested with.
To ensure consistent builds, pin the Flutter version using the
--flutter-version flag:
Verify PR builds with --dry-run
Section titled “Verify PR builds with --dry-run”To verify that code changes do not break your release or patch builds, you can
add a CI check that runs shorebird release or shorebird patch on every pull
request.
To prevent these validation builds from uploading artifacts or creating actual
releases/patches in the Shorebird Console, add the --dry-run (or -n) flag to
the command:
Build without code signing in restricted environments
Section titled “Build without code signing in restricted environments”If your CI runners do not have access to Apple distribution certificates or
provisioning profiles, you can still build and package Shorebird releases and
patches for iOS by passing the --no-codesign flag:
Releases built with --no-codesign cannot be launched via shorebird preview
or installed directly on devices. You must manually codesign the generated
.xcarchive in Xcode or through your signing pipeline before distribution.
Run CLI commands non-interactively
Section titled “Run CLI commands non-interactively”The Shorebird CLI automatically detects if it is running in a CI environment
(such as when the CI environment variable is set to true) and runs in
non-interactive mode. In this mode, prompts that normally require user
confirmation are skipped or use safe default options.
To guarantee that your CI builds never block on an interactive prompt, ensure
the SHOREBIRD_TOKEN environment variable is set. If you need to explicitly
bypass interactive prompts in other environments, you can pass the
--no-confirm flag to shorebird patch or shorebird release.
Thank you for reading this guide! If you have any questions or suggestions, feel free to reach out to us at our Discord.