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:
-
For your actual runtime (
staging
andproduction
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. -
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 useschema: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 fromstaging
/production
environment to determine if a change is breaking or not.
- Your
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 intomain
/master
branch.