ビルドスコープトークン

ビルドスコープトークン機能を使用すると、ビルド時に有効期限の短い VCS アクセストークンを自動的に取得できます。このトークンは既存の VCS 接続を通じて発行され、指定されたパラメーターに保存されます。ビルドステップでは、このトークンを使用して VCS 内のリソースにアクセスし、変更できます。

現時点では、トークンは GitHub アプリ接続を介してのみ発行できます。

トークンパラメーター

リポジトリスコープ

トークンはきめ細かく、ビルド機能設定で明示的にリストされているリポジトリへのアクセスのみを許可します。ユーザーまたは組織内のすべてのリポジトリへのアクセス権を持つグローバルトークンの作成はサポートされていません。

有効期間

トークンは最大 60 分間有効で、親ビルド（またはビルドチェーン）が完了すると自動的に期限切れになります。ビルドの実行時間が 1 時間を超える場合、トークンは使用される前に期限切れになる可能性があります。現在、ビルド中にトークンをリフレッシュすることはできません。

権限

トークンの権限は、発行元のアプリによって定義されます。例: 自動モードで作成された GitHub アプリ接続は、以下の権限を持つアプリを使用します。

コンテンツ: 書き込み
メタデータ: 読み取り
プルリクエスト: 読み取り
課題: 読み取り
メンバー: 読み取り
メール: 読み取り
ステータス: 書き込み
チェック: 書き込み

機能設定

ビルドスコープトークン機能を設定するには、次のプロパティを指定します：

タイプ: トークンの種類。現在、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 で作成したアプリには プルリクエスト: 読み取り 権限が付与されています。トークンはアプリの権限を継承するため、プルリクエストを作成するにはトークンを拡張する必要があります。
- 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 年 9 月 11 日