连接到 Jenkins

您可以使用 Jenkins 触发器和 Secure Source Manager Webhook 启动自动构建。

所需角色

如需获得创建 Jenkins 构建触发器所需的权限，请让管理员向您授予以下 IAM 角色：

• Secure Source Manager Repo Admin (roles/securesourcemanager.repoAdmin) 在您的代码库上
• Secure Source Manager 实例的 Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义 角色或其他预定义 角色来获取所需的权限。

如需了解如何授予 Secure Source Manager 角色， 请参阅 使用 IAM 进行访问权限控制 和 向用户授予实例访问权限。

设置 Webhook 触发器

Jenkins 使用构建触发器插件来启用 CI/CD 自动化。您可以配置触发器以侦听传入的事件（例如，将新提交推送到代码库或者启动拉取请求时），然后在收到新事件时自动执行构建。您还可以将触发器配置为在源代码库发生任何更改时构建代码，或者仅在更改符合特定条件时构建代码。

如需设置通用 Jenkins Webhook 触发器，请执行以下操作：

1. 在 Jenkins 服务器上安装 Jenkins Git 插件、 SSH 凭据插件 和 Generic Webhook Trigger 插件 。

2. 在 Jenkins 服务器中生成有效的 SSH 密钥对。 Secure Source Manager 仅支持 RSA 类型的密钥。

3. 运行以下命令，将 Secure Source Manager 实例网域添加到 Jenkins 服务器 SSH known_hosts 文件：

   ssh -t git@INSTANCE_ID-INSTANCE_PROJECT_NUMBER-ssh.us-central1.sourcemanager.dev
   

   其中：

   • INSTANCE_ID 是 Secure Source Manager 实例的名称。
   • INSTANCE_PROJECT_NUMBER 是您的 Secure Source Manager 实例的项目编号。如需了解在哪里查找项目编号，请参阅 标识项目 。

   例如，以下命令会添加项目编号为 123456789 的名为 prod-test-instance 的实例的实例网域。

   ssh -t [e-mail]
   

   回复 yes，将实例网域添加到已知主机列表中。

4. 在 Jenkins Manage Credentials （管理凭据）页面中：

   1. 选择 SSH username with private key （SSH 用户名与私钥）。
   2. 粘贴 Jenkins 服务器 SSH 私钥。
   3. 在 Kind （种类）下拉菜单中，根据需要填写其他字段。

5. 点击创建 。

6. 在 Jenkins 网页界面中，创建一个新的 Jenkins 作业。

7. 在 Jenkins 作业的配置页面中，在 Source Code Management （源代码管理）部分下，选择 Git 。

8. 在 Git 部分中，粘贴 Secure Source Manager 代码库 SSH 网址作为代码库网址，输入构建分支（例如 */main），然后选择之前在 Manage Credentials （管理凭据）页面中添加的已保存的 SSH 私钥凭据。

9. 在 Build Triggers （构建触发器）部分中，选择 Generic Webhook Trigger （通用 Webhook 触发器）。

   （可选）您可以添加令牌，以便仅在调用时提供该令牌时触发作业。如需添加令牌，您可以在 Generic Webhook Trigger （通用 Webhook 触发器）部分下的 Token （令牌）字段中输入令牌。

10. 在 Build （构建）部分中，提供您希望此 Jenkins 作业使用的构建脚本。例如，您可以执行 cat README.md 以输出 README.md 的内容。

11. 点击保存 以创建 Jenkins 作业。

设置服务帐号并授予所需权限

1. 如果您还没有要使用的服务帐号， 请创建一个服务账号。

   确保您对服务账号拥有 iam.serviceAccounts.actAs 权限。此权限是 Service Account User (roles/iam.serviceAccountUser) 角色的组成部分。

2. 在 Secure Source Manager 网页界面中，点击 更多选项 菜单。

3. 点击 Service account SSH keys （服务账号 SSH 密钥）。系统会打开 Service account SSH keys （服务账号 SSH 密钥）页面，并显示您添加的所有现有密钥的列表。

4. 点击添加密钥 。

5. 在 Add SSH key （添加 SSH 密钥）页面中，为您的密钥输入以下值：

   1. Service account（服务账号）：您希望在其中使用 SSH 密钥的服务账号的服务帐号电子邮件地址，格式为SA_NAME@PROJECT_ID.iam.gserviceaccount.com

      其中

      • SA_NAME 是服务帐号名称。
      • PROJECT_ID 是创建服务账号的项目 ID。

   2. SSH Public Key（SSH 公钥）：您的 Jenkins SSH 公钥。

授予 Secure Source Manager 服务代理权限

如果服务帐号与 Secure Source Manager 实例不在同一项目中，您还必须向 Secure Source Manager 服务代理 授予 Service Account Token Creator (roles/iam.serviceAccountTokenCreator) 角色 或 iam.serviceAccounts.signJwt 权限。

如果您的服务帐号与您的 Secure Source Manager 实例位于同一项目中，请跳至 向服务帐号授予代码库角色。

