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.mdindex 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 = falseallow = 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.mdindex 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 acommitment.-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 metricsfor 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 survivesa restart.-4. Client-side help for every conflict: `graft land --resolve --conflicts-dir+3. Client-side help for every conflict: `graft land --resolve --conflicts-dirDIR` 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 notwritten 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