/ci-cd-setup

name: ci-cd-setup
description: Generate CI/CD configuration for automated builds, tests, and distribution of iOS/macOS apps. Use when setting up GitHub Actions, Xcode Cloud, or fastlane for continuous integration, TestFlight, or App Store deployment.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22

CI/CD Setup Generator

Generate CI/CD configuration for automated builds, tests, and distribution of iOS/macOS apps.

When This Skill Activates

• User wants to automate their build and test process
• User mentions GitHub Actions, Xcode Cloud, or fastlane
• User wants to set up TestFlight or App Store deployment
• User asks about continuous integration for their app

Pre-Generation Checks

Before generating, verify:

1. **Existing CI Configuration**

   # Check for existing CI files
   ls -la .github/workflows/ 2>/dev/null
   ls -la ci_scripts/ 2>/dev/null
   ls -la fastlane/ 2>/dev/null

2. **Project Structure**

   # Find Xcode project/workspace
   find . -name "*.xcodeproj" -o -name "*.xcworkspace" | head -5

3. **Package Manager**

   # Check for SPM vs CocoaPods
   ls Package.swift 2>/dev/null
   ls Podfile 2>/dev/null

Configuration Questions

1. CI/CD Platform

• **GitHub Actions** (Recommended) - Full control, extensive marketplace
• **Xcode Cloud** - Native Apple integration, simpler setup
• **Both** - GitHub for PRs/tests, Xcode Cloud for releases

2. Distribution Method

• **TestFlight** - Beta testing via App Store Connect
• **App Store** - Production releases
• **Direct** (macOS only) - Notarized DMG/PKG distribution
• **All** - Full pipeline from dev to production

3. Include fastlane?

• **Yes** - Advanced automation, match for code signing
• **No** - Simpler setup using xcodebuild directly

4. Code Signing Approach

• **Manual** - Certificates in GitHub Secrets
• **match** (fastlane) - Git-based certificate management
• **Xcode Cloud Managed** - Apple handles signing

Generated Files

GitHub Actions

.github/workflows/
├── build-test.yml        # PR checks, unit tests
├── deploy-testflight.yml # TestFlight deployment
└── deploy-appstore.yml   # App Store submission

Xcode Cloud

ci_scripts/
├── ci_post_clone.sh      # Post-clone setup
└── ci_pre_xcodebuild.sh  # Pre-build configuration

fastlane

fastlane/
├── Fastfile              # Lane definitions
├── Appfile               # App configuration
└── Matchfile             # Code signing (if using match)

SwiftLint

.swiftlint.yml            # from templates/swiftlint/swiftlint.yml

Merging Skill Rule Fragments

Skills in this library may ship graduated enforcement as a `rules/swiftlint.yml` fragment (`opt_in_rules` + `custom_rules`) — prose rules turned into deterministic lint. When generating `.swiftlint.yml`:

1. Start from `templates/swiftlint/swiftlint.yml`. 2. For each skill the project actually uses, check for `skills/<category>/<skill>/rules/swiftlint.yml`; append its `custom_rules` entries and union its `opt_in_rules`. 3. Respect fragment scoping comments — e.g. `observable_object_legacy` applies only to iOS 17+/macOS 14+ deployment targets, and `xctest_in_unit_tests` must keep its UITests exclusion (XCUITest legitimately requires XCTest). 4. The generated `build-test.yml` runs the `lint` job automatically once `.swiftlint.yml` exists (`if: hashFiles('.swiftlint.yml') != ''`).

Current fragments: `security/` (hardcoded secrets), `ios/coding-best-practices` (print-in-production, legacy ObservableObject, force_unwrapping/force_try), `testing/tdd-feature` (XCTest scoped out of unit tests), `swift/concurrency` (@unchecked Sendable without justification).

Integration Steps

GitHub Actions Setup

1. **Add Repository Secrets** (Settings > Secrets and variables > Actions):

• `APP_STORE_CONNECT_API_KEY_ID` - API Key ID
• `APP_STORE_CONNECT_API_ISSUER_ID` - Issuer ID
• `APP_STORE_CONNECT_API_KEY_CONTENT` - Private key (.p8 content)
• `CERTIFICATE_P12` - Base64-encoded .p12 certificate
• `CERTIFICATE_PASSWORD` - Certificate password
• `PROVISIONING_PROFILE` - Base64-encoded provisioning profile

2. **Create App Store Connect API Key**:

• Go to App Store Connect > Users and Access > Keys
• Generate API Key with "App Manager" role
• Download the .p8 file (only available once)

3. **Export Certificate**:

   # Export from Keychain as .p12, then base64 encode
   base64 -i certificate.p12 | pbcopy

Xcode Cloud Setup

1. **Enable Xcode Cloud** in Xcode:

• Product > Xcode Cloud > Create Workflow
• Connect to App Store Connect

2. **Configure Workflow**:

• Set start conditions (branch, PR, tag)
• Configure environment variables
• Set up post-actions (TestFlight, App Store)

3. **Add ci_scripts** to repository for customization

fastlane Setup

1. **Install fastlane**:

   brew install fastlane

2. **Initialize** (if starting fresh):

   fastlane init

3. **Set up match** (optional, for code signing):

   fastlane match init
   fastlane match development
   fastlane match appstore

Best Practices

Caching

• Cache Swift Package Manager dependencies
• Cache DerivedData for faster builds
• Use selective caching to avoid stale artifacts

Secrets Management

• Never commit certificates or keys
• Use environment variables for sensitive data
• Rotate API keys periodically

Build Optimization

• Use incremental builds where possible
• Parallelize test execution
• Skip unnecessary steps on draft PRs

Notifications

• Slack/Discord integration for build status
• Email notifications for failures
• GitHub status checks for PRs

References

• [GitHub Actions for Xcode](https://github.com/actions/runner-images/blob/main/images/macos)
• [Xcode Cloud Documentation](https://developer.apple.com/docum