macos-release

Q: How do I install macos-release?

Run npx skills add https://github.com/fayazara/macos-app-skills --skill macos-release in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/macos-release/ (personal) or .claude/skills/macos-release/ (project).

by fayazaraCode Quality & Workflow

Release a native macOS app to GitHub with DMG packaging and Sparkle appcast updates. Use this skill whenever the user wants to publish a new version, create a release, ship an update, push a release to GitHub, or update the appcast. Also trigger when the user mentions DMG creation, Sparkle signing, notarization, archiving, or anything related to distributing a new version of their macOS app. This covers the full release pipeline: archive, notarize, export, create DMG, sign with Sparkle EdDSA, update appcast.xml, git push, and GitHub release creation.

Installs: 587
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/fayazara/macos-app-skills --skill macos-release

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads macos-release automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Release macOS App

This skill covers the full release pipeline for distributing a native macOS app outside the Mac App Store via GitHub Releases with Sparkle auto-update support.

Release Pipeline Overview

Bump version → Archive → Notarize → Export → Create DMG → Sign DMG → Update appcast.xml → Git push → GitHub Release

Prerequisites

The user needs these tools installed:

Tool	Install	Purpose
`create-dmg`	`brew install create-dmg`	Creates the DMG installer
`gh`	`brew install gh`	Creates GitHub releases
`git`	Built-in	Pushes appcast changes
Sparkle `sign_update`	Built automatically when the project is built with Sparkle	EdDSA-signs the DMG

The sign_update binary lives in DerivedData after building the project in Xcode:

find ~/Library/Developer/Xcode/DerivedData -name "sign_update" -type f 2>/dev/null | head -1

Step-by-Step Release Guide

1. Bump Version Numbers

In Xcode, update:

MARKETING_VERSION (e.g., 1.2) -- the user-facing version
CURRENT_PROJECT_VERSION (e.g., 5) -- the build number (must be unique per release)

Or via command line:

# Check current values
grep -E "MARKETING_VERSION|CURRENT_PROJECT_VERSION" YourApp.xcodeproj/project.pbxproj | head -4

2. Archive in Xcode

Product > Archive. This creates a release build with the proper signing identity.

3. Notarize and Export

In the Archives organizer:

Select the archive > Distribute App
Choose "Direct Distribution" (or "Developer ID" for notarization)
Wait for notarization to complete
Export to ~/Downloads/YourApp.app

4. Create DMG

create-dmg \
  --volname "YourApp" \
  --window-pos 200 120 \
  --window-size 660 400 \
  --icon-size 160 \
  --icon "YourApp.app" 180 170 \
  --app-drop-link 480 170 \
  --hide-extension "YourApp.app" \
  ~/Downloads/YourApp.dmg \
  ~/Downloads/YourApp.app

5. Sign DMG with Sparkle

/path/to/sign_update ~/Downloads/YourApp.dmg

This outputs the EdDSA signature and file length:

sparkle:edSignature="BASE64..." length="12345"

Save both values for the appcast.

6. Update appcast.xml

Add a new <item> at the top of the <channel> in your appcast.xml:

<item>
  <title>Version 1.2 (Build 5)</title>
  <pubDate>Mon, 26 May 2026 12:00:00 +0000</pubDate>
  <sparkle:version>5</sparkle:version>
  <sparkle:shortVersionString>1.2</sparkle:shortVersionString>
  <sparkle:minimumSystemVersion>14.0</sparkle:minimumSystemVersion>
  <description><![CDATA[<ul><li>Feature one</li><li>Bug fix two</li></ul>]]></description>
  <enclosure url="https://github.com/OWNER/REPO/releases/download/v1.2/YourApp.dmg"
             type="application/octet-stream"
             sparkle:edSignature="THE_SIGNATURE_FROM_STEP_5"
             length="THE_LENGTH_FROM_STEP_5" />
</item>

The pubDate should be RFC 2822 format. Generate it:

date -R

7. Commit and Push Appcast

git add appcast.xml
git commit -m "Release v1.2 appcast"
git push origin main

8. Create GitHub Release

gh release create v1.2 \
  ~/Downloads/YourApp.dmg \
  --title "v1.2" \
  --notes "- Feature one
- Bug fix two"

Automating the Pipeline

For frequent releases, build a CLI tool that automates steps 4-8. See references/release-pipeline.md for a template Go CLI that handles DMG creation, signing, appcast updates, and GitHub release creation in one command.

The CLI should:

Find sign_update in DerivedData automatically
Read version/build from the exported app's Info.plist via plutil
Parse and update appcast.xml (preserving existing entries)
Interactively collect release notes
Show a summary and ask for confirmation before proceeding
Create the GitHub release with the DMG attached

Release CLI Tool

This repo includes a Go CLI that automates steps 4-8 (DMG creation through GitHub release) in a single command. It reads configuration from a release.json file in your project root.

Setup

Create a release.json in your project root (see cli/release.example.json):

{
  "app_name": "MyApp",
  "github_repo": "owner/myapp"
}

Only app_name and github_repo are required. Everything else has sensible defaults:

Field	Default	Description
`bundle_name`	`{app_name}.app`	The .app bundle filename
`dmg_name`	`{app_name}.dmg`	Output DMG filename
`git_branch`	`main`	Branch to push appcast to
`min_system_version`	`14.0`	Sparkle minimum macOS version
`appcast_file`	`appcast.xml`	Appcast filename in repo root
`derived_data_prefixes`	`["{app_name}-"]`	DerivedData prefixes to search for `sign_update`

Run the CLI from your project directory:

