How to upload to HockeyApp from Mac OS X

This article describes how to upload an app to HockeyApp from Mac OS X with the Mac OS X client application. You can also see the article on How to create a new app for alternate methods to upload an app via the Dashboard from a browser or via the HockeyApp API: Apps.

Introduction

HockeyApp for Mac is an app for OS X that allows to easily integrate HockeySDK for iOS or OS X into your project, upload a new build, view your latest unresolved crash reports, and even stay up to date with the latest HockeyApp news.

This document contains the following sections:

Prerequisites

  1. OS X 10.8 or later

  2. HockeyApp for Mac 2.0 or later

Installation

  1. Download the latest version of HockeyApp for Mac 2.0 here.

  2. Extract the .zip archive.

  3. Copy HockeyApp for Mac to your Application folder.

  4. Open HockeyApp for Mac.

  5. Log in with your HockeyApp user account.

  6. Open the app preferences

  7. Open the tab "General" and install the Helper app.

  8. Close the dialog and you're ready to go.

Integration With Xcode

  1. Open your project.

  2. Select Product > Edit Scheme.

  3. Expand Archive.

  4. Select Post-actions.

  5. Click the + in the lower left corner of the right pane and select New Run Script Action.

  6. Select your project for the build settings and enter the following command below:

    /usr/local/bin/puck "${ARCHIVE_PATH}"
    
  7. Confirm with OK.

If you now build your product with Build & Archive and the build was successful, the .xcarchive is automatically opened with HockeyApp for Mac. You can enter your release notes and then HockeyApp for Mac creates and uploads both the .ipa and the .dSYM file. Please note that you have to configure the correct provisioning profile for AdHoc distribution in the build configuration that you use for Build & Archive.

Command Line Helper / Options

HockeyApp for Mac version 2.0 comes with a new command line helper called puck. You can install the helper app through HockeyApp > Preferences > General > Helper: Install. In contrast to the old command line options, the new helper app is able to send the arguments to HockeyApp for Mac even if it's already running or even directly upload to the HockeyApp server. You can also use the Jenkins HockeyApp Plugin to manage your apps.

If you are using HockeyApp for Mac 1.5, please see here.

Invoke using: puck [options] <filename>

  • <filename> is the full path to the .xcarchive, .ipa or .apk package.

Options (default values are listed first):

  • -version - print version
  • -help - print complete usage

  • Symbols:

    • -dsym_path=<path> - absolute path to dsym.zip file (ignored if is .xcarchive)
    • -mapping_path=<path> - absolute path to mapping.txt file (only usable if is .apk)
  • SCM:

    • -commit_sha=<text> - commit SHA for this build
    • -build_server_url=<text> - the URL of the build job on your build server
    • -repository_url=<text> - your source repository URL
    • -source_path=<text> - absolute path to the source root. Used to automatically get the current commit SHA.
  • Release Notes:

    • -notes=<text> - release notes text (single line only!)
    • -notes_path=<path> - absolute path to release notes file
    • -collect_notes_type=<value from below> - auto generate release notes using:
    • jenkins_this_run - the commits from this jenkins run only
    • jenkins_aggregate - the commits from all jenkins builds since the last successful build
    • -collect_notes_path=<path> - absolute path to this jobs workspace, usually ${WORKSPACE}
    • -notes_type=textile|markdown - type of release notes
  • Build Settings:

    • -download=false|true - allow download
    • -mandatory=false|true - set as mandatory update
    • -notify=false|true - notify testers
    • -tags=<comma-separated string> - restrict version to tags
  • Upload:

    • -force=false|true - force upload even if version already exists
    • -upload=all|build|symbols - what to upload from an .xcarchive
    • -submit=manual|auto - set to auto to automatically start the upload (with app_id and api_token provided, uploads will be done standalone by puck and synchronously)
  • Action after finish:

    • -open=notify|download|version|nothing - desktop notification, open download or version page after upload was finished
  • Application:

    • -app_id=<id> - enforce HockeyApp App ID
    • -release_type=auto|alpha|beta|live - set release type if app is created
  • Account:

    • -hostname=<hostname> - custom server hostname
    • -api_token=<token> - custom API token

Example

The following example shows how we:

  • provide automated daily builds using Jenkins,
  • only build if there are actual new commits in the repository
  • automatically provide markdown formatted release notes using the text provided in all commits since the last build and
  • submit the Git commit sha to the server so the Mac client can view the crash reports source code without any further manual setup.

