# fastlane-ios-release

> Automate the full iOS App pre-release pipeline with fastlane for Pope's projects: code signing (match), build/archive (build_app/gym), TestFlight upload (pilot), App Store metadata/screenshots upload & optional submission (deliver), plus preflight checks (tests, lint, versioning, changelog). Use when setting up or running a repeatable iOS release workflow.

- Author: Heng Xia
- Repository: rwmjhb/openclaw-skills
- Version: 20260201140253
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/rwmjhb/openclaw-skills
- Web: https://mule.run/skillshub/@@rwmjhb/openclaw-skills~fastlane-ios-release:20260201140253

---

---
name: fastlane-ios-release
description: "Automate the full iOS App pre-release pipeline with fastlane for Pope's projects: code signing (match), build/archive (build_app/gym), TestFlight upload (pilot), App Store metadata/screenshots upload & optional submission (deliver), plus preflight checks (tests, lint, versioning, changelog). Use when setting up or running a repeatable iOS release workflow."
---

# fastlane iOS Release Pipeline (Secure)

This skill helps you set up and run a **repeatable iOS release workflow** using fastlane.

## Safety & rules (must follow)

- **No secrets in git**: never commit `.p8`, passwords, tokens, `MATCH_PASSWORD`, or API key JSON.
- **No destructive ops by default**: avoid `match nuke`, deleting profiles, or revoking certs unless explicitly requested.
- **External side effects must be confirmed** before executing:
  - uploading to TestFlight/App Store
  - submitting for review
  - pushing tags/commits

## What fastlane can automate (high level)

From fastlane docs:
- Install/setup via Bundler + `fastlane init`
- **Codesigning** with `match` (shared certs/profiles stored encrypted in your repo/storage)
- **Build** with `build_app` (gym) to produce `.ipa` and dSYMs
- **TestFlight** upload/distribution with `pilot` / `upload_to_testflight`
- **App Store** upload of metadata/screenshots/binary with `deliver` / `upload_to_app_store` (optionally `submit_for_review`)

## Inputs to collect (one-time)

You (Pope) should provide:
1. iOS project path (Xcode workspace/project)
2. Scheme name(s) + configuration (Release)
3. Bundle ID(s) (main app + extensions, if any)
4. Team ID
5. Signing strategy:
   - match git repo URL (private) OR S3/GCS
   - match type(s): `appstore`, `development`, `adhoc` (optional)
6. App Store Connect auth method (preferred):
   - **API Key** (issuer_id, key_id, .p8 path) OR Apple ID (2FA)
7. Release policy:
   - TestFlight only vs App Store submission
   - phased release, automatic release
   - metadata/screenshots management

## Recommended structure in Fastfile

Create lanes that separate **verification** from **upload**:

- `lane :verify` (no side effects)
  - run tests (e.g. `scan`)
  - ensure clean git state
  - ensure version/build numbers
  - optional: `deliver` precheck only

- `lane :build` (local build only)
  - `match(type: "appstore")` (or `sync_code_signing`)
  - `build_app(...)` (`export_method: "app-store"`)

- `lane :beta` (TestFlight)
  - `verify`
  - `build`
  - `upload_to_testflight` (pilot)

- `lane :release` (App Store)
  - `verify`
  - `build`
  - `deliver(...)` (upload metadata/screenshots/binary)
  - optional: `submit_for_review: true` only if confirmed

## Implementation guide (setup)

### 1) Install via Bundler (recommended)

From fastlane docs (preferred approach):

```bash
# in repo root
cat > Gemfile <<'EOF'
source "https://rubygems.org"

gem "fastlane"
EOF
bundle update
```

Run fastlane via:
```bash
bundle exec fastlane <lane>
```

### 2) Initialize

```bash
bundle exec fastlane init
```

This generates `fastlane/Fastfile`, `Appfile`, etc.

### 3) Configure code signing with match

Docs: https://docs.fastlane.tools/actions/match/

**Recommended repo strategy:** one private repo, **branch per Apple Developer Team**.

#### 3.1 Create or choose a match repo

