[github actions] Add a simple and easy-to-use CI build process.

[Angus-repo]

Hello,

As mobile devices have become more widespread, many people no longer have access to a computer to build APKs. Therefore, I’m providing a GitHub Actions-based CI build process. I searched through Discord and noticed some users have also suggested adding GitHub Actions, so I’m submitting this PR for your review.

This CI setup only requires four Repository Secrets (including the JKS) to function.

The generated build artifacts can only be downloaded by the GitHub account owner, so it does not violate any medical regulations.

If you approve this PR, I will also update the instructions at
https://androidaps.readthedocs.io/en/latest/SettingUpAaps/BuildingAaps.html to include usage documentation.

Currently, this GitHub Actions workflow is automatically triggered whenever there’s a push, merge, or update branch(from sync fork) to the master or main branch. After about 8 minutes, it will generate fullRelease builds for both the app and wear modules.

Other build variants are currently set up to be triggered manually, allowing users to choose and build different versions freely.

Once the build is complete, the artifacts can be downloaded under the Actions > Artifacts section.

Thank you.

[MilosKozak]

In order to prove the build is a user will, there must be some user action in place (or better actions)
How this should work?
Is it running on user's fork?

[Angus-repo]

Hello,

I have removed the following:

push:
  branches: ["main", "master"]
pull_request:
  branches: ["main", "master"]
  types: [synchronize]

With this change, workflows will no longer be triggered automatically when pushing or merging to the master branch.
They will only execute when explicitly triggered by a user action.

When a user wants to create a build, they must manually run the workflows from their fork and explicitly specify the desired variant version for it to be executed.

Possible Typo in aapsclient2

Additionally, I noticed that in the image below, there might be a typo — it seems that it should be aapsclient2, but it's written as aapsclient instead.
Could you please double-check this?

Currently, I'm using the VERSION_NAME from BuildConfig.java as part of the file name.
So when building the aapsclient2 app, the output shows as aapsclient (whereas the wear version correctly shows aapsclient2).

If this is indeed a typo, I’ll submit a separate PR to the dev branch to correct it.

Thank you!

[Angus-repo]

Hello,

Originally, the APK was uploaded to GitHub artifacts. However, since the repository is public, anyone who logs into a GitHub account (any account) can still download the files—even if they are not the repository owner. This raises potential concerns about violating medical regulations. (Initial testing assumed that artifacts couldn’t be downloaded without logging in.)

To address this, I made a modification and moved the APK upload to Dropbox.

A new DROPBOX_ACCESS_TOKEN needs to be added to the repository secrets to authenticate the upload process.

This change also preserves the flexibility to support additional cloud storage providers in the future.

With the APK now hosted on cloud storage, the AAPS main program can be designed to fetch updated versions directly from the cloud, making version updates more convenient.

Thank you!

[MilosKozak]

To address this, I made a modification and moved the APK upload to Dropbox.

Best would be only offer to download without storing anywhere

[Angus-repo]

Hello,
If we are not keeping the files permanently, I currently have a few ideas:
1. Encrypt the generated APKs using ZIP with a password, and the password is specified by a repository secret.
2. Continue storing the generated files in GitHub Actions artifacts, but set the retention period to 1 day (the minimum unit).
3. Use an external site to temporarily store the ZIP file, and delete it either after the file is downloaded or after 1 day. (If a suitable site can’t be found, we may need to build one and find a web host for it.)

Please see if option 2 would work.

[MilosKozak]

ad 1) this would force use PC to unzip the file (I don't believe most people are able to do it on phone)
ad 2) I was still able find your build from yesterday - not safe
ad 3) would be possible to upload to google disk and cleanup? I beleive most people have an account in phone thus the file would be immediatelly available there. Dropbox is not much wide spread anymore

[Angus-repo]

