Ad Hoc.
Instalacja z linku.

1. Co przygotowujemy i dlaczego

Zbudujesz własną aplikację w GitHub Actions, podpiszesz ją profilem Ad Hoc i zainstalujesz na zarejestrowanym iPhonie z linku w Safari. Po kolejnej zmianie opublikujesz nową wersję. Na stronie pozostanie też historia wcześniejszych buildów.

Potrzebujesz aktywnego Apple Developer Program, dostępu do Certificates, Identifiers & Profiles, repozytorium z kodem aplikacji i iPhone’a. Mac przydaje się do przygotowania certyfikatu. Na Windowsie i Linuksie możesz użyć OpenSSL; samą kompilację i podpisywanie wykona runner macOS w GitHub Actions.

Przykład używa dwóch Twoich repozytoriów: repo aplikacji buduje i podpisuje IPA, a publiczne repo strony przechowuje instalator. Wystarczą standardowe usługi Apple i GitHub. Nie potrzebujesz dodatkowego backendu.

Klucz API Apple .p8 z części 2 nie jest potrzebny w tym wariancie. Profil tworzymy ręcznie w portalu Apple, a IPA publikujemy na własnej stronie. Ad Hoc wymaga App ID, ale nie wymaga rekordu aplikacji w App Store Connect ani grupy TestFlight.

2. Sprawdź, co już masz z TestFlight

Otwórz Certificates i wybierz właściwy zespół. Jeśli masz ważny Apple Distribution oraz odpowiadający mu klucz prywatny, wykorzystaj je ponownie. Nie twórz nowego certyfikatu tylko dla innego sposobu instalacji.

Na Macu otwórz Dostęp do pęku kluczy → Logowanie → Moje certyfikaty. Rozwiń Apple Distribution i sprawdź, czy pod nim jest klucz prywatny. Jeśli masz już plik AppleDistribution.p12 i znasz hasło eksportu, możesz go wykorzystać. Jeżeli odpowiednie sekrety są już w tym samym repo aplikacji, nie trzeba wgrywać ich ponownie.

Sam .cer nie zawiera klucza prywatnego. Najpierw poszukaj oryginalnego Maca lub kopii .p12. Nie unieważniaj certyfikatu używanego przez działające aplikacje. Apple Development z części o kablu nie zastępuje Apple Distribution w tym workflow.

Masz poprawny komplet? Pomiń tworzenie CSR i certyfikatu i przejdź do sprawdzenia App ID. Profil App Store z TestFlight zostaw; dla Ad Hoc przygotujemy osobny profil.

3. Nie masz certyfikatu? Przygotuj CSR i .p12

Ten krok wykonaj tylko, jeśli nie masz poprawnego kompletu z kroku 2. Nie nadpisuj istniejących kluczy.

Wykonaj tylko jedną zakładkę. Każda prowadzi od CSR do gotowego AppleDistribution.p12. Potem przejdź do sprawdzenia App ID w kroku 4. Podstawą są dokumentacja CSR oraz dokumentacja PKCS#12.

openssl version

mkdir -p ~/adhoc-signing
cd ~/adhoc-signing
export MSYS_NO_PATHCONV=1

openssl genpkey -algorithm RSA -aes-256-cbc -pkeyopt rsa_keygen_bits:2048 -out distribution.key
openssl req -new -sha256 -key distribution.key -out distribution.csr -subj "/CN=Jan Kowalski Distribution/emailAddress=jan@example.com"

openssl x509 -inform DER -in distribution.cer -out distribution.pem
openssl pkcs12 -export -inkey distribution.key -in distribution.pem -name "Apple Distribution" -out AppleDistribution.p12

openssl pkcs12 -info -noout -in AppleDistribution.p12

sudo apt update
sudo apt install openssl
openssl version
mkdir -p ~/adhoc-signing
cd ~/adhoc-signing
umask 077

