Skip to content

App Store Setup

Jump to bottom
Rob Lazzurs edited this page Jan 14, 2026 · 1 revision

Mac App Store Setup Guide

This guide walks you through setting up OnCall Notify for distribution on the Mac App Store.

Overview

OnCall Notify supports dual distribution:

  • Direct Distribution: Signed DMG files via GitHub Releases (already configured)
  • Mac App Store: Distribution through the official App Store (this guide)

Prerequisites

1. Apple Developer Program Membership

2. Required Tools

  • macOS 13.0+ with Xcode 15.0+
  • Command Line Tools installed: xcode-select --install
  • Access to App Store Connect

Step 1: App Store Connect Setup

1.1 Create App Record

  1. Go to App Store Connect
  2. Click My Apps → + → New App
  3. Fill in the details:
    • Platforms: macOS
    • Name: OnCall Notify
    • Primary Language: English (U.S.)
    • Bundle ID: Select ie.unicornops.oncallnotify
    • SKU: oncallnotify-macos (or your choice)
    • User Access: Full Access

1.2 App Information

Navigate to your app → App Information:

Category

  • Primary: Developer Tools or Productivity
  • Secondary: (optional) Business

App Store Icon

  • Size: 1024x1024 pixels
  • Format: PNG or JPEG
  • No alpha channel
  • No rounded corners (Apple adds these)

1.3 Pricing and Availability

Navigate to Pricing and Availability:

  • Price: Free (or set your price)
  • Availability: All countries or select specific ones
  • Pre-Order: Not recommended for first release

1.4 Privacy Policy

Required for all apps:

  1. Create a privacy policy (can host on GitHub Pages)
  2. Add URL in App Store Connect
  3. Must include:
    • What data you collect (API tokens stored locally)
    • How you use it (API calls to PagerDuty, etc.)
    • User rights (can delete data anytime)

Example privacy policy outline:

# Privacy Policy for OnCall Notify

## Data Collection
OnCall Notify does NOT collect, store, or transmit any user data to third parties.

## Local Storage
- API tokens are stored securely in macOS Keychain
- All data stays on your device
- No analytics or tracking

## Third-Party Services
The app connects to services you configure (e.g., PagerDuty) using API tokens you provide.
These connections follow the privacy policies of those services.

## Data Deletion
Simply delete the app to remove all stored data.

Step 2: Certificates and Provisioning

2.1 Create Certificates

You need two certificates for App Store distribution:

A. Mac App Store Application Certificate

  1. Go to Apple Developer Portal
  2. Click + to create a new certificate
  3. Select Mac App Store → Mac App Store Distribution
  4. Follow instructions to create a Certificate Signing Request (CSR): 
    # Open Keychain Access
# Keychain Access → Certificate Assistant → Request a Certificate from a Certificate Authority
# Enter your email, select "Saved to disk"
  5. Upload the CSR
  6. Download the certificate
  7. Double-click to install in Keychain

B. Mac App Store Installer Certificate

  1. Same process as above
  2. Select Mac Installer Distribution
  3. Download and install

2.2 Create Provisioning Profile

  1. Go to Profiles in Developer Portal
  2. Click + to create new profile
  3. Select Mac → Mac App Store
  4. Select your App ID: ie.unicornops.oncallnotify
  5. Select your Mac App Store Distribution certificate
  6. Name it: OnCallNotify App Store
  7. Download the .provisionprofile file
  8. Double-click to install

2.3 Export Certificates for GitHub Actions

To enable automated builds in GitHub Actions:

# Export App Store Application Certificate
security find-identity -v -p codesigning | grep "3rd Party Mac Developer Application"
# Note the certificate name

# Export to P12 format (will prompt for password - save this!)
security export -k login.keychain \
  -t identities \
  -f pkcs12 \
  -o appstore_app.p12 \
  -P "YOUR_EXPORT_PASSWORD"

# Base64 encode for GitHub Secret
base64 -i appstore_app.p12 -o appstore_app.p12.base64

# Repeat for Installer Certificate
security export -k login.keychain \
  -t identities \
  -f pkcs12 \
  -o appstore_installer.p12 \
  -P "YOUR_EXPORT_PASSWORD"

base64 -i appstore_installer.p12 -o appstore_installer.p12.base64

