签名插件添加了对数字签名构建文件和工件的能力。这些数字签名可用于证明谁构建了签名所附的工件，以及其他信息，例如签名生成时间。

签名插件目前仅支持生成 OpenPGP 签名（这是 发布到 Maven 中央存储库所需的签名格式）。

用法

要使用签名插件，请在您的构建脚本中包含以下内容

示例 1. 使用签名插件
build.gradle.kts
plugins {
    signing
}
build.gradle
plugins {
    id 'signing'
}

签名凭据

为了创建 OpenPGP 签名，您需要一个密钥对（有关使用 GnuPG 工具 创建密钥对的说明，请参阅 GnuPG HOWTOs）。您需要向签名插件提供您的密钥信息，这意味着三件事

  • 公钥 ID（密钥 ID 的最后 8 个符号。您可以使用 gpg -K 获取它）。

  • 包含您的私钥的密钥环文件的绝对路径。（从 gpg 2.1 开始，您需要使用命令 gpg --keyring secring.gpg --export-secret-keys > ~/.gnupg/secring.gpg 导出密钥）。

  • 用于保护您的私钥的密码。

这些项目必须分别作为signing.keyId、signing.secretKeyRingFile和signing.password属性的值提供。

鉴于这些值的个人和私密性质，一个好的做法是将它们存储在用户 Gradle 主目录中的gradle.properties文件中（在系统属性中描述），而不是在项目目录本身中。 
signing.keyId=24875D73
signing.password=secret
signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg

如果在用户gradle.properties文件中指定此信息（尤其是signing.password）对于您的环境不可行，您可以通过命令行提供此信息。

> gradle sign -Psigning.secretKeyRingFile=/Users/me/.gnupg/secring.gpg -Psigning.password=secret -Psigning.keyId=24875D73

使用内存中的 ASCII 编码密钥

在某些设置中，使用环境变量传递用于签名的密钥和密码更容易。例如，当使用 CI 服务器签署工件时，安全地提供密钥环文件通常很麻烦。另一方面，大多数 CI 服务器提供安全存储环境变量并将其提供给构建的方法。使用以下设置，您可以分别使用ORG_GRADLE_PROJECT_signingKey和ORG_GRADLE_PROJECT_signingPassword环境变量传递密钥（以 ASCII 编码格式）和密码。

build.gradle.kts
signing {
    val signingKey: String? by project
    val signingPassword: String? by project
    useInMemoryPgpKeys(signingKey, signingPassword)
    sign(tasks["stuffZip"])
}
build.gradle
signing {
    def signingKey = findProperty("signingKey")
    def signingPassword = findProperty("signingPassword")
    useInMemoryPgpKeys(signingKey, signingPassword)
    sign stuffZip
}

使用内存中的 ASCII 编码 OpenPGP 子密钥

为了防止主密钥的共享并确保其安全，也可以使用内存中的 ASCII 编码子密钥。使用内存中的 ASCII 编码密钥和子密钥之间的主要区别在于，必须指定密钥标识符。使用以下设置，您可以分别使用ORG_GRADLE_PROJECT_signingKeyId、ORG_GRADLE_PROJECT_signingKey和ORG_GRADLE_PROJECT_signingPassword环境变量传递密钥标识符、密钥（以 ASCII 编码格式）和密码。

build.gradle.kts
signing {
    val signingKeyId: String? by project
    val signingKey: String? by project
    val signingPassword: String? by project
    useInMemoryPgpKeys(signingKeyId, signingKey, signingPassword)
    sign(tasks["stuffZip"])
}
build.gradle
signing {
    def signingKeyId = findProperty("signingKeyId")
    def signingKey = findProperty("signingKey")
    def signingPassword = findProperty("signingPassword")
    useInMemoryPgpKeys(signingKeyId, signingKey, signingPassword)
    sign stuffZip
}

使用 OpenPGP 子密钥

OpenPGP 支持子密钥，它们类似于普通密钥，只是它们绑定到主密钥对。OpenPGP 子密钥的一项功能是，它们可以独立于主密钥被撤销，这使得密钥管理更容易。有关如何在软件开发中利用子密钥的实际案例研究，请参阅Debian wiki。

