# macos-cicd-distributor

> macOS app signing, notarization, and distribution expert. Guides developers through code signing with Developer ID, hardened runtime, notarization with notarytool, packaging as DMG/PKG/ZIP, and distribution via App Store, TestFlight, or direct download. Includes CI/CD automation for GitHub Actions and Xcode Cloud. Use when preparing a macOS app for release, debugging signing errors, setting up notarization pipelines, or troubleshooting Gatekeeper rejections.

- Author: eovidiu
- Repository: eovidiu/agents-skills
- Version: 20260204225927
- Stars: 2
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/eovidiu/agents-skills
- Web: https://mule.run/skillshub/@@eovidiu/agents-skills~macos-cicd-distributor:20260204225927

---

---
name: macos-cicd-distributor
description: macOS app signing, notarization, and distribution expert. Guides developers through code signing with Developer ID, hardened runtime, notarization with notarytool, packaging as DMG/PKG/ZIP, and distribution via App Store, TestFlight, or direct download. Includes CI/CD automation for GitHub Actions and Xcode Cloud. Use when preparing a macOS app for release, debugging signing errors, setting up notarization pipelines, or troubleshooting Gatekeeper rejections.
---

# macOS Signing, Notarization & Distribution

## Overview

Code signing, notarization, and distribution are the most error-prone part of shipping macOS apps. This skill provides battle-tested workflows, scripts, and templates that eliminate guesswork and prevent the common pitfalls that waste hours of developer time.

Use this skill when preparing a macOS app for release, debugging signing or Gatekeeper errors, setting up CI/CD pipelines, or choosing distribution strategies.

## Core Workflow

Every macOS app distribution follows this pipeline:

```
Build → Sign → Package → Notarize → Staple → Distribute
```

Each step has specific tools, requirements, and failure modes. This skill covers all of them.

## Decision Trees

### Which Distribution Channel?

```
Is this for the Mac App Store?
├─ YES → Apple Distribution cert + App Sandbox + Xcode Upload/Transporter
│        Reference: references/distribution-channels.md
└─ NO ↓

Is this for beta testers?
├─ YES → TestFlight for Mac (still requires notarization)
│        Reference: references/distribution-channels.md
└─ NO ↓

Is this for enterprise/internal use?
├─ YES → Developer ID + PKG + deploy via MDM (JAMF/Munki)
│        Reference: references/distribution-channels.md
└─ NO ↓

Direct download from website or GitHub?
└─ YES → Developer ID + DMG or ZIP + notarize + staple
         Reference: references/packaging.md
```

### Which Package Format?

```
Does the app need install scripts, LaunchDaemons, or system components?
├─ YES → PKG installer (pkgbuild + productbuild)
│        Reference: references/packaging.md
└─ NO ↓

Is this a consumer app (drag-to-Applications)?
├─ YES → DMG (hdiutil)
│        Reference: references/packaging.md
└─ NO ↓

GitHub Releases or automated web download?
├─ YES → ZIP (ditto, NEVER /usr/bin/zip)
│        Staple the .app BEFORE zipping
└─ NO → DMG
```

### What Certificate Do I Need?

| Distribution | Certificate | Sandbox Required? |
|---|---|---|
| Mac App Store | Apple Distribution | Yes |
| Direct download | Developer ID Application | No (hardened runtime required) |
| PKG installer | Developer ID Installer | No |
| Development/testing | Apple Development | No |

## End-to-End Workflows

### Developer ID (Direct Distribution)

The most common workflow for apps distributed outside the App Store:

```bash
# 0. Verify signing identity exists
security find-identity -v -p codesigning

# 1. Build archive
xcodebuild -scheme "MyApp" -configuration Release \
  -archivePath build/MyApp.xcarchive archive

# 2. Export with Developer ID signing
xcodebuild -exportArchive \
  -archivePath build/MyApp.xcarchive \
  -exportPath build/export \
  -exportOptionsPlist ExportOptions-DeveloperID.plist

# 3. Verify signature
codesign --verify --verbose=4 build/export/MyApp.app
codesign --display --entitlements :- build/export/MyApp.app

# 4. Create DMG
hdiutil create -volname "MyApp" \
  -srcfolder build/export/MyApp.app \
  -ov -format UDZO build/MyApp.dmg

# 5. Notarize (blocks until complete, typically 5-15 min)
xcrun notarytool submit build/MyApp.dmg \
  --keychain-profile "notary-profile" --wait

# 6. Staple the notarization ticket
xcrun stapler staple build/MyApp.dmg

# 7. Final verification
xcrun stapler validate build/MyApp.dmg
spctl -a -vvv -t install build/MyApp.dmg
```

**Template**: `assets/templates/ExportOptions-DeveloperID.plist`
**Script**: `scripts/sign-and-notarize.sh` (automated version)

### Mac App Store