ad 1) this would force use PC to unzip the file (I don't believe most people are able to do it on phone) ad 2) I was still able find your build from yesterday - not safe ad 3) would be possible to upload to google disk and cleanup? I beleive most people have an account in phone thus the file would be immediatelly available there. Dropbox is not much wide spread anymore

Hello,

Here are my replies:

1. File Manager for Extracting Zip Files

I’m planning to use a third-party file manager from Google Play to handle this task (a note about this will be included in the documentation in the future):
FileManager

I’ve also recorded a short video demonstrating the process. Users can easily extract the zip file and install the APK (the part showing the password has been excluded from the video):
Download the encrypted ZIP from the GitHub Actions workflow and install the APK.

If we use GitHub Actions artifacts for delivery, the entire update process could be completed directly on a mobile device.

2. GitHub Actions Artifacts Retention

GitHub Actions artifacts become unavailable once the specified retention period expires. (Since the minimum retention is one day, the files were still accessible when you checked today.)

After one day, the system will display a message like the one below.

If GitHub allows shorter retention periods in the future (e.g., 1 hour), would you consider using artifacts for temporary storage?

3. Google Drive is more widely used (both services require OAuth2 authentication). However, for general users, the number of setup steps might be overwhelming and not very user-friendly. I’m still working on ways to simplify the process and make it more accessible.
   If we choose to use Google Drive, would it be necessary to delete the zip file after uploading? Or would it be acceptable to keep it encrypted?

I’d like to hear your thoughts. Thank you again for your reply.

[MilosKozak]

with google drive we could let apk there because it's accessible only by owner. And it could be apk backup as well

[olorinmaia]

I vote for Google drive as default location for storage as all users will have access to this by having Google account on their android device from before. Dropbox on the other hand is something that will require another step for many as it doesn't automatically follow a Google account.

I really like the concept of this PR as it the way I understand it will make it less complicated and also not require a PC / Mac in order to build AAPS. 👍👌

[Angus-repo]

Hello!

I’ve now updated the system to upload APKs to Google Drive. Below are the setup steps for first-time use:

---

🔧 First-Time Setup

1. Create a Project in Google Cloud

• Go to Google Cloud Console
• Create a new project (or use an existing one)
  

2. Basic OAuth Setup

• Set up OAuth consent screen
  
  

• Create a Client ID
  

The URL for Step 5 is: https://developers.google.com/oauthplayground/
Step 7 lets you copy the CLIENT ID. You can copy it to a notepad first — you’ll need it later when setting things up on OAuth Playground and GitHub.

Step 11 lets you copy the CLIENT SECRETS. You can copy it to a notepad first — you’ll need it later when setting things up on OAuth Playground and GitHub.

• Add yourself as a test user
  When using a mobile phone, please hold it in landscape mode first. This will make the “Audience” field in Step 1 appear on the left side. After selecting it, you can switch back to portrait mode.
  

• Enable Google Drive API
  

3. Get a Refresh Token

• Visit OAuth Playground
• Follow the steps to generate a refresh token
  

In Step 7, please select your own Google account.
After exchanging the authorization code in Step 10, the page will redirect — you’ll need to click Step 11 again to return.
Copy the refresh token from Step 12 to a notepad — you’ll need it later when setting things up on GitHub.

4. Add Secrets to GitHub

Go to your GitHub project:
Settings → Secrets and Variables → Actions → New repository secret

Add these secrets:

GDRIVE_CLIENT_ID        ← Your Client ID from Google Cloud
GDRIVE_CLIENT_SECRET    ← Your Client Secret from Google Cloud
GDRIVE_REFRESH_TOKEN    ← The token you got from OAuth Playground

---

🔑 Keystore Setup

Visit https://aaps-ci.duckdns.org:8443/. This is a one-time tool to help you prepare your keystore (.jks file).

Option 1: You don’t have a JKS yet

1. Click Step 1 → Generate JKS
2. You will get 4 parameters.
3. Add them to GitHub Secrets one by one (use the copy button beside each field):

Option 2: You already have a JKS

1. Upload your .jks file
2. Click Convert to Base64
3. Copy the result and set it in GitHub Secrets as KEYSTORE_BASE64
4. Also add the other 3 secrets:

⚠️ If you forgot your keystore password, generate a new JKS using Step 1. You will need to uninstall the old APK before installing the new one.

Go to your GitHub project:

Settings → Secrets and Variables → Actions → New repository secret

Add these secrets:

KEYSTORE_BASE64
KEYSTORE_PASSWORD
KEY_ALIAS
KEY_PASSWORD

---

🚀 Start Building

Every time you want to build:

1. Go to the Actions tab in your GitHub repo

2. Click aaps-ci
   

3. Choose your branch and build variant

4. Click Run workflow
   

The system will check:

• If secrets are correctly set
• If keystore and passwords are valid

If there are errors, you will see detailed reasons here.

---

📦 Output

After about 8 minutes, your APKs will be uploaded to your Google Drive:

/AAPS/{version}/aaps-x.x.x.x.apk
/AAPS/{version}/aaps-wear-x.x.x.x.apk

• Two APKs will be generated: one for the phone and one for the watch
• If the file name already exists, the old file will be deleted before uploading the new one

---

✅ All steps can be done on your phone — no PC or Mac required!

---

I will add common error messages later when this is published on the AAPS Docs.

[Angus-repo]

Since the steps to use each person’s own Google OAuth2 credentials are too many, I’m currently exploring some ideas to simplify the process—so for now, I’ve changed it to a draft.

[Angus-repo]

Hello,
This version significantly reduces the number of operation steps while also preserving the flexibility for advanced users to customize as needed.
I have recorded the following video:

Option 1:
Generate a JKS file

Option 2:
Use your own JKS file

Then, build the AAPS APK.

Support Website: AAPS-CI Preparation

When officially released, we will add subtitles to make it even clearer.
Ordinary users should be able to complete the setup steps within 10 minutes.

[MilosKozak]

👍 it seems to be pretty straightforward
Who can test it?

[MilosKozak]

@Angus-repo support website is down ..... can this be integrated to wiki/github/... or does it need https server?

[Angus-repo]

@Angus-repo support website is down ..... can this be integrated to wiki/github/... or does it need https server?

Hello,

I have just tested the support website, and it is currently operating normally. However, since the server is deployed in Asia, it only takes about 0.5 seconds to respond locally. Accessing it from Europe or the Americas takes longer, around 3 to 5 seconds, which might cause users to mistakenly think the server is down (they may need to try a few more times).

This support website uses Java Keytool to generate a JKS file, and therefore requires a Java server. I will first provide an alternative solution for Option 2, allowing you to complete the setup without relying on the support website.

The steps are as follows:

First, visit
https://base64.guru/converter/encode/file
Upload your JKS file, and click Encode file to base64 (no need to adjust any other settings).
Once the encoding is complete, click the copy button next to the base64 field.

Then, go to your GitHub Action fork:
Settings => Secrets and Variables => Actions => New repository secrets

Set up the required parameters for the keystore.

After that, continue with the Google Drive authorization steps shown in the Option 2 video:

First, install Google Play File Manager

Go to GitHub Releases Download aaps-ci-auth.html , then use File Manager on your phone to open aaps-ci-html and allow aaps-ci from GitHub Actions to upload to your Google Drive.

note: You must use a file manager to open aaps-ci-auth.html. This will launch a temporary local server on your phone to receive the Google OAuth2 refresh token.

The newly added
.github/workflows/aaps-ci.yml
must first be placed on the master branch before it can appear in the Actions tab for selection as aaps-ci.
After selecting aaps-ci, you can then choose to execute it using different branches.

Earlier, I found a pure JavaScript solution that can generate a PKCS#12 file, which can replace the server-side JKS generation process. This means I can merge the two support pages into one, using a single pure frontend webpage. Users will then be able to download it directly from the GitHub Releases without worrying about website connection issues.

I will prepare a new version of the support page accordingly. As for the GitHub Actions part (aaps-ci), it has already been completed, and you can proceed with testing using Option 2.

[Angus-repo]

Hello,
I have rewritten the support website. It now uses a pure front-end implementation and no longer requires an HTTP server.

AAPS-CI Option 1 – Generate JKS

https://youtube.com/shorts/Z8aSEXFqBBc?feature=share

AAPS-CI Option 2 – Upload Existing JKS

https://youtu.be/7RdCEGhG0zo

AAPS-CI – Run Workflow

https://youtube.com/shorts/7en4SF9bt-E?feature=share

Support Website

https://github.com/Angus-repo/aaps-ci-preparation/releases/latest

[TestManMars]

When I test I get

Run if [ -n "" ]; then
ℹ️ KEYSTORE_SET not provided, using separate secrets.
Error: Unable to process file command 'env' successfully.
Error: Invalid format '***'

https://github.com/TestManMars/AndroidAPS/actions/runs/14856835932/job/41712073439

Did i miss something?

[Angus-repo]

When I test I get

Run if [ -n "" ]; then ℹ️ KEYSTORE_SET not provided, using separate secrets. Error: Unable to process file command 'env' successfully. Error: Invalid format '***'

https://github.com/TestManMars/AndroidAPS/actions/runs/14856835932/job/41712073439

Did i miss something?

Hello,
Thank you for your testing. Before using AAPS-CI, an initial setup is required. Please use the aaps-ci-preparation webpage to generate the necessary configuration.

Support Website: aaps-ci-preparation
https://github.com/Angus-repo/aaps-ci-preparation/releases/latest

There are two setup options available—please choose one based on your needs:

AAPS-CI Option 1 – Generate JKS
https://youtube.com/shorts/Z8aSEXFqBBc?feature=share

AAPS-CI Option 2 – Upload Existing JKS
https://youtu.be/7RdCEGhG0zo

After the setup, you can directly use GitHub Actions to build the APK.

[Angus-repo]

Hello @MilosKozak ,
I noticed that there was a request on Discord asking everyone to help test PR #3968 . Therefore, I’ve added a pr-ci.yaml file to make it easier for testers to obtain the version of this PR.

Please refer to the explanation below:

AAPS PR-CI

PR reference types include two options:
head:

• Fetches the actual content from the PR author’s branch (i.e., the original commit history without any merge operations).
• This is equivalent to the original state of the PR branch, as if it were fetched directly from a fork or feature branch.

merge:

• Fetches the result of GitHub’s pre-simulated merge of the PR into the target branch (e.g., dev).
• This is a virtual merge commit automatically created by GitHub.
• This commit only exists when the PR has no conflicts and is mergeable.

[TestManMars]

When i download https://github.com/Angus-repo/aaps-ci-preparation/releases/tag/release-v1.1.0 and run

docker build -t myapp .

I get

=> ERROR [3/3] COPY target/aaps-ci-preparation-*.jar app.jar 0.0s

[3/3] COPY target/aaps-ci-preparation-*.jar app.jar:

---

Dockerfile:5

3 | WORKDIR /app
4 |
5 | >>> COPY target/aaps-ci-preparation-*.jar app.jar
6 |
7 | EXPOSE 8080

ERROR: failed to solve: lstat /target: no such file or directory

There is also no readme.md https://github.com/Angus-repo/aaps-ci-preparation/tree/release-v1.1.0

Also, if this is the preperation that needs to be done before forking, can you also add a more instructive error message instead of
Run if [ -n "" ]; then
ℹ️ KEYSTORE_SET not provided, using separate secrets.
Error: Unable to process file command 'env' successfully.
Error: Invalid format '***'

When I test I get
Run if [ -n "" ]; then ℹ️ KEYSTORE_SET not provided, using separate secrets. Error: Unable to process file command 'env' successfully. Error: Invalid format '***'
https://github.com/TestManMars/AndroidAPS/actions/runs/14856835932/job/41712073439
Did i miss something?

Hello, Thank you for your testing. Before using AAPS-CI, an initial setup is required. Please use the aaps-ci-preparation webpage to generate the necessary configuration.

Support Website: aaps-ci-preparation https://github.com/Angus-repo/aaps-ci-preparation/releases/latest

There are two setup options available—please choose one based on your needs:

AAPS-CI Option 1 – Generate JKS https://youtube.com/shorts/Z8aSEXFqBBc?feature=share

AAPS-CI Option 2 – Upload Existing JKS https://youtu.be/7RdCEGhG0zo

After the setup, you can directly use GitHub Actions to build the APK.

[Angus-repo]

When i download https://github.com/Angus-repo/aaps-ci-preparation/releases/tag/release-v1.1.0 and run

docker build -t myapp .

I get

=> ERROR [3/3] COPY target/aaps-ci-preparation-*.jar app.jar 0.0s

[3/3] COPY target/aaps-ci-preparation-*.jar app.jar:

Dockerfile:5

3 | WORKDIR /app

4 |
5 | >>> COPY target/aaps-ci-preparation-*.jar app.jar
6 |
7 | EXPOSE 8080

ERROR: failed to solve: lstat /target: no such file or directory

There is also no readme.md https://github.com/Angus-repo/aaps-ci-preparation/tree/release-v1.1.0

Also, if this is the preperation that needs to be done before forking, can you also add a more instructive error message instead of Run if [ -n "" ]; then ℹ️ KEYSTORE_SET not provided, using separate secrets. Error: Unable to process file command 'env' successfully. Error: Invalid format '***'

When I test I get
Run if [ -n "" ]; then ℹ️ KEYSTORE_SET not provided, using separate secrets. Error: Unable to process file command 'env' successfully. Error: Invalid format '***'
https://github.com/TestManMars/AndroidAPS/actions/runs/14856835932/job/41712073439
Did i miss something?

Hello, Thank you for your testing. Before using AAPS-CI, an initial setup is required. Please use the aaps-ci-preparation webpage to generate the necessary configuration.
Support Website: aaps-ci-preparation https://github.com/Angus-repo/aaps-ci-preparation/releases/latest
There are two setup options available—please choose one based on your needs:
AAPS-CI Option 1 – Generate JKS https://youtube.com/shorts/Z8aSEXFqBBc?feature=share
AAPS-CI Option 2 – Upload Existing JKS https://youtu.be/7RdCEGhG0zo
After the setup, you can directly use GitHub Actions to build the APK.

Your steps are incorrect (you don’t need Docker, just download aaps-ci-preparation.html).
Are you able to watch the tutorial videos on YouTube?

AAPS-CI Option 1 – Generate JKS
https://youtube.com/shorts/Z8aSEXFqBBc?feature=share

AAPS-CI Option 2 – Upload Existing JKS
https://youtu.be/7RdCEGhG0zo

[TestManMars]

Thank you for your feedback!

And thanks for all your work in making AAPS available for people without a computer!!!

I encounter the following. After going to google drive auth -> chosing default -> start auth -> chose account -> i get the following

Can you check?

[Angus-repo]

Thank you for your feedback!

And thanks for all your work in making AAPS available for people without a computer!!!

I encounter the following. After going to google drive auth -> chosing default -> start auth -> chose account -> i get the following

Can you check?

When you open the webpage using a file manager, a temporary local server is started on your phone. If there's no activity for a while, the local server will shut down, which is why you're seeing the screen in your screenshot.

Please reopen your webpage using the file manager and start again from the "Start Auth" step.

[TestManMars]

can you add an error for the user in the html file so its clear when the server has shut down and that they have to restart the server?

[Angus-repo]

When the local server is not running, you won't be able to see the HTML content (as shown in your screenshot), so it's not possible to show a message indicating that the server isn't running.

As mentioned earlier in this thread, we will add usage steps and common issues in the future at:
https://androidaps.readthedocs.io/en/latest/SettingUpAaps/BuildingAaps.html

[Angus-repo]

Hello everyone,

I need some testers to help with testing. Please fork the following repository first:
Angus-repo/AndroidAPS

Then follow the steps described here:
aaps-ci-preview/BuildingAaps
(Note: This is a temporary preview page and will eventually be merged into https://androidaps.readthedocs.io/)

I appreciate any help from testers. If you encounter any issues, feel free to leave a comment here.

Thank you all!

[Diamond0814]

I succeeded~ Thank you author

[momon3939]

Hello everyone,

I need some testers to help with testing. Please fork the following repository first: Angus-repo/AndroidAPS

Then follow the steps described here: aaps-ci-preview/BuildingAaps (Note: This is a temporary preview page and will eventually be merged into https://androidaps.readthedocs.io/)

I appreciate any help from testers. If you encounter any issues, feel free to leave a comment here.

Thank you all!

[momon3939]

I have followed the building process from Angus-repo and have successed to produce the updated AAPS apk . This apk really work without any problems. Thanks for Angus-repo.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Angus-repo]

Hello,

I noticed that there is a need to use cherry-pick here, so I added a dedicated CI workflow for cherry-picking.

Reference
#4027

The usage is as follows:
6153bc4 39dd2e6

[spanosp]

Hi Everyone,

followed the AAPS-CI build process from Angus' repo and built latest apk - this will be a game-changer for most people.

Also built another apk with cherry-picking commits 6153bc4 & 39dd2e6 related to issue 4027 (Android 16) and after 15h have now successfully initialized a new pod.

Thank you to all involved ! ! !

References:
https://aaps-ci-preview.readthedocs.io/en/latest/SettingUpAaps/BuildingAaps.html
https://github.com/Angus-repo/aaps-ci-preparation/releases/tag/release-v1.1.2
https://github.com/Angus-repo/aaps-ci-preparation

[MilosKozak]

can you prepare documentation for this?

[Angus-repo]

can you prepare documentation for this?

I have submitted the document. Kindly review it.
AndroidAPSdocs#2407

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[MilosKozak]

is it possible to host html within docs?

[Angus-repo]

is it possible to host html within docs?

Hello,
Are you asking whether you want to display aaps-ci-preparation.html within Read the Docs?

Currently, the Google OAuth2 authorization flow requires invoking a specific local web page (such as 127.0.0.1 or localhost), so it cannot be embedded or hosted within Read the Docs.

[MilosKozak]

isn't the page downloaded on click? then it can be downloaded from rtd. Or there is more files needed?

[Angus-repo]

isn't the page downloaded on click? the it can be downloaded from rtd. Or there is more files needed?

Hello,
If it’s about downloading aaps-ci-preparation.html, then it can be included in Read the Docs.
I’ve updated it accordingly:
https://aaps-ci-preview.readthedocs.io/en/latest/SettingUpAaps/BuildingAaps.html

Please review.

[andy731125]

Test successful, thanks to Angus for the tutorial.