> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Git guard

> Refuse new remote branches and pull requests on configured machines with ttr git guard, keeping fleet work on the direct-to-main flow.

## Why this exists

Fleet machines publish `tutur3u/platform` and `upskii/platform` work directly to
`main`: review locally, rebase onto `origin/main`, commit as the configured
identity with a DCO sign-off, push fast-forward only, then run `bun git-sync`.
Pull requests and new remote branches from fleet machines are not part of that
flow. `ttr git guard` enforces it on each opted-in machine. Pushes are refused
before Git makes any network write, and PR creation is refused before `gh`
contacts GitHub.

## What it enforces

The guard applies only to pushes whose remote resolves to a guarded repository
(default: `tutur3u/platform`, `upskii/platform`). It matches on the last two
path segments of the remote URL, so https, ssh and scp-style remotes all match.
Credentials in a URL are never logged.

| Push | Result |
| - | - |
| `main` / `production`, fast-forward | allowed |
| `main` / `production`, non-fast-forward, create or delete | refused; no override |
| new branch (anything else) | refused; overridable |
| existing non-main branch | refused by default (`existingBranches: "allow"` to permit); overridable |
| existing `release-please--branches--*` | allowed; creating one is refused |
| branch matching `allowBranches` | allowed |
| deleting a non-protected branch, any tag | allowed and logged |
| other refs (`refs/notes/*`, …) | refused; overridable |

The ancestry check runs locally (`git merge-base --is-ancestor`). A stale clone
that lacks the remote commit is refused until you fetch and rebase.

The gh guard refuses these on guarded repositories:

* `gh pr create` (and its alias `gh pr new`)
* `gh api` POSTs to `repos/<owner>/<repo>/pulls`
* `gh api graphql` with `createPullRequest`
* `gh stack submit`

The repository comes from `-R/--repo`, `GH_REPO`, the REST path, or the
working directory's remotes. A GraphQL creation whose repository cannot be
resolved is refused. Every other `gh` command passes straight to the real `gh`
without starting Bun.

### Release flows that keep working

* release-please, Dependabot and the `release-*-package` workflows push from
  GitHub Actions, so client hooks never see them.
* `bun git-sync` pushes `main` and `production` as fast-forwards.
* `bun git-release-please` merges locally into `main`, then pushes `main` as a
  fast-forward.
* `scripts/tuturuuu-bot-token.js` (task-branch push plus `gh pr create`) is
  refused on guarded machines by design. A real exception uses a one-shot
  override.

## Install and operate

```bash theme={null}
ttr git guard install --shell zsh --agents # or bash / none; --agents optional
ttr git guard status                       # add --json for receipts
ttr git guard log --limit 20
```

`install` writes `~/.tuturuuu/git-guard/` (honours `TTR_GIT_GUARD_HOME`):

* `config.json`: opt-in config (`enabled`, `machine`, `repos`,
  `ffOnlyBranches`, `existingOnlyPrefixes`, `allowBranches`,
  `existingBranches`).
* `hooks/`: managed dispatchers. The global `core.hooksPath` points here.
  Each dispatcher chains to the hook the repository would otherwise run: the
  repo's recorded `ttr-guard.chainHooksPath` (for example `.githooks`), the
  previous global hooksPath, or `.git/hooks`. `.githooks/pre-push`, Git LFS and
  similar hooks keep working.
* `bin/gh`: the gh shim. A managed shell block puts it first on `PATH`.
  A gh alias cannot do this, because aliases cannot shadow built-in commands.
* `log.jsonl`: every refusal, guarded allow, override creation and
  consumption, install and uninstall.

A clone with a local `core.hooksPath` (this repository sets `.githooks` on
`bun install`) would bypass a global hooksPath. Two mechanisms close that gap:

* `install --repo <path>` repoints such clones and records the previous value.
* `scripts/install-git-hooks.js` keeps a clone on the guard's directory whenever
  `git config --global ttr-guard.hooksPath` names an installed guard.

`ttr git guard status` flags any listed clone that still bypasses the guard.

`ttr upgrade` and `ttr upgrade activate` refresh the hook and shim through the
new release. `ttr git guard uninstall` restores the previous hooksPath values and
shell files, and keeps the log.

## Exceptions

There is no environment-variable bypass. A real exception (release-please,
Dependabot, a USER-approved stack) uses an explicit override:

