From bda76d669d0081811cf306c8d82d8a5faa3258d4 Mon Sep 17 00:00:00 2001
From: Radek Simko <radek.simko@gmail.com>
Date: Tue, 14 Apr 2020 04:41:39 +0100
Subject: [PATCH] docs: Update signing section to reflect build hooks (#1439)

---
 www/content/sign.md | 58 ++++++++++++++++++++++++++++++---------------
 1 file changed, 39 insertions(+), 19 deletions(-)

diff --git a/www/content/sign.md b/www/content/sign.md
index 045a5411921..e114d379ac5 100644
--- a/www/content/sign.md
+++ b/www/content/sign.md
@@ -5,9 +5,13 @@ hideFromIndex: true
 weight: 60
 ---
 
-GoReleaser can sign some or all of the generated artifacts. Signing ensures
-that the artifacts have been generated by yourself and your users can verify
-that by comparing the generated signature with your public signing key.
+Signing ensures that the artifacts have been generated by yourself and your
+users can verify that by comparing the generated signature with your public
+signing key.
+
+GoReleaser provides means to sign both executables and archives.
+
+## Archives
 
 Signing works in combination with checksum files and it is generally sufficient
 to sign the checksum files only.
@@ -69,7 +73,7 @@ signs:
       - bar
 ```
 
-## Limitations
+### Limitations
 
 You can sign with any command that outputs a file.
 If what you want to use does not do it, you can always hack by setting the
@@ -89,9 +93,11 @@ And it will work just fine. Just make sure to always use the `${signature}`
 template variable as the result file name and `${artifact}` as the origin file.
 
 
-## Signing with gon
+## Executables
+
+Executables can be signed after build using post hooks.
 
-You can use [gon][] to create notarized macOS apps. Here's an example config:
+For example you can use [gon][] to create notarized MacOS apps:
 
 ```yaml
 builds:
@@ -102,27 +108,41 @@ builds:
   - windows
   goarch:
   - amd64
-# notice that we need a separated build for the macos binary only:
+
+# notice that we need a separated build for the MacOS binary only:
 - binary: foo
   id: foo-macos
   goos:
   - darwin
   goarch:
   - amd64
-signs:
-  - signature: "${artifact}.dmg"
-    ids:
-    - foo-macos # here we filter the macos only build id
-    # you'll need to have gon on PATH
-    cmd: gon
-    # you can follow the gon docs to properly create the gon.hcl config file:
-    # https://github.com/mitchellh/gon
-    args:
-    - gon.hcl
-    artifacts: all
+  hooks:
+    post: gon gon.hcl
 ```
+**`gon.hcl`:**
+```hcl
+# The path follows a pattern
+# ./dist/BUILD-ID_TARGET/BINARY-NAME
+source = ["./dist/foo-macos_darwin_amd64/foo"]
+bundle_id = "com.mitchellh.example.terraform"
+
+apple_id {
+  username = "mitchell@example.com"
+  password = "@env:AC_PASSWORD"
+}
+
+sign {
+  application_identity = "Developer ID Application: Mitchell Hashimoto"
+}
+```
+
+Note that notarizing may take some time, and will need to be run from a MacOS machine.
 
-Note that notarizing take some time, and will need to be run from a macOS machine.
+If you generate ZIP or DMG as part of your signing via gon you may need
+to ensure their file names align with desired pattern of other artifacts
+as GoReleaser doesn't control how these get generated beyond just executing `gon`
+with given arguments. Relatedly you may need to list these additional artifacts
+as `extra_files` in the `release` section to make sure they also get uploaded.
 
 You can also check [this issue](https://github.com/goreleaser/goreleaser/issues/1227) for more details.