Document push-authoritative releases

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

docs/content/get-started/index.md

@@ -15,7 +15,7 @@ Start new modules from the PSModule template repository:
 3. Replace placeholder metadata and remove scaffold sample files.
 4. Add your first public command and tests.
 5. Validate `.github/PSModule.yml` defaults for your module.
-6. [Open a draft pull request](your-first-release.md) and run the full pipeline.
+6. [Open a draft pull request](your-first-release.md), then release from its resulting important default-branch push.
 
 If the module needs several interdependent commands before it is usable at all, see
 [Module bootstrap](module-bootstrap.md) instead of shipping them as one command per step.
@@ -31,7 +31,7 @@ If the module needs several interdependent commands before it is usable at all,
 | Page | Description |
 | --- | --- |
 | [Repository setup](repository-setup.md) | GitHub Pages, `PSGALLERY_API_KEY`, permissions, and the caller workflow. |
-| [Your first release](your-first-release.md) | The pull request flow, version labels, and what happens on merge. |
+| [Your first release](your-first-release.md) | The pull request flow, version labels, and the resulting default-branch release. |
 | [Module bootstrap](module-bootstrap.md) | Getting a brand-new module to its first release with an integration branch. |
 
 For framework-level practices, refer to [MSX Ways of Working](https://msx.no/docs/Ways-of-Working/).

docs/content/get-started/module-bootstrap.md

@@ -20,7 +20,7 @@ Scope the integration branch to exactly that core, not to everything planned for
 
 1. Cut one long-lived branch from the default branch for the initial release, named for the outcome, e.g. `build-thing-module`.
 2. Open one pull request per function (or small group of related functions) targeting that branch instead of `main`. These PRs can land in parallel — there is no strict order between them, unlike a [stacked pull request](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests).
-3. Once the load-bearing core is coherent and complete, open the pull request that merges the integration branch into `main`. This becomes the module's first real release (`v1.0.0`).
+3. Once the load-bearing core is coherent and complete, open the pull request that merges the integration branch into `main`. Its resulting important push becomes the module's first real release (`v1.0.0`).
 4. Smaller follow-up features (one more function, a formatter, an alias) can keep targeting the integration branch before it lands, the same way they targeted it during bootstrap.
 
 ## After the core lands

docs/content/get-started/repository-setup.md

@@ -53,7 +53,7 @@ on:
       - unlabeled
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: false
 
 permissions:

docs/content/get-started/your-first-release.md

@@ -1,30 +1,37 @@
 ---
 title: Your first release
-description: The pull request flow, version labels, and what happens when a Process-PSModule pull request is merged.
+description: The pull request flow, version labels, and the default-branch push that creates a stable Process-PSModule release.
 ---
 
 # Your first release
 
-Process-PSModule is driven entirely by pull requests. There is no manual publish step, no version file to edit, and no
-tag to push by hand.
+Process-PSModule uses pull requests for review and release metadata, and an important push to the default branch as
+the authority for stable publication. There is no manual publish step, no version file to edit, and no tag to push by
+hand.
 
 ## The flow
 
 1. Clone the repository, create a branch, and make your changes.
 2. Push the branch and open a pull request against `main`.
 3. The workflow builds the module, runs tests on Windows, Linux, and macOS, lints the repository, and reports back on
    the pull request.
-4. Apply a version label to declare release intent (see below). Without a label, the change releases as a **patch**.
-5. Merge the pull request. The workflow publishes the module to the PowerShell Gallery, creates a GitHub Release and
-   tag, and deploys the documentation site to GitHub Pages.
+4. Apply a version label to declare release intent (see below). An unlabeled pull request defaults to a **patch** when
+   `Publish.Module.AutoPatching` is enabled, which is the default.
+5. Merge the pull request. Its resulting important push to `main` runs the stable release: after the pipeline passes,
+   it publishes the module to the PowerShell Gallery, creates a GitHub Release and tag for the tested commit, and
+   deploys the documentation site unless site publication is configured to skip. The closed-pull-request event only
+   cleans up prereleases.
+
+An important direct push to the default branch, or a manual dispatch on that branch, also creates a stable **patch**
+release with commit-based notes. It has no pull-request labels or body to use as metadata.
 
 ## Version labels
 
 | Label | Effect |
 | --- | --- |
 | `major` / `breaking` | Bump `MAJOR`. |
 | `minor` / `feature` | Bump `MINOR`. |
-| `patch` / `fix` | Bump `PATCH`. This is the default when no label is applied. |
+| `patch` / `fix` | Bump `PATCH`. This is the default for an unlabeled PR when `AutoPatching` is enabled. |
 | `Prerelease` | Publish a prerelease version from the pull request, before it is merged. |
 | `NoRelease` | Run the pipeline but skip publication. |
 
@@ -43,9 +50,9 @@ cleaned up automatically.
 
 ## When nothing is released
 
-If a pull request only touches files outside the configured important-file patterns — documentation, CI tweaks, comment
-typos — the build, test, and publish stages are skipped and no release is created. A comment on the pull request
-explains why. See
+If a pull request or default-branch push only touches files outside the configured important-file patterns —
+documentation, CI tweaks, comment typos — the build, test, and publish stages are skipped and no release is created.
+A pull-request comment explains why for pull-request runs. See
 [important-file change detection](../guides/calling-the-workflow.md#important-file-change-detection) to change which
 paths trigger a release.
 

docs/content/guides/calling-the-workflow.md

@@ -36,7 +36,7 @@ on:
       - unlabeled
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: false
 
 permissions:
@@ -61,6 +61,10 @@ Stable releases are evaluated from a push to the default branch. A merged pull r
 release notes; a direct default-branch push or a manual dispatch uses the default `Patch` bump and commit-based notes.
 Keep the `pull_request` trigger for CI, prereleases, and prerelease cleanup.
 
+The concurrency key keeps a pull request distinct from a default-branch push, so the close-event cleanup and the
+resulting stable release do not serialize as one run. Keep `cancel-in-progress: false`: a release-capable run mutates
+the PowerShell Gallery, GitHub Releases, and tags, so later runs must queue rather than interrupt it.
+
 ## Passing test data
 
 The reusable workflow at `.github/workflows/workflow.yml` declares four workflow-call secrets,

docs/content/index.md

@@ -9,7 +9,11 @@ An end-to-end PowerShell module pipeline that automates the entire lifecycle of
 
 ## How it works
 
-The workflow is triggered on pull requests to the repository's default branch. When a pull request is opened, closed, reopened, synchronized (push), or labeled, the workflow runs. Depending on the labels on the pull request, the [workflow results in different outcomes](reference/scenario-matrix.md).
+The caller workflow runs for pull-request lifecycle events and pushes to the repository's default branch. Open pull
+requests run CI and can publish prereleases; closed pull requests clean up their prereleases. An important
+default-branch push is the sole authority for a stable release. When that push is the exact merge commit of a pull
+request, its labels and release notes supply the release metadata. See the
+[scenario matrix](reference/scenario-matrix.md) for the resulting job execution.
 
 Everything is packaged into a single reusable workflow so that a module repository only needs a small caller workflow and one settings file. A user configures the behaviour by editing `.github/PSModule.yml`.
 
@@ -23,7 +27,7 @@ New to Process-PSModule? Work through these in order.
 | --- | --- |
 | [Get started](get-started/index.md) | Create a module repository from the template and get the pipeline running. |
 | [Repository setup](get-started/repository-setup.md) | Configure GitHub Pages, `PSGALLERY_API_KEY`, permissions, and the caller workflow. |
-| [Your first release](get-started/your-first-release.md) | The pull request flow, version labels, and what happens on merge. |
+| [Your first release](get-started/your-first-release.md) | The pull request flow, version labels, and the resulting default-branch release. |
 
 ## Guides
 
@@ -32,6 +36,7 @@ Task-oriented deep dives into the pipeline's functionality.
 | Page | Description |
 | --- | --- |
 | [Calling the workflow](guides/calling-the-workflow.md) | The caller workflow, passing test secrets and variables with `TestData`, and important-file change detection. |
+| [GitHub App authentication](guides/github-app-authentication.md) | Configure Shelly credentials and the scoped tokens used for repository API operations. |
 | [Configuring the pipeline](guides/configuring-the-pipeline.md) | Worked examples for coverage targets, rapid testing, linting, and PR-based release notes. |
 | [Structuring your module](guides/structuring-your-module.md) | The repository and module source layout the workflow expects, and how to declare dependencies. |
 | [Writing module tests](guides/writing-module-tests.md) | Test discovery, setup and teardown phases, and shared test infrastructure. |

docs/content/reference/pipeline-stages.md

@@ -132,8 +132,11 @@ How to write these tests, including the Pester version requirement and shared-in
 
 [workflow](https://github.com/PSModule/Process-PSModule/blob/main/.github/workflows/Publish-Module.yml)
 
+- An important default-branch push is the only stable-publication authority. A closed pull request performs
+  prerelease cleanup only.
 - Publishes the artifact to the PowerShell Gallery exactly as built — no version mutation.
-- Creates a GitHub Release using the version already stamped in the manifest.
+- Creates a GitHub Release only after the Gallery publication succeeds, targeting the exact tested push SHA and using
+  the version already stamped in the manifest.
 - Attaches the built module as a `.zip` asset on the GitHub Release so consumers can download the exact bytes that were tested and pushed to the PowerShell Gallery.
 - **Abandoned PR cleanup**: When a PR is closed without merging (abandoned), the workflow automatically cleans up any
   prerelease versions and tags that were created for that PR. This ensures that abandoned work doesn't leave orphaned

docs/content/reference/powershell-module-standard.md

@@ -111,15 +111,20 @@ Keep related things together so the connection between code and its context is v
 
 ### Linear versioning
 
-The release process treats each merged PR as a release on a single linear ancestry. There is no patching of older versions — security fixes go on the current tip of `main` only.
+The release process treats each important default-branch push as a release on a single linear ancestry. A merged pull
+request supplies release metadata when its merge commit exactly matches that push. There is no patching of older
+versions — security fixes go on the current tip of `main` only.
 
 ### Release and feature branches
 
-For large work, open a release branch and target it from feature branches. Apply the `Prerelease` label on the release branch PR to publish preview versions before the final merge to `main`.
+For large work, open a release branch and target it from feature branches. Apply the `Prerelease` label on the release
+branch PR to publish preview versions before its final merge creates the stable default-branch push.
 
 ## CI/CD pipeline
 
-The [Process-PSModule](https://github.com/PSModule/Process-PSModule) workflow orchestrates the full lifecycle. Every PR triggers a **Plan** job that resolves configuration and version, then conditionally runs build, test, lint, and publish stages.
+The [Process-PSModule](https://github.com/PSModule/Process-PSModule) workflow orchestrates the full lifecycle. Pull
+requests and default-branch pushes trigger a **Plan** job that resolves configuration and version, then conditionally
+runs build, test, lint, and publish stages.
 
 ### Pipeline stages
 
@@ -147,20 +152,20 @@ graph LR
 
 | Stage | Runs on | Purpose |
 | ----- | ------- | ------- |
-| **Plan** | All events | Loads `.github/PSModule.yml`, resolves version from PR labels, produces the Settings JSON |
+| **Plan** | All events | Loads `.github/PSModule.yml`, resolves the release context, produces the Settings JSON |
 | **Lint-Repository** | Open/Updated PR | Runs super-linter on the full repo (Markdown, YAML, etc.) |
-| **Lint-SourceCode** | Open/Updated PR, Merged PR, Manual | Runs PSScriptAnalyzer against `src/` |
-| **Build-Module** | Open/Updated PR, Merged PR, Manual | Compiles source into a versioned module artifact |
-| **Test-SourceCode** | Open/Updated PR, Merged PR, Manual | Framework tests on raw source files |
-| **Test-Module** | Open/Updated PR, Merged PR, Manual | Pester tests against the built module artifact |
-| **BeforeAll-ModuleLocal** | Open/Updated PR, Merged PR, Manual | Runs `tests/BeforeAll.ps1` once before the local test matrix |
-| **Test-ModuleLocal** | Open/Updated PR, Merged PR, Manual | Pester tests with the module installed locally (cross-OS matrix) |
+| **Lint-SourceCode** | Open/Updated PR, default-branch push/manual run | Runs PSScriptAnalyzer against `src/` |
+| **Build-Module** | Open/Updated PR, default-branch push/manual run | Compiles source into a versioned module artifact |
+| **Test-SourceCode** | Open/Updated PR, default-branch push/manual run | Framework tests on raw source files |
+| **Test-Module** | Open/Updated PR, default-branch push/manual run | Pester tests against the built module artifact |
+| **BeforeAll-ModuleLocal** | Open/Updated PR, default-branch push/manual run | Runs `tests/BeforeAll.ps1` once before the local test matrix |
+| **Test-ModuleLocal** | Open/Updated PR, default-branch push/manual run | Pester tests with the module installed locally (cross-OS matrix) |
 | **AfterAll-ModuleLocal** | Always (if tests started) | Runs `tests/AfterAll.ps1` for cleanup |
 | **Get-TestResults** | Always (if Plan succeeded) | Aggregates and reports test results |
 | **Get-CodeCoverage** | Always (if Plan succeeded) | Calculates and reports code coverage |
-| **Publish-Module** | Merged PR (or Prerelease label) | Publishes to PowerShell Gallery and creates a GitHub Release |
-| **Build-Docs / Build-Site** | Open/Updated PR, Merged PR, Manual | Generates documentation site from source |
-| **Publish-Site** | Merged PR | Deploys documentation site to GitHub Pages |
+| **Publish-Module** | Prerelease PR, stable default-branch push/manual run, or closed PR | Publishes a prerelease or stable release, or cleans up closed-PR prereleases |
+| **Build-Docs / Build-Site** | Open/Updated PR, default-branch push/manual run | Generates documentation site from source |
+| **Publish-Site** | Stable default-branch push/manual run | Deploys documentation site to GitHub Pages unless `Publish.Site.Skip` is set |
 
 ### Important file patterns
 
@@ -186,7 +191,7 @@ The **Plan** job resolves the next version before any build occurs. This means t
 
 **Flow:**
 
-1. `Get-PSModuleSettings` loads `.github/PSModule.yml` and determines `ReleaseType` from PR labels
+1. `Get-PSModuleSettings` loads `.github/PSModule.yml` and determines `ReleaseType` from the normalized event context
 2. `Resolve-PSModuleVersion` calculates the next semantic version from the latest Git tag
 3. `Build-PSModule` stamps the resolved version into the compiled manifest
 4. `Publish-PSModule` reads the version from the manifest (read-only) and publishes
@@ -203,6 +208,9 @@ The **Plan** job resolves the next version before any build occurs. This means t
 
 **Prerelease versions:** Adding a `Prerelease` label to the PR produces a prerelease tag (e.g., `1.2.3-preview0001`). The format is controlled by `IncrementalPrerelease` (sequential numbering) or `DatePrereleaseFormat` (.NET DateTime format string).
 
+An important direct default-branch push and a default-branch manual dispatch always resolve to `Patch`, regardless of
+`AutoPatching`. A push that exactly matches a merged pull request uses that PR's version label instead.
+
 **Tag format:** Releases are tagged with a configurable prefix (default `v`) — e.g., `v1.2.3`.
 
 ### Configuration (`.github/PSModule.yml`)
@@ -246,9 +254,11 @@ Test:
     PercentTarget: 0
 
 Publish:
+  Site:
+    Skip: false
   Module:
     Skip: false
-    AutoCleanup: true           # Delete prerelease tags after stable release
+    AutoCleanup: true           # Delete prerelease tags after stable release or PR closure
     AutoPatching: true           # Unlabeled PRs default to patch bump
     IncrementalPrerelease: true  # Sequential prerelease numbering
     DatePrereleaseFormat: ''     # Alternative: .NET DateTime format for prerelease
@@ -274,16 +284,17 @@ The `Publish-Module` stage:
 2. Reads the version from the compiled manifest (no recalculation)
 3. Publishes to the PowerShell Gallery
 4. Creates a GitHub Release with the module attached as a ZIP artifact
-5. Comments on the PR with links to the Gallery package and GitHub Release
+5. Comments on the associated PR with links to the Gallery package and GitHub Release
 6. Cleans up old prerelease tags when publishing a stable release (if `AutoCleanup: true`)
 
 The publish step only runs when:
 
 - All tests and code coverage pass (or are skipped)
-- The PR is merged to the default branch (stable release), or
+- An important push reaches the default branch (stable release), or
 - The PR carries the `Prerelease` label (prerelease from the feature/release branch)
 
-On abandoned (closed without merge) PRs, the pipeline cleans up any prerelease tags created for that branch.
+On any closed PR, the pipeline cleans up any prerelease tags created for that branch. A closed pull request cannot
+create a stable release.
 
 ## Tests