graphql-inspector-ci

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GraphQL Inspector - CI/CD Integration

GraphQL Inspector - CI/CD集成

Expert knowledge of integrating GraphQL Inspector into continuous integration and deployment pipelines for automated schema and operation validation.

精通将GraphQL Inspector集成到持续集成与部署（CI/CD）流水线中，实现自动化的Schema和操作验证。

Overview

概述

GraphQL Inspector provides multiple integration options for CI/CD, from simple CLI commands to dedicated GitHub Apps and Actions. This skill covers all integration patterns for automated GraphQL quality enforcement.

GraphQL Inspector为CI/CD提供了多种集成选项，从简单的CLI命令到专用的GitHub应用和Actions。本技能涵盖了所有用于自动化GraphQL质量管控的集成模式。

GitHub App

GitHub应用

The official GitHub App provides the richest integration:

官方GitHub应用提供最丰富的集成功能：

Features

功能特性

Automatic schema diff on pull requests
Comment with breaking changes summary
Block merges on breaking changes
Compare against base branch automatically

拉取请求中自动生成Schema差异对比
以评论形式总结破坏性变更
检测到破坏性变更时阻止合并
自动与基准分支进行对比

Installation

安装步骤

Install from GitHub Marketplace
Configure
```
.github/graphql-inspector.yaml
```
:

yaml

schema: 'schema.graphql'
branch: 'main'
endpoint: 'https://api.example.com/graphql'
diff: true
notifications:
  slack: ${{ secrets.SLACK_WEBHOOK }}

从GitHub Marketplace安装
配置
```
.github/graphql-inspector.yaml
```
：

yaml

schema: 'schema.graphql'
branch: 'main'
endpoint: 'https://api.example.com/graphql'
diff: true
notifications:
  slack: ${{ secrets.SLACK_WEBHOOK }}

GitHub Actions

Basic Schema Diff

基础Schema差异对比

yaml

name: GraphQL Schema Check
user-invocable: 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: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

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

      - name: Check for breaking changes
        run: |
          graphql-inspector diff \
            'git:origin/main:schema.graphql' \
            'schema.graphql'

yaml

name: GraphQL Schema Check
user-invocable: 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: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

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

      - name: Check for breaking changes
        run: |
          graphql-inspector diff \
            'git:origin/main:schema.graphql' \
            'schema.graphql'

Complete Validation Pipeline

完整验证流水线

yaml

name: GraphQL Validation
user-invocable: 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: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm install -g @graphql-inspector/cli

      - name: Schema Diff
        id: diff
        run: |
          graphql-inspector diff \
            'git:origin/main:schema.graphql' \
            'schema.graphql' \
            --onlyBreaking
        continue-on-error: true

      - name: Validate Operations
        run: |
          graphql-inspector validate \
            'src/**/*.graphql' \
            'schema.graphql' \
            --maxDepth 10

      - name: Audit Operations
        run: |
          graphql-inspector audit \
            'src/**/*.graphql'

      - name: Comment on 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: '⚠️ Breaking GraphQL schema changes detected!'
            })

yaml

name: GraphQL Validation
user-invocable: 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: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm install -g @graphql-inspector/cli

      - name: Schema Diff
        id: diff
        run: |
          graphql-inspector diff \
            'git:origin/main:schema.graphql' \
            'schema.graphql' \
            --onlyBreaking
        continue-on-error: true

      - name: Validate Operations
        run: |
          graphql-inspector validate \
            'src/**/*.graphql' \
            'schema.graphql' \
            --maxDepth 10

      - name: Audit Operations
        run: |
          graphql-inspector audit \
            'src/**/*.graphql'

      - name: Comment on 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: '⚠️ Breaking GraphQL schema changes detected!'
            })

Matrix Strategy for Multiple Schemas

多Schema矩阵策略

yaml

name: Multi-Schema Validation
user-invocable: 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: Install GraphQL Inspector
        run: npm install -g @graphql-inspector/cli

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

yaml

name: Multi-Schema Validation
user-invocable: 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: Install GraphQL Inspector
        run: npm install -g @graphql-inspector/cli

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

GitLab CI

Basic Configuration

基础配置

yaml

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"

yaml

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"

Merge Request Comments

合并请求评论

yaml

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=⚠️ Breaking GraphQL changes detected" \
          "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
      fi

yaml

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=⚠️ Breaking GraphQL changes detected" \
          "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
      fi

CircleCI

yaml

version: 2.1

jobs:
  graphql-check:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Install GraphQL Inspector
          command: npm install -g @graphql-inspector/cli
      - run:
          name: Schema Diff
          command: |
            graphql-inspector diff \
              'git:origin/main:schema.graphql' \
              'schema.graphql'
      - run:
          name: Validate Operations
          command: |
            graphql-inspector validate \
              'src/**/*.graphql' \
              'schema.graphql'

workflows:
  validate:
    jobs:
      - graphql-check

yaml

version: 2.1

jobs:
  graphql-check:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Install GraphQL Inspector
          command: npm install -g @graphql-inspector/cli
      - run:
          name: Schema Diff
          command: |
            graphql-inspector diff \
              'git:origin/main:schema.graphql' \
              'schema.graphql'
      - run:
          name: Validate Operations
          command: |
            graphql-inspector validate \
              'src/**/*.graphql' \
              'schema.graphql'

