lucene/help/publishing.txt

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 requires
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 recommended 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