“… I have to parse text to return from the command line and there is no spec on what will be returned…”

Not having a web service API for notarization may seem like a drawback at first. Although technically there is a web service, but Apple is keeping this API private.

On the other hand, Apple provides command-line tools to integrate notarization with automated workflows. In turn, these tools talk to Apples servers using a (private) network-based API. Obviously, these tools are part of Xcode and are the foundations for integrating notarization into your build pipeline.

Generally I find easier to integrate command-line tools into build pipelines as opposed to REST APIs. Specifically, if you only have access to a web API then you would need to write your own command-line tool to talk to it. In turn you would need to again integrate that tool into your CI/CD system.

“… But parsing text returned from these tools are difficult and there is no specification on what can be returned…,” you might exclaim. That is an assumption not entirely true. Later here I will show you how to interact with these notarization tools in a way that is easily automated.

With this information at hand, you can submit for notarization regularly from your build pipeline. For the purpose of early discovery of any changes that conflicts with notarization.

Structured Output Formats

The primary notarization command—altool—provides three output format options. Two of them are meant for controlling scripts to parse. These formats are selected by the value of the ‑‑output‑format parameter.

• normal — the plain text output intended for human consumption, it is also the default output format.
• json – JavaScript Object Notation format.
• xml – XML Property List.

The following are examples of each output format. I’ll be using the list providers command to show the list of iTunes Providers that your account has.

Plain Text Output

The following command runs the ‑‑list‑providers sub-command without any output format option. In turn the output defaults to plain text.

xcrun altool --list-providers

The following is the list providers command output in plain text. Evidently I have masked out the true identifiers of my Apple Developer Account.

ProviderName              ProviderShortname       PublicID                             WWDRTeamID 
------------------------- ----------------------- ------------------------------------ ---------- 
Sasmito Adibowo|123456789 SasmitoAdibowo123456789 00000000-0000-0000-0000-000000000000 A1BC23DEFG 

JSON Output

The following command runs the ‑‑list‑providers sub-command and tell it to output the result in JSON format.

xcrun altool \
  --list-providers \
  --output-format json

The following is the JSON output for the list providers command. By comparison, this output mode has more content than the plain text output—namely information on the operating system and tool itself.

{
  "tool-version": "1.234.5678",
  "tool-path": "/Applications/Xcode.app/…",
  "success-message": "Retrieved providers info",
  "os-version": “1.2.3”,
  "providers": [
    {
      "ProviderShortname": "SasmitoAdibowo123456789",
      "PublicID": "00000000-0000-0000-0000-000000000000",
      "WWDRTeamID": "A1BC23DEFG",
      "ProviderName": "Sasmito Adibowo|123456789"
    }
  ]
}

XML Output

Finally the following command runs the ‑‑list‑providers sub-command to return output in an XML format.

xcrun altool \
  --list-providers \
  --output-format xml

The returned information is essentially the same as the JSON output.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>os-version</key>
    <string>1.2.3</string>
    <key>providers</key>
    <array>
        <dict>
            <key>ProviderName</key>
            <string>Sasmito Adibowo|123456789</string>
            <key>ProviderShortname</key>
            <string>SasmitoAdibowo123456789</string>
            <key>PublicID</key>
            <string>00000000-0000-0000-0000-000000000000</string>
            <key>WWDRTeamID</key>
            <string>A1BC23DEFG</string>
        </dict>
    </array>
    <key>success-message</key>
    <string>Retrieved providers info</string>
    <key>tool-path</key>
    <string>/Applications/Xcode.app/…</string>
    <key>tool-version</key>
    <string>1.234.5678</string>
</dict>
</plist>

Which Format to Use?

Which output format to use for automating notarization? This largely depends on support provided by the consuming scripts. Notably which format is better supported by the scripting language. Generally, when you use cross-platform continuous integration systems, using the JSON output format would be a safe bet. Conversely, tools grown on the Mac such as the Swift Package Manager would have native support for parsing XML Property Lists. Finally if you program your workflow using shell scripts, XML Property List would be the better option–thanks to command-line tools built in macOS to process this file format.

My personal favorite command-line utility for extracting information from property lists is PlistBuddy. Markedly it is not available from the default search PATH—you invoke the tool by referring to its full path name: /usr/libexec/PlistBuddy. Regardless, you can have a look at its manual page for more information; open Terminal and type this command to summon it:

man PlistBuddy

For example, the following Z shell snippet would run the list providers command and extract the first ID into a shell variable.

xcrun altool \
  --apiKey … \
  --apiIssuer … \
  --list-providers \
  --output-format xml \
  > /tmp/provider-list.plist
providerShortName=$( \
  /usr/libexec/PlistBuddy \
  -c "Print providers:0:ProviderShortname" \
  /tmp/provider-list.plist )
echo $providerShortName

Next Steps

The altool command requires an authentication. You can configure an API key or app-specific password to give the command access to your Apple Developer Program account. Undoubtedly depending on your needs and constraints.

I’ve also prepared a ready-made script to automate packaging and notarization of macOS application bundles. Indeed you can use this as a starting point of your build automation.

Check out this article to see how a standard notarization workflow looks like. You should use this as a base for designing or integrating the workflow into your own build pipeline.

What are you waiting for? Automate your mac app notarization today!

---