/macos-distribution-workflow

name: macos-distribution-workflow
description: Inspect, prepare, validate, and troubleshoot exported macOS distribution artifacts. Use when checking signing identities, entitlements, hardened runtime, nested code, Gatekeeper, notarization readiness/results, stapling, or distribution-only launch failures.

macOS Distribution Workflow

Purpose

Treat a signed exported artifact as the source of truth for macOS distribution diagnosis. This workflow distinguishes project/account provisioning from artifact trust: inspect the bundle, classify the failure, and use the minimum verifiable repair or release-validation path.

When To Use

• Use for `.app`, `.pkg`, or disk-image distribution artifacts; signing state; entitlements; hardened runtime; nested signatures; Gatekeeper; notarization; stapling; and direct-distribution failures.
• Do not use for ordinary Debug builds, account-side certificate/profile creation, or project signing-setting edits without an artifact diagnosis.

Single-Path Workflow

1. Apply the Apple docs gate through `explore-apple-swift-docs`. Confirm the distribution channel and current signing/notarization requirement before acting. 2. Identify the exact artifact, distribution channel, main executable, nested frameworks/helpers/extensions, signing identity, and observed user-visible failure. 3. Read `references/artifact-inspection-and-classification.md` and inspect bundle structure, signature details, entitlements, nested code, and Gatekeeper assessment before prescribing a fix. 4. Classify the problem: unsigned/ad hoc signing, wrong identity, entitlement mismatch, hardened-runtime issue, nested-code ordering issue, sandbox issue, Gatekeeper assessment, or notarization/stapling readiness. 5. Keep account-side provisioning with `apple-developer-provisioning-workflow`; keep project signing or entitlement edits with `xcode-build-run-workflow`. Do not hand-edit/re-sign a built artifact as a first response to a project configuration problem. 6. For direct distribution, validate the outermost deliverable, notarization result, and stapling state appropriate to the chosen package shape. Keep local-debug validity distinct from distribution readiness. 7. Report the inspected artifact, evidence, failure class, smallest repair path, and the validation that remains after repair.

Inputs

• exported artifact path and intended distribution channel
• signing identity/entitlement context and nested-code shape
• observed launch, Gatekeeper, notarization, or upload failure
• current Xcode/macOS version and any prior validation output

Outputs

• artifact inspection result and precise failure classification
• project, account, or artifact owner for the next repair
• minimum validation sequence and distribution-readiness state

Guards and Stop Conditions

• Do not call notarization necessary for a normal local Debug run.
• Do not invent entitlements, signing identities, or distribution certificates.
• Do not treat a project setting as verified until the exported artifact was inspected.
• Do not re-sign an artifact casually; re-signing can invalidate nested signatures, profiles, or a prior notarization result.
• Stop when the distribution channel, actual artifact, or signing evidence is missing.

Fallbacks and Handoffs

• Recommend `diagnose-apple-entitlements` when source, profile, main or nested signed entitlements, and runtime authorization need a five-state comparison before choosing a repair owner.
• Recommend `apple-developer-provisioning-workflow` for documented account-side certificates, profiles, and identifier/capability state.
• Recommend `xcode-build-run-workflow` for entitlement/project-signing changes, archive/export, and build validation.
• Recommend `explore-apple-swift-docs` for current signing, notarization, or distribution policy.

References

• `references/artifact-inspection-and-classification.md`
• Recommend `references/snippets/apple-xcode-project-core.md` when the app needs reusable Xcode-project policy alongside distribution work.
• [Packaging Mac software for distribution](https://developer.apple.com/documentation/xcode/packaging-mac-software-for-distribution) documents distribution packaging and notarization context.