プロジェクトの管理

TeamCity では、プロジェクトによってビルド構成とサブプロジェクトが整理されます。 teamcity project コマンドグループを使用すると、プロジェクトの参照、VCS ルートの管理、パラメーターの管理、バージョン管理された設定のセキュアトークンの処理、プロジェクト構成のエクスポートまたは検証を行うことができます。

プロジェクトの一覧表示

すべての TeamCity プロジェクトを表示：

teamcity project list

親プロジェクトでフィルタリング:

teamcity project list --parent MyProject

結果を制限し、JSON として出力します。

teamcity project list --limit 20
teamcity project list --json
teamcity project list --json=id,name,parentProjectId,webUrl

  

project list フラグ

フラグ	説明
`-p`, `--parent`	親プロジェクト ID でフィルタリング
`-n`, `--limit`	表示するプロジェクトの最大数
`--json`	JSON として出力します。使用可能なフィールドを一覧表示するには `--json=` を使用し、特定のフィールドを表示するには `--json=f1,f2` を使用します。

プロジェクトツリー

サブプロジェクトとビルド構成を含むプロジェクト階層をツリーとして表示します。

teamcity project tree

特定のサブツリーを表示します。

teamcity project tree MyProject

ビルド構成を非表示にしてプロジェクト構造のみを表示します。

teamcity project tree --no-jobs

ツリーの深さを制限します。

teamcity project tree --depth 2

project tree フラグ

フラグ	説明
`--no-jobs`	ビルド構成を非表示にしてプロジェクトのみを表示する
`-d`, `--depth`	ツリーの深さを制限する (0 = 無制限)

プロジェクトの作成

ルートプロジェクトに新しいプロジェクトを作成します。

teamcity project create MyProject

明示的な ID を使用して作成します。

teamcity project create "My Project" --id MyProject

親プロジェクトに作成する:

teamcity project create MyProject --parent ParentProject

作成したプロジェクトを JSON 形式で出力します（スクリプト作成に便利です）。

teamcity project create MyProject --json

project create フラグ

フラグ	説明
`--id`	明示的なプロジェクト ID。デフォルトでは、TeamCity がお名前から自動生成した ID が使用されます。
`-p`, `--parent`	親プロジェクト ID。デフォルトは `_ルート` です。
`--json`	JSON 形式で出力
`-w`, `--web`	作成後、ブラウザーで新しいプロジェクトを開きます

プロジェクト詳細の表示

プロジェクトの詳細を表示します。

teamcity project view MyProject

ブラウザーでプロジェクトページを開きます。

teamcity project view MyProject --web

JSON として出力:

teamcity project view MyProject --json

VCS ルートの管理

VCS ルートは、TeamCity とバージョン管理リポジトリ間の接続を定義します。これらはプロジェクトレベルのエンティティであり、継承を通じて子プロジェクトから参照可能です。

VCS ルートの一覧表示

teamcity project vcs list --project MyProject
teamcity project vcs list --project MyProject --json
teamcity project vcs list --project MyProject --plain

   

VCS ルート詳細の表示

teamcity project vcs view MyProject_GitHubRepo
teamcity project vcs view MyProject_GitHubRepo --json
teamcity project vcs view MyProject_GitHubRepo --web

   

view コマンドは、すべての VCS ルートプロパティを人間が読みやすいラベルで表示します。セキュリティ保護されたプロパティ (パスワード、パスフレーズ) は ******** のようにマスクされます。

VCS ルートの作成

対話型ウィザードまたはフラグを使用して、Git VCS ルートを作成します。

teamcity project vcs create --project MyProject

ウィザードはリポジトリの URL、表示名、認証方法の入力を求めます。サポートされている認証方法は 6 種類です。

# Anonymous (public repos)
teamcity project vcs create --url https://github.com/org/repo.git --auth anonymous

# Password / Personal Access Token
teamcity project vcs create --url https://github.com/org/repo.git \
  --auth password --username oauth2 --password ghp_xxx

# SSH key uploaded to TeamCity
teamcity project vcs create --url git@github.com:org/repo.git \
  --auth ssh-key --ssh-key-name my-deploy-key

# SSH key from the build agent's default key
teamcity project vcs create --url git@github.com:org/repo.git --auth ssh-agent

# SSH key at a custom path on the build agent
teamcity project vcs create --url git@github.com:org/repo.git \
  --auth ssh-file --key-path /path/to/key

# Access token via a project connection
teamcity project vcs create --url https://github.com/org/repo.git \
  --auth token --connection-id PROJECT_EXT_1

   