openssl genpkey -algorithm RSA -aes-256-cbc -pkeyopt rsa_keygen_bits:2048 -out distribution.key
openssl req -new -sha256 -key distribution.key -out distribution.csr -subj "/CN=Jan Kowalski Distribution/emailAddress=jan@example.com"

openssl x509 -inform DER -in distribution.cer -out distribution.pem
openssl pkcs12 -export -inkey distribution.key -in distribution.pem -name "Apple Distribution" -out AppleDistribution.p12

openssl pkcs12 -info -noout -in AppleDistribution.p12

4. Sprawdź App ID i Bundle ID

Otwórz Identifiers. Jeśli aplikacja ma już App ID, wykorzystaj go. Bundle ID musi zgadzać się z kodem projektu, np. pl.jankowalski.testowaapka.

Od zera: + → App IDs → App → Continue. Wpisz Description, zaznacz Explicit i podaj własny Bundle ID. Sprawdź dane, kliknij Continue i Register. Te ekrany opisuje też tutorial 1. Dla samego Ad Hoc możesz pominąć jego część o tworzeniu rekordu w App Store Connect.

Nie zmieniaj identyfikatora istniejącej aplikacji tylko dla nowego kanału instalacji. W koncie Apple Developer zachowaj też Team ID; użyjemy go przy konfiguracji GitHub.

5. Odczytaj UDID: kabel albo profil

Wybierz jedną z dwóch metod. Jeśli masz już poprawny UDID, przejdź do rejestracji urządzenia. Nie publikuj pełnego identyfikatora na screenshotach.

Metoda A: przez kabel i Finder na Macu

1. Podłącz iPhone’a kablem do przesyłania danych i odblokuj go.
2. Potwierdź „Zaufaj temu komputerowi”, jeśli pojawi się komunikat.
3. Otwórz Finder i wybierz iPhone’a w sekcji Miejsca.
4. Klikaj wiersz informacji bezpośrednio pod nazwą urządzenia, aż zobaczysz UDID.
5. Skopiuj UDID, np. z menu pod prawym przyciskiem. Nie kopiuj EID.

Ilustracje tej metody znajdziesz również w tutorialu 3.

Metoda B: bez kabla, przez profil na iPhonie

1. Otwórz w Safari stronę odczytu UDID.
2. Pobierz profil Device UDID.
3. Przejdź do Ustawień i otwórz pobrany profil. Przeczytaj informacje i potwierdź instalację, jeśli chcesz skorzystać z tej usługi.
4. Wróć do wyniku w Safari i skopiuj UDID. W razie komunikatu bezpieczeństwa postępuj zgodnie z instrukcją na ekranie.

Odczyt odbywa się przez usługę obsługującą profil. Ten profil służy do odczytania identyfikatora. Nie jest profilem podpisującym aplikację i nie zastępuje rejestracji telefonu w Apple Developer. Metoda przez kabel pozostaje niezależną alternatywą.

6. Zarejestruj urządzenie w Apple Developer

Otwórz Devices. Jeśli Twój UDID już jest zarejestrowany i aktywny, wykorzystaj ten wpis.

1. Kliknij + i wybierz Register a Device.
2. Wybierz platformę obejmującą iOS, wpisz rozpoznawalną Device Name i swój Device ID (UDID).
3. Kliknij Continue i porównaj dane z odczytanym UDID.
4. Kliknij Register i sprawdź aktywny wpis na liście.

Nie wyłączaj urządzenia tylko po to, żeby odtworzyć tutorial. Apple ogranicza liczbę rejestracji; wyłączenie urządzenia w trakcie roku członkostwa nie zwraca wykorzystanego miejsca.

7. Utwórz profil Ad Hoc

Profil łączy App ID, certyfikat i wybrane urządzenia. Profil App Store z części 2 i profil Development z części 3 pozostają osobnymi plikami.

