Overview of Using AutoPkg - autopkg/autopkg GitHub Wiki

Once you have set up AutoPkg (see Getting Started for installation and configuration details), you will want to use it to download and/or package and/or add to your management system software titles. For each title, your workflow will, most commonly, consist of the following steps:

  1. Search for recipe(s)
  2. Add recipe repo(s)
  3. Create override(s)
  4. Run the override(s)
  5. Maintain your override(s) for future runs

Search for recipe(s)

You can search for recipes in one of these ways:

  • In Terminal, use the command autopkg search with your desired search term.
  • Use autopkgweb.com.
  • Use the Search bar on this page, which will offer to search this repo or search the org; you want to search the org (org:autopkg).
  • Go to the following URL, substituting your search term for SearchTerm (spaces should be escaped as %20): https://github.com/search? type=code&q=org%3Aautopkg+SearchTerm.
  • If using AutoPkgr (a GUI front end to AutoPkg, developed independently from this project), you can search GitHub using the "Search for a recipe on GitHub" field. If you use the Filter Recipes search field, it will only search the repos you have already downloaded.

For a deeper dive, see Finding Recipes.

If you cannot find a recipe that suits your needs, you may write your own.

Add recipe repo(s)

In order to run your recipes, AutoPkg needs a local copy of the repository (repo) that contains the recipes used. Since recipes can reference other recipes (through a parent-child relationship), the recipe you wish to use may require more than one repo.

The most common way to add a repo is using the repo-add verb (e.g., autopkg repo-add recipes adds the core recipes repo). You may also add all necessary recipes when creating your override (see the next step). If you run a recipe and it states that a recipe is not found, pay attention to the error message to determine which repo you need to add.

Create override(s)

While it is possible to run a recipe without creating an override, there are security and customization benefits to running an override. It is assumed that all recipes you are running in production will be overrides.

To create an override, go to the Terminal and use the autopkg make-override command. In most cases, you simply specify the name of the recipe you want to override (e.g., autopkg make-override FirefoxSignedPkg.pkg), which creates a recipe with the same name in your RecipeOverrides folder. If you add the -p or --pull option, AutoPkg attempts to pull the parent repos if they can't be found locally (as defined by your search paths); you may need a GitHub token for the --pull option to work reliably. Other useful options can be discovered using autopkg make-override --help.

If you wish to customize one or more of the Input Variables in the recipe, you do this by editing those values in the recipe override. A common case currently is deciding which architecture you wish to download (Apple Silicon or Intel) if no Universal download is available and the recipe supports choosing an architecture.

Run the override(s)

To run a recipe, use the autopkg run command. You commonly use the name of the recipe override you just created (e.g., autopkg run FirefoxSignedPkg.pkg), although other options like identifier or path are possible. (AutoPkg searches RecipeOverrides first before looking in the RecipeRepos, so the recipe name alone generally has the desired outcome.)

Maintain your override(s) for future runs

When you created the recipe override, trust information was included, consisting of information about the recipes and non-core processors used. When a recipe changes (e.g., the author changes the recipe and you update the repo using autopkg repo-update), the trust information stored in the override no longer matches the recipe, so AutoPkg refuses to run the updated recipe because it is no longer trusted.

Trust information is designed to let you know when things should be audited. If you get a trust error, you can audit the changes using the verb verify-trust-info (e.g., autopkg verify-trust-info -vv FirefoxSignedPkg.pkg); the -vv option provides a diff between the version you last trusted and the current version.

Once you trust the changes, you can update your override using the update-trust-info verb (e.g., autopkg update-trust-info FirefoxSignedPkg.pkg). After that, this version of the recipe runs without issue.