Skip to main content

Building the App

Android​

Android builds for the main and release/ branches are automated, using our CI Pipelines in Gitlab.

Internal testing builds are uploaded automatically to our internal android builds page.

Release builds, ones we make available to our customers, are uploaded manually to the Google Play Store. This will be automated at a later stage.

How are Android builds done?​

Android builds are creating using two scheduled pipelines that run daily, Monday through Friday, in 3 hour cycles: 9am, 12pm, 3pm and 6pm.

These scheduled pipelines are run on the main branch and on the release/ branch only. If you need to make a build for a different branch, see the next section.

The release/ branch pipeline has to be manually updated each time we want to change which release branch is being built, e.g. release/8-20-0 -> release/8-20-1.

Once a build is done - the build artifacts (APK files), will be uploaded automatically to our internal android builds page.

Creating a one-off build of the Android app for local testing​

If your team needs to test or showcase some feature on a development branch, without first merging to main, you can create a one-off build by running a new pipeline for that branch specifically.

You can do this from this page in Gitlab, or via the "Run Pipeline" button in the top right corner of the main Pipelines page.

Once you start a new pipeline on your chosen branch, all of the pipeline stages will run automatically, except for the upload stage. Uploading for these pipelines is set to be manual as actually releasing the build can be optional. Sometimes you may want to run a pipeline on your branch just to check that everything passes tests and builds correctly (e.g. for CI changes).

If the build jobs succeed, the artifacts (APK files) will be available from the relevant pipeline build job in the right-hand sidebar under "Job Artifacts". You can download a zip file to your machine which will contain the APK(s).

