⚡

GraphQLInspectorCI/CD自动化验证技能Skill graphql-inspector-ci

这个技能用于在CI/CD流水线中集成GraphQL Inspector，实现自动化的GraphQL模式和操作验证，检测破坏性变化，确保API兼容性，并支持GitHub Actions、GitLab CI等多种工具集成。关键词包括：GraphQL，CI/CD，自动化验证，模式检查，破坏性变化，API兼容性，GitHub Actions，GitLab CI，持续集成，自动化测试。

CI/CD 0 次安装 0 次浏览 更新于 3/25/2026

名称: graphql-inspector-ci 用户可调用: false 描述: 当在CI/CD流水线、GitHub Actions或GitLab CI中设置GraphQL Inspector进行自动模式验证时使用。 允许工具: [Read, Write, Edit, Bash, Glob, Grep]

GraphQL Inspector - CI/CD集成

专业知识，用于在持续集成和部署流水线中集成GraphQL Inspector，实现自动模式和操作验证。

概述

GraphQL Inspector提供多种CI/CD集成选项，从简单的CLI命令到专用的GitHub Apps和Actions。此技能涵盖所有自动化GraphQL质量保证的集成模式。

GitHub App

官方GitHub App提供最丰富的集成：

功能

  • 在拉取请求中自动模式差异
  • 评论包含破坏性变化摘要
  • 在破坏性变化时阻止合并
  • 自动与基础分支比较

安装

  1. 从GitHub Marketplace安装
  2. 配置.github/graphql-inspector.yaml：
schema: 'schema.graphql'
branch: 'main'
endpoint: 'https://api.example.com/graphql'
diff: true
notifications:
  slack: ${{ secrets.SLACK_WEBHOOK }}

GitHub Actions

基本模式差异

name: GraphQL模式检查
用户可调用: false
on:
  pull_request:
    paths:
      - 'schema.graphql'
      - '**/*.graphql'

jobs:
  schema-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: 设置Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: 安装GraphQL Inspector
        run: npm install -g @graphql-inspector/cli

      - name: 检查破坏性变化
        run: |
          graphql-inspector diff \
            'git:origin/main:schema.graphql' \
            'schema.graphql'

完整验证流水线

name: GraphQL验证
用户可调用: false
on:
  pull_request:
    paths:
      - '**/*.graphql'
      - 'src/**/*.tsx'
      - 'schema.graphql'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: 设置Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: 安装依赖
        run: npm install -g @graphql-inspector/cli

      - name: 模式差异
        id: diff
        run: |
          graphql-inspector diff \
            'git:origin/main:schema.graphql' \
            'schema.graphql' \
            --onlyBreaking
        continue-on-error: true

      - name: 验证操作
        run: |
          graphql-inspector validate \
            'src/**/*.graphql' \
            'schema.graphql' \
            --maxDepth 10

      - name: 审计操作
        run: |
          graphql-inspector audit \
            'src/**/*.graphql'

      - name: 在PR上评论
        if: steps.diff.outcome == 'failure'
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '⚠️ 检测到破坏性GraphQL模式变化！'
            })

多模式矩阵策略

name: 多模式验证
用户可调用: false
on: pull_request

jobs:
  validate:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        service:
          - { name: 'users', schema: 'services/users/schema.graphql' }
          - { name: 'orders', schema: 'services/orders/schema.graphql' }
          - { name: 'products', schema: 'services/products/schema.graphql' }

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: 安装GraphQL Inspector
        run: npm install -g @graphql-inspector/cli

      - name: 差异${{ matrix.service.name }}
        run: |
          graphql-inspector diff \
            'git:origin/main:${{ matrix.service.schema }}' \
            '${{ matrix.service.schema }}'

GitLab CI

基本配置

stages:
  - validate

graphql-diff:
  stage: validate
  image: node:20
  before_script:
    - npm install -g @graphql-inspector/cli
  script:
    - graphql-inspector diff "git:origin/main:schema.graphql" schema.graphql
  rules:
    - changes:
        - "**/*.graphql"

