From c73e51745909f05a633efc2f1a4b870b4b105dec Mon Sep 17 00:00:00 2001 From: Trent Blackburn Date: Thu, 30 Apr 2026 15:27:23 -0400 Subject: [PATCH 1/2] docs: Document required GitHub repository secrets The bundled CI/CD workflows assume three repository secrets are set (PS_GALLERY_KEY, CODECOV_TOKEN, GITGUARDIAN_API_KEY), but downstream users had no way to discover this short of reading the workflow files and tracing through to the failure modes. Adds a "Repository secrets" section to README documenting each secret with its required/optional status, source, and failure behavior. Adds a corresponding step to Initialize-Template.ps1's post-init "Next steps" output so users see the reminder right when they finish init, before their first push to GitHub triggers CI runs that need the secrets. Also clarifies the PS_GALLERY_KEY -> PSGALLERY_API_KEY env var mapping that the publish workflow performs (one of those subtleties that's easy to misconfigure when reading the workflow file directly). Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 5 +++++ Initialize-Template.ps1 | 3 ++- README.md | 15 +++++++++++++++ 3 files changed, 22 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 79a9853..c40039f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,11 @@ own `CHANGELOG.md` (generated from `CHANGELOG.template.md` during init). ## [Unreleased] +### Added + +- "Repository secrets" section in `README.md` documenting the GitHub Actions secrets the bundled workflows expect (`PS_GALLERY_KEY`, `CODECOV_TOKEN`, `GITGUARDIAN_API_KEY`) — required vs. optional, source, and failure mode when missing. +- `Initialize-Template.ps1` now mentions configuring GitHub repository secrets in its post-init "Next steps" output, between the build-test step and the first push. + ## [2026.04.29] - 2026-04-29 ### Added diff --git a/Initialize-Template.ps1 b/Initialize-Template.ps1 index 1d7181b..68b77a1 100644 --- a/Initialize-Template.ps1 +++ b/Initialize-Template.ps1 @@ -362,7 +362,8 @@ Write-Host " 1. Review the generated files in the $ModuleName folder" Write-Host ' 2. Review README.md and adjust to taste' Write-Host ' 3. Add your functions to the Public/ and Private/ folders' Write-Host ' 4. Run ./build.ps1 -Task Test to verify everything works' -Write-Host ' 5. Push to your GitHub repository' +Write-Host ' 5. Configure GitHub repository secrets (see "Repository secrets" in README.md)' +Write-Host ' 6. Push to your GitHub repository' Write-Host '' Write-Host 'You can safely delete this Initialize-Template.ps1 file.' -ForegroundColor Yellow Write-Host '' diff --git a/README.md b/README.md index 86c3eba..005c2a7 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,21 @@ A GitHub repository template for building, testing, and publishing PowerShell mo ``` 4. The script substitutes placeholders, renames files, optionally runs `git init`, and bootstraps build dependencies. Delete `Initialize-Template.ps1` when done. +5. Configure your new repository's GitHub Actions secrets — the bundled CI/CD workflows expect a few secrets to be set. See [Repository secrets](#repository-secrets) below. + +## Repository secrets + +The bundled GitHub Actions workflows expect the following secrets to be set in your repository under **Settings → Secrets and variables → Actions**: + +| Secret | Workflow | Required? | Source | Failure if missing | +|---|---|---|---|---| +| `PS_GALLERY_KEY` | `PublishModuleToPowerShellGallery.yaml` | Required to publish | [PowerShell Gallery API keys](https://www.powershellgallery.com/account/apikeys) (scope to your module name) | Publish job fails at the PowerShellBuild authentication assertion | +| `CODECOV_TOKEN` | `CI.yaml` | Optional | [Codecov](https://about.codecov.io/) after linking the repository | Coverage upload step is gated with `fail_ci_if_error: false`, so CI still passes — no coverage data is uploaded | +| `GITGUARDIAN_API_KEY` | `ggshield.yaml` | Required for that workflow to pass | [GitGuardian dashboard](https://dashboard.gitguardian.com/) (free tier available) | Workflow fails on every push with "Invalid GitGuardian API key" | + +`GITHUB_TOKEN` is automatically provided by GitHub Actions and does not need to be set. + +The publish workflow exposes `secrets.PS_GALLERY_KEY` to its job as the env var `PSGALLERY_API_KEY` — the variable PowerShellBuild reads when publishing. Set the secret as `PS_GALLERY_KEY`. ## Placeholders From a25eb4c709d8573092e620cf0e99f66e98a627de Mon Sep 17 00:00:00 2001 From: Trent Blackburn Date: Tue, 5 May 2026 10:21:17 -0400 Subject: [PATCH 2/2] docs(init): replace broken README pointer with link to template's secrets docs --- Initialize-Template.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Initialize-Template.ps1 b/Initialize-Template.ps1 index 68b77a1..654b58e 100644 --- a/Initialize-Template.ps1 +++ b/Initialize-Template.ps1 @@ -362,7 +362,7 @@ Write-Host " 1. Review the generated files in the $ModuleName folder" Write-Host ' 2. Review README.md and adjust to taste' Write-Host ' 3. Add your functions to the Public/ and Private/ folders' Write-Host ' 4. Run ./build.ps1 -Task Test to verify everything works' -Write-Host ' 5. Configure GitHub repository secrets (see "Repository secrets" in README.md)' +Write-Host ' 5. Configure GitHub repository secrets - see https://github.com/tablackburn/PowerShellModuleTemplate#repository-secrets' Write-Host ' 6. Push to your GitHub repository' Write-Host '' Write-Host 'You can safely delete this Initialize-Template.ps1 file.' -ForegroundColor Yellow