Merge branch 'alpha' into fix-setting-of-bg-targets

fastlane/testflight.md

@@ -16,6 +16,7 @@ These instructions allow you to build Trio without having access to a Mac.
 > 
 > It also creates an alive branch, if you don't already have one. See [Why do I have an alive branch?](#why-do-i-have-an-alive-branch).
 >
+> The [**Optional**](#optional) section provides instructions to modify the default behavior if desired. >
 
 ## Introduction
 
@@ -181,3 +182,70 @@ If a GitHub repository has no activity (no commits are made) in 60 days, then Gi
 The `build_trio.yml` file uses a special branch called `alive` and adds a dummy commit to the `alive` branch at regular intervals. This "trick" keeps the Actions enabled so the automated build works.
 
 The branch `alive` is created automatically for you. Do not delete or rename it! Do not modify `alive` yourself; it is not used for building the app.
+
+## OPTIONAL
+
+What if you don't want to allow automated updates of the repository or automatic builds?
+
+You can affect the default behavior:
+
+1. [`GH_PAT` `workflow` permission](#gh_pat-workflow-permission)
+1. [Modify scheduled building and synchronization](#modify-scheduled-building-and-synchronization)
+
+### `GH_PAT` `workflow` permission
+
+To enable the scheduled build and sync, the `GH_PAT` must hold the `workflow` permission scopes. This permission serves as the enabler for automatic and scheduled builds with browser build. To verify your token holds this permission, follow these steps.
+
+1. Go to your [FastLane Access Token](https://github.com/settings/tokens)
+2. It should say `repo`, `workflow` next to the `FastLane Access Token` link
+3. If it does not, click on the link to open the token detail view
+4. Click to check the `workflow` box. You will see that the checked boxes for the `repo` scope become disabled (change color to dark gray and are not clickable)
+5. Scroll all the way down to and click the green `Update token` button
+6. Your token now holds both required permissions
+
+If you choose not to have automatic building enabled, be sure the `GH_PAT` has `repo` scope or you won't be able to manually build.
+
+### Modify scheduled building and synchronization
+
+You can modify the automation by creating and using some variables.
+
+To configure the automated build more granularly involves creating up to two environment variables: `SCHEDULED_BUILD` and/or `SCHEDULED_SYNC`. See [How to configure a variable](#how-to-configure-a-variable). 
+
+Note that the weekly and monthly Build Trio actions will continue, but the actions are modified if one or more of these variables is set to false. **A successful Action Log will still appear, even if no automatic activity happens**.
+
+* If you want to manually decide when to update your repository to the latest commit, but you want the monthly builds and keep-alive to continue: set `SCHEDULED_SYNC` to false and either do not create `SCHEDULED_BUILD` or set it to true
+* If you want to only build when an update has been found: set `SCHEDULED_BUILD` to false and either do not create `SCHEDULED_SYNC` or set it to true
+    * **Warning**: if no updates to your default branch are detected within 90 days, your previous TestFlight build may expire requiring a manual build
+
+|`SCHEDULED_SYNC`|`SCHEDULED_BUILD`|Automatic Actions|
+|---|---|---|
+| `true` (or NA) | `true` (or NA) | keep-alive, weekly update check (auto update/build), monthly build with auto update|
+| `true` (or NA) | `false` | keep-alive, weekly update check with auto update, only builds if update detected|
+| `false` | `true` (or NA) | keep-alive, monthly build, no auto update |
+| `false` | `false` | no automatic activity, no keep-alive|
+
+### How to configure a variable
+
+1. Go to the "Settings" tab of your Trio repository.
+2. Click on `Secrets and Variables`.
+3. Click on `Actions`
+4. You will now see a page titled *Actions secrets and variables*. Click on the `Variables` tab
+5. To disable ONLY scheduled building, do the following:
+    - Click on the green `New repository variable` button (upper right)
+    - Type `SCHEDULED_BUILD` in the "Name" field
+    - Type `false` in the "Value" field
+    - Click the green `Add variable` button to save.
+7. To disable scheduled syncing, add a variable:
+    - Click on the green `New repository variable` button (upper right)
+    - - Type `SCHEDULED_SYNC` in the "Name" field
+    - Type `false` in the "Value" field
+    - Click the green `Add variable` button to save
+  
+Your build will run on the following conditions:
+- Default behaviour:
+    - Run weekly, every Wednesday at 08:00 UTC to check for changes; if there are changes, it will update your repository and build
+    - Run monthly, every first of the month at 06:00 UTC, if there are changes, it will update your repository; regardless of changes, it will build
+    - Each time the action runs, it makes a keep-alive commit to the `alive` branch if necessary
+- If you disable any automation (both variables set to `false`), no updates, keep-alive or building happens when Build Trio runs
+- If you disabled just scheduled synchronization (`SCHEDULED_SYNC` set to`false`), it will only run once a month, on the first of the month, no update will happen; keep-alive will run
+- If you disabled just scheduled build (`SCHEDULED_BUILD` set to`false`), it will run once weekly, every Wednesday, to check for changes; if there are changes, it will update and build; keep-alive will run