graphql-validate:
  stage: validate
  image: node:20
  before_script:
    - npm install -g @graphql-inspector/cli
  script:
    - graphql-inspector validate 'src/**/*.graphql' schema.graphql
  rules:
    - changes:
        - "**/*.graphql"
        - "src/**/*.tsx"

合并请求评论

graphql-diff:
  stage: validate
  image: node:20
  script:
    - npm install -g @graphql-inspector/cli
    - |
      OUTPUT=$(graphql-inspector diff "git:origin/main:schema.graphql" schema.graphql 2>&1 || true)
      if [[ "$OUTPUT" == *"Breaking"* ]]; then
        curl --request POST \
          --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
          --data "body=⚠️ 检测到破坏性GraphQL变化" \
          "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
      fi

CircleCI

version: 2.1

jobs:
  graphql-check:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: 安装GraphQL Inspector
          command: npm install -g @graphql-inspector/cli
      - run:
          name: 模式差异
          command: |
            graphql-inspector diff \
              'git:origin/main:schema.graphql' \
              'schema.graphql'
      - run:
          name: 验证操作
          command: |
            graphql-inspector validate \
              'src/**/*.graphql' \
              'schema.graphql'

workflows:
  validate:
    jobs:
      - graphql-check

配置文件

创建.graphql-inspector.yaml用于所有命令：

# 模式配置
schema:
  path: './schema.graphql'
  # 或用于联邦
  # federation: true

# 差异配置
diff:
  rules:
    - suppressRemovalOfDeprecatedField
  failOnBreaking: true
  failOnDangerous: false
  notifications:
    slack: ${SLACK_WEBHOOK_URL}

# 验证配置
validate:
  documents: './src/**/*.graphql'
  maxDepth: 10
  maxAliasCount: 5
  maxComplexityScore: 100

# 审计配置
audit:
  documents: './src/**/*.graphql'

高级模式

缓存依赖

# 带缓存的GitHub Actions
- name: 缓存npm
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-graphql-inspector

- name: 安装GraphQL Inspector
  run: npm install -g @graphql-inspector/cli

Slack通知

- name: 在破坏性变化时通知Slack
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {
        "text": "⚠️ 在${{ github.repository }}中检测到破坏性GraphQL变化",
        "attachments": [{
          "color": "danger",
          "title": "拉取请求#${{ github.event.pull_request.number }}",
          "title_link": "${{ github.event.pull_request.html_url }}"
        }]
      }
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

必需状态检查

配置仓库设置：

  1. 转到设置 → 分支 → 分支保护规则
  2. 启用“要求状态检查通过”
  3. 添加“GraphQL模式检查”作业作为必需项

远程模式比较

- name: 与生产环境差异比较
  run: |
    graphql-inspector diff \
      'https://api.production.example.com/graphql' \
      'schema.graphql'
  env:
    GRAPHQL_INSPECTOR_HEADERS: |
      Authorization: Bearer ${{ secrets.PROD_API_TOKEN }}

最佳实践

  1. 快速失败 - 使用--onlyBreaking专注于关键问题
  2. 缓存安装 - 使用npm缓存加速CI
  3. 必需检查 - 使模式验证成为必需检查
  4. 分支保护 - 在破坏性变化时阻止合并
  5. 通知 - 在破坏性变化时提醒团队
  6. 文档 - 在评论中链接到迁移指南
  7. 多环境 - 针对暂存和生产环境验证
  8. 并行作业 - 并行运行差异、验证和审计

故障排除

“权限被拒绝”用于git引用

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # 获取完整历史记录

CI中“模式未找到”

  • 验证文件路径在仓库中是否正确
  • 检查模式是否已提交（未被git忽略）
  • 如果相对路径失败，使用绝对路径

本地与CI结果不同

  • 确保GraphQL Inspector版本相同
  • 检查Node.js版本匹配
  • 验证git引用是否可访问

何时使用此技能

  • 设置自动模式验证
  • 在CI中配置破坏性变化检测
  • 构建GraphQL质量门
  • 与GitHub/GitLab工作流集成
  • 为模式变化创建PR评论
  • 在破坏性变化时阻止部署