# Export provisioning profile
base64 -i ~/Library/MobileDevice/Provisioning\ Profiles/*.provisionprofile \
  -o provisioning.base64

Step 3: GitHub Secrets Configuration

Add these secrets to your GitHub repository:

  1. Go to your repo → Settings → Secrets and variables → Actions
  2. Add the following Repository secrets:
Secret Name Value Description
APPSTORE_CERTIFICATE_BASE64 Contents of appstore_app.p12.base64 App signing certificate
APPSTORE_INSTALLER_CERTIFICATE_BASE64 Contents of appstore_installer.p12.base64 Installer signing certificate
APPSTORE_CERTIFICATE_PASSWORD Your export password Password used when exporting P12
APPSTORE_PROVISIONING_PROFILE_BASE64 Contents of provisioning.base64 Provisioning profile

Note: You should already have these secrets from direct distribution:

  • APPLE_DEVELOPER_ID - Your Apple ID email
  • APPLE_APP_PASSWORD - App-specific password
  • APPLE_TEAM_ID - Your team ID (e.g., ABC123XYZ)

Step 4: App Store Connect API Keys (Recommended)

Using API keys is more secure than Apple ID + password:

  1. Go to App Store Connect
  2. Navigate to Users and Access → Keys → App Store Connect API
  3. Click + to generate a new key
  4. Give it a name: GitHub Actions - OnCall Notify
  5. Access: App Manager or Admin
  6. Download the .p8 file (only available once!)
  7. Note the Key ID and Issuer ID

Add to GitHub Secrets:

Secret Name Value
APPSTORE_API_KEY Contents of the .p8 file
APPSTORE_API_KEY_ID Key ID from App Store Connect
APPSTORE_API_ISSUER_ID Issuer ID from App Store Connect

Update .github/workflows/appstore-release.yml to use API keys instead of Apple ID.

Step 5: Prepare Marketing Materials

5.1 Screenshots

Required sizes (capture on different macOS displays):

  • macOS: At least 3 screenshots
  • Minimum size: 1280 x 800 pixels
  • Maximum size: 2880 x 1800 pixels
  • Format: PNG or JPEG

Tips:

  • Show the app in use (menu bar popover open)
  • Show settings screen
  • Show alert notifications
  • Use Cmd+Shift+4 for screenshots

5.2 App Description

Navigate to App Store → macOS App Store in App Store Connect:

Promotional Text (170 characters max)

Stay on top of your on-call alerts with real-time notifications in your menu bar. 
Currently supports PagerDuty with more services coming soon.

Description (4000 characters max)

OnCall Notify is your unified on-call status monitor for macOS. Keep track of 
incidents, alerts, and on-call schedules directly from your menu bar.

FEATURES
• Real-time alert monitoring from your menu bar
• Separate counts for acknowledged and unacknowledged alerts
• Quick acknowledge incidents with one click
• Visual on-call status indicator
• See when your next shift starts
• Secure API token storage in macOS Keychain
• Auto-refresh every 60 seconds
• Native macOS UI built with SwiftUI
• Lightweight and efficient

CURRENTLY SUPPORTED SERVICES
• PagerDuty - Full support for incidents and on-call schedules

COMING SOON
• Atlassian Compass
• Atlassian Jira Service Management
• VictorOps/Splunk On-Call
• Alertmanager
• Custom webhooks

REQUIREMENTS
• macOS 13.0 (Ventura) or later
• Account with a supported service (currently PagerDuty)

PRIVACY & SECURITY
• No data collection or tracking
• API tokens stored securely in macOS Keychain
• All API requests use HTTPS
• No third-party analytics

OnCall Notify is free and open source, licensed under GPLv3.

Keywords (100 characters max, comma-separated)

pagerduty,oncall,alerts,monitoring,devops,sre,incidents,notifications,menu bar,status

Support URL

https://github.com/unicornops/oncallnotify/issues

Marketing URL (optional)

https://github.com/unicornops/oncallnotify

5.3 What's New (Version Information)

For your first release:

Initial release of OnCall Notify for macOS!

• Monitor your PagerDuty incidents in real-time
• See your on-call status at a glance
• Acknowledge incidents with one click
• Secure token storage in macOS Keychain
• Native macOS design with SwiftUI

This is the first public release. More services and features coming soon!

Step 6: Build and Upload

6.1 Manual Build (For Testing)

# Build locally using the App Store script
./build-appstore.sh 0.16.0

# The script will create:
# - build/AppStore/OnCallNotify.xcarchive
# - build/AppStore/OnCallNotify.pkg

# Validate before upload
xcrun altool --validate-app \
  -f build/AppStore/OnCallNotify.pkg \
  -t macos \
  --apple-id "YOUR_APPLE_ID" \
  --password "YOUR_APP_PASSWORD" \
  --team-id "YOUR_TEAM_ID"

# Upload manually
xcrun altool --upload-app \
  -f build/AppStore/OnCallNotify.pkg \
  -t macos \
  --apple-id "YOUR_APPLE_ID" \
  --password "YOUR_APP_PASSWORD" \
  --team-id "YOUR_TEAM_ID"

6.2 Automated Build (GitHub Actions)

# Trigger the App Store workflow
# Go to: Actions → App Store Release → Run workflow
# Enter version: 0.16.0

# Or use GitHub CLI
gh workflow run appstore-release.yml -f version=0.16.0

Step 7: Submit for Review

7.1 Add Build to Release

  1. Go to App Store Connect → Your App
  2. Click macOS App Store → + Version or select existing version
  3. Under Build, click + Add Build
  4. Select the build you just uploaded
  5. Wait for processing to complete (5-30 minutes)

7.2 Complete Required Information

App Review Information

  • Sign-in required: No (or provide test account if needed for PagerDuty)
  • Contact Information: Your email and phone
  • Notes: Include any setup instructions for reviewers

Example notes:

This is a menu bar app that monitors on-call alerts.

To test:
1. The app requires a PagerDuty account for full functionality
2. Test account credentials: [provide if needed]
3. The app icon appears in the menu bar at the top of the screen
4. Click the icon to see the menu

The app stores API tokens securely in macOS Keychain and makes
HTTPS requests to configured services.

Export Compliance

  • Does your app use encryption?: Yes (HTTPS)
  • Does it use standard encryption?: Yes
  • Usually qualifies for exemption (standard HTTPS encryption)

7.3 Submit for Review

  1. Review all information
  2. Click Add for Review or Submit for Review
  3. Answer any additional questions
  4. Submit!

7.4 Review Process

  • Typical timeframe: 1-3 days
  • Status tracking: App Store Connect shows current status
  • Notifications: You'll receive emails about status changes

Possible outcomes:

  • ✅ Approved: App goes live (or pending your release)
  • ⚠️ Metadata Rejected: Fix descriptions/screenshots and resubmit
  • ❌ Rejected: Address issues and resubmit with new build if needed

Step 8: Release

Once approved, you have options:

  1. Automatic Release: Goes live immediately upon approval
  2. Manual Release: You choose when to release
  3. Scheduled Release: Set a future date/time

Updating Your App

For future updates:

  1. Update version in Xcode project
  2. Build and upload new version (manually or via GitHub Actions)
  3. Create new version in App Store Connect
  4. Add "What's New" text
  5. Submit for review

Updates typically review faster than initial submissions.

Troubleshooting

Build Issues

Error: No matching provisioning profile

  • Ensure provisioning profile is installed
  • Check bundle ID matches exactly: ie.unicornops.oncallnotify
  • Verify profile hasn't expired

Error: Code signing failed

  • Check certificates are installed in Keychain
  • Verify certificate names match exactly
  • Try unlocking keychain: security unlock-keychain

Upload Issues

Error: Invalid package

  • Validate first with --validate-app
  • Check all entitlements are valid for App Store
  • Ensure no hardened runtime flags (not needed for App Store)

Error: Authentication failed

  • Verify Apple ID and app-specific password
  • Check team ID is correct
  • Try using API keys instead

Review Issues

Common rejection reasons:

  • Missing privacy policy
  • Incomplete app description
  • Screenshots don't show app functionality
  • App crashes on launch
  • Requires additional entitlements not declared

App Sandbox issues:

  • Test thoroughly with App Sandbox enabled
  • Keychain access works differently in sandbox
  • Network access requires entitlement (already added)

Testing Before Submission

TestFlight for Mac

  1. Upload build to App Store Connect
  2. Go to TestFlight tab
  3. Add internal testers (up to 100)
  4. Distribute for testing
  5. Get feedback before public release

App Sandbox Testing

Test locally with sandbox enabled:

# Build with sandbox entitlements
xcodebuild \
  -project OnCallNotify.xcodeproj \
  -scheme OnCallNotify \
  -configuration Release \
  CODE_SIGN_ENTITLEMENTS="OnCallNotify/OnCallNotify.AppStore.entitlements"

# Test the built app thoroughly
# Verify API calls work
# Verify Keychain access works
# Check all features function correctly

Checklist

Before submitting to App Store:

  • Apple Developer Program membership active
  • App created in App Store Connect
  • Certificates created and installed
  • Provisioning profile created and installed
  • GitHub secrets configured
  • Privacy policy published
  • App description written
  • Screenshots prepared (at least 3)
  • Keywords chosen
  • Support URL set
  • App tested with sandbox entitlements
  • Build uploaded successfully
  • Build processing completed
  • All App Store Connect fields completed
  • Export compliance answered
  • Review notes written (if needed)

Resources

Support

If you encounter issues:

  1. Check the App Store Connect Help
  2. Review the Apple Developer Forums
  3. Open an issue in the GitHub repository

Note: This guide is current as of January 2025. App Store Connect's interface and requirements may change over time.

Clone this wiki locally