workflows:
  validate:
    jobs:
      - graphql-check

Configuration File

配置文件

Create

.graphql-inspector.yaml

for all commands:

yaml

undefined

创建

.graphql-inspector.yaml

用于所有命令：

yaml

undefined

Schema configuration

schema: path: './schema.graphql'

Or for federation

federation: true

schema: path: './schema.graphql'

Or for federation

federation: true

Diff configuration

diff: rules: - suppressRemovalOfDeprecatedField failOnBreaking: true failOnDangerous: false notifications: slack: ${SLACK_WEBHOOK_URL}

Validate configuration

validate: documents: './src/**/*.graphql' maxDepth: 10 maxAliasCount: 5 maxComplexityScore: 100

Audit configuration

audit: documents: './src/**/*.graphql'

undefined

audit: documents: './src/**/*.graphql'

undefined

Advanced Patterns

高级模式

Caching Dependencies

依赖缓存

yaml

undefined

yaml

undefined

GitHub Actions with caching

name: Cache npm uses: actions/cache@v4 with: path: ~/.npm key: ${{ runner.os }}-graphql-inspector
name: Install GraphQL Inspector run: npm install -g @graphql-inspector/cli

undefined

name: Cache npm uses: actions/cache@v4 with: path: ~/.npm key: ${{ runner.os }}-graphql-inspector
name: Install GraphQL Inspector run: npm install -g @graphql-inspector/cli

undefined

Slack Notifications

Slack通知

yaml

- name: Notify Slack on breaking changes
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {
        "text": "⚠️ Breaking GraphQL changes in ${{ github.repository }}",
        "attachments": [{
          "color": "danger",
          "title": "Pull Request #${{ github.event.pull_request.number }}",
          "title_link": "${{ github.event.pull_request.html_url }}"
        }]
      }
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

yaml

- name: Notify Slack on breaking changes
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {
        "text": "⚠️ Breaking GraphQL changes in ${{ github.repository }}",
        "attachments": [{
          "color": "danger",
          "title": "Pull Request #${{ github.event.pull_request.number }}",
          "title_link": "${{ github.event.pull_request.html_url }}"
        }]
      }
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

Required Status Checks

必需状态检查

Configure repository settings:

Go to Settings → Branches → Branch protection rules
Enable "Require status checks to pass"
Add "GraphQL Schema Check" job as required

配置仓库设置：

进入Settings → Branches → Branch protection rules
启用“Require status checks to pass”
添加“GraphQL Schema Check”任务为必需检查项

Remote Schema Comparison

远程Schema对比

yaml

- name: Diff against production
  run: |
    graphql-inspector diff \
      'https://api.production.example.com/graphql' \
      'schema.graphql'
  env:
    GRAPHQL_INSPECTOR_HEADERS: |
      Authorization: Bearer ${{ secrets.PROD_API_TOKEN }}

yaml

- name: Diff against production
  run: |
    graphql-inspector diff \
      'https://api.production.example.com/graphql' \
      'schema.graphql'
  env:
    GRAPHQL_INSPECTOR_HEADERS: |
      Authorization: Bearer ${{ secrets.PROD_API_TOKEN }}

Best Practices

最佳实践

Fail fast - Use
```
--onlyBreaking
```
to focus on critical issues
Cache installation - Speed up CI with npm caching
Required checks - Make schema validation a required check
Branch protection - Block merges with breaking changes
Notifications - Alert team on breaking changes
Documentation - Link to migration guides in comments
Multiple environments - Validate against staging and production
Parallel jobs - Run diff, validate, and audit in parallel

快速失败 - 使用
```
--onlyBreaking
```
聚焦关键问题
缓存安装 - 利用npm缓存加速CI流程
必需检查 - 将Schema验证设为必需检查项
分支保护 - 检测到破坏性变更时阻止合并
通知提醒 - 破坏性变更时通知团队
文档说明 - 在评论中链接迁移指南
多环境验证 - 针对预发布和生产环境进行验证
并行任务 - 并行执行差异对比、验证和审计任务

Troubleshooting

故障排除

"Permission denied" for git refs

Git引用“Permission denied”

yaml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Fetch full history

yaml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Fetch full history

"Schema not found" in CI

CI中“Schema not found”

Verify file path is correct in repository
Check that schema is committed (not gitignored)
Use absolute paths if relative paths fail

验证仓库中的文件路径是否正确
确认Schema已提交（未被git忽略）
如果相对路径失败，使用绝对路径

Different results local vs CI

本地与CI结果不一致

Ensure same GraphQL Inspector version
Check Node.js version matches
Verify git refs are accessible

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

When to Use This Skill

适用场景

Setting up automated schema validation
Configuring breaking change detection in CI
Building GraphQL quality gates
Integrating with GitHub/GitLab workflows
Creating PR comments for schema changes
Blocking deployments with breaking changes

搭建自动化Schema验证流程
在CI中配置破坏性变更检测
构建GraphQL质量门禁
与GitHub/GitLab工作流集成
为Schema变更生成拉取请求评论
检测到破坏性变更时阻止部署