Skip to content

Git designed for AI agents.

docs: reloading the policy with SIGUSR1, and graft policy check

Federico Elia7bb27db19d61
diff --git a/doc/graft/CONFIGURATION.md b/doc/graft/CONFIGURATION.md
index 712eccf..f398c0d 100644
--- a/doc/graft/CONFIGURATION.md
+++ b/doc/graft/CONFIGURATION.md
@@ -86,7 +86,7 @@ reference, the first rule that applies decides:
| Key | Type | Default | Description |
|---|---|---|---|
| `actor` | string | `""` (everybody) | Glob (`path.Match` syntax) matched against the actor of the request: the agent of the token, or the acting user ID for the shared token. |
-| `refs` | array of strings | `[]` (every reference) | Globs matched against fully qualified references such as `refs/heads/main`. Syntax is `path.Match`, plus a trailing `/**` that matches any depth, so `refs/heads/**` matches `refs/heads/feature/x`, and any other trailing `**` that matches any remainder, so `refs/heads/release**` matches `refs/heads/release/1.0`. Invalid globs and empty entries are rejected at startup. |
+| `refs` | array of strings | `[]` (every reference) | Globs matched against fully qualified references such as `refs/heads/main`. Syntax is `path.Match`, plus a trailing `/**` that matches any depth, so `refs/heads/**` matches `refs/heads/feature/x`, and any other trailing `**` that matches any remainder, so `refs/heads/release**` matches `refs/heads/release/1.0`. Invalid globs and empty entries are rejected at startup, and by a reload, which keeps the policy in force. |
| `allow` | bool | `false` | Whether a matching update is allowed. |
Example: protect `main` for everybody except the `planner` agent, and allow
@@ -106,7 +106,39 @@ allow = false
allow = true
```
-The policy is read at startup. A change needs a restart.
+#### Reloading the policy
+
+Send SIGUSR1 to the gitaly process (or to gitaly-wrapper, which forwards it):
+it reads its configuration file again and puts the new `[[graft.policy]]` in
+force. SIGHUP is not a reload: it stops the server, or upgrades it in place
+with the graceful-upgrade bootstrap.
+
+- Only the policy is applied. Other changes of the file, `[[graft.agent]]`
+ included, are logged at WARN as needing a restart, and not applied.
+- A file that cannot be read, or whose policy is invalid (a bad glob, an empty
+ `refs` entry), is logged at ERROR and changes nothing: the policy in force
+ stays. Actors of the new policy that name no configured agent are logged at
+ WARN; they are not an error (an actor can be the user ID of a caller with
+ the shared token).
+- An update in flight is decided by the policy in force when the
+ reference-transaction hook runs, while git holds the references' locks: a
+ tightening applies to it even if its earlier checks allowed it. A land batch
+ whose members were admitted under another policy is refused there, and its
+ requests land alone, each decided by the policy in force.
+- Each node reloads its own file: reload every node, then compare their
+ `graft_policy_info`.
+
+Metrics: `graft_policy_reloads_total{result}` (`applied`, `unchanged`,
+`rejected`), `graft_policy_generation` (1 at startup, one more for every
+applied reload) and `graft_policy_info{sha256}` (1 for the hash of the
+policy in force). A denied agent update is logged at INFO with the
+`policy_generation` and `policy_sha256` that denied it; an allowed one at
+DEBUG.
+
+Before a reload, `graft policy check FILE` validates the file's policy as the
+reload will (exit 2 when it would be rejected) and prints its hash; with
+`-repo REPO` it lists the recent updates of the repository that the new policy
+would deny.
### `[[graft.agent]]`
diff --git a/doc/graft/LIMITATIONS.md b/doc/graft/LIMITATIONS.md
index 1272a38..a92680b 100644
--- a/doc/graft/LIMITATIONS.md
+++ b/doc/graft/LIMITATIONS.md
@@ -118,8 +118,16 @@ Git hooks use private.
### Standalone mode
-- The access policy is read at startup. Changing it needs a restart. There is
- no management API for policies.
+- The access policy is reloaded from the configuration file on SIGUSR1
+ (CONFIGURATION.md, "Reloading the policy"); every other setting, the agents
+ and their tokens included, needs a restart. There is no management API for
+ policies, and a reload is per node: nodes that share a storage core run
+ different policies between their reloads.
+- A caller that is not an agent (the shared token, or no token) is checked by
+ the policy only in pre-receive, before the references are locked. A reload
+ between its pre-receive and its commit can let one of its updates through
+ under the previous policy. An agent's update is decided again by the
+ reference-transaction hook with the policy in force.
- Policy globs use `path.Match` semantics with a trailing `**`: `prefix/**`
matches every reference below `prefix/` at any depth (not `prefix` itself),
and a bare `**` matches every reference. Invalid globs and empty `refs`
@@ -362,20 +370,18 @@ Git hooks use private.
Ordered roughly by the order we intend to work on them. None of this is a
commitment.
-1. Live policy reload, with a file watch or a signal, and a dry-run mode that
- reports what a policy change would allow.
-2. Eager derived data for `lastmod` and blame when a change lands, with metrics
+1. Eager derived data for `lastmod` and blame when a change lands, with metrics
for hit rates. Phase 3 computes `graph` and `changed-paths` eagerly.
-3. Changeset log retention, and an offset index of the file log that survives
+2. Changeset log retention, and an offset index of the file log that survives
a restart.
-4. Client-side help for every conflict: `graft land --resolve --conflicts-dir
+3. Client-side help for every conflict: `graft land --resolve --conflicts-dir
DIR` writes the conflicts of a land (the merged files with conflict markers,
the three sides and the resolver's proposals) into DIR, and
`graft land --resolved DIR` lands the result. A land without `--resolve`
that fails with `merge_conflict` writes nothing yet, and the files are not
written into the workspace itself (see [RESOLVE](RESOLVE.md)).
-5. Multi-node cache tiers with explicit invalidation for mutable keys.
-6. Signed changesets and a verifiable export of the log.
+4. Multi-node cache tiers with explicit invalidation for mutable keys.
+5. Signed changesets and a verifiable export of the log.
## Phase 4b limitations