From 5effe5450ecedcfadb710e59917e0d2e4f96591f Mon Sep 17 00:00:00 2001 From: Lee Chapman Date: Sun, 2 Aug 2026 10:38:20 -0700 Subject: [PATCH 1/5] docs: add org repository settings guidelines Capture the recommended common pattern for first-party repo defaults, branch protection, Dependabot/security, forks, and github-workflows CI. Co-authored-by: Cursor --- README.md | 1 + docs/REPO_SETTINGS.md | 153 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 154 insertions(+) create mode 100644 docs/REPO_SETTINGS.md diff --git a/README.md b/README.md index 5e97e70..e23faa5 100644 --- a/README.md +++ b/README.md @@ -9,5 +9,6 @@ Organization profile and community files for [DataKnifeAI](https://github.com/Da | [`docs/ORG_BRANDING.md`](docs/ORG_BRANDING.md) | Canonical mission, profile copy, and avatar guidance | | [`docs/NAMING.md`](docs/NAMING.md) | Repository naming for the agent pipeline (descriptive vs evocative; upstream integrations) | | [`docs/PROJECT_SETUP.md`](docs/PROJECT_SETUP.md) | For new/existing projects: review [agent-skills](https://github.com/DataKnifeAI/agent-skills) and [agent-workspace](https://github.com/DataKnifeAI/agent-workspace) | +| [`docs/REPO_SETTINGS.md`](docs/REPO_SETTINGS.md) | Recommended repo settings, branch protection, and security defaults | The profile README displays the **1024×1024** logo only. Smaller PNGs are retained for GitHub/GitLab avatar upload—see the branding doc. diff --git a/docs/REPO_SETTINGS.md b/docs/REPO_SETTINGS.md new file mode 100644 index 0000000..4dcc31a --- /dev/null +++ b/docs/REPO_SETTINGS.md @@ -0,0 +1,153 @@ +# DataKnifeAI repository settings + +Recommended **common pattern** for first-party (non-fork) repositories in the [DataKnifeAI](https://github.com/DataKnifeAI) organization. + +Aligned with the org mission: keep work **maintainable**, **automated**, and **stable**, and prefer setups that stay operable without one-off heroics. See [`ORG_BRANDING.md`](ORG_BRANDING.md) for identity and principles. + +This document describes the **target** state. Existing repos may drift; prefer fixing settings intentionally (new repos first, then high-traffic product repos) rather than bulk-changing everything at once. + +## Scope + +| Kind | Apply this pattern? | +|------|---------------------| +| First-party product / infra / tooling repos | Yes | +| Org meta repo (`.github`) | Yes (docs live in-repo; keep the surface small) | +| Private repos on free GitHub plans | Apply what the plan allows; classic branch protection / rulesets may be unavailable | +| Forks of upstream projects | Partial — see [Forks](#forks) | + +Org-level rulesets (if enabled later) should encode the same defaults so new repos inherit them. As of the last review, org rulesets were not readable without `admin:org` scope; do not assume they are configured. + +## New repository defaults + +Use these when creating a repo (UI or `gh repo create` / `gh repo edit`). + +| Setting | Recommended | Notes | +|---------|-------------|--------| +| Default branch | `main` | Already universal across first-party repos | +| Issues | **On** | Track work in the owning repo unless there is a deliberate hub | +| Projects | On (optional) | Harmless default; use org/user projects if preferred | +| Wiki | **Off** | Prefer Markdown in the repo (`README` / `docs/`) so docs version with code | +| Downloads | Off | Legacy “Downloads” tab; unused | +| Squash merge | **On** (preferred path) | Keeps `main` readable; matches linear-history protection | +| Merge commit | On or off | Optional; squash is the default contributor path | +| Rebase merge | On or off | Optional | +| Delete branch on merge | **On** | Avoids stale head branches | +| Auto-merge | Optional | Useful once required checks exist; not required | +| Allow force push / branch deletion on default | **Off** | Enforced via protection / rulesets | + +Example: + +```bash +gh repo edit DataKnifeAI/ \ + --default-branch main \ + --enable-issues \ + --enable-projects \ + --enable-squash-merge \ + --delete-branch-on-merge \ + --allow-update-branch +# Disable wiki when the API/UI allows (GitHub has no universal --disable-wiki flag on all gh versions). +``` + +## Default branch protection / rulesets + +Protect `main` (the default branch) on every **public** first-party repo that accepts contributions or automation. + +### Classic branch protection (common today) + +Target shape: + +| Rule | Recommended | +|------|-------------| +| Require a pull request before merging | **Yes** | +| Required approving reviews | **1** when more than one active maintainer; **0** is acceptable for solo-maintainer repos if a PR is still required | +| Dismiss stale reviews | **Yes** | +| Require review from Code Owners | Only if a `CODEOWNERS` file exists and is kept accurate | +| Require conversation resolution | **Yes** | +| Require linear history | **Yes** (pairs with squash-or-rebase) | +| Require status checks to pass | **Yes when CI exists** — name the checks that gate quality (see [github-workflows](#relation-to-github-workflows)) | +| Require branches to be up to date | **Yes** (`strict`) when checks are configured | +| Do not allow force pushes | **Yes** (deny) | +| Do not allow deletions | **Yes** (deny) | +| Include administrators | **Yes** (`enforce_admins`) so the same path applies to everyone | + +Empty required-check lists with “strict” up-to-date only are a weak gate. Prefer either real check names or omitting required checks until CI is wired. + +### Rulesets (optional overlay) + +Repository rulesets are fine for additive policy (for example Copilot code review on the default branch, block force-push / deletion). Prefer **one clear story**: either classic protection plus a small ruleset overlay, or a single ruleset that encodes the same intent. Avoid duplicating conflicting review requirements. + +## Dependabot and security basics + +| Control | Recommended | +|---------|-------------| +| Dependabot version updates | Enable `.github/dependabot.yml` for ecosystems the repo actually uses (`gomod`, `pip`, `npm`, `docker`, `github-actions`, `terraform`, …) on a weekly cadence | +| Vulnerability alerts / Dependabot security updates | **On** for first-party repos | +| Secret scanning / push protection | On where GitHub enables them for the visibility/plan | +| `CODEOWNERS` | Optional; add when ownership is stable enough that review routing helps | + +Do not add Dependabot ecosystems “for completeness” in repos with no lockfile or package manifest. + +## Forks + +Forks exist to track or contribute upstream. They intentionally differ: + +- **Issues off** (typical) — avoid splitting reports away from upstream +- Default branch may remain upstream’s (`main` or `master`) +- Do **not** force org branding, org issue templates, or full product protection onto forks unless the fork is permanently diverged into a first-party product +- Merge / delete-branch settings may stay loose; treat the fork as a mirror or contribution staging area + +When a fork becomes a long-lived DataKnifeAI product, graduate it: enable issues, adopt `main` if needed, and apply this document’s first-party pattern. + +## Relation to `github-workflows` + +Reusable CI lives in [`DataKnifeAI/github-workflows`](https://github.com/DataKnifeAI/github-workflows) (`workflow_call` workflows and composite actions). + +- Caller repos should **pin a tag** (for example `@v1`), not floating `@main`, once a release line is stable. +- After a consumer wires reusable workflows, add those job/check names to **required status checks** on `main` so automation actually gates merges. +- Mirror / security reusable workflows (GitLab push, Trivy, game-server verify) are opt-in per repo; protection should only require checks that the repo runs. + +Settings keep the branch **stable**; reusable workflows keep verification **automated** and consistent across consumers. + +## Alignment snapshot (review notes) + +Observed across org-owned non-fork repos (representative audit; not a live dashboard): + +**Mostly aligned** + +- Default branch `main` +- Issues and projects enabled +- All three merge strategies enabled; downloads off +- Many public repos share classic protection: PR required, dismiss stale reviews, linear history, conversation resolution, enforce admins, no force push / no branch deletion +- No `CODEOWNERS` files in sampled repos (consistent absence) + +**Common drift (fix toward this doc)** + +| Area | Drift | +|------|--------| +| Wiki | Off on some older product repos; still on for many others and `.github` | +| Delete branch on merge | On for an older core set; **off** on many newer repos | +| Auto-merge | Enabled only on an outlier (`high-command-mcp`) | +| Branch protection | **Missing** on several newer public repos (operators / related) and on `.github` | +| Required reviews | Often **0** approvals (PR still required); scripted intent elsewhere was 1 | +| Required status checks | Strict up-to-date with **empty** check lists on protected repos | +| Rulesets | Only a few repos (High Command) have a Copilot-review ruleset | +| Dependabot config | Present on a small minority | +| Vulnerability alerts | On for many newer repos; still off on a large older set | +| Private repos | Branch protection / rulesets blocked without a paid plan feature | + +Forks (separate): issues disabled; some default to `master`; not held to the first-party checklist. + +## Applying changes safely + +1. Set **new** repos to this pattern at creation time. +2. For existing repos, change settings in small batches; verify CI check names before requiring them. +3. Prefer documenting intent here over silent bulk edits across the org. +4. Private repos: enable whatever the plan allows; consider public + careful secrets hygiene, or a plan that includes protection, for repos that need hard gates. + +```bash +# Example: align merge hygiene on one repo +gh repo edit DataKnifeAI/ --enable-squash-merge --delete-branch-on-merge + +# Example: enable vulnerability alerts +gh api -X PUT "repos/DataKnifeAI//vulnerability-alerts" -H "Accept: application/vnd.github+json" +``` From f0a312d1e2236f9d6aa07806b5a8321269b999d4 Mon Sep 17 00:00:00 2001 From: Lee Chapman Date: Sun, 2 Aug 2026 10:38:34 -0700 Subject: [PATCH 2/5] docs: note .github settings after alignment tweak Co-authored-by: Cursor --- docs/REPO_SETTINGS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/REPO_SETTINGS.md b/docs/REPO_SETTINGS.md index 4dcc31a..f60dd4a 100644 --- a/docs/REPO_SETTINGS.md +++ b/docs/REPO_SETTINGS.md @@ -124,8 +124,8 @@ Observed across org-owned non-fork repos (representative audit; not a live dashb | Area | Drift | |------|--------| -| Wiki | Off on some older product repos; still on for many others and `.github` | -| Delete branch on merge | On for an older core set; **off** on many newer repos | +| Wiki | Off on some older product repos; still on for many others (prefer off) | +| Delete branch on merge | On for an older core set (and `.github`); **off** on many newer repos | | Auto-merge | Enabled only on an outlier (`high-command-mcp`) | | Branch protection | **Missing** on several newer public repos (operators / related) and on `.github` | | Required reviews | Often **0** approvals (PR still required); scripted intent elsewhere was 1 | From 9025912936b6cbba83e791d344b836e5595d0264 Mon Sep 17 00:00:00 2001 From: Lee Chapman Date: Sun, 2 Aug 2026 10:41:16 -0700 Subject: [PATCH 3/5] docs: link repo settings to project setup baseline Cross-link the open PROJECT_SETUP PR so settings guidance points at agent-skills / agent-workspace review for new and existing repos. Co-authored-by: Cursor --- README.md | 1 + docs/REPO_SETTINGS.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/README.md b/README.md index e23faa5..25d1392 100644 --- a/README.md +++ b/README.md @@ -10,5 +10,6 @@ Organization profile and community files for [DataKnifeAI](https://github.com/Da | [`docs/NAMING.md`](docs/NAMING.md) | Repository naming for the agent pipeline (descriptive vs evocative; upstream integrations) | | [`docs/PROJECT_SETUP.md`](docs/PROJECT_SETUP.md) | For new/existing projects: review [agent-skills](https://github.com/DataKnifeAI/agent-skills) and [agent-workspace](https://github.com/DataKnifeAI/agent-workspace) | | [`docs/REPO_SETTINGS.md`](docs/REPO_SETTINGS.md) | Recommended repo settings, branch protection, and security defaults | +| [`docs/PROJECT_SETUP.md`](https://github.com/DataKnifeAI/.github/pull/5) | New/existing projects: review agent-skills & agent-workspace (landing via PR #5) | The profile README displays the **1024×1024** logo only. Smaller PNGs are retained for GitHub/GitLab avatar upload—see the branding doc. diff --git a/docs/REPO_SETTINGS.md b/docs/REPO_SETTINGS.md index f60dd4a..1a9027e 100644 --- a/docs/REPO_SETTINGS.md +++ b/docs/REPO_SETTINGS.md @@ -4,6 +4,8 @@ Recommended **common pattern** for first-party (non-fork) repositories in the [D Aligned with the org mission: keep work **maintainable**, **automated**, and **stable**, and prefer setups that stay operable without one-off heroics. See [`ORG_BRANDING.md`](ORG_BRANDING.md) for identity and principles. +Related: agent skills / Cloud Agent workspace baseline — [`PROJECT_SETUP.md`](https://github.com/DataKnifeAI/.github/pull/5) (PR; path `docs/PROJECT_SETUP.md` after merge). + This document describes the **target** state. Existing repos may drift; prefer fixing settings intentionally (new repos first, then high-traffic product repos) rather than bulk-changing everything at once. ## Scope From 853d90cc9d5417fe30f92df3bf6ffa3d6a250658 Mon Sep 17 00:00:00 2001 From: Lee Chapman Date: Sun, 2 Aug 2026 10:49:03 -0700 Subject: [PATCH 4/5] docs: assume solo-dev branch protection Org is one maintainer; prefer 0 required reviews and soft admin enforcement so automation stays usable without multi-reviewer gates. Co-authored-by: Cursor --- docs/REPO_SETTINGS.md | 66 +++++++++++++++++++++++++++---------------- 1 file changed, 42 insertions(+), 24 deletions(-) diff --git a/docs/REPO_SETTINGS.md b/docs/REPO_SETTINGS.md index 1a9027e..de7a2c1 100644 --- a/docs/REPO_SETTINGS.md +++ b/docs/REPO_SETTINGS.md @@ -4,6 +4,8 @@ Recommended **common pattern** for first-party (non-fork) repositories in the [D Aligned with the org mission: keep work **maintainable**, **automated**, and **stable**, and prefer setups that stay operable without one-off heroics. See [`ORG_BRANDING.md`](ORG_BRANDING.md) for identity and principles. +Branch protection defaults assume a **solo maintainer** — safe and automatable, not multi-reviewer gates. Adjust when the org grows ([details](#default-branch-protection--rulesets)). + Related: agent skills / Cloud Agent workspace baseline — [`PROJECT_SETUP.md`](https://github.com/DataKnifeAI/.github/pull/5) (PR; path `docs/PROJECT_SETUP.md` after merge). This document describes the **target** state. Existing repos may drift; prefer fixing settings intentionally (new repos first, then high-traffic product repos) rather than bulk-changing everything at once. @@ -52,31 +54,47 @@ gh repo edit DataKnifeAI/ \ ## Default branch protection / rulesets +**Assumption:** DataKnifeAI is operated as a **solo developer** org today (and has been for a long time). Protection should keep `main` safe and automation-friendly without locking the sole maintainer behind review gates that nobody can fulfill. When the org grows, tighten—see [When the org grows](#when-the-org-grows). + Protect `main` (the default branch) on every **public** first-party repo that accepts contributions or automation. -### Classic branch protection (common today) +### Classic branch protection (solo-dev defaults) Target shape: -| Rule | Recommended | -|------|-------------| -| Require a pull request before merging | **Yes** | -| Required approving reviews | **1** when more than one active maintainer; **0** is acceptable for solo-maintainer repos if a PR is still required | -| Dismiss stale reviews | **Yes** | -| Require review from Code Owners | Only if a `CODEOWNERS` file exists and is kept accurate | -| Require conversation resolution | **Yes** | -| Require linear history | **Yes** (pairs with squash-or-rebase) | -| Require status checks to pass | **Yes when CI exists** — name the checks that gate quality (see [github-workflows](#relation-to-github-workflows)) | -| Require branches to be up to date | **Yes** (`strict`) when checks are configured | -| Do not allow force pushes | **Yes** (deny) | -| Do not allow deletions | **Yes** (deny) | -| Include administrators | **Yes** (`enforce_admins`) so the same path applies to everyone | - -Empty required-check lists with “strict” up-to-date only are a weak gate. Prefer either real check names or omitting required checks until CI is wired. +| Rule | Recommended (solo) | Notes | +|------|--------------------|--------| +| Require a pull request before merging | **Yes** | Keeps history reviewable and CI attachable even without a second person | +| Required approving reviews | **0** | Reviews are optional for solo; do not require 1+ until there is someone to approve | +| Dismiss stale reviews | **Yes** | Harmless if approvals are unused; useful if informal reviews happen | +| Require review from Code Owners | **Off** | Add only with a real `CODEOWNERS` file and more than one reviewer | +| Require conversation resolution | **Optional / Yes** | Useful so open threads are not forgotten; does not block solo merges by itself | +| Require linear history | **Yes** (preferred) | Pairs with squash (or rebase) as the contributor path | +| Require status checks to pass | **Only when CI exists and is reliable** | Name real check contexts; never invent empty required lists | +| Require branches to be up to date | **Yes** (`strict`) **only with real checks** | Skip until required checks are configured | +| Do not allow force pushes | **Yes** (deny) | Protect default branch history | +| Do not allow deletions | **Yes** (deny) | Protect default branch | +| Include administrators (`enforce_admins`) | **Off** (soft) for solo | Avoid locking the sole maintainer out when checks flake; tradeoff is admins can bypass. Turn on when a second person (or stable CI) makes self-bypass less necessary | + +Empty required-check lists with “strict” up-to-date only are a weak gate and noise. Prefer either real check names or omitting required checks until CI is wired. ### Rulesets (optional overlay) -Repository rulesets are fine for additive policy (for example Copilot code review on the default branch, block force-push / deletion). Prefer **one clear story**: either classic protection plus a small ruleset overlay, or a single ruleset that encodes the same intent. Avoid duplicating conflicting review requirements. +Repository rulesets are fine for additive policy (for example Copilot code review on the default branch, block force-push / deletion). Prefer **one clear story**: either classic protection plus a small ruleset overlay, or a single ruleset that encodes the same intent. Avoid duplicating conflicting review requirements—especially do not layer a “1 approval” ruleset on top of solo classic protection. + +### When the org grows + +Bump protection when there is more than one active maintainer or external contributors who need a real review gate: + +| Change | Target | +|--------|--------| +| Required approving reviews | **1** (or more for sensitive repos) | +| `CODEOWNERS` | Add and keep accurate; optionally require code-owner review | +| Include administrators | **On** so admins follow the same path | +| Org rulesets | Encode the shared defaults so new repos inherit them | +| Required status checks | Keep requiring only checks that actually run and stay green | + +Do not bulk-tighten every repo overnight; raise the floor on high-traffic product repos first, then new repos by default. ## Dependabot and security basics @@ -85,7 +103,7 @@ Repository rulesets are fine for additive policy (for example Copilot code revie | Dependabot version updates | Enable `.github/dependabot.yml` for ecosystems the repo actually uses (`gomod`, `pip`, `npm`, `docker`, `github-actions`, `terraform`, …) on a weekly cadence | | Vulnerability alerts / Dependabot security updates | **On** for first-party repos | | Secret scanning / push protection | On where GitHub enables them for the visibility/plan | -| `CODEOWNERS` | Optional; add when ownership is stable enough that review routing helps | +| `CODEOWNERS` | Optional for solo; add when multiple maintainers make review routing useful | Do not add Dependabot ecosystems “for completeness” in repos with no lockfile or package manifest. @@ -114,13 +132,13 @@ Settings keep the branch **stable**; reusable workflows keep verification **auto Observed across org-owned non-fork repos (representative audit; not a live dashboard): -**Mostly aligned** +**Mostly aligned (with solo-dev assumption)** - Default branch `main` - Issues and projects enabled - All three merge strategies enabled; downloads off -- Many public repos share classic protection: PR required, dismiss stale reviews, linear history, conversation resolution, enforce admins, no force push / no branch deletion -- No `CODEOWNERS` files in sampled repos (consistent absence) +- Where classic protection exists: PR required, often **0** required approvals, dismiss stale reviews, linear history, conversation resolution, no force push / no branch deletion +- No `CODEOWNERS` files in sampled repos (appropriate for solo) **Common drift (fix toward this doc)** @@ -129,9 +147,9 @@ Observed across org-owned non-fork repos (representative audit; not a live dashb | Wiki | Off on some older product repos; still on for many others (prefer off) | | Delete branch on merge | On for an older core set (and `.github`); **off** on many newer repos | | Auto-merge | Enabled only on an outlier (`high-command-mcp`) | -| Branch protection | **Missing** on several newer public repos (operators / related) and on `.github` | -| Required reviews | Often **0** approvals (PR still required); scripted intent elsewhere was 1 | -| Required status checks | Strict up-to-date with **empty** check lists on protected repos | +| Branch protection | **Missing** on several newer public repos (operators / related); apply solo-dev pattern when adding (`.github` meta repo aligned) | +| Enforce admins | Often **on** on older protected repos; solo default prefers **off** (document tradeoff if leaving on) | +| Required status checks | Strict up-to-date with **empty** check lists on some protected repos — clear or wire real CI | | Rulesets | Only a few repos (High Command) have a Copilot-review ruleset | | Dependabot config | Present on a small minority | | Vulnerability alerts | On for many newer repos; still off on a large older set | From f6d7596465b9a81ad9ecd695130fb721d65b3974 Mon Sep 17 00:00:00 2001 From: Lee Chapman Date: Sun, 2 Aug 2026 10:56:24 -0700 Subject: [PATCH 5/5] docs: point related links at merged setup docs Remove stale PR #5 README row and link PROJECT_SETUP/NAMING in-repo after main catch-up. Co-authored-by: Cursor --- README.md | 1 - docs/REPO_SETTINGS.md | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 25d1392..e23faa5 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,5 @@ Organization profile and community files for [DataKnifeAI](https://github.com/Da | [`docs/NAMING.md`](docs/NAMING.md) | Repository naming for the agent pipeline (descriptive vs evocative; upstream integrations) | | [`docs/PROJECT_SETUP.md`](docs/PROJECT_SETUP.md) | For new/existing projects: review [agent-skills](https://github.com/DataKnifeAI/agent-skills) and [agent-workspace](https://github.com/DataKnifeAI/agent-workspace) | | [`docs/REPO_SETTINGS.md`](docs/REPO_SETTINGS.md) | Recommended repo settings, branch protection, and security defaults | -| [`docs/PROJECT_SETUP.md`](https://github.com/DataKnifeAI/.github/pull/5) | New/existing projects: review agent-skills & agent-workspace (landing via PR #5) | The profile README displays the **1024×1024** logo only. Smaller PNGs are retained for GitHub/GitLab avatar upload—see the branding doc. diff --git a/docs/REPO_SETTINGS.md b/docs/REPO_SETTINGS.md index de7a2c1..f7e3625 100644 --- a/docs/REPO_SETTINGS.md +++ b/docs/REPO_SETTINGS.md @@ -6,7 +6,7 @@ Aligned with the org mission: keep work **maintainable**, **automated**, and **s Branch protection defaults assume a **solo maintainer** — safe and automatable, not multi-reviewer gates. Adjust when the org grows ([details](#default-branch-protection--rulesets)). -Related: agent skills / Cloud Agent workspace baseline — [`PROJECT_SETUP.md`](https://github.com/DataKnifeAI/.github/pull/5) (PR; path `docs/PROJECT_SETUP.md` after merge). +Related: [`PROJECT_SETUP.md`](PROJECT_SETUP.md) (agent skills / Cloud Agent workspace baseline), [`NAMING.md`](NAMING.md), [`ORG_BRANDING.md`](ORG_BRANDING.md). This document describes the **target** state. Existing repos may drift; prefer fixing settings intentionally (new repos first, then high-traffic product repos) rather than bulk-changing everything at once.