签名插件开箱即用地支持 OpenPGP 子密钥。只需在signing.keyId属性中指定一个子密钥 ID 作为值。

使用 gpg-agent

默认情况下，签名插件使用基于 Java 的 PGP 实现进行签名。此实现无法使用 gpg-agent 程序来管理私钥。如果您想使用 gpg-agent，您可以更改签名插件使用的签名者实现。

示例 2. 使用 GnuPG 签名
build.gradle.kts
signing {
    useGpgCmd()
    sign(configurations.runtimeElements.get())
}
build.gradle
signing {
    useGpgCmd()
    sign configurations.runtimeElements
}

这告诉签名插件使用GnupgSignatory而不是默认的PgpSignatory。GnupgSignatory依赖于gpg2程序来签署工件。当然，这需要安装GnuPG。

如果没有进一步的配置，PATH上找到的gpg（在Windows上：gpg.exe）可执行文件将被使用。密码由gpg-agent提供，默认密钥用于签名。

Gnupg 签名配置

GnupgSignatory支持许多配置选项来控制gpg的调用方式。这些通常在gradle.properties中设置。

示例：配置 GnupgSignatory

gradle.properties
signing.gnupg.executable=gpg
signing.gnupg.useLegacyGpg=true
signing.gnupg.homeDir=gnupg-home
signing.gnupg.optionsFile=gnupg-home/gpg.conf
signing.gnupg.keyName=24875D73
signing.gnupg.passphrase=gradle
signing.gnupg.executable

用于签名的gpg可执行文件。此属性的默认值取决于useLegacyGpg。如果为true，则可执行文件的默认值为“gpg”，否则为“gpg2”。

signing.gnupg.useLegacyGpg

如果使用GnuPG版本1，则必须为true，否则为false。该属性的默认值为false。

signing.gnupg.homeDir

设置GnuPG的主目录。如果没有给出，则使用GnuPG的默认主目录。

signing.gnupg.optionsFile

为GnuPG设置自定义选项文件。如果没有给出，则使用GnuPG的默认配置文件。

signing.gnupg.keyName

用于签名的密钥的ID。如果没有给出，则使用GnuPG中配置的默认密钥。

signing.gnupg.passphrase

用于解锁密钥的密码。如果没有给出，则使用gpg-agent程序获取密码。

所有配置属性都是可选的。

指定要签署的内容

除了配置签署方式（即签名配置）之外，您还必须指定要签署的内容。签名插件提供了一个DSL，允许您指定要签署的任务和/或配置。

签署出版物

发布工件时，您通常希望对其进行签名，以便工件的使用者可以验证其签名。例如，Java 插件定义了一个组件，您可以使用它使用Maven 发布插件（或Ivy 发布插件，分别）定义到 Maven（或 Ivy）存储库的出版物。使用签名 DSL，您可以指定此出版物的全部工件都应该被签名。

示例 3. 签署出版物
build.gradle.kts
signing {
    sign(publishing.publications["mavenJava"])
}
build.gradle
signing {
    sign publishing.publications.mavenJava
}

这将在您的项目中创建一个名为 signMavenJavaPublication 的任务（类型为 Sign），该任务将构建出版物中包含的所有工件（如果需要），然后为它们生成签名。签名文件将放置在被签署的工件旁边。

示例：签署出版物输出

gradle signMavenJavaPublication 的输出
> gradle signMavenJavaPublication
> Task :compileJava
> Task :processResources
> Task :classes
> Task :jar
> Task :javadoc
> Task :javadocJar
> Task :sourcesJar
> Task :generateMetadataFileForMavenJavaPublication
> Task :generatePomFileForMavenJavaPublication
> Task :signMavenJavaPublication

BUILD SUCCESSFUL in 0s
9 actionable tasks: 9 executed

此外，上述 DSL 允许 sign 多个用逗号分隔的出版物。或者，您可以指定 publishing.publications 来签署所有出版物，或者使用 publishing.publications.matching { … } 来签署与指定谓词匹配的所有出版物。

签名配置

