Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions .github/scripts/pr-package-comment.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
const marker = '<!-- community-pr-packages -->';

module.exports = async function commentPackages({ github, context, core }) {
const { owner, repo } = context.repo;
const repository = `${owner}/${repo}`;
const eventRun = context.payload.workflow_run;
const { data: run } = await github.rest.actions.getWorkflowRun({ owner, repo, run_id: eventRun.id });
if (run.event !== 'pull_request' || run.status !== 'completed' ||
run.repository.full_name !== repository || run.run_attempt !== eventRun.run_attempt) {
core.info('Ignoring an unrelated or superseded workflow run.');
return;
}
const { data: workflow } = await github.rest.actions.getWorkflow({ owner, repo, workflow_id: run.workflow_id });
if (workflow.path !== '.github/workflows/ci.yml') {
throw new Error('Package comments may only describe the repository CI workflow.');
}
const { data: recent } = await github.rest.actions.listWorkflowRuns({
owner, repo, workflow_id: run.workflow_id, event: 'pull_request', head_sha: run.head_sha, per_page: 100,
});
if (recent.workflow_runs.some(candidate => candidate.id > run.id)) {
core.info('A newer CI run already covers this commit.');
return;
}
// Fork runs can have an empty pull_requests array. Resolve via the commit API,
// then verify against the live PR; never accept a PR number from an artifact.
const candidates = run.pull_requests.length ? run.pull_requests :
await github.paginate(github.rest.repos.listPullRequestsAssociatedWithCommit, {
owner, repo, commit_sha: run.head_sha, per_page: 100,
});
const pulls = [];
for (const candidate of candidates) {
const { data: pull } = await github.rest.pulls.get({ owner, repo, pull_number: candidate.number });
if (pull.state === 'open' && pull.base.repo.full_name === repository &&
pull.head.sha === run.head_sha && pull.head.ref === run.head_branch &&
pull.head.repo?.id === run.head_repository.id) {
pulls.push(pull);
}
}
if (!pulls.length) {
core.info('No open PR still matches this run head; leaving comments unchanged.');
return;
}
const artifacts = await github.paginate(github.rest.actions.listWorkflowRunArtifacts, {
owner, repo, run_id: run.id, per_page: 100,
});
const packages = artifacts.flatMap(artifact => {
const match = /^pr-package-((?:Server|Launcher)\.[A-Za-z][A-Za-z0-9]*)-([0-9]+)-([0-9]+)$/.exec(artifact.name);
return match && match[2] === String(run.id) && match[3] === String(run.run_attempt) && !artifact.expired ?
[{ component: match[1], id: artifact.id }] : [];
}).sort((a, b) => a.component.localeCompare(b.component));
const server = process.env.GITHUB_SERVER_URL || 'https://github.com';
const runUrl = `${server}/${repository}/actions/runs/${run.id}`;
const lines = [
marker, '### PR plugin packages',
`Commit \`${run.head_sha}\` · [CI run ${run.id}, attempt ${run.run_attempt}](${runUrl}) · **${run.conclusion}**`,
'',
...packages.map(pkg => `- [${pkg.component}: download package ZIP](${runUrl}/artifacts/${pkg.id})`),
...(packages.length ? [
'',
'Each ZIP contains the `.nupkg`, SHA-256 sidecar and build manifest. Extract it before installing.',
'Artifacts expire after 7 days and downloading requires GitHub sign-in and repository access.',
'**Untrusted PR builds, not published releases.** Versions are unchanged; do not install over a trusted release without a backup.',
] : [
'No downloadable packages were produced by this attempt (documentation-only, failed, cancelled, or expired). See the CI run for details.',
]),
'',
'Direct download links are also available in the CI job summaries when PR comments are restricted.',
];
const body = lines.join('\n');
await core.summary.addRaw(body).write();
for (const pull of pulls) {
try {
const comments = await github.paginate(github.rest.issues.listComments, {
owner, repo, issue_number: pull.number, per_page: 100,
});
const existing = comments.find(comment =>
comment.user?.login === 'github-actions[bot]' && comment.body?.startsWith(marker));
// Recheck the live head immediately before writing, as the PR may have moved during API reads.
const { data: current } = await github.rest.pulls.get({ owner, repo, pull_number: pull.number });
if (current.state !== 'open' || current.head.sha !== run.head_sha) {
core.info('PR changed while resolving packages; skipping stale comment.');
continue;
}
if (existing) {
await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
} else {
await github.rest.issues.createComment({ owner, repo, issue_number: pull.number, body });
}
} catch (error) {
if (error.status !== 403 && error.status !== 404) throw error;
core.warning(`PR #${pull.number} comment unavailable (${error.status}); download packages from ${runUrl}.`);
}
}
};
44 changes: 40 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,18 @@ jobs:
runs-on: ubuntu-latest
outputs:
plugins: ${{ steps.registry.outputs.plugins }}
has_plugins: ${{ steps.registry.outputs.has_plugins }}
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
fetch-depth: 0
persist-credentials: false
- uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4.3.1
with:
dotnet-version: 10.0.x
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
with:
node-version: 22
- name: Validate release selection and repository metadata
shell: pwsh
run: |
Expand All @@ -26,23 +33,33 @@ jobs:
./eng/Test-ReleaseDestinations.ps1
./eng/Test-NuGetPublication.ps1
./eng/Test-GitHubPackages.ps1
- name: Select registered components
./eng/Test-CISelection.ps1
- name: Test PR artifact commenting
run: node --test eng/pr-package-comment.test.cjs
- name: Select impacted components
id: registry
shell: pwsh
env:
PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
run: |
Import-Module ./eng/PluginRelease.psm1 -Force
$plugins = ConvertTo-Json -InputObject @(Get-PluginRegistry | ForEach-Object key) -Compress
$plugins = ./eng/Resolve-CISelection.ps1 -BaseCommit $env:PR_BASE_SHA -HeadCommit $env:PR_HEAD_SHA
"plugins=$plugins" >> $env:GITHUB_OUTPUT
"has_plugins=$(@($plugins | ConvertFrom-Json).Count -gt 0)".ToLowerInvariant() >> $env:GITHUB_OUTPUT
if ($plugins -eq '[]') { 'Documentation-only change: no plugin packages required.' >> $env:GITHUB_STEP_SUMMARY }

