Orchestrate reusable workflow GitHub operations through a GitHub App

[MariusStorhaug]

Maintainers need the reusable workflow to inspect repositories, resolve versions, create releases, manage prereleases, and provide pull-request feedback without depending on the default GitHub Actions token. The workflow must run these GitHub operations under a configured GitHub App identity with access limited to the repository and operation being performed.

Request

Desired experience

A caller can provide GitHub App credentials through a stable reusable-workflow contract, and all GitHub-dependent stages use short-lived installation tokens from that App. Callers retain control of their local secret names while the reusable workflow exposes one documented integration contract.

Acceptance criteria

• GitHub-dependent reusable-workflow stages authenticate with a GitHub App installation token rather than falling back to github.token
• Each token is limited to the triggering repository and to the minimum permissions for its stage
• Callers can map their local App credential secret names to the stable GitHubAppClientId and GitHubAppPrivateKey contract
• Version planning, repository metadata reads, releases, assets, prerelease cleanup, and pull-request comments use the App token
• Documentation explains the caller contract, App installation permissions, token scope, and Dependabot configuration

---

Technical decisions

Reusable workflow contract: Require GitHubAppClientId and GitHubAppPrivateKey at the root workflow_call boundary. Callers map their own repository or organization secrets explicitly; secrets: inherit is not used.

Token lifecycle: Mint a separate short-lived token in Plan, Build-Module, and Publish-Module through SHA-pinned actions/create-github-app-token. Pass the token only as step-scoped GH_TOKEN to actions that call GitHub.

Permission model: Install the App with Contents: write and Pull requests: write. Metadata: read is automatic. Minted tokens are limited to the triggering repository; Plan requests Contents read and Pull requests write, Build-Module requests Metadata read, and Publish-Module requests Contents write and Pull requests write.

Caller permissions: The caller workflow's permissions: block controls only github.token for non-App operations. It neither grants nor restricts the installation token.

Dependabot: Dependabot runs require the App credentials in the repository's Dependabot secret store because they cannot read Actions secrets. This is an explicit pre-review trust boundary.

External hardening: Named token-input handling in GitHub-Script remains tracked in PSModule/GitHub-Script#103.

---

Implementation plan

Reusable workflow authentication

• Add the generic GitHub App credential contract and propagate it to Plan, Build-Module, and Publish-Module
• Mint repository-scoped, minimum-permission installation tokens in each GitHub-dependent workflow
• Route settings, version resolution, repository metadata, publishing, releases, comments, and prerelease cleanup through step-scoped GH_TOKEN
• Remove github.token fallbacks from the GitHub App path

Caller guidance and documentation

• Update canonical caller templates and examples for the App credential contract
• Document the App installation permission baseline, per-stage token scopes, and the separate caller github.token permissions
• Document the Dependabot secret-store requirement

Validation

• Build the Process-PSModule documentation site

[MariusStorhaug]

Restructured the issue description to the MSX three-section format and made the GitHub App requirement implementation-neutral.

• Reframed the request around reusable-workflow orchestration instead of a specific App name
• Recorded the token scope, permission, and Dependabot decisions
• Marked the completed implementation and documentation work in the plan