An auto tiler for macOS
parcel docs releasing-setup.md
7.0 kB · 112 lines
Markdown
at main

Releasing setup #

Owner checklist. Repository identities, hosting, and the default branch come from Scripts/product.env; don't paste credentials into that file. The launch script checks these policies read-only and stops if setup is incomplete. Make the settings and cleanup changes yourself; it never changes protections or deletes secrets.

source Scripts/product.env
printf 'GitHub repository: %s\nDefault branch: %s\n' "$PRODUCT_GITHUB_REPO" "$PRODUCT_DEFAULT_BRANCH"

Run Scripts/launch.sh --dry-run, then launch interactively on the signing Mac. Review the release environment approval before signing. The mirror and release workflows run from the configured default branch; release tags carry no secrets.

What CI builds and publishes #

The mirror workflow pulls Tangled's public default branch and new eligible release tags into GitHub every 15 minutes. Each new tag push triggers the tag dispatcher, which checks out trusted default-branch scripts and dispatches the release workflow there. Direct GitHub tag pushes follow the same path. Tangled needs no macOS runner or publishing credentials. The mirror copies at most three new tags per run because GitHub suppresses tag push events for larger batches. For direct GitHub pushes, also push at most three release tags at a time; use manual dispatch to recover a bulk import.

Release runs the screen-free CI gates, builds a universal app without signing secrets, then waits for the release environment approval. After approval it signs and notarizes the app and DMG, staples both, signs the update, and publishes the DMG, SHA256SUMS, and appcast.xml to a GitHub release. The Actions artifact named by PRODUCT_RELEASE_ARTIFACT also retains the finished DMG, checksums, appcast, and rendered cask for 30 days, including when publication fails.

Ordinary branch CI does not publish installers. Push a new vMAJOR.MINOR.PATCH tag to Tangled or GitHub to start a release. Tags whose tagged commit predates the dispatcher need an explicit release dispatch, as do existing tags when recovering a failed dispatch. Rerunning the mirror does not dispatch an existing tag again. From an authenticated owner checkout:

source Scripts/product.env
gh workflow run "$PRODUCT_RELEASE_WORKFLOW" --repo "$PRODUCT_GITHUB_REPO" \
  --ref "$PRODUCT_DEFAULT_BRANCH" -f tag=v0.1.0

Use the desired existing vMAJOR.MINOR.PATCH tag. It must point into the default branch's history and pass release ordering checks. To pull a new Tangled tag immediately instead of waiting for the schedule, run the Mirror workflow from GitHub Actions on the default branch. Inspect the Release run, then approve its signing job when the displayed tag and commit are correct. Completed installers appear under GitHub Releases; the installation is a drag into Applications.

Before the first signed release, set these environment secrets in release:

Secret Value
DEVELOPER_ID_P12 Base64-encoded Developer ID Application certificate and private key
DEVELOPER_ID_PASSWORD Password protecting that PKCS#12 archive
DEVELOPER_ID_IDENTITY Exact Developer ID Application signing identity
APPLE_TEAM_ID Team identifier matching the certificate
ASC_PRIVATE_KEY App Store Connect API private key contents (.p8)
ASC_KEY_ID API key identifier
ASC_ISSUER_ID API key issuer identifier
SPARKLE_PRIVATE_KEY Permanent update signing seed matching the committed public key

Scripts/parcel-dev.sh generate-update-key creates the update key locally and prints the public key to commit in Scripts/product.env. Keep that key stable. The public key is currently unset in the source template: local dry runs work, but CI deliberately refuses signed builds until the permanent key is committed and the environment is configured. GitHub publication uses its workflow token; no additional release PAT belongs in release.

If a run fails after creating a draft, fix the reported issue and dispatch the same tag again. The publisher resumes drafts and refuses to overwrite published releases. A failed tag dispatch also needs the explicit command above; the tag is retained. Site appcast deployment and tap publication remain separate owner steps, using the verified metadata saved with the run.