validate:
needs: repository
if: needs.repository.outputs.has_plugins == 'true'
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
plugin: ${{ fromJSON(needs.repository.outputs.plugins) }}
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
persist-credentials: false
- uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4.3.1
with:
dotnet-version: 10.0.x
Expand All @@ -58,4 +75,23 @@ jobs:
run: python -m pip install -r plugins/Launcher.MQTT/tests/ha-template-requirements.txt
- name: Validate ${{ matrix.plugin }}
shell: pwsh
run: ./eng/Validate-Plugin.ps1 -Plugin '${{ matrix.plugin }}' -OutputDirectory (Join-Path $env:RUNNER_TEMP 'community-plugin-artifacts')
env:
CI_PLUGIN: ${{ matrix.plugin }}
run: ./eng/Validate-Plugin.ps1 -Plugin $env:CI_PLUGIN -OutputDirectory (Join-Path $env:RUNNER_TEMP 'community-plugin-artifacts')
- if: github.event_name == 'pull_request'
name: Upload checked PR package
id: package
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: pr-package-${{ matrix.plugin }}-${{ github.run_id }}-${{ github.run_attempt }}
path: ${{ runner.temp }}/community-plugin-artifacts/
if-no-files-found: error
retention-days: 7
- if: github.event_name == 'pull_request'
name: Link package download
shell: pwsh
env:
CI_PLUGIN: ${{ matrix.plugin }}
ARTIFACT_URL: ${{ steps.package.outputs.artifact-url }}
run: |
"[$env:CI_PLUGIN package download]($env:ARTIFACT_URL) (expires after 7 days; PR code is untrusted)." >> $env:GITHUB_STEP_SUMMARY
29 changes: 29 additions & 0 deletions .github/workflows/pr-packages.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
name: PR package downloads

on:
workflow_run:
workflows: [CI]
types: [completed]

permissions: {}

