Skip to content

Recipe Overrides

Jump to bottom Edit New page
Elliot Jordan edited this page Sep 21, 2025 · 20 revisions

Overrides are how you configure certain exposed "Input variables" for a recipe, where you can customize the configuration for your environment. This allows for a recipe to be later updated by its maintainer(s) without overwriting your own local configuration changes. You can think of them somewhat like the ".local" config file pattern found throughout UNIX programs that are configured via text files, where you inherit a default configuration but can override specifics.

For example, if the recipe is Firefox, perhaps you want to fetch a different language version. If the recipe is designed for use with Munki, you will likely want to specify a specific location in your repo's file hierarchy, or modify certain pkginfo keys.

Another important role for recipe overrides is storing recipe parent trust information. As of AutoPkg 1.0, it is expected that you will create overrides for every recipe you run in production so that you can audit changes in parent recipes and non-core processors.

Getting info

Run autopkg info recipe to print out some useful info about the recipe:

Description:         Downloads Firefox disk image and imports into Munki.
                     Values for FIREFOX_BUILD correspond to directories here: http://download-origin.cdn.mozilla.net/pub/mozilla.org/firefox/releases/
                     Some useful values are: 'latest', 'latest-10.0esr', 'latest-esr', 'latest-3.6', 'latest-beta'
                     LOCALE corresponds to directories at http://download-origin.cdn.mozilla.net/pub/mozilla.org/firefox/releases/$FIREFOX_BUILD/mac/
                     Examples include 'en-US', 'de', 'ja-JP-mac', 'sv-SE', and 'zh-TW'
                     No idea if all Firefox builds are available in all the same localizations, so you may need to verify that any particular
                     combination is offered.
Identifier:          com.github.autopkg.munki.firefox-rc-en_US
Munki import recipe: True
Has check phase:     True
Builds package:      False
Recipe file path:    /Users/cadmin/Library/AutoPkg/RecipeRepos/com.github.autopkg.recipes/Mozilla/Firefox.munki.recipe
Parent recipe(s):    /Users/cadmin/Library/AutoPkg/RecipeRepos/com.github.autopkg.recipes/Mozilla/Firefox.download.recipe
Input values:

    LOCALE = "en_US";
    "MUNKI_REPO_SUBDIR" = "apps/firefox";
    NAME = Firefox;
    RELEASE = latest;
    pkginfo =     {
        catalogs =         (
            testing
        );
        description = "Mozilla Firefox is a free and open source web browser.";
        "display_name" = "Mozilla Firefox";
        name = "%NAME%";
        "unattended_install" = 1;
    };

Override file

Most of the time you will want to store your local changes in a file so that you only need to specify the recipe name when you want to run it, and it will automatically use your set of defined Input variables.

Making an override

Use the make-override verb to generate a template override file (plist format by default), which will be saved to the currently-configured override search location:

autopkg make-override Firefox.munki
Override file saved to /Users/cadmin/Library/AutoPkg/RecipeOverrides/Firefox.munki.recipe.

Let's examine its contents:

