{"id":13600986,"url":"https://github.com/mitchellh/gon","last_synced_at":"2025-09-29T00:32:11.041Z","repository":{"id":37908280,"uuid":"218877889","full_name":"mitchellh/gon","owner":"mitchellh","description":"Sign, notarize, and package macOS CLI tools and applications written in any language. Available as both a CLI and a Go library.","archived":true,"fork":false,"pushed_at":"2023-10-31T20:48:52.000Z","size":5715,"stargazers_count":1480,"open_issues_count":36,"forks_count":97,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-01-11T06:45:37.074Z","etag":null,"topics":["build-tool","golang","macos","notary"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mitchellh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-31T23:27:31.000Z","updated_at":"2025-01-08T22:51:49.000Z","dependencies_parsed_at":"2023-01-21T12:33:52.941Z","dependency_job_id":"f3d8a7ac-46d5-4b38-9acb-78271de00191","html_url":"https://github.com/mitchellh/gon","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitchellh%2Fgon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitchellh%2Fgon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitchellh%2Fgon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitchellh%2Fgon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mitchellh","download_url":"https://codeload.github.com/mitchellh/gon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234575225,"owners_count":18854925,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["build-tool","golang","macos","notary"],"created_at":"2024-08-01T18:00:51.897Z","updated_at":"2025-09-29T00:32:05.665Z","avatar_url":"https://github.com/mitchellh.png","language":"Go","readme":"**Archived:** I unfortunately no longer make active use of this project\nand haven't properly maintained it since early 2022. I welcome anyone to\nfork and take over this project. \n\n-----------------------------------------------------\n\n# gon - CLI and Go Library for macOS Notarization\n\ngon is a simple, no-frills tool for\n[signing and notarizing](https://developer.apple.com/developer-id/)\nyour CLI binaries for macOS. gon is available as a CLI that can be run\nmanually or in automation pipelines. It is also available as a Go library for\nembedding in projects written in Go. gon can sign and notarize binaries written\nin any language.\n\nBeginning with macOS Catalina (10.15), Apple is\n[requiring all software distributed outside of the Mac App Store to be signed and notarized](https://developer.apple.com/news/?id=10032019a).\nSoftware that isn't properly signed or notarized will be shown an\n[error message](https://github.com/hashicorp/terraform/issues/23033)\nwith the only actionable option being to \"Move to Bin\". The software cannot\nbe run even from the command-line. The\n[workarounds are painful for users](https://github.com/hashicorp/terraform/issues/23033#issuecomment-542302933).\ngon helps you automate the process of notarization.\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\n- [Features](#features)\n- [Example](#example)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Prerequisite: Acquiring a Developer ID Certificate](#prerequisite-acquiring-a-developer-id-certificate)\n  - [Configuration File](#configuration-file)\n  - [Notarization-Only Configuration](#notarization-only-configuration)\n  - [Processing Time](#processing-time)\n  - [Using within Automation](#using-within-automation)\n    - [Machine-Readable Output](#machine-readable-output)\n    - [Prompts](#prompts)\n- [Usage with GoReleaser](#usage-with-goreleaser)\n- [Go Library](#go-library)\n- [Troubleshooting](#troubleshooting)\n- [Roadmap](#roadmap)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\n## Features\n\n  * Code sign one or multiple files written in any language\n  * Package signed files into a dmg or zip\n  * Notarize packages and wait for the notarization to complete\n  * Concurrent notarization for multiple output formats\n  * Stapling notarization tickets to supported formats (dmg) so that\n    Gatekeeper validation works offline.\n\nSee [roadmap](#roadmap) for features that we want to support but don't yet.\n\n## Example\n\nThe example below runs `gon` against itself to generate a zip and dmg.\n\n![gon Example](https://user-images.githubusercontent.com/1299/68089803-66961b00-fe21-11e9-820e-cfd7ecae93a2.gif)\n\n## Installation\n\nThe easiest way to install `gon` is via [Homebrew](https://brew.sh):\n\n    $ brew install mitchellh/gon/gon\n\nYou may also download the appropriate release for your platform\nfrom the [releases page](https://github.com/mitchellh/gon/releases).\nThese are all signed and notarized to run out of the box on macOS 10.15+.\n\nYou can also compile from source using Go 1.13 or later using standard\n`go build`. Please ensure that Go modules are enabled.\n\n## Usage\n\n`gon` requires a configuration file that can be specified as a file path\nor passed in via stdin.  The configuration specifies\nall the settings `gon` will use to sign and package your files.\n\n**gon must be run on a macOS machine with XCode 11.0 or later.** Code\nsigning, notarization, and packaging all require tools that are only available\non macOS machines.\n\n```\n$ gon [flags] [CONFIG]\n```\n\nWhen executed, `gon` will sign, package, and notarize configured files\ninto requested formats. `gon` will exit with a `0` exit code on success\nand any other value on failure.\n\n### Prerequisite: Acquiring a Developer ID Certificate\n\nBefore using `gon`, you must acquire a Developer ID Certificate. To do\nthis, you can either do it via the web or via Xcode locally on a Mac. Using\nXcode is easier if you already have it installed.\n\nVia the web:\n\n  1. Sign into [developer.apple.com](https://developer.apple.com) with valid\n     Apple ID credentials. You may need to sign up for an Apple developer account.\n\n  2. Navigate to the [certificates](https://developer.apple.com/account/resources/certificates/list)\n     page.\n\n  3. Click the \"+\" icon, select \"Developer ID Application\" and follow the steps.\n\n  4. After downloading the certificate, double-click to import it into your\n     keychain. If you're building on a CI machine, every CI machine must have\n     this certificate in their keychain.\n\nVia Xcode:\n\n  1. Open Xcode and go to Xcode =\u003e Preferences =\u003e Accounts\n\n  2. Click the \"+\" in the bottom left and add your Apple ID if you haven't already.\n\n  3. Select your Apple account and click \"Manage Certificates\" in the bottom\n     right corner.\n\n  4. Click \"+\" in the bottom left corner and click \"Developer ID Application\".\n\n  5. Right-click the newly created cert in the list, click \"export\" and\n     export the file as a p12-formatted certificate. _Save this somewhere_.\n     You'll never be able to download it again.\n\nTo verify you did this correctly, you can inspect your keychain:\n\n```sh\n$ security find-identity -v\n  1) 97E4A93EAA8BAC7A8FD2383BFA459D2898100E56 \"Developer ID Application: Mitchell Hashimoto (GK79KXBF4F)\"\n     1 valid identities found\n```\n\nYou should see one or more certificates and at least one should be your\nDeveloper ID Application certificate. The hexadecimal string prefix is the\nvalue you can use in your configuration file to specify the identity.\n\n### Configuration File\n\nThe configuration file can specify allow/deny lists of licenses for reports,\nlicense overrides for specific dependencies, and more. The configuration file\nformat is [HCL](https://github.com/hashicorp/hcl/tree/hcl2) or JSON.\n\nExample:\n\n```hcl\nsource = [\"./terraform\"]\nbundle_id = \"com.mitchellh.example.terraform\"\n\napple_id {\n  username = \"mitchell@example.com\"\n  password = \"@env:AC_PASSWORD\"\n  provider = \"UL304B4VGY\"\n}\n\nsign {\n  application_identity = \"Developer ID Application: Mitchell Hashimoto\"\n}\n\ndmg {\n  output_path = \"terraform.dmg\"\n  volume_name = \"Terraform\"\n}\n\nzip {\n  output_path = \"terraform.zip\"\n}\n```\n\n```json\n{\n    \"source\" : [\"./terraform\"],\n    \"bundle_id\" : \"com.mitchellh.example.terraform\",\n    \"apple_id\": {\n        \"username\" : \"mitchell@example.com\",\n        \"password\":  \"@env:AC_PASSWORD\",\n        \"provider\":  \"UL304B4VGY\"\n    },\n    \"sign\" :{\n        \"application_identity\" : \"Developer ID Application: Mitchell Hashimoto\"\n    },\n    \"dmg\" :{\n        \"output_path\":  \"terraform.dmg\",\n        \"volume_name\":  \"Terraform\"\n    },\n    \"zip\" :{\n        \"output_path\" : \"terraform.zip\"\n    }\n}\n```\n\nSupported configurations:\n\n  * `source` (`array\u003cstring\u003e`) - A list of files to sign, package, and\n    notarize. If you want to sign multiple files with different identities\n    or into different packages, then you should invoke `gon` with separate\n    configurations. This is optional if you're using the notarization-only\n\tmode with the `notarize` block.\n\n  * `bundle_id` (`string`) - The [bundle ID](https://cocoacasts.com/what-are-app-ids-and-bundle-identifiers/)\n    for your application. You should choose something unique for your application.\n    You can also [register these with Apple](https://developer.apple.com/account/resources/identifiers/list).\n    This is optional if you're using the notarization-only\n\tmode with the `notarize` block.\n\n  * `apple_id` - Settings related to the Apple ID to use for notarization.\n\n    * `username` (`string`) - The Apple ID username, typically an email address.\n      This will default to the `AC_USERNAME` environment variable if not set.\n\n    * `password` (`string`) - The password for the associated Apple ID. This can be\n      specified directly or using `@keychain:\u003cname\u003e` or `@env:\u003cname\u003e` to avoid\n      putting the plaintext password directly in a configuration file. The `@keychain:\u003cname\u003e`\n      syntax will load the password from the macOS Keychain with the given name.\n      The `@env:\u003cname\u003e` syntax will load the password from the named environmental\n      variable. If this value isn't set, we'll attempt to use the `AC_PASSWORD`\n      environment variable as a default.\n      \n      **NOTE**: If you have 2FA enabled, the password must be an application password, not\n      your normal apple id password. See [Troubleshooting](#troubleshooting) for details.\n\n    * `provider` (`string`) - The App Store Connect provider when using\n      multiple teams within App Store Connect. If this isn't set, we'll attempt\n      to read the `AC_PROVIDER` environment variable as a default.\n\n  * `sign` - Settings related to signing files.\n\n    * `application_identity` (`string`) - The name or ID of the \"Developer ID Application\"\n      certificate to use to sign applications. This accepts any valid value for the `-s`\n      flag for the `codesign` binary on macOS. See `man codesign` for detailed\n      documentation on accepted values.\n\n    * `entitlements_file` (`string` _optional_) - The full path to a plist format .entitlements file, used for the `--entitlements` argument to `codesign`\n\n  * `dmg` (_optional_) - Settings related to creating a disk image (dmg) as output.\n    This will only be created if this is specified. The dmg will also have the\n    notarization ticket stapled so that it can be verified offline and\n    _do not_ require internet to use.\n\n    * `output_path` (`string`) - The path to create the zip archive. If this path\n      already exists, it will be overwritten. All files in `source` will be copied\n      into the root of the zip archive.\n\n    * `volume_name` (`string`) - The name of the mounted dmg that shows up\n      in finder, the mounted file path, etc.\n\n  * `zip` (_optional_) - Settings related to creating a zip archive as output. A zip archive\n    will only be created if this is specified. Note that zip archives don't support\n    stapling, meaning that files within the notarized zip archive will require an\n    internet connection to verify on first use.\n\n    * `output_path` (`string`) - The path to create the zip archive. If this path\n      already exists, it will be overwritten. All files in `source` will be copied\n      into the root of the zip archive.\n\nNotarization-only mode:\n\n  * `notarize` (_optional_) - Settings for notarizing already built files.\n    This is an alternative to using the `source` option. This option can be\n    repeated to notarize multiple files.\n\n    * `path` (`string`) - The path to the file to notarize. This must be\n      one of Apple's supported file types for notarization: dmg, pkg, app, or\n      zip.\n\n    * `bundle_id` (`string`) - The bundle ID to use for this notarization.\n      This is used instead of the top-level `bundle_id` (which controls the\n      value for source-based runs).\n\n    * `staple` (`bool` _optional_) - Controls if `stapler staple` should run\n      if notarization succeeds. This should only be set for filetypes that\n      support it (dmg, pkg, or app).\n\n\n### Notarization-Only Configuration\n\nYou can configure `gon` to notarize already-signed files. This is useful\nif you're integrating `gon` into an existing build pipeline that may already\nsupport creation of pkg, app, etc. files.\n\nBecause notarization requires the payload of packages to also be signed, this\nmode assumes that you have codesigned the payload as well as the package\nitself. `gon` _will not_ sign your package in the `notarize` blocks.\nPlease do not confuse this with when `source` is set and `gon` itself\n_creates_ your packages, in which case it will also sign them.\n\nYou can use this in addition to specifying `source` as well. In this case,\nwe will codesign \u0026 package the files specified in `source` and then notarize\nthose results as well as those in `notarize` blocks.\n\nExample in HCL and then the identical configuration in JSON:\n\n```hcl\nnotarize {\n  path = \"/path/to/terraform.pkg\"\n  bundle_id = \"com.mitchellh.example.terraform\"\n  staple = true\n}\n\napple_id {\n  username = \"mitchell@example.com\"\n  password = \"@env:AC_PASSWORD\"\n}\n```\n\n```json\n{\n  \"notarize\": [{\n    \"path\": \"/path/to/terraform.pkg\",\n    \"bundle_id\": \"com.mitchellh.example.terraform\",\n    \"staple\": true\n  }],\n\n  \"apple_id\": {\n     \"username\": \"mitchell@example.com\",\n     \"password\": \"@env:AC_PASSWORD\"\n  }\n}\n```\n\nNote you may specify multiple `notarize` blocks to notarize multipel files\nconcurrently.\n\n### Processing Time\n\nThe notarization process requires submitting your package(s) to Apple\nand waiting for them to scan them. Apple provides no public SLA as far as I\ncan tell.\n\nIn developing `gon` and working with the notarization process, I've\nfound the process to be fast on average (\u003c 10 minutes) but in some cases\nnotarization requests have been queued for an hour or more.\n\n`gon` will output status updates as it goes, and will wait indefinitely\nfor notarization to complete. If `gon` is interrupted, you can check the\nstatus of a request yourself using the request UUID that `gon` outputs\nafter submission.\n\n### Using within Automation\n\n`gon` is built to support running within automated environments such\nas CI pipelines. In this environment, you should use JSON configuration\nfiles with `gon` and the `-log-json` flag to get structured logging\noutput.\n\n#### Machine-Readable Output\n\n`gon` always outputs human-readable output on stdout (including errors)\nand all log output on stderr. By specifying `-log-json` the log entries\nwill be structured with JSON. You can process the stream of JSON using\na tool such as `jq` or any scripting language to extract critical information\nsuch as the request UUID, status, and more.\n\nWhen `gon` is run in an environment with no TTY, the human output will\nnot be colored. This makes it friendlier for output logs.\n\nExample:\n\n    $ gon -log-level=info -log-json ./config.hcl\n\t...\n\n**Note you must specify _both_ `-log-level` and `-log-json`.** The\n`-log-level` flag enables logging in general. An `info` level is enough\nin automation environments to get all the information you'd want.\n\n#### Prompts\n\nOn first-run may be prompted multiple times for passwords. If you\nclick \"Always Allow\" then you will not be prompted again. These prompts\nare originating from Apple software that `gon` is subprocessing, and not\nfrom `gon` itself.\n\nI do not currently know how to script the approvals, so the recommendation\non build machines is to run `gon` manually once. If anyone finds a way to\nautomate this please open an issue, let me know, and I'll update this README.\n\n## Usage with GoReleaser\n\n[GoReleaser](https://goreleaser.com) is a popular full featured release\nautomation tool for Go-based projects. Gon can be used with GoReleaser to\naugment the signing step to notarize your binaries as part of a GoReleaser\npipeline.\n\nHere is an example GoReleaser configuration to sign your binaries:\n\n```yaml\nbuilds:\n- binary: foo\n  id: foo\n  goos:\n  - linux\n  - windows\n  goarch:\n  - amd64\n# notice that we need a separated build for the macos binary only:\n- binary: foo\n  id: foo-macos\n  goos:\n  - darwin\n  goarch:\n  - amd64\nsigns:\n  - signature: \"${artifact}.dmg\"\n    ids:\n    - foo-macos # here we filter the macos only build id\n    # you'll need to have gon on PATH\n    cmd: gon\n    # you can follow the gon docs to properly create the gon.hcl config file:\n    # https://github.com/mitchellh/gon\n    args:\n    - gon.hcl\n    artifacts: all\n```\n\nTo learn more, see the [GoReleaser documentation](https://goreleaser.com/customization/#Signing).\n\n## Go Library\n\n[![Godoc](https://godoc.org/github.com/mitchellh/gon?status.svg)](https://godoc.org/github.com/mitchellh/gon)\n\nWe also expose a supported API for signing, packaging, and notarizing\nfiles using the Go programming language. Please see the linked Go documentation\nfor more details.\n\nThe libraries exposed are purposely lower level and separate out the sign,\npackage, notarization, and stapling steps. This lets you integrate this\nfunctionality into any tooling easily vs. having an opinionated `gon`-CLI\nexperience.\n\n## Troubleshooting\n\n### \"We are unable to create an authentication session. (-22016)\"\n\nYou likely have Apple 2FA enabled. You'll need to [generate an application password](https://appleid.apple.com/account/manage) and use that instead of your Apple ID password.\n\n## Roadmap\n\nThese are some things I'd love to see but aren't currently implemented.\n\n  * Expose more DMG customization so you can set backgrounds, icons, etc.\n    - The underlying script we use already supports this.\n  * Support adding additional files to the zip, dmg packages\n  * Support the creation of '.app' bundles for CLI applications\n","funding_links":[],"categories":["开源类库","Go","Open source library"],"sub_categories":["桌面开发","Desktop Development"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitchellh%2Fgon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmitchellh%2Fgon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitchellh%2Fgon/lists"}