Skip to content

Commit 80893c1

Browse files
psonnerapsonnera
committed
Update browser build documentation
1 parent b50a7f0 commit 80893c1

26 files changed

Lines changed: 122 additions & 80 deletions

‎aaps-builder/README.md‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ everything that can run there must come from an approved AAPS source:
3131
- clones the AAPS source from `github.com/nightscout/AndroidAPS` (release tags),
3232
- uses GitHub's own actions `actions/setup-java@v5` and `actions/upload-artifact@v7`
3333
(tags, like nightscout's own `aaps-ci.yml`),
34-
- talks to `api.github.com` (its own repository: visibility check, `built/…` tags)
34+
- talks to `api.github.com` (read-only: its own repository's visibility check)
3535
and, only with the optional `GDRIVE_OAUTH2` secret, to Google
3636
(`oauth2.googleapis.com`, `www.googleapis.com`) — the same endpoints as
3737
nightscout's `aaps-ci.yml`.
@@ -41,6 +41,14 @@ everything that can run there must come from an approved AAPS source:
4141
repository for updates. Workflow changes are announced in the docs
4242
(Docs updates page and the AAPS Builder page); users replace the file
4343
themselves with the newer version from the setup page.
44+
- **No automatic builds** (regulatory requirement): the only trigger is
45+
`workflow_dispatch`. Every build is started by the user, with the version and
46+
variant they choose. No `schedule`, no repository variables that change what
47+
is built, and the workflow token is read-only (`contents: read` everywhere):
48+
the build cannot write anything to the user's repository.
49+
50+
Review check before every change, in addition to the host list: the `on:`
51+
block contains only `workflow_dispatch`, and no `permissions:` line says `write`.
4452

4553
Review check before every change:
4654

@@ -79,15 +87,19 @@ notices kept in the files):
7987
variables, English-only texts, error messages point to the docs page.
8088
3. Setup page: English only (no language switch), seven steps, texts in the
8189
HTML, forge served locally, Content-Security-Policy, links to the docs
82-
relative so they follow the version and language being read, "Desktop site"
83-
hint for GitHub's mobile build page.
90+
relative so they follow the version and language being read, a scrolling
91+
hint for GitHub's mobile build page (swipe on the text, not on the job diagram).
92+
4. Workflow version 2: removed the weekly `schedule` trigger, the `AUTO_BUILD`
93+
and `AUTO_VARIANT` repository variables, the quiet skipping of scheduled runs
94+
and the `built/<version>-<variant>` tags that remembered scheduled builds.
95+
Permissions reduced to `contents: read`.
8496

8597
## Checksums (of the committed files, LF line endings)
8698

8799
```
88-
SHA-256(aaps-builder.html) = bd508a5c3418a4283d55818df2b43273673bc5d3493f6a70e49c97d12c2a981b
100+
SHA-256(aaps-builder.html) = 016a4d6231168e1ce69f15ec5558171371f8474510601feb4db7768aa579e9fa
89101
SHA-256(aaps-builder.app.js) = 000b7fbfc31e0c4ecdacafb4059e164f1ba33f41371de4ec832a720c4bb2a55f
90-
SHA-256(aaps-builder-build.yml) = d910dc80934e18d819b4541f449eaf7bf0342c5b73f1b5f568063aaae6c1f7f8
102+
SHA-256(aaps-builder-build.yml) = 3d96ef0b329b4d08c20bea62c9b5a38d7920259628bddf5ed0d8b18226b1c83e
91103
SHA-256(aaps-builder.forge.min.js) = dc67fd132427ad96c9666c844b39565413c40ddb1f2d063c53512fbf6d387dfd
92104
```
93105

@@ -106,8 +118,8 @@ endings and a different hash. Check the committed content instead:
106118
line (`# AAPS Builder build workflow, version N`). The setup page shows this
107119
number when the user copies the workflow.
108120
2. Run the review check above.
109-
3. Update the docs page if steps, timings, artifacts, variants, variables
110-
(`AUTO_BUILD`, `AUTO_VARIANT`) or error messages changed, and add an entry to
121+
3. Update the docs page if steps, timings, artifacts, variants or error
122+
messages changed, and add an entry to
111123
`docs/EN/Maintenance/DocumentationUpdate.md` telling users to replace their
112124
workflow file.
113125
4. Test with a private test repository: copy the workflow from a local build of

‎docs/EN/Maintenance/DocumentationUpdate.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
## October 2026
44

5+
- [Browser build with AAPS Builder](#aaps-builder): build workflow version 2. Automatic weekly builds are removed (no schedule, no `AUTO_BUILD` / `AUTO_VARIANT` variables, no `built/…` tags): every build is started by you, with the version and variant you choose, and the workflow only has read access to your repository. If your `.github/workflows/build.yml` says version 1, replace it as explained in [Updating AAPS](#aaps-builder-updates). Added screenshots for every step @psonnera
56
- [Browser build with AAPS Builder](#aaps-builder): the build workflow is now part of this documentation. No template repository: you create an empty private repository and add the workflow from the setup page (new step 2). The workflow no longer checks an outside repository for updates. If you created your repository from the earlier template, replace `.github/workflows/build.yml` with the workflow from the setup page as explained in [Updating AAPS](#aaps-builder-updates) @psonnera
67
- New page [Browser build with AAPS Builder](#aaps-builder): build AAPS from an Android phone with a setup page hosted on this site, with automatic weekly builds and no preparation file. It replaces the Android instructions of the browser build (File Manager Plus pages removed). AAPS Builder created by @dio99, docs @psonnera
78

‎docs/EN/Maintenance/UpdateBrowserBuild.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Update with a browser
22

33
```{tip}
4-
You built AAPS with **AAPS Builder**? You don't need this page: new AAPS versions are built automatically every week. See [Updating AAPS with AAPS Builder](#aaps-builder-updates).
4+
You built AAPS with **AAPS Builder**? You don't need this page: see [Updating AAPS with AAPS Builder](#aaps-builder-updates).
55
```
66

77
## Build yourself instead of download

‎docs/EN/SettingUpAaps/BrowserBuild.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Pick the method that matches the device you build from:
2020

2121
### On an Android phone: AAPS Builder (recommended)
2222

23-
A setup page walks you through creating your own private build repository in GitHub. Nothing to install, no preparation file, and new AAPS versions are built automatically every week. You download the app directly from GitHub. Google Drive is optional.
23+
A setup page walks you through creating your own private build repository in GitHub. Nothing to install, no preparation file, and you start each build yourself. You download the app directly from GitHub. Google Drive is optional.
2424

2525
This also works from a computer browser.
2626

‎docs/EN/SettingUpAaps/BrowserBuildAapsBuilder.md‎

Lines changed: 88 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -63,18 +63,37 @@ Keep this documentation page open in another tab: the steps below explain each p
6363

6464
The setup page runs entirely in your browser: your key and passwords are never sent anywhere, except into the GitHub secret you paste them into yourself. It remembers your GitHub username and repository name, so you can come back to it at any time to reopen your secrets page or your builds.
6565

66+
![The AAPS Builder setup page](../images/Building-the-App/CI/AapsBuilder30_Step1.png)
67+
6668
(aaps-builder-step1)=
6769

6870
## Step 1 – Create your private build repository
6971

7072
This step creates an empty private repository in your GitHub account. Only you can see it and the apps it builds.
7173

7274
1. Make sure you are logged in to github.com in this browser.
75+
7376
2. In **Your GitHub username**, type your GitHub username.
77+
7478
3. In **Name of your repository**, keep the suggestion `my-aaps`. If you already created your repository with another name, type that exact name.
79+
7580
4. Check the line **Your repository:** it shows `github.com/<your username>/my-aaps`.
76-
5. Tap **Create my private repository**. GitHub opens in a new tab with the name you chose and **Private** selected. Don't change anything, and don't add a README or other files.
77-
6. Tap the green **Create repository** button.
81+
82+
5. Tap **Create my private repository**.
83+
84+
![Setup page step 1 filled in](../images/Building-the-App/CI/AapsBuilder31_Step1Filled.png)
85+
86+
6. GitHub opens in a new tab with your account as **Owner** and the name you chose.
87+
88+
![GitHub Create a new repository page](../images/Building-the-App/CI/AapsBuilder32_GitHubNewRepo.png)
89+
90+
Scroll down: **Private**, **No template** and **Add README: Off** are already selected. Don't change anything, and don't add a README or other files.
91+
92+
![Private, no template, no README](../images/Building-the-App/CI/AapsBuilder33_GitHubConfig.png)
93+
94+
7. Scroll down and tap the green **Create repository** button.
95+
96+
![Create repository button](../images/Building-the-App/CI/AapsBuilder34_GitHubCreate.png)
7897

7998
Go back to the setup page tab.
8099

@@ -85,10 +104,28 @@ Go back to the setup page tab.
85104
The build workflow is a text file that tells GitHub how to build AAPS. You copy it from the setup page into your repository, once.
86105

87106
1. Tap **Copy workflow**. The page confirms **Workflow copied** and shows its version number.
107+
108+
![Workflow copied, version 1](../images/Building-the-App/CI/AapsBuilder35_Step2.png)
109+
88110
2. Tap **Open the new file page**. GitHub opens a new, empty file in your repository, already named `.github/workflows/build.yml`.
89111
3. Check the file name at the top: it must be exactly `.github/workflows/build.yml`.
90112
4. Paste the workflow into the big text area (long press on a phone).
91-
5. Tap **Commit changes…**, then **Commit changes** again in the window that opens.
113+
114+
5. Tap **Commit changes…**
115+
116+
![Workflow pasted into the new file](../images/Building-the-App/CI/AapsBuilder37_NewFilePasted.png)
117+
118+
6. then **Commit changes** again in the window that opens.
119+
120+
![Commit changes window](../images/Building-the-App/CI/AapsBuilder38_CommitDialog.png)
121+
122+
GitHub shows the new file `build.yml` in the `.github/workflows` folder of your repository.
123+
124+
![The workflow file in your repository](../images/Building-the-App/CI/AapsBuilder39_WorkflowAdded.png)
125+
126+
```{warning}
127+
Don't press your phone's **Back** button while the file editor is open: GitHub reloads the page and the pasted text disappears. If that happens, tap **Restore** in the blue banner.
128+
```
92129

93130
```{warning}
94131
Only use the workflow from this setup page. Don't copy a build workflow from another website or repository: the workflow runs next to your signing key.
@@ -100,6 +137,8 @@ Only use the workflow from this setup page. Don't copy a build workflow from ano
100137

101138
The app must be signed with your own key. Choose one of the two tabs. Read the [new key or existing key warning](#aaps-builder-before-you-start) first.
102139

140+
![Setup page step 3: the two key options](../images/Building-the-App/CI/AapsBuilder40_Step3.png)
141+
103142
### I already have a keystore
104143

105144
1. Tap **I already have a keystore**.
@@ -114,25 +153,38 @@ The page checks the password and the alias on your device. **Keystore OK! Contin
114153
### Create a new key
115154

116155
1. Tap **Create a new key**.
156+
117157
2. Choose a password and type it twice. Rules: at least 8 characters, only the letters a–z and A–Z, the digits 0–9 and symbols such as `! ? #`. No spaces, no accented letters, and not the `|` character.
118-
3. Tap **Create key**. It takes a few seconds. **Key created** appears.
158+
159+
3. Tap **Create key**. It takes a few seconds before **Key created** appears.
160+
161+
![New key form with the password typed twice](../images/Building-the-App/CI/AapsBuilder41_NewKey.png)
162+
119163
4. Tap **Download backup (aaps-keystore.jks)** and store the file, together with its password, somewhere safe off your phone (for example your own cloud storage). You need it if you ever build AAPS another way. The alias of this key is `aaps`.
120164

165+
![Key created and the backup box](../images/Building-the-App/CI/AapsBuilder42_KeyCreated.png)
166+
121167
(aaps-builder-step4)=
122168

123169
## Step 4 – Give the key to your repository
124170

125171
Step 4 unlocks when step 3 is done. Your key, its passwords and its alias are packed into one value, the `KEYSTORE_SET` secret.
126172

127-
1. Tap **Open the secrets page**. GitHub opens the **New secret** page of your repository. On a phone, it is below the settings menu: scroll down.
173+
1. Tap **Open the secrets page**.
174+
175+
![Setup page step 4](../images/Building-the-App/CI/AapsBuilder43_Step4.png)
176+
177+
2. GitHub opens the **New secret** page of your repository. On a phone, it is below the settings menu: scroll down.
178+
179+
![GitHub New secret form](../images/Building-the-App/CI/AapsBuilder11_NewSecret.png)
180+
181+
3. In the **Name** field, type `KEYSTORE_SET`. You can use the **Copy** button next to it on the setup page.
128182

129-
![GitHub New secret form](../images/Building-the-App/CI/AapsBuilder11_NewSecret.png)
183+
4. On the setup page, tap **Copy secret**. In the **Secret** field on GitHub, paste it (long press on a phone).
130184

131-
2. In the **Name** field, type `KEYSTORE_SET`. You can use the **Copy** button next to it on the setup page.
132-
3. On the setup page, tap **Copy secret**. In the **Secret** field on GitHub, paste it (long press on a phone).
133-
4. Tap **Add secret**. `KEYSTORE_SET` now shows under **Repository secrets**.
185+
5. Tap **Add secret**. `KEYSTORE_SET` now shows under **Repository secrets**.
134186

135-
![Repository secrets list with KEYSTORE_SET](../images/Building-the-App/CI/AapsBuilder13_SecretList.png)
187+
![Repository secrets list with KEYSTORE_SET](../images/Building-the-App/CI/AapsBuilder13_SecretList.png)
136188

137189
You only need to do this once.
138190

@@ -152,10 +204,14 @@ GitHub shows **Page not found** (404)? The username or repository name in step 1
152204
3. Tap **Run workflow**. A small form opens:
153205
- **Version**: keep `latest` to build the newest AAPS release, or type a release number such as `3.3.2.1`.
154206
- **Variant**: keep `fullRelease` for normal use with a pump. The other variants are explained in [build variants](#browserbuild-variant).
155-
207+
- Tap the green **Run workflow** button.
208+
156209
![Run workflow form with latest and fullRelease](../images/Building-the-App/CI/AapsBuilder16_RunWorkflow.png)
210+
211+
4. The build starts and shows **In progress**, with two parts: **Check**, then **Build AAPS**.
212+
213+
![Build in progress](../images/Building-the-App/CI/AapsBuilder45_BuildRunning.png)
157214

158-
4. Tap the green **Run workflow** button. The build starts and shows **In progress**.
159215
5. Wait 15 to 30 minutes. A green check means the build is done. A red cross means it failed: open the build to read the message, then see [troubleshooting](#aaps-builder-troubleshooting).
160216

161217
![Finished build with a green check](../images/Building-the-App/CI/AapsBuilder22_BuildDone.png)
@@ -175,12 +231,21 @@ If there is no **Build AAPS** or **Run workflow** button:
175231

176232
1. On your phone, open the setup page in **Chrome**, not in the GitHub app: the GitHub app cannot download builds. Log in to github.com if asked.
177233
2. Tap **Open my builds**, then the newest build with a green check.
178-
3. Tap the **Download AAPS** link in the build summary. You can also scroll down to **Artifacts** and tap `aaps-….apk`.
234+
235+
![Finished build: status Success and 2 artifacts](../images/Building-the-App/CI/AapsBuilder50_RunSummary.png)
236+
237+
3. Scroll down to the build summary and tap the **Download AAPS** link.
238+
239+
![Build summary with the Download AAPS link](../images/Building-the-App/CI/AapsBuilder51_DownloadLink.png)
179240

180241
```{tip}
181-
On a phone, GitHub may show only the status, duration and number of artifacts, without the summary or the download link. Open Chrome's menu **⋮** and tick **Desktop site**: the full build page appears.
242+
Scroll with your finger on the text, not on the diagram of the build steps: the diagram moves instead of the page.
182243
```
183244

245+
You can also scroll further down to **Artifacts** and tap the download icon next to `aaps-….apk`.
246+
247+
![Artifacts with the phone and watch apps](../images/Building-the-App/CI/AapsBuilder52_Artifacts.png)
248+
184249
4. When the download is done, open Chrome's menu **⋮** → **Downloads**, tap `aaps-….apk` and choose **Install**. If asked, allow installing apps from this source.
185250

186251
![Chrome Downloads with the AAPS APK](../images/Building-the-App/CI/AapsBuilder29_Downloads.png)
@@ -205,7 +270,11 @@ It needs one more secret, `GDRIVE_OAUTH2`. You get its value with the preparatio
205270

206271
1. On a **computer**, download the preparation file and open it as described in [Option 1 – Computer](BrowserBuildO1Computer.md). Skip the keystore part: you already have your key.
207272
2. Follow [Step 3 – Authorize Google Drive](#aaps-ci-google-drive-auth) to get the `GDRIVE_OAUTH2` value.
208-
3. On the setup page, step 7 opens your secrets page. Create a secret named `GDRIVE_OAUTH2` (the **Copy** button copies the name), paste the value, and tap **Add secret**.
273+
3. On the setup page, step 7 opens your secrets page.
274+
275+
![Setup page step 7](../images/Building-the-App/CI/AapsBuilder48_Step7.png)
276+
277+
Create a secret named `GDRIVE_OAUTH2` (the **Copy** button copies the name), paste the value, and tap **Add secret**.
209278

210279
From the next build, the APKs are also saved in Google Drive.
211280

@@ -215,13 +284,11 @@ Google stops the access if you don't build for 6 months, or if you change your G
215284

216285
## Updating AAPS
217286

218-
Before every update, [back up your settings](#aaps-builder-step6) as explained in step 6.
219-
220-
You don't need to do anything to get new AAPS versions. Once a week (Monday night), your repository checks for a new AAPS release and builds it automatically. A version that was already built is never built again. Download and install it as in [step 6](#aaps-builder-step6). You can also build by hand at any time, as in [step 5](#aaps-builder-step5).
221-
222-
To turn off automatic builds: in your repository, open **Settings** → **Secrets and variables** → **Actions** → **Variables**, and add a repository variable `AUTO_BUILD` with the value `false`.
287+
Your repository never builds anything by itself: you decide when to build, which version and which variant. When a new AAPS version is released:
223288

224-
Automatic builds use `fullRelease`. To build another variant automatically, add a repository variable `AUTO_VARIANT` with its name, for example `aapsclientRelease`.
289+
1. [Back up your settings](#aaps-builder-step6) as explained in step 6.
290+
2. Build the new version as in [step 5](#aaps-builder-step5). Keep `latest`, or type the release number.
291+
3. Download and install it as in [step 6](#aaps-builder-step6).
225292

226293
**Updates of the build workflow:** your repository never downloads a new workflow by itself. When the workflow changes, the [Docs updates & changes](../Maintenance/DocumentationUpdate.md) page says so. To update, open `.github/workflows/build.yml` in your repository, tap the pencil (**Edit**), replace the whole text with a fresh copy from the setup page (**Copy workflow** in step 2), and tap **Commit changes**. The first line of the file shows its version.
227294

‎docs/EN/SettingUpAaps/BuildingAaps.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Three methods are available to build the AAPS app:
1212

1313
### Build with a browser (recommended)
1414

15-
You can build the app with your smartphone using GitHub Actions. From an Android phone, the [AAPS Builder](#aaps-builder) setup page walks you through it, and new AAPS versions are built automatically. From a computer or an iPhone, you can also build with a fork and save the app in your Google Drive.
15+
You can build the app with your smartphone using GitHub Actions. From an Android phone, the [AAPS Builder](#aaps-builder) setup page walks you through it, and you start each build yourself. From a computer or an iPhone, you can also build with a fork and save the app in your Google Drive.
1616

1717
**[Follow these instructions.](./BrowserBuild.md)**
1818

0 commit comments

Comments
 (0)