GitLab Integration

This guide shows you how to create Shorebird releases and patches from GitLab CI/CD with a .gitlab-ci.yml file.

Prerequisites

✅ Shorebird CLI is installed on your machine

✅ You are logged into a Shorebird account.

✅ Your app has been initialized with shorebird init, and shorebird.yaml is committed to your repository.

Note

Refer to the getting started instructions for more information.

Quick start

There is no Shorebird component for GitLab. A job installs Shorebird with the same script you use locally, then adds it to the PATH:

shorebird-example:
  # Any image with Git, a JDK and the Android SDK works.
  image: ghcr.io/cirruslabs/flutter:stable
  # Runs only when you start it, rather than on every push.
  when: manual
  allow_failure: true
  script:
    - curl -fsSL https://shorebird.dev/install.sh | bash
    - export PATH="$HOME/.shorebird/bin:$PATH"
    - shorebird --version

Shorebird installs its own copy of Flutter in ~/.shorebird, so the Flutter version in the image does not matter. It does not install a JDK or the Android SDK, so the image needs those. shorebird doctor --verbose lists what it finds on the runner.

Authentication

Most Shorebird functionality, like creating releases and patches, requires authentication. To authenticate in your CI, create an API key from the Shorebird Console:

Watch the video: Create a Shorebird API key

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 for details on permission levels and other key management options.

Use a service account for shared CI

A personal API key stops working if its owner’s account is deleted. A service account belongs to your organization instead, and its key goes in SHOREBIRD_TOKEN the same way.

Migrating from shorebird login:ci

The shorebird login:ci command has been replaced by API keys, and tokens it generated stopped working on October 1, 2026. Create an API key in the console instead. The SHOREBIRD_TOKEN environment variable name has not changed, so your CI workflow files need only a new key value.

Next, copy the generated SHOREBIRD_TOKEN and navigate to your GitLab project’s CI/CD variables via:

"Settings" -> "CI/CD" -> "Variables".

Then, click "Add variable" and enter:

Key: SHOREBIRD_TOKEN
Value: <THE GENERATED SHOREBIRD_TOKEN>
Visibility: Masked (or Masked and hidden)
Protect variable: checked

Masking keeps the key out of job logs. Protect variable makes GitLab pass the key only to pipelines on protected branches and tags, so a pipeline on any other branch can’t read it. GitLab protects your default branch unless your project or group settings change that; if yours do, protect it under "Settings" -> "Repository" -> "Protected branches".

GitLab passes CI/CD variables to every job as environment variables, so the Shorebird CLI finds SHOREBIRD_TOKEN without any change to .gitlab-ci.yml.

Note

Signing in with OIDC is available for GitHub Actions only. GitLab jobs use an API key in SHOREBIRD_TOKEN.

Android code signing

shorebird release android and shorebird patch android run flutter build, so signing works exactly as it does for any Flutter app. Follow Flutter’s Android signing instructions, or the Shorebird version of them.

The only difference on CI is that the keystore is not already on the machine. The pipeline below expects four more CI/CD variables:

• ANDROID_KEYSTORE_BASE64: your upload keystore, base64-encoded on one line (base64 -i upload-keystore.jks | tr -d '\n').
• ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS and ANDROID_KEY_PASSWORD: the values your key.properties holds locally.

Check Protect variable on all four, as for SHOREBIRD_TOKEN, and mask each one GitLab accepts as masked (masked values need at least 8 characters and no spaces). Leave Expand variable reference cleared, which is the default since GitLab 18.6. If it is checked on ANDROID_KEYSTORE_PASSWORD or ANDROID_KEY_PASSWORD, GitLab reads a $ in the password as a reference to another variable and the build fails with a keystore password error.

The jobs decode the keystore to a path outside your checkout and write android/key.properties before the Shorebird command runs.

Without key.properties, the release build fails, because the release signing config from the Gradle setup above gets no storeFile. An app still on Flutter’s default release config signs with the debug key instead, which the Play Console rejects.

Create releases and patches

Add this to .gitlab-ci.yml. It adds two manual jobs to pipelines on your default branch: one creates an Android release, the other patches one. Your other jobs are left as they are.

# Settings shared by every Shorebird job.
.shorebird:
  # A default stage. If your file lists stages:, add deploy to it.
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual
  # Keep the pipeline from waiting on a manual job nobody runs.
  allow_failure: true
  before_script:
    # Install Shorebird and add it to the PATH for this job.
    - curl -fsSL https://shorebird.dev/install.sh | bash
    - export PATH="$HOME/.shorebird/bin:$PATH"

# Settings shared by the Android jobs below.
.android:
  extends: .shorebird
  # Any image with Git, a JDK and the Android SDK works.
  image: ghcr.io/cirruslabs/flutter:stable

