---
title: "GitLab Integration"
description: "Integrate Shorebird into your GitLab CI/CD pipelines"
---

This guide shows you how to create Shorebird releases and patches from [GitLab CI/CD](https://docs.gitlab.com/ci/) 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](https://console.shorebird.dev):

[Watch the video: Create a Shorebird API key](/videos/create-api-key.mp4)

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.

Use a service account for shared CI

A personal API key stops working if its owner’s account is deleted. A [service account](/account/service-accounts/) 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](/code-push/ci/github/#sign-in-with-oidc-instead-of-a-stored-key) 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](https://docs.flutter.dev/deployment/android#sign-the-app), or the [Shorebird version of them](/flutter-concepts/releasing-flutter-apps/android#step-3-configure-signing-in-gradle).

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](/code-push/ci/scripting) 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](https://docs.gitlab.com/ci/runners/hosted_runners/macos/), 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](/code-push/ci/fastlane#using-fastlane-on-ci), 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](/code-push/ci/generic#build-without-code-signing-in-restricted-environments) 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](https://docs.gitlab.com/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 Guide](/code-push/guides/development-workflow)Learn how to set up a fully automated development workflow with Shorebird.