Skip to content

Latest commit

 

History

History
183 lines (131 loc) · 10.3 KB

testflight.md

File metadata and controls

183 lines (131 loc) · 10.3 KB
Raw

Using GitHub Actions + FastLane to deploy to TestFlight

These instructions allow you to build Loop without having access to a Mac.

  • You can install Loop on phones via TestFlight that are not connected to your computer
  • You can send builds and updates to those you care for
  • You can install Loop on your phone using only the TestFlight app if a phone was lost or the app is accidentally deleted
  • You do not need to worry about specific Xcode/Mac versions for a given iOS

The setup steps are somewhat involved, but nearly all are one time steps. Subsequent builds are trivial. Your app must be updated once every 90 days, but it's a simple click to make a new build and can be done from anywhere. The 90-day update is a TestFlight requirement, which can be automated.

There are more detailed instructions in LoopDocs for using GitHub for Browser Builds of Loop, including troubleshooting and build errors. Please refer to:

Note that installing with TestFlight, (in the US), requires the Apple ID account holder to be 13 years or older. For younger Loopers, an adult must log into Media & Purchase on the child's phone to install Loop. More details on this can be found in LoopDocs.

Prerequisites

  • A GitHub account. The free level comes with plenty of storage and free compute time to build loop, multiple times a day, if you wanted to.
  • A paid Apple Developer account.
  • Some time. Set aside a couple of hours to perform the setup.

Save 6 Secrets

You require 6 Secrets (alphanumeric items) to use the GitHub build method and if you use the GitHub method to build more than Loop, e.g., Loop Follow or LoopCaregiver, you will use the same 6 Secrets for each app you build with this method. Each secret is indentified below by ALL_CAPITAL_LETTER_NAMES.

  • Four Secrets are from your Apple Account
  • Two Secrets are from your GitHub account
  • Be sure to save the 6 Secrets in a text file using a text editor
    • Do NOT use a smart editor, which might auto-correct and change case, because these Secrets are case sensitive

Generate App Store Connect API Key

This step is common for all GitHub Browser Builds; do this step only once. You will be saving 4 Secrets from your Apple Account in this step.

  1. Sign in to the Apple developer portal page.
  2. Copy the Team ID from the upper right of the screen. Record this as your TEAMID.
  3. Go to the App Store Connect interface, click the "Keys" tab, and create a new key with "Admin" access. Give it the name: "FastLane API Key".
  4. Record the issuer id; this will be used for FASTLANE_ISSUER_ID.
  5. Record the key id; this will be used for FASTLANE_KEY_ID.
  6. Download the API key itself, and open it in a text editor. The contents of this file will be used for FASTLANE_KEY. Copy the full text, including the "-----BEGIN PRIVATE KEY-----" and "-----END PRIVATE KEY-----" lines.

Create GitHub Personal Access Token

Log into your GitHub account to create a personal access token; this is one of two GitHub secrets needed for your build.

  1. Create a new personal access token:
    • Enter a name for your token, use "FastLane Access Token".
    • Change the selection to 90 days.
    • Select the repo permission scope.
    • Click "Generate token".
    • Copy the token and record it. It will be used below as GH_PAT.

Make up a Password

This is the second one of two GitHub secrets needed for your build.

The first time you build with the GitHub Browser Build method for any DIY app, you will make up a password and record it as MATCH_PASSWORD. Note, if you later lose MATCH_PASSWORD, you will need to delete and make a new Match-Secrets repository (next step).

Setup GitHub Match-Secrets Repository

The creation of the Match-Secrets repository is a common step for all GitHub Browser Builds; do this step only once. You must be logged into your GitHub account.

  1. Create a new empty repository titled Match-Secrets. It should be private.

Once created, you will not take any direct actions with this repository; it needs to be there for the GitHub to use as you progress through the steps.

Setup GitHub LoopWorkspace Repository

  1. Fork https://github.com/LoopKit/LoopWorkspace into your account.
  2. In the forked LoopWorkspace repo, go to Settings -> Secrets and variables -> Actions.
  3. For each of the following secrets, tap on "New repository secret", then add the name of the secret, along with the value you recorded for it:
    • TEAMID
    • FASTLANE_ISSUER_ID
    • FASTLANE_KEY_ID
    • FASTLANE_KEY
    • GH_PAT
    • MATCH_PASSWORD

Validate repository secrets