デフォルトでは、このコマンドは作成前に接続テストを実行します。 --no-test でスキップします:

teamcity project vcs create --url https://github.com/org/repo.git --auth anonymous --no-test

   

vcs create フラグ

フラグ	説明
`--url`	リポジトリ URL
`--name`	表示用のお名前 (省略した場合は URL から自動生成)
`-p`, `--project`	プロジェクト ID (デフォルト: _ルート)
`--auth`	認証メソッド: `パスワード`、 `ssh-key`、 `SSH エージェント`、 `ssh-file`、 `token`、 `匿名`
`--username`	ユーザー名 (パスワード認証用)
`--password`	パスワードまたは個人アクセストークン
`--stdin`	stdin からパスワードを読み取る
`--ssh-key-name`	TeamCity にアップロードされた SSH 鍵のお名前
`--key-path`	ビルドエージェント上の SSH 鍵ファイルへのパス
`--passphrase`	SSH 鍵のパスフレーズ
`--connection-id`	OAuth 接続 ID
`--branch`	デフォルトブランチ (デフォルト: `refs/heads/main`)
`--branch-spec`	ブランチ仕様
`--no-test`	作成前に接続テストをスキップ

VCS ルート接続のテスト

既存の VCS ルートがリポジトリに接続できるかどうかをテストします。

teamcity project vcs test MyProject_GitHubRepo

VCS ルートの削除

teamcity project vcs delete MyProject_GitHubRepo
teamcity project vcs delete MyProject_GitHubRepo --yes  # skip confirmation

SSH 鍵の管理

プロジェクトにアップロードされた SSH キーは、VCS ルート認証（TEAMCITY_SSH_KEY 認証方式）に使用できます。キーは子プロジェクトに継承されます。

SSH 鍵の一覧表示

teamcity project ssh list --project MyProject
teamcity project ssh list --project MyProject --json

SSH 鍵ペアの生成

TeamCity で ed25519 または RSA 鍵ペアを直接生成し、公開鍵を出力します：

teamcity project ssh generate --name deploy-key --project MyProject
teamcity project ssh generate --name deploy-key --type rsa --project MyProject

印刷した公開鍵を、Git ホスティングプロバイダのデプロイキーとして追加してください。

SSH 鍵のアップロード

teamcity project ssh upload ~/.ssh/id_ed25519 --project MyProject
teamcity project ssh upload key.pem --name my-deploy-key --project MyProject

SSH 鍵の削除

teamcity project ssh delete my-deploy-key --project MyProject
teamcity project ssh delete my-deploy-key --project MyProject --yes

プロジェクトとのつながり

接続（OAuth プロバイダー、Docker レジストリ、クラウド統合）はプロジェクトレベルで設定されます。 TeamCity は個々のジョブに資格情報を保存せずに外部サービスと通信でき、CLI で一覧表示、作成、認証、削除できます。

TeamCity の完全なリファレンスについては、接続の構成を参照してください。

接続の一覧表示

teamcity project connection list --project MyProject
teamcity project connection list --project MyProject --json

最初の列には接続 ID（例: PROJECT_EXT_42 ）が表示されます。この ID は、 authorize、 削除、 vcs create --auth token が使用するものです。

GitHub アプリ接続の作成

プロジェクトに GitHub アプリを登録してください。 GitHub アプリは自身として認証を行うため（ユーザーごとのトークンは不要）、ユーザーコンテキスト OAuth を必要としない CI ワークフローに適しています。

対話モードでは、CLI は GitHub のマニフェストフローを通じてまったく新しいアプリを登録します — ブラウザーが開き、作成をクリックすると、資格情報が自動的に戻ります：

teamcity project connection create github-app -p Backend
teamcity project connection create github-app -p Backend --owner my-org

すでに GitHub アプリをお持ちの場合は、 --no-manifest を通過し、ご自身で認証情報を入力してください。

teamcity project connection create github-app -p Backend --no-manifest \
    --name "Backend" --app-id 1234567 --client-id Iv1.abc \
    --private-key-file ./key.pem --stdin <<<"$CLIENT_SECRET"

   

作成後、CLI は authorize を実行するように促し、現在のユーザーがアプリにバインドされたトークンを取得します。 --no-authorize を使用してプロンプトをスキップします。

Docker レジストリ接続の作成

ジョブがシークレットをインライン化せずにイメージをプルおよびプッシュできるように、Docker レジストリ認証情報を登録します。

teamcity project connection create docker -p Backend

非対話型環境（CI/CD）では、パスワードを標準入力から渡してください。

