tfc-list-runs

Terraform Cloud の実行一覧

Terraform Cloud のワークスペースから、実行を一覧表示して絞り込み、整形された出力を取得します。

使用する場面

シナリオ	このスキルを使用	代替手段
任意の TFC ワークスペースの最近の実行を一覧表示する	tfc-list-runs	-
ステータス、操作、ソースで実行を絞り込む	tfc-list-runs	-
組織全体の実行を一覧表示する	tfc-list-runs	-
コミット SHA またはユーザーで実行を検索する	tfc-list-runs	-
ID がわかっている単一の実行のステータスをすばやく確認する	tfc-run-status	1 つの実行の詳細には run-status を使用
実行の plan/apply ログ出力を表示する	tfc-run-logs	ログの内容には run-logs を使用
構造化された plan JSON を分析する	tfc-plan-json	リソース変更の詳細には plan-json を使用
既知の Forum Virium ワークスペースの実行を一覧表示する	tfc-workspace-runs	簡易アクセスには workspace-runs を使用

前提条件

export TFE_TOKEN="your-api-token"        # User or team token
export TFE_ADDRESS="app.terraform.io"    # Optional

基本コマンド

ワークスペースの最近の実行を一覧表示する

#!/bin/bash
set -euo pipefail

TOKEN="${TFE_TOKEN:?TFE_TOKEN not set}"
BASE_URL="https://${TFE_ADDRESS:-app.terraform.io}/api/v2"
WORKSPACE_ID="${1:?Usage: $0 <workspace-id> [limit]}"
LIMIT="${2:-10}"

curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/workspaces/$WORKSPACE_ID/runs?page[size]=$LIMIT" | \
  jq -r '.data[] | [
    .id,
    .attributes.status,
    .attributes."created-at"[0:19],
    (.attributes.message // "No message")[0:50]
  ] | @tsv' | \
  column -t -s $'\t'

ワークスペース名で実行を一覧表示する（org が必要）

TOKEN="${TFE_TOKEN:?TFE_TOKEN not set}"
BASE_URL="https://${TFE_ADDRESS:-app.terraform.io}/api/v2"
ORG="ForumViriumHelsinki"
WORKSPACE="infrastructure-gcp"

# Get workspace ID first
WS_ID=$(curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/organizations/$ORG/workspaces/$WORKSPACE" | \
  jq -r '.data.id')

# List runs
curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/workspaces/$WS_ID/runs?page[size]=10" | \
  jq -r '.data[] | "\(.id) | \(.attributes.status) | \(.attributes."created-at"[0:19]) | \(.attributes.message // "No message")"'

ステータスで絞り込む

TOKEN="${TFE_TOKEN:?TFE_TOKEN not set}"
BASE_URL="https://${TFE_ADDRESS:-app.terraform.io}/api/v2"
WORKSPACE_ID="ws-abc123"

# Filter by single status
curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/workspaces/$WORKSPACE_ID/runs?filter[status]=errored" | \
  jq -r '.data[] | "\(.id) | \(.attributes.status) | \(.attributes."created-at")"'

# Filter by multiple statuses
curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/workspaces/$WORKSPACE_ID/runs?filter[status]=errored,canceled" | \
  jq -r '.data[] | "\(.id) | \(.attributes.status)"'

ステータスグループで絞り込む

# Non-final runs (in progress)
curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/workspaces/$WORKSPACE_ID/runs?filter[status_group]=non_final"

# Final runs (completed)
curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/workspaces/$WORKSPACE_ID/runs?filter[status_group]=final"

# Discardable runs
curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/workspaces/$WORKSPACE_ID/runs?filter[status_group]=discardable"

plan-only の実行を含める

デフォルトでは、plan-only の実行は除外されます。含めるには、次のようにします。

curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/workspaces/$WORKSPACE_ID/runs?filter[operation]=plan_and_apply,plan_only,save_plan,refresh_only,destroy"

組織全体の実行を一覧表示する

TOKEN="${TFE_TOKEN:?TFE_TOKEN not set}"
BASE_URL="https://${TFE_ADDRESS:-app.terraform.io}/api/v2"
ORG="ForumViriumHelsinki"

# All runs in org (limited info, no total count)
curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/organizations/$ORG/runs?page[size]=20" | \
  jq -r '.data[] | "\(.id) | \(.attributes.status)"'

# Filter by workspace names
curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/organizations/$ORG/runs?filter[workspace_names]=infrastructure-gcp,infrastructure-github"

整形された出力の例

リソース変更を含むテーブル形式

curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/workspaces/$WORKSPACE_ID/runs?page[size]=10&include=plan" | \
  jq -r '
    ["RUN_ID", "STATUS", "ADD", "CHG", "DEL", "CREATED"],
    (.data[] | [
      .id,
      .attributes.status,
      (.relationships.plan.data.id as $pid |
        (.included[] | select(.id == $pid) | .attributes."resource-additions" // 0)),
      (.relationships.plan.data.id as $pid |
        (.included[] | select(.id == $pid) | .attributes."resource-changes" // 0)),
      (.relationships.plan.data.id as $pid |
        (.included[] | select(.id == $pid) | .attributes."resource-destructions" // 0)),
      .attributes."created-at"[0:19]
    ]) | @tsv' | column -t

後続処理用の JSON 出力

curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/workspaces/$WORKSPACE_ID/runs?page[size]=5" | \
  jq '[.data[] | {
    id: .id,
    status: .attributes.status,
    created: .attributes."created-at",
    message: .attributes.message,
    has_changes: .attributes."has-changes",
    auto_apply: .attributes."auto-apply"
  }]'

使用可能な絞り込みパラメーター

パラメーター	説明	値の例
filter[status]	実行ステータス	applied、errored、planned、canceled
filter[status_group]	ステータスグループ	non_final、final、discardable
filter[operation]	操作の種類	plan_and_apply、plan_only、destroy
filter[source]	実行ソース	tfe-api、tfe-ui、tfe-configuration-version
filter[timeframe]	期間	2024、year、month
search[user]	VCS ユーザー名	ユーザー名の文字列
search[commit]	コミット SHA	SHA 文字列
search[basic]	複合検索	検索語

実行ステータス

終了状態： applied、planned_and_finished、discarded、errored、canceled、force_canceled、policy_soft_failed

未終了状態： pending、planning、planned、cost_estimating、policy_checking、confirmed、applying など

ページネーション

# Page 2 with 20 items per page
curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/workspaces/$WORKSPACE_ID/runs?page[number]=2&page[size]=20"

# Check pagination info
curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/workspaces/$WORKSPACE_ID/runs" | \
  jq '.meta.pagination'

レート制限

/runs エンドポイントには、特殊なレート制限として1 分あたり 30 リクエストが設定されています（ほとんどのエンドポイントのように 1 秒あたり 30 リクエストではありません）。スクリプトを作成する際は、この点を考慮してください。

関連項目

• tfc-run-logs：実行の plan/apply ログを取得
• tfc-run-status：実行のステータスをすばやく確認
• tfc-workspace-runs：既知のワークスペース向けの便利なラッパー