This step validates most of your six Secrets and provides error messages if it detects an issue with one or more.

  1. Click on the "Actions" tab of your LoopWorkspace repository and enable workflows if needed
  2. On the left side, select "1. Validate Secrets".
  3. On the right side, click "Run Workflow", and tap the green Run workflow button.
  4. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded.
  5. The workflow will check if the required secrets are added and that they are correctly formatted. If errors are detected, please check the run log for details.

Add Identifiers for Loop App

  1. Click on the "Actions" tab of your LoopWorkspace repository.
  2. On the left side, select "2. Add Identifiers".
  3. On the right side, click "Run Workflow", and tap the green Run workflow button.
  4. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded.

Create App Group

If you have already built Loop via Xcode using this Apple ID, you can skip on to Add App Group to Bundle Identifiers.

  1. Go to Register an App Group on the apple developer site.
  2. For Description, use "Loop App Group".
  3. For Identifier, enter "group.com.TEAMID.loopkit.LoopGroup", subsituting your team id for TEAMID.
  4. Click "Continue" and then "Register".

Add App Group to Bundle Identifiers

Note 1 - If you previously built with Xcode, the Names listed below may be different, but the Identifiers will match. A table is provided below the steps to assist. The Add Identifier Action that you completed above generates 6 identifiers, but only 4 need to be modified as indicated in this step.

Note 2 - Depending on your build history, you may find some of the Identifiers are already configured - and you are just verifying the status; but in other cases, you will need to configure the Identifiers.

  1. Go to Certificates, Identifiers & Profiles on the apple developer site.
  2. For each of the following identifier names:
    • Loop
    • Loop Intent Extension
    • Loop Status Extension
    • Small Status Widget
  3. Click on the identifier's name.
  4. On the "App Groups" capabilies, click on the "Configure" button.
  5. Select the "Loop App Group"
  6. Click "Continue".
  7. Click "Save".
  8. Click "Confirm".
  9. Remember to do this for each of the identifiers above.

Table with Name and Identifier for Loop 3

NAME IDENTIFIER
Loop com.TEAMID.loopkit.Loop
Loop Intent Extension com.TEAMID.loopkit.Loop.Loop-Intent-Extension
Loop Status Extension com.TEAMID.loopkit.Loop.statuswidget
Small Status Widget com.TEAMID.loopkit.Loop.SmallStatusWidget
WatchApp com.TEAMID.loopkit.Loop.LoopWatch
WatchAppExtension com.TEAMID.loopkit.Loop.LoopWatch.watchkitextension

Add Time Sensitive Notifications to Loop App ID

  1. Go to Certificates, Identifiers & Profiles on the apple developer site.
  2. Click on the "Loop" identifier
  3. Scroll down to "Time Sensitive Notifications"
  4. Tap the check box to enable Time Sensitive Notifications.
  5. Click "Save".
  6. Click "Confirm".

Create Loop App in App Store Connect

If you have created a Loop app in App Store Connect before, you can skip this section.

  1. Go to the apps list on App Store Connect and click the blue "plus" icon to create a New App.
    • Select "iOS".
    • Select a name: this will have to be unique, so you may have to try a few different names here, but it will not be the name you see on your phone, so it's not that important.
    • Select your primary language.
    • Choose the bundle ID that matches com.TEAMID.loopkit.Loop, with TEAMID matching your team id.
    • SKU can be anything; e.g. "123".
    • Select "Full Access".
  2. Click Create

You do not need to fill out the next form. That is for submitting to the app store.

Create Building Certficates

  1. Go back to the "Actions" tab of your LoopWorkspace repository in GitHub.
  2. On the left side, select "3. Create Certificates".
  3. On the right side, click "Run Workflow", and tap the green Run workflow button.
  4. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded.

Build Loop

  1. Click on the "Actions" tab of your LoopWorkspace repository.
  2. On the left side, select "4. Build Loop".
  3. On the right side, click "Run Workflow", and tap the green Run workflow button.
  4. You have some time now. Go enjoy a coffee. The build should take about 20-30 minutes.
  5. Your app should eventually appear on App Store Connect.
  6. For each phone/person you would like to support Loop on:
    • Add them in Users and Access on App Store Connect.
    • Add them to your TestFlight Internal Testing group.

TestFlight and Deployment Details

Please refer to LoopDocs: Set Up Users and LoopDocs: Deploy