---
title: "CI Integration"
description: "Integrate Shorebird in CI"
---

Building with Shorebird in CI should be a very small change from your existing Flutter CI builds. Changes required:

1. Installing Shorebird on the builder.
2. Getting Shorebird credentials onto the builder.
3. Replacing `flutter build --release` with `shorebird release` or `shorebird patch`.

## Prerequisites

[Section titled “Prerequisites”](#prerequisites)

Shorebird installs its own copy of Flutter in `~/.shorebird`. It does not install native platform toolchains. `shorebird release` and `shorebird patch` run `flutter build`, so a builder needs the same toolchain Flutter requires for your target platforms: a JDK and the Android SDK for Android, Xcode and CocoaPods for Apple platforms. See Flutter’s [install requirements](https://docs.flutter.dev/get-started/install) for the full list.

`shorebird doctor --verbose` lists the Android Studio, Android SDK, ADB, `JAVA_HOME`, Java version, and Gradle it detects on the builder.

```
shorebird doctor --verbose
```

## Supported CI providers

[Section titled “Supported CI providers”](#supported-ci-providers)

Detailed instructions are available for integrating into these providers:

[GitHub](/code-push/ci/github)Integrate Shorebird into your GitHub Actions workflows.

[Codemagic](/code-push/ci/codemagic)Integrate Shorebird into your Codemagic CI/CD pipelines.

If you do not use these providers, generic instructions are provided below:

## Installing Shorebird

[Section titled “Installing Shorebird”](#installing-shorebird)

Installing Shorebird is identical to how you install it locally. Most builders use Linux or Mac, which means running:

```
curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash
```

for more details, see [Getting Started](/).

## Getting Shorebird credentials onto the builder

[Section titled “Getting Shorebird credentials onto the builder”](#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](https://console.shorebird.dev):

[Create Shorebird API Key](https://demo.arcade.software/TQUMnX2QwuCRzEV1e8kN?embed\&embed_mobile=tab\&embed_desktop=inline\&show_copy_link=true)

1. Go to **Account → API Keys**.
2. Click **Create API Key**.
3. Give the key a name (e.g., “GitHub Actions — Flutter app”), choose an expiration, and select a permission level.
4. 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.

Caution

`SHOREBIRD_TOKEN` is a secret. Do not check it into source control or share it publicly. Store it in your CI platform’s secrets manager.

See [API Keys](/account/api-keys/#permissions) for details on permission levels and other key management options.

Migrating from `shorebird login:ci`

The `shorebird login:ci` command is deprecated. Existing tokens generated by `login:ci` will continue to work until September 2026, but new tokens should be created from the console. The `SHOREBIRD_TOKEN` environment variable name has not changed, so your CI workflow files need only a new key value.

Now that you have a token, it is important to keep that token secure. Using a secrets manager for the token, or secure environment variables, is recommended, 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.”](#replacing-flutter-build---release-with-shorebird)

### Releasing

[Section titled “Releasing”](#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:

```
flutter build ipa --dart-define=HERO=Mario
```

Would become:

```
shorebird release ios --dart-define=HERO=Mario
```

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

```
flutter build ipa --dart-define=HERO=Mario --enable-impeller
```

Would become:

```
shorebird release ios --dart-define=HERO=Mario -- --enable-impeller
```

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

```
shorebird release ios --flutter-version=3.47.4 --dart-define=HERO=Mario -- --enable-impeller
```

### Patching

[Section titled “Patching”](#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”](#ci-best-practices)

When integrating Shorebird into a continuous integration pipeline, following these best practices is recommended to ensure reliable and efficient builds:

### Pin the Flutter version for releases

[Section titled “Pin the Flutter version for releases”](#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:

```
shorebird release ios --flutter-version=3.22.2
```

Note

You do not need to pass `--flutter-version` to `shorebird patch`. Shorebird automatically detects the exact Flutter version used to build the original release and uses it to compile the patch.

### Verify PR builds with `--dry-run`

[Section titled “Verify PR builds with --dry-run”](#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:

```
shorebird patch android --dry-run
```

### Build without code signing in restricted environments

[Section titled “Build without code signing in restricted environments”](#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:

```
shorebird release ios --no-codesign
```

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”](#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 on [Discord](https://discord.gg/shorebird).