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?

End-to-End Workflows

Developer ID (Direct Distribution)

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

# 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

# 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 "[email protected]" \ --team-id "TEAMID" \ --password "xxxx-xxxx-xxxx-xxxx"
3. Copy templates into your project:
4. assets/templates/ExportOptions-DeveloperID.plist
5. assets/templates/Entitlements-HardenedRuntime.entitlements
6. 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:
4. assets/templates/github-actions-release.yml
5. 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

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.