diff --git a/.github/workflows/build_xdrip.yml b/.github/workflows/build_xdrip.yml index a5c5ba401..3f3806eb4 100644 --- a/.github/workflows/build_xdrip.yml +++ b/.github/workflows/build_xdrip.yml @@ -7,87 +7,222 @@ on: #push: schedule: - - cron: '0 04 * * *' # Checks for updates at 04:00 UTC every day - - cron: '0 04 1 * *' # Builds the app on the 1th every month + - cron: '0 8 * * 3' # Checks for updates at 08:00 UTC every Wednesday + - cron: '0 6 1 * *' # Builds the app on the 1st of every month at 06:00 UTC env: UPSTREAM_REPO: JohanDegraeve/xdripswift - UPSTREAM_BRANCH: ${{ github.ref_name }} # branch on upstream repository to sync from (relpace with specific branch name if needed) - TARGET_BRANCH: ${{ github.ref_name }} # target branch on fork to be kept in sync, and target branch on upstream to be kept alive (relpace with specific branch name if needed) - SYNC_UPSTREAM: 'true' # set to 'false' or 'true' to disable / enable syncing of fork with upstream repository - + UPSTREAM_BRANCH: ${{ github.ref_name }} # branch on upstream repository to sync from (replace with specific branch name if needed) + TARGET_BRANCH: ${{ github.ref_name }} # target branch on fork to be kept in sync, and target branch on upstream to be kept alive (replace with specific branch name if needed) + ALIVE_BRANCH: alive + jobs: validate: name: Validate uses: ./.github/workflows/validate_secrets.yml secrets: inherit + + # Checks if GH_PAT holds workflow permissions + # Checks for existence of alive branch; if non-existent creates it + check_alive_and_permissions: + needs: validate + runs-on: ubuntu-latest + name: Check alive branch and permissions + permissions: + contents: write + outputs: + WORKFLOW_PERMISSION: ${{ steps.workflow-permission.outputs.has_permission }} + + steps: + - name: Check for workflow permissions + id: workflow-permission + env: + TOKEN_TO_CHECK: ${{ secrets.GH_PAT }} + run: | + PERMISSIONS=$(curl -sS -f -I -H "Authorization: token ${{ env.TOKEN_TO_CHECK }}" https://api.github.com | grep ^x-oauth-scopes: | cut -d' ' -f2-); + + if [[ $PERMISSIONS =~ "workflow" || $PERMISSIONS == "" ]]; then + echo "GH_PAT holds workflow permissions or is fine-grained PAT." + echo "has_permission=true" >> $GITHUB_OUTPUT # Set WORKFLOW_PERMISSION to false. + else + echo "GH_PAT lacks workflow permissions." + echo "Automated build features will be skipped!" + echo "has_permission=false" >> $GITHUB_OUTPUT # Set WORKFLOW_PERMISSION to false. + fi + + - name: Check for alive branch + if: steps.workflow-permission.outputs.has_permission == 'true' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + if [[ "$(gh api -H "Accept: application/vnd.github+json" /repos/${{ github.repository_owner }}/xdripswift/branches | jq --raw-output 'any(.name=="alive")')" == "true" ]]; then + echo "Branch 'alive' exists." + echo "ALIVE_BRANCH_EXISTS=true" >> $GITHUB_ENV # Set ALIVE_BRANCH_EXISTS to true + else + echo "Branch 'alive' does not exist." + echo "ALIVE_BRANCH_EXISTS=false" >> $GITHUB_ENV # Set ALIVE_BRANCH_EXISTS to false + fi + - name: Create alive branch + if: env.ALIVE_BRANCH_EXISTS == 'false' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + # Get ref for JohanDegraeve/xdripswift:develop + SHA=$(curl -sS https://api.github.com/repos/${{ env.UPSTREAM_REPO }}/git/refs \ + | jq '.[] | select(.ref == "refs/heads/develop" ) | .object.sha' \ + | tr -d '"' + ); + + # Create alive branch based on JohanDegraeve/xdripswift:develop + gh api \ + --method POST \ + -H "Authorization: token $GITHUB_TOKEN" \ + -H "Accept: application/vnd.github.v3+json" \ + /repos/${{ github.repository_owner }}/xdripswift/git/refs \ + -f ref='refs/heads/alive' \ + -f sha=$SHA + + # Checks for changes in upstream repository; if changes exist prompts sync for build + # Performs keepalive to avoid stale fork check_latest_from_upstream: - needs: validate + needs: [validate, check_alive_and_permissions] runs-on: ubuntu-latest - name: Check upstream + name: Check upstream and keep alive outputs: NEW_COMMITS: ${{ steps.sync.outputs.has_new_commits }} - + steps: - name: Checkout target repo + if: | + needs.check_alive_and_permissions.outputs.WORKFLOW_PERMISSION == 'true' && + (vars.SCHEDULED_BUILD != 'false' || vars.SCHEDULED_SYNC != 'false') uses: actions/checkout@v3 with: - # optional: set the branch to checkout, - # sync action checks out your 'target_sync_branch' anyway - #submodules: recursive - ref: ${{ env.TARGET_BRANCH }} - - # REQUIRED step - # Step 2: run the sync action + token: ${{ secrets.GH_PAT }} + ref: alive + - name: Sync upstream changes - if: ${{ env.SYNC_UPSTREAM == 'true' }} && github.repository_owner != 'JohanDegraeve' # do not run the upstream sync action on the upstream repository + if: | # do not run the upstream sync action on the upstream repository + needs.check_alive_and_permissions.outputs.WORKFLOW_PERMISSION == 'true' && + vars.SCHEDULED_SYNC != 'false' && github.repository_owner != 'JohanDegraeve' id: sync uses: aormsby/Fork-Sync-With-Upstream-action@v3.4 with: - target_sync_branch: ${{ env.TARGET_BRANCH }} + target_sync_branch: ${{ env.ALIVE_BRANCH }} shallow_since: 6 months ago target_repo_token: ${{ secrets.GH_PAT }} upstream_sync_branch: ${{ env.UPSTREAM_BRANCH }} upstream_sync_repo: ${{ env.UPSTREAM_REPO }} - - # Step 3: Display a sample message based on the sync output var 'has_new_commits' + + # Display a sample message based on the sync output var 'has_new_commits' - name: New commits found - if: steps.sync.outputs.has_new_commits == 'true' + if: | + needs.check_alive_and_permissions.outputs.WORKFLOW_PERMISSION == 'true' && + vars.SCHEDULED_SYNC != 'false' && steps.sync.outputs.has_new_commits == 'true' run: echo "New commits were found to sync." - name: No new commits - if: steps.sync.outputs.has_new_commits == 'false' - run: echo echo "There were no new commits." - + if: | + needs.check_alive_and_permissions.outputs.WORKFLOW_PERMISSION == 'true' && + vars.SCHEDULED_SYNC != 'false' && steps.sync.outputs.has_new_commits == 'false' + run: echo "There were no new commits." + - name: Show value of 'has_new_commits' + if: needs.check_alive_and_permissions.outputs.WORKFLOW_PERMISSION == 'true' && vars.SCHEDULED_SYNC != 'false' run: | echo ${{ steps.sync.outputs.has_new_commits }} echo "NEW_COMMITS=${{ steps.sync.outputs.has_new_commits }}" >> $GITHUB_OUTPUT - - # Keep repository "alive": add empty commits to TARGET_BRANCH after "time_elapsed" days of inactivity to avoid inactivation of scheduled workflows + + # Keep repository "alive": add empty commits to ALIVE_BRANCH after "time_elapsed" days of inactivity to avoid inactivation of scheduled workflows - name: Keep alive - if: github.ref == 'refs/heads/${{ env.TARGET_BRANCH }}' + if: | + needs.check_alive_and_permissions.outputs.WORKFLOW_PERMISSION == 'true' && + (vars.SCHEDULED_BUILD != 'false' || vars.SCHEDULED_SYNC != 'false') uses: gautamkrishnar/keepalive-workflow@v1 # using the workflow with default settings with: - time_elapsed: 50 # Time elapsed from the previous commit to trigger a new automated commit (in days) - + time_elapsed: 20 # Time elapsed from the previous commit to trigger a new automated commit (in days) + + - name: Show scheduled build configuration message + if: needs.check_alive_and_permissions.outputs.WORKFLOW_PERMISSION != 'true' + run: | + echo "### :calendar: Scheduled Sync and Build Disabled :mobile_phone_off:" >> $GITHUB_STEP_SUMMARY + echo "You have not yet configured the scheduled sync and build for xDrip4iOS' browser build." >> $GITHUB_STEP_SUMMARY + echo "Synchronizing your fork of xdripswift with the upstream repository JohanDegraeve/xdripswift will be skipped." >> $GITHUB_STEP_SUMMARY + echo "If you want to enable automatic builds and updates for your xDrip4iOS, please follow the instructions \ + under the following path xdripswift/fastlane/testflight.md." >> $GITHUB_STEP_SUMMARY + + # Builds xDrip4iOS build: - needs: [validate, check_latest_from_upstream] + name: Build + needs: [validate, check_alive_and_permissions, check_latest_from_upstream] runs-on: macos-13 - if: ${{ github.event_name == 'workflow_dispatch' || github.event.schedule == '0 04 1 * *' || needs.check_latest_from_upstream.outputs.NEW_COMMITS == 'true' }} # runs if started manually, or if scheduled on the first each month, or if new commits were found + permissions: + contents: write + if: | # runs if started manually, or if sync schedule is set and enabled and scheduled on the first Saturday each month, or if sync schedule is set and enabled and new commits were found + github.event_name == 'workflow_dispatch' || + (needs.check_alive_and_permissions.outputs.WORKFLOW_PERMISSION == 'true' && + (vars.SCHEDULED_BUILD != 'false' && github.event.schedule == '0 6 1 * *') || + (vars.SCHEDULED_SYNC != 'false' && needs.check_latest_from_upstream.outputs.NEW_COMMITS == 'true' ) + ) steps: - name: Select Xcode version run: "sudo xcode-select --switch /Applications/Xcode_15.0.app/Contents/Developer" - - # Checks-out the repo - - name: Checkout Repo + + - name: Checkout Repo for syncing + if: | + needs.check_alive_and_permissions.outputs.WORKFLOW_PERMISSION == 'true' && + vars.SCHEDULED_SYNC != 'false' uses: actions/checkout@v3 + with: + token: ${{ secrets.GH_PAT }} + ref: ${{ env.TARGET_BRANCH }} + - name: Sync upstream changes + if: | # do not run the upstream sync action on the upstream repository + needs.check_alive_and_permissions.outputs.WORKFLOW_PERMISSION == 'true' && + vars.SCHEDULED_SYNC != 'false' && github.repository_owner != 'JohanDegraeve' + id: sync + uses: aormsby/Fork-Sync-With-Upstream-action@v3.4 + with: + target_sync_branch: ${{ env.TARGET_BRANCH }} + shallow_since: 6 months ago + target_repo_token: ${{ secrets.GH_PAT }} + upstream_sync_branch: ${{ env.UPSTREAM_BRANCH }} + upstream_sync_repo: ${{ env.UPSTREAM_REPO }} + + # Display a sample message based on the sync output var 'has_new_commits' + - name: New commits found + if: | + needs.check_alive_and_permissions.outputs.WORKFLOW_PERMISSION == 'true' && + vars.SCHEDULED_SYNC != 'false' && steps.sync.outputs.has_new_commits == 'true' + run: echo "New commits were found to sync." + + - name: No new commits + if: | + needs.check_alive_and_permissions.outputs.WORKFLOW_PERMISSION == 'true' && + vars.SCHEDULED_SYNC != 'false' && steps.sync.outputs.has_new_commits == 'false' + run: echo "There were no new commits." + + - name: Show value of 'has_new_commits' + if: | + needs.check_alive_and_permissions.outputs.WORKFLOW_PERMISSION == 'true' + && vars.SCHEDULED_SYNC != 'false' + run: | + echo ${{ steps.sync.outputs.has_new_commits }} + echo "NEW_COMMITS=${{ steps.sync.outputs.has_new_commits }}" >> $GITHUB_OUTPUT + + - name: Checkout Repo for building + uses: actions/checkout@v3 + with: + token: ${{ secrets.GH_PAT }} + submodules: recursive + ref: ${{ env.TARGET_BRANCH }} + # Patch Fastlane Match to not print tables - name: Patch Match Tables run: find /usr/local/lib/ruby/gems -name table_printer.rb | xargs sed -i "" "/puts(Terminal::Table.new(params))/d" - + # Install project dependencies - name: Install project dependencies run: bundle install @@ -122,4 +257,4 @@ jobs: name: build-artifacts path: | artifacts - buildlog + buildlog \ No newline at end of file diff --git a/fastlane/testflight.md b/fastlane/testflight.md index f8621872e..231e73998 100644 --- a/fastlane/testflight.md +++ b/fastlane/testflight.md @@ -1,4 +1,4 @@ -# Using Github Actions + FastLane to deploy to TestFlight +# Using GitHub Actions + FastLane to deploy to TestFlight These instructions allow you to build xDrip4iOS without having access to a Mac. @@ -7,10 +7,27 @@ These instructions allow you to build xDrip4iOS without having access to a Mac. * You can install xDrip4iOS on your phone using only the TestFlight app if a phone was lost or the app is accidentally deleted * You do not need to worry about specific Xcode/Mac versions for a given iOS -The setup steps are somewhat involved, but nearly all are one time steps. Subsequent builds are trivial. Your app must be updated once every 90 days, but it's a simple click to make a new build and can be done from anywhere. The 90-day update is a TestFlight requirement, which can be automated. +## **Automatic Builds** +> +> This new version of the browser build **defaults to** automatically updating and building a new version of xDrip4iOS according to this schedule: +> - automatically checks for updates weekly on Wednesdays and if updates are found, it will build a new version of the app +> - automatically builds once a month regardless of whether there are updates on the first of the month +> - with each scheduled run (weekly or monthly), a successful Build xDrip4iOS log appears - if the time is very short, it did not need to build - only the long actions (>20 minutes) built a new xDrip4iOS app +> +> 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. 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 or iAPS), 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. +> **Repeat Builders** +> - to enable automatic build, your `GH_PAT` token must have `workflow` scope +> - if you previously configured your `GH_PAT` without that scope, see [`GH_PAT` `workflow` permission](#gh_pat-workflow-permission) + +## 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. The 90-day update is a TestFlight requirement, and with this version of xDrip4iOS, the build process (once you've successfully built once) is automated to update and build at least once a month. + There are more detailed instructions in LoopDocs for using GitHub for Browser Builds of Loop, including troubleshooting and build errors. Please refer to: * [LoopDocs: GitHub Overview](https://loopkit.github.io/loopdocs/gh-actions/gh-overview/) @@ -20,65 +37,87 @@ Note that installing with TestFlight, (in the US), requires the Apple ID account ## Prerequisites -* A [github account](https://github.com/signup). The free level comes with plenty of storage and free compute time to build Xdrip4iOS, multiple times a day, if you wanted to. -* A paid [Apple Developer account](https://developer.apple.com). You may be able to use the free version, but that has not been tested. -* Some time. Set aside a couple of hours to perform the setup. -* Use the same GitHub account for all "Browser Builds" of the various DIY apps. +* A [GitHub account](https://github.com/signup). The free level comes with plenty of storage and free compute time to build xDrip4iOS, multiple times a day, if you wanted to. +* A paid [Apple Developer account](https://developer.apple.com). +* Some time. Set aside a couple of hours to perform the setup. + +## Save 6 Secrets + +You require 6 Secrets (alphanumeric items) to use the GitHub build method and if you use the GitHub method to build more than xDrip4iOS, e.g., Loop Follow or other apps, you will use the same 6 Secrets for each app you build with this method. Each secret is indentified below by `ALL_CAPITAL_LETTER_NAMES`. + +* Four Secrets are from your Apple Account +* Two Secrets are from your GitHub account +* Be sure to save the 6 Secrets in a text file using a text editor + - Do **NOT** use a smart editor, which might auto-correct and change case, because these Secrets are case sensitive ## Generate App Store Connect API Key -This step is common for all "Browser Builds", and should be done ony once. Please save the API key somewhere safe, so it can be re-used for other builds, or if needing to start from scratch. +This step is common for all GitHub Browser Builds; do this step only once. You will be saving 4 Secrets from your Apple Account in this step. 1. Sign in to the [Apple developer portal page](https://developer.apple.com/account/resources/certificates/list). -1. Copy the team id from the upper right of the screen. Record this as your `TEAMID`. -1. Go to the [App Store Connect](https://appstoreconnect.apple.com/access/api) interface, click the "Keys" tab, and create a new key with "Admin" access. Give it a name like "FastLane API Key". -1. Record the key id; this will be used for `FASTLANE_KEY_ID`. +1. Copy the Team ID from the upper right of the screen. Record this as your `TEAMID`. +1. Go to the [App Store Connect](https://appstoreconnect.apple.com/access/api) interface, click the "Keys" tab, and create a new key with "Admin" access. Give it the name: "FastLane API Key". 1. Record the issuer id; this will be used for `FASTLANE_ISSUER_ID`. +1. Record the key id; this will be used for `FASTLANE_KEY_ID`. 1. Download the API key itself, and open it in a text editor. The contents of this file will be used for `FASTLANE_KEY`. Copy the full text, including the "-----BEGIN PRIVATE KEY-----" and "-----END PRIVATE KEY-----" lines. -## Setup Github Match-Secrets repository - -This is also a common step for all "browser builds", do this step only once -1. Create a [new empty repository](https://github.com/new) titled `Match-Secrets`. It should be private. +## Create GitHub Personal Access Token -## Setup Github xdripswift repository -1. Fork https://github.com/JohanDegraeve/xdripswift into your account. If you already have a fork of Xdrip4iOS 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/JohanDegraeve/xdripswift. +Log into your GitHub account to create a personal access token; this is one of two GitHub secrets needed for your build. -If you have previously built Loop or another app using the "browser build" method, you can can re-use your previous personal access token (`GH_PAT`) and skip ahead to `step 2`. 1. Create a [new personal access token](https://github.com/settings/tokens/new): - * Enter a name for your token. Something like "FastLane Access Token". + * Enter a name for your token, use "FastLane Access Token". * Change the Expiration selection to `No expiration`. - * Select the `repo` and `workflow` permission scopes. + * Select the `workflow` permission scope - this also selects `repo` scope. * Click "Generate token". * Copy the token and record it. It will be used below as `GH_PAT`. -1. In the forked Xdrip4iOS repo, go to Settings -> Secrets -> Actions. + +## Make up a Password + +This is the second one of two GitHub secrets needed for your build. + +The first time you build with the GitHub Browser Build method for any DIY app, you will make up a password and record it as `MATCH_PASSWORD`. Note, if you later lose `MATCH_PASSWORD`, you will need to delete and make a new Match-Secrets repository (next step). + +## Setup GitHub Match-Secrets Repository + +The creation of the Match-Secrets repository is a common step for all GitHub Browser Builds; do this step only once. You must be logged into your GitHub account. + +1. Create a [new empty repository](https://github.com/new) titled `Match-Secrets`. It should be private. + +Once created, you will not take any direct actions with this repository; it needs to be there for the GitHub to use as you progress through the steps. + +## Setup GitHub xdripswift Repository + +1. Fork https://github.com/JohanDegraeve/xdripswift into your account. +1. In the forked xdripswift repo, go to Settings -> Secrets and variables -> Actions. 1. For each of the following secrets, tap on "New repository secret", then add the name of the secret, along with the value you recorded for it: * `TEAMID` - * `FASTLANE_KEY_ID` * `FASTLANE_ISSUER_ID` + * `FASTLANE_KEY_ID` * `FASTLANE_KEY` * `GH_PAT` - * `MATCH_PASSWORD` - just make up a password for this + * `MATCH_PASSWORD` ## Validate repository secrets -1. Click on the "Actions" tab of your Xdrip4iOS repository. -1. Select "1. Validate Secrets". -1. Click "Run Workflow", and tap the green button. +This step validates most of your six Secrets and provides error messages if it detects an issue with one or more. + +1. Click on the "Actions" tab of your xdripswift repository and enable workflows if needed +1. On the left side, select "1. Validate Secrets". +1. On the right side, click "Run Workflow", and tap the green `Run workflow` button. 1. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded. -1. The workflow will check if the required secrets are added and that they are correctly formatted. If errors are detected, please check the run log for details. +1. The workflow will check if the required secrets are added and that they are correctly formatted. If errors are detected, please check the run log for details. -## Add Identifiers for Xdrip4iOS App +## Add Identifiers for xDrip4iOS App -1. Click on the "Actions" tab of your Xdrip4iOS repository. -1. Select "2. Add Identifiers". -1. Click "Run Workflow", and tap the green button. +1. Click on the "Actions" tab of your xdripswift repository. +1. On the left side, select "2. Add Identifiers". +1. On the right side, click "Run Workflow", and tap the green `Run workflow` button. 1. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded. ## Create App Group -If you have already built Xdrip4iOS via Xcode using this Apple ID, you can skip on to [Create Xdrip4iOS App in App Store Connect](#create-Xdrip4iOS-app-in-app-store-connect). -_Please note that in default builds of Xdrip4iOS, 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 Loop or FreeAPS X. It may require some caution if transfering between FreAPS X and Loop._ +If you have already built Loop via Xcode using this Apple ID, you can skip on to [Add App Group to Bundle Identifiers](#add-app-group-to-bundle-identifiers). 1. Go to [Register an App Group](https://developer.apple.com/account/resources/identifiers/applicationGroup/add/) on the apple developer site. 1. For Description, use "Loop App Group". @@ -87,12 +126,15 @@ _Please note that in default builds of Xdrip4iOS, the app group is actually iden ## Add App Group to Bundle Identifiers +Note 1 - If you previously built with Xcode, the `Names` listed below may be different, but the `Identifiers` will match. A table is provided below the steps to assist. The Add Identifier Action that you completed above generates 6 identifiers, but only 4 need to be modified as indicated in this step. + +Note 2 - Depending on your build history, you may find some of the Identifiers are already configured - and you are just verifying the status; but in other cases, you will need to configure the Identifiers. + 1. Go to [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list) on the apple developer site. 1. For each of the following identifier names: * xdripswift * xdripswift xDrip4iOS-Widget * Watch App - * Watch App WatchKit Extension 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)_ @@ -116,20 +158,101 @@ If you have created a Xdrip4iOS app in App Store Connect before, you can skip th You do not need to fill out the next form. That is for submitting to the app store. -## Create Building Certficates +## Create Building Certificates -1. Go back to the "Actions" tab of your Xdrip4iOS repository in github. -1. Select "3. Create Certificates". -1. Click "Run Workflow", and tap the green button. +1. Go back to the "Actions" tab of your xdripswift repository in GitHub. +1. On the left side, select "3. Create Certificates". +1. On the right side, click "Run Workflow", and tap the green `Run workflow` button. 1. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded. ## Build Xdrip4iOS! -1. Click on the "Actions" tab of your Xdrip4iOS repository. -1. Select "4. Build Xdrip4iOS". _Are you working on a previuos fork of Xdrip4iOS and not seeing any GitHub workflows in the Actions tab? You may have to change the default branch so that it contains the .github/workflows files, or merge these changes into your default branch (typically `master`)._ -1. Click "Run Workflow", select your branch, and tap the green button. -1. You have some time now. Go enjoy a coffee. The build should take about 15 minutes. +1. Click on the "Actions" tab of your xdripswift repository. +1. On the left side, select "4. Build xDrip4iOS". +1. On the right side, click "Run Workflow", and tap the green `Run workflow` button. +1. You have some time now. Go enjoy a coffee. The build should take about 20-30 minutes. 1. Your app should eventually appear on [App Store Connect](https://appstoreconnect.apple.com/apps). -1. For each phone/person you would like to support Xdrip4iOS on: +1. For each phone/person you would like to support xDrip4iOS on: * Add them in [Users and Access](https://appstoreconnect.apple.com/access/users) on App Store Connect. * Add them to your TestFlight Internal Testing group. + +## TestFlight and Deployment Details + +Please refer to [LoopDocs: Set Up Users](https://loopkit.github.io/loopdocs/gh-actions/gh-first-time/#set-up-users-and-access-testflight) and [LoopDocs: Deploy](https://loopkit.github.io/loopdocs/gh-actions/gh-deploy/) + +## Automatic Build FAQs + +### Why do I have an `alive` branch? + +If a GitHub repository has no activity (no commits are made) in 60 days, then GitHub disables the ability to use automated actions for that repository. We need to take action more frequently than that or the automated build process won't work. + +The updated `build_xdrip.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 xDrip4iOS 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 xdripswift 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 xDrip4iOS 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 \ No newline at end of file