Ref Policies

Code Storage uses ref policies for branch protection. Each ref policy limits writes from one JWT. A ref policy is not a repository setting. It applies only to a request that uses its JWT. Give each client or task a JWT with the limits it needs.

A git:write scope grants write access. A ref policy can limit that access, but it cannot grant access.

The SDK accepts refPolicies on getRemoteURL(), getEphemeralRemoteURL(), and getImportRemoteURL(). The write methods in this guide also accept this option.

Policy operations

Operation	Constant	Effect
`no-force-push`	`OP_NO_FORCE_PUSH` (TypeScript/Python) / `OpNoForcePush` (Go)	Reject a non-fast-forward move when the ref already exists. Permit ref creation, ref deletion, and a fast-forward move.
`no-push`	`OP_NO_PUSH` (TypeScript/Python) / `OpNoPush` (Go)	Reject all updates to the matched ref. This includes ref creation and deletion.
`verify-sig`	`OP_VERIFY_SIG` (TypeScript/Python) / `OpVerifySig` (Go)	Reject an update when an introduced commit lacks a valid signature from a registered key.

Add a ref policy

The refPolicies option is an ordered list of rules. Each rule has a pattern and an optional ops list. This policy permits branches under agents/ in the default namespace. It rejects all other refs.

const agentPolicies = [
  { pattern: 'agents/*' }, // Permit these branches.
  { pattern: '*', ops: ['no-push'] }, // Reject every other ref.
];

const url = await repo.getRemoteURL({
  permissions: ['git:read', 'git:write'],
  refPolicies: agentPolicies,
});

agent_policies = [
    {"pattern": "agents/*"},  # Permit these branches.
    {"pattern": "*", "ops": ["no-push"]},  # Reject every other ref.
]

url = await repo.get_remote_url(
    permissions=["git:read", "git:write"],
    ref_policies=agent_policies,
)

agentPolicies := storage.RefPolicyList{
    {Pattern: "agents/*"}, // Permit these branches.
    {Pattern: "*", Ops: storage.Ops{storage.OpNoPush}}, // Reject every other ref.
}

url, err := repo.RemoteURL(ctx, storage.RemoteURLOptions{
    Permissions: []storage.Permission{storage.PermissionGitRead, storage.PermissionGitWrite},
    RefPolicies: agentPolicies,
})

A rule with no ops permits its matched ref. Code Storage also permits a write when no rule matches. Add a final * rule with no-push when you need an allowlist. This rule rejects each ref that no earlier rule permits.

Match refs

Use an exact ref or a prefix glob. A prefix glob has one final * after a slash. Use * to match all refs. Code Storage treats a pattern without refs/ as a branch name in the default namespace.

Pattern	Pattern after normalization	Match
`main`	`refs/heads/main`	The `main` branch in the default namespace
`agents/*`	`refs/heads/agents/*`	Branches under `agents/` in the default namespace
`refs/heads/*`	`refs/heads/*`	All branches in the default namespace
`refs/tags/*`	`refs/tags/*`	All tags in the default namespace
`refs/namespaces/ephemeral/refs/heads/*`	unchanged	All ephemeral branches
`*`	unchanged	All refs in all namespaces

Code Storage uses the first rule whose pattern matches the ref. It does not check a later rule when the first rule has no ops.

Put a broad rule after each specific rule. An earlier * rule hides all later rules.

Apply policies to ephemeral branches

Ref policies apply to ephemeral branches. Code Storage stores them in the ephemeral ref namespace. The policy sees the complete stored ref. For example, the ephemeral branch preview/pr-123 has this ref:

refs/namespaces/ephemeral/refs/heads/preview/pr-123

