构建范围令牌

构建范围令牌功能允许构建自动获取短期 VCS 访问令牌。该令牌通过现有的 VCS 连接发放，并存储在指定参数中。然后构建步骤可以使用此令牌访问和修改 VCS 中的资源。

目前，令牌只能通过 GitHub 应用连接发放。

令牌参数

仓库作用域

令牌权限精细，仅授予在构建功能设置中明确列出的仓库访问权限。不支持创建具有用户或组织全部仓库访问权限的全局令牌。

存活时间

令牌最多有效 60 分钟，并在父构建（或构建链）完成时自动过期。如果构建运行超过一小时，令牌可能会在被使用前过期。当前，令牌无法在构建过程中进行刷新。

权限

令牌权限由发放应用定义。例如，采用自动的模式创建的 GitHub 应用连接会使用具有以下权限的应用：

contents: 写入
元数据: 读取
pull_requests: 读取
问题: 读取
成员: 读取
emails: 读取
状态: 写入
检查: 写入

功能设置

要配置构建范围令牌功能，请指定以下属性：

类型: 令牌类型。目前，仅支持 GitHub 应用令牌。
形参名称: 用于存储发放令牌参数的名称。 TeamCity 会在构建结束后清除该值并进行屏蔽，以防泄露（如在构建日志中）。
连接: 用于发放令牌的 TeamCity VCS 连接。 GitHub 应用安装令牌只能通过启用启用构建范围令牌的 GitHub 应用连接创建。
可访问仓库: 以换行符分隔的可由令牌访问的仓库列表。

以下示例展示如何使用 Kotlin DSL配置此功能：

object MyConfig : BuildType({
    name = "My Build Config"

    params {
        param("GhaToken", "unknown")
    }

    steps {
        // ...
    }
    features {
        gitHubAppBuildScopedToken {
            parameterName = "GhaToken"
            connectionId = "PROJECT_EXT_79"
            targetRepositories = """
                teamcity-samples-core-concepts
                HelpLinkGenerator
            """.trimIndent()
        }
    }})

  

示例

本示例演示如何使用构建范围令牌功能发送授权的 GitHub REST API请求以创建拉取请求。

创建一个带有未绑定构建配置的项目。未配置 VCS 根时，无法直接访问仓库，因此所有操作必须使用手动发放的令牌。
打开项目设置并导航到连接设置选项卡。
新建 GitHub 应用连接（请确保已选择启用构建范围令牌）。
默认情况下，在第 3 步中创建的应用拥有 pull_requests: 读取 权限。由于令牌继承应用权限，需扩展权限以创建拉取请求。
- 转到 https://github.com/settings/apps ，点击与 TeamCity 连接关联的应用旁的编辑。
- 打开权限和事件部分并展开仓库权限。
- 将拉取请求设置为“读取和写入”。
- 点击保存更改。
- 在账户或组织设置中确认已更新的权限：转到 https://github.com/settings/installations ，点击审核请求，然后接受新权限。
打开配置设置，并导航到参数设置选项卡。
创建用于存储所发放令牌的参数。
打开配置的构建功能选项卡并添加构建范围令牌功能。
- 参数名称：输入第 6 步中创建的参数名称。
- 连接：选择在第 3 步中创建的连接。
- 可访问仓库：指定将创建拉取请求的仓库。
添加命令行构建步骤，用于向 /repos/{owner}/{repo}/pulls端点发送 POST 请求。
运行一次构建。若配置正确，构建日志将包含关于已创建拉取请求的响应。

18:10     "url": "https://api.github.com/repos/OWNER/REPO/pulls/2",
18:10     "id": 34314330272,
18:10     "node_id": "PR_kwDOafdszPG887Mv-2g",
18:10     "html_url": "https://github.com/OWNER/REPO/pull/2",
18:10     "diff_url": "https://github.com/OWNER/REPO/pull/2.diff",
18:10     "patch_url": "https://github.com/OWNER/REPO/pull/2.patch",
18:10     "issue_url": "https://api.github.com/repos/OWNER/REPO/issues/2",
18:10     "number": 2,
18:10     "state": "open",
18:10     "locked": false,
18:10     "title": "Amazing new feature",
...

  

以下 Kotlin DSL 示例展示完整配置：

version = "2026.1"

project {
    buildType(Build)

    features {
        githubAppConnection {
            id = "PROJECT_EXT_79"
            displayName = "GHA with tokens"
            appId = "APP_ID"
            clientId = "CLIENT_ID"
            clientSecret = "CLIENT_SECRET"
            privateKey = "PRIVATE_KEY"
            ownerUrl = "https://github.com/OWNER"
            useUniqueCallback = true
            allowBuildScopedTokens = true
        }
    }
    
object Build : BuildType({
    name = "Build"

    params { param("GhaToken", "n/a") }

    steps {
        script {
            id = "simpleRunner_1"
            scriptContent = """
                curl -L \
                  -X POST \
                  -H "Accept: application/vnd.github+json" \
                  -H "Authorization: Bearer %GhaToken%" \
                  -H "X-GitHub-Api-Version: 2026-03-10" \
                  https://api.github.com/repos/OWNER/REPO/pulls \
                  -d '{"title":"Amazing new feature","body":"Please pull these awesome changes in!","head":"new-feature","base":"main"}'
            """.trimIndent()
        }
    }

    features {
        gitHubAppBuildScopedToken {
            parameterName = "GhaToken"
            connectionId = "PROJECT_EXT_79"
            targetRepositories = "REPO"
        }
    }
})

  

2026年 8月 6日