> ## 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.

# Change Approval

When several [workspaces](/docs/governance/workspaces) share one Git repository, you can require
that changes to a specific workspace are approved by a named group of people, while changes
to the other workspaces are unaffected.

## How it works

Each workspace is a separate top-level folder in the repository — the `sales` workspace
lives in `/sales/`
(see [repository structure](/docs/governance/git-version-control#git-repository-structure)).
When a user clicks **Publish changes** in Honeydew Studio, a pull request is opened into the
repository's default branch.

A path-based approval rule in your Git provider requires approval from a named group on any
pull request that changes files in the workspace folder. Because the rule is tied to a
folder path, it applies only to pull requests that touch that workspace.

All major Git providers support such rules — see
[Other Git providers](#other-git-providers). The section below covers
[GitHub](/docs/integration/git/github).

<Note>
  This controls **who approves changes before they reach `prod`**. It does not control who can
  edit the workspace in Honeydew Studio — for that, see
  [workspace level access control](/docs/governance/workspaces#workspace-level-access-control).
</Note>

## Require approval for a workspace on GitHub

On GitHub, the approval requirement is a **Required reviewers** rule in a branch
[ruleset](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets).
Adding rulesets requires **admin permissions** on the repository, and the approvers must be
in a GitHub **team** — the rule accepts teams, not individual users.

The example below protects a workspace whose folder is `sales`, using a team called
`sales-approvers`.

<Steps>
  <Step title="Create a team for the approvers">
    [Create a team](https://docs.github.com/en/organizations/organizing-members-into-teams/creating-a-team)
    with the people who should approve changes, and give it the **Write** role on the
    repository.

    <Warning>
      The team must be **visible** and have **Write** access to the repository. GitHub ignores
      secret teams, and teams without write access — even if every member already has write
      access individually.
    </Warning>
  </Step>

  <Step title="Create the ruleset">
    In the repository's **Settings > Rules > Rulesets**,
    [create a branch ruleset](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository)
    that is **Active**, targets the default branch, and has:

    * **Require a pull request before merging**, with **Required approvals** set to **0**
    * A **Required reviewers** entry with the `sales-approvers` team, the number of approvals
      to require, and the file pattern `sales/**`
    * An empty **Bypass list** — if the `Honeydew.ai` application can bypass the ruleset, it
      merges pull requests automatically and the approval requirement never applies
      (see [GitHub setup](/docs/integration/git/github))

    <Warning>
      Set **Required approvals** to **0**. It applies to *every* pull request in the repository,
      so any value above `0` would also require approvals for your other workspaces. The
      **Required reviewers** entry is what requires approval for the protected folder.
    </Warning>

    File patterns use `.gitignore` syntax. A deeper path, such as `sales/entities/**`, protects
    part of a workspace instead of all of it. To protect more than one workspace, add a
    reviewer entry for each.
  </Step>
</Steps>

<Note>
  Keep this ruleset **separate** from the one that requires the
  [validation status check](/docs/governance/ci-cd/github-actions). A bypass applies to a whole
  ruleset — with separate rulesets, the Honeydew application can keep bypassing the validation
  check for unprotected workspaces while being unable to bypass the approval requirement.
</Note>

<Note>
  **Require a pull request before merging** applies to the whole default branch: direct
  pushes stop working for every workspace, including
  [direct edits to metadata files](/docs/governance/git-version-control#edit-files-directly).
  Pull requests for the other workspaces still merge without approval.
</Note>

<Note>
  To name individual users as approvers, or on a user-owned repository that has no teams, use
  a
  [`CODEOWNERS` file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)
  with the **Require review from Code Owners** rule instead. The folder patterns then live in
  the `CODEOWNERS` file rather than in a **Required reviewers** entry; the
  **Required approvals** setting, the bypass list, and the repository-wide effects are the
  same.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The pull request can be merged without approval">
    Check, in order:

    * The folder pattern matches the workspace folder name exactly, including capitalization.
      A non-matching pattern requests no reviewers and reports no error
    * The **Enforcement status** of the ruleset is **Active**
    * The ruleset targets the default branch
    * Neither the Honeydew application nor the person merging is in the **Bypass list**
  </Accordion>

  <Accordion title="No reviewers are requested on the pull request">
    Usually the team cannot be resolved. Common causes:

    * The team is **secret** rather than visible
    * The team does not have **Write** access to the repository
    * The team belongs to a different organization than the one that owns the repository
    * The folder pattern does not match any file that the pull request changes
  </Accordion>

  <Accordion title="Other workspaces now require approval too">
    **Required approvals** is set above `0`. That setting applies to every pull request in the
    repository, independently of the folder pattern. Set it back to `0`.

    Also check that no folder pattern matches all files, such as `**`.
  </Accordion>

  <Accordion title="Pull requests for other workspaces stopped merging automatically">
    The approval rules were added to the same ruleset that requires the
    [validation status check](/docs/governance/ci-cd/github-actions), and removing the Honeydew
    application from that ruleset's bypass list also stopped it bypassing the check. Move the
    approval rules into a separate ruleset, and restore the bypass on the validation ruleset.
  </Accordion>

  <Accordion title="Direct pushes to the default branch are rejected">
    This is expected: **Require a pull request before merging** applies to the whole default
    branch. Open a pull request instead.
  </Accordion>
</AccordionGroup>

## Other Git providers

All major providers can restrict approval to specific people by path, but the feature has a
different name in each, and Bitbucket Cloud does not enforce it:

| Provider                                      | Feature                            | Where it is defined                                    | Enforced                                                                                                      |
| --------------------------------------------- | ---------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| [GitHub](/docs/integration/git/github)             | Required reviewers, or Code Owners | Repository ruleset, or `.github/CODEOWNERS`            | Yes                                                                                                           |
| [GitLab](/docs/integration/git/gitlab)             | Code Owners                        | `CODEOWNERS`                                           | Yes, with **Required approval from code owners** on a protected branch. Requires the Premium or Ultimate tier |
| [Bitbucket](/docs/integration/git/bitbucket)       | Code owners                        | `.bitbucket/CODEOWNERS`                                | No — owners are added as *suggested* reviewers and can be removed by the author                               |
| [Azure DevOps](/docs/integration/git/azure-devops) | Automatically included reviewers   | Branch policy with a path filter, configured in the UI | Yes                                                                                                           |

<Note>
  On Bitbucket Cloud, code owners cannot enforce approval on their own. Use a merge check
  that requires a minimum number of approvals, keeping in mind that it applies to all pull
  requests in the repository, not only to one workspace.
</Note>

## Limitations

* Approval is required for every change to the protected folder, regardless of who
  published it
* Honeydew opens pull requests through its Git application, rather than as the user who
  published the change. To enforce separation of duties, keep the people who publish
  changes out of the approvers team, and require more than one approval for sensitive
  workspaces