1. Otwórz Profiles i kliknij +.
2. W sekcji Distribution wybierz Ad Hoc, następnie Continue.
3. Wybierz App ID zgodny z Bundle ID projektu.
4. Zaznacz Apple Distribution, którego klucz masz w pliku .p12.
5. Wybierz swój iPhone i ewentualnie inne urządzenia, na których chcesz instalować tę aplikację.
6. Nadaj nazwę, np. TestowaApka-AdHoc. Sprawdź dane i kliknij Generate.
7. Kliknij Download. Zachowaj rzeczywistą nazwę pliku, np. TestowaApkaAdHoc.mobileprovision.

Jeśli masz już ważny profil Ad Hoc zgodny z tymi wymaganiami, wykorzystaj go. Nie trzeba tworzyć duplikatu dla screenshotu. Każda aplikacja o innym Bundle ID potrzebuje odpowiedniego profilu.

8. Dodaj trzy sekrety podpisywania

W repozytorium z kodem aplikacji otwórz Settings → Secrets and variables → Actions → Secrets → New repository secret. Przykład: jankowalski/testowa-apka. Repo aplikacji będzie kompilować i podpisywać build.

Jeżeli dwa sekrety certyfikatu z TestFlight są już poprawnie ustawione w tym repo, pozostaw je. Profil Ad Hoc dodaj pod nową nazwą. Nie nadpisuj profilu App Store.

macOS: kopiuj po jednym pliku

Wykonaj pierwszą komendę, wklej schowek do sekretu certyfikatu i zapisz. Dopiero potem wykonaj drugą dla profilu. Dostosuj nazwy i ścieżki:

base64 -i ~/Desktop/AppleDistribution.p12 | tr -d '\n' | pbcopy
base64 -i ~/Desktop/TestowaApkaAdHoc.mobileprovision | tr -d '\n' | pbcopy

[Convert]::ToBase64String([IO.File]::ReadAllBytes("$HOME\adhoc-signing\AppleDistribution.p12")) | Set-Clipboard
[Convert]::ToBase64String([IO.File]::ReadAllBytes("$HOME\adhoc-signing\TestowaApkaAdHoc.mobileprovision")) | Set-Clipboard

umask 077
base64 -w 0 AppleDistribution.p12 > certificate.base64.txt
base64 -w 0 TestowaApkaAdHoc.mobileprovision > profile.base64.txt

Hasła nie koduj. Kliknij Add secret po każdym wpisie. Base64 nie szyfruje danych. Nie wklejaj wartości sekretów do czatu ani screenshotów i nie dodawaj ich do Git.

9. Przygotuj publiczny hosting instalatora

iOS musi pobrać manifest i IPA przez HTTPS, bez logowania. W przykładzie użyjemy publicznego repozytorium GitHub Pages o nazwie ios-builds. Repo z kodem aplikacji może pozostać prywatne.

1. Utwórz na swoim koncie publiczne repo strony, np. jankowalski/ios-builds, z README i gałęzią main. Jeśli masz już odpowiednią stronę, wykorzystaj ją.
2. Dodaj plik index.html do katalogu głównego. Minimalna treść jest poniżej. Dodaj także pusty plik .nojekyll.
3. Otwórz Settings → Pages. W Build and deployment wybierz Deploy from a branch → main → /(root) → Save.
4. Po wdrożeniu otwórz adres pokazany w Pages i sprawdź HTTPS.

<!doctype html>
<html lang="pl"><meta charset="utf-8">
<title>Buildy iOS</title>
<a href="adhoc/">Aplikacje Ad Hoc</a>
</html>

Dla repo jankowalski/ios-builds adresem katalogu będzie zwykle https://jankowalski.github.io/ios-builds/adhoc/. Dla repo jankowalski.github.io: https://jankowalski.github.io/adhoc/. Przy własnej domenie użyj jej rzeczywistego adresu. Katalog adhoc pojawi się po pierwszej publikacji buildu.

Pliki IPA będą publicznie dostępne. iOS pozwoli je zainstalować tylko na urządzeniach z profilu. Podpisany IPA zawiera profil z identyfikatorami urządzeń, więc taki hosting nie jest prywatnym magazynem.

