mcpField
T
tfc-list-runs

tfc-list-runs

github.com/laurigates云与 DevOps5956 次安装1 天前更新
代码仓库

关于 tfc-list-runs

用于列出和筛选 Terraform Cloud 工作区或组织运行记录的技能。它支持按状态、操作、来源、提交 SHA 或用户搜索，并可输出格式化结果供查看或后续处理。

主要功能

  1. 01列出工作区或组织的运行记录
  2. 02按状态、操作和来源筛选
  3. 03按提交 SHA 或用户搜索
  4. 04以表格或 JSON 格式输出
  5. 05分页浏览运行记录

适用场景

  1. 01查看工作区近期运行记录
  2. 02查找出错或指定状态的运行
  3. 03定位关联某次提交或用户的运行
  4. 04在脚本中处理运行数据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/laurigates/claude-plugins --skill tfc-list-runs

安装后在 Claude Code 中输入/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使用 run-status 查看单次运行的详情
查看某次运行的计划/应用日志输出tfc-run-logs使用 run-logs 查看日志内容
分析结构化计划 JSONtfc-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"
包含仅计划的运行

默认情况下，不包含仅计划的运行。若要包含这些运行：

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]提交 SHASHA 字符串
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 端点有特殊的速率限制：每分钟 30 个请求（大多数端点的限制是每秒 30 个请求）。编写脚本时请做好相应安排。

另请参阅

  • tfc-run-logs：获取某次运行的计划/应用日志
  • tfc-run-status：快速查看某次运行的状态
  • tfc-workspace-runs：便捷访问已知工作区

评论

支持 Markdown