用途
本技能提供将 GraphQL Inspector 集成到 CI/CD 流水线中的专家知识，用于自动化 schema 与操作（operation）校验。适用于搭建自动化 schema 验证、在 CI 中配置破坏性变更检测、构建 GraphQL 质量门禁、集成 GitHub/GitLab 工作流、为 schema 变更生成 PR 评论，以及用破坏性变更阻止部署等场景。
主要能力
GraphQL Inspector 提供多种 CI/CD 集成选项，从简单 CLI 命令到专用 GitHub App 与 Actions。
GitHub App
官方 GitHub App 提供最丰富的集成，功能包括：在拉取请求上自动执行 schema diff、以评论形式给出破坏性变更摘要、在存在破坏性变更时阻止合并、自动与基础分支比较。安装方式为从 GitHub Marketplace 安装，并配置 .github/graphql-inspector.yaml，示例配置包含 schema、branch、endpoint、diff 以及 Slack 通知等字段。
GitHub Actions
资料给出多种工作流示例：
- 基础 Schema Diff：在 pull_request 触发、路径匹配 schema.graphql 或 **/*.graphql 时，检出代码（fetch-depth: 0）、安装 Node.js 20、全局安装
@graphql-inspector/cli，然后运行graphql-inspector diff 'git:origin/main:schema.graphql' 'schema.graphql'。 - 完整验证流水线：依次执行 Schema Diff（带
--onlyBreaking，continue-on-error）、Validate Operations（graphql-inspector validate 'src/**/*.graphql' 'schema.graphql' --maxDepth 10）、Audit Operations（graphql-inspector audit 'src/**/*.graphql'），并在 diff 失败时通过 actions/github-script 在 PR 上创建评论。 - 多 Schema 矩阵策略：使用 matrix 对 users、orders、products 等多个服务的 schema 分别执行 diff。
GitLab CI
资料给出基础配置示例，包含 validate 阶段、node:20 镜像、安装 CLI，并分别执行 graphql-inspector diff 与 graphql-inspector validate，通过 rules 限定在 /*.graphql 或 src//*.tsx 变更时触发。还给出合并请求评论示例：捕获 diff 输出，若包含 "Breaking" 则通过 GitLab API 在 MR 上创建说明破坏性变更的评论。
CircleCI
资料给出 version 2.1 配置示例，使用 cimg/node:20.0 镜像，依次执行安装 CLI、Schema Diff、Validate Operations，并在 workflows 中运行 graphql-check 作业。
配置文件
可创建 .graphql-inspector.yaml 统一配置所有命令，涵盖 schema（path 或 federation）、diff（rules、failOnBreaking、failOnDangerous、notifications）、validate（documents、maxDepth、maxAliasCount、maxComplexityScore）、audit（documents）等。
高级模式
资料包含：缓存 npm 依赖以加速 CI；在破坏性变更时通过 slackapi/slack-github-action 发送 Slack 通知；在仓库设置中配置必需状态检查（Settings → Branches → Branch protection rules，启用 Require status checks to pass，并加入 GraphQL Schema Check 作业）；以及通过 GRAPHQL_INSPECTOR_HEADERS 环境变量携带认证头，对生产环境远程 schema 执行 diff。
最佳实践
资料列出：快速失败（使用 --onlyBreaking 聚焦关键问题）、缓存安装、将 schema 验证设为必需检查、用分支保护阻止破坏性变更合并、通知团队、在评论中链接迁移指南、针对多环境验证、并行运行 diff/validate/audit。
限制与故障排查
资料给出常见问题：git refs 出现 "Permission denied" 时需设置 fetch-depth: 0 获取完整历史；CI 中 "Schema not found" 需检查文件路径、确认 schema 已提交（未被 gitignore）、必要时使用绝对路径；本地与 CI 结果不一致需确保 GraphQL Inspector 版本、Node.js 版本一致，并确认 git refs 可访问。
使用方式
核心安装命令为 npm install -g @graphql-inspector/cli，主要命令包括 graphql-inspector diff、graphql-inspector validate、graphql-inspector audit。具体配置与工作流示例见上文各平台章节。