Installing and Updating

Which download do you want?

Every release is published on the GHManage releases page. Take the first file listed for your computer unless you have a reason not to.

File Use it if
GHManage-win-Setup.exe Windows. Installs GHManage and keeps it up to date.
GHManage-win-Portable.zip Windows, when you want a folder you can run from anywhere. Nothing is installed, and it never updates itself.
GHManage-osx.dmg Mac. Open it and drag GHManage to Applications.
GHManage-osx-Portable.zip Mac, when you would rather unzip the app yourself. It contains the same app as the DMG.

The other files on the release page (*.nupkg, RELEASES, releases.win.json, assets.win.json, releases.osx.json, assets.osx.json) are the update feed the installed app reads. You never need to download them.

Installing on Windows

Run GHManage-win-Setup.exe. It installs for your user account only, into %LocalAppData%\GHManage, so there is no administrator prompt. A Start menu shortcut is added, and GHManage starts when setup finishes.

Releases are signed, so Windows knows who published them and SmartScreen does not warn about an unknown publisher.

Installing on a Mac

Open GHManage-osx.dmg and move GHManage to Applications. The app is signed and notarized by Apple, so Gatekeeper opens it without complaint.

You can keep the app anywhere, not just in Applications: a Mac app carries its own updater inside it, so it keeps updating wherever it lives.

How updating works

Installed copies of GHManage, on Windows and on the Mac, keep themselves up to date. A couple of seconds after GHManage starts it checks for a newer release in the background. If it finds one, it downloads it quietly and the status bar says:

“GHManage 1.2.3 downloaded — it will be installed next time you start GHManage.”

Nothing interrupts you and nothing restarts on its own. The next time you start GHManage, the new version is the one that opens.

That message is replaced by the next thing GHManage tells you, so the update also gets an item of its own on the status bar, GHManage 1.2.3 ready to install, which stays there until you restart. Press F6 until you reach the status bar, arrow to that item, and press Enter or Space. The Update Available dialog offers Restart Now to install immediately, and Later to leave it for your next start. See The status bar for moving around the bar.

To check by hand, choose Help → Check for Updates…. It always answers: either “GHManage 1.2.3 is up to date”, or the Update Available dialog.

An update never touches your favorites, the repositories you opened by address, or anything else you have set up.

The portable versions

The portable zips are complete copies of GHManage that run from any folder and write nothing outside it except your settings. They cannot update themselves. Help → Check for Updates… in a portable copy says so: “GHManage is running as a portable copy, which cannot update itself.” To update a portable copy, download the new zip and replace the old folder.

Where your settings live

Favorites, the repositories you opened by address, and your other settings are small files in a ghmanage folder: %APPDATA%\ghmanage on Windows and ~/.config/ghmanage on the Mac. Installed and portable copies share them. GHManage never stores GitHub credentials; those belong to gh.

If updates ever misbehave, the update log is %APPDATA%\GHManage\ghmanage-update.log on Windows and ~/Library/Logs/GHManage/ghmanage-update.log on the Mac. Attaching it to a bug report helps.

Running from source

If you would rather run the Python source, you need Python 3.9 or later. From a copy of the repository:

pip install -r requirements.txt
python ghviewer.py

Three command-line options work in every copy, installed or not:

Option What it does
--repo OWNER/NAME Opens that repository straight away instead of starting on the repository list.
--version Prints the version and exits.
--debug Writes more detail to the update log.

For example, to start GHManage on the issues of NVDA’s repository, nvaccess/nvda:

Options can be combined, so --repo nvaccess/nvda --debug does both.