```bash theme={null}
ttr git guard allow-once --kind push --repo tutur3u/platform \
  --ref <branch> --reason "<why>" --approved-by <who>
ttr git guard allow-once --kind pr --repo tutur3u/platform \
  --reason "<why>" --approved-by <who>
```

Overrides:

* need a reason and an approver
* expire after 15 minutes by default (`--ttl-minutes`, at most 120)
* are consumed by an atomic rename, so exactly one push or PR creation uses each
  one
* are logged both when created and when consumed

Protected-branch rewrites and deletions cannot be overridden.

## Limits and server-side backstop

Client hooks are advisory: `git push --no-verify` skips them, and the GitHub MCP
server talks to the API directly instead of through `gh`. `install --agents`
closes the MCP gap for Claude agents. For each Claude settings file
(`~/.claude/settings.json`, `$CLAUDE_CONFIG_DIR`, and each `~/.claude-t3/<account>/`)
it:

* backs the file up once into the guard home
* adds only `permissions.deny` rules for the GitHub MCP `create_pull_request` and
  `create_pull_request_with_copilot` tools; no other key or rule is changed
* is idempotent

`status` lists each file. `uninstall` removes exactly the rules the guard added
and keeps any rule the user already had.

The durable backstop is the server-side ruleset below. The CLI never applies
it.

## Server-side ruleset (tutur3u/platform)

`tutur3u/platform` adds one repository ruleset after the local guard ships.
`upskii/platform` is private on the free plan and stays local-guard only.

```json theme={null}
{
  "name": "D354b no new remote branches (fleet direct-to-main)",
  "target": "branch",
  "enforcement": "active",
  "conditions": {
    "ref_name": {
      "include": ["~ALL"],
      "exclude": [
        "refs/heads/main",
        "refs/heads/production",
        "refs/heads/release-please--branches--**",
        "refs/heads/dependabot/**"
      ]
    }
  },
  "rules": [{ "type": "creation" }],
  "bypass_actors": []
}
```

* **Scope.** The only rule is `creation`: updates to existing branches,
  deletions and pull requests are untouched. Fast-forward pushes to `main` and
  `production` are excluded here and keep their existing D191 and
  protected-branch rulesets unchanged.
* **Release bots by ref, not by bypass.** The legitimate server-side branch
  creators are release-please (`release-please--branches--*`, through
  `RELEASE_PLEASE_TOKEN`) and Dependabot (`dependabot/*`).
  `release-please-auto-merge` only pushes `main` and deletes branches. The
  ruleset excludes those ref patterns instead of naming bypass actors, because
  fleet lanes push as the same user identity that holds bypass on the existing
  rulesets. A user bypass would void the rule for exactly the pushes it exists
  to stop.
* **Side effects.** GitHub UI "revert" branches and agent-created branches are
  refused. A genuine emergency branch needs a reviewed ruleset change.
* **Apply.** The security reviewer gives an exact acknowledgement of this JSON,
  then the named executor applies it once:
  `gh api -X POST repos/tutur3u/platform/rulesets --input <file>`. The executor
  reads it back by id and compares it with the acknowledged JSON.
* **Applied.** Ruleset `27390877`, created on 2026-11-17 under acknowledgement
  D354B-RULESET-01. The readback matched every field. A throwaway
  `guard-probe/*` push with `--no-verify` was rejected with
  `GH013 … creations being restricted`, and no probe ref exists.
* **Changes.** There is no merge queue today. Enabling one first needs a
  `refs/heads/gh-readonly-queue/**` exclusion. Every change to this ruleset,
  including one for an emergency branch, needs its own exact acknowledgement.
* **Verify.** The next release-please run still creates or updates its branch,
  and a Dependabot branch still appears. A throwaway branch pushed with
  `--no-verify` by a normal user token is rejected by the server. Delete nothing
  else.

## Rollout check

On each machine, after `ttr upgrade` and `ttr git guard install`:

1. `git push origin HEAD:guard-probe/<machine>` from a guarded clone is refused,
   and no remote branch appears.
2. `gh pr create --head guard-probe/<machine>` in the same clone is refused.
3. `ttr git guard status --json` shows the hook current, global hooksPath active,
   the gh guard active, and both refusals in `lastRefusals`.

Regression coverage lives in `packages/sdk/src/cli/git-guard-*.test.ts` and
`scripts/install-git-hooks.test.js`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.