10. Pozwól workflow zapisywać buildy

Workflow aplikacji musi zapisywać pliki w drugim repozytorium. W tym przykładzie użyjemy tokenu z dostępem ograniczonym do repo strony.

1. GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
2. Podaj nazwę, np. Publish iOS builds, termin ważności i właściwego Resource owner.
3. W Repository access wybierz Only select repositories i wskaż wyłącznie repo strony, np. ios-builds.
4. W Repository permissions ustaw Contents: Read and write. Zachowaj domyślne Metadata read.
5. Wygeneruj token. Jeśli właścicielem jest organizacja, może być wymagane jej zatwierdzenie.
6. W repo aplikacji dodaj Repository secret BUILDS_REPO_TOKEN z wartością tokenu.

Nie pokazuj tokenu na screenie. Automatyczny GITHUB_TOKEN repo aplikacji nie zastępuje dostępu do innego repo. Dodatkowo push wykonany standardowym GITHUB_TOKEN nie wyzwala publikacji Pages z gałęzi. Token opisany tutaj służy tylko do publikacji, nie do podpisywania iOS.

11. Ustaw cztery Variables

W repo aplikacji otwórz Settings → Secrets and variables → Actions → Variables → New repository variable.

Zastąp wszystkie przykłady swoimi wartościami. Adres musi zawierać nazwę repo dla GitHub Project Pages, chyba że używasz własnej domeny. Workflow zapisuje pliki do adhoc/ w repo strony. Zmienne nie zastępują Bundle ID w projekcie ani danych profilu.

12. Dodaj gotowe pliki do repo aplikacji

Pobierz komplet plików ZIP. Rozpakuj go i skopiuj pliki do repo aplikacji, zachowując ścieżki. Folder .github może być ukryty przez menedżer plików.

Przykład zakłada projekt Swift/XcodeGen z project.yml w katalogu głównym, wspólną nazwą projektu i schematu oraz jedną aplikacją. Dla projektu Xcode bez XcodeGen dostosuj generowanie. Workspace, inne frameworki, extensions i Watch wymagają zmian w kompilacji i mapowaniu profili.

Workflow importuje istniejący certyfikat, tworzy niepodpisane archiwum, weryfikuje profil i eksportuje IPA metodą release-testing. Potem usuwa tymczasowe zasoby podpisywania i publikuje wyłącznie pliki instalatora. Nie tworzy nowych certyfikatów ani profili w Apple.

IPA musi mieć mniej niż 100 MiB w tym przykładzie. Większe pliki wymagają innego hostingu binarnego. Historia zwiększa rozmiar repo; przykład nie usuwa starszych wersji automatycznie.

Zapisz pliki na main. Nie nadpisuj istniejącego workflow o tej samej nazwie bez porównania jego zawartości.

13. Uruchom build ręcznie albo przez [adhoc]

W repo aplikacji otwórz Actions → Build and publish Ad Hoc → Run workflow. Wybierz main i kliknij Run workflow. Ręczne uruchomienie wymaga obecności pliku workflow na domyślnej gałęzi.

Możesz też dopisać znacznik do wiadomości ostatniego commita wysyłanego na main:

Add breathing animation [adhoc]

Przy kilku commitach liczy się ostatni. Przy squash merge dodaj znacznik do końcowej wiadomości squasha. Zwykły push bez znacznika pomija job Ad Hoc. Nie twórz pustych commitów tylko do uruchamiania buildu.

14. Sprawdź podpisanie i publikację

Otwórz run i sprawdź etapy archiwizacji, walidacji profilu, eksportu IPA i publikacji. Zielony workflow oznacza, że build został zapisany w repo strony. Osobno poczekaj na wdrożenie GitHub Pages.

Numer kompilacji pochodzi z GITHUB_RUN_NUMBER. Nowe uruchomienie dostaje nowy numer; Re-run tego samego runa zachowuje numer. Po zmianie kodu uruchom nowy build, a nie tylko ponów stary.

