Project113

Ref (Branch/Tag) Policies

Ref policies protect branches and tags by defining who can pull, push, merge, or force push to specific refs using pattern matching.

How Ref Policies Work

When a user attempts a Git operation (pull, push, merge, force push) on a branch or tag, the platform evaluates ref policies in priority order. The first matching policy determines whether the action is allowed or denied.

Creating a Ref Policy

  1. Navigate to your repository's Settings.
  2. Go to the Ref Policies section.
  3. Click Add Policy.
  4. Configure the policy:
    • Name — A descriptive name (e.g., "Protect master branch").
    • Patterns — SQL LIKE patterns to match ref names (e.g., master, release/%, v%). Use % to match any sequence of characters and _ to match exactly one character.
    • Ref type — Whether this applies to branches (heads), tags (tags), or other refs. Pick one per policy.
    • Priority — Higher priority policies are evaluated first.
    • Permissions — Which actions to allow or deny (read, write, create, delete, merge, force push).
    • Subjects — Who this policy applies to (accounts, members, groups, roles, or audiences). All permissions in a policy share the same subject set, so use a separate policy when different subjects need different permissions.
  5. Click Save.

Example: Protecting Master

To protect the master branch from force pushes and restrict merges to the maintainer role, create two policies:

  • Name: "Block force pushes" — Pattern: master, Ref type: heads
  • Deny: git.ref.force_push for subjects Members
  • Name: "Maintainers can merge" — Pattern: master, Ref type: heads
  • Allow: git.ref.merge for the maintainer role

See the Permissions Reference for all Git reference permissions and their descriptions.