Fix: Unsigned macOS .pkg Blocked by Gatekeeper Using productbuild

Fix: Unsigned macOS .pkg Blocked by Gatekeeper Using productbuild

Written by

in

Quick answer: To distribute a macOS .pkg installer outside the Mac App Store without triggering Gatekeeper errors, build component packages with pkgbuild, assemble them into a product archive with productbuild --distribution, and sign the final .pkg using a Developer ID Installer certificate before notarizing it.

Why this happens

When distributing a macOS application outside the Mac App Store as an installer package (.pkg), Gatekeeper inspects both the installer archive itself and the app bundle inside it. Legacy GUI packaging tools like Apple’s retired PackageMaker no longer exist in modern toolchains, and raw component packages or installers signed with the wrong certificate type (Developer ID Application instead of Developer ID Installer) will fail Gatekeeper verification.

Apple splits modern command-line packaging into three distinct tools shipped with macOS:

  • pkgbuild creates individual component packages containing an app payload and installation scripts.
  • productbuild wraps one or more component packages together with a Distribution.xml file (which controls welcome screens, licenses, and target requirements) into a final product archive.
  • productsign (or the --sign flag on productbuild) signs the installer archive using a Developer ID Installer certificate.

Note that these steps apply strictly to direct distribution outside the Mac App Store. Mac App Store .pkg files use 3rd Party Mac Developer Installer (or Apple Distribution) certificates and different productbuild rules.

How to fix it

1. Build and sign a product archive with pkgbuild and productbuild

First, make sure your .app bundle is already signed with your Developer ID Application certificate and has the Hardened Runtime enabled. Then, package and sign the .pkg using a Developer ID Installer certificate installed in your Keychain.

Step 1: Stage your payload and generate a component plist

Avoid passing --root MyApp.app directly without a staging folder, or pkgbuild may place the contents of your app bundle directly at the root directory instead of keeping the .app folder intact. Create a clean staging directory first:

mkdir -p build/payload/Applications
cp -R "path/to/MyApp.app" build/payload/Applications/

Analyze the staged root to generate a component property list:

pkgbuild --analyze --root build/payload Component.plist

Open Component.plist and check BundleIsRelocatable. By default, pkgbuild sets BundleIsRelocatable to true, meaning the macOS Installer will overwrite an existing copy of your app anywhere on the user’s disk (such as a copy sitting in ~/Downloads) instead of installing into /Applications. Set BundleIsRelocatable to <false/> in Component.plist if you always want the app installed to /Applications.

Step 2: Build the component package

Run pkgbuild using your staging root, component plist, bundle identifier, and version:

pkgbuild \
  --root build/payload \
  --component-plist Component.plist \
  --identifier "com.example.MyApp.pkg" \
  --version "1.0.0" \
  --install-location "/" \
  MyApp-Component.pkg

If you need preinstall or postinstall shell scripts, place executable scripts with those exact filenames (no .sh extension) inside a folder and pass --scripts ./Scripts.

Step 3: Synthesize and customize Distribution.xml

Generate a baseline distribution definition from your component package(s):

productbuild --synthesize \
  --package MyApp-Component.pkg \
  Distribution.xml

If your project builds multiple targets—such as a main app and a helper app—pass multiple --package flags (--package Main.pkg --package Helper.pkg) to include both in the same Distribution.xml. You can edit Distribution.xml to add <title>, <welcome>, <license>, or <background> elements pointing to files in a resources directory.

Step 4: Build and sign the final .pkg

Combine the distribution file, resources, and component packages, signing directly with your Developer ID Installer identity:

productbuild \
  --distribution Distribution.xml \
  --package-path . \
  --resources ./Resources \
  --sign "Developer ID Installer: Your Name (TEAMID1234)" \
  MyApp-Installer.pkg

If you have an unsigned .pkg that was already generated earlier in a build pipeline, you can sign it separately with productsign:

productsign \
  --sign "Developer ID Installer: Your Name (TEAMID1234)" \
  Unsigned-Installer.pkg \
  MyApp-Installer.pkg

Verify the signature before distributing:

pkgutil --check-signature MyApp-Installer.pkg

Step 5: Notarize and staple the installer

On modern macOS releases, a Developer ID signature alone is not enough—Gatekeeper also requires notarization. Submit the signed .pkg with notarytool and staple the ticket:

xcrun notarytool submit MyApp-Installer.pkg \
  --keychain-profile "AC_PASSWORD" \
  --wait

