CI/CD and Hive CLI

This guide is a collection of features and capabilities you can configure with Hive, to integrate it with Continuous Integration (CI) Continuous Deployment (CD) setups.

Overview

The Hive CLI can be installed on any environment, including CI/CD environments.

If you are using a JavaScript/NodeJS project, you should install the Hive CLI under devDependencies of your project, and use it directly with your preferred package manager (for example: yarn hive ... or pnpm hive ...).

If you are using a different runtime environment for your project, you should install the Hive CLI binary and use it directly as a binary (hive ...).

Schema Revision Workflow

For production pipelines, separate schema validation, release preparation, and deployment:

1. Run hive schema:check for every pull request.
2. Run hive schema:push during the merge or release flow.
3. Run hive schema:publish --revision when the corresponding service is deployed.

This workflow publishes the exact immutable schema revision prepared by the release flow. It also prevents a schema from becoming current in the registry before the service that implements it is deployed.

1. Check in Pull Requests

hive schema:check "path/to/schema.graphql" \
  --registry.accessToken "$HIVE_TOKEN" \
  --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>"

For distributed schemas, include --service and, when needed, --url.

2. Push During Merge or Release

Use a stable, immutable release identifier such as the Git commit SHA:

hive schema:push "path/to/schema.graphql" \
  --registry.accessToken "$HIVE_TOKEN" \
  --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \
  --revision "$GIT_COMMIT_SHA"

Pushing uploads the SDL but does not publish a schema version or update the Hive CDN. A revision name cannot later be reused with different SDL.

For Apollo Federation and Schema Stitching projects, include the service name:

hive schema:push "path/to/schema.graphql" \
  --registry.accessToken "$HIVE_TOKEN" \
  --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \
  --service "<YOUR_SERVICE_NAME>" \
  --revision "$GIT_COMMIT_SHA"

3. Publish During Deployment

Pass the same revision to the deployment job. The job does not need the schema file because Hive uses the SDL stored by the push step:

hive schema:publish \
  --registry.accessToken "$HIVE_TOKEN" \
  --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \
  --revision "$GIT_COMMIT_SHA"

For a distributed schema, also provide the service name and the deployed service URL:

hive schema:publish \
  --registry.accessToken "$HIVE_TOKEN" \
  --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \
  --service "<YOUR_SERVICE_NAME>" \
  --url "<YOUR_SERVICE_URL>" \
  --fail-on-composition-error \
  --revision "$GIT_COMMIT_SHA"

For Federation projects, --fail-on-composition-error stops the deployment job without recording an invalid schema version if the proposed subgraph causes the supergraph or a contract to fail composition. This protects the deployment boundary from changes that landed after the pull-request check and from concurrent subgraph releases.

Use separate tokens with the minimum required permissions for each stage: Schema check for pull requests, Schema push for the merge or release flow, and Schema publish for deployment.

GitHub Check Suites

If you are using GitHub Actions, you can specify an additional flag to the Hive CLI: --github.

If GitHub Integration is enabled for your organization, and the GitHub repository has access to the GitHub repository the action is running from is active, you may specify an additional --github flag to report the results back to GitHub as Check Suite (for schema:check and schema:publish commands):

hive schema:publish \
  --target "org/project/target" \
  path/to/schema.graphql \
  --github

hive schema:check \
  --target "org/project/target" \
  path/to/schema.graphql \
  --github

GitHub Workflow for CI

The following workflow runs the check for every pull request and associates the results with the pull request.

on:
  pull_request:
    branches: [main]
jobs:
  check:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - name: schema check
        env:
          # If you self-host your hive server:
          HIVE_ENDPOINT: ${{ secrets.HIVE_ENDPOINT }}
        run: |
          curl -sSL https://graphql-hive.com/install.sh | sh
          hive schema:check "path/to/schema.graphql" \
            --registry.accessToken "${{ secrets.HIVE_TOKEN }}" \
            --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \
            --github

GitHub Merge Queue

GitHub Merge Queue tests the accumulated changes from multiple pull requests. If a schema check compares the complete merge group against the latest schema in the registry, it can report breaking changes introduced and approved by an earlier pull request again.

Pass --baseline with a <revision>:<path> value to compare the checked-out service schema against a schema file at the merge group’s base commit. Hive composes both versions with the other services currently stored in the registry and evaluates only the difference between those compositions. Composition errors, conditional breaking changes, and contract checks are still evaluated.

on:
  merge_group:
    types: [checks_requested]
jobs:
  check:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
        with:
          # --base loads the schema from Git history.
          fetch-depth: 0
      - name: schema check
        env:
          # If you self-host your Hive server:
          # HIVE_ENDPOINT: ${{ secrets.HIVE_ENDPOINT }}
          MERGE_GROUP_BASE_SHA: ${{ github.event.merge_group.base_sha }}
        run: |
          curl -sSL https://graphql-hive.com/install.sh | sh
          hive schema:check "path/to/schema.graphql" \
            --registry.accessToken "${{ secrets.HIVE_TOKEN }}" \
            --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \
            --service "<YOUR_SERVICE_NAME>" \
            --baseline "$MERGE_GROUP_BASE_SHA:path/to/schema.graphql" \
            --github

For a merge_group event, the Hive CLI automatically extracts the pull request number and merge group head commit. The --github flag reports the result on that commit and uses the same context as the pull request workflow, so approved breaking changes remain associated with the pull request.

The --baseline option also accepts a local schema file. When using the Git revision syntax shown above, the value must reference one file and the checkout must contain the referenced commit.

GitHub Workflow for Merge and Deployment

The following workflow pushes an immutable schema revision for every change merged into main. A separate deployment job can then publish that exact revision after deploying the service.

on:
  push:
    branches: [main]
jobs:
  push-schema:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - name: schema push
        env:
          # If you self-host your hive server:
          HIVE_ENDPOINT: ${{ secrets.HIVE_ENDPOINT }}
        run: |
          curl -sSL https://graphql-hive.com/install.sh | sh
          hive schema:push "path/to/schema.graphql" \
            --registry.accessToken "${{ secrets.HIVE_TOKEN }}" \
            --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \
            --revision "${{ github.sha }}"

During deployment, pass the same commit SHA or release identifier to hive schema:publish --revision. For distributed schemas, include --service in both commands and --url when publishing.

Multi Environment Best Practices

By default each project has three targets: development, staging, and production. You can utilize these environments (or even add more), to model a multi environment/stage depployment process.

For CI, run hive schema:check. After merging, run hive schema:push for the respective target and publish that revision with hive schema:publish --revision during deployment. Each target can be configured to use the usage data from other targets for conditional breaking changes based on usage data.

Example

Three branches:

New features are developed on a branch that targets the main branch. The hive schema:check command is run against the development target. conditional breaking changes are configured on staging and production targets.

When the feature is ready for QA, the branch is merged into main. The hive schema:publish command is triggered by CD workflow, and the schema is published to the development target.

When the feature is ready for staging, the main branch is merged into staging. The hive schema:publish command is triggered by the CD workflow, and the schema is published to the staging target.

When the feature is ready for production, the staging branch is merged into production. The hive schema:publish command is triggered by the CD workflow, and the schema published to the production target.