通常需要签署配置的工件。例如，Java 插件 配置一个 jar 来构建，并且此 jar 工件被添加到 runtimeElements 配置中。使用签名 DSL，您可以指定此配置的所有工件都应该被签署。

示例 4. 签署配置
build.gradle.kts
signing {
    sign(configurations.runtimeElements.get())
}
build.gradle
signing {
    sign configurations.runtimeElements
}

这将在您的项目中创建一个名为 signRuntimeElements 的任务（类型为 Sign），该任务将构建任何 runtimeElements 工件（如果需要），然后为它们生成签名。签名文件将放置在被签署的工件旁边。

示例：签署配置输出

gradle signRuntimeElements 的输出
> gradle signRuntimeElements
> Task :compileJava
> Task :processResources
> Task :classes
> Task :jar
> Task :signRuntimeElements

BUILD SUCCESSFUL in 0s
4 actionable tasks: 4 executed

签名任务输出

在某些情况下，您需要签署的工件可能不是配置的一部分。在这种情况下，您可以直接签署生成要签署工件的任务。

示例 5. 签署任务输出
build.gradle.kts
tasks.register<Zip>("stuffZip") {
    archiveBaseName = "stuff"
    from("src/stuff")
}

signing {
    sign(tasks["stuffZip"])
}
build.gradle
tasks.register('stuffZip', Zip) {
    archiveBaseName = 'stuff'
    from 'src/stuff'
}

signing {
    sign stuffZip
}

这将在您的项目中创建一个名为 signStuffZip 的任务（类型为 Sign），该任务将构建输入任务的存档（如果需要），然后签署它。签名文件将放置在被签署的工件旁边。

示例：签署任务输出

gradle signStuffZip 的输出
> gradle signStuffZip
> Task :stuffZip
> Task :signStuffZip

BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed

要使任务可签名，它必须生成某种类型的存档，即它必须扩展 AbstractArchiveTask。执行此操作的任务包括 Tar、Zip、Jar、War 和 Ear 任务。

条件签名

一个常见的用法模式是在特定条件下才需要对构建工件进行签名。例如，您可能不需要对非发布版本进行签名。要实现这一点，您可以将条件指定为 required() 方法的参数。

示例 6. 指定何时需要签名
build.gradle.kts
version = "1.0-SNAPSHOT"
extra["isReleaseVersion"] = !version.toString().endsWith("SNAPSHOT")

signing {
    setRequired({
        (project.extra["isReleaseVersion"] as Boolean) && gradle.taskGraph.hasTask("publish")
    })
    sign(publishing.publications["main"])
}
build.gradle
version = '1.0-SNAPSHOT'
ext.isReleaseVersion = !version.endsWith("SNAPSHOT")

signing {
    required { isReleaseVersion && gradle.taskGraph.hasTask("publish") }
    sign publishing.publications.main
}

在此示例中，我们只希望在构建发布版本并准备发布时才需要签名。因为我们正在检查任务图以确定是否要发布，所以必须将 signing.required 属性设置为闭包以延迟评估。有关更多信息，请参阅 SigningExtension.setRequired(java.lang.Object)。

如果 required 条件不成立，则只有在配置了签名者凭据时才会对工件进行签名。或者，您可能希望完全跳过签名，无论签名者凭据是否可用。如果是这样，您可以配置 Sign 任务以跳过，例如通过使用 onlyIf() 方法附加谓词，如以下示例所示

示例 7. 指定何时跳过签名
build.gradle.kts
tasks.withType<Sign>().configureEach {
    onlyIf("isReleaseVersion is set") { project.extra["isReleaseVersion"] as Boolean }
}
build.gradle
tasks.withType(Sign) {
    onlyIf("isReleaseVersion is set") { isReleaseVersion }
}

发布签名

在对 出版物 进行签名时，生成的签名工件会自动添加到相应的出版物中。因此，在发布到存储库时，例如通过执行 publish 任务，您的签名将与其他工件一起分发，无需任何额外的配置。

在对 配置 和 任务 进行签名时，生成的签名工件会自动添加到 signatures 依赖项配置中。