codesign is the macOS command-line tool that signs and verifies Apple binaries. xcodebuild calls it during the archive and export steps; fastlane gym, EAS Build, and every iOS CI plugin eventually shell out to it. Knowing what it does is the difference between staring at 'Code Signing Error' for an hour and fixing the build in two minutes.
Where it lives, and which Macs have it
The binary is at /usr/bin/codesign on every Mac. You will see it written as codesign, OS X codesign, or just "code sign on Mac" depending on how old the documentation is: OS X was renamed macOS in 2016, and the tool itself has not changed name since it shipped with Mac OS X 10.5 Leopard. Anything you read about OS X codesign still applies.
It arrives with the Xcode Command Line Tools rather than with the operating system alone, so a clean Mac needs xcode-select --install before the command resolves. There is no version for Linux or Windows, which is the constraint behind building an iOS app on Windows: signing has to happen on a Mac even when everything else does not.
# Confirm the tool is present and see its version which codesign codesign --version # Install it if the command is not found xcode-select --install
Sign a build
codesign --force --sign "Apple Distribution: Acme Corp (ABCDE12345)" \ --entitlements MyApp.entitlements \ --options runtime \ --timestamp \ MyApp.app
Verify a signature
# Quick health check codesign --verify --verbose=4 MyApp.app # Show identity, timestamp, hardened runtime, and entitlements codesign -dvv --entitlements :- MyApp.app
Common errors and what they mean
- errSecInternalComponent
- The keychain refused codesign access to the private key. Run
security set-key-partition-list -S apple-tool:,apple: -k <pw> <keychain>after importing the .p12 on CI. - User interaction is not allowed
- Same keychain partition list issue as codesign wants to access key in your keychain, surfaced when the keychain is locked. Unlock it with
security unlock-keychainfirst. - no identity found
- The certificate is not in any keychain in the search list, or the keychain is locked, or you typed the identity name wrong.
- resource fork, Finder information, or similar detritus not allowed
- Some file inside the bundle has extended attributes that codesign refuses to sign over. Run
xattr -cr MyApp.appbefore signing.