xcrun stapler staple MyApp-Installer.pkg

2. Automate packaging in an Xcode Archive script or CI step

If you want to build the .pkg automatically from Xcode build settings during an Archive/Install build, add a dedicated Package directory to your repository containing Distribution.xml, Component.plist, Resources, and Scripts.

In a post-archive script or Run Script build phase configured with Run script: For install builds only, read CFBundleShortVersionString or CFBundleVersion from the built app and invoke pkgbuild and productbuild:

set -euo pipefail

APP_PATH="${BUILT_PRODUCTS_DIR}/${FULL_PRODUCT_NAME}"
VERSION=$(/usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" "${APP_PATH}/Contents/Info.plist")
SAFE_NAME=$(echo "${PRODUCT_NAME}" | tr ' ' '_')
STAGE_DIR="${TEMP_DIR}/pkg_stage"

rm -rf "${STAGE_DIR}"
mkdir -p "${STAGE_DIR}/Applications"
ditto "${APP_PATH}" "${STAGE_DIR}/Applications/${FULL_PRODUCT_NAME}"

pkgbuild \
  --root "${STAGE_DIR}" \
  --component-plist "${SRCROOT}/Package/Component.plist" \
  --scripts "${SRCROOT}/Package/Scripts" \
  --identifier "com.example.pkg.${SAFE_NAME}" \
  --version "${VERSION}" \
  --install-location "/" \
  "${TEMP_DIR}/${SAFE_NAME}-Component.pkg"

productbuild \
  --distribution "${SRCROOT}/Package/Distribution.xml" \
  --package-path "${TEMP_DIR}" \
  --resources "${SRCROOT}/Package/Resources" \
  --sign "Developer ID Installer: Your Name (TEAMID1234)" \
  "${BUILT_PRODUCTS_DIR}/${SAFE_NAME}-${VERSION}.pkg"

Using ditto instead of cp -R preserves extended attributes, symlinks inside frameworks, and code signatures inside the .app bundle.

3. Inspect existing .pkg archives with pkgutil

If your installer behaves unexpectedly or you want to inspect how another standard macOS installer structures its Distribution.xml and scripts, expand the flat package into a folder using pkgutil:

pkgutil --expand MyApp-Installer.pkg ExpandedPackage

Note that modifying files inside an expanded package and running pkgutil --flatten invalidates any existing cryptographic signature. Always re-sign with productsign after flattening.

4. Alternative: Use the third-party “Packages” GUI/CLI tool

If maintaining hand-written Distribution.xml files, localization folders, and component plists becomes tedious, many macOS developers use Packages by Stéphane Sudre. It provides a native macOS GUI for configuring payloads, installation scripts, requirements, and custom installer steps, while also installing a packagesbuild command-line tool that fits directly into Xcode build phases and CI scripts. Even when building with packagesbuild, sign the resulting .pkg with productsign and notarize it with notarytool.

How to prevent it

  • Keep certificate types straight: Sign .app bundles, binaries, and frameworks with Developer ID Application, and sign .pkg archives exclusively with Developer ID Installer.
  • Disable bundle relocation unless needed: Always verify BundleIsRelocatable is false in Component.plist so macOS Installer does not silently update an old copy of your app in ~/Downloads or a build folder.
  • Preserve symlinks when staging: Use ditto rather than plain cp when copying .app bundles into your staging directory so framework symlinks remain valid.
  • Notarize the outer container: When distributing a .pkg, notarize and staple the signed .pkg itself—not just the .app inside it.

FAQ

Do I need a .pkg if my macOS app doesn’t need root scripts or system extensions?

Usually no. If your app is a self-contained .app bundle that goes straight into /Applications, a signed and notarized .dmg or .zip is simpler to maintain. Use a .pkg when you need preinstall/postinstall scripts, LaunchDaemons, audio plug-ins, or multi-location payloads.

Why does productsign fail with could not find appropriate signing identity?

You likely only have a Developer ID Application certificate in your Keychain. Open Xcode’s Settings > Accounts > Manage Certificates (or the Apple Developer portal) and create a Developer ID Installer certificate—only the Account Holder role on an Apple Developer Team can generate Developer ID certificates.

Can I submit a Developer ID signed .pkg to the Mac App Store?

No. App Store Connect rejects packages signed with Developer ID Installer. Mac App Store packages must be signed with Apple Distribution or 3rd Party Mac Developer Installer and built without custom Distribution.xml install scripts.

Sources & credits

Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.