向 GitHub API 进行身份验证

法律通告

概述

可以使用 GitHub App 或 personal access token (classic) 向 GitHub API 验证 Actions Runner Controller (ARC)。

使用 GitHub App 对 ARC 进行身份验证

1. 创建由组织拥有的 GitHub App。 有关详细信息，请参阅“注册 GitHub 应用”。 按如下所示配置 GitHub App。

   1. 对于“主页 URL”，请输入 https://github.com/actions/actions-runner-controller。

   2. 在“权限”下，单击“存储库权限”。 然后使用下拉菜单选择以下访问权限。

      • 管理：读取和写入

        注意

        Administration: Read and write 仅在配置 Actions Runner Controller 以在存储库范围内注册时必需。 在组织范围内注册时，它不是必需的。

      • 元数据：只读

   3. 在“权限”下，单击“组织权限”。 然后使用下拉菜单选择以下访问权限。

      • 自托管运行器：读取和写入

2. 创建 GitHub App 后，在 GitHub App 页面上，记下“应用 ID”的值。 稍后会用到此值。

3. 在“私钥”下，单击“生成私钥”并保存 .pem 文件。 稍后会用到此密钥。

4. 在页面左上角的菜单中，单击“安装应用”，然后单击组织旁边的“安装”，以在组织上安装应用 。

5. 确认组织的安装权限后，记下应用安装 ID。 稍后将使用它。 可以在应用安装页上找到应用安装 ID，该页的 URL 格式如下：

   https://HOSTNAME/organizations/ORGANIZATION/settings/installations/INSTALLATION_ID

6. 将应用 ID、安装 ID 以及前面步骤中下载的 .pem 私钥文件作为机密注册到 Kubernetes。

   若要使用 GitHub App 的值创建 Kubernetes 机密，请运行以下命令。

   注意

   在安装 gha-runner-scale-set 图表的同一命名空间中创建机密。 在此示例中，命名空间是 arc-runners，与快速入门文档对应。 有关详细信息，请参阅“操作运行器控制器快速入门”。

   Bash

   kubectl create secret generic pre-defined-secret \
      --namespace=arc-runners \
      --from-literal=github_app_id=123456 \
      --from-literal=github_app_installation_id=654321 \
      --from-literal=github_app_private_key='-----BEGIN RSA PRIVATE KEY-----********'
   

   然后在 values.yaml 文件的副本中使用 githubConfigSecret 属性，将机密名称作为引用传递。

   githubConfigSecret: pre-defined-secret
   

有关其他 Helm 配置选项，请参阅 ARC 存储库中的 values.yaml。

使用 personal access token (classic) 对 ARC 进行身份验证

ARC 可以使用 personal access tokens (classic) 注册自托管运行器。

1. 使用所需范围创建 personal access token (classic)。 根据你是在存储库、组织或企业级别注册运行器，所需的范围会有所不同。 若要详细了解如何创建 personal access token (classic)，请参阅“管理个人访问令牌”。

   下面是 ARC 运行器所需的 personal access token 范围的列表。

   • 存储库运行器：repo
   • 组织运行器：admin:org
   • 企业运行器：manage_runners:enterprise

2. 若要使用 personal access token (classic) 的值创建 Kubernetes 机密，请运行以下命令。

   注意

   在安装 gha-runner-scale-set 图表的同一命名空间中创建机密。 在此示例中，命名空间是 arc-runners，与快速入门文档对应。 有关详细信息，请参阅“操作运行器控制器快速入门”。

   Bash

   kubectl create secret generic pre-defined-secret \
      --namespace=arc-runners \
      --from-literal=github_token='YOUR-PAT'
   

3. 在 values.yaml 文件的副本中，将机密名称作为引用传递。

   githubConfigSecret: pre-defined-secret
   

   有关其他 Helm 配置选项，请参阅 ARC 存储库中的 values.yaml。

使用 fine-grained personal access token 对 ARC 进行身份验证

ARC 可以使用 fine-grained personal access tokens 注册自托管运行器。