jobs:
comment:
if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.repository.full_name == github.repository
runs-on: ubuntu-latest
permissions:
actions: read
contents: read
pull-requests: write
steps:
# Only load tooling from the commit containing this trusted workflow, never the PR.
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
ref: ${{ github.workflow_sha }}
persist-credentials: false
sparse-checkout: .github/scripts
- uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
with:
script: |
const comment = require('./.github/scripts/pr-package-comment.cjs');
await comment({ github, context, core });
4 changes: 4 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,10 @@ keep component-specific packaging and host runtime exclusions in their projects.
the CI matrix, and release selection. New components do not need a copied CI
matrix entry or release job. The generic component tag trigger still fails closed
on unknown prefixes, mismatched versions, and commits not reachable from `main`.
PR impact selection is conservative for shared or unknown paths; keep its
regressions in `eng/Test-CISelection.ps1` current when classifying a new docs-only
area. See [PR packages](README.md#pull-request-packages) for download links,
fork behavior and commenting prerequisites.

Before submitting changes, run the repository checks and the validation
command(s) for affected components from the root [README](README.md#build-and-validate).
Expand Down
32 changes: 32 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ pwsh .\eng\Test-Repository.ps1
pwsh .\eng\Test-ReleaseDestinations.ps1
pwsh .\eng\Test-NuGetPublication.ps1
pwsh .\eng\Test-GitHubPackages.ps1
pwsh .\eng\Test-CISelection.ps1
node --test .\eng\pr-package-comment.test.cjs
```

Validate a single plugin and create its local install artifact with
Expand All @@ -45,6 +47,36 @@ pwsh .\eng\Validate-Plugin.ps1 -Plugin <Server.Mcp|Server.RecompCatalog|Launcher
The output directory must not already exist. See each plugin README for its
focused build, test, and installation instructions.

## Pull request packages

PR CI validates and packages impacted plugins. Component changes (including
packaged READMEs) select that component; shared build, dependency, tooling,
workflow, registry, source-pin, and unclassified changes select all components.
Root documentation, `docs/`, and agent-skill-only changes do not produce packages.
Pushes to `main` continue to validate every registered plugin.

Download a ZIP from the **PR plugin packages** comment, or from the CI run's
**Artifacts** / job-summary links. Extract it to get the `.nupkg`, SHA-256 sidecar
and build manifest. Artifacts expire after seven days; GitHub sign-in and
repository access are required. Failed attempts can provide packages for
components that finished validation; the comment shows the overall run result.
Versions remain component-owned and unchanged: these are **untrusted PR builds,
not releases**, and nothing is published to a feed. Back up installed plugin data
before trying one; do not assume same-version packages are interchangeable.

Fork PRs use the same read-only build workflow, without repository secrets.
GitHub may require a maintainer to approve a fork's first run. A separate
`workflow_run` workflow posts or updates the comment using only artifact metadata
and tooling from its own trusted default-branch commit. It never downloads,
extracts or executes PR artifacts. It verifies the current PR head/repository
and excludes stale attempts. If commenting is denied, it reports a warning and
the CI artifact/job-summary downloads remain available.

The comment workflow must first exist on the default branch. Until this change
is merged, package links are available from the PR's CI run rather than an
automatic comment. Commenting also depends on Actions being allowed to request
`pull-requests: write`; no PAT or additional secret is needed.

## Repository guidance

- [Contributing](CONTRIBUTING.md) — shared project conventions and contributor
Expand Down
24 changes: 23 additions & 1 deletion eng/PluginRelease.psm1
Original file line number Diff line number Diff line change
Expand Up @@ -160,4 +160,26 @@ function Resolve-PluginSelection {
return @($selected.ToArray())
}

Export-ModuleMember -Function Assert-PluginComponentIdentity, Assert-ReleaseSourceCheckout, Assert-ReleaseWorkflowContext, Get-PluginRegistry, Get-PluginVersion, Resolve-PluginSelection, Test-PluginSemVer
function Get-ImpactedPlugins {
param([Parameter(Mandatory)][AllowEmptyCollection()][string[]] $ChangedPaths)

$registry = @(Get-PluginRegistry)
$selected = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)
foreach ($path in $ChangedPaths) {
$normalized = $path.Replace('\', '/')
$component = @($registry | Where-Object { $normalized.StartsWith("plugins/$($_.key)/", [StringComparison]::Ordinal) })
if ($component.Count -eq 1) {
$null = $selected.Add($component[0].key)
}
elseif ($normalized -cmatch '^(README|CONTRIBUTING|RELEASES)\.md$|^\.github/skills/|^docs/') {
continue
}
else {
# Unknown paths are shared until explicitly classified, never silently skipped.
return @($registry | ForEach-Object key)
}
}
return @($registry | Where-Object { $selected.Contains($_.key) } | ForEach-Object key)
}

Export-ModuleMember -Function Assert-PluginComponentIdentity, Assert-ReleaseSourceCheckout, Assert-ReleaseWorkflowContext, Get-ImpactedPlugins, Get-PluginRegistry, Get-PluginVersion, Resolve-PluginSelection, Test-PluginSemVer
20 changes: 20 additions & 0 deletions eng/Resolve-CISelection.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
[CmdletBinding()]
param(
[string] $BaseCommit,
[string] $HeadCommit
)

$ErrorActionPreference = 'Stop'
Import-Module (Join-Path $PSScriptRoot 'PluginRelease.psm1') -Force
if ($BaseCommit -or $HeadCommit) {
if ($BaseCommit -cnotmatch '^[0-9a-f]{40}$' -or $HeadCommit -cnotmatch '^[0-9a-f]{40}$') {
throw 'PR selection requires both exact base and head commit SHAs.'
}
$paths = @(& git -C (Split-Path $PSScriptRoot -Parent) diff --name-only --no-renames "$BaseCommit...$HeadCommit" --)
if ($LASTEXITCODE -ne 0) { throw 'Could not determine PR changes; refusing an incomplete package selection.' }
$plugins = @(Get-ImpactedPlugins -ChangedPaths $paths)
}
else {
$plugins = @(Get-PluginRegistry | ForEach-Object key)
}
ConvertTo-Json -InputObject $plugins -Compress
Loading
Loading