Collect Secrets

Collect and Save Secrets

Section Summary (click to open/close)

You require 6 Secrets (alphanumeric items) to use the GitHub Browser Build method and if you use the GitHub Browser Build method to build more than Loop, e.g., LoopFollow or LoopCaregiver, you must use the same 6 Secrets for each app you build with this method.

Each secret is identified with ALL_CAPITAL_LETTER_NAMES.

• Four Secrets are from your Apple Account
• One Secret is from your GitHub account
• One Secret is a password you make up and save
• 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 the case, because these Secrets are case-sensitive
  • Refer back to Save Your Information for more details about smart vs text editors

To skip the detailed instructions, click on Collect the Four Apple Secrets

You need to save your information digitally, so you can copy and paste. The information is created in one place and used in another. Refer to Configure Secrets for how the Secrets are used. In addition to the 6 Secrets, other important information to keep handy (like usernames and passwords) is listed below. Be sure to keep this file secure.

Created at developer.apple.com

• Email address (this is your username)
• password
• Four items used as Secrets
  • TEAMID
  • FASTLANE_ISSUER_ID
  • FASTLANE_KEY_ID
  • FASTLANE_KEY

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
• One item used as a Secret
  • GitHub Personal Access Token (GH_PAT)

Created yourself

• a password - make one up and save it (MATCH_PASSWORD)

Collect the Four Apple Secrets

Section Summary (click to open/close)

You will be saving 4 Secrets from your Apple Account in this step.

1. Sign in to the Apple Developer portal page.
2. If you need to accept a new agreement (happens about twice a year), be sure to do so now
   • Need help? Look at this section on the update page: Accept Agreements
3. The first Apple Secret is your Team ID.
   • Copy the Team ID from the upper right of the screen. Record this as your TEAMID.
4. The final 3 Apple Secrets come from the creation of the "FastLane API Key".
   • Go to the App Store Connect interface, click the "Integrations" tab, and create a new key with "Admin" access. Give it the name: "FastLane API Key".
5. Record three more secrets
   • Record the issuer id; this will be used for FASTLANE_ISSUER_ID.
   • Record the key id; this will be used for FASTLANE_KEY_ID.
   • 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.

To skip the detailed instructions, click on Collect the GH_PAT Secret

This section provides detailed instructions for the four Secrets associated with your Apple Developer ID.

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 everything in the file from -----BEGIN PRIVATE KEY----- and ending in -----END PRIVATE KEY-----

New Apple Developer Account

If you have an Apple Developer Account, skip ahead to Find TEAMID.

If not, 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

Find TEAMID

Sign in to your Apple Developer account at this link: Apple Developer portal page.

1. Click Account in the top menu bar
2. If you need to accept a new agreement (happens about twice a year), be sure to do so now
   • Need help? Look at this section on the update page: Accept Agreements

3. Click the Membership Details icon

   

4. Next to the Team ID field, is a 10-character ID number. This is your Apple Developer TEAMID.

Record this for use as TEAMID in your Secrets file. You will also need it when you Create  App Group.

• Stop a moment and double-check

• If you get this wrong, you will have errors at the very end, which require you to delete some items and repeat some steps on this page

  Do not "type" what you think you see

  Copy and paste the Team ID from the webpage.

  • TEAMID must be 10 characters
  • Avoid typing an 8 when it should be a B

Generate API Key

This step is used to create and save the final 3 Secrets you need from your Apple Developer account.

Paid Apple Developer Account is Required

To generate the API Key, you must have a paid Apple Developer account.

If you are waiting for Apple to enable your account, you can skip ahead to create a New GitHub Account and Create GitHub Personal Access Token. You then pause at Configure Secrets until your Apple account is active.

1. Click this link to open in a new tab: App Store Connect/Access/Integrations/API

   • The top of the display is shown in the graphic below

   

   • Click the Integrations tab as indicated in the graphic above

     • If this is your first time here, you will see:

       "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

     • 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 choose Admin in the access dropdown menu
   • Confirm the name and that "Admin" is selected and then click on the "Generate" button.

