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 ...).

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 schema.graphql --github

hive schema:check schema.graphql --github

GitHub Workflow for CI

The following workflow will run the check workflow for every Pull Request, and will associated the check results with the Pull Request.

on:
  pull_request:
    branches: [main]
jobs:
  check:
    runs-on: ubuntu-22.04
    steps:
      - name: checkout
        uses: actions/checkout@v3
      - name: schema check
        env:
          HIVE_TOKEN: ${{ secrets.HIVE_TOKEN }}
        run: |
          curl -sSL https://graphql-hive.com/install.sh | sh
          hive schema:check "schema.graphql" \
            --registry.accessToken ${{ env.HIVE_TOKEN }} \
            --github

GitHub Workflow for CD

The following workflow will run the publish the latest schema to the schema registry for every push to main branch.

on:
  push:
    branches: [main]
jobs:
  publish:
    runs-on: ubuntu-22.04
    steps:
      - name: checkout
        uses: actions/checkout@v3
      - name: schema publish
        env:
          HIVE_TOKEN: ${{ secrets.HIVE_TOKEN }}
          HIVE_ENDPOINT: ${{ secrets.HIVE_ENDPOINT }}
        run: |
          curl -sSL https://graphql-hive.com/install.sh | sh
          hive schema:publish "schema.graphql" \
            --registry.accessToken ${{ env.HIVE_TOKEN }} \
            --github

Best Practices

We recommend using 2 different models schema publication to Hive:

1. For your actual runtime (staging and production targets), we recommend using a Hive Client library that runs along with your GraphQL gateway, and publishes the GraphQL schema, along with Usage Reporting feature enabled.

2. For your development process (development target), we recommend using CI pipelines to publish the schema to Hive using Hive CLI:

   • Your main / master branch should use schema:publish command to set the schema, once a change has been made and approved.
   • Your Pull Request CI pipeline should use schema:check command to validate the schema and compare it against the latest valid schema of the target.
   • The development target may also use the Cross-target checks for Conditional Breaking Changes and use real-time traffic from staging / production environment to determine if a change is breaking or not.

Implementing the above will allow you to:

• Have full control of your schema changes, and be able to identify and manage changes made to your GraphQL schema through Pull Requests.
• Have a complete overview of your GraphQL schema evolution
• Have a clear distinction between your development and production environments, and be able to manage them separately.
• Combine the observability from your production environment, into the development process, to identify breaking changes before they are merged into main / master branch.