# Decode the keystore and write key.properties for release signing.
.android_signing: &android_signing
  - echo "$ANDROID_KEYSTORE_BASE64" | base64 -d > /tmp/upload-keystore.jks
  - |
    cat > android/key.properties <<EOF
    storePassword=$ANDROID_KEYSTORE_PASSWORD
    keyPassword=$ANDROID_KEY_PASSWORD
    keyAlias=$ANDROID_KEY_ALIAS
    storeFile=/tmp/upload-keystore.jks
    EOF

release-android:
  extends: .android
  variables:
    # Pin the Flutter version so every release builds the same way.
    FLUTTER_VERSION: '3.47.7'
  script:
    - *android_signing
    - shorebird release android --flutter-version="$FLUTTER_VERSION"
  artifacts:
    # The app bundle to upload to the Play Store.
    paths:
      - build/app/outputs/bundle/release/app-release.aab

patch-android:
  extends: .android
  variables:
    # The release to patch. "latest" is the most recently updated release.
    RELEASE_VERSION: latest
  script:
    - *android_signing
    - shorebird patch android --release-version="$RELEASE_VERSION"

To run a job, open the pipeline and click Run (▶) on release-android or patch-android. To patch a release other than the latest, click the job’s name instead and set RELEASE_VERSION to that release’s version, such as 1.0.0+1, before running it.

If your app uses flavors, pass --flavor to both commands and change the artifact path to match, for example build/app/outputs/bundle/<flavor>Release/app-<flavor>-release.aab.

GitLab sets CI=true in every job, so the Shorebird CLI runs non-interactively and never waits for input. A prompt with no safe default fails with an error that names the flag to pass. For example, shorebird patch fails on native code changes unless you pass --allow-native-diffs. See Scripting the Shorebird CLI for the full rules.

Run on tags instead

To release or patch when you push a tag rather than by hand, give every Shorebird job its own rules, including the iOS jobs below. extends merges settings key by key but replaces lists, so a job’s rules replace the manual rule from .shorebird rather than adding to it. In release-android and release-ios:

rules:
  - if: $CI_COMMIT_TAG =~ /^v/

and in patch-android and patch-ios:

rules:
  - if: $CI_COMMIT_TAG =~ /^patch-/

Then remove allow_failure: true from .shorebird. It only keeps the pipeline from waiting on a manual job. On a job that runs on its own, it reports a failed release or patch as passed with warnings, so the tag pipeline looks green when nothing was published.

Protect these tag patterns under "Settings" -> "Repository" -> "Protected tags", and allow only Maintainers to create them. Pipelines for unprotected tags don’t receive your protected variables, and protecting the tags keeps anyone who can push a branch from publishing a release or patch.

iOS

shorebird release ios and shorebird patch ios need Xcode, so iOS jobs run on a macOS runner. On GitLab’s hosted macOS runners, which need a GitLab Premium or Ultimate plan, tags selects the machine and image selects the macOS and Xcode version. Add a job like this next to the Android ones:

release-ios:
  extends: .shorebird
  tags:
    - saas-macos-medium-m1
  # Pin the image so the Xcode version only changes when you change it.
  image: macos-26-xcode-26
  variables:
    FLUTTER_VERSION: '3.47.7'
  script:
    - shorebird release ios --flutter-version="$FLUTTER_VERSION"
  artifacts:
    # The IPA to upload to App Store Connect.
    paths:
      - build/ios/ipa/*.ipa

A patch-ios job takes the same tags and image, with the variables of patch-android and shorebird patch ios --release-version="$RELEASE_VERSION" as its script. The hosted runner docs list the current images.

Every job on a hosted macOS runner starts on a fresh VM with no signing identity, so as written release-ios fails at code signing. Install your distribution certificate and provisioning profile in the job’s script before the Shorebird command, on every run. Use fastlane match, or store a base64-encoded .p12 and profile in CI/CD variables and import them with security. To skip signing on CI, pass --no-codesign as the generic CI guide describes. That builds no IPA, only build/ios/archive/Runner.xcarchive, so change the job’s artifact path to that archive to keep it, then sign and distribute it from Xcode with Manage Version and Build Number unchecked.

On a self-hosted runner on a Mac, use your runner’s tags instead. A shell runner ignores image and uses the Xcode installed on the machine. If it keeps its home directory between jobs, the install script stops when ~/.shorebird already exists, so override before_script to install Shorebird only when it is missing:

before_script:
  - '[ -d "$HOME/.shorebird" ] || curl -fsSL https://shorebird.dev/install.sh |
    bash'
  - export PATH="$HOME/.shorebird/bin:$PATH"

A self-hosted runner needs the certificate and profile too, either installed in the keychain of the user the runner runs as or imported by the job as above.

For an example of a fully automated development workflow, see the Development Workflow Guide.

Development Workflow GuideLearn how to set up a fully automated development workflow with Shorebird.