# Chapter 38. The Signing Plugin

The signing plugin adds the ability to digitally sign built files and artifacts. These digital signatures can then be used to prove who built the artifact the signature is attached to as well as other information such as when the signature was generated.

The signing plugin currently only provides support for generating PGP signatures (which is the signature format required for publication to the Maven Central Repository).

## 38.1. Usage

To use the Signing plugin, include in your build script:

Example 38.1. Using the Signing plugin

`build.gradle`

    apply plugin: 'signing'

## 38.2. Signatory credentials

In order to create PGP signatures, you will need a key pair (instructions on creating a key pair using the GnuPG tools can be found here). You need to provide the signing plugin with your key information, which means three things:

- The public key ID (an 8 character hexadecimal string).

- The absolute path to the secret key ring file containing your private key.

- The passphrase used to protect your private key.

These items must be supplied as the property projects `signing.keyId`, `signing.password` and `signing.secretKeyRingFile` respectively. Given the personal and private nature of these values, a good practice is to store them in the user `gradle.properties` file (described in Section 12.2, “Gradle properties and system properties”).

    signing.keyId=24875D73
    signing.password=secret
    signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg

If specifying this information in the user `gradle.properties` file is not feasible for your environment, you can source the information however you need to and set the project properties manually.

    import org.gradle.plugins.signing.Sign

    gradle.taskGraph.whenReady { taskGraph ->
        if (taskGraph.allTasks.any { it instanceof Sign }) {
            // Use Java 6's console to read from the console (no good for a CI environment)
            Console console = System.console()
            console.printf "\n\nWe have to sign some things in this build.\n\nPlease enter your signing details.\n\n"
            allprojects*.setProperty("signing.keyId", console.readLine("PGP Key Id: "))
            allprojects*.setProperty("signing.secretKeyRingFile", console.readLine("PGP Secret Key Ring File (absolute path): "))
            allprojects*.setProperty("signing.password", console.readPassword("PGP Private Key Password: "))
            console.printf "\nThanks.\n\n"
        }
    }

## 38.3. Specifying what to sign

As well as configuring how things are to be signed (i.e. the signatory configuration), you must also specify what is to be signed. The Signing plugin provides a DSL that allows you to specify the tasks and/or configurations that should be signed.

### 38.3.1. Signing Configurations

It is common to want to sign the artifacts of a configuration. For example, the Java plugin configures a jar to built and this jar artifact is added to the `archives` configuration. Using the Signing DSL, you can specify that all of the artifacts of this configuration should be signed.

Example 38.2. Signing a configuration

`build.gradle`

    signing {
        sign configurations.archives
    }

This will create a task (of type `Sign`) in your project named “`signArchives`”, that will build any `archives` artifacts (if needed) and then generate signatures for them. The signature files will be placed alongside the artifacts being signed.

Example 38.3. Signing a configuration output

Output of `gradle signArchives`

    > gradle signArchives
    :compileJava
    :processResources
    :classes
    :jar
    :signArchives

    BUILD SUCCESSFUL

    Total time: 1 secs

### 38.3.2. Signing Tasks

In some cases the artifact that you need to sign may not be part of a configuration. In this case you can directly sign the task that produces the artifact to sign.

Example 38.4. Signing a task

`build.gradle`

    task stuffZip (type: Zip) {
        baseName = "stuff"
        from "src/stuff"
    }

    signing {
        sign stuffZip
    }

This will create a task (of type `Sign`) in your project named “`signStuffZip`”, that will build the input task's archive (if needed) and then sign it. The signature file will be placed alongside the artifact being signed.

Example 38.5. Signing a task output

Output of `gradle signStuffZip`

    > gradle signStuffZip
    :stuffZip
    :signStuffZip

    BUILD SUCCESSFUL

    Total time: 1 secs

For a task to be “signable”, it must produce an archive of some type. Tasks that do this are the `Tar`, `Zip`, `Jar`, `War` and `Ear` tasks.

### 38.3.3. Conditional Signing

A common usage pattern is to only sign build artifacts under certain conditions. For example, you may not wish to sign artifacts for non release versions. To achieve this, you can wrap whatever logic you need around the signing DSL.

Example 38.6. Conditional signing

`build.gradle`

    version = '1.0-SNAPSHOT'
    isReleaseVersion = !version.endsWith("SNAPSHOT")

    signing {
        if (isReleaseVersion) {
            sign configurations.archives
        }
    }

## 38.4. Publishing the signatures

When specifying what is to be signed via the Signing DSL, the resultant signature artifacts are automatically added to the “`signatures`” dependency configuration that the signing plugin adds. This means that if you want to upload your signatures to your distribution repository along with the artifacts for which the signature is for you are going to have to create a new configuration that combines them. By default, created artifacts such as jars and the like are added to the “`archives`” configuration. You can create a new configuration that extends “`archives`” and “`signatures`”.

Example 38.7. Adding the published configuration

`build.gradle`

    configurations {
        published.extendsFrom archives, signatures
    }

This also means that instead of configuring and using the “`uploadArchives`” to distribute your artifacts, you would use the equivalent “`uploadPublished`” task. See Chapter 36, Artifact Management for more on artifacts and configurations.

## 38.5. Signing POM files

When deploying signatures for your artifacts to a Maven repository, you will also want to sign the published POM file. The signing plugin adds a `signPom()` method that can be used in the `beforeDeployment()` block in your upload task configuration.

Example 38.8. Signing a POM for deployment

`build.gradle`

    uploadPublished {
        repositories {
            mavenDeployer {
                beforeDeployment { MavenDeployment deployment -> signPom(deployment) }
            }
        }
    }