feat: merge queue schema checks

[n1ru4l]

Improves schema checks for GitHub merge queues.

The Problem

Breaking changes are approved only within the context of a single pull request. This prevents unintended "global" approvals overlaps with other open/outdated pull requests.

Merge queue actions runs are composed of multiple pull request commits:

Check 1 runs on: main + PR 1
Check 2 runs on: main + PR 1 + PR 2
Check 3 runs on: main + PR 1 + PR 2 + PR 3

Without an explicit baseline, changes introduced and approved by an earlier pull request can be reported again when checking a later merge queue item. Because the later check uses a different pull request context, those changes are considered unapproved.

The solution

Adds a --baseline option to hive schema:check. The baseline service schema can be loaded from:

• A local file
• A file from Git history using the <sha>:<file> syntax

hive schema:check \
  --target the-guild/hive-console/development \
  --baseline 43e728ea9:schema.graphqls \
  --service products \
  --contextId "hive-console#67" \
  schema.graphqls

Example for Github Action

npx @graphql-hive/cli schema:check \
  --registry.endpoint ${{ secrets.HIVE_REGISTRY_ENDPOINT }} \
  --registry.accessToken ${{ secrets.HIVE_REGISTRY_ACCESS_TOKEN }} \
  --target ${{ secrets.HIVE_REGISTRY_TARGET }} \
  --baseline "${{ github.event.merge_group.base_sha }}:subgraphs/products.graphql" \
  --github \
  --service products \
  ./subgraphs/products.graphql

Full GitHub Action Yaml Flow

on:
  pull_request:
  merge_group:
    types: [checks_requested]
  push:
    branches: [main]

jobs:
  hive-check:
    name: queue-check
    if: github.event_name != 'push'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - name: Check out code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Seyup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: "24"

      - run: npm i @graphql-hive/cli@0.62.0-alpha-20260817121742-bf67c8ac3f17445156934ff3eb282dcd476e1a0f

      - run: npx @graphql-hive/cli --version

      - name: Hive Check Pull Request
        if: github.event_name == 'pull_request'
        run: |
          npx @graphql-hive/cli schema:check \
            --registry.endpoint ${{ secrets.HIVE_REGISTRY_ENDPOINT }} \
            --registry.accessToken ${{ secrets.HIVE_REGISTRY_ACCESS_TOKEN }} \
            --target ${{ secrets.HIVE_REGISTRY_TARGET }} \
            --contextId "${{ github.repository }}#${{ github.event.pull_request.number }}" \
            --service products \
            ./subgraphs/products.graphql

      - name: Hive Check Merge Queue
        if: github.event_name == 'merge_group'
        run: |
          npx @graphql-hive/cli schema:check \
            --registry.endpoint ${{ secrets.HIVE_REGISTRY_ENDPOINT }} \
            --registry.accessToken ${{ secrets.HIVE_REGISTRY_ACCESS_TOKEN }} \
            --target ${{ secrets.HIVE_REGISTRY_TARGET }} \
            --github \
            --baseline "${{ github.event.merge_group.base_sha }}:subgraphs/products.graphql" \
            --service products \
            ./subgraphs/products.graphql

  publish-products:
    name: publish-products-schema
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: "24"

      - run: npm i @graphql-hive/cli@0.61.4-alpha-20260806131739-1a2a9fb31b8a1555a91c888607a6e63204044707

      - name: Publish products schema
        run: |
          npx @graphql-hive/cli schema:publish \
            --registry.endpoint ${{ secrets.HIVE_REGISTRY_ENDPOINT }} \
            --registry.accessToken ${{ secrets.HIVE_REGISTRY_ACCESS_TOKEN }} \
            --target ${{ secrets.HIVE_REGISTRY_TARGET }} \
            --service products \
            ./subgraphs/products.graphql

The provided service schema is composed into a baseline supergraph using the remaining registry state (subgraphs), which is then compared against the proposed schema composed supergraph. This ensures that each merge queue item reports only the changes introduced relative to its intended baseline.

Implementation Notes

Failing baseline composition

A schema check will fail if the base composition fails, as we cannot create a schema change diff in that case:

A manual approval is also blocked if the baseline composition fails.

Skipping baseline composition

In case the registry (service) state is identical to the baseline state, we can safely skip the composition of the baseline and safe some computation power.

--github flag

The hive schema:check --github flag, can now detect when dispatched by a merge queue event and automatically extracts the pull request number (used for constructing the context id) from event.merge_group.head_ref and base sha (used as additional meta information) from event.merge_group.base_sha and passes it along to the server.

---

I set up a demo over here: https://github.com/graphql-hive/hive-cli-github-merge-queue-demo, the workflow file shows how this new feature is intended to be used in Github Actions: https://github.com/graphql-hive/hive-cli-github-merge-queue-demo/blob/main/.github/workflows/ci.yml

Other

Closes #8326
Documentation graphql-hive/docs#158

[theguild-bot]

🚀 Snapshot Release (alpha)

The latest changes of this PR are available as alpha on npm (based on the declared changesets):

Package	Version	Info
@graphql-hive/cli	0.62.0-alpha-20260818092454-058febc6189a7772d6921bd01041285dcae4779a	npm ↗︎ unpkg ↗︎
hive	11.12.0-alpha-20260818092454-058febc6189a7772d6921bd01041285dcae4779a	npm ↗︎ unpkg ↗︎

[github-actions]

🐋 This PR was built and pushed to the following Docker images:

Targets: build

Platforms: linux/amd64

Image Tags: 11.12.0-alpha-058febc, 058febc, 058febc6189a7772d6921bd01041285dcae4779a