docs: Document required GitHub repository secrets

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

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 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
 Write-Host ''

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