Skip to content

Commit 6c74f0f

Browse files
author
andriypolandki
committed
docs(config): add self-host review config templates in config/examples
1 parent a151d8a commit 6c74f0f

8 files changed

Lines changed: 1159 additions & 15 deletions

File tree

‎.gittensory.minimal.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@
44
#
55
# Copy this file to your repo root as `.gittensory.yml` and customize from here.
66
# (This filename is not read directly — only `.gittensory.yml` / `.github/gittensory.yml` are.)
7-
# For every supported field, defaults, and examples see `.gittensory.yml.example`.
7+
# Also shipped at config/examples/gittensory.minimal.yml for self-host operators.
8+
# For every supported field, defaults, and examples see `.gittensory.yml.example` or
9+
# config/examples/gittensory.full.yml.
810
#
911
# Safe by default:
1012
# - Gate off (enable explicitly when you are ready)

‎.gittensory.yml.example‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,11 @@
66
# review engine scores, gates, and comments on its pull requests — as
77
# config-as-code, versioned alongside the project it governs.
88
#
9-
# STARTER TEMPLATES:
10-
# .gittensory.minimal.yml — smallest safe copy-paste starter (gate off, observe-only autonomy)
11-
# .gittensory.yml.example — exhaustive, field-by-field reference (this file's expanded form)
9+
# STARTER TEMPLATES (also shipped under config/examples/ for self-host operators):
10+
# config/examples/gittensory.minimal.yml — smallest safe starter (gate off, observe-only autonomy)
11+
# config/examples/gittensory.full.yml — exhaustive reference (body synced with this file)
12+
# .gittensory.minimal.yml — same minimal starter at repo root
13+
# .gittensory.yml.example — this file
1214
#
1315
# WHERE IT LIVES (first match wins):
1416
# .gittensory.yml → .github/gittensory.yml → .gittensory.json → .github/gittensory.json

‎apps/gittensory-ui/src/routes/docs.self-hosting-configuration.tsx‎

