Project Management

A Hive project represents a GraphQL API project running a GraphQL schema, created under an organization.

Within a Hive project, you can create targets (which are equivalent to runtime environments) and manage different schemas across different contextual runtimes.

Supported project types

Hive supports the following project types:

Single Schema: a GraphQL project that has a single GraphQL schema developed as a standalone.
Schema Stitching: a form of remote schema merging allowing developers to merge any GraphQL schema(s), under one or many gateways. You can use either direct Schema Stitching or GraphQL Mesh for this project type.
Apollo Federation: a form of remote schema merging developed according to the Federation specification.

Create a new project

To create a new project, click on Create Project + button from your organization’s main page:

Choose a project type based on your project’s stack, and then enter the project slug.

💡

Please note that a project type cannot be changed once it is created. However, you can always create an unlimited number of projects under your organization.

Manage existing project

GitHub Repository

Once you have your Hive organization integrated with GitHub, no additional steps are needed. Please double check that the GitHub integration has access to all the GitHub repositories you plan to use with Hive.

💡

Previously, you could only connect a single GitHub repository to a project. However, that does not make sense when using federated/composite schema project the subgraphs can be in different repositories.

Having a Project connected with your GitHub repositories gives you the following benefits:

Publish Check Suite back to GitHub (when --github flag is used for your schema:publish and schema:check commands - you can learn move about this feature here).
Have direct connection between a schema version and a Git commit in your repository in Hive dashboard.

Change slug of a project

Slug is a unique (within an organization) identifier for your project.

Similarly to changing organization’s slug, you can change the slug of your organization by visiting Settings tab of your project:

⚠️

Changing the slug of your project will also change the URL, and will invalidate any existing links to your project.

Delete a project

As the owner of an organization, you have the option to delete a project, including all targets, settings and all data collected during your use of Hive.

To delete an project, go to the Settings tab of your project, and use the Delete Project section.

⚠️

This action is not reversible!

Alerts and Notifications

Hive allows you to configure alerts and notifications for your projects. To get started with alerts and notifications, go to the Settings tab of your project, and click on the Alerts tab.

To use alerts and notifications, you need to have at least one Alert Channel configured, and then you need to create an Alert that will be triggered when a specific condition is met.

Alert Channels

Alert Channels are a way to configure how you want to receive alerts and notifications from Hive.

From the Alerts tab of your project, you can create and manage your Alert Channels.

At the moment, Hive supports the following transports to ship your alerts and notifications:

Slack

Integrating your project with a Slack channel will allow you to receive alerts and notifications shipped directly to a Slack channel.

To integrate your project with a Slack channel, you first need to activate the Slack integration at the organization level.

Once you have activated the Slack integration, you can configure a Slack channel to connect to your Hive project:

To send messages to private channels, invite the @GraphQLHive account first. Without this invitation, our Slack app will be unable to post messages to the channel.

MS Teams Webhook

You set up Hive MS Teams webhook to receive alerts and notifications from Hive, when an alert or a notification is triggered. All you need to do is to provide a valid HTTP URL, and Hive will dispatch a POST request to that URL, with a JSON payload acceptable by MS Teams. MS Teams Webhook JSON example

Typically the webhook URL looks like:

https://USERNAME.webhook.office.com/webhookb2/XXXXX/IncomingWebhook/YYYY/ZZZZZ

You can find more information on how to set up a webhook in MS Teams in the official documentation - Create Incoming Webhooks.

HTTP Webhook

You can implement a custom HTTP webhook to receive alerts and notifications from Hive, when an alert or a notification is triggered.

All you need to do is to provide a valid HTTP URL, and Hive will dispatch a POST request to that URL, with a JSON payload as body (with Content-Type: application/json header set) when an alert or a notification is triggered.

⚠️

Note that using this form of alert is intended to implement custom flows. You cannot use an Incoming Webhook feature of products like MSTeams or Slack, because the expected payload is different.

⚠️

Hive Cloud uses Cloudflare Worker to communicate with your endpoint. This means that endpoint’s address must contain a valid hostname (not an IP address), and the port must be standard.

Every type of event/notification has a different JSON payload, please refer to the information below, for a specific payload structure for every kind of alert.

Alerts and Notifications

Alerts are a way to configure when you want to receive alerts and notifications from Hive.

From the Alerts tab of your project, you can create and manage your Active Alerts and Notifications.

To create a new kind of alert, use the Create Alert button and choose the Alert type, Alert Channel and the target’s slug.

At the moment, Hive supports the following types of alerts and notifications (if you need a different kind of alert, you can collaborate with us on this GitHub issue):

Schema Changed Notification

An alert triggered when a fully valid and composable schema is published to a target.

This notification has the following payload when shipped over the HTTP webhook channel:

type SchemaChangedNotificationPayload = {
  /** General information about organization triggered the event */
  organization: {
    id: string
    cleanId: string
    name: string
  }
  /** General information about project triggered the event */
  project: {
    id: string
    cleanId: string
    name: string
  }
  /** General information about target triggered the event */
  target: {
    id: string
    cleanId: string
    name: string
  }
  /** Information about the published schema and the commit identification */
  schema: {
    id: string
    commit: string
    valid: boolean
  }
  /** List of changes and their criticality */
  changes: Array<{
    criticality: 'Breaking' | 'Dangerous' | 'Safe'
    message: string
    path?: string
  }>
  /** Useful information about the schema publication flow */
  messages: string[]
  /** List of validation and composition error */
  errors: Array<{
    message: string
    path?: string
  }>
  /** A boolean indicator set to true, when this is the first schema published to the target */
  initial: boolean
}

SSO with OIDC Targets & Tokens