Copy API Key Secrets

The Integrations screen appears again with content similar to the graphic below; the key information is blanked out for security.

Review the graphic and then follow the directions below to save more parameters you will need to Configure Secrets

1. 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 the Issuer 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
2. Hover to the right of the Key ID and the Copy Key ID button shows up
   • Tap on the Copy Key ID button - this copies the Key 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

3. Click on the Download API Key button - you will be warned you can only download this once.

   

4. Find your AuthKey download in your downloads folder. The name of the file will be "AuthKey_KeyID.p8" where KeyID matches your FASTLANE_KEY_ID

   • Double-click to open it and you will be presented a message asking how you'd like to open it (The 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)

   

5. 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

   

Organize your Key File

Pro Tip: Use the same folder as your Secrets Reference File

It's a good idea to keep all your important files in one place. You probably set up a a folder for your Secrets Reference File. Use the same folder for your API key - be sure to label the file so you know what the key is. For example, change the name from KPMAM8y3G5.p8 to API_KEY_KPMAM8y3G5.p8.

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 GitHub Browser Build
  • Remote Commands Config Vars: make sure you have a config var of LOOP_PUSH_SERVER_ENVIRONMENT with a value of production or remote commands will not work with Nightscout
• This is true for using Nightscout directly or using LoopCaregiver

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.

Collect the GH_PAT Secret

If you already have a GitHub Account, skip ahead to Create GitHub Personal Access Token.

New GitHub Account

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 selecting Continue for Free

The free level comes with plenty of storage and compute time to build the Loop app.

Create GitHub Personal Access Token

Section Summary (click to open/close)

Log into your GitHub account to create a personal access token, which you will save as GH_PAT.

Click to create a new personal access token:

• Enter a name for your token, use "FastLane Access Token"
• Change the Expiration selection to No expiration
• Select the workflow permission scope (repo will be automatically selected)
  • This step enables automatic building
• Click "Generate token"
• Copy the token and record it. It will be used below as GH_PAT

To skip the detailed instructions, click on Make up a Password.

Default Settings

These instructions are a prerequisite for automatic update and automatic build.

Refer to Modify Automatic Building if you don't want to accept the default recommendation to automatically update and build.

You must be logged into your GitHub account before starting this step. If you are continuing, you are already logged in.

1. You will be creating a new GitHub Personal Access Token and giving it the name "FastLane Access Token"

2. 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
     • Edit the note box to be FastLane Access Token
   • The default Expiration time is 30 days - but you should select No expiration (use the dropdown 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 workflow permission scope
   • A check will automatically appear in the repo scope as well - this is normal
   • 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)

   

   What does repo and workflow do?

   • repo: enables manual build actions
   • workflow: enables repo and automatic build actions

3. 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 Personal Access Token for GH_PAT if you lose it, but then you have to update that in the Secrets for all repositories using GitHub Build.

   

Make up a Password

If you have not already made up a password, do it now and record it as MATCH_PASSWORD. Note that if you build more than one app, you use the same MATCH_PASSWORD for all the apps. Every app needs to have the same 6 Secrets.

What is this Password used for?

The MATCH_PASSWORD is a special password called a passphrase that is used to encrypt and decrypt your certificates from Apple so they can be used when building with GitHub; it helps keeps your certificates secret and safe.

A passphrase is a little different from a regular password. A password is what you usually use to log in to a website or game. A passphrase is a secret code that helps protect important files by adding an extra layer of security when files are encrypted.

Passphrase Suggestions

To make a passphrase that is hard to guess and keeps your certificates safe:

• Use at least 15 characters (20 is even better) and you can include spaces
• Mix in big letters, small letters, numbers, and symbols like $ or #
• Don’t use words or numbers that people might guess, like your name or birthday

If you already created a MATCH_PASSWORD that does not meet the criteria listed above, no worries, you are protecting an Apple developer certificate - not the family fortune. That information is provided for new builders who want guidance.

Next Step

The next step is to Prepare your Fork (Copy of LoopWorkspace).