Contents
Rules for agents
Write your team's rules for agents in the [policy] section of the committed .gitta.toml. gitta checks them in its git hooks and in the pull request check. When work breaks a rule, the check fails with one plain line, like a failing test. gitta never asks a question.
Write the rules
# .gitta.toml
gate = "pytest -q"
weakened_checks = "block"
[policy]
agents_push_to_main = "block"
agents_never_change = ["infra/**", ".github/workflows/*.yml"]
needs_approval = ["db/migrations/**", "src/auth/**"]| Rule | Effect |
|---|---|
agents_push_to_main = "block" | An agent cannot push to main. It pushes a branch and opens a pull request. The default is "allow". |
agents_never_change = [globs] | Agent work that changes a matching path does not merge, does not push and fails the pull request check. Approval does not change this. |
needs_approval = [globs] | Agent work that changes a matching path merges only with a person's approval. |
Globs use * inside one folder and ** across folders. A plain folder name such as "src/auth" covers everything in it.
Commit the file. gitta reads the rules from the committed file on main, so only a reviewed commit to main changes them. A broken [policy] section fails the check with the line number, so a typo never turns the rules off.
What a person's approval is
| Where | Approval |
|---|---|
| A merge on a laptop | A person runs the merge, outside an agent session. An agent that runs the merge itself gets the refusal. |
gitta land | A person runs gitta land. When an agent runs it, a person runs gitta approve <agent> <reason> first. |
| The pull request check | An approving review on the pull request. |
What an agent sees
The agent gets the reason in the output of its git command and can change its work.
$ git push origin main
gitta: add-search may not push to main directly; the rule is in the [policy] section of .gitta.toml. Push a branch and open a pull request.
error: failed to push some refs
$ git merge add-search
gitta: add-search changed infra/prod/main.tf, and agents never change infra/**; the rule is in the [policy] section of .gitta.toml.Each refusal is in the audit trail as a blocked event, and it counts as a stopped merge in the usage report.
Which work is agent work
On a machine with gitta, the work of every agent worktree gitta knows, and every git command an agent runs, is agent work. In the pull request check, a pull request is agent work when one of its commits has a co-author trailer of an AI tool, such as Claude, Codex, Copilot or Cursor.
Team rules from the server Enterprise
A team server can add rules for every repository. Put a [policy] section in a file and give the server its path in GITTA_POLICY_FILE.
# team-policy.toml on the server
[policy]
agents_push_to_main = "block"
agents_never_change = ["**/secrets/**", "deploy/prod/**"]The server also shows its rules at GET /v1/policy. It sends them with each answer to an agent report, and gitta keeps them in .gitta/server-policy.toml. The hooks read that copy, so a check never waits for the server. The pull request check fetches the rules when GITTA_SERVER and GITTA_SERVER_TOKEN are set.
Server rules add to the rules of the repository. A repository cannot remove them or set them to "allow". The message names the server as the source of the rule.
gitta: add-search may not push to main directly; the rule is in the team policy on the gitta server. Push a branch and open a pull request.For the related setting for removed tests and weakened checks, see Warnings.