<?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>Identifier</key>
    <string>local.munki.Firefox</string>
    <key>Input</key>
    <dict>
        <key>DISABLE_CODE_SIGNATURE_VERIFICATION</key>
        <false/>
        <key>LOCALE</key>
        <string>en-US</string>
        <key>MUNKI_REPO_SUBDIR</key>
        <string>apps/firefox</string>
        <key>NAME</key>
        <string>Firefox</string>
        <key>RELEASE</key>
        <string>latest</string>
        <key>pkginfo</key>
        <dict>
            <key>catalogs</key>
            <array>
                <string>testing</string>
            </array>
            <key>description</key>
            <string>Mozilla Firefox is a free and open source web browser.</string>
            <key>display_name</key>
            <string>Mozilla Firefox</string>
            <key>name</key>
            <string>%NAME%</string>
            <key>unattended_install</key>
            <true/>
        </dict>
    </dict>
    <key>ParentRecipe</key>
    <string>com.github.autopkg.munki.firefox-rc-en_US</string>
    <key>ParentRecipeTrustInfo</key>
    <dict>
        <key>non_core_processors</key>
        <dict>
            <key>MozillaURLProvider</key>
            <dict>
                <key>git_hash</key>
                <string>92758e3756ac9f090e69531b0821ebf1842c899c</string>
                <key>path</key>
                <string>~/Library/AutoPkg/RecipeRepos/com.github.autopkg.recipes/Mozilla/MozillaURLProvider.py</string>
                <key>sha256_hash</key>
                <string>9f9ae9a7416e59067ba92dde475b925595daa9ac436e82467e1b97bacbb6856b</string>
            </dict>
        </dict>
        <key>parent_recipes</key>
        <dict>
            <key>com.github.autopkg.download.firefox-rc-en_US</key>
            <dict>
                <key>git_hash</key>
                <string>10541f07e781358fc489c1ed615de9ce85ee95a5</string>
                <key>path</key>
                <string>~/Library/AutoPkg/RecipeRepos/com.github.autopkg.recipes/Mozilla/Firefox.download.recipe</string>
                <key>sha256_hash</key>
                <string>25f3d12e7586fb4970fb469b45a2b37f4aa0bc4a549ea93f082c77f1b4439d60</string>
            </dict>
            <key>com.github.autopkg.munki.firefox-rc-en_US</key>
            <dict>
                <key>git_hash</key>
                <string>10541f07e781358fc489c1ed615de9ce85ee95a5</string>
                <key>path</key>
                <string>~/Library/AutoPkg/RecipeRepos/com.github.autopkg.recipes/Mozilla/Firefox.munki.recipe</string>
                <key>sha256_hash</key>
                <string>59a32356ec309af8e562c5062f379adb95fb97e2a64c681f341521a7846c63d9</string>
            </dict>
        </dict>
    </dict>
</dict>
</plist>

Input keys and merging

The Input key is a complete copy of that of the source recipe's, which you may modify to suit your needs. When a recipe is run, each key in the override's Input dict will be merged on top of the recipe's (hence the name "override").

You may also wish to remove the override's Input keys altogether, and instead let AutoPkg use the values that are defined in the original recipe. For example, for recipes with a stable, known download URL, this URL may be present as an Input variable so that it is easily customizable. All URLs will eventually break and need to be fixed, however, and you may wish to leave it out of your override file entirely if you expect it to be fixed quickly by the recipe maintainer. In other words, if you wish, you may reduce your override's Input items to include only the items you wish to change from the defaults set by the recipe.

The ParentRecipe key points AutoPkg to the identifier of the recipe for which this is an override. In fact, an override is no different from a child recipe in its structure and its logic as to how its contents inherit and override its parent's.

Testing the override

To test the override, open the new override file that was saved to Library/AutoPkg/RecipeOverrides/Firefox.munki.recipe with a text editor, and change something. For example, we can change RELEASE to latest-esr. Save the changes. Now run autopkg info Firefox.munki again and look at what's changed (we're cutting out some redundant parts in this sample output below):

---
Identifier:          local.munki.Firefox
Munki import recipe: True
Has check phase:     True
Builds package:      False
Recipe file path:    /Users/cadmin/Library/AutoPkg/RecipeOverrides/Firefox.munki.recipe
Parent recipe(s):    /Users/cadmin/Library/AutoPkg/RecipeRepos/com.github.autopkg.recipes/Mozilla/Firefox.munki.recipe
                     /Users/cadmin/Library/AutoPkg/RecipeRepos/com.github.autopkg.recipes/Mozilla/Firefox.download.recipe
Input values:

    LOCALE = "en_US";
    "MUNKI_REPO_SUBDIR" = "apps/firefox";
    NAME = Firefox;
    RELEASE = "latest-esr";
---

Verify first that RELEASE is set to our overridden value.

More interestingly, notice that the Recipe file path has changed from its source recipe file in RecipeRepos to the path of our override. This is because an override is actually a child recipe, in exactly the same way that Firefox.munki is a child recipe of the Firefox.download recipe.

Command-line: the -k/--key option

A second way to override any input variable is at the command line using the --key option:

autopkg run \
  --key MUNKI_REPO_SUBDIR=some/custom/location \
  --key RELEASE=latest-esr \
  Firefox.munki

Any overrides given at the command line will always take precedence over those present in an override file. You might use this to re-run a recipe but retrieve an alternate beta release, specify a different MUNKI_REPO value for testing a recipe, etc.

Note that this option only reliably works for <string> input variables, as --key can only set strings. While AutoPkg may successfully convert a string to other variable types, it could require a very specific syntax to do so (e.g., FAIL_RECIPES_WITHOUT_TRUST_INFO).

