From bd7b295651281e6b684e0fc6992586535a51d901 Mon Sep 17 00:00:00 2001
From: Gerd Aschemann <gerd@aschemann.net>
Date: Thu, 8 Aug 2024 11:41:19 +0200
Subject: [PATCH] Add GPG agent configuration

---
 build.gradle                         |  3 ++
 src/docs/development/publishing.adoc | 57 +++++++++++++++++++++++++---
 2 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/build.gradle b/build.gradle
index a7e3e10b..fe338130 100644
--- a/build.gradle
+++ b/build.gradle
@@ -199,6 +199,9 @@ configure(subprojects) {
 
     signing {
         required = { project.hasProperty('enableSigning') && project.property('enableSigning') == 'true' }
+        if (project.hasProperty('useGpgCmd') && project.property('useGpgCmd') == 'true') {
+            useGpgCmd()
+        }
         sign publishing.publications
     }
 }
diff --git a/src/docs/development/publishing.adoc b/src/docs/development/publishing.adoc
index ec0ca9ff..a30969ed 100644
--- a/src/docs/development/publishing.adoc
+++ b/src/docs/development/publishing.adoc
@@ -29,6 +29,7 @@ Additionally, you need to create https://central.sonatype.org/publish/generate-p
 ===== Artifact signing
 
 To successfully upload artifacts and other files (POM etc.), a valid PGP signature is required.
+A proper GPG (agent) setup is beyond the scope of this tutorial.
 Therefore, you need to set up GnuPG in your local `+${HOME}/.gradle/gradle.properties+`,
 according to the https://docs.gradle.org/current/userguide/signing_plugin.html#sec:signatory_credentials[Gradle Signatory documentation].
 
@@ -36,18 +37,53 @@ Add the following entries:
 
 [source,properties]
 ----
-signing.keyId=24875D73
-signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg <1>
-signing.password=<SECRET> # <2>
+signing.keyId=24875D73 <1>
+signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg <2>
+signing.password=<SECRET> # <3>
 ----
-<1> Note that you need to specify the literal path to your home directory; it is not possible to refer to system properties like `+${user.home}+` here.
-<2> Instead of putting the clear text password into the file, you should  provide it on the command line when calling Gradle
+<1> You have to provide the id of your key (of course).
+<2> Note that you need to specify the literal path to your home directory; it is not possible to refer to system properties like `+${user.home}+` here.
+<3> Instead of putting the clear text password into the file, you should  provide it on the command line when calling Gradle
 +
 [source,shell]
 ----
 ./gradlew -Psigning.password=... <task>
 ----
 
+[[tip:gpg-agent]]
+[TIP]
+.Use GPG Agent
+====
+Alternatively,
+you may use the https://linux.die.net/man/1/gpg-agent[GPG Agent] of your https://gnupg.org/[GnuPG] installation
+to cache the secret in memory,
+thereby reducing the risk of accidentally exposing the clear text passphrase in your command line or environment.
+
+You can make use of it by setting the flag `useGpgCmd` to `true`:
+
+[source,shell]
+----
+./gradlew -PuseGpgCmd=true <task>
+----
+
+Note that the (native) `gpg` command is used in background and that it cannot request the passphrase when executed.
+This may lead to errors like
+
+[source]
+----
+gpg: Sorry, we are in batchmode - can't get input
+
+FAILURE: Build failed with an exception.
+----
+
+In this case, you have to make sure the agent is started and the password is cached, e.g., by executing
+
+[source,shell]
+----
+echo empty | gpg --clearsign -o /dev/null
+----
+====
+
 ==== Publishing actions
 
 Adjust version number::
@@ -76,6 +112,17 @@ The `jreleaserDeploy` task will implicitly call the task `signAll` which signs
 and pushes all required files for publication to a local repository.
 JReleaser picks them up from there and loads them up to the Maven Central staging area as a new version.
 
+[TIP]
+.Use GPG Agent (command) in practice
+====
+If you have GPG configured properly, you may use the <<tip:gpg-agent,GPG-Agent>>.
+
+[source,bash,subs="callouts+"]
+----
+./gradlew jreleaserDeploy -PenableSigning=true -PuseGpgCmd=true
+----
+====
+
 Publish on Maven Central::
 Finally, publish the staged version on Maven Central,
 i.e., https://central.sonatype.com/publishing[Sonatype Central].