Skip to content

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.

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
# Now we're able to use Shorebird CLI in our workflow
- name: πŸš€ Use Shorebird
run: shorebird --version

In the above workflow, we’re using the setup-shorebird action to configure Shorebird in our CI and in subsequent steps we can execute any Shorebird commands.

Currently setup-shorebird only supports the latest stable version of shorebird.

Authentication

Most Shorebird functionality, like creating releases and patches, requires being authenticated. In order to authenticate with Shorebird in CI, you will need to generate a CI token.

Terminal window
shorebird login:ci

You will be prompted to go through a similar OAuth Flow as when using shorebird login, however, shorebird login:ci will not store any credentials on your device. Instead, a Shorebird token will be generated for you to use in CI.

The output should look something like:

$ shorebird login:ci
The Shorebird CLI needs your authorization to manage apps, releases, and patches on your behalf.
In a browser, visit this URL to log in:
https://accounts.google.com/o/oauth2/v2/auth...
Waiting for your authorization...
πŸŽ‰ Success! Use the following token to login on a CI server:
<SHOREBIRD_TOKEN>
Example:
export SHOREBIRD_TOKEN="$SHOREBIRD_TOKEN" && shorebird patch android

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 we can use the SHOREBIRD_TOKEN in our 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
runs-on: ubuntu-latest
steps:
- name: πŸ“š Git Checkout
uses: actions/checkout@v3
- name: 🐦 Setup Shorebird
uses: shorebirdtech/setup-shorebird@v1
- name: πŸš€ Shorebird Release
uses: shorebirdtech/shorebird-release@v0
with:
platform: android # or 'ios'

Create Patches

name: Shorebird Patch
on:
workflow_dispatch:
env:
SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}
jobs:
patch:
defaults:
run:
shell: bash
runs-on: ubuntu-latest
steps:
- name: πŸ“š Git Checkout
uses: actions/checkout@v3
- name: 🐦 Setup Shorebird
uses: shorebirdtech/setup-shorebird@v1
# 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@v0
with:
platform: android # or 'ios'

Fully Automated Workflow Example

A fully automated workflow between your project repository and the CI service can allow developers to trigger deploys of your application just by pushing to the project repository, streamlining the development workflow, which can reduce the chance of error due to repetitive, manual tasks.

There are several ways of setting this up, and in many instances, how it is set up will depending on how the git workflow of your project is structured, or which CI service is used, among other factors.

This guide is a simple proposal for setting up a Fully automated workflow using GitHub Actions. It is intentionally simple so that it can be easily adapted to different requirements and contexts.

Goal

We will be implementing an automation in a project that have the following goals:

  • Any branches created off from main that starts with the prefix release/ will trigger a release at Shorebird.
  • Any additional commits on those branches will trigger patches.

Prerequisites

Before anything, if you don’t have a Shorebird account, be sure to create one at shorebird.dev (Don’t worry, it is free to start have a generous quota that is way more than enough for this guide).

You will also need a GitHub account and a project repository created. If you don’t have an account yet, create one at GitHub, and create a new repository, which for this guide we will call shorebird_automated_workflow.

Getting Started

First thing, lets create a new Flutter project simply by running:

Terminal window
flutter create shorebird_automated_workflow

Be sure to initialize your project as a git repository:

Terminal window
cd shorebird_automated_workflow
git init
git remote add origin <THE_URL_OF_YOUR_REPOSITORY>

Next we need to initialize shorebird in it! Check out the Code Push Getting Started guide for more info.

Setting up GitHub Actions

We provide a collection of official GitHub Actions to help you with the integration. For this guide we will be using shorebird-setup, shorebird-release and shorebird-patch, you can learn more about them at the beginning of this page.

Create a new file at .github/workflows/shorebird_android.yml with the following content:

name: Shorebird Android
on:
push:
branches:
- releases/*
env:
SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}
jobs:
shorebird_android:
defaults:
run:
shell: bash
runs-on: ubuntu-latest
steps:
- name: πŸ“š Git Checkout
uses: actions/checkout@v3
- name: 🐦 Setup Shorebird
uses: shorebirdtech/setup-shorebird@v1
- name: πŸš€ Shorebird Release
if: ${{ github.event.created }}
uses: shorebirdtech/shorebird-release@v0
with:
platform: android
- name: πŸš€ Shorebird Patch
if: ${{ !github.event.created }}
uses: shorebirdtech/shorebird-patch@v0
with:
platform: android

Let’s take a closer look at the above workflow. The workflow will be triggered whenever a push is made to a branch that starts with releases/.

It will then run the clone of the repository and setup the Shorebird CLI.

Next the workflow is divided into two conditional steps. If the push is the one that created the branch, it will trigger a release. Otherwise it will trigger a patch.

That’s it! You should be able to push the changes to your repository and see the workflow running in the actions tab of your repository.

Give it a try! Create a new branch called releases/1.0.0 and push it to your repository:

Terminal window
git checkout -b releases/1.0.0
git push origin releases/1.0.0

That will trigger the action! Once the workflow finishes, check the Shorebird console and you should see a new release for your app.

Next lets make the following change in our app:

class MyApp extends StatelessWidget {
const MyApp({super.key});
// This widget is the root of your application.
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter Demo',
theme: ThemeData(
// This is the theme of your application.
//
// Try running your application with "flutter run". You'll see the
// application has a blue toolbar. Then, without quitting the app, try
// changing the primarySwatch below to Colors.green and then invoke
// "hot reload" (press "r" in the console where you ran "flutter run",
// or simply save your changes to "hot reload" in a Flutter IDE).
// Notice that the counter didn't reset back to zero; the application
// is not restarted.
primarySwatch: Colors.blue,
primarySwatch: Colors.green,
),
home: const MyHomePage(title: 'Flutter Demo Home Page'),
);
}
}

And commit and push it!

Terminal window
git add .
git commit -m "Change primarySwatch to green"
git push origin releases/1.0.0

That will trigger the action again, but now a patch will be created πŸŽ‰.

Summary

As mentioned, the workflow presented here is just one way of setting up a fully automated workflow. Feel free to adapt it based on your teams needs and existing processes.

Some ways the workflow can be expanded are:

  • Instead of directly committing to the branch after the release was made. Developers would land their changes and fixes on their main branch, and then cherry-pick it to the release branch!
  • Both shorebird-release and shorebird-patch returns the version/patch-number created. The workflow could be expanded in order for tags to be created in the repository, using the version number returned allowing snapshots of the code to be easily identified.

See this workflow in action by checking out our Time Shift App.

Thank you for reading this guide! If you have any questions or suggestions, feel free to reach out to us at our Discord.