Building and Shipping
Verify your game across every target with nsgo check, configure metadata, icons and signing in nsgo.yaml, and build release packages for macOS, Windows, Linux, the web, iOS and Android with nsgo build.
Configure nsgo.yaml
nsgo build reads app identity, icons, signing and target defaults from nsgo.yaml at your project root. Every flag on nsgo build (-name, -id, -version, -build-number, -output, -target, -channel) overrides the matching setting in nsgo.yaml for one build.
name: My Game
id: com.example.mygame
version: 1.0.0
build_number: 1
copyright: "© 2026 Example Studio"
icon:
apple: assets/AppIcon.icon # Icon Composer .icon (macOS/iOS) or .icns (macOS)
png: assets/Icon.png # square PNG (1024x1024 recommended)
build:
output: dist
installers: true
targets:
- macos_arm64
- macos_x64
- windows_x64
- windows_arm64
- linux_x64
- linux_arm64
- web
- ios
- android_arm64
id: reverse-DNS bundle identifier / application ID (for examplecom.example.mygame). Keep it stable across releases; Apple App Store, Google Play and Microsoft Store key your app on it.version: user-facing semantic version (CFBundleShortVersionString, AndroidversionName).build_number: monotonically increasing integer for every store upload (CFBundleVersionon Apple platforms,versionCodeon Android). When omitted, it derives fromversion.resources/vsassets/: game files loaded at runtime ("asset:...") live inresources/and ship inside every package; build-time inputs such as icons live inassets/and are compiled into platform icon formats. Usemobile.exclude_resourcesinnsgo.yamlto omit desktop-only files from iOS and Android packages.
App icons
Place default icons in assets/ and nsgo build picks them up automatically without extra configuration:
assets/AppIcon.icon(Apple Icon Composer) orassets/AppIcon.icns(macOS only) for macOS and iOS.assets/Icon.png(a square PNG, 1024×1024 recommended) for Windows, Linux, Android, the web, and any Apple target withouticon.apple.
To distinguish development builds from releases, add -dev variants (assets/AppIcon-dev.icon, assets/Icon-dev.png) or set dev.icon; nsgo dev uses them automatically.
For desktop installers, you can also set macos.dmg_icon, macos.dmg_background (PNG with optional @2x twin), windows.installer_icon and windows.uninstaller_icon in nsgo.yaml.
Verify all targets before building
Check your host machine's toolchains first:
go tool nsgo doctor
Run nsgo check to vet your Go code (and any catalogs) across every target before building release packages:
go tool nsgo check -target all
Or check the 6 game platforms explicitly:
go tool nsgo check -target macos,windows,linux,web,ios,android
- Pass
-jobs Nto vet up toNtargets in parallel. - A bare OS name (
macos,windows,linux) expands to both itsarm64andx64architectures;androidexpands toandroid_arm64(android_x64requires an Android NDK). - On Linux or Windows hosts,
-target allskips Apple targets that require macOS and Xcode; namingiosexplicitly fails if Xcode is absent.
Run headless tests with go tool nsgo test, or run tests on a real platform with go tool nsgo test -target macos|windows|linux|web|ios_simulator|android.
Build release packages
nsgo build compiles stripped release binaries and writes one directory per target under <output>/<name>-<version>-<target>, plus distributable release files.
# Build every target configured in nsgo.yaml
go tool nsgo build
# Build all targets Go and Xcode can build on this machine
go tool nsgo build -target all
# Build store-formatted packages instead of direct installers
go tool nsgo build -channel store -target macos,windows,linux,ios,android
-channel chooses how packages are formatted and updated:
direct(default): direct-download installers and archives (.dmg, NSIS.exe,.deb/Arch/.AppImage,.apk,.ipa, web.zip).store: store submission packages (Mac App Store.pkg, Microsoft Store.msix, Flathub.tar.gz+ Flatpak manifest, Google Play.aab, iOS.ipa).none: skips auto-update feeds while keeping direct packaging.
Pass -installers=false if you only want the raw unpacked app directories on desktop targets. Pass -run to launch a built package immediately on this machine, a connected device, or a local web server.
Targets
| Platform | Target names | Direct build (-channel direct) |
Store build (-channel store) |
Host requirements |
|---|---|---|---|---|
| macOS | macos_arm64, macos_x64 (macos) |
.app + .dmg |
Sandboxed .pkg |
macOS for signing/notarization |
| Windows | windows_x64, windows_arm64 (windows) |
.exe bundle + NSIS installer |
.msix |
Any host (Go cross-compiles) |
| Linux | linux_x64, linux_arm64 (linux) |
Binary bundle + .deb, Arch pkg, .AppImage |
.tar.gz + AppStream + Flatpak manifest |
Any host (Go cross-compiles) |
| Web | web |
Static WebAssembly site + .zip |
Same static site | Any host |
| iOS | ios, ios_simulator |
.ipa |
.ipa |
macOS + Xcode |
| Android | android_arm64 (android), android_x64 |
.apk |
.aab |
Any host (android_x64 needs NDK) |
macOS
Build Apple Silicon, Intel, or both:
go tool nsgo build -target macos
- Code signing: without an identity, macOS apps are signed ad hoc (fine for local testing, rejected by Gatekeeper when downloaded). For direct distribution, pass a Developer ID Application certificate via
sign.identityor-sign:go tool nsgo build -target macos -sign "Developer ID Application: Example Studio (TEAMID)" - Notarization: to open on other Macs without Gatekeeper warnings, configure a keychain profile (
xcrun notarytool store-credentials) insign.notarizeor pass-notarize <profile>. In CI, set the App Store Connect API key environment variablesNSGO_NOTARY_KEY(path to.p8),NSGO_NOTARY_KEY_IDandNSGO_NOTARY_ISSUER.nsgo buildsubmits the.dmg(or zipped.app), waits for approval, and staples the ticket to both the.appand.dmg. - Mac App Store: set
macos.category(for examplepublic.app-category.games),sign.macos_profile(Mac App Store provisioning profile) and optionallysign.installer(Mac Installer Distribution identity), then build with-channel store:go tool nsgo build -channel store -target macosnsgo buildsigns the app in the App Sandbox and packages a.pkginstaller ready to upload via Transporter.
Windows
Build x64, ARM64, or both:
go tool nsgo build -target windows
- Direct distribution: produces the application directory and an NSIS setup installer (
-installers=true, default). Setwindows.publisherandcopyrightinnsgo.yamlto populate executable metadata and uninstall entries. - Code signing: sign executables and the installer to prevent SmartScreen warnings. Pass a PKCS#12
.pfxcertificate with-certificate(orsign.certificate) and provide its password inNSGO_CERTIFICATE_PASSWORD, plus an RFC 3161 timestamp server (-timestamp-url/sign.timestamp_url, defaults tohttp://timestamp.digicert.com):
For hardware tokens or cloud signing services, useNSGO_CERTIFICATE_PASSWORD="$PFX_PASSWORD" \ go tool nsgo build -target windows -certificate certs/win.pfx-sign-command(orsign.sign_command) where%1stands for each file path. - Microsoft Store: set
windows.store.identity,windows.store.publisher(CN=...) andwindows.store.publisher_namefrom Partner Center, then build with-channel storeto produce an.msixpackage (left unsigned so the Store signs it on publication):go tool nsgo build -channel store -target windows
Linux
Build x64, ARM64, or both:
go tool nsgo build -target linux
- Direct distribution: builds
.deb(Debian/Ubuntu), Arch packages and.AppImagebundles. Configure desktop metadata innsgo.yaml:
Add extra runtime dependencies withlinux: categories: [Game] maintainer: "Example Studio <games@example.com>" summary: "A 2D adventure game" license: MITlinux.dependsandlinux.recommendsif your game ships helper binaries. - Flathub / Flatpak: build with
-channel storeto emit.tar.gzarchives containing<id>.metainfo.xmlAppStream metadata and aflatpak/<id>.ymlmanifest targeting the GNOME runtime (linux.flatpak_runtimeoverrides the default runtime version). Submit the manifest to Flathub or build locally withflatpak-builder.
The web
Build the static WebAssembly bundle:
go tool nsgo build -target web
Test the production build locally before deploying:
go tool nsgo build -target web -run
dist/<name>-<version>-web/ contains the HTML, JS, WebAssembly binary and resources/ files, and nsgo build also writes a .zip archive in the releases directory. Upload the directory contents to any static host (GitHub Pages, Cloudflare Pages, Netlify, itch.io, or S3). Remember that browsers gate audio behind the first user gesture (see sound).
iOS
Requires macOS with Xcode installed. Build for physical devices (.ipa) or the simulator:
go tool nsgo build -target ios
go tool nsgo build -target ios_simulator
- Signing: provide an App Store, Ad Hoc or Development provisioning profile matching
idviasign.profile(or-profile).nsgo buildautomatically selects the matching signing identity from your keychain, or you can specify it explicitly withsign.identity(or-sign). - Store submission:
- Upload
<name>.ipato App Store Connect / TestFlight with Apple's Transporter app or Xcode. - Increment
build_number(CFBundleVersion) for every upload. - Configure iPad multitasking and screen orientations with
apple.requires_full_screenandapple.orientations(portrait,portrait_upside_down,landscape_left,landscape_right), and add any requiredInfo.plistentries underapple.info.
- Upload
Android
Build ARM64 (needs only Go — CGO_ENABLED=0, no Android SDK or NDK required):
go tool nsgo build -target android_arm64
To also build android_x64 (for x86_64 emulators or Chromebooks), install an Android NDK and pass -target android_arm64,android_x64.
- Signing: configure a PKCS#12 or JKS keystore via
sign.keystore(or-keystore) andsign.key_alias(or-key-alias). Never commit passwords tonsgo.yaml; pass them via environment variables:
Without a keystore,NSGO_KEYSTORE_PASSWORD="$STORE_PW" NSGO_KEY_PASSWORD="$KEY_PW" \ go tool nsgo build -channel store -target android_arm64 \ -keystore certs/upload.p12 -key-alias uploadnsgo buildsigns APKs with the project's debug key (for sideloading only, rejected by Google Play). - Google Play: build with
-channel storeto produce a signed.aab(Android App Bundle) for Google Play Console. Incrementbuild_number(versionCode) on every upload, setandroid.target_sdkto Google Play's current required API level (minSdkVersionis 28), and declare any extra permissions underandroid.permissions.