help/publishing.txt - lucene - Git at Google

 Distribution and artifact publishing
 ====================================


 See all distribution-related tasks by running:
 gradlew tasks --group distribution


 Maven
 -----

 To publish Lucene Maven artifacts to a local ~/.m2 repository, run:

 gradlew mavenToLocal

 To publish Lucene Maven artifacts to Apache repositories
 (CI or release manager's job, typically!), run:

 gradlew mavenToApacheSnapshots -PasfNexusUsername= -PasfNexusPassword=
 gradlew mavenToApacheReleases  -PasfNexusUsername= -PasfNexusPassword= [optional signing options]

 See artifact signing section below if you plan to use mavenToApacheReleases.

 It is a good idea to avoid passing passwords on command line. CI jobs have
 these properties saved in ~/.gradle/gradle.properties - this way they
 are read automatically.

 Apache Releases repository will not accept snapshots.


 Release (distribution) artifacts
 --------------------------------

 To collect all release artifacts, and optionally sign them, run:

 gradlew assembleRelease [optional signing options]

 All distribution artifacts will be placed under:

 lucene/distribution/build/release

 Artifact signing is optional (but required if you're really making a release).


 Artifact signing
 ----------------

 Certain tasks may optionally sign artifacts or require artifacts to be signed:

  assembleRelease
  mavenToApacheReleases

 Signing can be enabled by adding the "-Psign" option, for example:

 gradlew assembleRelease mavenToApacheReleases -Psign

 By default gradle uses a Java-based implementation of PGP for signing, which requieres
 several "signing.*" properties via either ~/.gradle/gradle.properties or command-line options:

 https://docs.gradle.org/current/userguide/signing_plugin.html#sec:signatory_credentials

 An example full command-line that assembles signed artifacts could look like this:

 gradlew assembleRelease mavenToApacheReleases -Psign -Psigning.keyId=... -Psigning.password=... -Psigning.secretKeyRingFile=...

 The keyId is the last 8 digits of your key (gpg -k will print your keys). Gradle documentation has more options
 of secure passing of private key information and passwords.


 Artifact signing using an external GPG with GPG Agent
 -----------------------------------------------------

 You can use an external GPG command to deal with signing artifacts, with out needing to give gradle your passphrase,
 by adding a "-PuseGpg" option, but this changes the properties you must specify:

 For gpg2:
 gradlew [tasks] -Psign -PuseGpg -Psigning.gnupg.keyName=...

 For gpg:
 gradlew [tasks] -Psign -PuseGpg -Psigning.gnupg.keyName=... -Psigning.gnupg.useLegacyGpg=true

 The keyName is the last 8 digits of your key (gpg -k will print your keys).

 There are additional (optional) "signing.gnupg.*" properties which exist that may be useful/necessary in your system:

 signing.gnupg.useLegacyGpg=true                    # Changes the default executable from `gpg2` to `gpg` and explicitly sets `--use-agent`
 signing.gnupg.executable=gpg                       # Allows explicit control over what command executable used (ex: `gpg2`, `gpg`, `gpg.exe`, etc...)
 signing.gnupg.homeDir=/tmp/gnupg-home              # overrides GnuPG's default home directory (ex: `~/.gnupg/`)
 signing.gnupg.optionsFile=/tmp/gnupg-home/my.conf  # overrides GnuPG's default configuration file
 signing.gnupg.passphrase=...                       # Provide your passphrase to gradle to hand off to gpg.  *NOT RECOMMENDED*, see below.

 If in doubt, consult gradle's signing plugin documentation:
 https://docs.gradle.org/current/userguide/signing_plugin.html#sec:using_gpg_agent

 "signing.gnupg.passphrase" is not recomended because there is no advantage to using an external GPG process if you use it.  If you
 are comfortable giving gradle your passphrase, then there is no reason to use an external GPG process via '-PuseGpg'.   Just use the
 "signing.*" options described previuosly to let gradle deal with your key directly.

 Because of how Gradle's signing plugin invokes GPG, using an external GPG process *only* works if your GPG configuration uses a
 GPG agent (required by gpg2) and if the "pinentry" for your GPG agent does not require access to the tty to prompt you for a password.

 If you the following command fails with your GPG configuration, you can not use an external GPG process with gradle:

 echo foo | gpg --batch --no-tty --armor --detach-sign --use-agent --local-user YOUR_KEY_NAME


 Notes About GPG Error Messages
 ------------------------------

 ### `gpg: signing failed: Inappropriate ioctl for device` or `Invalid IPC response`

 This typically happens if your `gpg-agent` is configured (either globally for your operating system, or personally in your
 `~/.gnupg/gpg-agent.conf`) to use a `pinentry` command which depends on using the same `tty` as the `gpg` command (ex: `pinentry-curses`,
 or `pinentry-tty`, etc...).

 `tty` based `pinentry` implementations do not work when Gradle's signing plugin is attempting to invoke `gpg` -- among other problems:
 Gradle is multi-threaded and we sign multiple artifacts by default.  Even if you use "--max-workers 1" to force single-threaded execution,
 the signing plugin invokes gpg with `--batch --no-tty`, making it impossible for gpg (or a tty based pinentry) to prompt you for your passphrase
 in the same terminal where you run Gradle.

 Developers are encouraged to configure a *non* `tty` based `pinentry` (ex: `pinentry-gnome`, `pinentry-x11`, `pinentry-qt`, `pinentry-mac`,
 `pinentry-wsl-ps1`, etc...) either globally in your operating system, or personally in your `~/.gnupg/gpg-agent.conf`, or in a new
 `gpg-agent.conf` file a new GnuPG configuration directory (containing a copy of your private keys) that you direct gradle to via
 `signing.gnupg.homeDir`

 If this is not possible, then you should avoid using an external GPG process, and use the default (pure java) Artifact signing support


 ### `gpg: signing failed: No such file or directory`

 This may mean that there is a problem preventing `gpg` from communicating correctly with the `gpg-agent` (and/or invoking your `pinentry`
 program) that is independent of gradle.  Try running `pkill gpg-agent` and then retrying your `./gradlew` command
	Distribution and artifact publishing
	====================================


	See all distribution-related tasks by running:
	gradlew tasks --group distribution


	Maven
	-----

	To publish Lucene Maven artifacts to a local ~/.m2 repository, run:

	gradlew mavenToLocal

	To publish Lucene Maven artifacts to Apache repositories
	(CI or release manager's job, typically!), run:

	gradlew mavenToApacheSnapshots -PasfNexusUsername= -PasfNexusPassword=
	gradlew mavenToApacheReleases -PasfNexusUsername= -PasfNexusPassword= [optional signing options]

	See artifact signing section below if you plan to use mavenToApacheReleases.

	It is a good idea to avoid passing passwords on command line. CI jobs have
	these properties saved in ~/.gradle/gradle.properties - this way they
	are read automatically.

	Apache Releases repository will not accept snapshots.


	Release (distribution) artifacts
	--------------------------------

	To collect all release artifacts, and optionally sign them, run:

	gradlew assembleRelease [optional signing options]

	All distribution artifacts will be placed under:

	lucene/distribution/build/release

	Artifact signing is optional (but required if you're really making a release).


	Artifact signing
	----------------

	Certain tasks may optionally sign artifacts or require artifacts to be signed:

	assembleRelease
	mavenToApacheReleases

	Signing can be enabled by adding the "-Psign" option, for example:

	gradlew assembleRelease mavenToApacheReleases -Psign

	By default gradle uses a Java-based implementation of PGP for signing, which requieres
	several "signing.*" properties via either ~/.gradle/gradle.properties or command-line options:

	https://docs.gradle.org/current/userguide/signing_plugin.html#sec:signatory_credentials

	An example full command-line that assembles signed artifacts could look like this:

	gradlew assembleRelease mavenToApacheReleases -Psign -Psigning.keyId=... -Psigning.password=... -Psigning.secretKeyRingFile=...

	The keyId is the last 8 digits of your key (gpg -k will print your keys). Gradle documentation has more options
	of secure passing of private key information and passwords.


	Artifact signing using an external GPG with GPG Agent
	-----------------------------------------------------

	You can use an external GPG command to deal with signing artifacts, with out needing to give gradle your passphrase,
	by adding a "-PuseGpg" option, but this changes the properties you must specify:

	For gpg2:
	gradlew [tasks] -Psign -PuseGpg -Psigning.gnupg.keyName=...

	For gpg:
	gradlew [tasks] -Psign -PuseGpg -Psigning.gnupg.keyName=... -Psigning.gnupg.useLegacyGpg=true

	The keyName is the last 8 digits of your key (gpg -k will print your keys).

	There are additional (optional) "signing.gnupg.*" properties which exist that may be useful/necessary in your system:

	signing.gnupg.useLegacyGpg=true # Changes the default executable from `gpg2` to `gpg` and explicitly sets `--use-agent`
	signing.gnupg.executable=gpg # Allows explicit control over what command executable used (ex: `gpg2`, `gpg`, `gpg.exe`, etc...)
	signing.gnupg.homeDir=/tmp/gnupg-home # overrides GnuPG's default home directory (ex: `~/.gnupg/`)
	signing.gnupg.optionsFile=/tmp/gnupg-home/my.conf # overrides GnuPG's default configuration file
	signing.gnupg.passphrase=... # Provide your passphrase to gradle to hand off to gpg. NOT RECOMMENDED, see below.

	If in doubt, consult gradle's signing plugin documentation:
	https://docs.gradle.org/current/userguide/signing_plugin.html#sec:using_gpg_agent

	"signing.gnupg.passphrase" is not recomended because there is no advantage to using an external GPG process if you use it. If you
	are comfortable giving gradle your passphrase, then there is no reason to use an external GPG process via '-PuseGpg'. Just use the
	"signing.*" options described previuosly to let gradle deal with your key directly.

	Because of how Gradle's signing plugin invokes GPG, using an external GPG process only works if your GPG configuration uses a
	GPG agent (required by gpg2) and if the "pinentry" for your GPG agent does not require access to the tty to prompt you for a password.

	If you the following command fails with your GPG configuration, you can not use an external GPG process with gradle:

	echo foo \| gpg --batch --no-tty --armor --detach-sign --use-agent --local-user YOUR_KEY_NAME


	Notes About GPG Error Messages
	------------------------------

	### `gpg: signing failed: Inappropriate ioctl for device` or `Invalid IPC response`

	This typically happens if your `gpg-agent` is configured (either globally for your operating system, or personally in your
	`~/.gnupg/gpg-agent.conf`) to use a `pinentry` command which depends on using the same `tty` as the `gpg` command (ex: `pinentry-curses`,
	or `pinentry-tty`, etc...).

	`tty` based `pinentry` implementations do not work when Gradle's signing plugin is attempting to invoke `gpg` -- among other problems:
	Gradle is multi-threaded and we sign multiple artifacts by default. Even if you use "--max-workers 1" to force single-threaded execution,
	the signing plugin invokes gpg with `--batch --no-tty`, making it impossible for gpg (or a tty based pinentry) to prompt you for your passphrase
	in the same terminal where you run Gradle.

	Developers are encouraged to configure a non `tty` based `pinentry` (ex: `pinentry-gnome`, `pinentry-x11`, `pinentry-qt`, `pinentry-mac`,
	`pinentry-wsl-ps1`, etc...) either globally in your operating system, or personally in your `~/.gnupg/gpg-agent.conf`, or in a new
	`gpg-agent.conf` file a new GnuPG configuration directory (containing a copy of your private keys) that you direct gradle to via
	`signing.gnupg.homeDir`

	If this is not possible, then you should avoid using an external GPG process, and use the default (pure java) Artifact signing support


	### `gpg: signing failed: No such file or directory`

	This may mean that there is a problem preventing `gpg` from communicating correctly with the `gpg-agent` (and/or invoking your `pinentry`
	program) that is independent of gradle. Try running `pkill gpg-agent` and then retrying your `./gradlew` command