Jenkins 处理凭证

Secret 文本，带密码的用户名，Secret 文件

Jenkins 的声明式流水线语法有一个 credentials() 辅助方法（在environment 指令中使用），它支持 secret 文本，带密码的用户名，以及 secret 文件凭据。如果你想处理其他类型的凭据，请参考其他凭据类型一节（见下）。

Secret 文本

下面的流水线代码演示了如何使用环境变量为 secret 文本凭据创建流水线的示例。

在该示例中，将两个 secret 文本凭据赋予各自的环境变量来访问 Amazon Web 服务（AWS）。这些凭据已在 Jenkins 中配置了各自的凭据 ID jenkins-aws-secret-key-id 和 jenkins-aws-secret-access-key。

pipeline {
    agent {
        // 此处定义 agent 的细节
    }
    environment {
        AWS_ACCESS_KEY_ID     = credentials('jenkins-aws-secret-key-id')
        AWS_SECRET_ACCESS_KEY = credentials('jenkins-aws-secret-access-key')
    }
    stages {
        stage('Example stage 1') {
            steps {
                // 
            }
        }
        stage('Example stage 2') {
            steps {
                // 
            }
        }
    }
}

带密码的用户名

下面的流水线代码片段展示了如何创建一个使用带密码的用户名凭据的环境变量的流水线。

在该示例中，带密码的用户名凭据被分配了环境变量，用来使你的组织或团队以一个公用账户访问 Bitbucket 仓库；这些凭据已在 Jenkins 中配置了凭据 ID jenkins-bitbucket-common-creds

environment {
    BITBUCKET_COMMON_CREDS = credentials('jenkins-bitbucket-common-creds')
}

这实际设置了下面的三个环境变量, 只要后面加上 _USR 加上 _PSW就是用户名和密码

• BITBUCKET_COMMON_CREDS - 包含一个以冒号分隔的用户名和密码，格式为 username:password。

• BITBUCKET_COMMON_CREDS_USR - 附加的一个仅包含用户名部分的变量。

• BITBUCKET_COMMON_CREDS_PSW - 附加的一个仅包含密码部分的变量。

Secret 文件

就流水线而言，secret 文件的处理方式与 Secret 文本 完全相同。

实际上，secret 文本和 secret 文件凭据之间的唯一不同是，对于 secret 文本，凭据本身直接输入到 Jenkins 中，而 secret 文件的凭据则原样保存到一个文件中，之后将传到 Jenkins。

与 secret 文本不同的是，secret 文件适合：

• 太笨拙而不能直接输入 Jenkins

• 二进制格式，比如 GPG 文件

其他凭据类型

如果你需要在流水线中设置除了 secret 文本、带密码的用户名、secret 文件以外的其他凭据——即 SSH 秘钥或证书，那么请使用 Jenkins 的片段生成器特性，你可以通过 Jenkins 的经典 UI 访问它。
SSH User Private Key 示例

withCredentials(bindings: [sshUserPrivateKey(credentialsId: 'jenkins-ssh-key-for-abc', \
                                             keyFileVariable: 'SSH_KEY_FOR_ABC', \
                                             passphraseVariable: '', \
                                             usernameVariable: '')]) {
  // some block
}
可选的 passphraseVariable 和 usernameVariable 定义可以在最终的流水线代码中删除。

Certificate 示例

withCredentials(bindings: [certificate(aliasVariable: '', \
                                       credentialsId: 'jenkins-certificate-for-xyz', \
                                       keystoreVariable: 'CERTIFICATE_FOR_XYZ', \
                                       passwordVariable: 'XYZ-CERTIFICATE-PASSWORD')]) {
  // some block
}

可选的 aliasVariable 和 passwordVariable 变量定义可以在最终的流水线代码中删除。

下面的代码片段展示了一个完整的示例流水线，实现了上面的 SSH User Private Key 和 Certificate 片段:

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent {
        // define agent details
    }
    stages {
        stage('Example stage 1') {
            steps {
                withCredentials(bindings: [sshUserPrivateKey(credentialsId: 'jenkins-ssh-key-for-abc', \
                                                             keyFileVariable: 'SSH_KEY_FOR_ABC')]) {
                  // 
                }
                withCredentials(bindings: [certificate(credentialsId: 'jenkins-certificate-for-xyz', \
                                                       keystoreVariable: 'CERTIFICATE_FOR_XYZ', \
                                                       passwordVariable: 'XYZ-CERTIFICATE-PASSWORD')]) {
                  // 
                }
            }
        }
        stage('Example stage 2') {
            steps {
                // 
            }
        }
    }
}

为了维护这些证书的安全性和匿名性，如果你试图从 withCredentials( ... ) { ... } 步骤中检索这些凭据变量的值，在 Secret 文本 示例（见上）中的相同行为也适用于这些 SSH 公私钥对证书和凭据变量类型。

• 在 片段生成器 的示例步骤中使用 withCredentials: Bind credentials to variables 选项时，只有当前流水线项目有访问权限的凭据才可以从凭据字段中选择。 虽然你可以为你的流水线手动编写 withCredentials( ... ) { ... } 步骤（ 如上所示），但更建议使用 片段生成器 来防止指定超出该流水线访问范围的证书，可以避免运行步骤时失败。

• 你也可以用 片段生成器 来生成处理 secret 文本，带密码的用户名以及 secret 文件的 withCredentials( ... ) { ... } 步骤。但是，如果你只需要处理这些类型的证书的话，为了提高你流水线代码的可读性，更建议你使用在上面一节中描述的相关过程。

• 在 Groovy 中使用单引号而不是双引号来定义脚本（sh 的隐式参数）。单引号将使 secret 被 shell 作为环境变量展开。双引号可能不太安全，因为这个 secret 是由 Groovy 插入的，所以一般操作系统的进程列表（以及 Blue Ocean 和经典 UI 中的流水线步骤树）会意外地暴露它：

node {
  withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
    sh /* 错误！ */ """
      set +x
      curl -H 'Token: $TOKEN' https://some.api/
    """
    sh /* 正确 */ '''
      set +x
      curl -H 'Token: $TOKEN' https://some.api/
    '''
  }
}