Policy approval
Policy approval lets you define, per repository, what a pull request needs before it's approved, for example "Hud says it's safe to merge and our security scan passed." Hud then checks every PR against it.
In the web app, you turn it on with Auto approve PRs, one of a repository's Hud PR reviewer settings.
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.
Before you start
- The PR risk check runs on the repository, with Hud reviewer check turned on. Its check shows on each PR as
Hud Reviewer. If it isn't set up yet, PR risk check walks you through it: connect GitHub, connect your AI provider, link your services and turn on the review. - You're an account admin in Hud. Only admins can turn on Auto approve PRs and write the Hud policy; everyone else sees them read-only. Settings → Members shows each person's role.
- If you don't see Settings → Agentic Workflows, or Auto approve PRs in the repository's panel, chat with our support team or email [email protected] to turn it on for your account.
Turn it on
- In Hud, go to Settings → Agentic Workflows, find the repository under Repository workflow and select Configure.
- Under Hud PR reviewer, turn on Auto approve PRs. It needs Hud reviewer check turned on first.
- Select Configure next to Auto approve PRs, and write your policy in the editor or select Import .yml file. Select Save to close the editor, then Save in the repository panel. Or commit a
.policy.ymlto the repository instead (see Which policy applies). - In GitHub, make
Hud Approval Policya 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 addHud Approval Policy. See GitHub's guide to requiring status checks.
Until there's a policy, saved in Hud or committed to GitHub, Hud posts no Hud Approval Policy status, so a PR that requires it waits. An empty editor shows an example policy (one approving review) in gray. It isn't used until you type a policy, or select Reset to default to fill it in, and save.
Writing a policy
A policy has two parts:
approval_rules: named rules. Each rule can have anifblock (when the rule applies; otherwise it's skipped) and arequiresblock (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 inor:/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 PR risk 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 fallbackIn 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):
- A policy file in the repository:
.policy.ymlat the root of the PR's base branch (it can also point to a policy in another repository withremote:). - An organization-wide policy:
policy.ymlat the root of your organization's.githubrepository. - The Hud policy from the web app.
A policy file in GitHub overrides the Hud policyIf the repository has a
.policy.yml, or your organization has a sharedpolicy.ymlin its.githubrepository, the policy you wrote in the web app 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 doesn't 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 Reviewercounts as passed only when Hud says "Safe to merge." "Review required" and "High risk" don't pass. PRs Hud can't review (not eligible, filtered out by what they change, or the analysis failed) finish asneutral. To let those through, changeconclusionsto[success, neutral]. Drafts, PRs without the trigger label and PRs into a branch other than the default get noHud Reviewercheck at all, so a rule that requires it waits.- The Hud policy is validated when you save. If policy-bot rejects it, nothing is saved: the repository panel shows "policy-bot rejected the Hud policy. Open Configure to see why.", and the editor lists the errors. Very large policies are rejected too; removing comments usually fixes that.
- Saving the Hud policy re-evaluates open PRs, so their
Hud Approval Policystatus updates without a new push. - Turning off Auto approve PRs stops status updates. If
Hud Approval Policyis 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 Policyas a required check only after it has run on a few PRs.
Updated 25 days ago

