# 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](/docs/api-reference/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](/docs/api-reference/cli#nodejs) 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](/docs/api-reference/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](/docs/management/organizations#github) is enabled for your organization, and
the
[GitHub repository has access to the GitHub repository the action is running from](/docs/management/projects#github-repository)
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):

```bash
hive schema:publish path/to/schema.graphql --github
```

```bash
hive schema:check 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.

```yaml filename=".github/workflows/ci.yml"
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 }}' \
            --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.

```yaml filename=".github/workflows/cd.yml"
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 }}' \
            --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](/docs/management/targets#conditional-breaking-changes) based on usage
data.

### Example

Three branches:

| Git Branch | Hive Target |
| ---------- | ----------- |
| main       | development |
| staging    | staging     |
| production | production  |

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.