```bash
# 1. Archive
xcodebuild -scheme "MyApp" -configuration Release \
  -archivePath build/MyApp.xcarchive archive

# 2. Export for App Store
xcodebuild -exportArchive \
  -archivePath build/MyApp.xcarchive \
  -exportPath build/export \
  -exportOptionsPlist ExportOptions-AppStore.plist

# 3. Upload via Transporter CLI or Xcode
xcrun altool --upload-app -f build/export/MyApp.pkg \
  -t macos --apiKey KEY_ID --apiIssuer ISSUER_ID

# Or use Xcode: Organizer → Distribute App → App Store Connect
```

**Template**: `assets/templates/ExportOptions-AppStore.plist`
**Template**: `assets/templates/Entitlements-Sandbox.entitlements`

## Quick Start

### First-Time Setup

1. **Get certificates** from Apple Developer Portal
2. **Store notarization credentials**:
   ```bash
   xcrun notarytool store-credentials "notary-profile" \
     --apple-id "you@example.com" \
     --team-id "TEAMID" \
     --password "xxxx-xxxx-xxxx-xxxx"
   ```
3. **Copy templates** into your project:
   - `assets/templates/ExportOptions-DeveloperID.plist`
   - `assets/templates/Entitlements-HardenedRuntime.entitlements`
4. **Use the automation script**:
   ```bash
   bash scripts/sign-and-notarize.sh build/export/MyApp.app
   ```

### CI/CD Setup

1. **Export your .p12 certificate** and encode as base64
2. **Create App Store Connect API key** (preferred over Apple ID in CI)
3. **Copy the GitHub Actions template**:
   - `assets/templates/github-actions-release.yml`
4. **Set up CI keychain**:
   ```bash
   bash scripts/setup-keychain-ci.sh
   ```

**Reference**: `references/ci-cd-automation.md`

## When to Use This Skill

Trigger this skill when:
- Preparing a macOS app for first release
- Setting up code signing certificates
- Debugging "damaged app" or Gatekeeper errors
- Creating or fixing notarization pipelines
- Choosing between DMG, PKG, or ZIP
- Setting up GitHub Actions / Xcode Cloud for macOS
- Migrating from `altool` to `notarytool`
- Troubleshooting CI signing identity issues
- Preparing for Mac App Store submission
- Adding hardened runtime or entitlements
- Understanding macOS Sequoia security changes

## Quick Reference: Verification Commands

| What | Command |
|---|---|
| List signing identities | `security find-identity -v -p codesigning` |
| Verify app signature | `codesign --verify --verbose=4 MyApp.app` |
| Show entitlements | `codesign --display --entitlements :- MyApp.app` |
| Gatekeeper check (app) | `spctl -a -t exec -vv MyApp.app` |
| Gatekeeper check (pkg) | `spctl -a -vvv -t install MyInstaller.pkg` |
| Verify PKG signature | `pkgutil --check-signature MyInstaller.pkg` |
| Validate staple | `xcrun stapler validate MyApp.dmg` |
| Check quarantine attr | `xattr -l MyApp.app \| grep quarantine` |
| Remove quarantine | `xattr -cr MyApp.app` |
| Validate plist | `plutil -lint MyApp.entitlements` |
| Notarization log | `xcrun notarytool log <id> --keychain-profile "profile"` |
| Notarization history | `xcrun notarytool history --keychain-profile "profile"` |

## Resources

### references/
Comprehensive documentation loaded as needed:

- `code-signing.md` - Certificates, codesign flags, deep signing, hardened runtime, entitlements
- `notarization.md` - notarytool workflow, auth methods, rejection debugging, stapling
- `packaging.md` - DMG, PKG, ZIP creation and when to use each
- `distribution-channels.md` - App Store, Developer ID, TestFlight, enterprise
- `troubleshooting.md` - Common errors, Gatekeeper, Sequoia changes
- `ci-cd-automation.md` - GitHub Actions, Xcode Cloud, Fastlane, CI keychain

### scripts/
Ready-to-use automation:

- `sign-and-notarize.sh` - End-to-end: sign → DMG → notarize → staple
- `verify-distribution.sh` - Run all verification checks with pass/fail report
- `setup-keychain-ci.sh` - CI keychain creation, cert import, partition list

### assets/templates/
Copy-paste templates:

- `ExportOptions-DeveloperID.plist` - xcodebuild export for Developer ID
- `ExportOptions-AppStore.plist` - xcodebuild export for App Store
- `Entitlements-HardenedRuntime.entitlements` - Minimal hardened runtime
- `Entitlements-Sandbox.entitlements` - App Sandbox for App Store
- `Distribution.xml` - productbuild distribution descriptor
- `github-actions-release.yml` - Complete signing + notarization CI pipeline

## Summary

**Shipping macOS apps requires getting every step right.** A single misstep in signing, entitlements, or packaging produces cryptic errors that are hard to diagnose.

This skill eliminates guesswork:
- **Decision trees** tell you which path to take
- **Scripts** automate the error-prone steps
- **Templates** give you correct starting points
- **Troubleshooting** guides diagnose what went wrong

**Build it. Sign it. Ship it.**