ci: add iPhone deploy workflow + CI/CD setup docs

- .gitea/workflows/pr-iphone-deploy.yml: PR → Build → iPhone → LGTM → Merge - docs/ci-cd-setup.md: Mac runner + secrets setup guide
2026-06-26 20:50:53 +00:00
parent bd81ce92ad
commit 001062c6d3
2 changed files with 272 additions and 0 deletions
--- a/docs/ci-cd-setup.md
+++ b/docs/ci-cd-setup.md
@@ -0,0 +1,127 @@
+# CI/CD Setup — iPhone Deploy Workflow
+
+This guide covers setting up a **Gitea Actions** macOS runner to automatically build, test, and deploy **TabataGo** to a physical iPhone on every PR to `main`.
+
+## Prerequisites
+
+### Hardware
+- **Mac** running macOS 15 (Sequoia) or later
+- **Xcode 26+** installed (required for iOS 26.0 / watchOS 11.0 targets)
+- **iPhone** (iOS 26+) connected via USB, with Developer Mode enabled
+
+### Software
+- [Gitea Actions Runner](https://docs.gitea.com/usage/actions/act-runner) installed and registered
+- `brew` (Homebrew) installed
+- `xcodegen` (installed automatically by the workflow)
+- `libimobiledevice` + `ideviceinstaller` (installed automatically by the workflow)
+
+## 1. Register the macOS Runner
+
+```bash
+# On the Mac:
+./act_runner register \
+  --instance https://gitea.1000co.fr \
+  --token <RUNNER_TOKEN> \
+  --name "macos-runner" \
+  --labels macos
+
+# Start the runner
+./act_runner daemon
+```
+
+> **Important:** The runner must have the label `macos` because the workflow uses `runs-on: macos`.
+
+## 2. iPhone Preparation
+
+1. Connect the iPhone to the Mac via USB
+2. Trust the computer on the iPhone when prompted
+3. Enable **Developer Mode** on the iPhone:  
+   `Settings → Privacy & Security → Developer Mode`
+4. Get the device UDID:
+   ```bash
+   # Via Xcode: Window → Devices and Simulators, or:
+   idevice_id -l
+   ```
+
+## 3. Configure Secrets
+
+Add these secrets in the Gitea repository:  
+`Settings → Actions → Secrets`
+
+| Secret Name | Description | How to Get |
+|-------------|-------------|------------|
+| `IPHONE_UDID` | 40-character UDID of the target iPhone | `idevice_id -l` on the connected Mac |
+| `GITEA_TOKEN` | Gitea API token with repo + pull request scope | `Gitea → Settings → Applications → Generate Token` |
+
+### Gitea Token Permissions
+The token needs:
+- `read:repository` — to read PR metadata
+- `write:issue` — to post LGTM comments
+- `write:pull_request` — to merge approved PRs
+
+## 4. Xcode Signing
+
+The workflow uses **automatic code signing**. Ensure:
+
+1. The Mac runner is signed into an Apple Developer account in Xcode:
+   ```bash
+   # Verify:
+   xcrun security find-identity -v -p codesigning
+   ```
+
+2. The Apple ID used must be part of the team `2MJF39L8VY` (configured in `ExportOptions.plist`).
+
+3. For first-time setup, open Xcode on the runner Mac and sign in:
+   ```
+   Xcode → Settings → Accounts → Add Apple ID
+   ```
+
+## 5. Workflow Overview
+
+The workflow at `.gitea/workflows/pr-iphone-deploy.yml` triggers on PRs to `main`:
+
+```
+PR Opened / Updated
+       ↓
+  Checkout + XcodeGen generate
+       ↓
+  Resolve SPM packages
+       ↓
+  Build for iPhone (Release)
+       ↓
+  Export IPA + Install on device
+       ↓
+  Run unit tests
+       ↓
+  Post LGTM comment on PR
+       ↓
+  Auto-merge (if no failures)
+```
+
+## 6. Manual Test Run
+
+To test the workflow locally on the runner Mac:
+
+```bash
+# Simulate the build:
+cd tabatago-swift
+xcodegen generate
+xcodebuild build \
+  -project TabataGo.xcodeproj \
+  -scheme TabataGo \
+  -destination "id=<YOUR_IPHONE_UDID>" \
+  -configuration Release \
+  -allowProvisioningUpdates
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Device not found" | Check USB connection, trust prompt, UDID in secrets |
+| "Code signing failed" | Sign into Xcode on the runner Mac, verify team membership |
+| "No provisioning profile" | Run `-allowProvisioningUpdates` or open project in Xcode once |
+| `xcodegen: command not found` | `brew install xcodegen` (workflow handles this) |
+| `ideviceinstaller` fails | Ensure iPhone is unlocked and trusted; try Xcode Organizer manually |
+| Runner doesn't pick up job | Verify runner label is `macos` and runner is connected |
+| Token permission errors | Ensure `GITEA_TOKEN` has `write:issue` and `write:pull_request` scopes |