|
|
@@ -2,7 +2,7 @@
|
|
|
|
|
|
These instructions allow you to build Trio without having access to a Mac.
|
|
|
|
|
|
-* You can install Trio on phones via TestFlight that are not connected to your computer
|
|
|
+* You can install Trio on phones using TestFlight that are not connected to your computer
|
|
|
* You can send builds and updates to those you care for
|
|
|
* You can install Trio 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
|
|
|
@@ -16,17 +16,20 @@ These instructions allow you to build Trio without having access to a Mac.
|
|
|
>
|
|
|
> It also creates an alive branch, if you don't already have one. See [Why do I have an alive branch?](#why-do-i-have-an-alive-branch).
|
|
|
>
|
|
|
+> The [**Optional**](#optional) section provides instructions to modify the default behavior if desired. >
|
|
|
|
|
|
## Introduction
|
|
|
|
|
|
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.
|
|
|
|
|
|
-Note that TestFlight requires apple id accounts 13 years or older. This can be circumvented by logging into Media & Purchase on the child's phone with an adult's account. More details on this can be found in [LoopDocs](https://loopkit.github.io/loopdocs/gh-actions/gh-deploy/#install-testflight-loop-for-child).
|
|
|
+Note that installing with TestFlight requires the Apple ID account holder for the phone be 13 years or older (age varies with country). This can be circumvented by logging into Media & Purchase on the child's phone with an adult's account. More details on this can be found in [LoopDocs](https://loopkit.github.io/loopdocs/gh-actions/gh-deploy/#install-testflight-loop-for-child).
|
|
|
|
|
|
This method for building without a Mac was ported from Loop. If you have used this method for Loop or one of the other DIY apps (Loop Caregiver, Loop Follow, Xdrip4iOS), some of the steps can be re-used and the full set of instructions does not need to be repeated. This will be mentioned in relevant sections below.
|
|
|
|
|
|
There are more detailed instructions in LoopDocs for doing Browser Builds of Loop and other apps, including troubleshooting and build errors. Please refer to [LoopDocs](https://loopkit.github.io/loopdocs/gh-actions/gh-other-apps/) for more details.
|
|
|
|
|
|
+If you build multiple apps, you may want to use a free *GitHub* organization. Please refer to [LoopDocs: Use a *GitHub* Organization Account](https://loopkit.github.io/loopdocs/gh-actions/gh-other-apps/#use-a-github-organization-account).
|
|
|
+
|
|
|
## Prerequisites
|
|
|
|
|
|
* A [github account](https://github.com/signup). The free level comes with plenty of storage and free compute time to build Trio, multiple times a day, if you wanted to.
|
|
|
@@ -43,6 +46,8 @@ You require 6 Secrets (alphanumeric items) to use the GitHub build method and if
|
|
|
* 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
|
|
|
|
|
|
+Refer to [LoopDocs: Make a Secrets Reference File](https://loopkit.github.io/loopdocs/gh-actions/gh-first-time/#make-a-secrets-reference-file) for a handy template to use when saving your Secrets.
|
|
|
+
|
|
|
## 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.
|
|
|
@@ -56,7 +61,7 @@ This step is common for all GitHub Browser Builds; do this step only once. You w
|
|
|
|
|
|
## Create GitHub Personal Access Token
|
|
|
|
|
|
-If you have previously built another app using the "browser build" method, you can can re-use your previous personal access token (`GH_PAT`) and skip this step.
|
|
|
+If you have previously built another app using the "browser build" method, you use the same personal access token (`GH_PAT`), so skip this step.
|
|
|
|
|
|
Log into your GitHub account to create a personal access token; this is one of two GitHub secrets needed for your build.
|
|
|
|
|
|
@@ -71,18 +76,14 @@ Log into your GitHub account to create a personal access token; this is one of t
|
|
|
|
|
|
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 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`. You use the same password for all DIY apps. Note, if you later lose `MATCH_PASSWORD`, you will need to delete your Match-Secrets repository (automatically created), and go through the GitHub actions again.
|
|
|
|
|
|
-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.
|
|
|
+## GitHub Match-Secrets Repository
|
|
|
|
|
|
-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.
|
|
|
+> A private Match-Secrets repository is automatically created under your GitHub username the first time you run a GitHub Action. Because it is a private repository - only you can see it. You will not take any direct actions with this repository; it needs to be there for GitHub to use as you progress through the steps.
|
|
|
|
|
|
## Setup Github Trio repository
|
|
|
-1. Fork https://github.com/nightscout/Trio into your account. If you already have a fork of Trio in GitHub, you can't make another one. You can continue to work with your existing fork, or delete that from GitHub and then and fork https://github.com/nightscout/Trio.
|
|
|
+1. Fork https://github.com/nightscout/Trio into your account. If you already have a fork of Trio in GitHub, you can't make another one. You can continue to work with your existing fork, or delete that from GitHub and then fork https://github.com/nightscout/Trio.
|
|
|
1. In the forked Trio 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`
|
|
|
@@ -94,7 +95,7 @@ Once created, you will not take any direct actions with this repository; it need
|
|
|
|
|
|
## Validate repository secrets
|
|
|
|
|
|
-This step validates most of your six Secrets and provides error messages if it detects an issue with one or more.
|
|
|
+This step validates most of your six Secrets and provides error messages if it detects an issue with one or more. In addition, if you do not have a private Match-Secrets repository it creates one for you.
|
|
|
|
|
|
1. Click on the "Actions" tab of your Trio repository and enable workflows if needed
|
|
|
1. On the left side, select "1. Validate Secrets".
|
|
|
@@ -102,6 +103,8 @@ This step validates most of your six Secrets and provides error messages if it d
|
|
|
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.
|
|
|
|
|
|
+> There can be a delay after you start a workflow before the screen changes. Refresh your browser to see if it started. And if it seems to take a long time to finish - refresh your browser to see if it is done.
|
|
|
+
|
|
|
## Add Identifiers for Trio App
|
|
|
|
|
|
1. Click on the "Actions" tab of your Trio repository.
|
|
|
@@ -111,32 +114,78 @@ This step validates most of your six Secrets and provides error messages if it d
|
|
|
|
|
|
## Create App Group
|
|
|
|
|
|
-If you have already built Trio via Xcode using this Apple ID, you can skip on to [Create Trio App in App Store Connect](#create-trio-app-in-app-store-connect).
|
|
|
-_Please note that in default builds of Trio, the app group is actually identical to the one used with Loop, so please enter these details exactly as described below. This is to ease the setup of apps such as Xdrip4iOS. It may require some caution if transfering between Trio and Loop._
|
|
|
+If you previously built Trio using Mac with Xcode with this Apple ID, skip ahead to [Optional: App Group Description Modification](#optional-app-group-description-modification).
|
|
|
+
|
|
|
+_Please note that Trio uses the same app group as Loop. This enables other apps such as Xdrip4iOS to share data with Trio. It may require some caution if transfering between Trio and Loop._
|
|
|
|
|
|
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".
|
|
|
1. For Identifier, enter "group.com.TEAMID.loopkit.LoopGroup", substituting your team id for `TEAMID`.
|
|
|
+ * If you are told that this group already exists, skip ahead to [Optional: App Group Description Modification](#optional-app-group-description-modification)
|
|
|
1. Click "Continue" and then "Register".
|
|
|
|
|
|
+### Optional: App Group Description Modification
|
|
|
+
|
|
|
+> This step is not required, but if you previously built using a Mac with Xcode, it is a good idea to update the **NAME** associated with the **IDENTIFIER** for the Loop App Group. Notice in the table below that the XCode version of the **NAME** is the same as the **IDENTIFIER** but with the `.` replaced with a space.
|
|
|
+
|
|
|
+_Referring to the link and table below, tap on the **IDENTIFIER** for the `Loop App Group`, edit the Description to match the **NAME**, then Save the change._
|
|
|
+
|
|
|
+* [App Group List](https://developer.apple.com/account/resources/identifiers/list/applicationGroup)
|
|
|
+
|
|
|
+| NAME | XCode version | IDENTIFIER |
|
|
|
+|:--|:--|:--|
|
|
|
+| Loop App Group | group com TEAMID loopkit LoopGroup| group.com.TEAMID.loopkit.LoopGroup |
|
|
|
+
|
|
|
+## Bundle Identifiers
|
|
|
+
|
|
|
+Open this link in a separate browser window:
|
|
|
+
|
|
|
+* [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list) on the Apple developer site
|
|
|
+* You will select each of the Identifiers as instructed below, modify it if needed and then save it.
|
|
|
+
|
|
|
+### Optional: Identifier Description Modification
|
|
|
+
|
|
|
+> This step is not required, but if you previously built using a Mac with Xcode or during early Beta testing for Trio, it is a good idea to update the **NAME** associated with each **IDENTIFIER** to match the table below.
|
|
|
+
|
|
|
+_Referring to the table below, tap on each **IDENTIFIER** that has a different **NAME**, edit the Description to match the **NAME**, then Save the change for that identifier._
|
|
|
+
|
|
|
+#### Table of Identifiers
|
|
|
+
|
|
|
+* If you built previously using a Mac with Xcode, you may see the XCode version in your **NAME** column - it starts with XC and then the **IDENTIFIER** is appended where the `.` is replaced with a space, the example for Trio is shown in detail
|
|
|
+* If you built during early beta testing, you might not have `Trio` at the beginning of each **IDENTIFIER** and the full **NAME** may be slightly different
|
|
|
+
|
|
|
+| NAME | XCode version | IDENTIFIER |
|
|
|
+|:--|:--|:--|
|
|
|
+| Trio | XC org nightscout TEAMID trio | org.nightscout.TEAMID.trio |
|
|
|
+| Trio LiveActivity | - | org.nightscout.TEAMID.trio.LiveActivity |
|
|
|
+| Trio Watch | XC IDENTIFIER | org.nightscout.TEAMID.trio.watchkitapp |
|
|
|
+| Trio WatchKit Extension | XC IDENTIFIER | org.nightscout.TEAMID.trio.watchkitapp.watchkitextension |
|
|
|
+
|
|
|
## Add App Group to Bundle Identifiers
|
|
|
|
|
|
+> This step is required for first-time builders using GitHub Actions (Browser Build).
|
|
|
+
|
|
|
+> If you previously built using a Mac with Xcode you can skip ahead to [Create Trio App in App Store Connect](#create-trio-app-in-app-store-connect).
|
|
|
+
|
|
|
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:
|
|
|
- * FreeAPS
|
|
|
- * FreeAPS watchkitapp
|
|
|
- * FreeAPS watchkitapp watchkitextension
|
|
|
-1. Click on the identifier's name.
|
|
|
-1. On the "App Groups" capabilies, click on the "Configure" button.
|
|
|
-1. Select the "Loop App Group" _(yes, "Loop App Group" is correct)_
|
|
|
+1. Repeat this step for these three Identifier **NAMES** - refer to the [Table](#table-of-identifiers) above if your Names look different; if they do, see [Optional: Identifier Description Modification](#optional-identifier-description-modification)
|
|
|
+ * Trio
|
|
|
+ * Trio Watch
|
|
|
+ * Trio WatchKit Extension
|
|
|
+1. Click on the **IDENTIFIER** row.
|
|
|
+1. Scroll down to the "App Groups" capabilies row, click on the "Configure" (or "Edit") button.
|
|
|
+1. Select (or verify the selection for) the "Loop App Group" _(yes, "Loop App Group" is correct)_
|
|
|
1. Click "Continue".
|
|
|
1. Click "Save".
|
|
|
1. Click "Confirm".
|
|
|
-1. Remember to do this for each of the identifiers above.
|
|
|
+1. Remember to do this for each of three identifiers listed under step 2.
|
|
|
+
|
|
|
+There is an additional identifier, but it does not need the App Group added to it:
|
|
|
+* Trio LiveActivity
|
|
|
|
|
|
## Create Trio App in App Store Connect
|
|
|
|
|
|
-If you have created a Trio app in App Store Connect before, you can skip this section as well.
|
|
|
+If you created a Trio app in App Store Connect before, skip ahead to [Create Building Certficates](#create-building-certficates).
|
|
|
|
|
|
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".
|
|
|
@@ -181,3 +230,70 @@ If a GitHub repository has no activity (no commits are made) in 60 days, then Gi
|
|
|
The `build_trio.yml` file uses a special branch called `alive` and adds a dummy commit to the `alive` branch at regular intervals. This "trick" keeps the Actions enabled so the automated build works.
|
|
|
|
|
|
The branch `alive` is created automatically for you. Do not delete or rename it! Do not modify `alive` yourself; it is not used for building the app.
|
|
|
+
|
|
|
+## OPTIONAL
|
|
|
+
|
|
|
+What if you don't want to allow automated updates of the repository or automatic builds?
|
|
|
+
|
|
|
+You can affect the default behavior:
|
|
|
+
|
|
|
+1. [`GH_PAT` `workflow` permission](#gh_pat-workflow-permission)
|
|
|
+1. [Modify scheduled building and synchronization](#modify-scheduled-building-and-synchronization)
|
|
|
+
|
|
|
+### `GH_PAT` `workflow` permission
|
|
|
+
|
|
|
+To enable the scheduled build and sync, the `GH_PAT` must hold the `workflow` permission scopes. This permission serves as the enabler for automatic and scheduled builds with browser build. To verify your token holds this permission, follow these steps.
|
|
|
+
|
|
|
+1. Go to your [FastLane Access Token](https://github.com/settings/tokens)
|
|
|
+2. It should say `repo`, `workflow` next to the `FastLane Access Token` link
|
|
|
+3. If it does not, click on the link to open the token detail view
|
|
|
+4. Click to check the `workflow` box. You will see that the checked boxes for the `repo` scope become disabled (change color to dark gray and are not clickable)
|
|
|
+5. Scroll all the way down to and click the green `Update token` button
|
|
|
+6. Your token now holds both required permissions
|
|
|
+
|
|
|
+If you choose not to have automatic building enabled, be sure the `GH_PAT` has `repo` scope or you won't be able to manually build.
|
|
|
+
|
|
|
+### Modify scheduled building and synchronization
|
|
|
+
|
|
|
+You can modify the automation by creating and using some variables.
|
|
|
+
|
|
|
+To configure the automated build more granularly involves creating up to two environment variables: `SCHEDULED_BUILD` and/or `SCHEDULED_SYNC`. See [How to configure a variable](#how-to-configure-a-variable).
|
|
|
+
|
|
|
+Note that the weekly and monthly Build Trio actions will continue, but the actions are modified if one or more of these variables is set to false. **A successful Action Log will still appear, even if no automatic activity happens**.
|
|
|
+
|
|
|
+* If you want to manually decide when to update your repository to the latest commit, but you want the monthly builds and keep-alive to continue: set `SCHEDULED_SYNC` to false and either do not create `SCHEDULED_BUILD` or set it to true
|
|
|
+* If you want to only build when an update has been found: set `SCHEDULED_BUILD` to false and either do not create `SCHEDULED_SYNC` or set it to true
|
|
|
+ * **Warning**: if no updates to your default branch are detected within 90 days, your previous TestFlight build may expire requiring a manual build
|
|
|
+
|
|
|
+|`SCHEDULED_SYNC`|`SCHEDULED_BUILD`|Automatic Actions|
|
|
|
+|---|---|---|
|
|
|
+| `true` (or NA) | `true` (or NA) | keep-alive, weekly update check (auto update/build), monthly build with auto update|
|
|
|
+| `true` (or NA) | `false` | keep-alive, weekly update check with auto update, only builds if update detected|
|
|
|
+| `false` | `true` (or NA) | keep-alive, monthly build, no auto update |
|
|
|
+| `false` | `false` | no automatic activity, no keep-alive|
|
|
|
+
|
|
|
+### How to configure a variable
|
|
|
+
|
|
|
+1. Go to the "Settings" tab of your Trio repository.
|
|
|
+2. Click on `Secrets and Variables`.
|
|
|
+3. Click on `Actions`
|
|
|
+4. You will now see a page titled *Actions secrets and variables*. Click on the `Variables` tab
|
|
|
+5. To disable ONLY scheduled building, do the following:
|
|
|
+ - Click on the green `New repository variable` button (upper right)
|
|
|
+ - Type `SCHEDULED_BUILD` in the "Name" field
|
|
|
+ - Type `false` in the "Value" field
|
|
|
+ - Click the green `Add variable` button to save.
|
|
|
+7. To disable scheduled syncing, add a variable:
|
|
|
+ - Click on the green `New repository variable` button (upper right)
|
|
|
+ - - Type `SCHEDULED_SYNC` in the "Name" field
|
|
|
+ - Type `false` in the "Value" field
|
|
|
+ - Click the green `Add variable` button to save
|
|
|
+
|
|
|
+Your build will run on the following conditions:
|
|
|
+- Default behaviour:
|
|
|
+ - Run weekly, every Wednesday at 08:00 UTC to check for changes; if there are changes, it will update your repository and build
|
|
|
+ - Run monthly, every first of the month at 06:00 UTC, if there are changes, it will update your repository; regardless of changes, it will build
|
|
|
+ - Each time the action runs, it makes a keep-alive commit to the `alive` branch if necessary
|
|
|
+- If you disable any automation (both variables set to `false`), no updates, keep-alive or building happens when Build Trio runs
|
|
|
+- If you disabled just scheduled synchronization (`SCHEDULED_SYNC` set to`false`), it will only run once a month, on the first of the month, no update will happen; keep-alive will run
|
|
|
+- If you disabled just scheduled build (`SCHEDULED_BUILD` set to`false`), it will run once weekly, every Wednesday, to check for changes; if there are changes, it will update and build; keep-alive will run
|
Andreas Stokholm