NB: If you have run this pipeline on a branch other than main or release/* you cannot successfully run the "upload" job, so as mentioned you'll need to download the artifact from the build job itself.

Production builds​

The production builds are done manually, by taking the previously build artifact from a scheduled release/ branch pipeline, and uploading it manually to the Google Play Store's dev portal.

[Section still under construction - see @john.hatvani for more details regarding this process].

iOS​

We do not currently have a process for creating iOS builds automatically. We are exploring ways we could do this, but right now, if you need or want to make a build of the iOS app, you'll have to do so manually, following the instructions below. (Updated 14/02/2022)

How are iOS builds done?​

At the moment, iOS builds are done entirely manually, by SSHing into a Mac Mini in our Brisbane office, and then running fastlane scripts on said machine, which will then create the iOS builds and upload them to Apple's App Store Connect website. To access App Store Connect, you will need to create an Apple account with your work email and then sign up to the Apple Developer Program through your work-based Apple ID, and get someone from the App Core team to link your account with our apps.

A note on App Store Connect and version numbers​

Apple is a bit quirky when it comes to what is considered a valid version number and build number. If you are creating or modifying the app's version number, or creating a new build (which will require a new build string, which you pass to fastlane when creating a new build for UAT and PROD), make sure that they fit the below requirements.

Note: Always check the source links if you run into any issues, in case the below text has fallen out of date with the source documentation.

Version Numbers​

The version number is a two-period-separated list of integers, as in 4.5.2. The first integer represents a major revision, the second a minor revision, and the third a maintenance release. The version number is shown on the App Store and that version should match the version number you enter later in App Store Connect. For details on possible values, see CFBundleShortVersionString.

From this page on the App Store Connect Help website.

Build Strings​

The build string represents an iteration (released or unreleased) of the bundle and is also a two-period-separated list of integers, as in 1.2.3. For Mac apps, the user can view the version number and build string in the About window. For details on possible values, see CFBundleVersion.

From this page on the App Store Connect Help website.

Note: We often just refer to these as "build numbers", but this is the technically correct term.

Picking the right build string when building a new bundle of the app​

For a new app version (never built before)​

Ensure you are actually checked out on the correct branch for the new version you want to make a first time build for, e.g. release/10-0-0, in the terminal of machine being used for the iOS builds. Once that is done, given that this is a brand new version, you should be giving it 0 and 1 as the build strings to be used for the first two builds, one for UAT and one for PROD, for each brand of the app you're building.

Note: remember to check that the MARKETING_VERSION of the app has been updated as well and matches the version you're trying to build for, as this is what Xcode will look for when creating the bundle. See this section for more info.

For a new build (of an existing version)​

The main rule with builds for iOS is that build strings need to be incremental. As they are simple integers, you just need to look at the previous two builds that have been made successfully and pass the next two numbers to fastlane when you're making the builds.

e.g. if the last two builds were 49 and 50, then you will be giving the following numbers to the build command: ~/bin/buildios 51 52.

How to build an iOS app bundle, manually​

First, you will need to SSH into our Mac Mini used to make these builds (located in the Brisbane office), by going to the IP address the our Mac Mini iOS builds machine, stored in the shared 1Password vault. The login details are in our shared 1Password vault under 'iOS Builds Mac Mini'. The password to connect and log into the Mac Mini are the same.

NOTE: If working remotely, connect to our 'Ladbrokes Australia AU VPN (L2TP)' VPN network. If you don't have the VPN setup, contact Desktop Support.

Before you log in, check that you don't see a message saying Your screen is being observed. This means that someone else is already logged in, and probably making a build. Check with people in #chapter-native-apps to make sure you aren't booting anyone inadvertently.

Once logged in, you should see three windows:

  • Terminal, where you will be running the commands needed for the build.
  • XCode, required to upload the build archives to Test Flight, and,
  • VS Code, showing you the build instructions, and the script used to make the build itself, in case you need to change anything.

In case the windows/instructions are missing...

Click to see the build instructions
Whatever instructions are on the Mac Mini take priority, and should be considered the most up to date version. If the instructions here and on the Mac Mini are different, notify someone in the App Core team to update this documentation.

Manual iOS builds:

There should be three windows open on this Mac Mini

  • A Terminal window, open at the react-native/ios folder
  • XCode, with the 'Organizer' menu open
  • This VS Code window with two tabs open
    • The instructions you're reading right now
    • The fastlane buildios script

In case some of these windows are not open, go ahead and open them:

  • Open Terminal, and cd into the react-native/ios.
  • Open XCode, go to the 'Window' menu in the Mac top bar, and open the 'Organizer'.
  • Follow the build instructions below.

Build Steps:

  1. Check out the branch that you want to create a build for, e.g. git checkout release/8-24-0
  2. Make sure working dir is clean git reset --hard HEAD
  3. Make sure working dir is up to date (and on the correct branch): git pull
  4. Make sure you are in the ios/ sub-directory
  5. Install project dependencies yarn setup (this will run 3 commands sequentially: yarn && ./postinstall.sh && yarn pod).
  6. Run ~/bin/buildios <1> <2>, where <1> is the UAT build number, and <2> is the PROD (live release) build number.
    1. Apple will only accept incrementally larger build numbers.
    2. NOTE: UAT goes by ODD numbers, Live goes by EVEN Numbers.
    3. For the current build numbers for a given version, see Test Flight.
  7. Hopefully it doesn't break.
  8. Open Xcode (if it is not already)
    1. click window in the top bar
    2. click organizer
  9. Click the dropdown in the top right to change brands to release
  10. Click on the version you would like to release
  11. Click Distribute App
  12. Select App Store Connect
  13. Select Upload
  14. Select All options
    1. Go through each drop down selecting each option (choose the eligible option)
  15. Click Upload
  16. Pray nothing goes wrong

NOTE: All passwords required for building/signing/uploading are in the keychain, and should be recognised by fastlane.


Making a one-off build for testing​

Production builds - running locally on plugged in device​

Sometimes you need to test changes on a Production bundle, with all debug code removed, running the same code that a customer would be running from the App Store.

To build and run a bundle on your own iOS device instead of the simulator, see the React Native documentation for running the app on a connected device for the official guide.

When building Production bundles, you'll be using a different set of build certificates in Xcode - @john.hatvani may need to provide you with these. Make sure you select the correct target to build, i.e. <brand> - Release, otherwise you will be building the usual debug bundle that points to UAT, that we use for development.

Production builds - via TestFlight​

If you need to have multiple people test or demo WIP features or changes on a non-release branch, by using TestFlight, you will have to build and upload a new bundle the same way that we create all our other bundles when pushing them to TestFlight prior to deploying them onto the App Store.

Note that this is a bit tricky as there is no nice way to signal that a particular version of build is being used for a specific test by providing a custom version or build number like 8.28.0-test-feature or 8.28.0(test-feature)

You will either have to use an existing version, or create a brand new one.

If using an existing version, ideally the version that your feature is meant to eventually release on, and simply create new builds for said version, but ensure that you enter details in the build's "Test Details", stating that the particular build is being used to test a feature or change not yet merged with the rest of the code which will be released. This note will appear to testers in TestFlight when they download the particular build for the version.

If using a brand new version, you should create a patch version of the current one, as it will be the equivalent of a hot-fix, and if needed a new one can easily always be made to supersede it - whereas major and minor versions are slated for planned releases. e.g. If the current version being worked on is 10.0.0, and you want to use a new version to make a test bundle for your non-release feature or change to be tested in TestFlight, then make a new version 10.0.1, or if one already exists, e.g. 10.0.2 and so on.

If in doubt, opt for creating a new patch version, over simply creating a new build for an existing version.