Document valid caller concurrency policies

GitHub Actions requires static queue values and rejects queue: max with cancellation. Separate production and pull-request caller jobs preserve both required behaviors.

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

Author: MariusStorhaug

.github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md

@@ -165,14 +165,30 @@ on:
       - labeled
       - unlabeled
 
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
 permissions: {}
 
 jobs:
-  Process-PSModule:
+  Process-PSModule-Production:
+    if: ${{ github.event_name != 'pull_request' }}
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      queue: max
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    secrets:
+      PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
+      GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
+      GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
+
+  Process-PSModule-PullRequest:
+    if: ${{ github.event_name == 'pull_request' }}
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+      queue: single
+      cancel-in-progress: true
     permissions:
       contents: read
       pages: write
@@ -184,11 +200,10 @@ jobs:
       GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
 ```
 
-The only permitted variation is an optional `TestData` entry under
-`jobs.Process-PSModule.secrets`. Do not add `with:` inputs, extra jobs,
-conditions, schedule changes, `run-name`, permission changes, trigger changes,
-concurrency changes, debug options, or version overrides. Repository-owned
-automation belongs in separate workflow files.
+The only permitted variation is an optional identical `TestData` entry under both caller jobs' `secrets` mappings.
+Do not add `with:` inputs, extra jobs, conditions, schedule changes, `run-name`, permission changes, trigger changes,
+concurrency changes, debug options, or version overrides. Repository-owned automation belongs in separate workflow
+files.
 
 ### TestData preservation
 

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

@@ -52,33 +52,51 @@ on:
       - labeled
       - unlabeled
 
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  queue: ${{ github.event_name == 'pull_request' && 'single' || 'max' }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
+permissions: {}
 
 jobs:
-  Process-PSModule:
+  Process-PSModule-Production:
+    if: ${{ github.event_name != 'pull_request' }}
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      queue: max
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    secrets:
+      PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
+      GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
+      GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
+
+  Process-PSModule-PullRequest:
+    if: ${{ github.event_name == 'pull_request' }}
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+      queue: single
+      cancel-in-progress: true
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
     uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
       GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
       GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
 ```
 
-Every permission in that block is required. GitHub App installation tokens perform repository writes. A push to `main` publishes a stable release after the full pipeline passes;
-the pull-request trigger handles CI, prereleases, and prerelease cleanup. See
+Every permission on the calling jobs is required. GitHub App installation tokens perform repository writes. A push to
+`main` publishes a stable release after the full pipeline passes; the pull-request trigger handles CI, prereleases,
+and prerelease cleanup. See
 [Workflow inputs](../reference/workflow-inputs.md) for what each permission is used for, and
 [Calling the workflow](../guides/calling-the-workflow.md) for passing test secrets and variables.
 
-The caller-level concurrency block retains production and manual work while replacing obsolete work for the same pull
-request. The fallback expression uses the pull-request number for every pull-request action, including `closed`; other
-events use their Git ref. Keep its group distinct from the reusable workflow's prefixed group.
+The production job retains pushes, dispatches, and scheduled work in the maximum native queue. The pull-request job
+cancels obsolete activity and uses the pull-request number for every action, including `closed`. GitHub requires a
+literal queue value and does not permit cancellation with `queue: max`, so the two jobs use separate compatible
+policies. Keep both groups distinct from the reusable workflow's prefixed group.
 
 ## 4. Add the settings file
 

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

