ビルドスコープトークン

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

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

トークンパラメーター

リポジトリのスコープ

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

生きる時が来た

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

許可

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

目次: 書く
メタデータ: 読み取り
pull_requests: 読み取り
課題: 読み取り
メンバー: 読み取り
メール: 読み取り
ステータス: 書く
チェック: 書く

機能設定

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

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

関連ページ：

接続を構成

TeamCity 接続は、外部サービスへのアクセスに必要な資格情報を保存します。このサードパーティサービスの種類に基づいて、2 つの主要な接続カテゴリがあります。VCS 接続これらの接続は、GitHub、GitLab、Bitbucket クラウドなどの VCS プロバイダーへのアクセスに必要な情報を保存します。これらの接続は、プロジェクト、ビルド構成、パイプラインを最も速く作成する方法を提供します。認証は自動的に処理されるため、リポジトリを選択するだけでビルドステップの設定を開始できます。接続が...

リフレッシュ可能なアクセストークンの管理

TeamCity には、機能上 VCS ホスティングプロバイダーへのアクセスを必要とするエンティティが複数あります:VCS ルート、コミットステータスパブリッシャー、プルリクエスト機能など。これらのエンティティは通常、複数の VCS 認証オプションを提供します。通常のユーザー名 / ログイン資格情報 — この認証方法は最も脆弱であるため、主要な VCS ホスティングプロバイダーによって徐々に廃止されています。個人アクセストークン (PAT) — VCS プロバイダー側で発行され、TeamCity...

インストールトークンエンドポイント: GitHub 認証トークンをプログラムで発行する方法

TeamCity/GitHub アプリ接続では、TeamCity が GitHub リポジトリにアクセスするための認証トークンを発行できます。これは通常、UI でプロジェクトを作成するか、VCS 認証トークンページで手動でトークンを発行すると自動的に行われます。エンドポイントは、UI を使用せずにこれらのトークンを生成する代替手段を提供します。これは、ビルド構成や VCS ルートを REST API 経由で設定する場合に特に便利です。これにより、ルートに必要なトークン ID をプログラムで取得できま...

Kotlin DSL

TeamCity では、バージョン管理で設定を XML 形式で保存するだけでなく、DSL (Kotlin 言語に基づく) で設定を保存することもできます。バージョン管理に保存された DSL を使用すると、プログラムで設定を定義できます。Kotlin は静的に型指定されるため、IDE で自動補完機能を自動的に受け取ります。これにより、利用可能な API オプションの発見がはるかに簡単になります。TeamCity での Kotlin DSL の使用に関するブログ投稿シリーズと推奨リファクタリングの記...

ビルド構成の作成と編集

ビルド構成とパイプラインは、実際の CI/CD ルーチンを表します。ビルド構成には、一連のビルドステップ（ビルド実行中に実行される基本操作）と、これらのステップの実行に必要な設定が格納されます。これらの設定には以下が含まれます。構成の動作をすばやく変更できるパラメーター。特定の条件が満たされたときに TeamCity が自動的に新しいビルドを開始できるようにするトリガー。構成の機能を拡張する機能を構築します。特定のビルドエージェントで構成ビルドを実行できるようにするエージェント要件。その他。ビル...

VCS ルートの設定

VCS ルートは、TeamCity ←→ VCS リポジトリ通信の基礎です。この不可欠な要素は、リポジトリのチェックアウト、コードソースのタグ付け、ビルドステータスの VCS への返信など、さまざまな操作を実行するために必要な VCS プロバイダーへの接続を定義します。VCS ルートには次の情報が保存されます。TeamCity がリモートファイルをプルおよびプッシュするために使用する URL を取得してプッシュします。ブランチ情報: TeamCity が追跡する必要があるリポジトリブランチのリスト...