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.

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.

Authentication

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.

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 🎉

Create releases

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

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:
          platform: android # Use 'ios' (requires runs-on: macos-latest)

The shorebird-release action also outputs the release version:

- name: 🚀 Shorebird Release
  id: shorebird-release
  uses: shorebirdtech/shorebird-release@v1
  with:
    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)

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'

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