Skip to content

VoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription & audiobook creation in 646 languages.

ci(ios): add TestFlight upload workflow

velixio08fe4b70b8b7
diff --git a/.github/workflows/ios-testflight.yml b/.github/workflows/ios-testflight.yml
new file mode 100644
index 000000000..4eeee7839
--- /dev/null
+++ b/.github/workflows/ios-testflight.yml
@@ -0,0 +1,105 @@
+# iOS TestFlight — signs the companion app with the team's App Store Connect API
+# key and uploads it to TestFlight. Owner-dispatched from `main` only; nothing is
+# submitted for App Store review (see docs/mobile.md → TestFlight).
+
+name: iOS TestFlight
+
+on:
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ios-testflight
+ cancel-in-progress: false
+
+jobs:
+ testflight:
+ if: github.ref == 'refs/heads/main'
+ runs-on: macos-15
+ timeout-minutes: 60
+ # Holds the App Store Connect secrets; restrict it to `main` in repository settings.
+ environment: app-store-connect
+ env:
+ # Unique and increasing per upload, including reruns of the same run.
+ VOICESTUDIO_IOS_BUILD_NUMBER: ${{ github.run_number }}.${{ github.run_attempt }}
+ steps:
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+ with:
+ persist-credentials: false
+
+ - name: Require signing credentials
+ env:
+ ASC_KEY_ID: ${{ secrets.APP_STORE_CONNECT_KEY_ID }}
+ ASC_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }}
+ ASC_KEY: ${{ secrets.APP_STORE_CONNECT_API_KEY }}
+ TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+ run: |
+ for name in ASC_KEY_ID ASC_ISSUER_ID ASC_KEY TEAM_ID; do
+ test -n "${!name}" || { echo "Missing $name; see docs/mobile.md → TestFlight"; exit 1; }
+ done
+
+ - name: Generate Xcode project
+ run: |
+ brew install xcodegen
+ xcodegen generate --spec mobile/ios/VoiceStudio/project.yml
+
+ - name: Write App Store Connect API key
+ env:
+ ASC_KEY: ${{ secrets.APP_STORE_CONNECT_API_KEY }}
+ run: |
+ umask 077
+ printf '%s\n' "$ASC_KEY" > "$RUNNER_TEMP/asc_api_key.p8"
+
+ # Automatic signing with the API key creates the cloud-managed Apple
+ # Distribution certificate and App Store profile; no .p12 is stored.
+ - name: Archive signed app
+ env:
+ ASC_KEY_ID: ${{ secrets.APP_STORE_CONNECT_KEY_ID }}
+ ASC_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }}
+ TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+ run: |
+ xcodebuild -project mobile/ios/VoiceStudio/VoiceStudio.xcodeproj \
+ -scheme VoiceStudio -configuration Release \
+ -destination 'generic/platform=iOS' \
+ -archivePath "$RUNNER_TEMP/VoiceStudio.xcarchive" \
+ -allowProvisioningUpdates \
+ -authenticationKeyPath "$RUNNER_TEMP/asc_api_key.p8" \
+ -authenticationKeyID "$ASC_KEY_ID" \
+ -authenticationKeyIssuerID "$ASC_ISSUER_ID" \
+ DEVELOPMENT_TEAM="$TEAM_ID" CODE_SIGN_STYLE=Automatic \
+ archive
+
+ - name: Verify archive signature and version
+ run: |
+ APP="$RUNNER_TEMP/VoiceStudio.xcarchive/Products/Applications/VoiceStudio.app"
+ codesign --verify --deep --strict "$APP"
+ codesign -dvv "$APP" 2>&1 | grep -q '^Authority=Apple Distribution:'
+ test "$(/usr/libexec/PlistBuddy -c 'Print CFBundleVersion' "$APP/Info.plist")" = "$VOICESTUDIO_IOS_BUILD_NUMBER"
+
+ - name: Upload to TestFlight
+ env:
+ ASC_KEY_ID: ${{ secrets.APP_STORE_CONNECT_KEY_ID }}
+ ASC_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }}
+ TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+ run: |
+ /usr/libexec/PlistBuddy -c 'Add :method string app-store-connect' \
+ -c 'Add :destination string upload' \
+ -c "Add :teamID string $TEAM_ID" \
+ -c 'Add :signingStyle string automatic' \
+ -c 'Add :manageAppVersionAndBuildNumber bool false' \
+ -c 'Add :testFlightInternalTestingOnly bool true' \
+ "$RUNNER_TEMP/ExportOptions.plist"
+ xcodebuild -exportArchive \
+ -archivePath "$RUNNER_TEMP/VoiceStudio.xcarchive" \
+ -exportOptionsPlist "$RUNNER_TEMP/ExportOptions.plist" \
+ -exportPath "$RUNNER_TEMP/export" \
+ -allowProvisioningUpdates \
+ -authenticationKeyPath "$RUNNER_TEMP/asc_api_key.p8" \
+ -authenticationKeyID "$ASC_KEY_ID" \
+ -authenticationKeyIssuerID "$ASC_ISSUER_ID"
+
+ - name: Remove API key
+ if: always()
+ run: rm -f "$RUNNER_TEMP/asc_api_key.p8"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index aef776866..b65f2b24f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -64,6 +64,8 @@ metadata and the backend fallback mirror it.
- New `mobile` workflow builds and tests both phone apps; a contract test fails when their theme or API description drifts from the desktop app (#2965)
+- iOS TestFlight workflow: maintainers can upload a signed iPhone build for internal testers from `main` ([guide](docs/mobile.md#testflight-maintainers))
+
- Gallery preview fallback smoke no longer flakes when a slower runner reads the playing clip in several byte ranges (#3018)
## [0.5.7] — 2026-10-17
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index 49c39b48e..81147b702 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -48,6 +48,10 @@ Electron publication uses these GitHub Actions secrets:
and `APPLE_TEAM_ID` for macOS notarization and stapling.
- `ELECTRON_WINDOWS_CSC_LINK` and `ELECTRON_WINDOWS_CSC_KEY_PASSWORD` for
Windows Authenticode signing. The macOS certificate cannot sign Windows apps.
+- `APP_STORE_CONNECT_KEY_ID`, `APP_STORE_CONNECT_ISSUER_ID` and
+ `APP_STORE_CONNECT_API_KEY` in the `app-store-connect` environment for the
+ iOS TestFlight upload ([`mobile.md`](mobile.md#testflight-maintainers)).
+ TestFlight is not a release channel.
- The repository `GITHUB_TOKEN` for draft creation and asset uploads.
- `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` for the Docker Hub mirror.
- `POSTHOG_PROJECT_TOKEN` (secret) and `POSTHOG_HOST` (repository variable),
diff --git a/docs/mobile.md b/docs/mobile.md
index 9f60e269d..1fcbdb4d5 100644
--- a/docs/mobile.md
+++ b/docs/mobile.md
@@ -75,3 +75,23 @@ after 7 days; turn on Developer Mode on the iPhone (Settings → Privacy &
Security) when iOS asks. App text uses the
Electron locale catalogs (`mobile.*` keys). The `mobile` workflow builds and
tests both apps.
+
+## TestFlight (maintainers)
+
+The `iOS TestFlight` workflow signs the iPhone app and uploads it to TestFlight
+for the team's internal testers. It is dispatched by hand from `main` and never
+submits the app for App Store review. One-time setup in the Apple Developer team:
+
+1. Register the App ID `com.voicestudio.mobile` (Certificates, Identifiers &
+ Profiles → Identifiers) and create the app in App Store Connect with it.
+2. Create an App Store Connect API key with the **Admin** role (Users and
+ Access → Integrations). Admin lets CI create the cloud-managed Apple
+ Distribution certificate and App Store profile, so no `.p12` is stored.
+3. Create the `app-store-connect` environment (Settings → Environments), limit
+ it to the `main` branch, and add `APP_STORE_CONNECT_KEY_ID`,
+ `APP_STORE_CONNECT_ISSUER_ID` and `APP_STORE_CONNECT_API_KEY` (the full
+ `.p8` text). `APPLE_TEAM_ID` is shared with macOS notarization.
+
+The version is the root `package.json` version without any `-beta.N` suffix
+(App Store Connect accepts only `X.Y.Z`); the build number is the workflow run
+number and attempt, so every upload is new.
diff --git a/mobile/ios/scripts/prepare_resources.py b/mobile/ios/scripts/prepare_resources.py
index 9bc112cb4..8d451953c 100644
--- a/mobile/ios/scripts/prepare_resources.py
+++ b/mobile/ios/scripts/prepare_resources.py
@@ -2,6 +2,7 @@
"""Copy authoritative catalogs; localize OS permission prompts; derive version from root."""
import argparse
import json
+import os
import pathlib
import plistlib
import re
@@ -26,6 +27,21 @@ def lookup(catalog, key):
return value if isinstance(value, str) else None
+def marketing_version(version):
+ # App Store Connect accepts only X.Y.Z, so a beta uploads as its X.Y.Z under a new build number.
+ match = re.fullmatch(r"(\d+\.\d+\.\d+)(?:-beta\.\d+)?", version)
+ if not match:
+ raise ValueError(f"Unsupported app version for iOS: {version}")
+ return match.group(1)
+
+
+def build_number(value):
+ # TestFlight needs a new, increasing build number per upload: up to three integers.
+ if not re.fullmatch(r"\d+(?:\.\d+){0,2}", value):
+ raise ValueError(f"Invalid iOS build number: {value}")
+ return value
+
+
def prepare(output, info):
output.mkdir(parents=True, exist_ok=True)
catalogs = output / "Catalogs"
@@ -58,8 +74,8 @@ def prepare(output, info):
(localized / "InfoPlist.strings").write_text("\n".join(lines) + "\n")
version = json.loads((ROOT / "package.json").read_text())["version"]
data = plistlib.loads((IOS / "VoiceStudio/Info.plist").read_bytes())
- data["CFBundleShortVersionString"] = version
- data["CFBundleVersion"] = "1"
+ data["CFBundleShortVersionString"] = marketing_version(version)
+ data["CFBundleVersion"] = build_number(os.environ.get("VOICESTUDIO_IOS_BUILD_NUMBER", "1"))
data["CFBundleLocalizations"] = sorted(path.stem for path in source.glob("*.json"))
for field, key in permissions.items():
data[field] = lookup(english, key)
diff --git a/tests/test_ios_testflight.py b/tests/test_ios_testflight.py
new file mode 100644
index 000000000..3f919df94
--- /dev/null
+++ b/tests/test_ios_testflight.py
@@ -0,0 +1,65 @@
+import importlib.util
+import plistlib
+from pathlib import Path
+
+import pytest
+import yaml
+
+
+ROOT = Path(__file__).resolve().parents[1]
+WORKFLOW = ROOT / ".github" / "workflows" / "ios-testflight.yml"
+SPEC = importlib.util.spec_from_file_location("prepare_resources", ROOT / "mobile/ios/scripts/prepare_resources.py")
+prepare_resources = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(prepare_resources)
+
+
+def load_workflow():
+ return yaml.load(WORKFLOW.read_text(), Loader=yaml.BaseLoader)
+
+
[email protected](("version", "expected"), [("0.5.7", "0.5.7"), ("0.5.8-beta.2", "0.5.8")])
+def test_marketing_version_is_app_store_shaped(version, expected):
+ assert prepare_resources.marketing_version(version) == expected
+
+
[email protected]("version", ["0.5", "0.5.8-rc.1", "v0.5.8"])
+def test_marketing_version_rejects_unsupported_versions(version):
+ with pytest.raises(ValueError):
+ prepare_resources.marketing_version(version)
+
+
+def test_build_number_comes_from_the_environment(tmp_path, monkeypatch):
+ monkeypatch.setenv("VOICESTUDIO_IOS_BUILD_NUMBER", "42.2")
+ prepare_resources.prepare(tmp_path / "bundle", tmp_path / "Info.plist")
+ info = plistlib.loads((tmp_path / "Info.plist").read_bytes())
+ assert info["CFBundleVersion"] == "42.2"
+ assert prepare_resources.re.fullmatch(r"\d+\.\d+\.\d+", info["CFBundleShortVersionString"])
+
+
[email protected]("value", ["", "1.2.3.4", "12a"])
+def test_build_number_rejects_values_app_store_connect_refuses(value):
+ with pytest.raises(ValueError):
+ prepare_resources.build_number(value)
+
+
+def test_workflow_is_manual_main_only_and_read_only():
+ workflow = load_workflow()
+ assert set(workflow["on"]) == {"workflow_dispatch"}
+ assert workflow["permissions"] == {"contents": "read"}
+ job = workflow["jobs"]["testflight"]
+ assert job["if"] == "github.ref == 'refs/heads/main'"
+ assert job["environment"] == "app-store-connect"
+ assert "github.run_attempt" in job["env"]["VOICESTUDIO_IOS_BUILD_NUMBER"]
+
+
+def test_workflow_signs_verifies_and_cleans_up_the_key():
+ steps = load_workflow()["jobs"]["testflight"]["steps"]
+ names = [step.get("name") for step in steps]
+ assert names.index("Verify archive signature and version") < names.index("Upload to TestFlight")
+ cleanup = steps[-1]
+ assert cleanup["name"] == "Remove API key" and cleanup["if"] == "always()"
+ source = WORKFLOW.read_text()
+ assert "CODE_SIGNING_ALLOWED=NO" not in source
+ assert "testFlightInternalTestingOnly bool true" in source
+ # Secrets reach only the steps that need them, never the whole job.
+ assert "secrets." not in yaml.dump(load_workflow()["jobs"]["testflight"].get("env", {}))