graphql-inspector-ci（GraphQL inspector CI 文档）

GraphQL Inspector - CI/CD Integration

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

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.

GitHub App

The official GitHub App provides the richest integration:

Features

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

Installation

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

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

GitHub Actions

Basic Schema Diff

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

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

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

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

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

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:

# Schema configuration
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'

Advanced Patterns

Caching Dependencies

# 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

Slack Notifications

- 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:

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

Remote Schema Comparison

- 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

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

Troubleshooting

"Permission denied" for git refs

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

"Schema not found" in CI

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

Different results local vs CI

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

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