How to track GraphQL Schema Changes with GitHub Actions?

name: 'Usage of graphql-inspector GitHub Action'
on:
push:
    branches:
        - main
jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
        - uses: actions/checkout@v4
        - uses: kamilkisiela/graphql-inspector@master
            with:
            schema: 'master:schema.graphql'

graphql-inspector

🕵️‍♀️ Validate schema, get schema change notifications, validate operations, find breaking changes, look for similar types, schema coverage

What is graphql-inspector?​

It is a tool that has been designed for us to be able to manage changes inside our GraphQL schemas in a much more effective way. This is quite a necessary tool to ensure that updates to our schemas are error-free for the already used services.

Features of GraphQL Inspector:

• Schema Change Detection: Generates a list of changes between two GraphQL schemas, where every change is categorized as either breaking, non-breaking, or dangerous. This precision can help you understand what the change will bring.
• Validation: The process of validating documents and fragments against a schema to ensure that the queries or mutations conform to the given schema.
• Notifications: It can also be configured to send notifications for schema changes, keeping everybody in the loop about the update.
• Locating Similar or Duplicate Types: It helps locate the similar or duplicated types across the schemas, one of the essentials for a successful schema design.
• Schema Coverage: Checks how much of our schema does our operations cover, which therefore can help us understand unused or underutilized parts of the schema. Example Use-Cases:

Use-Cases of GraphQL Inspector:​

• Schema Changes Validation: we can use the GraphQL inspector to validate if we will break something in our production schema by pushing the changes.
• Schema Optimization: Find duplicated types, to allow the schema to be optimized, for efficiency and easier maintenance. The integration of GraphQL Inspector into our development workflow will enhance our ability to change schema management and application integrity.

How to Use Multiple Names for GraphQL Inspector Actions?​

When using multiple GraphQL Inspector actions, differentiate each by assigning unique names. This prevents GitHub from overwriting the results.

- uses: kamilkisiela/graphql-inspector@master
  with:
    name: Validate Public API
    schema: 'master:public.graphql'
 
- uses: kamilkisiela/graphql-inspector@master
  with:
    name: Check Internal API
    schema: 'master:internal.graphql'

How to Disable Annotations in GraphQL Inspector?​

By default, annotations are enabled. You can disable them using:

- uses: kamilkisiela/graphql-inspector@master
  with:
    schema: 'master:schema.graphql'
    annotations: false

How to Configure Failure on Breaking Changes?​

GraphQL Inspector fails the check on breaking changes by default. You can change this behavior:

- uses: kamilkisiela/graphql-inspector@master
  with:
    schema: 'master:schema.graphql'
    fail-on-breaking: false

How to Approve Breaking Changes Using Labels?​

To handle breaking changes as expected and mark them safe:

- uses: kamilkisiela/graphql-inspector@master
  with:
    schema: 'master:schema.graphql'
    approve-label: expected-breaking-change

How to Use GraphQL API Endpoint as Schema Source?​

Specify an endpoint as the schema source for comparisons:

- uses: kamilkisiela/graphql-inspector@master
  with:
    endpoint: 'https://my-app.com/graphql'
    schema: 'https://pr-1234.my-app.dev/graphql'

How to Apply Custom Rules in GraphQL Inspector?​

Apply predefined or custom rules for detailed schema inspections:

- uses: kamilkisiela/graphql-inspector@master
  with:
    schema: 'master:schema.graphql'
    rules: |
      suppressRemovalOfDeprecatedField
      custom-rule.js

How to Implement Usage-Based Logic with Custom Rules?​

For rules that require usage data, set up the following:

- uses: kamilkisiela/graphql-inspector@master
  with:
    schema: 'master:schema.graphql'
    rules: |
      considerUsage
    onUsage: check-usage.js