# 在 GitHub Actions 中使用 gh api 调用 GraphQL 并解析结果
## 核心机制：设置认证与环境变量
要在 GitHub Actions 工作流步骤中调用 GitHub API，首先必须确保当前环境具备合法的访问凭证。GitHub CLI（gh）已预装在所有 GitHub 托管的运行器上，但执行任何命令前，需在步骤的环境变量（env）中显式设置 `GH_TOKEN`。
通常做法是将 `${{ secrets.GITHUB_TOKEN }}` 赋值给 `GH_TOKEN`。该令牌默认拥有足够的权限进行只读操作或创建资源，无需额外配置即可调用 GraphQL API 或执行其他子命令。
## 步骤一：构建 GraphQL 查询与 gh api 调用
在 YAML 工作流文件中，使用 `run` 步骤执行脚本时，可调用 `gh api graphql` 子命令。该命令接受 `-f` 参数传入 JSON 格式的变量（如仓库所有者、名称），并通过 `-F` 参数传递字符串变量。
查询语句需包裹在单引号内以避免 shell 解析干扰，同时使用 `--jq` 选项直接提取 JSON 中的特定字段（例如 `.data.repository.issues.totalCount`），将结果输出为纯文本字符串。这种管道式处理避免了手动编写复杂的 JSON 解析逻辑。
## 步骤二：将 API 返回数据写入环境变量
为了在后续步骤中使用查询结果，需利用 `echo 'KEY'=value >> $GITHUB_ENV` 语法将变量注入 GitHub Actions 的环境上下文。
例如，将 GraphQL 查询返回的开放问题数量存储为 `NUM_OPEN_ISSUES`。此操作必须在当前步骤完成，且目标变量名不能包含特殊字符或空格，否则会导致解析失败。
## 步骤三：在后续步骤中复用数据
一旦变量被写入 `$GITHUB_ENV`，它便可在同一工作流的其他步骤中被引用。例如，在创建新 Issue 时，可直接使用 `${NUM_OPEN_ISSUES}` 作为标题或正文的一部分，实现动态内容生成。
整个流程展示了如何在无外部依赖的情况下，通过 GitHub CLI 和内置环境变量机制，高效地完成数据获取、转换与复用任务。