Overview of Using AutoPkg

Once you have setup 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:

• 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.
• In Terminal, use the command autopkg search with your desired search term.**
• 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.

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

** Note that this kind of search does not work reliably unless you add a GitHub token to your AutoPkg Preferences (e.g., defaults write com.github.autopkg GITHUB_TOKEN GitHubTokenValue). A future version of AutoPkg (likely 3.0) will first search internally amongst the recipe repos you have downloaded to partially avoid this issue.

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 (though 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 will simply specify the name of the recipe you want to override (e.g., autopkg make-override FirefoxSignedPkg.pkg), which will create a recipe with the same name in your RecipeOverrides folder. If you add the -p or --pull option, it will attempt 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, you 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 will search RecipeOverrides first before looking in the RecipeRepos, so just using the recipe name will generally have 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 will no longer match that of the recipe, so AutoPkg will not 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 will provide 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). Then this version of the recipe will run without issue.