Skip to content

Latest commit

 

History

History
260 lines (179 loc) · 14.3 KB

prepare-fork.md

File metadata and controls

260 lines (179 loc) · 14.3 KB

Fork LoopWorkspace

???+ tip "Are you a Caregiver? Are you planning to build more than one app? (Click to close/open)" Did you skip the optional section to Create a Free GitHub Organization{: target="_blank" }?

If you plan to build more that one app and use your personal account, you must add the 6 <code>Secrets</code> to each repository for each app. It is not hard but it can get tiresome.

If you make use of the organization option, you only enter the 6 <code>Secrets</code> one time for all your repositories. This is strongly recommended, but not required, for all Browser Builders.

???+ abstract "Section Summary (click to open/close)" Fork https://github.com/LoopKit/LoopWorkspace{: target="_blank" } into your account.

[<span class="loop-bigger">:material-skip-forward:</span>](#configure-secrets) To skip the detailed instructions, click on [Configure <code>Secrets</code>](#configure-secrets)

!!! warning "Existing Fork" If you already have a fork of LoopWorkspace, click on Already Have LoopWorkspace to decide what to do. That section provides links to return you to these instructions.

Create the Fork

  1. Click this link https://github.com/LoopKit/LoopWorkspace{: target="_blank" } to open the LoopWorkspace repository owned by LoopKit

  2. At the upper right side of the screen, click on the word Fork

    fork information for LoopWorkspace{width="700"} {align="center"}

  3. Refer the the GIF below:

    • If you created a free organization (strongly recommended), you will see the display shown in the GIF below where you will choose your organization as the owner
      • If you did not set up a free organization, my-name will be automatically filled in as the owner (Owner)
    • If you already have a fork, you should not proceed, see Already Have a LoopWorkspace
    • The repository name is already filled in
      • Do not rename the repository to something else
      • It needs to match the original repository name or automatic building will not work
    • Leave the selection that says "Copy the main branch only" checked
    • Click on the green Create fork button

    fork information for LoopWorkspace{width="700"} {align="center"}

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 :octicons-x-16: (x) to dismiss the Successfully fetched message
  • In the middle, click on the Dismiss button to remove the "Your branch is not protected" message

after creating the fork LoopWorkspace{width="500"} {align="center"}

Carefully compare your screen to the graphic below paying attention to the highlighted sections.

  • Note that your URL is https://github.com/my-name-org/LoopWorkspace or https://github.com/my-name/LoopWorkspace where my-name is the name you chose:
    • Many graphics for LoopDocs are created using a free GitHub organization called loopdocs-tester
  • The comment on the second row indicates where the  fork  came from (that is a clickable link)
  • The branch that is selected :octicons-git-branch-16: is main
  • The message says "This branch is up to date with LoopKit/LoopWorkspace:main"

after creating the fork LoopWorkspace{width="700"} {align="center"}

Configure Secrets

If you set up a GitHub organization (strongly recommended), follow this set of instructions.

If you decided to not to use a GitHub organization, skip ahead to Personal Account: Prepare to Enter Secrets.

!!! tip "What if I already have a bunch of forks in my personal account?" You do not have to switch to an organization. But if you want to make the move, follow instructions here Switch to a GitHub Organization

Prepare to Enter Secrets

You will be adding Secrets and Variables to your organization. This makes them available to any app you decide to build as long as you set up your free GitHub organization as the owner of the fork.

  1. Tap on this GitHub link{: target="_blank" } to see your organizations. (If you don't see a screen similar to the graphic below - you are not logged in to GitHub).

    settings screen{width="700"} {align="center"}

  2. Choose your organization name from the list (most people will only see one organization)

    • I chose loopdocs-tester as my organization, so you will see that name in the URL for graphics in this section.

    settings screen{width="700"} {align="center"}

  3. Click on the Settings Icon near the top right

    • If you don't see ⚙️ Settings, make your browser wider or scroll to the right
    • After you click on ⚙️ Settings, your screen will show a lot of menu items on the left side of the screen.
    • Scroll down until you can see the Security section with Secrets and variables drop down.
    • Click on the dropdown icon and then selection Actions

    settings screen{width="600"} {align="center"}

  4. Your screen should now look like the graphic below. Note that the Secret tab is automatically selected.

    action secrets and variables screen{width="700"} {align="center"}

The next steps are identical whether you are configuring your organizations Secrets and Variables or doing this for every repository in a private account.

Personal Account: Prepare to Enter Secrets

This section is only if you are using a personal GitHub account to build. Using an organization is recommended.

Log into GitHub.

  1. Return to your forked copy of LoopWorkspace

    • Click on your personal icon at the upper right to see the dropdown menu and select "Your repositories"

    dropdown-menu{width="200"} {align="center"}

  2. Click on LoopWorkspace to open that repository

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

      settings screen{width="700"} {align="center"}

  4. On the left side, find the Secrets and variables dropdown and choose Actions

At this point the instructions are the same whether you are using an organization or a personal account.

Enter the Secrets

The steps to enter the Secrets and Variables are identical whether you are configuring these in your organization account or repeating this for every repository in a private account.

Your screen should look like the graphic below. If not head back to Configure Secrets. Note that the Secret tab is automatically selected.

action secrets and variables screen{width="700"} {align="center"}

  1. Tap on the green button at the top right of your screen labeled New repository secret (highlighted above)
    • A new screen appears as shown in the first graphic below
    • Do not do anything until reading the sub-bullets, examining the graphics, and proceeding to the next section where each Secret name is provided for you to copy and paste
      • Under Name *, click on YOUR_SECRET_NAME and paste one of the 6 secret names, as directed in Enter Each Secret
      • Click inside the Secret * box and paste the value for that secret
      • Once you click on Add Secret, the secret will be added
      • The second graphic below shows TEAMID added and ready for save

dialog for entering a new secret{width="700"} {align="center"}

teamid secret ready to be saved{width="700"} {align="center"}

Enter Each Secret

Enter the name of each Secret found in Save Your Information and your value for that Secret.

  • Once you save a secret value, you will not be able to view what you entered, so check carefully before you hit Add Secret
    • You can replace the value for any secret later - but you can't view the saved value
  • Be especially careful with your TEAMID
    • If TEAMID is incorrect, the initial Actions will succeed but Build Loop will fail and you will have some clean-up to do

You can copy the names of the Secrets by hovering to the right of each word below until you see the copy button (:material-content-copy:). Click on the button to copy the Secret name and paste it into GitHub where you see YOUR_SECRET_NAME. This avoids 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 - if you did not already make up a password and save it with your other Secrets, do it now
    • The MATCH_PASSWORD must be the same for any repository using this method (Other Apps{: target="_blank" })

Once all six Secrets have been added to your LoopWorkspace, your screen should look similar to the graphic below.

  • Check that all of your Secrets are spelled correctly
  • If one is misspelled, delete it and add a New repository secret with the correct name

all secrets entered{width="700"} {align="center"}

Add Variable

This is a new step. It will be used when Loop 3.6.0 is released. This enables automatic generation and renewal of the certificates needed to build your app.

  1. While in the same screen where you enter the Secrets, click on the Variables tab to the right of the Secrets tab:
  2. Select new variable and give it the name the ENABLE_NUKE_CERTS and enter true as the value
ENABLE_NUKE_CERTS

What did you just do?

  • When Loop 3.6.0 is released, certificates will be automatically updated if you have configured this Variable
  • After Loop 3.6.0 is released, as long as your Apple developers license is valid and all agreements are signed: you can skip the steps to create or renew your certificates!

enable nuke certs{width="700"} {align="center"}

Next Step

The next step is to Validate Secrets and Add Identifiers.

Switch to a GitHub Organization

If you are someone who already has a lot of forks in your personal account and want to switch to using a GitHub organization. Here's how:

  1. Follow the steps to create your organization
  2. Add the Secrets and the Variable as explained in Prepare to Enter Secrets
  3. Fork all the repos you normally use, but this time, set your organization as the owner
  4. For each repository in your organization:
    • Tap on the Actions tab
    • Enable Actions
    • Run the Create Certificates Action and wait for success
    • Run the Build Action
      • WHAT??
      • That's right - all the setup is done on the Apple side and you already did that
      • If you succeesfully built with your private GitHub account, everything is already configured
      • The one thing you might want to do is copy customizations from your private account fork to the organization fork
  5. Return to your private GitHub account

Important

Your personal GitHub account is still needed. The free organization points to your private account as a member. If you delete your personal GitHub account, you lose access to your organization account too.

Already Have LoopWorkspace?

Some people may already have a copy (fork) of LoopWorkspace.

If your copy (fork) is not from LoopKit, follow the Delete and Start Fresh directions.

If your copy (fork) is from LoopKit:

  • Open your LoopWorkspace repository (https://github.com/my-name-org/LoopWorkspace) where you use your version of my-name in the URL
  • Review the graphic in the Configure: 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 Validate Secrets and Add Identifiers

Delete and Start Fresh

If your fork is not from LoopKit:

  • Delete your LoopWorkspace repository
    • Instructions to delete a repository are found at GitHub Docs{: target="_blank" }
  • Return to Fork LoopWorkspace and follow all the instructions