- Private repo example: `ios-certificates-signing`
- Branch name example: `team-<TEAM_ID>`

#### 3.2 Prefer HTTPS for headless/CI unless SSH keys are guaranteed

If this machine/CI doesn’t have GitHub SSH keys configured, `git@github.com:...` will fail.
Use HTTPS + basic auth:

- `git_url("https://github.com/<owner>/<repo>.git")`
- `MATCH_GIT_BASIC_AUTHORIZATION` (Base64 of `username:token`)

Example (GitHub CLI token):
```bash
TOKEN=$(gh auth token)
export MATCH_GIT_BASIC_AUTHORIZATION=$(printf "<github-username>:%s" "$TOKEN" | base64)
```

#### 3.3 Required env vars (do NOT commit secrets)

Set match passphrase (encrypt/decrypt):
```bash
export MATCH_PASSWORD="<your-passphrase>"  # do not commit
```

Apple Developer Portal auth for match (pick one):
- **Recommended for CI/headless:** `FASTLANE_SESSION` (generated by `fastlane spaceauth`)
- Fallback: interactive Apple ID login (not stable for automation)

> Important: App Store Connect API Key is great for `pilot/deliver`, but **match still needs Dev Portal auth**.

#### 3.4 Generating FASTLANE_SESSION (one-time, interactive)

If you hit errors like:
- `Missing username, and running in non-interactive shell`

Generate a session token:
```bash
export FASTLANE_USER="<apple-id-email>"
bundle exec fastlane spaceauth
```
Save the resulting `FASTLANE_SESSION=...` into your secret store (file/CI secret).

#### 3.5 Run match

One-time bootstrap (creates/repairs certs/profiles and pushes to match repo):
```bash
bundle exec fastlane match appstore --verbose
```

Verification-only (does not create new signing assets):
```bash
bundle exec fastlane match appstore --readonly
```

### 4) Build (gym/build_app)

Docs: https://docs.fastlane.tools/actions/build_app/

Example:
```ruby
build_app(
  workspace: "YourApp.xcworkspace",
  scheme: "YourApp",
  configuration: "Release",
  export_method: "app-store"
)
```

### 5) Upload to TestFlight (pilot)

Docs: https://docs.fastlane.tools/actions/pilot/

Prefer App Store Connect API Key auth.

### 6) Upload to App Store (deliver)

Docs: https://docs.fastlane.tools/actions/deliver/

Use `deliver init` to pull metadata templates.

## Supporting files

- `references/fastfile-template.md`: opinionated Fastfile skeleton with safe lanes
- `references/env-vars.md`: required environment variables (no secrets in repo)
- `references/security-review.md`: mandatory review for release automation
- `scripts/bootstrap_fastlane.sh`: generate fastlane files with placeholders (supports --dry-run)
- `scripts/security_scan.sh`: scan the skill itself for secrets/dangerous commands

## Project notes: cat-ai-assistant (MeowMemo) concrete values

These were successfully verified in Pope’s environment:

- Flutter repo: `/Users/pope/github_repository/cat-ai-assistant/cat_ai_assistant_flutter/`
- Xcode project: `ios/Runner.xcodeproj`
- Scheme: `Runner`
- Bundle ID: `com.catai.assistant.catAiAssistant`
- Team ID: `T3HYL5JSS9`
- Match repo (private): `https://github.com/rwmjhb/ios-certificates-signing.git`
- Match branch (per-team): `team-T3HYL5JSS9`

### Ruby/Bundler pitfall (macOS system Ruby vs Homebrew Ruby)

If you see errors like:
- `Could not find 'bundler' (4.x) required by Gemfile.lock`

Your terminal is likely using `/usr/bin/ruby`.
Fix by prepending Homebrew Ruby:

```bash
export PATH="/opt/homebrew/opt/ruby/bin:/opt/homebrew/bin:$PATH"
hash -r
ruby -v
bundle -v
```

## Mandatory security review

Before packaging or using this workflow for real releases, run:

1) Read & satisfy: `references/security-review.md`
2) Scan: `bash scripts/security_scan.sh .`