1. 使用所需范围创建 fine-grained personal access token。 所需范围会有所不同，具体取决于你是在仓库还是在组织级别注册运行器。 若要详细了解如何创建 fine-grained personal access token，请参阅“管理个人访问令牌”。

   下面是 ARC 运行器所需的 personal access token 范围的列表。

   • 仓库运行器：

     • 管理：读取和写入

   • 组织运行器：

     • 管理****：只读
     • 自托管运行器：读取和写入

2. 若要使用 fine-grained personal access token 的值创建 Kubernetes 机密，请运行以下命令。

   注意

   在安装 gha-runner-scale-set 图表的同一命名空间中创建机密。 在此示例中，命名空间是 arc-runners，与快速入门文档对应。 有关详细信息，请参阅“操作运行器控制器快速入门”。

   Bash

   kubectl create secret generic pre-defined-secret \
      --namespace=arc-runners \
      --from-literal=github_token='YOUR-PAT'
   

3. 在 values.yaml 文件的副本中，将机密名称作为引用传递。

   githubConfigSecret: pre-defined-secret
   

   有关其他 Helm 配置选项，请参阅 ARC 存储库中的 values.yaml。

使用保管库机密对 ARC 进行身份验证

从 gha-runner-scale-set 版本 0.12.0 开始，ARC 支持从外部保管库中检索 GitHub 凭据。 Vault 集成是按运行器规模集配置的。 这意味着你可以根据自身的安全性和运营需求，对某些规模集使用 Kubernetes 机密，而对其他规模集使用基于保管库的机密。

启用保管库集成

为某个运行器规模集启用保管库集成：

1. 将 values.yaml 文件中的 githubConfigSecret 字段设置为存储在保管库中的密钥名称****。 该值必须为字符串类型。
2. 取消注释并配置 values.yaml 文件中的 keyVault 部分，填写相应的提供程序和访问详情。
3. 向控制器和监听器提供所需的证书 (.pfx)****。 你可以通过以下方式完成此操作：将证书包含在控制器镜像中并重新构建，或使用 listenerTemplate 和 controllerManager 字段将证书作为卷装载到控制器和监听器中。

机密格式

存储在 Azure Key Vault 中的机密必须采用 JSON 格式。 具体结构取决于所使用的身份验证类型：

示例：GitHub 令牌

{
  "github_token": "TOKEN"
}

示例：GitHub 应用

{
  "github_app_id": "APP_ID_OR_CLIENT_ID",
  "github_app_installation_id": "INSTALLATION_ID",
  "github_app_private_key": "PRIVATE_KEY"
}

为保管库集成配置 values.yaml

证书以 .pfx 文件格式存储，并装载到容器的 /akv/cert.pfx 路径中。 下面的示例展示了如何配置 keyVault 部分以使用该证书进行身份验证：

keyVault:
  type: "azure_key_vault"
  proxy:
    https:
      url: "PROXY_URL"
      credentialSecretRef: "PROXY_CREDENTIALS_SECRET_NAME"
    http: {}
    noProxy: []
  azureKeyVault:
    clientId: <AZURE_CLIENT_ID>
    tenantId: <AZURE_TENANT_ID>
    url: <AZURE_VAULT_URL>
    certificatePath: "/akv/cert.pfx"

向控制器和监听器提供证书

ARC 需要一个 .pfx 证书来进行保管库的身份验证。 在控制器安装期间，必须将该证书提供给控制器和监听器两个组件。 你可以通过在 values.yaml 文件中使用 controllerManager 和 listenerTemplate 字段，将证书作为卷进行装载：

volumes:
  - name: cert-volume
    secret:
      secretName: my-cert-secret
volumeMounts:
  - mountPath: /akv
    name: cert-volume
    readOnly: true

listenerTemplate:
  volumeMounts:
    - name: cert-volume
      mountPath: /akv/certs
      readOnly: true
  volumes:
    - name: cert-volume
      secret:
        secretName: my-cert-secret

下面的代码是规模集 values.yml 文件的示例。

listenerTemplate:
  spec:
    containers:
      - name: listener
        volumeMounts:
          - name: cert-volume
            mountPath: /akv
            readOnly: true
    volumes:
      - name: cert-volume
        secret:
          secretName: my-cert-secret

法律通告

部分内容改编自 Apache-2.0 许可证下的 https://github.com/actions/actions-runner-controller/ ：

Copyright 2019 Moto Ishizawa

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.