Merge When Approved

Merge when approved lets Hud merge pull requests for you once they're approved, so safe PRs don't wait for someone to click the button.

Hud checks the PR each time something changes (new reviews, labels, comments, or finished checks). When the PR is approved and everything else your branch protection requires has passed, Hud merges it as the Hud GitHub app.

Merge when approved is based on the open-source bulldozer from Palantir, and uses the same .bulldozer.yml format. This page covers the basics; for the full list of options, see the bulldozer documentation.

Turn it on

Merge when approved builds on Policy Approval, so turn that on first.

1. In Hud, go to Settings → Agentic Workflows and open the repository.
2. Under Hud PR reviewer, turn on Hud reviewer check and Auto approve PRs.
3. Turn on Merge when approved.
4. Optionally, click Configure merge config to change which PRs merge and how (account admins only). Or, commit a .bulldozer.yml to the repository instead (see Which config applies).

The default config

If you don't set your own config, Hud uses this one:

version: 1
merge:
  ignore:
    labels: ["do not merge", "do-not-merge", "wip"]
  required_statuses: ["Hud Approval Policy"]
  method: squash
  options:
    squash:
      title: pull_request_title
      body: pull_request_body
  delete_after_merge: true

It squash-merges every PR that passed Hud Approval Policy, unless it has a do not merge, do-not-merge, or wip label. The squashed commit uses the PR's title and description, and the branch is deleted after the merge.

Example: merge only labeled PRs

To merge only the PRs you opt in, add a trigger. Here, Hud merges an approved PR only after someone adds the auto-merge label:

version: 1
merge:
  trigger:
    labels: ["auto-merge"]
  ignore:
    labels: ["do not merge", "do-not-merge", "wip"]
  required_statuses: ["Hud Approval Policy"]
  method: squash
  options:
    squash:
      title: pull_request_title
      body: pull_request_body
  delete_after_merge: true

If a PR matches both trigger and ignore, it isn't merged.

🚧

Keep Hud Approval Policy in required_statuses

This is what makes Hud wait for approval. If you remove it, and Hud Approval Policy isn't a required check in your branch protection, PRs can merge as soon as the other checks pass.

Which config applies

When more than one config is defined for a repository, they take precedence in the following order (highest first):

1. A config file in the repository: .bulldozer.yml at the root of the PR's base branch.
2. An organization-wide config: bulldozer.yml at the root of your organization's .github repository.
3. The merge config you saved in the Hud UI.
4. Hud's default config (above).

Because the file is read from the base branch, edits to .bulldozer.yml take effect only after they merge.

Good to know

• Hud follows your branch protection. It merges only when GitHub allows it. If your rules require approving reviews, PRs approved only by the policy won't merge. Use the required Hud Approval Policy status as your gate instead. If your rules restrict who can push, allow the Hud app.
• The merge method must be allowed in the repository. The default is squash. If the repository doesn't allow squash merges, change method to merge or rebase.
• Hud doesn't update PR branches. If your branch protection requires branches to be up to date, the PR author needs to update the branch before Hud can merge.
• The merge config is validated when you save. If bulldozer rejects it, the errors are shown and nothing is saved. Reset to default brings back Hud's default config.
• Saving doesn't re-check open PRs. That would merge every approved PR at once. The new config applies from each PR's next event, such as a new review, label, or finished check.
• Turning off Auto approve PRs also turns off Merge when approved.