Skip to main content
← Back to workflows

How to track GraphQL Schema Changes with GitHub Actions?

kamilkisiela-graphql-inspector -
GitHub Action
November 29, 2023
1,640
Contributors
Contributor - kamilkisiela
Categories
CICUBE ANALYTICS INSIGHTS
Engineering Velocity: 25% Team Time Lost to CI Issues
View Platform →
3.5h
Time Saved/Dev/Week
40%
Faster Releases
Click for next insight
Usage
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 logo

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