Skip to main content

Getting started

Install a binary for your runner's operating system and architecture from Releases, and put stemma (stemma.exe on Windows) on your PATH. To use the current source checkout, see development.

A catalog repository can pin the release with Mise instead, so local runs and CI install the same verified binary:

mise use github:woodleighschool/stemma
mise lock

Commit the Mise configuration and mise.lock.

The runner is the computer executing Stemma. It can prepare software for a different operating system; see runtime requirements.

Create a catalog​

Our catalog is a starting point with software definitions and plugins. See starting a catalog for its structure, or create a minimal one below.

This walkthrough prepares Chrome for a local Munki repository. It needs no service credentials and does not install Chrome on the runner. For Windows and Intune, use the same command sequence with the Intune example.

Create a directory and initialise Git:

mkdir my-catalog
cd my-catalog
git init
mkdir software

Save this as stemma.yaml:

apiVersion: stemma/v1alpha1
kind: Project
metadata:
  name: my-catalog
spec:
  imports:
    - software/**/*.yaml
  destinations:
    munki:
      operation: munki
      config:
        path: munki-repo

Save this as software/chrome.yaml:

apiVersion: stemma/v1alpha1
kind: MacSoftware
metadata:
  name: chrome
spec:
  source:
    url: https://dl.google.com/dl/chrome/mac/universal/stable/gcem/GoogleChrome.pkg
  application:
    bundle_id: com.google.Chrome
  destinations:
    munki:
      pkginfo:
        catalogs:
          - testing
        description: Google Chrome.

Add munki-repo/ to .gitignore; it will contain this walkthrough's published repository. Downloads and prepared artifacts use the system's user cache directory by default. See cache and offline runs for inspection and overrides.

Prepare and review​

Run from the catalog:

stemma validate
stemma update
git diff -- stemma.lock
stemma prepare
stemma plan

validate checks the documents and operation contracts without credentials or downloads. update downloads the installer and writes its lock document under stemma.lock/. A new document is untracked: open it directly as well as checking git status. prepare builds what the lock pins and inspects it.

plan reads the destination and reports the changes it would make. It can fetch locked inputs into an empty cache, but does not write to the destination. It is the dry run.

The selected bundle supplies application metadata. You do not need to repeat its version and bundle identifier as separate extraction steps.

Commit stemma.yaml, software/ and stemma.lock/ when the inputs are right.

Publish​

stemma apply

For this example, publication writes pkginfo, installer content and catalogs under munki-repo/. It does not enrol or target a device. Publishing to an existing repository can affect clients already using it; destination configuration defines that behaviour.

Run stemma plan again to see whether anything remains to reconcile. apply re-reads destination state; it does not replay a saved plan.

Pick up a new version​

stemma update MacSoftware/chrome
stemma prepare MacSoftware/chrome
git diff -- stemma.lock
stemma plan MacSoftware/chrome

update checks upstream again and records what it finds. Review and commit the new lock before applying. See sources and updates for local changes, cold caches and URLs whose content changes in place.