DOCS LLMs

Zero to Shipped: the Complete Launch Path

Zero to Shipped: the Complete Launch Path

How to take a desktop app from "MVP on a laptop" to licensed, self-updating, distributed through LicenseSeat, CI-notarized, and sellable — and how much of that an agent can drive without a human.

This guide is the map; the deep guides are the territory. It exists because the full path crosses four systems (LicenseSeat, your repo's CI, Apple, Stripe) and the expensive failures live between them, where no single guide's scope reaches. Every pitfall named here happened during a real launch (Clipbasket, a Tauri macOS app, August 2026) — including two server-side plan misconfigurations that would have failed every single launch-day demo request while every dashboard screen looked correct.

Deep guides this map links into:


The Human Actions Inventory

Everything a human must do, in one place, so an agent can request them all up front instead of stalling mid-flight. Everything not listed here is agent-drivable.

# Action When Why a human
H1 Create the LicenseSeat account/organization Once Dashboard signup + email confirmation
H2 Apple Developer Program membership + Developer ID Application certificate Once Apple identity verification; certificate custody
H3 Apple app-specific password for notarization Once Generated at appleid.apple.com, behind Apple 2FA
H4 Put the five Apple values + updater private key into CI secrets Once Secret custody (see the table below)
H5 Supervise the first notarizing CI run Once A "dry run" REALLY submits to Apple; the first one should be watched
H6 Stripe account + stripe login (CLI authentication to the RIGHT account) + Payment Link creation Once Financial account and authentication are human acts. Everything downstream of an authenticated CLI is agent-drivable — see Phase 5
H7 DNS record + redirect rule for the updates vanity domain Once DNS provider access
H8 Publish the release (create the git tag / GitHub Release) Each release This is the trigger that signs + notarizes + publishes; keep it a deliberate human act
H9 Buy once with a real card after launch Once The only honest test of the money path

Everything else — product configuration, plan and entitlement setup, key generation, client integration, release pipeline authoring, artifact publishing, feed verification, even a full end-to-end update rehearsal against production — can be done by an agent, subject to the API-coverage notes at the bottom.


Phase 1 — LicenseSeat: product, plans, entitlements, keys

Where: the dashboard (some of this is dashboard-only today — see API coverage).

  1. Create the product (slug is forever — it is in every URL and compiled into the client).
  2. Set the product's commerce fields: support_email, upgrade_url (where an unlicensed app sends people to buy — a page you control, not a raw payment link: it is server-side and updatable, but demo licenses snapshot it into their metadata at issue time, so set it before the first demo is ever issued), and for EU consumer sales the digital-content consent flag so license emails carry the withdrawal text.
  3. Create the plans. Typical pair: a time-limited demo (duration_days: 14) and a paid plan (perpetual, or however you sell).
  4. Give every plan its entitlements. This is where two real launch-day failures lived, so read the contract carefully:

The entitlement contract (get this exactly right)

Each entitlement entry on a plan needs:

  • key — the feature name your client checks. The client must never invent keys; the plan is the source of truth.
  • duration_type — required: one of perpetual, match_license_expiry, or fixed. A demo plan's features almost always want match_license_expiry (they die with the demo). A paid-perpetual plan's features want perpetual, except time-boxed grants like an update window.
  • duration — only with fixed, and it is a string like "1.year" or "30.days" — not a bare number.
  • Anything else on the entry (limit, max_clips, display names…) is copied into the entitlement's metadata at issue time and arrives in the validation payload's active_entitlements[].metadata — which is exactly where clients should read caps from.

Why this section is stern: validation of these rules happens at issuance, not only at save. A plan seeded earlier (or written by hand) with a missing duration_type, or duration: 12 instead of "1.year", sits in the dashboard looking perfectly healthy — and then every attempt to issue a license from it fails. On a product whose first-run gate requests a demo license, that is a 100% launch-day outage that no green dashboard warns you about.

Prove the plans, don't trust them

The five-minute check that would have caught both real-world failures — issue one license from each plan and validate it over the real wire:

# from your server console / support of choice: issue a test license per plan,
# then, with your product's pk key:
curl -s -X POST "https://licenseseat.com/api/v1/products/<slug>/licenses/validate" \
  -H "Authorization: Bearer pk_live_…" -H "Content-Type: application/json" \
  -d '{"license_key":"<the test key>"}'

Confirm: valid: true, every expected entitlement key present, caps in each entitlement's metadata, and (for demos) demo: true plus your upgrade_url. Then revoke the test licenses. Note: licenses with audit history revoke rather than delete — that is by design, use revocation.

  1. Generate or import signing keys (dashboard, updater card): the updater signing key for your framework, and note the licensing offline key's ID + public key for the client build.
  2. Mint API keys: the product's pk_ (compiled into the client) and an sk_ with releases:write (CI's publish credential; store as a CI secret, never in the repo).

