GitHub Integration

The Setup Shorebird GitHub Action allows you to integrate Shorebird into your existing GitHub Workflows.

Prerequisites

✅ Shorebird CLI is installed on your machine

✅ You are logged into a Shorebird account.

Note

Refer to the getting started instructions for more information.

Quick start

To integrate Shorebird into your CI, use the setup-shorebird action. The setup-shorebird action downloads Shorebird and adds it to the system path.

name: Shorebird Workflow Example

on:
  workflow_dispatch:

jobs:
  example:
    defaults:
      run:
        shell: bash

    runs-on: ubuntu-latest

    steps:
      # Use the setup-shorebird action to configure Shorebird
      - name: 🐦 Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1
        with:
          cache: true # Optionally cache your Shorebird installation

      # Now we're able to use Shorebird CLI in our workflow
      - name: 🚀 Use Shorebird
        run: shorebird --version

In the above workflow, the setup-shorebird action is used to configure Shorebird in CI, and subsequent steps can execute any Shorebird commands.

By default, setup-shorebird installs the latest stable Shorebird release. To pin a CLI release, pass shorebird-version (the version shorebird --version prints, such as 1.6.136). Pinning isn’t recommended: Shorebird’s servers stop accepting old CLI versions over time, so a pinned workflow eventually breaks. To build with a specific Flutter version, pass --flutter-version to shorebird release instead, or flutter-version to the shorebird-release action, as in Create releases.

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 GitHub repository secrets via:

"Settings" -> "Secrets and variables" -> "Actions".

Then, click "New repository secret" and paste your SHOREBIRD_TOKEN:

name: SHOREBIRD_TOKEN
secret: <THE GENERATED SHOREBIRD_TOKEN>

Now the SHOREBIRD_TOKEN can be used in the GitHub workflow to perform authenticated functions such as creating patches 🎉

Sign in with OIDC instead of a stored key

A workflow can sign in with the short-lived OIDC token GitHub issues to each job, so no Shorebird secret is stored in GitHub and nothing has to be rotated. The job signs in as a service account in your organization and can do what that account’s role allows.

Signing in with OIDC needs Shorebird 1.6.129 or newer. On an older CLI, use an API key in SHOREBIRD_TOKEN instead.

Note

Trust rules are available on Business and Enterprise plans. If your organization moves to a plan without them, its existing trust rules keep working and can still be deleted, but new ones cannot be added.

Add a trust rule

