AAPS: ako na podpisový kľúč pre GitHub

Zostavovali ste AndroidAPS v Android Studiu a teraz chcete prejsť na GitHub Actions? Najdôležitejšou vecou, ktorú si treba preniesť, je pôvodný podpisový kľúč. V tomto návode ukážem, kde ho nájsť, ako ho pripraviť pre AAPS Builder a kedy má zmysel vytvoriť nový.

Článok nadväzuje na návod na zostavenie AAPS cez prehliadač.

Pôvodný alebo nový kľúč?

AAPS už používam a mám pôvodný keystore: prenesiem existujúci kľúč.
AAPS zostavujem prvýkrát: vytvorím nový kľúč a odložím jeho zálohu.
AAPS používam, ale kľúč alebo heslo nemám: najskôr skontrolujem zálohy. Nový kľúč nie je náhradou pôvodného pri bežnej aktualizácii.

Aplikácia podpísaná iným kľúčom nedokáže pri tomto postupe aktualizovať pôvodnú inštaláciu. Zmena počítača či prechod na GitHub preto samy osebe nie sú dôvodom vytvárať nový kľúč. Toto rozhodnutie vysvetľuje aj oficiálny prehľad možností keystore.

Čo je keystore a čo si pripraviť

Keystore je súbor obsahujúci podpisový kľúč a certifikát. Obvykle má príponu .jks alebo .keystore. Pripravte si súbor, heslo ku keystore, alias konkrétneho kľúča a heslo ku kľúču. Obe heslá môžu byť rovnaké, ale nemusí to tak byť. Alias býva key0. Rozhodujúca je vaša skutočná hodnota.

1. Nájdite pôvodný kľúč v Android Studiu

Na počítači, na ktorom ste zostavovali AAPS, otvorte projekt. V ponuke Build → Generate Signed Bundle / APK zvoľte APK a pokračujte do podpisového dialógu. Názvy sa môžu mierne líšiť podľa verzie Android Studia. Ak sú údaje zapamätané, v poli Key store path nájdete cestu k súboru a vedľa sú údaje o aliase a heslách.

Súbor skopírujte cez správcu súborov na bezpečné miesto. Nemusíte kvôli tomu zostavovať ďalšie APK ani vytvárať nový kľúč. Ak je dialóg prázdny, hľadajte vo vlastných zálohách alebo priečinku, kam ste kľúč pri prvom zostavení uložili. Dokumentácia AAPS opisuje aj zálohovanie keystore.

2. Načítajte kľúč do AAPS Buildera

Otvorte oficiálny nastavovací sprievodca AAPS Buildera. Použite vlastný súkromný repozitár s oficiálnym workflow pripravený podľa postupu na vytvorenie repozitára a pridanie workflow. V kroku pre podpisový kľúč zvoľte I already have a keystore.

Vyberte pôvodný súbor keystore.
Vyplňte heslo k súboru a vyberte alebo napíšte správny alias.
Ak má samotný kľúč iné heslo, vypnite voľbu rovnakých hesiel a doplňte ho.
Potvrďte kontrolu tlačidlom Check and continue.

Import existujúceho podpisového kľúča v AAPS Builderi — Formulár pre existujúci keystore. Použite údaje pôvodného kľúča z Android Studia, pričom na obrázku nie sú zobrazené žiadne súkromné údaje.

3. Uložte KEYSTORE_SET do GitHubu

Sprievodca pripraví hodnotu KEYSTORE_SET. V repozitári otvorte Settings → Secrets and variables → Actions a vytvorte nový repository secret. Názov je KEYSTORE_SET, hodnotou je celý dlhý text zo sprievodcu. Samotné slovo KEYSTORE_SET do poľa hodnoty nestačí. Potom secret uložte.

Súbor .jks nevkladajte do záložky Code ani do commitu. Použite úložisko Secrets. Workflow môže s tajomstvom pracovať, preto používajte oficiálny workflow a dôveryhodným ľuďom udeľujte prístup k repozitáru uvážene. Ako fungujú GitHub Actions secrets.

GitHub Actions secret KEYSTORE_SET — GitHub po uložení zobrazuje názov secretu. Hodnota podpisového kľúča na snímke nie je.

Nemáte kľúč? Vytvorte nový

Pri prvej inštalácii vyberte v tom istom sprievodcovi možnosť Create a new key. Zadajte heslo dvakrát a vytvorenie potvrďte. Sprievodca požaduje aspoň osem znakov bez diakritiky, pričom treba rešpektovať aj jeho ďalšie validačné hlásenia.

Stiahnite ponúknutú zálohu aaps-keystore.jks. Odložte súbor, heslo a alias key0 mimo telefónu. Následne uložte pripravený KEYSTORE_SET rovnako ako pri existujúcom kľúči. Pri ďalších zostaveniach používajte tento kľúč opakovane.

Čo ak si nepamätáte alias alebo heslo?