Recipe override directories

Recipe overrides are saved to the recipe override directory.

  1. The default recipe override directory is ~/Library/AutoPkg/RecipeOverrides
  2. You may set the RECIPE_OVERRIDE_DIRS preference to an array of directories instead. All directories defined here will be searched when running recipes, but new overrides will be saved only to the first directory in the list.
  3. You may also specify an alternate recipe override directory using the --override-dir option to autopkg

Suggestions for Managing Munki Override Recipes with Non-Universal (arm64 and x-86_64) Architectures

Apps which are not compiled to be Universal (working on both Apple Silicon and Intel Macs) will need multiple overrides (typically one per architecture). The following should be considered when creating an override for a Non-Universal app:

  • The resulting pkginfo file will need to contain the supported_architectures array indicating which architecture types this recipe supports.
    • The name value in the munki pkginfo should be the same for both architectures. Munki will handle which pkginfo to use based on the supported_architectures array. This way, you will only need to add one name to your manifests.
  • The URL for the download recipe will need to be different for each architecture. Check the download.recipe to see if the author has provided helpful hints and a default in the munki.recipe.
    • Some vendors may us arm64 and x86_64 in their download URLs and some may not. Be aware that you may need to change one override key or multiple depending on how the URLs and recipes are constructed.
  • Changing the identifier for each override file will allow AutoPkg to properly cache downloads.
    • E.g. local.munki.AppName.arm64 and local.munki.AppName.x86_64
  • You may want to make the MUNKI_REPO_SUBDIR different for each override.

Below is an example of an arm64 override. To make this work as an x86_64 override, we would want to change:

  • The Identifier key value
  • The ARCH key value
  • The MUNKI_REPO_SUBDIR key value
  • The url key value
<?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>Identifier</key>
    <string>local.munki.Figma-arm64</string>
    <key>Input</key>
    <dict>
        <key>ARCH</key>
        <string>arm64</string>
        <key>MUNKI_REPO_SUBDIR</key>
        <string>Figma/Figma-arm64</string>
        <key>NAME</key>
        <string>Figma</string>
        <key>pkginfo</key>
        <dict>
            <key>catalogs</key>
            <array>
                <string>testing</string>
            </array>
            <key>category</key>
            <string>Productivity</string>
            <key>description</key>
            <string>Design, prototype, and gather feedback all in one place with Figma.</string>
            <key>developer</key>
            <string>Figma</string>
            <key>display_name</key>
            <string>Figma</string>
            <key>name</key>
            <string>%NAME%</string>
            <key>supported_architectures</key>
            <array>
                <string>%ARCH%</string>
            </array>
            <key>unattended_install</key>
            <true/>
        </dict>
        <key>url</key>
        <string>https://desktop.figma.com/mac-arm/Figma.zip</string>
    </dict>
    <key>ParentRecipe</key>
    <string>com.github.dataJAR-recipes.munki.Figma</string>
    <key>ParentRecipeTrustInfo</key>
    <dict>
        <key>non_core_processors</key>
        <dict/>
        <key>parent_recipes</key>
        <dict>
            <key>com.github.dataJAR-recipes.download.Figma</key>
            <dict>
                <key>git_hash</key>
                <string>f4813d7e69e7bfb064d7a8d1c85c9c2c9290f264</string>
                <key>path</key>
                <string>~/Library/AutoPkg/RecipeRepos/com.github.autopkg.dataJAR-recipes/Figma/Figma.download.recipe</string>
                <key>sha256_hash</key>
                <string>1dc83f36648a1437a3f06bf52222733d07fd8b2b8679c2f9f4f1b331a04f1393</string>
            </dict>
            <key>com.github.dataJAR-recipes.munki.Figma</key>
            <dict>
                <key>git_hash</key>
                <string>7f2d853e594ffa778011b5f71e561f0ad9cc43bd</string>
                <key>path</key>
                <string>~/Library/AutoPkg/RecipeRepos/com.github.autopkg.dataJAR-recipes/Figma/Figma.munki.recipe</string>
                <key>sha256_hash</key>
                <string>5d3c5b99df1c1d34f4e155332ae9121c2c8d8ec98bcf7b9fda4090a730808032</string>
            </dict>
        </dict>
    </dict>
</dict>
</plist>
Add a custom footer

Table of Contents

AutoPkg Reference

Development

Legacy Documentation

Clone this wiki locally