Full Jenkins shell script:

#!/bin/bash
ARCHIVE_DEST_PATH="${WORKSPACE}/archive"
ARCHIVE_PACKAGE="$ARCHIVE_DEST_PATH.xcarchive"

# Remove old archive
if [ -f "$ARCHIVE_PACKAGE/Info.plist" ]; then
    rm -r "$ARCHIVE_PACKAGE"
fi

# Check if we have any changes, otherwise don't build
if [ -s "${WORKSPACE}/../builds/${BUILD_NUMBER}/changelog.xml" ]; then

    # Patch the version string for the daily alpha build
    perl -pe '$build = ".$ENV{BUILD_NUMBER}";s/(BUILD_NUMBER = )(\d+)/$1.$2.$build/eg;' -i "${WORKSPACE}/Support/buildnumber.xcconfig"

    # Invoke the build
    xcodebuild -scheme 'HockeyApp Alpha' -archivePath "$ARCHIVE_DEST_PATH" archive

    # Upload to HockeyApp
    if [ -f "$ARCHIVE_PACKAGE/Info.plist" ]; then
    /usr/local/bin/puck -submit=auto -download=true -collect_notes_type=jenkins_aggregate -collect_notes_path="${WORKSPACE}" -notes_type=markdown -source_path="${WORKSPACE}" -repository_url=http://repository.server/repository-path -api_token=10101010101010101010101010101010 -app_id=01010101010101010101010101010101 "$ARCHIVE_PACKAGE"
    fi

    # Reset any temporary changes made above
    git reset --hard

else
    echo "Not building since there are no change commits."
fi

The values http://repository.server/repository-path for repository_url, 10101010101010101010101010101010 for api_token, and 01010101010101010101010101010101 for app_id are obviously placeholders :)

Legacy Information

Version 1.5

Options (default values listed first):

  • -help - print complete usage
  • -dsym_path=<path> - absolute path to dsym.zip file
  • -notes_path=<path> - absolute path to release notes file
  • -download=false|true - allow download
  • -mandatory=false|true - set as mandatory update
  • -notify=false|true - notify testers
  • -tags=<comma-separated string> - restrict version to tags
  • -release_type=auto|alpha|beta|live - set release type if app is created
  • -app_id=<id> - enforce HockeyApp App ID
  • -submit=manual|auto - set to manual to automatically start the upload
  • -force=false|true - force upload even if version already exists
  • -open=nothing|download|version - open download or version page after upload was finished
  • -api_token=<token> - custom API token

Example:

hoch -submit=auto -notify=true -open=download -tags=alphatesters,betatesters -app_id=4567abcd8901ef234567abcd8901ef23 MyApp.xcarchive

HockeyApp for Mac will automatically upload MyApp.ipa and MyApp.dSYM.zip from the archive and notify all testers.

Version 1.0-1.3

Previous versions (1.0 - 1.3) offered different command line options for the open command:

  • autoSubmit - the .ipa or .xcarchive will be automatically uploaded after it has been opened; you will see the progress bar, but not have the chance to specify release notes; after the upload is finished HockeyMac will be closed.
  • downloadOff - the checkbox "Download" will be set to off after the file was opened.
  • identifier - upload to app with this public identifier
  • notes - absolute path to release notes file
  • notifyOn - the checkbox "Notify" will be set to on after the file was opened.
  • onlyIPA - only for .xcarchive files; uploads only the .ipa file
  • onlyDSYM - only for .xcarchive files; uploads only the .dSYM.zip file
  • openNoPage - do nothing after upload was successful
  • openDownloadPage - open the download page after upload was successful
  • openVersionPage - open the version page after upload was successful
  • setAlpha - set release type to 'alpha'
  • setBeta - set release type to 'beta'
  • setLive - set release type to 'live'
  • tags - only allow users who are tagged by these tags to download the app (restrict downloads)
  • token - use this api token instead of the one configured in settings.

Please note that the command line options are passed to the app only at the first start. If the HockeyMac is already running, it will not consider any new arguments. In addition upload only tokens cause the app NOT to be downloadable and notifications will NOT be send.

Example:

open -a HockeyApp MyApp.xcarchive --args autoSubmit notifyOn openDownloadPage tags=alphatesters,betatesters identifier=4567abcd8901ef234567abcd8901ef23

HockeyMac will automatically upload MyApp.ipa and MyApp.dSYM.zip from the archive and notify all testers.