Phase 2 — Client integration

Covered end to end by the Agentic Integration Playbook: SDK setup, activation/validation/offline flows, tier engines, demo-request UX. For a Swift/Xcode app rather than a Tauri one, the platform-specific lane — pinning, key injection, sandbox entitlements, headless tests — is Integrating LicenseSeat in a Swift macOS App. Nothing to duplicate here except the one interface note this map needs:

  • Compile into the client: the pk_ key, the licensing signing public key + key ID, the updater public key, and the feed URL — ideally on your own domain.

Phase 3 — The release pipeline (CI, signing, notarization)

Two workflows, not one:

The preflight (build-only, no Apple)

Before the release workflow ever runs, a workflow_dispatch-only preflight on the same runner image should: run the full test suite, then build a release-profile bundle with the real repo variables so the release-build guards execute against the values that will ship, then verify the bundle (universal check on macOS). No secrets, no keychain, no signing, no notarization.

This is not ceremony. One real preflight sequence caught, in five runs for cents: a toolchain-profile gap, nine latent test races that only lose on loaded runners, an undocumented cross-compiler dependency, and — the one that would have killed the supervised notarizing run at compile time — a signing-key CI variable stored without its base64 = padding. Presence in the secrets list proves nothing; compiling with the values is the only verification that counts.

Apple team and bundle-ID hygiene (read before your first notarization)

Apple's anti-fraud enforcement is automated, opaque, and terminal — accounts get permanently terminated under ADP §3.2(f) with no meaningful detail and a minimum one-year reapplication ban. The patterns that trip it are worth engineering around, because the cost of a false positive is your signing identity:

  • A bundle ID lives and dies with one team. The single most dangerous act in the ecosystem is notarizing a bundle ID that has history under a different team — especially from a young account. Apple's systems read it as zombie-app hijacking, and developer reports of same-day permanent terminations for exactly this exist. If you ever restructure entities, do not migrate bundle IDs: ship new products under the new team and let old ones live out their lives where they were born.
  • New bundle ID + established team is the safe quadrant. First-time notarization of a virgin bundle ID from an account with history is the most ordinary operation there is. (First-ever submissions from a new team can take hours instead of minutes while Apple runs extra checks — delay, not judgment.)
  • Keep notarization volume boring. A quiet team suddenly submitting a burst of throwaway builds is an anomaly signature. This is another reason the preflight exists: iterate where Apple isn't watching, and let Apple see only the dry run and real releases.
  • Keep the submitting Apple ID's team memberships clean. An Apple ID that sits on multiple teams links those teams in Apple's graph. CI credentials should belong to exactly the team that ships the product.
  • If enforcement ever hits anyway: do not resubmit anything. Capture the submission ID and the notice, and appeal through Apple Developer Support with the account's shipping history; Apple's own termination notices name Platform Regulation complaint channels as further recourse.

The release workflow

