diff --git a/.github/scripts/pr-package-comment.cjs b/.github/scripts/pr-package-comment.cjs new file mode 100644 index 0000000..36397ae --- /dev/null +++ b/.github/scripts/pr-package-comment.cjs @@ -0,0 +1,94 @@ +const marker = ''; + +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}.`); + } + } +}; diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 967afe4..218bca8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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: | @@ -26,16 +33,24 @@ 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 @@ -43,6 +58,8 @@ jobs: 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 @@ -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 diff --git a/.github/workflows/pr-packages.yml b/.github/workflows/pr-packages.yml new file mode 100644 index 0000000..feee671 --- /dev/null +++ b/.github/workflows/pr-packages.yml @@ -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 }); diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6ca3a38..88490ae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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). diff --git a/README.md b/README.md index 676619d..d8cffd2 100644 --- a/README.md +++ b/README.md @@ -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 @@ -45,6 +47,36 @@ pwsh .\eng\Validate-Plugin.ps1 -Plugin ' + Invoke-FixtureGit add . + Invoke-FixtureGit -c user.name=CI -c user.email=ci@example.invalid commit --quiet -m shared + $head = (Invoke-FixtureGit rev-parse HEAD).Trim() + if ((& $fixtureScript -BaseCommit $base -HeadCommit $head) -cne $allJson) { + throw 'Real shared-file diffs must select every component.' + } + $previousExitCode = $global:LASTEXITCODE + try { + & $fixtureScript -BaseCommit ('0' * 40) -HeadCommit $head 2>$null + throw 'A missing git commit was accepted.' + } + catch { + if ($_.Exception.Message -notmatch 'Could not determine PR changes') { throw } + } + finally { + $global:LASTEXITCODE = $previousExitCode + } +} +finally { + Remove-Item -LiteralPath $fixture -Recurse -Force +} +Write-Output 'CI impact selection tests passed.' diff --git a/eng/pr-package-comment.test.cjs b/eng/pr-package-comment.test.cjs new file mode 100644 index 0000000..46205d7 --- /dev/null +++ b/eng/pr-package-comment.test.cjs @@ -0,0 +1,168 @@ +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const { readFileSync } = require('node:fs'); +const { join } = require('node:path'); +const commentPackages = require('../.github/scripts/pr-package-comment.cjs'); + +function fixture() { + const run = { + id: 100, run_attempt: 2, workflow_id: 7, event: 'pull_request', status: 'completed', + conclusion: 'success', head_sha: 'a'.repeat(40), head_branch: 'feature', + repository: { full_name: 'LANCommander/LANCommander.Community' }, + head_repository: { id: 22 }, pull_requests: [{ number: 42 }], + }; + const pull = { + number: 42, state: 'open', base: { repo: run.repository }, + head: { sha: run.head_sha, ref: run.head_branch, repo: run.head_repository }, + }; + const state = { + run, pull, workflowPath: '.github/workflows/ci.yml', recent: [], + artifacts: [{ name: 'pr-package-Server.Mcp-100-2', id: 10, expired: false }], + comments: [], associated: [pull], writes: [], warnings: [], summaries: [], info: [], + }; + const github = { + rest: { + actions: { + getWorkflowRun: async () => ({ data: state.run }), + getWorkflow: async () => ({ data: { path: state.workflowPath } }), + listWorkflowRuns: async () => ({ data: { workflow_runs: state.recent } }), + listWorkflowRunArtifacts: 'artifacts', + }, + repos: { listPullRequestsAssociatedWithCommit: 'associated' }, + pulls: { + get: async () => { + state.getPullCount = (state.getPullCount || 0) + 1; + return { data: state.getPullCount > 1 && state.changedPull ? state.changedPull : state.pull }; + }, + }, + issues: { + listComments: 'comments', + createComment: async request => { + if (state.writeError) throw state.writeError; + state.writes.push({ operation: 'create', ...request }); + }, + updateComment: async request => state.writes.push({ operation: 'update', ...request }), + }, + }, + paginate: async method => state[method], + }; + const context = { + repo: { owner: 'LANCommander', repo: 'LANCommander.Community' }, + payload: { workflow_run: { id: 100, run_attempt: 2 } }, + }; + const core = { + info: message => state.info.push(message), + warning: message => state.warnings.push(message), + summary: { addRaw: body => ({ write: async () => state.summaries.push(body) }) }, + }; + return { state, execute: () => commentPackages({ github, context, core }) }; +} + +test('links current-attempt packages without reading or executing artifact contents', async () => { + const { state, execute } = fixture(); + state.artifacts.push( + { name: 'pr-package-Launcher.MQTT-100-2', id: 11 }, + { name: 'pr-package-Server.Mcp-100-1', id: 12 }, + { name: 'pr-package-Server.Mcp-99-2', id: 13 }, + { name: 'pr-package-Server.Quake3-100-2', id: 14, expired: true }, + { name: 'pr-package-[click](javascript:bad)-100-2', id: 15 }, + { name: 'release-manifest.json', id: 16 }, + ); + await execute(); + assert.equal(state.writes.length, 1); + const { body } = state.writes[0]; + assert.match(body, /actions\/runs\/100\/artifacts\/10/); + assert.match(body, /actions\/runs\/100\/artifacts\/11/); + assert.doesNotMatch(body, /artifacts\/(12|13|14|15|16)/); + assert.match(body, /Untrusted PR builds/); + assert.match(body, /7 days/); + assert.equal(state.summaries[0], body); +}); + +test('forks with no run PR metadata resolve via commit and verify live head repository', async () => { + const { state, execute } = fixture(); + state.run.pull_requests = []; + await execute(); + assert.equal(state.writes.length, 1); +}); + +for (const reason of ['head SHA', 'head repository', 'head branch', 'base repository', 'closed PR']) { + test(`does not comment on a mismatched ${reason}`, async () => { + const { state, execute } = fixture(); + if (reason === 'head SHA') state.pull.head.sha = 'b'.repeat(40); + if (reason === 'head repository') state.pull.head.repo = { id: 999 }; + if (reason === 'head branch') state.pull.head.ref = 'other'; + if (reason === 'base repository') state.pull.base.repo = { full_name: 'other/repository' }; + if (reason === 'closed PR') state.pull.state = 'closed'; + await execute(); + assert.equal(state.writes.length, 0); + }); +} + +test('does not overwrite comments after PR head moves during API reads', async () => { + const { state, execute } = fixture(); + state.changedPull = { ...state.pull, head: { ...state.pull.head, sha: 'b'.repeat(40) } }; + await execute(); + assert.equal(state.writes.length, 0); +}); + +test('updates only its own marked bot comment, not user content', async () => { + const { state, execute } = fixture(); + state.comments = [ + { id: 1, user: { login: 'contributor' }, body: '' }, + { id: 2, user: { login: 'github-actions[bot]' }, body: ' old links' }, + ]; + await execute(); + assert.equal(state.writes[0].operation, 'update'); + assert.equal(state.writes[0].comment_id, 2); +}); + +for (const reason of ['newer run', 'newer attempt', 'wrong event']) { + test(`skips ${reason}`, async () => { + const { state, execute } = fixture(); + if (reason === 'newer run') state.recent = [{ id: 101 }]; + if (reason === 'newer attempt') state.run.run_attempt = 3; + if (reason === 'wrong event') state.run.event = 'push'; + await execute(); + assert.equal(state.writes.length, 0); + }); +} + +test('rejects runs from an unexpected workflow', async () => { + const { state, execute } = fixture(); + state.workflowPath = '.github/workflows/other.yml'; + await assert.rejects(execute, /only describe the repository CI/); +}); + +test('failed or documentation-only attempts explicitly replace stale download links', async () => { + const { state, execute } = fixture(); + state.run.conclusion = 'failure'; + state.artifacts = []; + await execute(); + assert.match(state.writes[0].body, /\*\*failure\*\*/); + assert.match(state.writes[0].body, /No downloadable packages/); +}); + +test('comment permission failures warn and preserve summary download links', async () => { + const { state, execute } = fixture(); + state.writeError = { status: 403 }; + await execute(); + assert.equal(state.warnings.length, 1); + assert.match(state.warnings[0], /comment unavailable \(403\)/); + assert.match(state.summaries[0], /artifacts\/10/); +}); + +test('unexpected API failures are not suppressed', async () => { + const { state, execute } = fixture(); + state.writeError = new Error('API unavailable'); + state.writeError.status = 500; + await assert.rejects(execute, /API unavailable/); +}); + +test('privileged workflow checks out only its own trusted commit and grants no publishing permissions', () => { + const workflow = readFileSync(join(__dirname, '../.github/workflows/pr-packages.yml'), 'utf8'); + assert.match(workflow, /workflow_run:/); + assert.match(workflow, /ref: \$\{\{ github\.workflow_sha \}\}/); + assert.match(workflow, /persist-credentials: false/); + assert.doesNotMatch(workflow, /pull_request_target|download-artifact|secrets\.|contents: write|packages: write/); +}); diff --git a/plugins/Server.RecompCatalog/README.md b/plugins/Server.RecompCatalog/README.md index a58b723..965d2cc 100644 --- a/plugins/Server.RecompCatalog/README.md +++ b/plugins/Server.RecompCatalog/README.md @@ -84,8 +84,8 @@ checksum. Host assemblies are compile-time references, not bundled dependencies. dotnet pack .\plugins\Server.RecompCatalog\LANCommander.Community.Server.RecompCatalog\LANCommander.Community.Server.RecompCatalog.csproj -c Release -o artifacts ``` -Pull request CI validates all components. A component tag publishes this -package to the repository's GitHub Release and GitHub Packages NuGet feed. +Pull request CI validates impacted components (all components for shared changes). +A component tag publishes this package to the repository's GitHub Release and GitHub Packages NuGet feed. NuGet.org publication is also automatic when the repository `NUGET_API_KEY` secret is configured. See the repository's [plugin release procedure](../../RELEASES.md) for eligibility, permissions, and retry behavior.