feat: prefer GitHub App auth for compliance workflows

Author: seekskyworld

.github/workflows/cla-reusable.yml

@@ -53,6 +53,10 @@ on:
         required: false
         default: I have read the ICLA and I hereby sign this agreement.
         type: string
+      app-id:
+        required: false
+        default: ""
+        type: string
 
 jobs:
   cla:
@@ -132,10 +136,19 @@ jobs:
             core.setOutput("corporate_authorization_display_name", corporateAuthorizationDisplayName);
             core.setOutput("sign_comment", signComment);
 
+      - name: Create GitHub App token
+        id: app_token
+        if: ${{ inputs.app-id != '' && secrets.CLA_APP_PRIVATE_KEY != '' }}
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ inputs.app-id }}
+          private-key: ${{ secrets.CLA_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+
       - name: Persist signed contributors
         uses: actions/github-script@v8
         with:
-          github-token: ${{ secrets.CLA_BOT_TOKEN != '' && secrets.CLA_BOT_TOKEN || secrets.GITHUB_TOKEN }}
+          github-token: ${{ steps.app_token.outputs.token || secrets.CLA_BOT_TOKEN || secrets.GITHUB_TOKEN }}
           script: |
             const prNumber =
               context.payload.pull_request?.number ??
@@ -292,7 +305,7 @@ jobs:
       - name: Check and collect CLA signatures
         uses: contributor-assistant/github-action@v2.6.1
         env:
-          GITHUB_TOKEN: ${{ secrets.CLA_BOT_TOKEN != '' && secrets.CLA_BOT_TOKEN || secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ steps.app_token.outputs.token || secrets.CLA_BOT_TOKEN || secrets.GITHUB_TOKEN }}
         with:
           path-to-document: https://github.com/${{ github.repository }}/blob/${{ inputs.default-branch }}/${{ inputs.icla-path }}
           path-to-signatures: ${{ inputs.signatures-path }}

.github/workflows/cla.yml

@@ -27,4 +27,5 @@ jobs:
       issue-is-pr: ${{ github.event_name == 'issue_comment' && github.event.issue.pull_request != null }}
       comment-body: ${{ github.event.comment.body || '' }}
       default-branch: ${{ github.event.repository.default_branch }}
+      app-id: ${{ vars.CLA_APP_ID }}
       compliance-profile: bsl-change-license-commercial

.github/workflows/pr-compliance-reusable.yml

@@ -24,16 +24,29 @@ on:
         required: false
         default: ""
         type: string
+      app-id:
+        required: false
+        default: ""
+        type: string
 
 jobs:
   validate-pr-metadata:
     runs-on: ubuntu-latest
     steps:
+      - name: Create GitHub App token
+        id: app_token
+        if: ${{ inputs.app-id != '' && secrets.CLA_APP_PRIVATE_KEY != '' }}
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ inputs.app-id }}
+          private-key: ${{ secrets.CLA_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+
       - name: Resolve compliance profile
         id: resolve_profile
         uses: actions/github-script@v8
         with:
-          github-token: ${{ secrets.CLA_BOT_TOKEN != '' && secrets.CLA_BOT_TOKEN || secrets.GITHUB_TOKEN }}
+          github-token: ${{ steps.app_token.outputs.token || secrets.CLA_BOT_TOKEN || secrets.GITHUB_TOKEN }}
           script: |
             const profiles = {
               "bsl-change-license-commercial": {
@@ -82,7 +95,7 @@ jobs:
       - name: Validate PR declarations
         uses: actions/github-script@v8
         with:
-          github-token: ${{ secrets.CLA_BOT_TOKEN != '' && secrets.CLA_BOT_TOKEN || secrets.GITHUB_TOKEN }}
+          github-token: ${{ steps.app_token.outputs.token || secrets.CLA_BOT_TOKEN || secrets.GITHUB_TOKEN }}
           script: |
             const prNumber = Number(${{ inputs.pr-number }});
             const body = ${{ toJson(inputs.pr-body) }};

.github/workflows/pr-compliance.yml

@@ -22,4 +22,5 @@ jobs:
       pr-body: ${{ github.event.pull_request.body }}
       pr-author-login: ${{ github.event.pull_request.user.login }}
       default-branch: ${{ github.event.repository.default_branch }}
+      app-id: ${{ vars.CLA_APP_ID }}
       compliance-profile: bsl-change-license-commercial

CONTRIBUTING.md

@@ -28,7 +28,10 @@
 为了让 CLA 流程正常工作，仓库维护者还需要完成以下配置：
 
 1. 在 GitHub 仓库设置中启用 Actions。
-2. 如果组织允许把 Workflow permissions 设为 `Read and write`，可以直接启用；如果组织层强制只读，则需要额外设置仓库 secret `CLA_BOT_TOKEN`，其值应为具有 `repo` 与 `workflow` 范围的 token。
+2. 推荐配置 GitHub App：
+   - repository variable `CLA_APP_ID`
+   - repository secret `CLA_APP_PRIVATE_KEY`
+   如果暂时还没切 GitHub App，可临时保留仓库 secret `CLA_BOT_TOKEN` 作为兼容兜底。
 3. 在默认分支保护规则里把 `CLA` 和 `PR Compliance` 两个检查都加入必过状态。
 4. 额外创建一个未受保护的 `cla-signatures` 分支，专门存储 `.github/cla/signatures.json`。
 5. 不要手动创建 `.github/cla/signatures.json`，首次有人签署时工作流会自动创建。
@@ -48,6 +51,7 @@ git switch main
 ## 说明
 
 - 当前 CLA 流程基于 `contributor-assistant/github-action`。
+- PR 评论与 `cla-signatures` 写入会优先使用 GitHub App 身份。
 - 默认只有 bot 账号在 `allowlist` 中自动豁免，维护者和普通开发者都需要至少完成一次真实签署。
 - 机器人评论签署即代表你确认接受 [`docs/legal/ICLA.md`](./docs/legal/ICLA.md) 中的条款。
 - 企业贡献需要额外的 [`docs/legal/CCLA.md`](./docs/legal/CCLA.md) 或等效书面授权。

docs/organization-rollout.md

@@ -41,7 +41,7 @@ scripts/github/rollout-org-compliance.sh \
   --org golutra \
   --central-workflow-repo golutra/platform-workflows \
   --compliance-profile bsl-change-license-commercial \
-  --workflow-ref v1.1.1 \
+  --workflow-ref 0.1.0 \
   --execute
 ```
 
@@ -78,12 +78,13 @@ caller workflow 会统一变成只传 profile 的形式：
 ```yaml
 jobs:
   cla:
-    uses: golutra/platform-workflows/.github/workflows/cla-reusable.yml@v1.1.1
+    uses: golutra/platform-workflows/.github/workflows/cla-reusable.yml@0.1.0
     with:
       event-name: ${{ github.event_name }}
       issue-is-pr: ${{ github.event_name == 'issue_comment' && github.event.issue.pull_request != null }}
       comment-body: ${{ github.event.comment.body || '' }}
       default-branch: ${{ github.event.repository.default_branch }}
+      app-id: ${{ vars.CLA_APP_ID }}
       compliance-profile: bsl-change-license-commercial
 ```
 
@@ -127,9 +128,11 @@ jobs:
 
 如果组织层把 `GITHUB_TOKEN` 默认权限限制为只读，还需要在每个业务仓库设置一个具有 `repo` 和 `workflow` 范围的仓库 secret：
 
-- `CLA_BOT_TOKEN`
+- repository variable `CLA_APP_ID`
+- repository secret `CLA_APP_PRIVATE_KEY`
+- 可选：仓库 secret `CLA_BOT_TOKEN` 作为兼容兜底
 
-中央 reusable workflows 会优先使用这个 secret 来：
+中央 reusable workflows 会优先使用 GitHub App token；如果没有配置成功，再回退到 `CLA_BOT_TOKEN`，最后才回退到 `GITHUB_TOKEN`。它们会用这个 token 来：
 
 - 在 PR 下评论签署提示与合规检查结果
 - 把签署记录写入 `cla-signatures` 分支

docs/repository-compliance-onboarding.md

@@ -11,18 +11,23 @@
    - `.github/workflows/cla.yml`
    - `.github/workflows/pr-compliance.yml`
 2. 为目标仓库创建未受保护的 `cla-signatures` 分支。
-3. 如果组织层限制 `GITHUB_TOKEN` 为只读，则在目标仓库创建 `CLA_BOT_TOKEN` secret。
-4. 在默认分支保护规则中把 `CLA` 和 `PR Compliance` 设为 required checks。
-5. 发起一个真实测试 PR，验证：
+3. 为目标仓库配置 GitHub App 凭据：
+   - repository variable `CLA_APP_ID`
+   - repository secret `CLA_APP_PRIVATE_KEY`
+4. 如需兼容旧流程，可临时保留仓库 secret `CLA_BOT_TOKEN` 作为回退。
+5. 在默认分支保护规则中把 `CLA` 和 `PR Compliance` 设为 required checks。
+6. 发起一个真实测试 PR，验证：
    - `PR Compliance` 自动触发
    - `CLA` 自动触发
    - 评论签署文本后，签名记录被写入 `cla-signatures`
+   - 评论作者与账本写入使用 GitHub App 身份
    - 两个检查都能通过
 
 ## 常见失败点
 
 - 没有 `cla-signatures` 分支，导致签署记录无法写入。
-- 组织层把 workflow token 限制为只读，但仓库没有设置 `CLA_BOT_TOKEN`。
+- workflow 调用里没有传 `app-id`，或仓库没有配置 `CLA_APP_ID` / `CLA_APP_PRIVATE_KEY`。
+- 组织层把 workflow token 限制为只读，同时仓库里既没有 GitHub App 私钥，也没有 `CLA_BOT_TOKEN` 兜底。
 - 默认分支没有 required checks，导致工作流虽然跑了，但不能真正阻塞合并。
 - PR 没有按模板填写，导致 `PR Compliance` 一直失败。
 

scripts/github/rollout-org-compliance.sh

@@ -334,6 +334,7 @@ jobs:
       issue-is-pr: \${{ github.event_name == 'issue_comment' && github.event.issue.pull_request != null }}
       comment-body: \${{ github.event.comment.body || '' }}
       default-branch: \${{ github.event.repository.default_branch }}
+      app-id: \${{ vars.CLA_APP_ID }}
       compliance-profile: ${compliance_profile}
 EOF
 }
@@ -369,6 +370,7 @@ jobs:
       pr-body: \${{ github.event.pull_request.body }}
       pr-author-login: \${{ github.event.pull_request.user.login }}
       default-branch: \${{ github.event.repository.default_branch }}
+      app-id: \${{ vars.CLA_APP_ID }}
       compliance-profile: ${compliance_profile}
 EOF
 }