src/site/apt/usage.apt.vm

 ------
 Usage
 ------
 Dennis Lundberg
 ------
 2011-03-19
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

Usage

* Sign artifacts with GnuPG

  Signs all of a project's attached artifacts with GnuPG.

  You need to have previously configured the default key.

  <<<gpg>>> also needs to be on the search path.

  First you add the plugin to your <<<pom.xml>>> like this:

+----------+
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-gpg-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>sign-artifacts</id>
            <phase>verify</phase>
            <goals>
              <goal>sign</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
+----------+

  Then you specify the passphrase on the command line. Like this:

+----------+
mvn verify -Dgpg.passphrase=thephrase
+----------+

  If you don't specify a passphrase, it will prompt for one.

  <<Note:>> When using the GPG Plugin in combination with the Maven Release Plugin, you might need to specify the passphrase
  like this:

+----------+
mvn release:perform -Darguments=-Dgpg.passphrase=thephrase
+----------+

  This accounts for the fact, that the Release Plugin forks Maven and system properties of the current Maven session are
  unfortunately not automatically propagated to the forked Maven session (see also {{{https://issues.apache.org/jira/browse/MGPG-9}MGPG-9}}).


* Configure passphrase in settings.xml

  Instead of specifying the passphrase on the command line, you can place it in your local <<<settings.xml>>>
  either in clear or {{{http://maven.apache.org/guides/mini/guide-encryption.html}encrypted}} text.

+----------+
<settings>
  [...]
  <servers>
    [...]
    <server>
      <id>gpg.passphrase</id>
      <passphrase>clear or encrypted text</passphrase>
    </server>
  </servers>
</settings>
+----------+

* Configure passphrase in settings.xml with a keyname

  To allow discovery of keyname and passphrase at build time, configure this plugin to map both <keyname> and <passphraseServerId> to
  a fixed property.


+----------+
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-gpg-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>sign-artifacts</id>
            <phase>verify</phase>
            <goals>
              <goal>sign</goal>
            </goals>
            <configuration>
              <keyname>${gpg.keyname}</keyname>
              <passphraseServerId>${gpg.keyname}</passphraseServerId>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
+----------+


  and use local <<<settings.xml>>> to discover the passphrase via the keyname

+----------+
<settings>
  [...]
  <servers>
    [...]
    <server>
      <id>your.keyname</id>
      <passphrase>clear or encrypted text</passphrase>
    </server>
  </servers>

  [...]
  <profiles>
    <profile>
      <id>my_profile_id</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <gpg.keyname>your.keyname</gpg.keyname>
      </properties>
    </profile>
  <profiles>
</settings>
+----------+