go run github.com/fayazara/macos-app-skills/release/cli@latest

Or clone this repo and run locally:

go run ./release/cli

The CLI is interactive -- it prompts for release notes and asks for confirmation before proceeding. It must be run in a terminal the user can interact with.

What the CLI Does

Finds release.json by walking up from the current directory
Checks that create-dmg, gh, git, and Sparkle's sign_update are available
Validates the exported app in ~/Downloads/ (reads version, build, Sparkle keys from Info.plist)
Warns if the build number already exists in the appcast
Collects release notes interactively (one bullet per line, empty line to finish)
Shows a release summary and asks for confirmation
Creates the DMG via create-dmg
Signs the DMG with Sparkle's sign_update (EdDSA)
Updates appcast.xml with the new release entry
Commits and pushes the appcast
Creates a GitHub release with the DMG attached

Common Issues

Problem	Solution
`sign_update` not found	Build the project in Xcode first so DerivedData has the Sparkle artifacts
`gh` auth failure	Run `gh auth login`
Duplicate build number in appcast	Bump `CURRENT_PROJECT_VERSION` before archiving
Notarization fails	Check signing identity, entitlements, and hardened runtime settings
DMG is too large	Check for debug symbols or unnecessary frameworks in the export
App won't update	Verify `SUFeedURL` points to the raw appcast URL, not the GitHub page URL

Appcast Hosting

The simplest hosting: commit appcast.xml to your GitHub repo and use the raw URL:

https://raw.githubusercontent.com/OWNER/REPO/main/appcast.xml

This must match SUFeedURL in your app's Info.plist.

FAQ

What does the macos-release skill do?

How do I install macos-release?

Run npx skills add https://github.com/fayazara/macos-app-skills --skill macos-release in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/macos-release/ (personal) or .claude/skills/macos-release/ (project).

Which AI agents can use macos-release?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is macos-release safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains macos-release?

It is published by fayazara in fayazara/macos-app-skills. It has 587 recorded installs.

More from fayazara/macos-app-skills

View all →

macos-patterns

fayazara/macos-app-skills

Essential native macOS development patterns that web developers don't know about. Use this skill whenever the user is building a macOS app and needs guidance on native patterns, or when they ask about menu bar apps, floating panels, window levels, keyboard shortcuts, file pickers, clipboard, drag and drop, screen capture, activation policy, Quick Look, launch at login, or any macOS-specific API. Also trigger when the user seems to be applying web development patterns to macOS (e.g., using z-index thinking for windows, expecting simple clipboard APIs, or not understanding focus/activation). This is the "how things actually work on macOS" reference that prevents the AI from generating confident but wrong code. Use this skill proactively whenever building any native macOS app.

Backend & APIs676 installs

macos-settings-ui

fayazara/macos-app-skills

Build a proper macOS settings/preferences window with liquid glass support for macOS 26 (Tahoe). Use this skill whenever the user asks to create a settings window, preferences UI, settings view, or preferences pane for a macOS app. Also trigger when the user mentions "liquid glass settings", "NavigationSplitView settings", "grouped Form settings", "macOS settings layout", or wants to add/fix/rebuild a settings screen in any native macOS SwiftUI app. This includes phrases like "add settings to my app", "create a preferences window", "my settings look wrong", "fix my settings UI", or even just "I need a settings view". If the user is building a macOS app and mentions settings or preferences in any context, use this skill.

Frontend & Design655 installs

macos-build

fayazara/macos-app-skills

Build a native macOS app using xcodebuild from the command line. Use this skill whenever the user asks to build, compile, or check if their macOS project compiles successfully. Also use it when the user asks to fix build errors, verify changes compile, or run a debug build. Trigger on phrases like "build the app", "does it compile", "run xcodebuild", "fix build errors", or even just "build".

Code Quality & Workflow614 installs

macos-auto-update

fayazara/macos-app-skills

Add Sparkle auto-update support to a native macOS app. Use this skill whenever the user wants to add auto-updates, implement Sparkle, set up an appcast feed, add "Check for Updates" to their app, or integrate automatic update checking. Also trigger when the user mentions Sparkle, appcast, SUFeedURL, EdDSA signing, or update notifications. This covers the full setup: adding the Sparkle SPM dependency, creating the UpdaterManager singleton, wiring it into the app delegate and UI, configuring Info.plist, and generating the initial appcast.xml.

Frontend & Design569 installs

macos-notch-ui

fayazara/macos-app-skills

Add a Dynamic Island-style notch UI to a macOS app. Use this skill whenever the user wants to create a notch overlay, notch extender, Dynamic Island for Mac, notch indicator, or any UI that extends from the MacBook notch area. Also trigger when the user mentions "notch shape", "notch window", "notch cutout", "notch panel", "recording indicator near the notch", "Dynamic Island style", or wants to show status/content that appears to emerge from the hardware notch. This covers the NSPanel setup, the NotchShape with concave Bezier ear curves, screen positioning math, spring animations, and show/hide choreography.

Frontend & Design566 installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs

macos-release

Install

Install

Describe the task

Review the result

SKILL.md

Release macOS App

Release Pipeline Overview

Prerequisites

Step-by-Step Release Guide

1. Bump Version Numbers

2. Archive in Xcode

3. Notarize and Export

4. Create DMG

5. Sign DMG with Sparkle

6. Update appcast.xml

7. Commit and Push Appcast

8. Create GitHub Release

Automating the Pipeline

Release CLI Tool

Setup

What the CLI Does

Common Issues

Appcast Hosting

FAQ

More from fayazara/macos-app-skills

Popular code quality & workflow skills