# 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. ```sh source Scripts/product.env printf 'GitHub repository: %s\nDefault branch: %s\n' "$PRODUCT_GITHUB_REPO" "$PRODUCT_DEFAULT_BRANCH" ``` - [ ] Create an expiring **fine-grained GitHub PAT**, restricted to `$PRODUCT_GITHUB_REPO` only, with **Contents: write** and **Workflows: write**. Put it only in the GitHub `mirror` environment secret **`MIRROR_TOKEN`**. If launch has cached the old token in Keychain, use `--replace-secret MIRROR_TOKEN` to store the new PAT. Release dispatch uses the ephemeral workflow token with Actions write, so the PAT needs no additional permission. - [ ] Set GitHub's default branch to `$PRODUCT_DEFAULT_BRANCH` (`main` by default). Both `mirror` and `release` environments must use **Selected branches and tags** with exactly one **branch** policy named `$PRODUCT_DEFAULT_BRANCH`; no tag policies or wildcard branches. `release` must require the repository owner as its only reviewer, with **Allow administrators to bypass configured protection rules** off. - [ ] Protect `$PRODUCT_DEFAULT_BRANCH`: an active branch ruleset with **Block force pushes** and **Restrict deletions**, no bypass actors or exclusions, targeting that branch, the default branch, or all branches. Alternatively, classic branch protection must disallow force pushes and deletions and apply to administrators. - [ ] Create the active **`release-tags`** tag ruleset targeting **`refs/tags/v*`**, with **Restrict updates** and **Restrict deletions**, no exclusions or bypass actors. - [ ] Keep signing, notarization, and private update-key secrets only in `release`. Remove any repository-level signing/notarization/update-key or `MIRROR_TOKEN` copies in GitHub Settings after confirming the environment secrets are complete. Commit the permanent `PRODUCT_UPDATE_PUBLIC_KEY` before the first release; never rotate it implicitly. - [ ] Delete the old **`MIRROR_TOKEN`** and any other spindle secrets from Tangled's Secrets UI, then revoke that old token in GitHub. Tangled must hold no secrets. - [ ] Bootstrap predecessor metadata before launching against an existing release. CI now publishes each release's `appcast.xml` as a GitHub release asset. Preflight reads the latest published release's asset and requires a strictly newer commit, version, and build number. Published tags use numeric `vMAJOR.MINOR.PATCH` versions and positive integer build numbers. Local packaging can use prerelease and build suffixes, but the ordered release pipeline rejects them. If that release lacks `appcast.xml`, stop and manually restore its original exact metadata asset. Never generate replacement metadata, invent or reuse build numbers, or bypass the predecessor check. 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](../.github/workflows/mirror.yml) pulls Tangled's public default branch and new eligible release tags into GitHub every 15 minutes. Each new tag push triggers the [tag dispatcher](../.github/workflows/release-tag.yml), which checks out trusted default-branch scripts and dispatches the [release workflow](../.github/workflows/release.yml) 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: ```sh 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.