diff --git a/.claude/pr-reviews/nsheaps/github-actions/1/1771874092/documentation/REPORT.md b/.claude/pr-reviews/nsheaps/github-actions/1/1771874092/documentation/REPORT.md index 47964ad..65c5390 100644 --- a/.claude/pr-reviews/nsheaps/github-actions/1/1771874092/documentation/REPORT.md +++ b/.claude/pr-reviews/nsheaps/github-actions/1/1771874092/documentation/REPORT.md @@ -100,15 +100,15 @@ This PR delivers strong, well-structured documentation that significantly exceed ### Summary of Deductions -| Category | Deduction | Reason | +| Category | Deduction | Reason | | ---------------------------------- | --------- | --------------------------------------------------------------------- | --- | -------------------------------- | -| Missing troubleshooting/error docs | -5 | No guidance on common failure modes | -| Missing prerequisites | -2 | No runner/dependency requirements noted | -| Incomplete edge-case docs | -4 | maxdepth 2 limit, root-path sync naming, never-deletes implications | -| env-vars behavior mismatch | -2 | README implies compose-level injection, script does GITHUB_ENV export | -| auth-type values underdocumented | -2 | No explanation of what each auth type requires | -| Missing function docstrings | -2 | `discover_compose_files` and `export_env_vars` lack docstrings | -| Minor inline comment gaps | -1 | ` | | true`on curl,`sort -z` rationale | +| Missing troubleshooting/error docs | -5 | No guidance on common failure modes | +| Missing prerequisites | -2 | No runner/dependency requirements noted | +| Incomplete edge-case docs | -4 | maxdepth 2 limit, root-path sync naming, never-deletes implications | +| env-vars behavior mismatch | -2 | README implies compose-level injection, script does GITHUB_ENV export | +| auth-type values underdocumented | -2 | No explanation of what each auth type requires | +| Missing function docstrings | -2 | `discover_compose_files` and `export_env_vars` lack docstrings | +| Minor inline comment gaps | -1 | ` | | true`on curl,`sort -z` rationale | ## References diff --git a/.github/settings.yml b/.github/settings.yml new file mode 100644 index 0000000..e40887e --- /dev/null +++ b/.github/settings.yml @@ -0,0 +1,344 @@ +# ---------------------------------------------------------------- +# Auto-merged from nsheaps/.github on every sync. +# Source: https://github.com/nsheaps/.github/blob/37d696c8b0725bb8e70379cd6ee7db04264312eb/ansible/config/org-settings.yaml +# Edits to this file are KEPT on the next sync (deep merge). +# To remove an org default, delete the key here — it will not come back. +# ---------------------------------------------------------------- +# ---------------------------------------------------------------- +# Auto-generated from ansible/config/org-settings.yaml. DO NOT EDIT. +# Edit the template, not this file. +# Source: https://github.com/nsheaps/.github/blob/37d696c8b0725bb8e70379cd6ee7db04264312eb/ansible/config/org-settings.yaml +# ---------------------------------------------------------------- +# nsheaps org-wide repository defaults — TEMPLATE +# +# This file is the source of truth. It contains ${ENV_VAR} placeholders +# that get substituted by the sync-org-settings workflow (envsubst), +# which writes two rendered outputs back to this repo: +# - .github/org-settings.yaml — rendered (no @default hydration) +# - .github/default-settings.yaml — rendered + @default uncommented +# Edit THIS file for org-wide changes; the rendered outputs are auto-generated. +# +# Sync workflow: +# https://github.com/nsheaps/.github/blob/main/.github/workflows/sync-all.yaml +# +# After rendering, the unified ansible playbook (sync-all) walks every +# managed repo and either: +# - First-touch (no .github/settings.yml in target) → pushes default-settings.yaml +# - Existing target → merges org-settings.yaml in +# +# Merger script + tests: +# https://github.com/nsheaps/.github/blob/main/scripts/org_settings_merge.py +# +# Merge semantics — short version: +# - scalars : target wins (repo's existing value preserved) +# - mappings : recurse +# - rulesets[] : matched by `name`, deep-merged per item +# - rulesets[].rules[] : matched by `type`, deep-merged per item +# - bypass_actors[] : matched by (actor_id, actor_type) — SOURCE wins on scalars +# - enforcement omitted : normalized to `active` at write time +# +# Do not set per-repo identity (name/description/homepage/topics) here — +# those belong to each repo. +# +# `# @default` convention: lines tagged `# @default` are uncommented ONLY +# on a repo's FIRST sync (when it has no settings.yml yet). After that the +# commented source line is invisible to deep-merge, so a later change to +# the commented value can't accidentally overwrite the repo's value. +# ---------------------------------------------------------------- + +# These settings affect the repository itself. +# See https://docs.github.com/en/rest/repos/repos#update-a-repository +repository: + # NOTE: We deliberately do NOT set `name`, `description`, `homepage`, + # or `topics` from the org defaults — those belong to each repo. + # Edit them directly in your repo's .github/settings.yml. + # + # The booleans below are commented with `# @default` — they're set on + # this repo's FIRST sync only. After that, your value wins; org changes + # to the commented line are invisible to subsequent merges. + + # A short description of the repository that will show up on GitHub + # description: ... + + # A URL with more information about the repository + # homepage: https://example.github.io/ + + # A comma-separated list of topics to set on the repository + # topics: ... + + # Either `true` to make the repository private, or `false` to make it public. + # NOTE: intentionally not set org-wide — public/private is a per-repo decision. + # private: false + + # Either `true` to enable issues for this repository, `false` to disable them. + has_issues: true + + # Either `true` to enable projects for this repository, or `false` to disable them. + # NOTE: We use org-level projects, not repo-level. + has_projects: false + + # Either `true` to enable the wiki for this repository, `false` to disable it. + has_wiki: false + + # Either `true` to enable downloads for this repository, `false` to disable them. + has_downloads: false + + # Updates the default branch for this repository. + default_branch: main + + # Either `true` to allow squash-merging pull requests, or `false` to prevent + # squash-merging. + allow_squash_merge: true + + # Either `true` to allow merging pull requests with a merge commit, or `false` + # to prevent merging pull requests with merge commits. + allow_merge_commit: false + + # Either `true` to allow rebase-merging pull requests, or `false` to prevent + # rebase-merging. + allow_rebase_merge: true + + # Either `true` to enable automatic deletion of branches on merge, or `false` + # to disable. + delete_branch_on_merge: true + + # Either `true` to allow auto-merge on pull requests, or `false` to disallow. + allow_auto_merge: true + + # The default value for a squash merge commit title: + # - PR_TITLE — default to the pull request's title + # - COMMIT_OR_PR_TITLE — default to the commit's title (if only one commit) + # or the pull request's title (when more than one commit) + squash_merge_commit_title: PR_TITLE + + # The default value for a squash merge commit message: + # - PR_BODY — default to the pull request's body + # - COMMIT_MESSAGES — default to the branch's commit messages + # - BLANK — default to a blank commit message + squash_merge_commit_message: PR_BODY + +# Labels: managed centrally via .github/org-labels.yaml and synced to all +# managed repos by the sync-org-settings workflow's sync-labels job. +# Intentionally omitted from settings.yml so the two sources don't fight. + +# Rulesets — repository-level branch/tag rulesets. +# Docs: https://github.com/repository-settings/app/blob/master/docs/plugins/rulesets.md +# API : https://docs.github.com/en/rest/repos/rules +# +# enforcement values: +# - active : rules are enforced +# - disabled : ruleset exists but is not enforced (dormant) +# - evaluate : rules are checked and reported but not enforced (preview) +# NOTE: If `enforcement` is omitted on a ruleset, the sync writer fills it +# with `active`. Each ruleset below either: +# - sets `enforcement: active` (always-on org policy — overriding is discouraged), or +# - sets `enforcement: disabled` plus a commented `# enforcement: 'active'` +# sibling that a repo can uncomment (and delete the disabled line) to enable, or +# - omits `enforcement` and provides a commented `# enforcement: 'active'` +# hint that a repo can uncomment to lock the ruleset on explicitly. +# +# bypass_actors[].bypass_mode values: +# - always : prompts the user to bypass at push/merge time (GitHub UI default) +# - pull_request : bypass only allowed via a PR (push-time bypass blocked) +# NOTE: omitting bypass_mode lets the merger fill `always`. +# +# Every ruleset seeds repo admins (RepositoryRole id 5) as bypass actors so +# the org doesn't lock admins out. Repos can append more bypass_actors; for +# the admin entry itself, source-wins (you can't silently widen admin bypass +# to `always` if the org set `pull_request`). +rulesets: + # ---- 1. No delete / no force-push on the default branch ---- + - name: protect-default-branch + target: branch + enforcement: active # always enforced — overriding this is discouraged + conditions: + ref_name: + include: + - '~DEFAULT_BRANCH' # special selector: whatever the default branch is + exclude: [] + bypass_actors: + # Repo admins can bypass (always = prompts at push/merge time, not silent exempt). + # Repos can add more actors (other teams, integrations). + - actor_id: 5 + actor_type: RepositoryRole # 1=read 2=triage 3=write 4=maintain 5=admin + bypass_mode: always + # automation-nsheaps GitHub App — actor_id is substituted from 2549081 + + # by sync-org-settings when this template is rendered to org-settings.yaml. + - actor_id: 2549081 + + actor_type: Integration + bypass_mode: always + rules: + - type: deletion # block branch deletion + - type: non_fast_forward # block force-push + + # ---- 2. PR required (0 reviews) ---- + - name: require-pr + target: branch + enforcement: 'active' # uncomment to lock this ruleset on in this repo + conditions: + ref_name: + include: ['~DEFAULT_BRANCH'] + exclude: [] + bypass_actors: + # Repo admins can bypass (always = prompts at push/merge time, not silent exempt). + # Repos can add more actors (other teams, integrations). + - actor_id: 5 + actor_type: RepositoryRole # 1=read 2=triage 3=write 4=maintain 5=admin + bypass_mode: always + # automation-nsheaps GitHub App — actor_id is substituted from 2549081 + + # by sync-org-settings when this template is rendered to org-settings.yaml. + - actor_id: 2549081 + + actor_type: Integration + bypass_mode: exempt + # Mend Renovate cloud GitHub App (renovate[bot], app id 2740) — same + # trusted-automation bypass as automation-nsheaps above, so Renovate's + # *branch* automerge can push dependency updates straight to the default + # branch without a human review/PR. App id is a public constant, hardcoded + # like the github-actions[bot] integration_id below (not a secret, so no + # envsubst placeholder). Renovate is deliberately NOT a bypass actor on + # the required-status-checks ruleset, so green checks remain mandatory. + - actor_id: 2740 + actor_type: Integration + bypass_mode: exempt + rules: + - type: pull_request + # The 5 params below are REQUIRED by the API for type=pull_request. + # All defaults here are permissive (0 reviewers, no other gates) so + # the rule only gates "must use a PR" — repos override to add stricter + # checks. allowed_merge_methods is optional; left to repo preference. + parameters: + required_approving_review_count: 0 + dismiss_stale_reviews_on_push: false + require_code_owner_review: false + require_last_push_approval: false + required_review_thread_resolution: false + # allowed_merge_methods: [merge, squash, rebase] # optional + + # ---- 3. Review required — 1 reviewer (active by default) ---- + - name: require-1-review + target: branch + enforcement: disabled + # enforcement: 'active' + conditions: + ref_name: + include: ['~DEFAULT_BRANCH'] + exclude: [] + bypass_actors: + # Repo admins can bypass (always = prompts at push/merge time, not silent exempt). + # Repos can add more actors (other teams, integrations). + - actor_id: 5 + actor_type: RepositoryRole # 1=read 2=triage 3=write 4=maintain 5=admin + bypass_mode: always + # automation-nsheaps GitHub App — actor_id is substituted from 2549081 + + # by sync-org-settings when this template is rendered to org-settings.yaml. + - actor_id: 2549081 + + actor_type: Integration + bypass_mode: exempt + # Mend Renovate cloud GitHub App (renovate[bot], app id 2740) — see the + # require-pr ruleset above for rationale. Present here so Renovate stays + # exempt from the review requirement if a repo enables this ruleset. + - actor_id: 2740 + actor_type: Integration + bypass_mode: exempt + rules: + - type: pull_request + parameters: + required_approving_review_count: 1 + # The remaining 4 fields are required by the API for type=pull_request + # whenever ANY parameters are provided. Sensible safe defaults below; + # repos override per-repo. + dismiss_stale_reviews_on_push: true + require_code_owner_review: false + require_last_push_approval: false + required_review_thread_resolution: true + + # ---- 4. Checks required ---- + # NOTE: shipped ACTIVE. The required_status_checks list seeds an org-wide + # lint check (GitHub Actions App, context "lint") so every managed repo + # gates merges on a workflow named `lint`. Repos that don't yet have one + # should add `.github/workflows/lint.yaml` (or have it synced in via + # sync-files); per-repo additional checks go in this same list. + # GitHub App IDs in `integration_id`: + # 15368 = github-actions[bot] (workflows running on GitHub Actions) + # This is commented because not every repo has a lint workflow but they should + # When this is copied, so is the comment, and they can then uncomment as needed. + # In the long term, we should try to keep build/test/format/lint consistent between all repos + # - name: require-checks + # target: branch + # enforcement: active + # conditions: + # ref_name: + # include: ["~DEFAULT_BRANCH"] + # exclude: [] + # bypass_actors: + # # Repo admins can bypass (always = prompts at push/merge time, not silent exempt). + # # Repos can add more actors (other teams, integrations). + # - actor_id: 5 + # actor_type: RepositoryRole # 1=read 2=triage 3=write 4=maintain 5=admin + # bypass_mode: always + # # automation-nsheaps GitHub App — actor_id is substituted from 2549081 + + # # by sync-org-settings when this template is rendered to org-settings.yaml. + # - actor_id: 2549081 + + # actor_type: Integration + # bypass_mode: always + # rules: + # - type: required_status_checks + # parameters: + # strict_required_status_checks_policy: false + # required_status_checks: + # # Org-wide: a workflow named `lint` must pass. Repos that don't + # # have one yet should add .github/workflows/lint.yaml (or sync the + # # canonical one in). Repos add more entries below for their own CI. + # - context: lint + # integration_id: 15368 # github-actions[bot] + + # ---- 5. Review required — 1 reviewer from CODEOWNERS (disabled by default) ---- + # NOTE: shipped DISABLED. Repos with a meaningful CODEOWNERS file flip to + # `enforcement: active` and likely set `require-1-review.enforcement: disabled` + # so the two don't double up. + - name: require-codeowner-review + target: branch + enforcement: disabled + # enforcement: 'active' # uncomment (and remove the disabled line above) to enable + conditions: + ref_name: + include: ['~DEFAULT_BRANCH'] + exclude: [] + bypass_actors: + # Repo admins can bypass (always = prompts at push/merge time, not silent exempt). + # Repos can add more actors (other teams, integrations). + - actor_id: 5 + actor_type: RepositoryRole # 1=read 2=triage 3=write 4=maintain 5=admin + bypass_mode: always + # automation-nsheaps GitHub App — actor_id is substituted from 2549081 + + # by sync-org-settings when this template is rendered to org-settings.yaml. + - actor_id: 2549081 + + actor_type: Integration + bypass_mode: exempt + # Mend Renovate cloud GitHub App (renovate[bot], app id 2740) — see the + # require-pr ruleset above for rationale. Present here so Renovate stays + # exempt from the codeowner-review requirement if a repo enables this + # ruleset. + - actor_id: 2740 + actor_type: Integration + bypass_mode: exempt + rules: + - type: pull_request + parameters: + required_approving_review_count: 1 + require_code_owner_review: true + dismiss_stale_reviews_on_push: true + # Required by the API for type=pull_request whenever any + # parameters are provided. Sensible default; repos override. + require_last_push_approval: false + required_review_thread_resolution: true diff --git a/LICENSE.md b/LICENSE.md index e70157b..c3fc5da 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -11,7 +11,7 @@ Copyright (c) 2026 Nathan Heaps. All rights reserved. > (https://polyformproject.org/licenses/internal-use/1.0.0), which is > purpose-built for "use the software for internal business operations, do > not distribute it." The one substantive adaptation is that PolyForm grants -> rights to *"you and your company"* (whoever accepts the license), whereas +> rights to _"you and your company"_ (whoever accepts the license), whereas > this license grants them to a **single, specifically named licensee** > (Oura, defined below). That is a real difference: the licensor here is not > a generic member of the licensee's organization, so the "permitted diff --git a/pages/index.html b/pages/index.html index 820fe74..caec1b6 100644 --- a/pages/index.html +++ b/pages/index.html @@ -319,8 +319,7 @@

Detailed setup walkthrough

 cp pages/index.html docs/index.html
-# Settings → Pages → Source: GitHub Actions (or branch /docs)
+# Settings → Pages → Source: GitHub Actions (or branch /docs)

Then use https://<your-org>.github.io/<repo>/ as the redirect. Any other HTTPS static host (Vercel, Netlify, etc.) works equally well.