| name | create-autopkg-recipes |
| description | Create AutoPkg recipes (download, pkg, munki, install, etc.) for a macOS app
from a vendor URL. Use whenever the user asks to create, generate, scaffold,
or add AutoPkg recipes for an app.
Keywords:
- AutoPkg, autopkg
- .download.recipe, .pkg.recipe, .munki.recipe, .install.recipe
- Recipe Robot, recipe-robot
- homebysix-recipes, Munki, pkg
|
| user-invocable | true |
Create AutoPkg Recipes
Scaffold recipes for a macOS app following repo conventions. E2E test download+pkg before handing off.
1. Check for duplicates
autopkg search <AppName>.download (try vendor-prefixed variants too, e.g. Google<AppName>). Any match, any repo → surface and ask before building.
2. Gather metadata
Note: download URL / appcast / GH releases, developer, description, display name. Don't fully download — HEAD only (curl -sIL); let Recipe Robot fetch. Never fabricate a domain from a relative URL — resolve against the domain actually fetched.
GitHub Pages sites (e.g. *.github.io) often return an HTML shell with content loaded via JS. For these, a full curl against the page is fine — also check the sibling GitHub repo's releases with gh (gh release list -R <owner>/<repo>) as a shortcut for version and asset info.
If it's a normal GitHub-releases / direct-URL / Sparkle app, skip straight to step 3 — don't pre-inspect.
Skip signals (ask first, don't silently build or drop): Mac App Store-only; paid-only with no public trial DMG; TestFlight/beta-only; source-only (no prebuilt binary).
3. Recipe Robot
/Applications/Recipe Robot.app/Contents/Resources/scripts/recipe-robot <input>
Accepts: direct download URL, Sparkle appcast, GitHub/BitBucket/SourceForge project URL, Dropbox link, local .app/.pkg/.dmg/archive. Rejects marketing pages and existing .recipe files — find the real download/appcast/repo URL instead.
- Config error → ask user to run
--configure.
- False "recipe exists" match →
--ignore-existing (don't use reflexively).
- Version-pinned URL (e.g.
/v1.2.3/App.dmg) → prepend URLTextSearcher against a stable page to capture the current URL.
- Modernizing an old recipe → run RR with
--ignore-existing, diff+merge into the existing recipes rather than replacing.
No RR installed → hand-author, modeling after a repo recipe with the same delivery format.
Gated/API-driven downloads (HEAD returns HTML/4xx, JS-triggered download): hand-author chained URLTextSearcher steps to extract the real URL, feed into URLDownloader via result_output_var_name: url. Examples: Ecosia/EcosiaBrowser.download.recipe, Google/Antigravity.download.recipe.
Structured APIs (tracks/locales/channels, avoids duplicated regex across recipes): custom processor <Vendor><Purpose>InfoProvider.py subclassing autopkglib.URLGetter. Example: Cocktail/CocktailReleasesInfoProvider.py. For one URL behind an API, URLTextSearcher is enough.
4. Conventions
- Directory = app name (or developer, if one already exists for them). Recipe Robot often uses the developer's display name instead of the app name — rename after RR if needed.
- Filenames: no spaces, even if
Input/NAME has one (e.g. TightStudio.pkg.recipe for app "Tight Studio").
- Identifier:
com.github.homebysix.<type>.<App>, no spaces.
- Match
MinimumVersion, Input/NAME, ParentRecipe, processor order to neighbors. MinimumVersion should be the highest required AutoPkg version across the recipe chain — pre-commit hooks will catch mismatches.
- Download recipe always has
CodeSignatureVerifier. Quote subject.OU if it starts with a digit (= "7D2YX5DQ6M") — unquoted fails at runtime despite linting fine.
- ZIP (no appcast):
URLDownloader → EndOfCheckPhase → Unarchiver → CodeSignatureVerifier → Versioner.
- ZIP (Sparkle enclosure, not DMG): also needs
Unarchiver between EndOfCheckPhase and CodeSignatureVerifier. Inspect the enclosure URL type from the appcast before assuming DMG.
- Munki
pkginfo: set both unattended_install and unattended_uninstall to true. RR only sets unattended_install — manually verify both are present. Write a factual, non-salesy one-line description (no marketing copy, no emojis, no blank placeholder) — verify against the app itself (mount DMG, check Info.plist, strings the binary) if unsure.
- Delete the app icon
.png RR drops next to the recipes — a local scratch file, not committed.
plutil -lint every file.
Multi-arch apps: RR won't add an ARCH var. Parameterize manually (%ARCH% in asset_regex/re_pattern/url), default Input/ARCH to arm64, document alternatives in Description. Don't set munki supported_architectures from %ARCH% (vendor/munki naming mismatches, blocks Rosetta unnecessarily) unless the binary genuinely can't run under Rosetta.
Recognize, don't add unless asked: StopProcessingIf after EndOfCheckPhase (marginal gain, download step already skips); pseudo-universal pkgs merging arch builds (prefer true universal build or two recipes); third-party aggregators (Homebrew/MacUpdate) as the binary/version source — go direct to vendor, each hop is a supply-chain trust cost.
5. Security — ask before proceeding
No code signature requirement, or insecure HTTP anywhere (download/appcast). Explain the risk; proceed only on explicit yes.
6. E2E test
autopkg run -vvq <App>/<App>.download.recipe <App>/<App>.pkg.recipe
Don't run install/munki — they write to /Applications, the munki repo, etc. Trust-info warnings on uncommitted recipes are expected.
7. Report
What was created, what tested clean, caveats (missing Team ID, unusual signing, dev-name mismatch, skipped tests). Don't commit or push unless asked.