Triggered by publishing a GitHub Release (H8) or manual dispatch — never by push. It imports the Developer ID certificate into a throwaway keychain, builds, signs, notarizes (a dry run REALLY submits to Apple — H5), staples, verifies, attaches artifacts, and publishes the LicenseSeat feed via the publish pipeline.

One content rule for that publish step: the notes it posts render inside customers' update dialogs, so never forward a GitHub Release body verbatim — auto-generated PR lists leak internal titles and repo URLs to every customer. Cut auto-notes in CI and/or curate notes on the platform; the doctrine.

Secrets/variables an agent should request from the human (H4), by exact name and with the verification each one deserves:

Name Kind Gotcha
APPLE_CERTIFICATE_P12 + _PASSWORD secret Export must contain exactly one Developer ID Application identity
APPLE_ID, APPLE_TEAM_ID secret Team must be the entity that ships THIS product
APPLE_APP_SPECIFIC_PASSWORD secret Map it to whatever env name your tooling expects (APPLE_PASSWORD for tauri-bundler)
updater private key secret If passwordless, leave the password secret unset (empty is correct)
sk_ releases:write token secret Scope to releases only; it publishes feeds
pk_, signing public key, signing key ID, updater public key variables Padding survives no clipboard (a 43-char Ed25519 key is a truncated 44-char one), and tauri signer writes .pub files already base64-encoded — storing base64(.pub) double-encodes it. Verify by compiling (preflight), not by eyeballing

Rehearse the update path before the first real release

The full production update path can be proven without Apple and without touching your stable channel: build two throwaway versions locally (0.0.1/0.0.2) with a throwaway updater keypair and the feed pointed at ?channel=beta, publish 0.0.2 to the beta channel with a short-lived sk_, run 0.0.1, and watch it update itself through the real publish → feed → download → signature-verify → install → relaunch chain. Then yank the beta release, revoke the temporary token, shred the throwaway keys. Stable stays a 204 the whole time; the real updater key never leaves custody. ~15 minutes, and after it the only unproven link in your entire pipeline is Apple's notarization itself.


Phase 4 — The updates domain

Before the first release (the URL ships inside the binary): put the feed behind a domain you own (H7). One DNS record, one path-and-query-preserving 308, one curl -sIL verification.


Phase 5 — Selling

  1. Payment Link (H6), with the EU consent checkbox where required.

    The agent/human split, precisely: creating the account and running stripe login are human; everything after is CLI/API-drivable — payment_links list (the mapping needs the plink_… ID, which the public URL does not contain), auditing the link's config, setting the EU withdrawal-consent custom text (payment_links update with custom_text[terms_of_service_acceptance][message]; the dashboard only offers a generic ToS checkbox, which does NOT waive the withdrawal right — the message field supports markdown links), and webhook_endpoints create with checkout.session.completed + charge.refunded. Two ordering rules: create the LicenseSeat webhook endpoint FIRST (it mints the tokenized URL the Stripe endpoint points at), and treat the returned whsec_ signing secret like any credential — store it server-side without echoing it through logs or transcripts. Verify the consent checkbox by LOOKING at the live checkout page: the generic dashboard toggle and the compliant custom message are visually distinct, and only one of them protects you.

  2. Put it behind your site's buy button; keep the product's upgrade_url pointing at your pricing page rather than the raw link.

  3. Wire the payment provider's webhook to LicenseSeat so checkout issues and emails the license key automatically. The exact contract, learned live:

    • Create the LicenseSeat webhook endpoint FIRST (dashboard → Webhooks): it mints the tokenized destination URL and stores the provider's signing secret.
    • Map the Payment Link ID, not the price or product ID — the mapping validates the plink_ prefix specifically, and the public buy-URL slug is NOT the ID (fetch it via payment_links list).
    • Stripe after-payment redirect: …/products/<slug>/thank_you/{CHECKOUT_SESSION_ID} (literal placeholder) shows the key instantly — buyers never wait on email.
    • Quantity: fixed at 1. Fulfillment issues one key per checkout session; adjustable quantity charges for keys it will not deliver.
    • Consent evidence needs nothing extra: the checkout session retains the consent response and the payment-event row stores the payload verbatim. emails the license key automatically.
  4. After launch: one real purchase with a real card (H9), then verify the full chain — email arrived (with consent text where applicable), key activates, entitlements arrive, an update from a previous version installs.