A short preview/* pattern becomes refs/heads/preview/*. It matches branches in the default namespace only.

Target	Pattern
One ephemeral branch	`refs/namespaces/ephemeral/refs/heads/preview/pr-123`
Ephemeral branches under `preview/`	`refs/namespaces/ephemeral/refs/heads/preview/*`
All ephemeral branches	`refs/namespaces/ephemeral/refs/heads/*`
Refs in the default and ephemeral namespaces	`*`

This URL permits only ephemeral branches under agents/:

const url = await repo.getEphemeralRemoteURL({
  permissions: ['git:read', 'git:write'],
  refPolicies: [
    { pattern: 'refs/namespaces/ephemeral/refs/heads/agents/*' },
    { pattern: '*', ops: ['no-push'] },
  ],
});

url = await repo.get_ephemeral_remote_url(
    permissions=["git:read", "git:write"],
    ref_policies=[
        {"pattern": "refs/namespaces/ephemeral/refs/heads/agents/*"},
        {"pattern": "*", "ops": ["no-push"]},
    ],
)

url, err := repo.EphemeralRemoteURL(ctx, storage.RemoteURLOptions{
	Permissions: []storage.Permission{
		storage.PermissionGitRead,
		storage.PermissionGitWrite,
	},
	RefPolicies: storage.RefPolicyList{
		{Pattern: "refs/namespaces/ephemeral/refs/heads/agents/*"},
		{Pattern: "*", Ops: storage.Ops{storage.OpNoPush}},
	},
})

See Ephemeral Namespace for remote URLs and branch promotion.

Use a policy with an SDK call

Pass the same option to an SDK method that writes a ref. The SDK puts the rules in the JWT for that call.

await repo.createBranch({
  baseRef: headSha,
  targetBranch: 'agents/research-bot',
  refPolicies: agentPolicies,
});

await repo.create_branch(
    base_ref=head_sha,
    target_branch="agents/research-bot",
    ref_policies=agent_policies,
)

_, err := repo.CreateBranch(ctx, storage.CreateBranchOptions{
    BaseRef:      headSHA,
    TargetBranch: "agents/research-bot",
    RefPolicies:  agentPolicies,
})

These SDK write methods accept a ref policy:

createBranch() and deleteBranch()
createTag() and deleteTag()
createCommit(), createCommitFromDiff(), and restoreCommit()
merge() and pullUpstream()
createNote(), appendNote(), and deleteNote()

The policy checks the target ref.

Add a policy to a JWT

The SDK converts refPolicies to the refs JWT claim. Each claim entry is an ordered [pattern, ops] pair.

{
  "refs": [
    ["refs/heads/main", ["no-force-push"]],
    ["*", ["no-push"]]
  ]
}

Keep the array order. JSON objects do not represent these rules. See Authentication & Security for the other JWT claims.

Commit signature checks

The verify-sig operation checks each commit that an update introduces to the matched ref. Code Storage checks each signature against the registered organization keys. A registered key does not enable a check by itself. Add verify-sig to a ref policy rule. See Commit Signing for key setup, check behavior, and an example.

Do not target a verify-sig ref with createCommit, createCommitFromDiff, or merge. These methods create unsigned commits.

Where ref policies apply

Code Storage checks ref policies on these write paths:

A Git push over HTTPS
A supported SDK or HTTP API method that updates a ref

Legacy `ops` option

Remote URL methods also accept a top-level ops list. This old option applies its operations to the * rule. Use refPolicies in new code. It shows the catch-all rule and supports specific refs.

Getting Started

Features

Workflows

Reference

Policy operations

Add a ref policy

Match refs

Apply policies to ephemeral branches

Use a policy with an SDK call

Add a policy to a JWT

Commit signature checks

Where ref policies apply

Legacy `ops` option

​Policy operations

​Add a ref policy

​Match refs

​Apply policies to ephemeral branches

​Use a policy with an SDK call

​Add a policy to a JWT

​Commit signature checks

​Where ref policies apply

​Legacy ops option

Policy operations

Add a ref policy

Match refs

Apply policies to ephemeral branches

Use a policy with an SDK call

Add a policy to a JWT

Commit signature checks

Where ref policies apply

Legacy `ops` option