@@ -35,18 +35,34 @@ on:
       - labeled
       - unlabeled
 
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  queue: ${{ github.event_name == 'pull_request' && 'single' || 'max' }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
+permissions: {}
 
 jobs:
-  Process-PSModule:
+  Process-PSModule-Production:
+    if: ${{ github.event_name != 'pull_request' }}
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      queue: max
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    secrets:
+      PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
+      GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
+      GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
+
+  Process-PSModule-PullRequest:
+    if: ${{ github.event_name == 'pull_request' }}
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+      queue: single
+      cancel-in-progress: true
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
     uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
@@ -60,10 +76,11 @@ 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 each pull request distinct from the default branch, so a close event interrupts only its own
-pull-request activity and does not block the resulting stable release. Pull-request events replace obsolete activity;
-all other events, including a manual default-branch release, retain the maximum native queue. The reusable workflow
-uses a distinct prefixed concurrency group. Do not give the caller the reusable workflow's group name.
+The production job serializes default-branch pushes, manual releases, and scheduled work in the maximum native queue.
+The pull-request job uses a separate group for each pull request, so a close event interrupts only its own activity and
+does not block the resulting stable release. Its `single` queue and cancellation replace obsolete activity. GitHub
+requires a literal queue value and rejects cancellation with `queue: max`, so these policies must remain separate.
+The reusable workflow uses a distinct prefixed concurrency group. Do not give either caller job that group name.
 
 ## Passing test data
 
@@ -85,21 +102,14 @@ The reusable workflow accepts test data through `TestData` and no longer declare
 - `TEST_USER_USER_FG_PAT`
 - `TEST_USER_PAT`
 
-If a caller passed any of these secrets directly, place them in the `secrets` map inside `TestData`.
-The environment variable names used by the tests can stay the same; only the workflow-call interface
-changes:
+If a caller passed any of these secrets directly, place them in the `secrets` map inside `TestData`. Add the same
+`TestData` mapping to the `secrets` block of both caller jobs. The environment variable names used by the tests can
+stay the same; only the workflow-call interface changes:
 
 ```yaml
-jobs:
-  Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
-    secrets:
-      PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
-      GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
-      GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
-      TestData: >-
-        { "secrets": { "TEST_USER_PAT": "${{ secrets.TEST_USER_PAT }}",
-        "TEST_APP_ORG_CLIENT_ID": "${{ secrets.TEST_APP_ORG_CLIENT_ID }}" } }
+TestData: >-
+  { "secrets": { "TEST_USER_PAT": "${{ secrets.TEST_USER_PAT }}",
+  "TEST_APP_ORG_CLIENT_ID": "${{ secrets.TEST_APP_ORG_CLIENT_ID }}" } }
 ```
 
 ### Passing test phase data (secrets and variables)
@@ -112,25 +122,17 @@ workflow. It is one JSON object with two maps, so everything the tests need is v
 { "secrets": { "NAME": "value" }, "variables": { "NAME": "value" } }
 ```
 
-Values under `secrets` are masked in the logs; values under `variables` are not. Build it in the
-calling workflow and pass it through the `secrets:` block (so the whole blob is masked). Reference each
-secret directly as `"${{ secrets.<name> }}"` and each variable as `${{ toJSON(vars.<name>) }}`. A
-folded `>-` scalar keeps the source readable while producing a single-line value, as long as the JSON
-content lines stay at the same indentation level:
+Values under `secrets` are masked in the logs; values under `variables` are not. Build it in the calling workflow and
+pass it through the `secrets:` blocks of both caller jobs so the whole blob is masked. Reference each secret directly
+as `"${{ secrets.<name> }}"` and each variable as `${{ toJSON(vars.<name>) }}`. A folded `>-` scalar keeps the source
+readable while producing a single-line value, as long as the JSON content lines stay at the same indentation level:
 
 ```yaml
-jobs:
-  Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
-    secrets:
-      PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
-      GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
-      GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
-      TestData: >-
-        { "secrets": { "CONFLUENCE_API_TOKEN": "${{ secrets.CONFLUENCE_API_TOKEN }}" },
-        "variables": { "CONFLUENCE_SITE": ${{ toJSON(vars.CONFLUENCE_SITE) }},
-        "CONFLUENCE_USERNAME": ${{ toJSON(vars.CONFLUENCE_USERNAME) }},
-        "CONFLUENCE_SPACE_KEY": ${{ toJSON(vars.CONFLUENCE_SPACE_KEY) }} } }
+TestData: >-
+  { "secrets": { "CONFLUENCE_API_TOKEN": "${{ secrets.CONFLUENCE_API_TOKEN }}" },
+  "variables": { "CONFLUENCE_SITE": ${{ toJSON(vars.CONFLUENCE_SITE) }},
+  "CONFLUENCE_USERNAME": ${{ toJSON(vars.CONFLUENCE_USERNAME) }},
+  "CONFLUENCE_SPACE_KEY": ${{ toJSON(vars.CONFLUENCE_SPACE_KEY) }} } }
 ```
 
 Each entry becomes an environment variable in the test jobs, so the module's Pester tests read the

docs/content/guides/github-app-authentication.md

@@ -18,11 +18,18 @@ The reusable workflow declares two required secrets at its `workflow_call` bound
 | `GitHubAppPrivateKey` | The GitHub App private key passed to the token action. |
 
 The names are the reusable workflow contract, not a requirement for the caller's repository or organization secret
-names. Map the caller's secrets explicitly:
+names. Map the caller's secrets explicitly in both caller jobs:
 
 ```yaml
 jobs:
-  Process-PSModule:
+  Process-PSModule-Production:
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    secrets:
+      PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
+      GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
+      GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
+
+  Process-PSModule-PullRequest:
     uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}

docs/content/reference/repository-standard.md

@@ -117,11 +117,19 @@ The module repository owns a caller workflow; the framework owns the reusable wo
 | Caller workflow | The module repository | `.github/workflows/Process-PSModule.yml` |
 | Reusable workflow | [`PSModule/Process-PSModule`](https://github.com/PSModule/Process-PSModule) | `.github/workflows/workflow.yml` |
 
-The caller workflow declares the triggers, concurrency, and permissions for the module repository, and delegates the work:
+The caller workflow declares the triggers, concurrency, and permissions for the module repository. Its production and
+pull-request jobs use the same reusable workflow and explicit secret mapping:
 
 ```yaml
 jobs:
-  Process-PSModule:
+  Process-PSModule-Production:
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@<commit-sha> # <version tag>
+    secrets:
+      PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
+      GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
+      GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
+
+  Process-PSModule-PullRequest:
     uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@<commit-sha> # <version tag>
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}

docs/content/specification/design.md

@@ -19,10 +19,9 @@ documented in [Workflow inputs](../reference/workflow-inputs.md).
 
 ### Trigger admission
 
-The [workflow trigger design](workflow-triggers/design.md) owns caller-level admission before processing: a retained
-production queue and replaceable pull-request activity. The caller's workflow-level group covers the complete reusable
-workflow call through its final enabled stage; the reusable workflow identifies closure and performs optional prerelease
-cleanup.
+The [workflow trigger design](workflow-triggers/design.md) owns caller admission before processing: a retained
+production queue and replaceable pull-request activity. The caller jobs cover each complete reusable-workflow call
+through its final enabled stage; the reusable workflow identifies closure and performs optional prerelease cleanup.
 
 ### Composed reusable workflows