Lines changed: 75 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -91,13 +91,81 @@ function SelfHostingConfiguration() {
9191
<p>
9292
This page covers the environment layer and the shape of the config file. For the full field
9393
list — every <code>gate:</code> and <code>settings:</code> key, its default, and what it
94-
does — see <Link to="/docs/tuning">Tuning your reviews</Link>, and for a complete,
95-
commented, copy-pasteable manifest see{" "}
96-
<a href="https://github.com/JSONbored/gittensory/blob/main/.gittensory.yml.example">
97-
<code>.gittensory.yml.example</code>
98-
</a>{" "}
99-
in the repo — the authoritative reference for every field, including several documented only
100-
in its comments (see below).
94+
does — see <Link to="/docs/tuning">Tuning your reviews</Link>, and for copy-paste templates
95+
see the table below (also shipped inside the self-host image at{" "}
96+
<code>config/examples/</code>).
97+
</p>
98+
99+
<h2>Config templates</h2>
100+
<p>
101+
Start from a template instead of reverse-engineering env flags, private-config precedence,
102+
and the parser. Every template uses the same schema for a public repo-root{" "}
103+
<code>.gittensory.yml</code> or a container-private <code>GITTENSORY_REPO_CONFIG_DIR</code>{" "}
104+
mount — only what you put in each file differs.
105+
</p>
106+
<FeatureRow
107+
items={[
108+
{
109+
title: "gittensory.minimal.yml",
110+
description:
111+
"Smallest safe starter — gate off, observe-only autonomy, no accidental merge/close/label writes. Copy to the repo root or a private mount.",
112+
},
113+
{
114+
title: "gittensory.full.yml",
115+
description:
116+
"Exhaustive commented reference — every gate:, settings:, review:, and features: field with defaults and allowed values. Body kept in sync with .gittensory.yml.example.",
117+
},
118+
{
119+
title: "global.gittensory.yml + repo-override.gittensory.yml",
120+
description:
121+
"Private self-host only — illustrative fleet global default and per-repo overlay (deep-merge). Never commit real policy into these example paths.",
122+
},
123+
]}
124+
/>
125+
<CodeBlock
126+
lang="bash"
127+
code={`# Public repo (contributor-visible)
128+
cp config/examples/gittensory.minimal.yml .gittensory.yml
129+
130+
# Self-host private mount (operator-only policy)
131+
mkdir -p gittensory-config
132+
cp config/examples/global.gittensory.yml gittensory-config/.gittensory.yml`}
133+
/>
134+
<Callout variant="note">
135+
Keep anti-abuse thresholds, maintainer allowlists, and autonomy dials in the{" "}
136+
<strong>private</strong> mount — not in a public <code>.gittensory.yml</code> contributors
137+
can read. <code>config/examples/TEMPLATES.md</code> documents the public-vs-private split
138+
and how to apply the templates to <code>gittensory</code>, <code>awesome-claude</code>, and{" "}
139+
<code>metagraphed</code> without committing private policy. Lint before deploy:{" "}
140+
<code>npx tsx scripts/gittensory-config-lint.ts path/to/.gittensory.yml</code>.
141+
</Callout>
142+
<p>Authoritative copies in git:</p>
143+
<ul>
144+
<li>
145+
<a href="https://github.com/JSONbored/gittensory/blob/main/config/examples/gittensory.minimal.yml">
146+
<code>config/examples/gittensory.minimal.yml</code>
147+
</a>
148+
</li>
149+
<li>
150+
<a href="https://github.com/JSONbored/gittensory/blob/main/config/examples/gittensory.full.yml">
151+
<code>config/examples/gittensory.full.yml</code>
152+
</a>{" "}
153+
(same body as{" "}
154+
<a href="https://github.com/JSONbored/gittensory/blob/main/.gittensory.yml.example">
155+
<code>.gittensory.yml.example</code>
156+
</a>
157+
)
158+
</li>
159+
<li>
160+
<a href="https://github.com/JSONbored/gittensory/blob/main/config/examples/TEMPLATES.md">
161+
<code>config/examples/TEMPLATES.md</code>
162+
</a>{" "}
163+
— catalog + fleet usage notes
164+
</li>
165+
</ul>
166+
<p>
167+
Several gate-only fields are documented only in the full template comments — see below for
168+
the config-as-code blocks with no dashboard equivalent.
101169
</p>
102170

103171
<h2>Required baseline env</h2>

‎config/examples/README.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ This directory ships **generic, safe** examples for the self-host **private** co
55
contains no real policy, thresholds, logins, or repo names — copy what you need into your own
66
mounted config directory and edit it there (never in this repo).
77

8+
See **[TEMPLATES.md](./TEMPLATES.md)** for the full template catalog (minimal + exhaustive
9+
`gittensory.yml` starters, public-vs-private usage, and fleet notes for `gittensory`,
10+
`awesome-claude`, and `metagraphed` without committing private policy).
11+
812
The private config directory is read by `src/selfhost/private-config.ts` and is kept **out of the
913
public GitHub repo** on purpose: contributors can read a public `.gittensory.yml`, so anti-abuse
1014
thresholds, maintainer/admin allowlists, autonomy dials, and model/effort settings belong here
@@ -22,10 +26,11 @@ ${GITTENSORY_REPO_CONFIG_DIR}/.gittensory.yml # 4. global default,
2226
```
2327

2428
`.yaml` and `.json` are accepted everywhere `.yml` is. Every one of these files uses the **exact
25-
same schema** as the public `.gittensory.yml` — see [`.gittensory.yml.example`](../../.gittensory.yml.example)
26-
at the repo root for the exhaustive, field-by-field reference (not duplicated here, so the two
27-
never drift out of sync). For the smallest safe starter, copy [`.gittensory.minimal.yml`](../../.gittensory.minimal.yml)
28-
to your repo root as `.gittensory.yml` and customize from there.
29+
same schema** as the public `.gittensory.yml` — see [`gittensory.full.yml`](./gittensory.full.yml)
30+
(or [`.gittensory.yml.example`](../../.gittensory.yml.example) at the repo root) for the exhaustive,
31+
field-by-field reference. For the smallest safe starter, copy [`gittensory.minimal.yml`](./gittensory.minimal.yml)
32+
(or [`.gittensory.minimal.yml`](../../.gittensory.minimal.yml)) to your repo root as `.gittensory.yml`
33+
or into your private mount and customize from there.
2934

3035
## Precedence chain
3136

‎config/examples/TEMPLATES.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Gittensory review config templates
2+
3+
Copy-paste templates for `.gittensory.yml` — the per-repo review manifest. Every file in this
4+
directory uses the **same schema** whether it lives in a public repo root or a self-host private
5+
mount (`GITTENSORY_REPO_CONFIG_DIR`).
6+
7+
## Template catalog
8+
9+
| File | Purpose |
10+
|------|---------|
11+
| [`gittensory.minimal.yml`](./gittensory.minimal.yml) | Smallest safe starter — gate off, observe-only autonomy, no accidental writes |
12+
| [`gittensory.full.yml`](./gittensory.full.yml) | Exhaustive commented reference — every `gate:`, `settings:`, `review:`, and `features:` field |
13+
| [`global.gittensory.yml`](./global.gittensory.yml) | **Private only** — illustrative fleet-wide default for a self-host mount |
14+
| [`repo-override.gittensory.yml`](./repo-override.gittensory.yml) | **Private only** — per-repo overlay deep-merged over `global.gittensory.yml` |
15+
16+
Canonical copies of the minimal and full templates also live at the repo root as
17+
[`.gittensory.minimal.yml`](../../.gittensory.minimal.yml) and
18+
[`.gittensory.yml.example`](../../.gittensory.yml.example). CI keeps the `config/examples/` copies
19+
in sync with those files.
20+
21+
## Public repo root vs private self-host mount
22+
23+
| Layer | Path | Who can read it | Typical contents |
24+
|-------|------|-----------------|------------------|
25+
| **Public** | `.gittensory.yml` or `.github/gittensory.yml` in git | Contributors | `wantedPaths`, test expectations, public review presentation |
26+
| **Private global** | `${GITTENSORY_REPO_CONFIG_DIR}/.gittensory.yml` | Operator only | Shared autonomy baseline, contributor caps, maintainer allowlists |
27+
| **Private per-repo** | `${GITTENSORY_REPO_CONFIG_DIR}/owner__repo/.gittensory.yml` | Operator only | Repo-specific CI context names, AI mode, overrides |
28+
29+
When **either** a private global or private per-repo file exists, the loader **never fetches** the
30+
public repo file for that review — mount private policy deliberately. See [README.md](./README.md)
31+
for precedence and deep-merge rules.
32+
33+
**Never commit real private policy** (maintainer logins, thresholds, autonomy dials you do not want
34+
contributors to read) into a public repository. Copy `global.gittensory.yml` into your gitignored
35+
`gittensory-config/` mount and edit there.
36+
37+
## Quick start
38+
39+
### Public repo (contributor-visible config)
40+
41+
```bash
42+
cp config/examples/gittensory.minimal.yml .gittensory.yml
43+
# edit wantedPaths / gate when ready
44+
```
45+
46+
### Self-host private mount (operator-only policy)
47+
48+
```bash
49+
mkdir -p gittensory-config
50+
cp config/examples/global.gittensory.yml gittensory-config/.gittensory.yml
51+
# edit your-admin-login placeholders before going live
52+
# optional per-repo overlay:
53+
mkdir -p gittensory-config/myorg__myrepo
54+
cp config/examples/repo-override.gittensory.yml gittensory-config/myorg__myrepo/.gittensory.yml
55+
```
56+
57+
Point `GITTENSORY_REPO_CONFIG_DIR` at that directory (default `/config` in `docker-compose.yml` maps
58+
`./gittensory-config`).
59+
60+
## Fleet examples (without committing private policy)
61+
62+
These patterns apply to common JSONbored repos. **Do not copy real maintainer logins or thresholds
63+
into public git** — use the private mount for anything marked *private* below.
64+
65+
### `JSONbored/gittensory` (dogfooding)
66+
67+
- **Public** `.gittensory.yml` in the repo: work-area guardrails, test expectations, gate dimensions
68+
contributors should understand.
69+
- **Private** `gittensory-config/` (gitignored locally, operator mount in production): fleet
70+
autonomy, anti-abuse caps, maintainer exemption lists — the same split described in
71+
[`global.gittensory.yml`](./global.gittensory.yml).
72+
- Start from `gittensory.minimal.yml` in the public repo until gate semantics are tuned, then promote
73+
fields into the private global default as you enable autonomous review.
74+
75+
### `JSONbored/awesome-claude` (public template repo)
76+
77+
- Prefer **`gittensory.minimal.yml`** or a trimmed public manifest: `wantedPaths`, linked-issue
78+
policy, and advisory gate modes only.
79+
- Keep contributor caps, `autoCloseExemptLogins`, and `autonomy.close: auto` in **private config
80+
only** — this repo is meant to be copied; do not bake operator-specific enforcement into its
81+
public history.
82+
83+
### `JSONbored/metagraphed` (sibling product repo)
84+
85+
- Same split as `gittensory`: public manifest for transparent contributor guidance; private mount
86+
for thresholds and maintainer-only rules.
87+
- Use `repo-override.gittensory.yml` when one repo needs different `expectedCiContexts` or
88+
`gate.checkMode: disabled` while sharing a fleet-wide `global.gittensory.yml` baseline.
89+
90+
## Validation
91+
92+
Every template in this directory is parsed in CI (`test/unit/config-templates.test.ts` and
93+
`test/unit/selfhost-config-examples.test.ts`). The exhaustive template body is kept identical to
94+
`.gittensory.yml.example` from `# WHERE IT LIVES` onward. Lint a local file before deploy:
95+
96+
```bash
97+
npx tsx scripts/gittensory-config-lint.ts path/to/.gittensory.yml
98+
```

0 commit comments

Comments
 (0)