GitHub First-Time
Build Loop using GitHub Actions¶
This is only available for Loop 3 and greater versions and for Loop development branches.
Time Estimate
- If you have never built Loop (allow up to one week elapsed time)
- Requesting and getting an Apple Developer Account: 1-2 days
- Creating and configuring your GitHub repositories (without Apple Information): 1-2 hours
- Adding Secrets (requires Apple Developer Account): 1 hour
- Performing the Action steps: 30 minutes to 2 hours
- If you have previously built Loop with Xcode you have fewer steps and are probably familiar with some of the concepts
- Expect 1 to 2 hours
Summary
Once you have Apple Developer and GitHub accounts
- Apple: Generate an API Key
- GitHub:
- Create an access token (GH_PAT)
- Create a Match-Secrets private repository
- Fork a repository (copy of LoopWorkspace)
- Add Secrets to your repository
- Action: 1. Verify Secrets
- Action: 2. Add Identifiers
- Apple:
- Configure Identifiers for Loop
- Create your version of Loop in App Store (personal use only, not for distribution)
- GitHub:
- Action: 3. Create Certificates
- Action: 4. Build Loop
- Apple: Set up Internal TestFlight Group
- Phone: Install Loop with TestFlight
FAQs
- Do I need a Mac computer? No. This can be done on any browser, although it will be easier using a computer or tablet than just using a phone.
- Can I do this on my phone? Yes, but the graphics shown on this page are from a computer browser.
- Isn't it hard to build every 90 days? The initial setup (this page) and deploy (next page) takes a lot of your focused time. But once you build once, subsequent builds take very little of your time to start, then the rest is done automatically.
- Can I use this for my child? You, as the adult, can install using TestFlight on your child's phone. The explict steps are provided at GitHub Deploy: Install TestFlight Loop for Child.
- Can I still use my customizations? Yes. Customize with GitHub
You must build Loop every 90 days when you use GitHub build method.
- We recommend you configure your GitHub personal access token to never expire
- If you have one that expires, go to GitHub Update: Regenerate GitHub Token
- Building a new version literally takes seconds once open your browser and go to your GitHub account
Prerequisites¶
Read and Review
Building with GitHub using a browser requires you to do a series of steps in order with no mistakes. But once you've done it once, subsequent builds are trivial.
At each point in the process
- Check to make sure what you are doing matches the instructions
- Check to make sure you did not skip a step
Different people approach this differently. Choose your method to achieve success:
- Print the summary section above, go through the page sequentially doing each step and check off each step as you go
- Read this whole page, then review it and read the GitHub Errors: Most Common Mistakes section, then return to this page and start doing each step
- Figure out your method and use it
Loop 3 requires iOS 15.1 or higher, no reason not to update to latest iOS
Build Loop¶
There are only two prerequisites to build Loop with this method.
- Paid Apple Developer account
- Free GitHub account
Install Loop¶
You will need TestFlight, from the Apple App Store, installed on your Compatible Phone. You will install Loop on that phone using the TestFlight app.
Use Loop¶
In order to use Loop, you need a Compatible Pump and Compatible CGM. For pumps other than Omnipod DASH, you also need a RileyLink Compatible Device.
For the initial steps, you'll be going back and forth between GitHub and Apple Developer webpages. It is best to open each in a separate window or tab for your browser.
New Terms with GitHub Build¶
There are a number of terms that may seem unfamiliar with the GitHub Build. As you move through this page, there will be detailed instructions, but it helps to have the overview.
Some of these terms have ToolTips, so hover your mouse over the item - or review in the Glossary.
- You may find some terms in the Glossary not in alphabetical order. All the Secrets discussed on this page, are listed under Secrets in the Glossary.
Others terms need an expanded explanation. If reading about the new terms first is confusing, finish reviewing the whole page and then come back.
Modules
: You won't see this term but the concept is important when explaining the other terms- The Loop code uses modules to handle different components of the entire app
- Some of these modules must be associated with your unique App Group
- Others do not have this requirement
Identifiers
: The Identifiers refer to the Modules that must be available to build Loop with GitHub- There are 4 Identifier Names for LoopWorkspace that must be associated with your App Group
Loop
,Loop Intent Extension
,Loop Status Extension
andSmall Status Widget
- There are 2 other Identifier Names that must exist but do not require that association
WatchApp
andWatchAppExtension
- On the
Identifier
screen, there will beNAME
andIDENTIFIER
columns- The items you see under the
NAME
column depend on whether you previously built with Xcode and may start withXC
- The items under the
IDENTIFIER
column match the table in the documentation
- The items you see under the
- There are 4 Identifier Names for LoopWorkspace that must be associated with your App Group
Secrets
: a method to securely embed personal information into your fork of LoopWorkspace to enable GitHub to have access required to build Loop- There are 6 Secrets that must be added to your fork of LoopWorkspace
- These Secrets work for any branch in your fork (
main
ordev
, for example) - These same Secrets are added to your GitHub fork for Other Apps configured with the same GitHub build method
App Store Connect
: a website available for Apple Developers to review their apps- Once you purchase an Apple Developer annual account, you are an Apple Developer and have access to this site
- Most Loopers will not have an App on their page until using the GitHub build method
- The name of an app must be unique across the entire App Store worldwide
- You will need a unique name for your Loop App
- API
Key
: Application Programming Interface Key- This key will be obtained by you from the Apple Developer website to enable your GitHub account to interface with Apple to create your app
Actions
: a custom application for the GitHub Actions platform that performs a complex but frequently repeated task- With Loop 3, actions to Verify Secrets, Add Identifiers, Create Certificates and Build Loop are provided to enable users to build the Loop app from a browser on any computer
- The GitHub system is maintained by Microsoft Corporation and they do a good job of keeping it running - however, if there is a problem, it will be reported on GitHub Status.
Configure to use GitHub Build Actions¶
Review the entire process before starting and then go through slowly and carefully.
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.
- You can send Loop app updates to those you care for
- You can access and install the Loop app via TestFlight if you lose or damage your device
- You do not need to worry about correct Xcode or macOS versions
The setup steps are somewhat involved, but nearly all are one-time steps. Subsequent builds are trivial. The initial steps are best done on a computer where you can save and archive information for later use. Use a text-only editor for this archive file for your Secrets. People have gotten into difficulties when a lower-case character was "auto-corrected" to upper-case when pasting into their archive file.
TestFlight can be used to deploy Loop to a child's phone (under age 13 in the US) but requires a few extra steps on the phone itself. See Install TestFlight Loop for Child.
Your app must be updated once every 90 days, at the current time, but it's simple to make a new build and can be done from anywhere, see Update Loop using GitHub Actions.
Save Your Information¶
Archive This Information
For many of the steps on this page, you will need to have access to usernames, email addresses, passwords, and in some cases, special parameters.
- Record these in a safe place so you can find them when you need them
- A digital copy is best because you will be copying and pasting in different locations
Be sure to use a Text-Only editor like NotePad (PC) or TextEdit (Mac) to archive your information.
A Note about Capitalization and Spaces
In places you will be told to give something a name like: FastLane API Key or FastLane Access Token. Please copy from the docs to use those exact names.
The Secrets that you will add later use names that are capitalized and use underscore _ instead of spaces. Be precise and careful.
The relationship and creation of each item is explained step-by-step on this page.
Use a Text-Only Editor
If you use a "smart" editor, it may change lower-case letters to upper-case letters at the beginning of a line when you paste items into your archive file.
If even one character is capitalized when it should not be, you will get GitHub Errors.
If you use a smart editor to store your FASTLANE_KEY, you are likely to get the mysterious invalid curve name
error.
The list below indicates what you need to record (save digitally so you can copy and paste). Notice that some information is created in one place and used in another. The items in all capital letters will be added to the Secrets for your LoopWorkspace fork, so they are listed twice in the list below.
Needed or created at developer.apple.com
- Email address (this is your username)
- password
TEAMID
FASTLANE_ISSUER_ID
FASTLANE_KEY_ID
FASTLANE_KEY
Needed or created at github.com
- Email address
- password
- username
- Your GitHub repository address will be:
https://github.com/username
- Your LoopWorkspace repository address will be:
https://github.com/username/LoopWorkspace
- GitHub Personal Access Token (GH_PAT)
- a password - make one up and save it (
MATCH_PASSWORD
)
Needed when you Configure Secrets
- Save names and values in a text-only editor
- These same secrets are used for Loop and for Other Apps
TEAMID
FASTLANE_ISSUER_ID
FASTLANE_KEY_ID
FASTLANE_KEY
GH_PAT
MATCH_PASSWORD
Apple Developer Account¶
If you have an Apple Developer Account, you should sign in to your account before starting. There will be links to take you to specific pages; if you are not already logged in, you will be required to log in before you can go to that page.
If you do not already have a paid Apple Developer account, you need to purchase one ($99 annual fee). It may take a few days for the account to be enabled.
- LoopDocs has an Apple Developer Program page that explains in detail how to sign up for an account
- This link takes you straight to Apple Developer account to sign up
Generate API Key¶
You cannot generate the API Key until you have the paid Apple Developer account set up. If you are still waiting for Apple to enable your account, you can skip ahead to complete part of the GitHub steps (see New GitHub Account or Setup GitHub), but you will need to pause at Configure Secrets.
This section will walk you through the steps required to gather or create these parameters.
Name | Description |
---|---|
TEAMID |
This 10-character identifier is associated with your Apple Developer ID and never changes |
FASTLANE_ISSUER_ID |
The issuer ID is associated with your Apple Developer ID and never changes |
FASTLANE_KEY_ID |
Key ID provided when you create an API key in App Store Connect; it is associated with the FASTLANE_KEY |
FASTLANE_KEY |
Copy the full key from the text file you downloaded when generating the API key - Filename has FASTLANE_KEY_ID value embedded in it.Include everthing in the file from -----BEGIN PRIVATE KEY----- and ending in -----END PRIVATE KEY----- |
Each step has a link to take you to the specific page you need to do the next step. It is best if you open each link in a separate tab or window so you can refer back to these instructions as you move along.
- Open this link: Apple developer portal page.
- Look at the upper right hand corner of that page
- The 10-character ID number below your name is your
TEAMID
- If all you see are icons, click on the Membership Details icon
- Record this for use when you configure your Secrets and when you configure your unique App Group
- Stop a moment and double check - if you get this wrong, you will have errors later
- Do not "type" what you think you see; copy and paste from the
Team ID
from the webpage. (Avoid the wrong number of characters; avoid typing an8
when it should be aB
.)
- Do not "type" what you think you see; copy and paste from the
-
Open this link:
App Store Connect/Access/API
-
Click the
Keys
tab-
If this is your first time here, there will be a dialog for you to follow:
"
Permission is required to access the App Store Connect API. You can request access on behalf of your organization.
"- Click on
Request Access
and follow directions until access is granted
- Click on
-
Once access is granted, click on the
Generate API Key
button
-
-
If you did not get routed through the
permission is required
screens click the blue + sign
- A new
Generate API Key
dialog box will appear as shown in the graphic below
- Enter the name of the key as "
FastLane API Key
" and chooseAdmin
in the access drop down menu - Confirm the name and that "
Admin
" is selected and then click on the "Generate
" button.
-
Copy API Key Secrets¶
The Keys
screen is seen again with the additional content similar to that shown in the graphic below; the key information is blanked out for security.
-
Review the graphic and then follow directions below to save more parameters you will need to Configure Secrets
-
A button labeled Copy is always adjacent to the
Issuer ID
above the word Active (this is the same for all keys that you generate with this Apple Developer ID)- Tap on the
Copy
button - this copies theIssuer ID
into your paste buffer - In the file where you are saving information, paste this with the indication that it is for
FASTLANE_ISSUER_ID
- Tap on the
- Hover to the right of the
Key ID
and theCopy Key ID
button shows up- Tap on the
Copy Key ID
button - this copies theKey ID
into your paste buffer - In the file where you are saving information, paste this with the indication that it is for
FASTLANE_KEY_ID
- Tap on the
-
Click on the
Download API Key
button - you will be warned you can only download this once. -
Find your
AuthKey
download in your downloads folder. The name of the file will be "AuthKey_KeyID.p8
" whereKeyID
matches yourFASTLANE_KEY_ID
- Double-click to open it and you will be presented a message asking how you'd like to open it (message shown is for a Mac - translate these directions to whatever computer you are using)
- Click on "
Choose Application...
" and then select "TextEdit
" (on a Mac, NotePad on a PC, or any text-only editor you prefer)
-
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- On a Mac, use Cmd+A, then Cmd+C to copy all the contents
- On a PC, use Ctrl+A , then Ctrl+C to copy all the contents
- In the file where you are saving information, paste this with the indication that it is for
FASTLANE_KEY
- Copy the full text, including the "
Do Not Confuse Your Keys¶
API Key vs APN Key
If you use Remote Commands with Nightscout, you may notice the Application Programming Interface (API) key has the same type of format as the Apple Push Notification (APN) key. The keys for both of these purposes are p8 keys, but they should not be confused with each other.
The Secrets for building with GitHub use the API Key.
The config vars for Nightscout use the APN Key.
- If you are using remote commands with Nightscout and building with the GitHub build, you must also add the config var of
LOOP_PUSH_SERVER_ENVIRONMENT
with a value ofproduction
to your Nightscout site or the remote commands will not work.
Done with Apple Secrets¶
In summary, from this section, you have found or generated the following, and saved copies for later use
TEAMID
FASTLANE_ISSUER_ID
FASTLANE_KEY_ID
FASTLANE_KEY
Time for a Break?
This is a good place to pause if you need to. Just note where you are on the page so you can return later.
Lost FASTLANE_KEY¶
I can't find my FASTLANE_KEY
If you cannot find where you stored your information, you can get a new key. You cannot recover an old one. Return to Generate API Key, but add this initial step.
When you use the link in the Generate API Key step, you will see an Active key. You must first click Edit by the Active section, revoke your "FastLane API Key
" and then follow the directions to generate a new one. You will have to update the Secrets
for every App repository when you take this step.
The FASTLANE_KEY_ID
and FASTLANE_KEY
must both be updated.
New GitHub Account¶
If you have a GitHub account, you can skip to Setup GitHub. Make sure you know your GitHub associated email, username (username
) and password.
If you do not already have a GitHub account, you need to create one. Be sure to record the email, password and username for your GitHub account.
Decide on a couple of usernames that you will be happy with - this will get embedded into your GitHub URL. Your first choice might not be available, so be prepared with several candidates. Your personal URL will be: https://github.com/username
.
- Click on this link to sign up for a free account: github account signup
- You will need to enter the email you want associated your GitHub account
- You will be asked to enter a password
- You will be asked to enter a username
- You will be asked if you want to receive email, ok to say
N
for no - you still get important account information with that email - Solve the puzzle to prove you're a person
- Check the associated email to get the code and enter the code into github.com to confirm your account
- You should get the Welcome to GitHub screen
- Indicate it is "Just me" on your team and Continue
- Don't check anything on the next screen, just tap
Continue
- Select the
Free
option by selectingContinue for Free
The free level comes with plenty of storage and compute time to build Loop.
Setup GitHub¶
Now you will configure a personal access token (GH_PAT
), create one new repository and then fork the LoopWorkspace
repository.
Create GH_PAT¶
You must be logged into your GitHub account before starting this step. If you are continuing, you are already logged in.
- You will be creating a new GitHub
Personal Access Token
and giving it the name "FastLane Access Token
" -
Open this link: https://github.com/settings/tokens/new
- Referring to the graphic
- Note that
Tokens (classic)
is highlighted - Most Looper will use the
classic Token
- If you are a developer who needs to use fine-grained
tokens
, that is fine
- If you are a developer who needs to use fine-grained
- Edit the note box to be
FastLane Access Token
- Note that
- The default Expiration time is 30 days - but you should select
No expiration
(use the drop down menu to select)- GitHub will show a yellow warning when you do this
- It is ok to ignore the warning
- Add a check beside the
repo
permission scope - Scroll all the way to the bottom and click
Generate token
(it's a long way, ignore all other settings, do not check anything else)
- Referring to the graphic
-
A new screen appears showing your access token
- Copy the
token
and record it - once you leave this screen you can't see it again - You will use this for
GH_PAT
when you set up your Secrets - You can Regenerate GitHub Token for
GH_PAT
if you lose it, but best to keep it safe
- Copy the
Create Match-Secrets¶
Open your github.com URL (this is https://github.com/username
), where you replace username
with the name you chose above.
Create a new private repository - you can either click on the link below, or follow the instructions with the first graphic:
- Click on this link: (https://github.com/new)
or
-
At the top right of the screen, click on the + sign and select
New Repository
This shows you a screen similar to the following graphic which has 3 regions highlighted:
- In
Repository name
, typeMatch-Secrets
(use a hyphen betweenMatch
andSecrets
) - Be sure to check the box
Private
(red circle) to make the repository private - Please confirm you selected
Match-Secrets
repository as private. - Scroll to the bottom of the page and tap on "
Create repository
"
You will then be shown a screen with a lot of options - you will not do anything on this screen except leave it.
- Click on just your username (as indicated by the red rectangle) to return to your main GitHub URL.
You will not be interacting with your Match-Secrets
repository directly. It needs to exist for other actions to work correctly.
You are done with this part of the set up.
Fork LoopWorkspace¶
Existing Fork
Some people may already have a fork of LoopWorkspace
. Click on Already Have LoopWorkspace, decide what to do and follow the appropriate link back to these instructions.
- Open this link https://github.com/LoopKit/LoopWorkspace to open the
LoopWorkspace
repository owned byLoopKit
. - Review the highlighted locations of the graphic below (yours won't look quite like this yet), but the
Fork
button is in the same place - At upper right side of the screen, click on the word
Fork
- If you already have a fork, it will not allow you to proceed, see Already Have LoopWorkspace
-
Now your screen should look like the graphic below
- Your username will be automatically filled in as the owner (
Owner
) LoopWorkspace
is automatically filled in as the repository name (Repository Name
)- Leave the selection that says "
Copy the main branch only
" checked - Click on the green
Create fork
button
- Your username will be automatically filled in as the owner (
Successful Fork¶
After creating the fork, your screen should be similar to the next graphic - it will say main
for the branch instead of dev
because this graphic was prepared before the release of Loop 3. You may or may not see the messages you are told to dismiss in the next two bullets. No worries if you don't see them.
- Near the top right, click on the close button (
x
) to dismiss theSuccessfully fetched
message - In the middle, click on the
Dismiss
button to remove the "Your branch is not protected
" message
Carefully compare your screen to the graphic below paying attention to the highlighted sections.
- Note that your username is now showing
- The comment under your username indicates where the fork came from (that is a clickable link)
- The branch that is selected is
main
- The message says "
This branch is up to date with LoopKit/LoopWorkspace:main
"
Time for a Break?
This is a good place to pause if you need to. Just note where you are on the page so you can return later.
Configure Secrets¶
Secrets can be used for Other Apps
- There are 6 Secrets that must be added to your fork of
LoopWorkspace
- These Secrets work for any branch in your fork (
main
ordev
, for example) - These same Secrets would be added to your fork of a repository for Other Apps
You need to be logged into GitHub.
-
Return to your forked copy of
LoopWorkspace
- Click on your personal icon at upper right to see the drop-down menu and select "
Your repositories
"
- Click on your personal icon at upper right to see the drop-down menu and select "
-
You should see (at least) 2 repositories:
Match-Secrets
andLoopWorkspace
- Click on
LoopWorkspace
to open that repository -
Click on the Settings Icon near the top right of your LoopWorkspace
- If you don't see ⚙️
Settings
, make your browser wider or scroll to the right - If you still don't see ⚙️
Settings
, then you are not on your fork or you need to sign in to your GitHub account -
After you click on ⚙️
Settings
, your screen should look like the graphic below
- If you don't see ⚙️
-
On the left side, find the
Secrets and variables
dropdown and chooseActions
-
After you select on
Actions
, your screen should look like the graphic below
-
-
Tap on the green button at the top right of your screen labeled
New repository secret
(refer to the graphic above where the button is highlighted)- A new dialog screen appears as shown in the graphic below
- Do not do anything yet - first read what you will do in the next section
- In the
Name *
box where it saysYOUR_SECRET_NAME
, you will click in the box and paste one of the 6 secret names, as directed in Enter Each Secret - In the
Secret *
box, you will click in the box and paste the value for that secret - Once you click on
Add Secret
, the secret will be added
- In the
Enter Each Secret¶
Refer to the list of parameters found in Save Your Information. This is the time you will enter these items.
Take a calming breath. This next part requires care.
- Once you enter and save a secret value, you will not be able to view what you just entered, so check carefully before you hit
Add Secret
to save it- You can replace the value for any secret later - you just can't see what you entered before
- If you make a mistake, the actions you take in the next sections will fail, but the error messages help you figure out which secrets you need to fix
- So collect the list of information you've gathered so it's handy and make up a password for the
MATCH_PASSWORD
and save that in your secrets archive file - Confirm, one more time, that your
TEAMID
is correct- If it is not, all will appear fine until you try to Build Loop and then you will get failures
For each of the following secrets, follow the directions below - this list is configured with a copy button when you hover to the right of each word - this helps avoid spelling errors.
TEAMID
FASTLANE_ISSUER_ID
FASTLANE_KEY_ID
FASTLANE_KEY
GH_PAT
MATCH_PASSWORD
- For the
FASTLANE_KEY
value, copy the entire contents from-----BEGIN PRIVATE KEY-----
through-----END PRIVATE KEY-----
- For
MATCH_PASSWORD
value - make up a password for this and save it for later use- The
MATCH_PASSWORD
must be the same for any repository using this method (Other Apps)
- The
Once all six secrets have been added to your LoopWorkspace
, you are done with Settings. Your screen should look similar to the graphic below.
- Take a moment to be sure all of your secrets are spelled correctly
- If you notice a mistake, just delete the one that is not spelled correctly and add a
New repository secret
with the correct name
Time for a Break?
This is a good place to pause if you need to. Just note where you are on the page so you can return later.
Validate Secrets¶
This step checks that the Secrets you added are correct. Some things cannot be validated at this point, but most can and a relatively clear error message is provided.
This will be updated soon, but for now - follow the instructions under "Add Identifiers for Loop", but do the first action: "1 Validate Secrets".
Add Identifiers for Loop¶
Near the top middle of your LoopWorkspace
fork, there is an Actions
tab. If you have used Actions
on this repository before, skip ahead to Add Identifiers.
First Use of Actions Tab¶
Click on the Actions
tab of your LoopWorkspace
repository.
- The first time you click on
Actions
with this repository you'll be informed thatWorkflows aren't being run on this forked repository
as shown in the graphic below -
Tap on the green button that says:
I understand my workflows, go ahead and enable them
The workflows
are now displayed: look at the list on the left side as shown in the graphic below. (You can dismiss the Actions Enabled
message using the X
near the upper right side if it appears).
Add Identifiers¶
Refer to the graphic below for the numbered steps:
- Click on the
Actions
tab of yourLoopWorkspace
repository - On the left side, click on 2.
Add Identifiers
- On the right side, click
Run Workflow
to show a drop-down menu- You will see your default branch (should be
main
) - If your default branch is not
main
, review GitHub Early Adopters
- You will see your default branch (should be
-
Tap the green button that says
Run workflow
.
The Add Identifier
Action should complete (succeed or fail) in a few minutes as shown in the graphic below.
- If you see the green check () continue to the next section
- If you see the red
X
():- Examine the Error tells you how to download the file needed to diagnose your problem.
- Action: Add Identifiers Errors lets you know what to search for in the downloaded file
- Once you've resolved the error, repeat the Action: Add Identifiers step
Configure Identifiers for Loop¶
Create App Group¶
The Loop
App Group already exists if you previously built Loop using Xcode with this Apple Developer ID. If that is the case, skip ahead to Find Loop Identifier.
If you have never built Loop with Xcode using your TEAMID
, you need to create an App Group associated with your TEAMID
.
- Open this link:
Register an App Group
on the Apple developer site. - For
Description
, useLoop App Group
. - For
Identifier
, entergroup.com.TEAMID.loopkit.LoopGroup
, substituting your team id forTEAMID
. - Double-check the spelling - your
TEAMID
must be correct and theLoop
App Group must match the format shown in the previous step- A mistake here means you will not be able to build Loop until you fix it
- Click
Continue
and thenRegister
.
Find Loop Identifier¶
Open this link: Certificates, Identifiers & Profiles: Identifiers List
on the Apple developer site.
New Builders¶
If you never built using Xcode, then after successfully performing the Add Identifiers
Action, you will see the six items listed under NAME
in the table below with the associated IDENTIFIER
information, where your Developer ID
replaces the TEAMID
in the identifier.
Previous Xcode Builders¶
If you have built Loop using Xcode, then at least the Loop identifier will appear as XC com.TEAMID.loopkit.Loop
under the NAME
column. There may be other differences in the NAME
column, but key off what you see under the IDENTIFIER
column of the table. Only the six listed in the table below are of interest when building Loop.
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 |
Loop 2 to Loop 3 Builders
Several people who built earlier versions of Loop with Xcode and are using the GitHub method say they can't find the identifier names. You can key off the IDENTIFIER
instead of the NAME
column in the table above.
Or
Follow the Delete Identifiers
instructions and then run Action: Add Identifiers
again. You might not be able to delete the "Loop" identifier, so it will still begin with XC
, but the others will appear with the short names shown above.
Add or Review Configuration for Loop Identifier¶
Find and click on the row for the Loop identifier on the Certificates, Identifiers & Profiles: Identifiers List page. Look in the IDENTIFIER
column to find com.TEAMID.loopkit.Loop
. The name in the NAME
column may be different than Loop.
NAME |
IDENTIFIER |
---|---|
Loop |
com.TEAMID.loopkit.Loop |
The Edit Your App ID Configuration
screen will open. You will be taking two actions for the Loop identifier.
- Looking at the
App Services
column, scroll down to theApp Groups
row- Ensure the check box (under the
Capabilities
column) forApp Groups
is checked - (
XC Loop
) - If the wordEdit
shows up underNOTES
, move on to step 2 below - If the word
Configure
shows up, tap on it- This opens the
App Group Assignment
screen - Check the box by
Loop
App Group that uses yourTEAMID
ingroup.com.TEAMID.loopkit.LoopGroup
and thenContinue
- This opens the
- Ensure the check box (under the
-
Continue scrolling down to the
Time Sensitive Notifications
row- Check, or confirm the box is checked, next to
Time Sensitive Notifications
as shown in the following graphic - This is only needed for the
Loop
identifier
- Check, or confirm the box is checked, next to
-
Now scroll slowly back up to the top of the page. As you go, confirm that each of these is configured with a check mark; if any are missing, click to enable.
Time Sensitive Notifications
SiriKit
Push Notifications
HealthKit
App Groups
(enabled withgroup.com.TEAMID.loopkit.LoopGroup
)
If you modified settings for the Loop
identifier, the Save
button at the top right will become active. Click on Save
before leaving this page - otherwise, the change does not take effect.
- Tap on
Save
- This opens the
Modify App Capabilities
confirmation screen - Click on
Confirm
If you did not need to make changes, the Save
button will not be active.
- Tap on the
< All Identifiers
button at the top left
The full list of Identifiers should be displayed again.
Add App Group to Other Identifiers¶
You will now be checking the status for 3 more identifiers to ensure the App Group is configured to use the Loop
App Group. You must add or confirm the App Group for these 3 identifiers:
NAME |
IDENTIFIER |
---|---|
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 |
Find and click on a given identifier row on the Certificates, Identifiers & Profiles: Identifiers List page.
The Edit Your App ID Configuration
screen will open. You will be taking one action for each of these three identifiers.
Looking at the App Services
column, scroll down to the App Groups
row
- Ensure the check box (under the
Capabilities column
) forApp Groups
is checked - If the word
Edit
shows up underNOTES
, return to the identifiers list - If the word
Configure
shows up, tap on it- This opens the
App Group Assignment
screen - Check the box by
Loop App Group
that uses yourTEAMID
ingroup.com.TEAMID.loopkit.LoopGroup
and thenContinue
- This opens the
If you had to modify a given identifier, the Save
button at the top right will become active
- Tap on
Save
- This opens the
Modify App Capabilities confirmation
screen - Click on
Confirm
If you did not need to make changes, the Save
button will not be active.
- Tap on the
< All Identifiers
button at the top left
The full list of Identifiers should be displayed again.
Create Loop App in App Store Connect¶
If you have created a Loop app
in App Store Connect before, you can skip this section.
If have previously used some kind of remote build, like diawi
or TestFlight
, you may have your Loop in the App Store but can't see it. Don't worry - there are instructions for this case.
-
Open this link:
App Store Connect / Apps
to view your apps; log in if needed.- If you have never added an app to App Store Connect, you will not see the icons inside the red rectangle and should keep going, although some people report the search icon shows up for them
- If you have an app that is not shown, you will see a search icon and the
All Statuses
dropdown. If you get to step 3 and cannot find yourcom.TEAMID.loopkit.Loop
in the Bundle ID drop-down, this means you need to follow Find My Loop.
-
Click the
Add Apps
button or the blue "plus" icon ( ) and selectNew App
as shown in the graphic below -
The
New App
dialog box opens and should appear similar to the graphic below. Before you fill anything out, make sure yourBundle ID
is available in the dropdown menu (it shows asChoose
in the graphic below). If you do not seecom.TEAMID.loopkit.Loop
, withTEAMID
matching yourTEAMID
in the dropdown menu; back out of this screen and follow the directions in Find My Loop instead.- Select
iOS
. - Enter a name: this will have to be unique
- You could start with
Loop_ABC
whereABC
are your initials - If that is already taken, you can add a number, for example,
Loop_ABC_123
- This name is what you see on the App Store Connect list and in the TestFlight app
- Once installed on your phone, you will see Loop with the standard Loop Logo
- You can Change the App Store Connect Name later if you want
- You could start with
- Select your primary language.
- Choose the
Bundle ID
that matchescom.TEAMID.loopkit.Loop
SKU
can be anything; for example123
.- Select "
Full Access
".
- Select
-
One last check - if the
Bundle ID
has a number other than your actual 10-digitTEAMID
embedded in it, you will be creating an App in the App Store that you cannot use- In this case, do NOT select
Create
- Instead, go back and put the correct value into the
TEAMID
Secret and follow the steps in Delete Identifiers
- In this case, do NOT select
- Click
Create
but do not fill out the next form. That is for submitting to the app store and you will not be doing that.
You are done with this activity and can close the browser tab. It's time to head back to your GitHub account and Create Certificates
Find My Loop¶
This section is for people who were not able to follow the instructions in the last section because com.TEAMID.loopkit.Loop
, with TEAMID
matching your TEAMID
, was not in the dropdown menu for Bundle ID
.
There are two possible reasons:
- You did not complete Add App Group to Bundle Identifiers or one of the predecessor steps; review those steps
- Your app is already in App Store Connect, but you cannot see it
You may have no memory of ever setting up Loop
in App Store Connect. If you previously used some kind of remote build, like diawi
, your Loop
may be there as a Removed App.
-
Open this link: App Store Connect / Apps, look for
All Statuses
dropdown indicator and selectRemoved Apps
-
Click on the App name:
-
Ensure this is the app you want by selecting on
App Information
, highlighted on the left side in the graphic below.- Examine its
Bundle ID
(not in view in this graphic) - confirm it is correct. - The format should be:
com.TEAMID.loopkit.Loop
with your TEAMID included
- Examine its
-
Then scroll down to the bottom and choose
Restore App
. -
Make sure
User Access
is set toFull Access
and click onRestore
. -
You are done with this step and ready to Create Certificates
Create Certificates¶
Refer to the graphic below for the numbered steps:
- Click on the "
Actions
" tab of yourLoopWorkspace
repository - On the left side, click on "
Create Certificates
" - On the right side, click "
Run Workflow
" to show a drop-down menu- You will see your default branch (should be
main
) - If your default branch is not
main
, review GitHub Early Adopters
- You will see your default branch (should be
-
Tap the green button that says "
Run workflow
". -
Wait a minute or two for the action to finish
- If this action fails, head over to Action: 3. Create Certificates Errors
- Once you've resolved the error, repeat the Actions Add Identifiers and then
Create Certificates
. (TheAdd Identifiers
might not be required but it is fast and should be done as a matter of routine.)
Build Loop¶
Refer to the graphic below for the first four steps:
- Click on the "
Actions
" tab of yourLoopWorkspace
repository. - On the left side, click on "4.
Build Loop
". - On the right side, click "
Run Workflow
" to show a drop-down menu- You will see your default branch (should be
main
) - If your default branch is not
main
, review GitHub Early Adopters
- You will see your default branch (should be
-
Tap the green button that says "
Run workflow
". -
Wait a few minutes to make sure there is not an early failure
- If this action fails, head over to Action: Build Loop Errors
- Once you've resolved the error, it's a good idea to repeat all three steps in this order:
- Add Identifiers
- Create Certificates
- Build Loop
- If the process appears to be happening without an error, go do something else for a while. The build should take about 20-30 minutes.
- Your app should eventually appear on
App Store Connect
.
Set Up Users and Access (TestFlight)¶
Once the first build completes, you will be able to configure TestFlight for the app.
You are configuring a private capability for your family using an Internal Testing group (max of 100). You need the Apple ID email address for each adult installing from your build. When building for a child, you will use your own Apple ID, not theirs. See Install TestFlight Loop for Child.
-
First you need to add the email address(es) to your App Store Connect Access Users list:
- Open this link: Users and Access
- You must provide a role for each person -
Customer Support
is a good choice - Once you have added them here, you'll be able to select them in the
TestFlight
group for your app
- You must provide a role for each person -
- Open this link: Users and Access
-
Open this link: App Store Connect / Apps to view your apps; log in if needed. Then select your Loop app. Click on
TestFlight
tab and theInternal Testing
to add a group. -
Fill out the name you want for the
Internal Testing
group- Be sure to check the box
Enable automatic distribution
- Click
Create
when done (this can always be modified later)
- Be sure to check the box
-
As soon as you create the group, you'll be asked who should be included
- Click in the box beside each person you want to include
- Each person in this group will get an email each time you update (build again) on GitHub
- Click
Add
when you are done - If building for a child, you will send the invitation to yourself because you will install for your child: See Install Loop for Child
Deployment¶
The GitHub Deployment walks you through the steps to deploy to a phone.
Extra Steps¶
Most people won't need the information on the rest of this page.
Already Have LoopWorkspace¶
Some people may already have a fork of LoopWorkspace
. They might even have one that they forked from somewhere other than LoopKit
.
Suggestions - choose one of these methods:
- Update the repository if it is forked from
LoopKit
- Open your
LoopWorkspace
repository (https://github.com/username/LoopWorkspace
) where you use your GitHubusername
in the URL - Review the graphic in the Successful Fork section
- Make sure all the items highlighted by red rectangles are correct with the possible exception of your fork being up to date
- If you see a message that your fork is not up to date - tap on the
Sync fork
button and follow the instructions - Continue with the Create GH_PAT section
- Open your
- Delete that repository if it is from somewhere other than
LoopKit
or the fork you wanted to start with (which might have customizations that you want)- Instructions to delete a repository are found at GitHub Docs
- You just need to make sure that a repository called
LoopWorkspace
is no longer in your GitHub account - Return to Fork LoopWorkspace and follow all the instructions
Delete Identifiers¶
When you have already built Loop with Xcode, the Identifier names will not match the directions and you might have trouble deciding which ones to configure. Your existing Loop
identifier will have a name that starts with XC
as shown below, where your 10-digit TEAMID
is used.
Name: XC com TEAMID loopkit Loop
Identifier: com.TEAMID.loopkit.Loop
The Identifier
that is associated with the Loop
identifier cannot be deleted if it is already in the App Store but all others can. If you attempt to delete the XC
Loop identifier, you may be told it cannot be deleted because it is in use in the app store. That's OK. Same for other identifiers (if you build a bunch of Apps). If a Bundle ID
has ever been associated with an app in the App Store, you cannot delete the Identifier
.
To make it easy when configuring the identifiers, go through and delete as many as you can.
- Open this link: Certificates, Identifiers & Profiles: Identifiers List on the Apple developer site.
- Use the graphic below as a guide to removing identifiers
- Keep repeating the steps until you've removed all the identifiers you can (or want to) delete
- It is OK to delete an identifier even if it does have your correct
TEAMID
- If you try to delete the
Loop
identifier with yourTEAMID
, it will refuse, don't worry, just keep going
- If you try to delete the
- Note - this graphic indicates where on this page you can find your
TEAMID
- If you notice an identifier with a value embedded in it that does not have your
TEAMID
, then delete it if you can and Update Secrets with your correctTEAMID
- If you try to delete a Loop identifier that does not have your
TEAMID
, but you already added to the App Store, it will refuse, don't worry, just keep going
- If you notice an identifier with a value embedded in it that does not have your
If coming here from the GitHub Errors page because you enter the wrong TEAMID
in Secrets
- return to that page once you've deleted as many identifiers as you can: Errors: Wrong TEAMID in Secrets.
If you were just trying to clean up the identifiers, then follow these steps:
- Run Action: Add Identifiers to add Identifiers with the documented short names
- If you did not complete Find Loop Identifier step, do it now
- Complete the Add App Group to Other Identifiers
- If you did not complete the Create Loop App in App Store Connect step, do it now
- Continue with Create Certificates and then Build Loop