1. 运行以下命令，获取服务帐号的现有 IAM 政策：

   gcloud iam service-accounts get-iam-policy SERVICE_ACCOUNT \
       --format json
   

   其中 SERVICE_ACCOUNT 是您要使用的服务帐号。 账号应采用数字服务帐号 ID 或电子邮件地址格式，例如：123456789876543212345 或 [e-mail]。

   输出内容包括任何现有绑定，或者，如果不存在任何绑定，则包括类似于以下内容的 etag 值：

   {
   "etag": "BwUjHYKJUiQ="
   }
   

   重要提示： 保留 etag 值，以确保您不会覆盖其他人的政策 更改。get-iam-policy如果您想覆盖所有其他更改，可以移除 etag 值。

2. 将输出内容复制到名为 policy.json 的新文件中。

3. 如需向 Secure Source Manager 服务代理授予 Service Account Token Creator (roles/iam.ServiceAccountTokenCreator) 角色，请修改 policy.json 以添加以下内容：

   {
       "role": "roles/iam.serviceAccountTokenCreator",
       "members": [
           "serviceAccount:[e-mail]"
       ]
   }
   

   其中 INSTANCE_PROJECT_NUMBER 是 Secure Source Manager 实例的项目编号。

4. 运行以下命令，替换服务帐号的现有 IAM 政策：

   gcloud iam service-accounts set-iam-policy SERVICE_ACCOUNT POLICY_FILE
   

   替换以下内容：

   • 将 SERVICE_ACCOUNT 替换为服务帐号 ID 或电子邮件地址。
   • 将 POLICY_FILE 替换为 JSON 格式文件的位置和名称，包括新政策。

向服务帐号授予代码库角色

1. 在 Secure Source Manager 网页界面中，前往您要向服务帐号授予权限的代码库。
2. 点击权限 标签页。
3. 点击 Add Users （添加用户）。
4. 在 Add principal （添加主账号）字段中，输入服务帐号电子邮件地址。
5. 在角色 下拉菜单中，选择 Secure Source Manager Repository Reader （Secure Source Manager 代码库读取器）。

6. 运行以下命令，为服务帐号分配 securesourcemanager.instanceAccessor 角色：

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:SA_EMAIL \
       --role=roles/securesourcemanager.instanceAccessor
   

   替换以下内容：

   • 将 PROJECT_ID 替换为 Secure Source Manager 实例项目 ID。
   • 将 SA_EMAIL 替换为服务帐号电子邮件地址。

设置 Webhook

1. 在 Secure Source Manager 网页界面中，前往您要为其创建 Webhook 的代码库。
2. 点击设置 。
3. 点击 Webhooks ，然后点击 Add webhook 。

4. 在 Hook ID （钩子 ID）字段中，输入 Webhook 的 ID。

   注意： 钩子 ID 必须遵循 资源命名惯例。 它们必须仅包含小写字母、数字或短划线，必须以字母开头，并且在创建 Webhook 后无法更改。

5. 在 Target 网址 （目标网址）字段中，输入 Jenkins 触发器网址。

6. 如果您在配置 Jenkins 触发器时使用了可选令牌，则 Jenkins 触发器网址将在末尾包含该令牌。为防止令牌泄露，请将其从目标网址末尾移除，并复制到 Sensitive Query String （敏感查询字符串）字段。

   如需在触发器网址中找到令牌，请查找以 token= 开头的文本

   例如，如果您的网址类似于以下网址： https://jenkins-server.com/generic-webhook-trigger/invoke?token=jenkins-job1

   复制并移除 Target 网址 （目标网址）字段中以问号 ?token=jenkins-job1 开头的部分。然后移除初始问号，将剩余部分 token=jenkins-job1 移至 Sensitive Query String （敏感查询字符串）字段。

7. 在 Trigger on （触发条件）部分中，选择以下选项之一：

   • Push（推送）：在向代码库推送时触发。
   • Pull request state changed（拉取请求状态已更改）：在拉取请求状态发生更改时触发。

8. 如果您选择了 Push（推送），则可以在 Branch filter（分支过滤器）字段中输入推送事件的许可名单。

   Branch filter （分支过滤器）字段使用 glob 模式，只有对匹配的分支执行的操作才会导致构建触发器。如果该字段为空或 *，则系统会报告所有分支的推送事件。

9. 点击 Add webhook 。

10. Webhook 会显示在 Webhooks （Webhook）页面中。

    注意： 添加或修改 Webhook 时， Sensitive Query String 的长度可能与输入的内容不一致，这 是正常现象，因为系统会使用占位符字符串来确保安全。

测试 Webhook

1. 在 Secure Source Manager Webhooks （Webhook）页面中，点击要测试的 Webhook。

2. 前往页面底部，然后点击 Test delivery （测试传送）。

   系统会将一个虚假事件添加到传送队列中。该事件可能需要几秒钟才会显示在传送记录中。

3. 您还可以使用 git 命令推送或合并拉取请求来测试 Webhook。

4. 在 Jenkins 项目中，在 Build History （构建记录）中查看由测试事件触发的构建。

5. 在发送第一个测试传送后，您还可以在 Secure Source Manager Webhook 页面的 Recent deliveries （最近传送）部分中查看测试传送的请求 和响应 。

后续步骤

• 浏览 Jenkins 文档。