echo "$DOCKER_TOKEN" | teamcity project connection create docker -p Backend \
    --name GHCR --url https://ghcr.io --username my-org --stdin

接続の認証

OAuth スタイルの接続 (GitHub アプリ、Bitbucket、GitLab、…) では、TeamCity がそのユーザーとしてアップストリームを呼び出せるようになる前に、ユーザーごとの認可ステップが必要です。これは、たとえば vcs create --auth token が接続を介してリポジトリを検証する前に必要となります。

teamcity project connection authorize PROJECT_EXT_42 -p Backend

このコマンドはブラウザーを開いて OAuth フローを完了させ、生成されたトークンを現在のユーザーに関連付けられて保存します。ユーザー OAuth フローのない接続タイプ（Docker、AWS）ではエラーが返されます。

接続の削除

teamcity project connection delete PROJECT_EXT_42 -p Backend
teamcity project connection delete PROJECT_EXT_42 -p Backend --force

対話型の確認プロンプトをスキップするには、 --force (または -f) を渡します - スクリプトで便利です。

プロジェクトパラメーターの管理

プロジェクトパラメーターは、プロジェクト内のすべてのビルド構成に継承されます。ジョブパラメーターと全く同じように機能します。

パラメーターの一覧表示

teamcity project param list MyProject
teamcity project param list MyProject --json

パラメーター値の取得

teamcity project param get MyProject VERSION

パラメーターの設定

teamcity project param set MyProject VERSION "2.0.0"
teamcity project param set MyProject SECRET_KEY "my-secret-value" --secure

パラメーターの削除

teamcity project param delete MyProject MY_PARAM

セキュアトークン

セキュアトークンを使用すると、バージョン管理下に置かずに、バージョン管理された設定内の機密値（パスワード、API キーなど）を参照できます。実際の値は TeamCity に安全に保存され、 credentialsJSON:<token> 識別子を使用して参照されます。

セキュアトークンの保存

機密値を保存し、トークン参照を受け取ります。

# Interactive prompt for the value
teamcity project token put MyProject

# Pass the value directly
teamcity project token put MyProject "my-secret-password"

# Read from stdin (useful for piping)
echo -n "my-secret" | teamcity project token put MyProject --stdin

   

このコマンドは credentialsJSON:<uuid> 形式のトークンを返します。このトークンをバージョン管理された設定ファイルで使用してください。

セキュアトークン値の取得

セキュアトークンの元の値を取得します。

teamcity project token get MyProject "credentialsJSON:abc123-def456..."
teamcity project token get MyProject "abc123-def456..."

バージョン対応設定

プロジェクト設定のエクスポート

プロジェクト設定を、Kotlin DSL または XML 構成を含む ZIP アーカイブとしてエクスポートします。

# Export as Kotlin DSL (default)
teamcity project settings export MyProject

# Export as Kotlin DSL explicitly
teamcity project settings export MyProject --kotlin

# Export as XML
teamcity project settings export MyProject --xml

# Save to a specific file
teamcity project settings export MyProject -o settings.zip

# Use relative IDs in the export
teamcity project settings export MyProject --relative-ids

   

エクスポートされたアーカイブは、CI/CD 構成のバージョン管理、TeamCity インスタンス間での設定の移行、設定をコードとしてレビューするために使用できます。

settings export フラグ

フラグ	説明
`--kotlin`	Kotlin DSL としてエクスポート (デフォルト)
`--xml`	XML 形式でエクスポート
`-o`, `--output`	出力ファイルパス（デフォルト）: `projectSettings.zip`)
`--relative-ids`	エクスポートされた設定では相対 ID を使用する (デフォルトで有効)

バージョン対応設定の同期ステータスの表示

プロジェクトのバージョン管理された設定の同期状態を確認します。

teamcity project settings status MyProject
teamcity project settings status MyProject --json

これは、バージョン管理設定が有効になっているかどうか、現在の同期状態、最後に正常に同期されたタイムスタンプ、VCS のルートとフォーマット情報、前回の同期試行で発生したエラーを表示します。

Kotlin DSL の検証

TeamCity 構成ジェネレーターを実行して Kotlin DSL 構成を検証します：

teamcity project settings validate
teamcity project settings validate ./path/to/.teamcity
teamcity project settings validate --verbose

   

このコマンドは、現在のディレクトリまたはその親ディレクトリにある .teamcity ディレクトリを自動的に検出します。 DSL ディレクトリに Maven (mvn) が存在する場合はそれを使用し、存在する場合は Maven ラッパー (mvnw) を使用します。

2026 年 9 月 11 日