Skip to content

Update README and testflight instruction files #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Mar 11, 2023
Merged

Update README and testflight instruction files #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
5970b21
Update GitHub build instructions
marionbarker Mar 6, 2023
d214050
Add link to testflight.md in README
marionbarker Mar 6, 2023
89e7ed8
grammar fix
marionbarker Mar 6, 2023
a4871ae
Update for clarity
marionbarker Mar 6, 2023
a3656c6
update GitHub row to Secrets and variables
marionbarker Mar 6, 2023
59e83b0
fix link and add notes
marionbarker Mar 6, 2023
30f4033
fix typo
marionbarker Mar 6, 2023
a917686
Change suggested expiration for GH_PAT to 90 days
marionbarker Mar 8, 2023
e408688
Merge branch 'dev' into wip/testflight-update
marionbarker Mar 10, 2023
cc18196
Update README
marionbarker Mar 10, 2023
8b06fcb
Clarify a comment on testflight instructions
marionbarker Mar 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 17 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,19 @@
# LoopWorkspace

## Clone
The Loop app can be built using GitHub in a browser on any computer or using a Mac with Xcode.

* Non-developers may prefer the GitHub method
* Developers or Loopers who want full build control may prefer the Mac/Xcode method

## GitHub Build Instructions

The GitHub Build Instructions are at this [link](fastlane/testflight.md) and further expanded in [LoopDocs: Browser Build](https://loopkit.github.io/loopdocs/gh-actions/gh-overview/).

## Mac/Xcode Build Instructions

The rest of this README contains information needed for Mac/Xcode build. Additonal instructions are found in [LoopDocs: Mac/Xcode Build](https://loopkit.github.io/loopdocs/build/overview/).

### Clone

This repository uses git submodules to pull in the various workspace dependencies.

Expand All @@ -12,7 +25,7 @@ git clone --branch=<branch> --recurse-submodules https://github.com/LoopKit/Loop

Replace `<branch>` with the initial LoopWorkspace repository branch you wish to checkout.

## Open
### Open

Change to the cloned directory and open the workspace in Xcode:

Expand All @@ -21,13 +34,13 @@ cd LoopWorkspace
xed .
```

## Input your development team
### Input your development team

You should be able to build to a simulator without changing anything. But if you wish to build to a real device, you'll need a developer account, and you'll need to tell Xcode about your team id, which you can find at https://developer.apple.com/.

Select the LoopConfigOverride file in Xcode's project navigator, uncomment the `LOOP_DEVELOPMENT_TEAM`, and replace the existing team id with your own id.

## Build
### Build

Select the "Loop (Workspace)" scheme (not the "Loop" scheme) and Build, Run, or Test.

Expand Down
123 changes: 97 additions & 26 deletions fastlane/testflight.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,104 @@
# Using Github Actions + FastLane to deploy to TestFlight
# Using GitHub Actions + FastLane to deploy to TestFlight

These instructions allow you to build Loop without having access to a Mac. They also allow you to easily install Loop on phones that are not connected to your computer. So you can send builds and updates to those you care for easily, or have an easy to access backup if you run Loop for yourself. You do not need to worry about correct Xcode/Mac versions either. An app built using this method can easily be deployed to newer versions of iOS, as soon as they are available.
These instructions allow you to build Loop without having access to a Mac.

The setup steps are somewhat involved, but nearly all are one time steps. Subsequent builds are trivial. Note that TestFlight requires apple id accounts 13 years or older. 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.
* 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:

* [LoopDocs: GitHub Overview](https://loopkit.github.io/loopdocs/gh-actions/gh-overview/)
* [LoopDocs: GitHub Errors](https://loopkit.github.io/loopdocs/gh-actions/gh-errors/)

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](https://loopkit.github.io/loopdocs/gh-actions/gh-deploy/#install-testflight-loop-for-child).

## Prerequisites

* A [github account](https://github.com/signup). 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](https://developer.apple.com). You may be able to use the free version, but that has not been tested.
* A [GitHub account](https://github.com/signup). 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](https://developer.apple.com).
* 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](https://developer.apple.com/account/resources/certificates/list).
1. Copy the team id from the upper right of the screen. Record this as your `TEAMID`.
1. Go to the [App Store Connect](https://appstoreconnect.apple.com/access/api) interface, click the "Keys" tab, and create a new key with "Admin" access. Give it a name like "FastLane API Key".
1. Record the key id; this will be used for `FASTLANE_KEY_ID`.
1. Copy the Team ID from the upper right of the screen. Record this as your `TEAMID`.
1. Go to the [App Store Connect](https://appstoreconnect.apple.com/access/api) interface, click the "Keys" tab, and create a new key with "Admin" access. Give it the name: "FastLane API Key".
1. Record the issuer id; this will be used for `FASTLANE_ISSUER_ID`.
1. Record the key id; this will be used for `FASTLANE_KEY_ID`.
1. 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.

## Setup Github
1. Create a [new empty repository](https://github.com/new) titled `Match-Secrets`. It should be private.
1. Fork https://github.com/LoopKit/LoopWorkspace into your account.
## 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](https://github.com/settings/tokens/new):
* Enter a name for your token. Something like "FastLane Access Token".
* 30 days is fine, or you can select longer if you'd like.
* 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`.
1. In the forked LoopWorkspace repo, go to Settings -> Secrets -> Actions.

## 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](https://github.com/new) 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.
1. In the forked LoopWorkspace repo, go to Settings -> Secrets and variables -> Actions.
1. 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_KEY_ID`
* `FASTLANE_ISSUER_ID`
* `FASTLANE_KEY_ID`
* `FASTLANE_KEY`
* `GH_PAT`
* `MATCH_PASSWORD` - just make up a password for this
* `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
1. On the left side, select "1. Validate Secrets".
1. On the right side, click "Run Workflow", and tap the green `Run workflow` button.
1. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded.
1. 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.
1. Select "Add Identifiers".
1. Click "Run Workflow", and tap the green button.
1. On the left side, select "2. Add Identifiers".
1. On the right side, click "Run Workflow", and tap the green `Run workflow` button.
1. 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 [Create Loop App in App Store Connect](#create-loop-app-in-app-store-connect).
If you have already built Loop via Xcode using this Apple ID, you can skip on to [Add App Group to Bundle Identifiers](#add-app-group-to-bundle-identifiers).

1. Go to [Register an App Group](https://developer.apple.com/account/resources/identifiers/applicationGroup/add/) on the apple developer site.
1. For Description, use "Loop App Group".
Expand All @@ -56,6 +107,10 @@ If you have already built Loop via Xcode using this Apple ID, you can skip on to

## 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](https://developer.apple.com/account/resources/identifiers/list) on the apple developer site.
1. For each of the following identifier names:
* Loop
Expand All @@ -70,6 +125,18 @@ If you have already built Loop via Xcode using this Apple ID, you can skip on to
1. Click "Confirm".
1. 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](https://developer.apple.com/account/resources/identifiers/list) on the apple developer site.
1. Click on the "Loop" identifier
Expand All @@ -80,7 +147,7 @@ If you have already built Loop via Xcode using this Apple ID, you can skip on to

## Create Loop App in App Store Connect

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

1. Go to the [apps list](https://appstoreconnect.apple.com/apps) on App Store Connect and click the blue "plus" icon to create a New App.
* Select "iOS".
Expand All @@ -95,18 +162,22 @@ You do not need to fill out the next form. That is for submitting to the app sto

## Create Building Certficates

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

## Build Loop!
## Build Loop

1. Click on the "Actions" tab of your LoopWorkspace repository.
1. Select "Build Loop".
1. Click "Run Workflow", select your branch, and tap the green button.
1. On the left side, select "4. Build Loop".
1. On the right side, click "Run Workflow", and tap the green `Run workflow` button.
1. You have some time now. Go enjoy a coffee. The build should take about 20-30 minutes.
1. Your app should eventually appear on [App Store Connect](https://appstoreconnect.apple.com/apps).
1. For each phone/person you would like to support Loop on:
* Add them in [Users and Access](https://appstoreconnect.apple.com/access/users) on App Store Connect.
* Add them to your TestFlight Internal Testing group.

## TestFlight and Deployment Details

Please refer to [LoopDocs: Set Up Users](https://loopkit.github.io/loopdocs/gh-actions/gh-first-time/#set-up-users-and-access-testflight) and [LoopDocs: Deploy](https://loopkit.github.io/loopdocs/gh-actions/gh-deploy/)