Release Instructions

Some assumptions:

  • master is the default branch and is production-ready
  • commits made to master are built and pass in buddybuild
  • production is our public release branch and may not match master
  • ideally, production will perfectly reproduce master
  • but if master is in an un-releasable state, we cherry-pick commits to this branch
  • this is an exception rather than the preferred maintenance method
  • all master and production builds are sent to App Store Connect, with the same buddybuild build number
  • App Store Connect has "internal" testers (mobile devs, product integrity)
  • thus, App Store Connect and TestFlight can have "external" testers which we add manually
  • currently, no plans exist for "external" users to include anyone outside of Mozilla

Distributing Builds through buddybuild (branch / release)

all commits on all branches and pull requests are automatically built

  1. Push to the git branch available on and open a pull request
  2. Open buddybuild from a mobile device and browse to the build
  3. Alternatively, add an email address to the "Deployments" email list(s)
  4. this is expected to be a small group of contributors and Mozillians

Preparing a Release (for TestFlight or App Store)

  1. Update the release notes under docs/
  2. create a pull request to collaborate and get approval
  3. determine the next build number and include it in release notes
  4. merge the release notes to master branch
  5. this will result in a release build matching the build number provided
  6. Create and merge a pull request from master to production so it tracks the release
  8. Create a tag from production matching the format:
  9. for example: 1.2.1399 is major version 1.2, (buddybuild) build 1399
  10. for example: is major version 1.3 with 1 patch release, (buddybuild) build 1624
  11. push the tag to GitHub and create a corresponding "Release" on
  12. copy the release notes to the "Release" on GitHub
  13. download the .ipa from buddybuild and attach it to the Release on GitHub
  14. Hopefully by now the build has been uploaded to App Store Connect
  15. Browse to App Store Connect and continue the "Distributing..." instructions
  16. Download and unzip dSYM build artifact from buddybuild
  17. Upload dSYM files to Sentry using sentry-cli using sentry instructions

In Case of Emergency (Release)

similar to above, but requires explicit cherry-pick commits on production branch when master branch is not in a release-able state

  1. Merge the emergency changes or fixes or features to default master branch as usual
  2. Update the release notes
  3. Create and merge a pull request up to and including the last release-able commit on master to production
  4. Then git cherry-pick each additional commit from master to be included in the release
  5. thus skipping or avoiding the non-release-able commits
  6. Push the resulting production branch to
  7. Create a tag from production matching the format:
  8. for example: git tag -a -s -m "1.3.1 (Build 1624)"
  9. Push the tag to GitHub and create a corresponding "Release" on
  10. copy the release notes to the "Release" on GitHub
  11. Browse to buddybuild and find the desired production branch build to distribute
  12. download the .ipa from buddybuild and attach it to the Release on GitHub
  13. From the buddybuild's build "Deploy" tab, select the "Upload to App Store Connect" link
  14. Browse to App Store Connect to find the build and continue the "Distributing..." instructions

Distributing Builds through TestFlight (release)

all master and production branch builds are automatically uploaded from buddybuild to App Store Connect.

NOTE: if for some reason buddybuild does not deploy a build to App Store Connect, download the full App Store Connect .ipa from buddybuild and use the "Application Loader" app to manually upload it yourself.

  1. Browse to TestFlight > Builds > iOS in App Store Connect
  2. Find the desired build number to distribute
  3. Provide export compliance responses

    Does your app use encryption? Select Yes even if your app only uses the standard encryption in iOS and macOS.


Does your app qualify for any of the exemptions provided in Category 5, Part 2 of the U.S. Export Administration Regulations?

Yes (c) Limited to authentication, digital signature, or the decryption of data or files

  1. Once provided, this makes the build immediately available to "internal" App Store Connect users
  2. Copy the release notes for this release and add them to the "Test Details"
  3. Add at least one other "Group" of "external" testers to the build
  4. after review, this will make it available for all those "external" testers
  5. example: "lockbox-dev" which includes our other non-App Store Connect engineers
  6. example: "Product" which includes other product and content Mozillians
  7. example: "Cohort A" which includes the first round of volunteers to test

Distributing through the App Store (release)

  1. Browse to the App Store section in App Store Connect
  2. Confirm the "App Information" details are accurate and complete
  3. Confirm the "Pricing and Availability" details are accurate and complete
  4. Browse to the "iOS App" section to "Prepare for Submission"
  5. provide the version information (keywords, URLs, promotional screenshots)
  6. select the corresponding build number for the App Store release
  7. set the release instructions (manually, immediately, on a date)
  8. Save and "Submit for Review"
  9. Wait for notification the app is ready for release and then release it (manually, on schedule and/or phased)

NOTE: brand new apps may take up to 2 or more hours to appear throughout the App Store whereas existing app (updates) can appear within an hour. Schedule accordingly!

Taking screenshots for new releases

Screenshots are automated via Fastlane. To get Fastlane, run brew cask install fastlane. From there, you will be able to run fastlane snapshot in the root directory of the project to run the screenshot task.

Configuration: - [languages] Update / add desired locales to fastlane/Snapfile - [devices] Update / add desired device sizes to fastlane/Snapfile - text size Update the CONTENT_SIZE variable in LockboxXCUITests/BaseTestCase.swift

Updating the version

Once a version has been merged or released, the major app version should be increased

  • Update the value in Common/Resources/Info.plist for the Lockbox app, for example from 1.2 to 1.3
  • Also update the value in CredentialProvider/Info.plist for the extension to the exact same version
  • Be sure to submit the new build to TestFlight Beta App Review ASAP so that review doesn't prevent external user testing