From fac10a78dc68b40c8d1aefbd16e399d4b1b93e78 Mon Sep 17 00:00:00 2001 From: James Maes Date: Sat, 10 Oct 2026 18:50:54 -0500 Subject: [PATCH 1/2] docs(template): clarify first restore and required checks Document local package trials and creation of NuGet locks after generation. Refer onboarding to the canonical check table and correct standalone installed-update and tooling context names. Refs: KofTwentyTwo/AppKit#10, KofTwentyTwo/AppKit#20 Co-Authored-By: Codex (GPT-6) Signed-off-by: James Maes --- CONTRIBUTING.md | 4 ++-- README.md | 2 ++ TEMPLATE.md | 25 +++++++++++++++++-------- 3 files changed, 21 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ebef7b..b09940e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -90,8 +90,8 @@ pre-commit install --hook-type pre-commit --hook-type commit-msg | `ci / build-test` | Locked restore, zero-warning build, unit tests, 100% coverage gate | | `ci / format` | `dotnet format --verify-no-changes --severity warn` | | `ci / ui-tests` | FlaUI end-to-end tests of the app | -| `ci / installed-updates` | Real stable/dev installers, upgrades, restart and published-output UI smoke | -| `scripts / powershell`, `scripts / javascript` | Tool lint, setup/coverage boundary tests, review tests and dependency signatures | +| `installed-updates` | Real stable/dev installers, upgrades, restart and published-output UI smoke | +| `powershell`, `javascript` | Tool lint, setup/coverage boundary tests, review tests and dependency signatures | | `codeql / analyze (javascript-typescript)` | Static analysis of repository review tooling | | `review / automated` (single maintainer) | Current-commit automated review acknowledged by the configured human maintainer | diff --git a/README.md b/README.md index 8357752..519cb0b 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,8 @@ Prerequisites: - Optionally Visual Studio 2026 (Windows App SDK workload) or Rider ```powershell +# Once after generation, create and commit the NuGet locks locally: +# dotnet restore Kof22App.slnx -p:Platform=x64 dotnet restore Kof22App.slnx -p:Platform=x64 --locked-mode dotnet build Kof22App.slnx -p:Platform=x64 -warnaserror dotnet test Kof22App.slnx -p:Platform=x64 --no-build --filter "FullyQualifiedName!~UiTests" diff --git a/TEMPLATE.md b/TEMPLATE.md index f747fdc..e4f26a9 100644 --- a/TEMPLATE.md +++ b/TEMPLATE.md @@ -18,6 +18,15 @@ dotnet new k22-winapp -n Contoso.Notes --appId contoso-notes --displayName "Cont --description "Quick notes that stay out of the way." -o Contoso.Notes ``` +To try the installable package before its first publication, run from this clone: + +```powershell +dotnet pack templates/KofTwentyTwo.Templates.WindowsApp.csproj -c Release -p:Version=0.1.0 -p:RestoreLockedMode=true -o artifacts/template +dotnet new install ./artifacts/template/KofTwentyTwo.Templates.WindowsApp.0.1.0.nupkg +dotnet new k22-winapp -n Contoso.Notes --appId contoso-notes --displayName "Contoso Notes" -o artifacts/Contoso.Notes +# Add --cli false for a GUI-only app; use a fresh output directory each time. +``` + | Option | Default | What it sets | | --- | --- | --- | | `-n`, `--name` | (required) | Solution, project, namespace, and executable names (`Contoso.Notes.slnx`, `Contoso.Notes.Core`, `Contoso.Notes.exe`), and the repository name in links | @@ -32,8 +41,10 @@ The copyright year in license headers becomes the current year. ## After generating -The generator omits dependency lock files. Before the first commit, run the README's -restore, build, test, coverage and format commands, then commit the resulting +The generator omits NuGet dependency lock files. Before the first commit, run +`dotnet restore .slnx -p:Platform=x64` in the generated directory to create +them, then run the README's locked restore, build, test, coverage and format +commands. Commit the resulting `packages.lock.json` files. Install the included hooks with `pre-commit install --hook-type pre-commit --hook-type commit-msg` after `git init`. The generated PowerShell tooling gate uses PSScriptAnalyzer 1.25.0. @@ -41,12 +52,10 @@ The generated PowerShell tooling gate uses PSScriptAnalyzer 1.25.0. 1. Follow [the preview/apply/validate setup runbook](docs/repository-setup.md). Create the GitHub repository (public, Product tier), push `main`, and apply the [repository standard's](https://github.com/KofTwentyTwo/standards/blob/main/standards/repository.md) - settings and rulesets, with these required checks: `pr / title`, `pr / dco`, - `pr / dependency-review`, `security / secrets`, `security / sca`, - `security / workflows`, `codeql / analyze (csharp)`, `codeql / analyze (actions)`, - `ci / build-test`, `ci / format`, `ci / ui-tests`, `scripts / powershell`, - `scripts / javascript`, `codeql / analyze (javascript-typescript)`, and - `review / automated` for the single-maintainer policy. + settings and rulesets. Use the setup tool's required contexts and + [CONTRIBUTING.md](CONTRIBUTING.md)'s check table; standalone job names have no + workflow-name prefix. The source repository additionally requires `template`; + generated application repositories do not. 2. Create the `release` environment limited to `v*` tags, and list the repository in the [standards repository inventory](https://github.com/KofTwentyTwo/standards/blob/main/MAINTAINERS.md#repositories) (`K22-REPO-42`; the conformance checker fails until it is listed). -- 2.54.0 From 758e7737728623431c7248b0c1a3bc2dd4296b3b Mon Sep 17 00:00:00 2001 From: James Maes Date: Sat, 10 Oct 2026 19:02:05 -0500 Subject: [PATCH 2/2] fix(template): allow pinned security scanner containers Hosted bootstrap showed that GitHub rejects the security builder container actions under the selected-actions policy. Permit only its exact published Gitleaks and Trivy image digests; preserve selected actions and required security gates. Validation: 55 script cases, full analysis of changed module/tests, guide lint and normal hooks. Refs: KofTwentyTwo/AppKit#10, KofTwentyTwo/AppKit#20 Co-Authored-By: Codex (GPT-6) Signed-off-by: James Maes --- build/GitHubRepository.Tests.ps1 | 15 +++++++++++++++ build/GitHubRepository.psm1 | 9 ++++++++- docs/repository-setup.md | 6 ++++++ 3 files changed, 29 insertions(+), 1 deletion(-) diff --git a/build/GitHubRepository.Tests.ps1 b/build/GitHubRepository.Tests.ps1 index 6a33f1c..9f7cb66 100644 --- a/build/GitHubRepository.Tests.ps1 +++ b/build/GitHubRepository.Tests.ps1 @@ -47,6 +47,21 @@ Describe 'Required checks match standalone workflow jobs' ` Describe 'Generated repository administration' ` { + It 'allows the digest-pinned security containers without permitting arbitrary container actions' ` + { + $plan = Get-GitHubRepositoryPlan -Repository 'Example/Notes' + $policy = ($plan.Requests | Where-Object Path -Like '*/actions/permissions/selected-actions').Body + $policy.patterns_allowed.Count | Should -Be 3 + $policy.patterns_allowed | Should -Contain 'KofTwentyTwo/standards/*@*' + $containers = @($policy.patterns_allowed | Where-Object { $_.StartsWith('docker://', [StringComparison]::Ordinal) }) + $containers.Count | Should -Be 2 + foreach($container in $containers) + { + $container | Should -Match '^docker://ghcr\.io/(gitleaks/gitleaks:v8\.30\.1|aquasecurity/trivy:0\.75\.0)@sha256:[0-9a-f]{64}$' + $container | Should -Not -Match '\*' + } + } + InModuleScope GitHubRepository ` { BeforeEach ` diff --git a/build/GitHubRepository.psm1 b/build/GitHubRepository.psm1 index 572b03c..0e6923c 100644 --- a/build/GitHubRepository.psm1 +++ b/build/GitHubRepository.psm1 @@ -74,7 +74,14 @@ function Get-GitHubRepositoryPlan @{ Method = 'PUT'; Path = "$root/actions/permissions/workflow"; Body = @{ default_workflow_permissions = 'read'; can_approve_pull_request_reviews = $false } }, @{ Method = 'PUT'; Path = "$root/actions/permissions/fork-pr-contributor-approval"; Body = @{ approval_policy = 'all_external_contributors' } }, @{ Method = 'PUT'; Path = "$root/actions/permissions"; Body = @{ enabled = $true; allowed_actions = 'selected' } }, - @{ Method = 'PUT'; Path = "$root/actions/permissions/selected-actions"; Body = @{ github_owned_allowed = $true; verified_allowed = $true; patterns_allowed = @('KofTwentyTwo/standards/*@*') } }, + @{ Method = 'PUT'; Path = "$root/actions/permissions/selected-actions"; Body = @{ + github_owned_allowed = $true; verified_allowed = $true + # Exact container actions used by the published v0.1.2 security builder. + patterns_allowed = @('KofTwentyTwo/standards/*@*', + 'docker://ghcr.io/gitleaks/gitleaks:v8.30.1@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f', + 'docker://ghcr.io/aquasecurity/trivy:0.75.0@sha256:af6acf9a6b85dfe389a1941505c0ce9efef52a4719635e1a962f022a3d855daa') + } + }, @{ Method = 'PUT'; Path = "$root/environments/release"; Body = @{ deployment_branch_policy = @{ protected_branches = $false; custom_branch_policies = $true } } }, @{ Method = 'POST'; Path = "$root/environments/release/deployment-branch-policies"; Body = @{ name = 'v*'; type = 'tag' } }, @{ Method = 'POST'; Path = "$root/rulesets"; Body = $main }, diff --git a/docs/repository-setup.md b/docs/repository-setup.md index 23f4bbf..0edc409 100644 --- a/docs/repository-setup.md +++ b/docs/repository-setup.md @@ -66,6 +66,12 @@ and environment protections are retained. API failures stop immediately; earlier successful requests may remain, so validate and resolve the reported failure before rerunning. The tool never creates repositories, pushes, merges, tags or releases. +The selected Actions policy permits the shared standards workflows, GitHub-owned +and verified actions, and the exact digest-pinned Gitleaks/Trivy container actions +used by the published security builder. GitHub also checks container actions +against this policy; missing entries prevent the security workflow from starting. +Review these exact references whenever the shared builder pin changes. + ## Finish and verify Register ownership/tier in the standards `MAINTAINERS.md` inventory through a -- 2.54.0