Overview

Honeydew stores all semantic-layer metadata in Git, so you can manage semantic-layer changes with the same practices you use for code: control who can change what, review and validate changes before they merge, and automate what happens after they merge. Two layers work together:

Your Git provider enforces review and ownership rules on pull requests — required reviews, branch protection, and code owners.
Your CI/CD system runs automated steps that call Honeydew over an API. This works with any CI/CD system — GitHub Actions, GitLab CI/CD, CircleCI, Jenkins, Azure Pipelines, and others.

Honeydew provides a ready-made GitHub Action for validation. It is currently the only prebuilt integration; for other CI/CD systems and for other steps, call the API directly.

What you can do

Capability	What it does	Where to look
Control who can change what	Require review and approval on pull requests, and assign owners to specific entities, metrics, or domains with code owners	Git version control
Validate changes before merge	Reload a branch from Git and fail the build if any object has errors	GitHub Action, GraphQL validation, Native App example workflow
Promote across environments	Point the `prod` branch and dev branches at different databases, schemas, warehouses, and roles	Environments
Materialize to the warehouse	Build and refresh datasets and caches in Snowflake or Databricks	dbt, Pipeline architecture, Native App deployment
Generate schemas for BI tools	Generate schemas and models for your BI tools from domains, and publish them from a pipeline	Publish to BI tools, BI tools

A typical flow: your Git provider requires the right owners to approve a pull request, the pipeline validates the branch before merge, and once merged the pipeline promotes, materializes, and generates BI schemas as needed.

How it works

Governance rules — required reviews and code owners — are configured in your Git provider and apply to every pull request. See Git version control. The automated steps call Honeydew through one of two interfaces, which expose the same operations for reloading branches, validating objects, deploying datasets, and generating BI models:

GraphQL API — HTTPS endpoint authenticated with an API key and secret. Language- and tool-agnostic, so it fits any CI/CD runner.
Snowflake Native App — the same operations as SEMANTIC_LAYER.API.* SQL procedures, for pipelines that already have a Snowflake connection.

The two interfaces expose equivalent operations (for example, reset_workspace in GraphQL maps to RELOAD_WORKSPACE in the Native App). Choose whichever matches your pipeline.

A pipeline authenticates with its own API key, so reloading a branch runs in the API key’s session and does not affect users editing that workspace in Honeydew Studio. Validation is safe to run on active branches.

Validate changes in a pipeline

Validation is the most common step, and the same request pattern applies to every other operation. The example below reloads the workspace from Git and then queries entities for errors. With curl:

export API_KEY="your_api_key"
export API_SECRET="your_api_secret"
export API_URI="https://api.honeydew.cloud/api/public/v1/graphql"

# Reload the branch from the latest commit
curl -sS -X POST "${API_URI}" \
  -H "Content-Type: application/json" \
  -H "X-Honeydew-Workspace: sales" \
  -H "X-Honeydew-Branch: prod" \
  -u "${API_KEY}:${API_SECRET}" \
  -d '{"query":"mutation { reset_workspace }"}'

# Report objects that fail validation
curl -sS -X POST "${API_URI}" \
  -H "Content-Type: application/json" \
  -H "X-Honeydew-Workspace: sales" \
  -H "X-Honeydew-Branch: prod" \
  -u "${API_KEY}:${API_SECRET}" \
  -d '{"query":"query { entities { name error { description } } }"}'

If your organization uses a custom hostname for the API connection, use it in place of api.honeydew.cloud. You can locate it in the Honeydew UI, under the API section in Settings.

Fail the pipeline step when any object reports an error.

This example is illustrative — it reports only entity-level errors. A complete check also inspects fields, domains, dynamic datasets, global parameters, context items, and agents, and exits non-zero when any of them report an error. See Validate a Workspace for the full query set.

On GitHub, the GitHub Action runs the complete sequence for you. On any other CI/CD system, port the full query set from Validate a Workspace and fail the step on any returned error — the two-call check above is not sufficient on its own. Structural validation confirms the model loads and resolves, but not that its generated SQL runs. To catch a model that is valid yet produces SQL that fails against the warehouse — for example, after a source column is renamed — compile representative queries with get_sql_from_yaml, or run them with adhoc_sql.

Environments map each branch to a data-warehouse connection, so pipeline steps that run against the warehouse — compiling query SQL, materializing datasets — use the connection for that branch automatically. Keep dev branches pointed at a dev warehouse so automated steps never run against production.

Authentication

CI/CD pipelines authenticate with an API key. Use an organization-level key as a service account, and give it the lowest role the pipeline needs:

Viewer — sufficient to reload a branch, validate objects, and generate BI schemas.
Editor — required to modify objects or deploy datasets.
Admin — required to reload a workspace for all users (publish to production).

Store the API key and secret in your CI/CD provider’s secret store, and restrict the key to your pipeline’s IP addresses with IP Access Control.

The public GraphQL API is not enabled by default. Contact support@honeydew.ai to enable it for your organization.

Quick Start

Semantic Ecosystem

Modeling Reference

Context Layer

Management

Integrations

Security

Release Notes

What you can do

How it works

Validate changes in a pipeline

Authentication

​What you can do

​How it works

​Validate changes in a pipeline

​Authentication

What you can do

How it works

Validate changes in a pipeline

Authentication