W katalogu adhoc/apps/ repo strony pojawią się kolejne wersje: IPA, manifest, ikona i metadane. Strona główna pokazuje najnowszą wersję każdej opublikowanej aplikacji; tapnięcie nazwy otwiera historię. Nie ma etapu TestFlight Processing.

15. Zainstaluj i zaktualizuj aplikację

1. Na zarejestrowanym iPhonie otwórz w Safari własny adres ADHOC_BASE_URL.
2. Znajdź ikonę, nazwę i wersję swojej aplikacji.
3. Naciśnij Install i potwierdź komunikat iOS.
4. Poczekaj na instalację na ekranie początkowym, otwórz aplikację i sprawdź jej działanie.

Link itms-services wskazuje manifest HTTPS, a manifest wskazuje IPA. Nie musisz ręcznie otwierać pobranego IPA w aplikacji Pliki. Przycisk pozostaje Install także przy aktualizacji, ponieważ Safari nie udostępnia stronie wiarygodnej informacji o zainstalowanej wersji.

Po następnej zmianie opublikuj nowy build. Przy tym samym Bundle ID i zgodnym podpisywaniu instalacja może zastąpić wcześniejszą wersję Ad Hoc. Tapnij nazwę lub ikonę aplikacji, aby wybrać konkretną wersję z historii. Starszy build nadal musi mieć ważny podpis i obejmować Twój telefon.

Przejście między TestFlight i Ad Hoc może wymagać usunięcia wcześniejszej instalacji. Najpierw zabezpiecz dane. Cofnięcie wersji również może być niezgodne z danymi zapisanymi przez nowszą aplikację. Ważność Ad Hoc wynika z podpisu i profilu, nie z 90 dni TestFlight.

16. Nowe urządzenie i rozwiązywanie problemów

Po dodaniu kolejnego iPhone’a zarejestruj jego UDID w Apple, odtwórz profil Ad Hoc z odpowiednią listą urządzeń, pobierz go i zaktualizuj ADHOC_PROVISIONING_PROFILE_BASE64. Następnie uruchom nowy build. Stare IPA zachowują stary profil.

Sprawdzaj konkretny komunikat. Nie obchodź błędów podpisu przez „Zawsze ufaj” i nie unieważniaj działających certyfikatów bez ustalenia przyczyny.

Przejdź z asystentem: jeden krok na wiadomość

Skopiuj prompt do nowej rozmowy i dołącz pliki przykładu. Przejdziemy od sprawdzenia istniejących zasobów do instalacji i aktualizacji. Screenshoty dodamy po rzeczywistym przejściu kolejnych ekranów.

