Public Flipper Releases
This document outlines how Flipper releases work on GitHub.
Kick-Off
A release is kicked off by a special commit that has a subject with the format
Flipper Release vX.Y.Z
, e.g. 4fa2c9761.
This is triggered from a bot within Facebook that runs prepare-release.sh but the only thing special about the commit is its subject line. Anyone could run the script and would kick off the remaining jobs once the commit lands in main.
The commit bumps the version of Flipper Desktop as well as various SDK components and libraries that are to be published to npm and other package repositories.
Importantly, it is immediately followed by a "SNAPSHOT" commit (e.g. 02a56da3f) which sets
the version of our Java dependencies to X.Y.(Z+1)-SNAPSHOT
(that's the
patch version incremented by one and a -SNAPSHOT
suffix appended).
That's a weird Maven-ism which allows us to continuously publish snapshot
releases from the main branch.
Desktop Release
The release process for the desktop app is entirely driven by GitHub Actions.
The entry point is the release.yml workflow
which is triggered by changes to the desktop/package.json
file on the main branch.
GitHub Actions has a limitation we need to work around here: It allows push events to as triggers for a workflow, but not individual commits. This requires us to first scan through all potential commits of a push to identify commits that match the aforementioned versioning schema. This is done through a custom action.
Only if this action is successful, the remaining steps are taken which
- Check out the versioning commit.
- Create a git tag for it.
- Create a GitHub release for the tag.
- Build releases for Linux, Mac and Windows.
- Upload all these releases to temporary storage.
- Download the release artifacts and attach them to the GitHub release.
- Dispatch to separate workflows for publishing Cocoapods and npm packages (see below).
iOS Release
iOS releases are run in GitHub Actions but exist as a separate workflow. They can be triggered in three ways:
- When a tag is pushed.
- By manually triggering the workflow (see below).
- Through a
dispatch_workflow
event which is issued as a last step of the desktop release process.

The workflow follows the default Cocoapods update procedure, bumps and published both the Flipper and FlipperKit pod and finally creates a pull request containing the updated references. This PR must be manually merged.
Authentication is managed through the secret environment variable COCOAPODS_TRUNK_TOKEN
.
npm releases
The JavaScript libraries published as part of a Flipper release closely follow the iOS release procedure. Same as before, it is a workflow that is triggered by one of the three events, which should in all but exceptional circumstances be a dispatch event. The workflow is defined in publish-npm.yml.
From there, we use a script to
bump the versions of our Yarn workspaces, and publish all public packages (flipper
, flipper-babel-transformer
, ...)
and our React Native bindings.
The authentication to npm is managed by a secret environment variable called FLIPPER_NPM_TOKEN
.
Android Release
Android has three types of jobs currently running. The snapshot
job is an
outlier in that it still runs on CircleCI. This gives us some additional
capacity as these jobs can take quite a while and the occasional failure
due to timeouts or network errors isn't a dealbreaker.
The three jobs are:
- The
snapshot
job runs on every commit on the main branch and publishes "SNAPSHOT" releases to Maven Central. It runs on CircleCI. - The
publish-android
job is usually triggered by adispatch_workflow
event. It uploads our Java artifacts to Maven Central and attaches the Android sample app to the release page on GitHub. It runs on GitHub Actions. - The
android-sample
job runs on every push and open pull request. It builds the sample and tutorial apps and uploads the sample APK as artifact for easy debugging and testing.
CircleCI Configuration
The Android snapshot build is run on
CircleCI
and configured in
.circleci/config.yml
There are two potential points for breakage:
- The base image used in the build instructions refers to a specific SDK version and requires occasional updating.
- The platform installation through the
sdkmanager
tool of the Android SDK may require additional SDKs or NDKs to be installed if they're not part of the base image.
One non-obvious aspect is that of authentication for uploads. The repository contains a symmetrically encrypted copy of our credentials to Sonatype (for Maven Central). The snapshot release script decodes the file on the fly by using a secret Circle CI exposes through an environment variable.
GitHub Action Workflow
As with the iOS release before, the workflow for Android releases is triggered by three types of events:
- When a tag is pushed.
- By manually triggering the workflow.
- Through a
dispatch_workflow
event which is issued as a last step of the desktop release process.
In normal circumstances, the third event will kick off an Android release build.
The workflow is defined in publish-android.yml
.
We first install two NDK versions that are required by our dependencies. To publish release artifacts
(i.e. non-SNAPSHOT
artifacts), Maven Central requires them to be signed with a GnuPG key. The
only requirement about the key itself is, that it needs to be exported to a Keyserver. Ours
is published to the Ubuntu Keyserver.
To publish your own key, run
gpg --send-keys --keyserver keyserver.ubuntu.com <KEY_ID>
For the initial setup, the secret keyring was exported as gpg2 --export-secret-keys <secret_key_id> | base64
and stored
as secret on GitHub with the name GPG_KEY_CONTENTS
. As part of the workflow, it is written to disk after reversing the base64 encoding.
The key id and key password are subsequently stored in the gradle.properties
along with the path to the key. Paths here need to be
absolute, otherwise Gradle will look them up relative to the sub-projects (android/
, android/sample
, ...).
Maven Central is managed by Sonatype. To sign up follow their guide which
involves creating a JIRA account and opening an issue to apply for the com.facebook
namespace. You will need
to find an existing member of this namespace to vouch for you. While this is a lot, it ensures that nobody
from outside the organisation can publish under our name.
The publish
(previously uploadArchives
) gradle task uses the OSSRH Sonatype Nexus credentials to upload all Flipper Java artifacts. That
includes the core SDK as well as our plugins. The credentials are not your login to Nexus, but the user tokens
you can get from your profile.
This is followed by the closeAndReleaseRepository
gradle task, which is part of the
gradle-maven-publish-plugin
. It uses the credentials
to identify a "staging repository" and automatically close it. This staging repository is identified by the
SONATYPE_STAGING_PROFILE
property. Sonatype usually requires people to manually go to a web UI, verify that a given release is
complete and click some buttons. The plugin aims to do this for you.
Troubleshooting
There are a few parts which can go wrong here.
- Upload fails: Maven Central is (at the time of writing) overloaded with projects migrating from JCenter. The upload task attempts to retry but it can still time out. Manually re-running the job through the GitHub UI should do the trick.
- Closing fails: Same as before, this can happen because of timeouts.
- Retrying to close fails because of duplicate staging repositories: This is particularly annoying because you cannot fix this through automation. It happens when artifacts are uploaded multiple times and now more than one staging repository exists. You must first drop (not close or release) the existing ones before restarting the job. To do this, go to Staging Repositories, select the open repositories and click "Drop".
- NDK mismatch: If Gradle complains about a missing NDK, this usually indicates that a dependency
has a hard requirement on a particular NDK. You can add it to the list in the
sdkmanager
command. - Artifacts not available: Maven Central syncs with a delay of sometimes a few hours. You can check directly on the Maven2 main server if the artifacts with the new version number are uploaded.