> ## 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.
# Git Version Control
Honeydew leverages a **Git** development workflow to store and manage changes
to all semantic layer metadata, backed by a Git repository providing version control.
The Git repository can be either provided and managed by the customer,
within their Git provider of choice, or hosted by Honeydew.
The metadata is stored within the Git repository in an [open format (YAML)](/docs/yaml-schema).
Metadata YAML files can be directly edited in any external editor, not just by using the Honeydew Studio UI
## Git Provider Integration
Honeydew supports integration with all major Git providers.
Choose your preferred provider for detailed setup instructions:
* [GitHub](/docs/integration/git/github)
* [GitLab](/docs/integration/git/gitlab)
* [Bitbucket](/docs/integration/git/bitbucket)
* [Azure DevOps](/docs/integration/git/azure-devops)
## Git Repository Structure
Different [workspaces](/docs/governance/workspaces) reside within the same repository as separate folders,
each containing their separate semantic layer metadata, [environment settings](/docs/governance/environments) and more.
### Repository Structure
```
your-organization-repo/
├── hr-workspace/
│ ├── schema/
│ | ├── entity1/
│ | | ├── attributes/
│ | | | ├── attribute1.yml
│ | | | ├── attribute2.yml
│ | | | └── ...
│ | | ├── datasets/
│ | | | └── entity1_dataset.yml
│ | | ├── metrics/
│ | | | ├── metric1.yml
│ | | | ├── metric2.yml
│ | | | └── ...
│ | | └── entity1.yml
│ | ├── entity2/
│ | └── ...
│ ├── domains/
│ | ├── domain1.yml
│ | └── ...
│ ├── perspectives/
│ | ├── dynamic_dataset1.yml
│ | └── ...
│ └── workspace.yml
├── gtm-workspace/
│ └── ...
└── ...
```
Each workspace folder contains:
* **schema/**: All entities, each with its attributes, metrics, and datasets
* **domains/**: Domain configurations and settings
* **perspectives/**: Dynamic datasets, including pre-aggregates
* **workspace.yml**: Workspace-level settings and configurations, including [environments settings](/docs/governance/environments)
Different [workspaces](/docs/governance/workspaces) within an organization can share the same Git repository,
but maintain complete semantic separation through folder isolation
## Git-Based Development Workflow
### Branch-Based Development
Changes in Honeydew are made over branches in Git, following standard development practices:
1. **Branches**:
* Users work on branches for their changes
* Branches in Git are automatically created when a user creates a new branch for making changes
in Honeydew Studio
* Changes within a branch that are done in Honeydew Studio UI,
are scoped to a specific workspace and do not affect other workspaces
* Branches are shared across all users within a workspace, allowing any user to access and
collaborate on any branch
* Each Honeydew branch maps to a Git branch named `/` — for example,
branch `q3-fixes` of workspace `sales` is stored on the Git branch `sales/q3-fixes`.
The `prod` version of every workspace lives on the repository's default branch.
CI/CD tools use this convention to detect which workspace and branch a change belongs to
(see the [CI/CD Overview](/docs/governance/ci-cd/overview))
2. **Discarding Changes**: At any time, users can discard a branch with all the changes that were made in it
3. **Production Publishing**:
* When users click **Publish changes** in Honeydew Studio UI, a **Pull/Merge Request** is automatically created
in the Git repository, from the underlying Git branch to the main Git branch.
* Users can review all the changes they have performed, before publishing.
4. **Merging**:
Two workflows are supported:
* The Pull/Merge Request is **automatically merged** after creation (recommended for evaluation period and small teams)
* The Pull/Merge Request **requires manual review** and approval before merging (recommended for production workflows)
Currently there is no way to configure automatic/manual merging permission per user or per branch.
This functionality is coming soon.
Once merged, the `prod` version is updated with the new changes and becomes the new shared source of truth
for all users and tools that use the semantic model represented by the workspace.
In some cases you would want to manually review and merge Pull/Merge Requests, and not allow automatic merging
at any circumstance. This can be achieved by setting branch protection rules in your Git provider
to require mandatory review and approval for any Pull/Merge Requests, before merging to the main branch.
Additional fine-grained rules, such as requiring named approvers for a specific workspace or
for specific entities/metrics, can be configured at Git provider level, using required
reviewer rules, the **Code Owners** functionality, or other branch protection policies.
See [Change Approval](/docs/governance/change-approval) for step-by-step instructions on requiring
approval from specific people for changes to a specific workspace.
### Branch cleanup after merge
The branch list in Honeydew Studio reflects the branches that exist in the Git repository,
so deleting a Git branch also removes that branch from Honeydew.
When a Pull/Merge Request is merged in the Git provider rather than in Honeydew Studio,
nothing deletes the underlying branch, and merged branches accumulate in the branch list.
Configure your Git provider to delete the source branch on merge to clean them up:
| Provider | Setting |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [GitHub](/docs/integration/git/github#clean-up-merged-branches) | **Automatically delete head branches** (repository-wide) |
| [GitLab](/docs/integration/git/gitlab#clean-up-merged-branches) | **Enable "Delete source branch" option by default** (project-wide) |
| [Bitbucket](/docs/integration/git/bitbucket#clean-up-merged-branches) | **Delete source branch by default** (repository or project) |
| [Azure DevOps](/docs/integration/git/azure-devops#clean-up-merged-branches) | **Delete `` after merging** (selected per Pull Request) |
This covers only branches that were merged through a Pull/Merge Request. Branches that were
never published, and branches whose Pull/Merge Request was closed without merging, still need
to be discarded in Honeydew Studio.
Honeydew caches the branch list, and changes made directly in Git — including branches deleted
by your Git provider on merge, or deleted manually — do not refresh it on their own.
To refresh it in Honeydew Studio, open the workspace menu and select
**Reload current workspace for all users**.
From a pipeline, use the **Reload All Workspaces** mutation
([GraphQL](/docs/integration/graphql-api#workspaces-and-branches)) or `RELOAD_ALL_WORKSPACES` in the
[Snowflake Native App](/docs/integration/snowflake-native-app#workspace-and-branches). These refresh
the branch list for the calling user only — to refresh it for everyone, use the
**for All Users** variants, such as `RELOAD_ALL_WORKSPACES_FOR_ALL_USERS`.
### Changes history
All changes to the semantic layer metadata are tracked in Git, providing a complete history of every modification.
Users can view the history of changes, compare different versions, and revert to previous states if needed.
Currently, reverting changes must be done outside of Honeydew Studio UI, by reverting the relevant commits in Git.
Reverting changes from within Honeydew Studio UI is coming soon.
### Collaboration Features
Honeydew provides real-time collaboration capabilities through shared branch access:
* **Shared Branch Access**: Any user can access and work on any branch created
by other users, enabling collaborative development on features or analyses
* **Branch-based Collaboration**: Teams can create branches for collaborative
projects, with multiple users contributing changes to the same branch
* **Change Detection**: Users receive status updates when other users make changes to the `prod` version
while they are working on their branch
* **Branch Refresh**: Users can refresh their branch with the latest changes from `prod`,
similar to standard Git development flows
* **Conflict Resolution**: Honeydew Studio does not provide any dedicate tools for conflict resolution.
Standard Git workflows apply for resolving conflicts within any yaml files.
Since Honeydew stores each entity, attribute, metric, dataset, and domain as separate YAML files,
the chances of merge conflicts are significantly reduced, even with multiple users working concurrently.
## Development Workflows
Development flows outside of Honeydew Studio UI can operate directly on the Git repository.
### Edit files directly
The following use cases can benefit from using a code editor directly on files in the Git repository:
* **Major Refactoring**: Large-scale changes can be performed by editing the semantic layer YAML files directly
* **Bulk Operations**: Mass updates across multiple entities, metrics, or attributes
* **Automation**: Script-based metadata management and deployment
You can run validations on changes in the Git repository by using the Honeydew Snowflake Native Application -
you can find an [example here](integration/snowflake-native-app#example-workflow).
### Use with your Git provider capabilities
* **Code Review**: Honeydew creates Pull/Merge Requests that can be reviewed within your Git provider UI
* **CI/CD Pipelines**: Use Git provider CI/CD capabilities to validate, deploy, and publish
semantic layer changes automatically. See the [CI/CD Overview](/docs/governance/ci-cd/overview)
for the full workflow, or the [GitHub Action](/docs/governance/ci-cd/github-actions) to validate
pull requests on GitHub
* **Complex conflict resolution**: Use your Git tools to handle complex merge conflicts if they happen