Policy Approval

Policy approval lets you define, per repository, what a pull request needs in order to be approved — for example "Hud says it's safe to merge and our security scan passed" — and have Hud enforce it on every PR.

Hud evaluates the policy each time the PR changes (new commits, reviews, labels, finished checks) and reports the result as a single GitHub commit status named Hud Approval Policy. Make that status required in your branch protection, and the policy becomes your merge gate.

Policy approval is based on the open-source policy-bot from Palantir, and uses the same policy.yml format. This page covers the basics; for the full list of rules, predicates, and options, see the policy-bot documentation.

Turn it on

1. In Hud, go to Settings → Agentic Workflows and open the repository.
2. Turn on Policy approval.
3. Write your policy in the Hud policy editor and save (account admins only — other users see it read-only). Or, commit a .policy.yml to the repository instead (see Which policy applies).
4. In GitHub, make Hud Approval Policy a required status check. Go to the repository's Settings → Rules → Rulesets (or Settings → Branches for classic branch protection rules), edit the rule for your default branch, turn on Require status checks to pass, and add Hud Approval Policy. See GitHub's guide to requiring status checks.

Writing a policy

A policy has two parts:

• approval_rules — named rules. Each rule can have an if block (when the rule applies — otherwise it's skipped) and a requires block (what must be true for it to be approved: reviews, passing checks, and so on).
• policy.approval — which rules must be approved. Listed rules must all pass; wrap them in or: / and: to combine them. Skipped rules are ignored.

Pick rule names that finish the sentence "This PR is approved if…" and keep them short — they show up in the status description on the PR.

Hud's own check appears on PRs as Hud Reviewer — that's the name to use in your policy.

Example 1: Hud + code review tool + security reviewer

Approve only when all three checks pass on the latest commit.

policy:
  approval:
    - all required checks passed

approval_rules:
  - name: all required checks passed
    requires:
      conditions:
        has_status:
          conclusions: [success]
          statuses:
            - "Hud Reviewer"
            - "static-code-analysis-cr-tool"
            - "security-reviewer"

Example 2: Hud approves, unless sensitive folders changed

Hud's check is enough on its own, unless the PR touches infra/, migrations/, or src/payments/. Then the Hud rule is skipped and a maintainer has to approve.

policy:
  approval:
    - or:
        - hud passed and no sensitive paths
        - a maintainer approved

approval_rules:
  - name: hud passed and no sensitive paths
    if:
      no_changed_files:
        paths:
          - "^infra/"
          - "^migrations/"
          - "^src/payments/"
    requires:
      conditions:
        has_status:
          conclusions: [success]
          statuses: [Hud Reviewer]

  - name: a maintainer approved
    requires:
      count: 1
      teams:
        - "my-org/maintainers"

paths are regular expressions matched against file paths from the repository root.

Example 3: Hud approves PRs from trusted authors

PRs opened by alice, bob, or carol only need Hud's check to pass. Everyone else needs one approving review from someone with write access.

policy:
  approval:
    - or:
        - hud passed for a trusted author
        - a reviewer approved

approval_rules:
  - name: hud passed for a trusted author
    if:
      has_author_in:
        users: ["alice", "bob", "carol"]
    requires:
      conditions:
        has_status:
          conclusions: [success]
          statuses: [Hud Reviewer]

  - name: a reviewer approved
    requires:
      count: 1
      permissions: ["write"]

has_author_in also accepts teams ("my-org/team") and organizations.

📘

Always include a fallback

In examples 2 and 3, the second rule is the path to approval when the Hud rule is skipped. Without it, those PRs would have no way to get approved.

Which policy applies

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

1. A policy file in the repository — .policy.yml at the root of the PR's base branch (it can also point to a policy in another repository with remote:).
2. An organization-wide policy — policy.yml at the root of your organization's .github repository.
3. The Hud policy from the Hud UI.

🚧

A policy file in GitHub overrides the Hud policy

If the repository has a .policy.yml (or your organization has a shared .github/policy.yml), the policy you wrote in the Hud UI is not used for that repository. The Hud policy editor tells you when this is the case and which file wins. If that file can't be loaded, the PR reports the error — Hud does not fall back to the Hud policy.

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

Good to know

• Status and check names must match exactly what GitHub shows on the PR. For GitHub Actions, that's the job name.
• Hud Reviewer counts as passed only when Hud says "Safe to merge." "Review required" and "High risk" don't pass. PRs Hud doesn't analyze (not eligible, filtered out, or analysis failed) finish as neutral. To let those through, change conclusions to [success, neutral].
• The Hud policy is validated when you save. If policy-bot rejects it, the errors are listed under the editor and nothing is saved. Very large policies are rejected too; removing comments usually fixes that.
• Saving the Hud policy re-evaluates open PRs, so their Hud Approval Policy status updates without a new push.
• Turning off Policy approval stops status updates. If Hud Approval Policy is still a required check, PRs can't merge until you remove the requirement or turn it back on.
• Test a policy first. Try it on one repository, or add Hud Approval Policy as a required check only after it has run on a few PRs.