1. In the console, open your organization’s Settings and select Service accounts. You need the Admin or Owner role to manage service accounts.
2. Create a service account for the workflow, or pick an existing one. Its role decides what the workflow can do: Developer, the default, can create releases and patches, and App Manager can also create, update, and delete apps. A workflow that signs in with OIDC needs no API key.
3. Under GitHub Actions, click Add workflow and enter:
   • Owner and Repository: where the workflow lives.
   • Workflow file: the path of the workflow file that defines the job, such as .github/workflows/release.yaml. If the job is in a reusable workflow, enter that file, not the workflow that calls it. A reusable workflow from another repository cannot sign in.
   • Environment (recommended): the GitHub environment the job runs in. Requiring one lets you add reviewers or branch restrictions in GitHub before a release can run.
   • Ref pattern (optional): the branches or tags allowed to sign in, such as refs/heads/main or refs/tags/*. Leave it empty to accept any ref.

Trust rules explains how each field is matched. The console then shows your project’s ID, which the workflow needs. It is also the number after /orgs/ in the console’s address bar, and shorebird orgs list lists it (shorebird account orgs before 1.6.135).

Add a trust rule from the command line

shorebird service-accounts (Shorebird 1.6.135 or newer) makes the same changes. Create the service account, then add a trust rule to it. Run these commands signed in with shorebird login and with SHOREBIRD_TOKEN unset. API keys can’t create, change, or delete service accounts, their keys, or their trust rules.

shorebird service-accounts create release --role developer --org-id <project id>
shorebird service-accounts trust add release --org-id <project id> \
  --github-repo acme/app --workflow release.yaml --ref main

A rule needs --ref, --environment, or both, unless you pass --any-ref. A rule for any ref and no environment lets anyone who can push a branch sign in. --ref main means refs/heads/main; to match several refs, give a full ref ending in *, such as refs/tags/*. The command prints the permissions and env the workflow needs. Run shorebird service-accounts trust add --help for its other options.

See Manage service accounts from the CLI for the other commands.

Configure the workflow

The job needs permission to request an OIDC token, the environment the rule names (if any), and SHOREBIRD_PROJECT_ID set to your project’s ID. The ID is not a secret.

name: Shorebird Release

on:
  workflow_dispatch:

jobs:
  release:
    runs-on: ubuntu-latest
    environment: production # Only if your trust rule names an environment
    permissions:
      contents: read
      id-token: write
    env:
      SHOREBIRD_PROJECT_ID: '123' # Your project's ID from the console

    steps:
      - name: 📚 Git Checkout
        uses: actions/checkout@v7

      - name: 🐦 Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1
        with:
          cache: true

      - name: 🚀 Shorebird Release
        run: shorebird release android

Do not set SHOREBIRD_TOKEN in a job that signs in with OIDC. When SHOREBIRD_TOKEN is set, the Shorebird CLI uses it instead. If you are moving a workflow from an API key to OIDC, remove the SHOREBIRD_TOKEN line and the repository secret, then revoke the API key.

If the sign-in is refused, the CLI prints the reason, such as No trust rule matches this workflow. Check that the repository, workflow file, environment and ref of the job match the trust rule. Jobs started by pull_request_target can’t sign in; see when a sign-in is refused.

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. Store it as a base64-encoded repository secret, decode it to a path outside your checkout, and point key.properties at that path before the Shorebird step 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

The simplest way to create a release is using the official Shorebird GitHub Actions:

• Setup Shorebird GitHub Action.
• Shorebird Release GitHub Action.

name: Shorebird Release

on:
  workflow_dispatch:

env:
  SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}

jobs:
  release:
    defaults:
      run:
        shell: bash

    # Use 'macos-latest' if you are building for iOS
    runs-on: ubuntu-latest

    steps:
      - name: 📚 Git Checkout
        uses: actions/checkout@v7

      - name: 🐦 Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1
        with:
          cache: true

      - name: Set up Java
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: 🚀 Shorebird Release
        uses: shorebirdtech/shorebird-release@v1
        with:
          flutter-version: 3.47.9
          platform: android # Use 'ios' (requires runs-on: macos-latest)

flutter-version is required. It’s the Flutter version the release is built with, and every patch to that release is built with it too. Pass a version from shorebird flutter versions list, or latest for the newest stable Flutter version Shorebird supports. shorebird release --help lists the other values.

Tip

The shorebird-release action also outputs the release version:

- name: 🚀 Shorebird Release
  id: shorebird-release
  uses: shorebirdtech/shorebird-release@v1
  with:
    flutter-version: 3.47.9
    platform: android # or 'ios'

- name: 📝 Output Release Version
  run: echo ${{ steps.shorebird-release.outputs.release-version }}

Create patches

name: Shorebird Patch

on:
  workflow_dispatch:

env:
  SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}

jobs:
  patch:
    defaults:
      run:
        shell: bash

    # Use 'macos-latest' if you are patching for iOS
    runs-on: ubuntu-latest

    steps:
      - name: 📚 Git Checkout
        uses: actions/checkout@v7

      - name: 🐦 Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1
        with:
          cache: true

      - name: Set up Java
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'

      # Note: all signing information (key.properties, etc.) must be set up on
      # this runner for `shorebird patch android` to work.
      - name: 🚀 Shorebird Patch
        uses: shorebirdtech/shorebird-patch@v1
        with:
          platform: android # Use 'ios' (requires runs-on: macos-latest)
          release-version: latest
          track: stable

latest patches the most recently updated release. If a newer release might still be in store review, pass the exact version of the release your users have instead; see Patching.

Tip

The shorebird-patch action also outputs the patch number:

- name: 🚀 Shorebird Patch
  id: shorebird-patch
  uses: shorebirdtech/shorebird-patch@v1
  with:
    platform: android # or 'ios'
    release-version: latest
    track: stable

- name: 📝 Output Patch Version
  run: echo ${{ steps.shorebird-patch.outputs.patch-number }}

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.