Metadata-Version: 2.4
Name: autopkg-wrapper
Version: 2026.4.4
Summary: A package used to execute some autopkg functions, primarily within the context of a GitHub Actions runner.
Project-URL: Repository, https://github.com/smithjw/autopkg-wrapper
Author-email: James Smith <james@smithjw.me>
License-Expression: BSD-3-Clause
License-File: LICENSE
Requires-Python: ~=3.14.0
Requires-Dist: idna
Requires-Dist: jamf-pro-sdk
Requires-Dist: pygithub
Requires-Dist: requests
Requires-Dist: ruamel-yaml
Requires-Dist: toml
Requires-Dist: urllib3>=2.5.0
Description-Content-Type: text/markdown

# autopkg-wrapper

`autopkg_wrapper` is a small package that can be used to run [`autopkg`](https://github.com/autopkg/autopkg) within CI/CD environments such as GitHub Actions.

The easiest way to run it is by installing with pip.

```shell
pip install autopkg-wrapper
```

## Development

This project uses `uv` for dependency management and `mise` tasks for common workflows.

```bash
mise run install
mise run test
mise run build
```

## Command Line Parameters

<!-- CLI-PARAMS-START -->

```shell
usage: autopkg_wrapper [-h] [--recipe-file RECIPE_FILE |
                       --recipes [RECIPES ...]]
                       [--recipe-processing-order [RECIPE_PROCESSING_ORDER ...]]
                       [--autopkg-bin AUTOPKG_BIN] [--dry-run] [--debug]
                       [--disable-recipe-trust-check] [--update-trust-only]
                       [--disable-git-commands] [--concurrency CONCURRENCY]
                       [--github-token GITHUB_TOKEN]
                       [--branch-name BRANCH_NAME] [--create-pr]
                       [--create-issues]
                       [--overrides-repo-path OVERRIDES_REPO_PATH]
                       [--post-processors [POST_PROCESSORS ...]]
                       [--autopkg-prefs AUTOPKG_PREFS] [--process-reports]
                       [--reports-zip REPORTS_ZIP]
                       [--reports-extract-dir REPORTS_EXTRACT_DIR]
                       [--reports-dir REPORTS_DIR]
                       [--reports-out-dir REPORTS_OUT_DIR]
                       [--reports-run-date REPORTS_RUN_DATE]
                       [--reports-strict]

Run autopkg recipes

options:
  -h, --help            show this help message and exit
  --recipe-file RECIPE_FILE
                        Provide the list of recipes to run via a JSON file for
                        easier management.
  --recipes [RECIPES ...]
                        Recipes to run via CLI flag or environment variable.
                        If the '--recipes' flag is used, simply provide a
                        space-separated list on the command line: `autopkg-
                        wrapper --recipes recipe_one.download
                        recipe_two.download` Alternatively, you can provide a
                        space/comma-separated list in the 'AW_RECIPES'
                        environment variable: `export
                        AW_RECIPES="recipe_one.download recipe_two.download"`
                        `export AW_RECIPES="recipe_one.pkg,recipe_two.pkg"`
                        `autopkg-wrapper`
  --recipe-processing-order [RECIPE_PROCESSING_ORDER ...]
                        This option comes in handy if you include additional
                        recipe type names in your overrides and wish them to
                        be processed in a specific order. We'll specifically
                        look for these recipe types after the first period (.)
                        in the recipe name. Order items can be either a full
                        type suffix (e.g. "upload.jamf") or a partial token
                        (e.g. "upload", "auto_update"). Partial tokens are
                        matched against the dot-separated segments after the
                        first '.' so recipes like "Foo.epz.auto_update.jamf"
                        will match "auto_update". This can also be provided
                        via the 'AW_RECIPE_PROCESSING_ORDER' environment
                        variable as a comma-separated list (e.g.
                        "upload,self_service,auto_update"). For example, if
                        you have the following recipes to be processed:
                        ExampleApp.auto_install.jamf ExampleApp.upload.jamf
                        ExampleApp.self_service.jamf And you want to ensure
                        that the .upload recipes are always processed first,
                        followed by .auto_install, and finally .self_service,
                        you would provide the following processing order:
                        `--recipe-processing-order upload.jamf
                        auto_install.jamf self_service.jamf` This would ensure
                        that all .upload recipes are processed before any
                        other recipe types. Within each recipe type, the
                        recipes will be ordered alphabetically. We assume that
                        no extensions are provided (but will strip them if
                        needed - extensions that are stripped include .recipe
                        or .recipe.yaml).
  --autopkg-bin AUTOPKG_BIN
                        Path to the autopkg binary (default:
                        /usr/local/bin/autopkg). Can also be set via
                        AW_AUTOPKG_BIN.
  --dry-run             Show planned actions without executing external
                        commands
  --debug               Enable debug logging when running script
  --disable-recipe-trust-check
                        If this option is used, recipe trust verification will
                        not be run prior to a recipe run. This does not set
                        FAIL_RECIPES_WITHOUT_TRUST_INFO to No. You will need
                        to set that outside of this application.
  --update-trust-only   Only verify and update trust information for recipes
                        without running them. Recipes that already pass trust
                        verification will be skipped. This mode automatically
                        formats updated recipe files and does not perform git
                        operations. Supports glob patterns in --recipes (e.g.,
                        "overrides/**/*.recipe.yaml").
  --disable-git-commands
                        If this option is used, git commands won't be run
  --concurrency CONCURRENCY
                        Number of recipes to run in parallel (default: 10)
  --github-token GITHUB_TOKEN
  --branch-name BRANCH_NAME
                        Branch name to be used recipe overrides have failed
                        their trust verification and need to be updated. By
                        default, this will be in the format of
                        "fix/update_trust_information/YYYY-MM-DDTHH-MM-SS"
  --create-pr           If enabled, autopkg_wrapper will open a PR for updated
                        trust information
  --create-issues       Create a GitHub issue for recipes that fail during
                        processing
  --overrides-repo-path OVERRIDES_REPO_PATH
                        The path on disk to the git repository containing the
                        autopkg overrides directory. If none is provided, we
                        will try to determine it for you.
  --post-processors [POST_PROCESSORS ...]
                        One or more autopkg post processors to run after each
                        recipe execution
  --autopkg-prefs AUTOPKG_PREFS
                        Path to the autopkg preferences you'd like to use
  --process-reports     Process autopkg report directories or zip and emit
                        markdown summaries
  --reports-zip REPORTS_ZIP
                        Path to an autopkg_report-*.zip to extract and process
  --reports-extract-dir REPORTS_EXTRACT_DIR
                        Directory to extract the zip into (default:
                        autopkg_reports_summary/reports)
  --reports-dir REPORTS_DIR
                        Directory of reports to process (if no zip provided)
  --reports-out-dir REPORTS_OUT_DIR
                        Directory to write markdown outputs (default:
                        autopkg_reports_summary/summary)
  --reports-run-date REPORTS_RUN_DATE
                        Run date string to include in the summary
  --reports-strict      Exit non-zero if any errors are detected in processed
                        reports
```

<!-- CLI-PARAMS-END -->

## Examples

Run recipes (serial):

```bash
autopkg_wrapper --recipes Foo.download Bar.download
```

Run 3 recipes concurrently and process reports afterward:

```bash
autopkg_wrapper \
  --recipe-file /path/to/recipe_list.txt \
  --concurrency 3 \
  --disable-git-commands \
  --process-reports \
  --reports-out-dir /tmp/autopkg_reports_summary \
  --reports-strict
```

Process a reports zip explicitly (no recipe run):

```bash
autopkg_wrapper \
  --process-reports \
  --reports-zip /path/to/autopkg_report-2026-02-02.zip \
  --reports-extract-dir /tmp/autopkg_reports \
  --reports-out-dir /tmp/autopkg_reports_summary
```

Update trust info for all recipes in a directory (using glob patterns):

```bash
# Update trust for all recipes in a directory
autopkg_wrapper --update-trust-only --recipes "overrides/**/*.recipe.yaml"

# With concurrency for faster processing
autopkg_wrapper --update-trust-only --recipes "overrides/**/*.recipe.yaml" --concurrency 10

# Dry run to see what would be updated
autopkg_wrapper --update-trust-only --recipes "overrides/**/*.recipe.yaml" --dry-run

# Update trust for specific subdirectory
autopkg_wrapper --update-trust-only --recipes "overrides/Firefox/*.recipe.yaml"
```

## Environment Variables

Many command-line options can be set via environment variables for convenience in CI/CD environments. Environment variable names follow the pattern `AW_<OPTION_NAME>`.

### Available Environment Variables

| Environment Variable         | CLI Option                  | Default                                    | Description                              |
| ---------------------------- | --------------------------- | ------------------------------------------ | ---------------------------------------- |
| `AW_RECIPES`                 | `--recipes`                 | None                                       | Comma or space-separated list of recipes |
| `AW_RECIPE_FILE`             | `--recipe-file`             | None                                       | Path to recipe list file                 |
| `AW_RECIPE_PROCESSING_ORDER` | `--recipe-processing-order` | None                                       | Recipe processing order                  |
| `AW_AUTOPKG_BIN`             | `--autopkg-bin`             | `/usr/local/bin/autopkg`                   | Path to autopkg binary                   |
| `AW_DEBUG`                   | `--debug`                   | `False`                                    | Enable debug logging                     |
| `AW_CONCURRENCY`             | `--concurrency`             | `10`                                       | Number of parallel recipe runs           |
| `AW_TRUST_BRANCH`            | `--branch-name`             | `fix/update_trust_information/<timestamp>` | Git branch name for trust updates        |
| `AW_CREATE_PR`               | `--create-pr`               | `False`                                    | Create PR for trust updates              |
| `AW_OVERRIDES_REPO_PATH`     | `--overrides-repo-path`     | None                                       | Path to overrides repository             |
| `AW_POST_PROCESSORS`         | `--post-processors`         | None                                       | AutoPkg post processors                  |
| `AW_AUTOPKG_PREFS_FILE`      | `--autopkg-prefs`           | None                                       | Path to autopkg preferences              |
| `AW_REPORTS_ZIP`             | `--reports-zip`             | None                                       | Path to reports zip file                 |
| `AW_REPORTS_EXTRACT_DIR`     | `--reports-extract-dir`     | `autopkg_reports_summary/reports`          | Extract directory for reports            |
| `AW_REPORTS_DIR`             | `--reports-dir`             | None                                       | Directory of reports to process          |
| `AW_REPORTS_OUT_DIR`         | `--reports-out-dir`         | `autopkg_reports_summary/summary`          | Output directory for processed reports   |
| `AW_REPORTS_RUN_DATE`        | `--reports-run-date`        | `""`                                       | Run date string for reports              |
| `SLACK_WEBHOOK_TOKEN`        | `--slack-token`             | None                                       | Slack webhook token                      |
| `GITHUB_TOKEN` or `GH_TOKEN` | `--github-token`            | None                                       | GitHub token for PR/issue creation       |

### Important: Empty String Behavior

**Environment variables set to empty strings are treated as unset and will use the default value.**

This is intentional defensive behavior to prevent errors from misconfiguration. For example:

```bash
# These all use the default value
export AW_AUTOPKG_BIN=""
export AW_CONCURRENCY=""
export AW_REPORTS_OUT_DIR=""
```

This prevents issues like trying to execute an empty string as a binary path. If you need to explicitly set an empty value, use the CLI flag instead:

```bash
# Use CLI flag to explicitly set empty string
autopkg_wrapper --autopkg-bin "" --recipes test.recipe
```

To use default values, either **unset** the environment variable or set it to an empty string:

```bash
# Both of these will use the default
unset AW_AUTOPKG_BIN
export AW_AUTOPKG_BIN=""
```

### Examples

```bash
# Set via environment variables
export AW_AUTOPKG_BIN="/opt/homebrew/bin/autopkg"
export AW_CONCURRENCY="5"
export AW_DEBUG="true"
autopkg_wrapper --recipes Firefox.download Chrome.download

# Override environment variable with CLI flag
export AW_CONCURRENCY="5"
autopkg_wrapper --recipes test.recipe --concurrency 10  # Uses 10, not 5

# Mix environment variables and CLI flags
export AW_RECIPES="Firefox.download,Chrome.download"
export AW_CONCURRENCY="5"
autopkg_wrapper --debug  # Uses recipes and concurrency from env
```

## Recipe Processing Flow

```mermaid
flowchart TD
    start([Start]) --> args[Parse CLI args]
    args --> load[Load recipes list]
    load --> order{Processing order provided?}
    order -- Yes --> batches[Build recipe batches by type]
    order -- No --> all[Single batch of all recipes]
    batches --> log[Log each batch type and identifiers]
    all --> log
    log --> run[Run batch recipes concurrently within batch]
    run --> next{More batches?}
    next -- Yes --> log
    next -- No --> git[Apply git updates serially]
    git --> notify[Send notifications]
    notify --> pr{Create PR?}
    pr -- Yes --> createPR[Open trust update PR]
    pr -- No --> issues{Create issues?}
    createPR --> issues
    issues -- Yes --> createIssue[Open failures issue]
    issues -- No --> reports{Process reports?}
    createIssue --> reports
    reports -- Yes --> process[Process reports output]
    reports -- No --> done([Done])
    process --> done
```

Related code:

- `autopkg_wrapper/autopkg_wrapper.py`
- `autopkg_wrapper/utils/recipe_batching.py`
- `autopkg_wrapper/utils/recipe_ordering.py`
- `autopkg_wrapper/utils/report_processor.py`
- `autopkg_wrapper/notifier/slack.py`

Notes:

- During recipe runs, per‑recipe plist reports are written to `/private/tmp/autopkg`.
- Log output references full recipe identifiers (for example, `Foo.upload.jamf`) and batch logs list recipe identifiers grouped by type.
- When `--process-reports` is supplied without `--reports-zip` or `--reports-dir`, the tool processes `/private/tmp/autopkg`.
- If `AUTOPKG_JSS_URL`, `AUTOPKG_CLIENT_ID`, and `AUTOPKG_CLIENT_SECRET` are set, uploaded package rows are enriched with Jamf package links.
  - No extra CLI flag is required; enrichment runs automatically when all three env vars are present.

An example folder structure and GitHub Actions Workflow is available within the [`actions-demo`](actions-demo)

## Credits

- [`autopkg_tools` from Facebook](https://github.com/facebook/IT-CPE/tree/main/legacy/autopkg_tools)
- [`autopkg_tools` from Facebook, modified by Gusto](https://github.com/Gusto/it-cpe-opensource/tree/main/autopkg)