Launch-order rule of thumb

Configuration that licenses depend on (plans, entitlements, upgrade_url, signing keys) before the first license exists. Domains and feed URLs before the first binary ships. Apple rehearsal (preflight) before the supervised notarizing run. The money path last, proven with real money once.


API coverage for agents

What an agent can drive over the public API today with pk_/sk_ keys: the entire license lifecycle (issue, validate, activate, deactivate, revoke, heartbeat, machine files, offline tokens, demo issuance) and the entire release pipeline (draft, register artifact, upload, finalize, publish, download tokens, feeds, signing-key reads).

What is dashboard-or-console-only today — the gaps between "mostly agentic" and "fully agentic":

  • Product creation and configuration (slug, demo gate, upgrade_url, consent flags)
  • Plan and entitlement management — notable because the entitlement contract above is exactly where the silent launch-killers live; an API with save-time validation would turn that class of failure into a 422
  • API-key minting (pk_/sk_), including short-lived scoped tokens for rehearsals
  • Signing-key generation/import

Until those exist, a fully-agentic bootstrap needs either dashboard automation or operator console access for Phase 1; everything after Phase 1 is API-clean. These gaps are tracked as feature requests on the platform — if you are reading this after they shipped, the sections above marked "dashboard" should have API equivalents; prefer them.


Process pitfalls for agents

Not about LicenseSeat, Apple, or code. These are the three ways a correct piece of work still lands wrong, all of them observed on real releases.

1. Verify a pull request's base branch before merging it. A branch that has been open for weeks was based on whatever the default branch was called then. If the repository has since renamed or switched its default branch, the PR still points at the old one — and squashing it lands your work on a branch nobody builds, nobody reviews, and nobody notices is diverging. The check costs one command:

gh pr view <n> --json baseRefName --jq .baseRefName
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name

Compare them before the merge, not after the release fails to contain your change. Retargeting a PR is trivial; unwinding a squash into a stale branch is not.

2. A CI failure that dies in 2–5 seconds with zero steps executed is a billing problem, not a code signal. GitHub Actions blocks runs when a spending limit is hit or a payment method fails, and the resulting run looks like a red X on your commit. Nothing was compiled; nothing was tested. Two consequences worth internalising:

  • Do not "fix" it. Read the run: if no step produced output, there is nothing in your diff to fix. Chasing it wastes an hour and can produce real changes justified by a phantom failure.
  • macOS runners bill at 10× the Linux rate. A macOS-heavy matrix can drain a free-tier pool mid-month and take every other workflow in the account down with it. When the notarizing lane is the thing that has to run, budget for it deliberately — and keep iteration on cheap runners (this is a second reason the preflight pattern pays for itself).

While billing is blocked, local verification is the source of truth, and any statement about CI being green is unearned. Say which one you actually ran.

3. Piping a build, test run, or deploy through grep, tail or head swallows its exit code. In a pipeline the shell reports the last command's status, so a failing build followed by a successful grep is a successful step. set -o pipefail fixes it in bash; the more robust habit is to stop piping altogether:

xcrun xctest "$TEST_BUNDLE" > "$LOG" 2>&1     # status is the test run's
grep -F "some marker" "$LOG"                   # judged separately

Capture to a file, check the status, then interrogate the file — and upload it as an artifact on failure. The same rule kills the related anti-pattern of deciding a run succeeded because its output contained a success string: match on the exit status first, on file contents second, and fail closed when the two disagree.