Repository navigation
Agree the Process-PSModule caller workflow structure #514
Copy link
Copy link
Open
Description
Outcome
The Process-PSModule caller workflow structure is explicitly agreed before canonical guides, templates, or consumer repositories change. The inventory and candidate YAML provide evidence for the decision; they do not establish the standard by themselves.
Evidence
- Draft PR: ⚙️ [Maintenance]: Process-PSModule caller fleets can be audited consistently #515
- Current inventory: 60 default-branch caller workflows, with all dimensions captured in the generated fleet inventory.
- Candidate design:
docs/content/reference/process-workflow-fleet-standard.mdin PR ⚙️ [Maintenance]: Process-PSModule caller fleets can be audited consistently #515. - Agreed reference policy: controlled PSModule-owned automation may use a floating major tag such as
@v8; external automation remains full-SHA pinned.
Recommendations for review
These are recommendations, not decisions. The checklist below remains the approval record.
| Decision | Recommended candidate | Evidence and rationale |
|---|---|---|
| Identity | File, workflow, and job all use Process-PSModule. |
All 60 current callers use the same file and workflow identity; stable names simplify discovery and required checks. |
| Wrapper scope | Use the canonical workflow file exactly; repository-owned automation uses separate workflow files. | Keeps every fleet caller directly comparable. |
| Trigger ownership | Caller owns manual dispatch, scheduled health, default-branch push, and pull-request events. | GitHub requires caller-defined triggers; v8 stable releases depend on default-branch push while CI, prerelease, and cleanup depend on PR events. |
| Pull-request activities | closed, opened, reopened, synchronize, labeled, and unlabeled. |
The current fleet has the first five. unlabeled is needed so label removal is evaluated instead of leaving stale release intent. |
| Concurrency | `${{ github.workflow }}-${{ github.event.pull_request.number | |
| Permissions | Top-level permissions: {}; caller job grants contents: read, pages: write, and id-token: write. |
Use GITHUB_TOKEN for repository-local, non-user-facing checkout and Pages operations. Use scoped GitHub App tokens when the built-in boundary is insufficient and for all user-facing comments, labels, statuses, releases, and cleanup. |
| Fork behavior | No caller condition. Plan classifies fork PRs as restricted read-only validation and denies privileged capabilities. |
Centralizes execution policy while preserving safe fork build, lint, and test coverage. |
| Credentials | Explicitly map PSGALLERY_API_KEY, SHELLY_CLIENT_ID, and SHELLY_PRIVATE_KEY; optionally map TestData JSON for module-local tests. |
This is the v8 producer contract, avoids unrelated inheritance, and preserves the four observed test-data callers. |
| Optional surface | Permit only optional TestData under secrets. |
Every other field matches the canonical template exactly. |
Structural decisions to approve
- Contract scope: require the complete canonical
Process-PSModule.yml; repository-owned automation uses separate workflow files. - Trigger ownership: which of manual dispatch, schedule, default-branch push, and pull-request events belong in every caller.
- Pull-request activities: whether all of
closed,opened,reopened,synchronize,labeled, andunlabeledare mandatory. - Concurrency: use workflow plus PR number or full
github.ref; setcancel-in-progressto${{ github.event_name == 'pull_request' }}. - Permissions: default deny globally; grant the caller job
contents: read,pages: write, andid-token: write; use scoped GitHub App tokens for user-facing interactions and operations beyond the built-in token boundary. - Fork behavior: keep the caller unconditional; let
Planauthorize restricted fork validation while denying App tokens, publication, deployment, cleanup, and mutations. - Credentials: require the three explicit v8 mappings; allow optional
TestDataJSON with separatesecretsandvariablesmaps; do not usesecrets: inherit. - Optional surface:
TestDatais the only permitted variation from the canonical template. - Identity: final file, workflow, and job names used for discovery and stable checks.
Scope
- Inventory every default-branch workflow that calls
PSModule/Process-PSModule/.github/workflows/workflow.yml. - Record workflow identity, triggers, concurrency, permissions, reference, inputs, secrets, and extra jobs.
- Compare the evidence with the v8 producer contract.
- Record each approved structural decision and its rationale.
- Update canonical documentation only after the checklist above is resolved.
Non-goals
- Do not modify caller workflows across the fleet in this task.
- Do not treat the candidate YAML as approved merely because it appears in documentation or a draft PR.
- Do not start the rollout campaign until this issue records the agreed structure.
Acceptance criteria
- The complete current repository list and workflow metadata are documented.
- GitHub and local-checkout inventory refresh paths are tested.
- Every structural decision above has an explicit outcome.
- Required elements and optional variations use the approved outcomes rather than inferred commonality.
- Canonical guides and templates are updated only after approval.
- Campaign issue ⚙️ [Maintenance]: [process-v8-major-tag] Roll the v8 caller across the fleet #438 references the approved decision record.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels
Activity
[-]Define the Process-PSModule caller workflow standard[/-][+]Agree the Process-PSModule caller workflow structure[/+]MariusStorhaug commentedon Aug 15, 2026
Reusable workflow location is now confirmed: keep
PSModule/Process-PSModule/.github/workflows/workflow.yml@v8. A private cross-repository experiment with provider Actions access set touserfailed before job creation when the caller referenced a root-level file. GitHub returned:references to workflows must be rooted in '.github/workflows'. The workflow displayname:is not part of the reference.MariusStorhaug commentedon Aug 15, 2026
Credential mapping is selected. The common caller maps the three v8 credentials explicitly.
TestDatais the only approved optional secret mapping so modules can supply the documented JSONsecrets/variablesenvelope to module-local tests. Callers omit it when unused.with.Debug: trueis not part of the conforming caller surface; Debug keeps its reusable-workflow default offalse.MariusStorhaug commentedon Aug 15, 2026
Caller-template rule is locked: replace
.github/workflows/Process-PSModule.ymlwith the canonical template. The only permitted difference is optionalTestDataundersecrets. Repository-owned automation belongs in separate workflow files.