Zabudnutý alias ešte neznamená stratený kľúč. Ak máte súbor a jeho heslo, nástroj keytool z JDK dokáže vypísať záznamy:

keytool -list -keystore "/cesta/k/vasmu-klucu.jks"

Cestu nahraďte vlastnou. Heslo zadáte až na výzvu, nemusí byť súčasťou príkazu. Výpis pomôže nájsť alias, ale neobnoví zabudnuté heslo ani nepotvrdí, že ide o kľúč použitý v telefóne. Dokumentácia nástroja keytool.

Ak pôvodný kľúč alebo potrebné heslo nenájdete, pripravte si obnovu pred odinštalovaním AAPS. Exportujte aktuálne nastavenia, skopírujte ich mimo telefónu a majte uložené hlavné heslo k exportu. Hoci nastavenia obsahujú aj stav cieľov, ich export nie je zálohou podpisového kľúča. Postup obnovy si prejdite v dokumentácii záloh AAPS.

Pozor na miešanie staršieho a nového postupu

Stránka BrowserBuildKeystore patrí k staršiemu postupu cez fork a prípravný súbor. Má vlastné kroky a samostatné secrets. Tento článok používa AAPS Builder s jedným KEYSTORE_SET. Nepreberajte medzi nimi mechanicky názvy secrets ani pravidlá úpravy hesiel.

Ako ho získať existujúci kľúc zo secrets GitHub Actions?

GitHub uloženú hodnotu secretu v nastaveniach znova neukáže. Môžete ju nahradiť alebo vymazať, ale nedá sa odtiaľ jednoducho skopírovať. Workflow však vie secret použiť — preto starší oficiálny postup AAPS ponúka export keystore do zaheslovaného archívu.

Nasledujúce kroky platia pre starší browser build cez fork, ktorý obsahuje exportný workflow a má funkčné pripojenie ku Google Drive:

GitHub Actions secrets vrátane nastaveného ZIP_PASSWORD — *Pripravené secrets: KEYSTORE_SET, GDRIVE_OAUTH2 a ZIP_PASSWORD. GitHub ukazuje ich názvy, nie hodnoty.*

V pôvodnom repozitári otvorte nastavenia secrets pre Actions. Pridajte ZIP_PASSWORD s novým heslom na ochranu exportu. Heslo na ochranu exportu musí obsahovať iba písmená anglickej abecedy a číslice, pričom heslo samotného kľúča sa nemení.
V Actions vyberte CI KeyStore Export a spustite ho cez Run workflow.
Po úspešnom dokončení nájdete na svojom Google Drive v priečinku AAPS/KeyStore zaheslovaný ZIP s kľúčom. Podľa verzie workflow má názov keystore.zip alebo keystore-RRRRMMDD-HHMMSS.zip, pričom v zobrazenom repozitári sa používa názov s dátumom a časom.
Archív stiahnite a rozbaľte pomocou hesla ZIP_PASSWORD. Obsahuje keystore.jks a keyStoreInfo.txt s heslami a aliasom.
V AAPS Builderi použite možnosť existujúceho keystore. Načítajte získaný súbor, doplňte údaje z keyStoreInfo.txt a vytvorený KEYSTORE_SET uložte do nového repozitára.

Zoznam GitHub Actions s workflow CI Keystore Export — *V záložke Actions vyberte vľavo CI Keystore Export.*

Detail CI Keystore Export s tlačidlom Run workflow — *Detail exportného workflow. Po príprave ZIP_PASSWORD a prístupu ku Google Drive spustíte export cez Run workflow. Snímka zachytáva stav pred prvým spustením.*

Úspešne dokončené kroky exportu podpisového kľúča na Google Drive — Skutočný export: kontrola kľúča, vytvorenie zaheslovaného ZIPu aj nahranie na Google Drive prešli úspešne. Krok Upload APKs to Google Drive má všeobecný názov, v tomto workflow však nahráva ZIP s keystore.

Pri chybe ukladania na Drive skontrolujte platnosť jeho autorizácie v pôvodnom postupe. Archív aj heslo si bezpečne odložte. Podrobnosti: oficiálny export keystore a prechod zo staršieho forku.

Pred prvou aktualizáciou z GitHubu

Zálohujte nastavenia AAPS a pokračujte spustením zostavenia AAPS cez Run workflow. Pri konflikte podpisu najskôr skontrolujte použitý keystore a alias. Úspešný build potvrdzuje zostavenie APK, nie zhodu s podpisom vašej nainštalovanej aplikácie. Pôvodnú inštaláciu nemažte len preto, aby zmizla chybová hláška.

Pri prechode z Android Studia na GitHub meníte miesto zostavovania. Podpisový kľúč by ste mali presunúť na GitHub.

O autorovi

Ľubor Jurena

Zakladateľ skHosting.eu, systémový a sieťový architekt a človek žijúci s diabetom. Na glykemia.sk prepájam osobnú skúsenosť s diabetickými technológiami a prácou pre open-source komunitu.

Viac o mne →