Przeczytaj https://aleksanderfigiel.pl/ios-adhoc-tutorial-4/ i dołączone pliki przykładu. Jeśli nie masz dostępu, poproś o treść lub pliki. Nie udawaj odczytu.
Poprowadź mnie po polsku przez samodzielne Ad Hoc dla własnej aplikacji iOS. To ogólny setup Apple Developer + GitHub Actions + publiczny hosting HTTPS, bez dodatkowego backendu lub centralnego signera. Jeden mały krok na wiadomość; po każdym czekaj na potwierdzenie albo screenshot.
Najpierw sprawdź mój system, dostęp do Apple Developer, repo aplikacji i istniejące zasoby z TestFlight. Zbieraj konkretne nazwy i identyfikatory dopiero przy odpowiednim kroku. Nie używaj przykładów Jana Kowalskiego jako moich danych.
Jeśli mam ważny Apple Distribution i pasujący klucz prywatny lub .p12, użyj ich ponownie. Nie twórz duplikatów dla screenów. Sam .cer nie wystarczy. Apple Development nie zastępuje Apple Distribution. Jeśli brakuje kompletu, przejdź przez CSR, portal Certificates, import .cer i eksport .p12 z hasłem. Nie unieważniaj certyfikatów używanych przez inne aplikacje.
UDID odczytaj według mojego wyboru: Finder po kablu albo profil ze strony https://aleksanderfigiel.pl/udid/ bez kabla. Wyjaśnij, że odczyt UDID nie rejestruje urządzenia w Apple. Nie myl UDID z EID. Następnie sprawdź aktywny wpis w Devices albo zarejestruj nowe urządzenie. Nie każ wyłączać już zarejestrowanego telefonu.
Przygotuj ręcznie profil Distribution > Ad Hoc dla mojego App ID, certyfikatu z .p12 i wybranych urządzeń. Pobierz go. Profil App Store z TestFlight pozostaje osobny. Ten przykład nie używa Apple API .p8 i nie tworzy profili automatycznie.
W repo aplikacji ustaw DISTRIBUTION_CERTIFICATE_P12_BASE64, DISTRIBUTION_CERTIFICATE_PASSWORD i ADHOC_PROVISIONING_PROFILE_BASE64. Pliki koduj Base64, hasło pozostaw zwykłym tekstem. Wykorzystaj już poprawnie zapisane sekrety certyfikatu. Nie proś o wartości sekretów, hasła, pliki .p12 ani klucze prywatne w czacie.
Pomóż skonfigurować osobne publiczne repo strony z GitHub Pages z main/(root), HTTPS, index.html i .nojekyll. Ostrzeż rzeczowo, że publiczny IPA zawiera profil z UDID. Ustal prawdziwy adres katalogu /adhoc/, uwzględniając nazwę repo przy Project Pages. Token fine-grained ogranicz do repo strony z Contents read/write; zapisz go jako BUILDS_REPO_TOKEN w repo aplikacji, bez ujawniania w czacie.
Ustaw Variables: XCODE_PROJECT, APPLE_TEAM_ID, BUILDS_REPOSITORY, ADHOC_BASE_URL. Sprawdź zgodność projektu, schematu i Bundle ID. Gotowy przykład dotyczy jednej aplikacji Swift/XcodeGen bez extensions/Watch. Dla innego projektu dostosuj kompilację, nie deklaruj zgodności bez sprawdzenia.
Dodaj pliki z ZIP zachowując ścieżki. Uruchom Actions > Build and publish Ad Hoc > Run workflow na main albo użyj [adhoc] w ostatnim commicie pusha. Zwykły push pomija job. Nie twórz pustych commitów. Znaczniki [skip testflight] działają tylko, jeśli istniejący workflow je sprawdza; nie przedstawiaj ich jako funkcji GitHub. Nie dodawaj [testflight] do zmiany dotyczącej tylko Ad Hoc.
Sprawdź build, podpis i publikację Pages, a potem instalację na rzeczywistym iPhonie przez Safari. Sprawdź aktualizację i historię. Strona nie wykrywa zainstalowanej wersji. Przed ewentualnym usuwaniem aplikacji zabezpiecz dane. Dodanie urządzenia wymaga nowego profilu, aktualizacji sekretu i nowego buildu.
Zbieraj screenshoty po jednym, korzystając z podpisanych placeholderów. Na screenshotach nie może być sekretów, haseł ani pełnych UDID. Do publikacji użyj kopii z anonimizacją. Nie deklaruj udanego testu bez potwierdzenia. Nie używaj znaku em dash. Zakończ listą potwierdzonych zasobów i braków, bez przenoszenia ich do innych systemów i bez publikacji w App Store.

Źródła i zakres sprawdzenia

To samodzielny przykład do przejścia z własną aplikacją i kontami Apple/GitHub. Pliki sprawdzono lokalnie pod kątem składni i logiki. Pełny build, podpisywanie i instalacja tego wariantu wymagają jeszcze przejścia na urządzeniu. Placeholdery nie są dowodem ukończonych testów.

• Apple: profil Ad Hoc
• Apple: tworzenie CSR
• Apple: rejestracja urządzenia
• Apple: urządzenia i limity
• GitHub: GitHub Pages
• GitHub: tokeny fine-grained
• GitHub: warunki jobów
• OpenSSL: PKCS#12