> ## Documentation Index
> Fetch the complete documentation index at: https://honeydew.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

Honeydew stores all semantic-layer metadata in [Git](/docs/governance/git-version-control), 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.

<Note>
  Honeydew provides a ready-made [GitHub Action](/docs/governance/ci-cd/github-actions) for
  validation. It is currently the only prebuilt integration; for other CI/CD systems and for
  other steps, call the API directly.
</Note>

## 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](/docs/governance/git-version-control#branch-based-development)                                                                                                                           |
| **Validate changes before merge** | Reload a branch from Git and fail the build if any object has errors                                                       | [GitHub Action](/docs/governance/ci-cd/github-actions), [GraphQL validation](/docs/integration/graphql-api#validate-a-workspace), [Native App example workflow](/docs/integration/snowflake-native-app#example-workflow) |
| **Promote across environments**   | Point the `prod` branch and dev branches at different databases, schemas, warehouses, and roles                            | [Environments](/docs/governance/environments)                                                                                                                                                                  |
| **Materialize to the warehouse**  | Build and refresh datasets and caches in Snowflake or Databricks                                                           | [dbt](/docs/integration/etl-tools/dbt), [Pipeline architecture](/docs/integration/etl-tools/pipeline-architecture), [Native App deployment](/docs/integration/snowflake-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](/docs/integration/graphql-api#publish-to-bi-tools), [BI tools](/docs/integration/bi-tools/supported-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](/docs/governance/git-version-control#branch-based-development).

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](/docs/integration/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](/docs/integration/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.

<Note>
  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.
</Note>

## 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`:

```bash theme={null}
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 } } }"}'
```

<Note>
  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**.
</Note>

Fail the pipeline step when any object reports an `error`.

<Warning>
  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](/docs/integration/graphql-api#validate-a-workspace) for the full query set.
</Warning>

On GitHub, the [GitHub Action](/docs/governance/ci-cd/github-actions) runs the complete sequence
for you. On any other CI/CD system, port the full query set from
[Validate a Workspace](/docs/integration/graphql-api#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`](/docs/integration/graphql-api#queries), or run them with `adhoc_sql`.

<Tip>
  [Environments](/docs/governance/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.
</Tip>

## Authentication

CI/CD pipelines authenticate with an [API key](/docs/access-control/api-keys). 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).

<Tip>
  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](/docs/access-control/ip-access-control).
</Tip>

<Warning>
  The public GraphQL API is not enabled by default. Contact [support@honeydew.ai](mailto:support@honeydew.ai) to enable it
  for your organization.
</Warning>