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 \
  --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 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:
      - 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 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:
      - uses: actions/checkout@v4
      - name: schema publish
        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:publish"'path/to/schema.graphql" \
            --registry.accessToken "${{ secrets.HIVE_TOKEN }}" \
            --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \
            --github

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, and for CD, run hive schema:publish on the respective target for that environment. 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.