跳到主要内容

远程认证

注册表 和 kmpkg_from_git() 会直接调用 Git 命令行工具拉取远程资源。部分资源可能限制匿名访问，需要通过认证或提供凭据才能访问。

以下所有策略的核心目标一致：确保 git clone https://.... 命令无需人工交互即可执行成功。这让 kmpkg 无需适配具体的认证方案细节，同时能兼容未来新增的安全增强措施，保证向前兼容性。

预填充 Git 凭据​

你可以通过 git credential approve 命令预填充 Git 凭据：

PowerShell 示例​

"url=https://github.com`npath=kumose/kmpkg`nusername=unused`npassword=$MY_PAT`n" | git credential approve

Bash 示例​

echo "url=https://github.com"$'\n'"path=kumose/kmpkg"$'\n'"username=unused"$'\n'"password=$MY_PAT"$'\n' | git credential approve

承载认证（Bearer auth）​

对于需要承载认证的系统，可通过 git config 进行配置：

信息

这些配置项必须通过 --global 参数设置

git config --global --unset-all http.<uri>.extraheader
git config --global http.<uri>.extraheader "AUTHORIZATION: bearer <System_AccessToken>"

<uri> 可根据实际场景填写，例如 https://dev.azure.com/MYORG/。更多细节请参考 git config 官方文档。

（原始来源：构建过程中认证 Git 仓库的最佳方式）。

Azure DevOps 用户注意：你可能需要启用 Azure 作业授权范围的访问权限，并在 YAML 流水线中引用目标仓库：

resources: 
  repositories:
    - repository: <友好名称>
      type: git
      name: <组织>/<仓库>
      tag: tags/<标签>

...

jobs:
 - job: Build
   uses:
     repositories: [<友好名称>]

通过环境变量传递凭据（不推荐）​

你可以通过 KMPKG_KEEP_ENV_VARS 或 KMPKG_ENV_PASSTHROUGH_UNTRACKED 环境变量传递凭据：

export KMPKG_KEEP_ENV_VARS=MY_TOKEN_VAR
export MY_TOKEN_VAR=abc123

随后可在私有端口中，通过 kmpkg_from_git()、kmpkg_from_github() 或 kmpkg_from_gitlab() 辅助函数使用该凭据：

示例 1：kmpkg-from-git-example/portfile.cmake​

# kmpkg-from-git-example/portfile.cmake
set(MY_TOKEN_VAR "")
if(DEFINED ENV{MY_TOKEN_VAR})
    set(MY_TOKEN_VAR "$ENV{MY_TOKEN_VAR}@")
endif()
kmpkg_from_git(
    URLS "https://${MY_TOKEN_VAR}host.com/normal/url/path"
    ...
)

示例 2：kmpkg-from-github-example/portfile.cmake​

# kmpkg-from-github-example/portfile.cmake
kmpkg_from_github(
    AUTHORIZATION_TOKEN "$ENV{MY_TOKEN_VAR}"
)

对于私有端口，我们建议使用 kmpkg_from_git() 而非 kmpkg_from_github()/kmpkg_from_gitlab()，并优先采用上文的“预填充凭据”方案。

传递 Jenkins gitUsernamePassword 凭据​

从 Jenkins 向 GitHub 进行 Git 认证，最简单且最安全的方式是使用 GitHub App，并配合以下配置：

withCredentials([gitUsernamePassword(credentialsId: 'jenkins-github-app')]) {
  withEnv(['KMPKG_KEEP_ENV_VARS=GIT_ASKPASS']) {
    bat 'cmake'
  }
}

该配置会将 GIT_ASKPASS 环境变量设置为一个辅助脚本的路径（该脚本用于响应 Git 凭据查询），并指示 kmpkg 保留此环境变量。其中的密码为 GitHub App 令牌，有效期为 1 小时。