diff --git a/.github/labeler.yml b/.github/labeler.yml deleted file mode 100644 index 97d707a4..00000000 --- a/.github/labeler.yml +++ /dev/null @@ -1,30 +0,0 @@ -root: -- changed-files: - - any-glob-to-any-file: '*' - -Configuration File: -- changed-files: - - any-glob-to-any-file: configurationFiles/** - -Executable: -- changed-files: - - any-glob-to-any-file: src/** - -Kusto Query Language: -- changed-files: - - any-glob-to-any-file: kusto/** - -WorkFlow: -- changed-files: - - any-glob-to-any-file: .github/** - -documentation: -- changed-files: - - any-glob-to-any-file: - - docs/*.* - - README.md - - CHANGELOG.md - -scripts: -- changed-files: - - any-glob-to-any-file: scripts/*.* \ No newline at end of file diff --git a/.github/tests/release-policy.test.cjs b/.github/tests/release-policy.test.cjs new file mode 100644 index 00000000..f4454cc3 --- /dev/null +++ b/.github/tests/release-policy.test.cjs @@ -0,0 +1,144 @@ +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); +const test = require('node:test'); +const vm = require('node:vm'); + +const workflow = fs.readFileSync( + path.join(__dirname, '..', 'workflows', 'workflow.yml'), + 'utf8' +); +const scriptMatch = workflow.match( + / script: \|\r?\n((?: [^\r\n]*(?:\r?\n|$))*)/ +); +assert.ok(scriptMatch, 'The release policy script must exist in the workflow.'); +const script = scriptMatch[1].replace(/^ {12}/gm, ''); + +test('no workflow uses pull_request_target and the labeler is removed', () => { + const workflowDirectory = path.join(__dirname, '..', 'workflows'); + for (const file of fs.readdirSync(workflowDirectory)) { + if (/\.ya?ml$/i.test(file)) { + const content = fs.readFileSync(path.join(workflowDirectory, file), 'utf8'); + assert.doesNotMatch(content, /\bpull_request_target\b/, file); + } + } + assert.equal(fs.existsSync(path.join(workflowDirectory, 'labeler.yml')), false); + assert.equal(fs.existsSync(path.join(__dirname, '..', 'labeler.yml')), false); +}); + +function mergedPullRequest(overrides = {}) { + return { + merged_at: '2026-10-19T12:00:00Z', + merge_commit_sha: 'trusted-commit', + base: { repo: { id: 123 }, ref: 'main' }, + labels: [{ name: 'Release' }], + ...overrides + }; +} + +async function evaluate(pullRequests, { branch = 'main', apiError } = {}) { + const outputs = {}; + const endpoint = Symbol('listPullRequestsAssociatedWithCommit'); + const context = { + repo: { owner: 'microsoft', repo: 'CollectServiceFabricData' }, + sha: 'trusted-commit', + ref: `refs/heads/${branch}`, + payload: { repository: { id: 123 } } + }; + const github = { + rest: { repos: { listPullRequestsAssociatedWithCommit: endpoint } }, + paginate: async (method, options) => { + assert.equal(method, endpoint); + assert.deepEqual({ ...options }, { + ...context.repo, + commit_sha: context.sha, + per_page: 100 + }); + if (apiError) { + throw apiError; + } + return pullRequests; + } + }; + await vm.runInNewContext(`(async () => {\n${script}\n})()`, { + github, + context, + core: { + setOutput: (name, value) => { + outputs[name] = value; + } + } + }); + return outputs; +} + +test('a Release-labelled merge publishes a stable release', async () => { + assert.deepEqual(await evaluate([mergedPullRequest()]), { + publish: true, + prerelease: false + }); +}); + +test('a Pre-release-labelled merge publishes a prerelease', async () => { + const pr = mergedPullRequest({ labels: [{ name: 'Pre-release' }] }); + assert.deepEqual(await evaluate([pr]), { publish: true, prerelease: true }); +}); + +test('Pre-release takes precedence when both labels are present', async () => { + const pr = mergedPullRequest({ + labels: [{ name: 'Release' }, { name: 'Pre-release' }] + }); + assert.deepEqual(await evaluate([pr]), { publish: true, prerelease: true }); +}); + +test('a fork PR can release only after its merge matches the trusted push', async () => { + const pr = mergedPullRequest({ + head: { repo: { id: 456 }, sha: 'untrusted-head' } + }); + assert.equal((await evaluate([pr])).publish, true); + pr.merge_commit_sha = 'untrusted-head'; + assert.equal((await evaluate([pr])).publish, false); +}); + +test('master merges are supported', async () => { + const pr = mergedPullRequest({ base: { repo: { id: 123 }, ref: 'master' } }); + assert.equal((await evaluate([pr], { branch: 'master' })).publish, true); +}); + +for (const [name, pullRequests] of [ + ['direct push', []], + ['unlabelled merge', [mergedPullRequest({ labels: [] })]], + ['unrelated label', [mergedPullRequest({ labels: [{ name: 'documentation' }] })]], + ['case-mismatched release label', [mergedPullRequest({ labels: [{ name: 'release' }] })]], + ['open or unmerged PR', [mergedPullRequest({ merged_at: null })]], + ['different merge commit', [mergedPullRequest({ merge_commit_sha: 'older-commit' })]], + ['different base repository', [mergedPullRequest({ base: { repo: { id: 456 }, ref: 'main' } })]], + ['different base branch', [mergedPullRequest({ base: { repo: { id: 123 }, ref: 'master' } })]] +]) { + test(`${name} does not publish`, async () => { + assert.deepEqual(await evaluate(pullRequests), { + publish: false, + prerelease: false + }); + }); +} + +test('only the merged PR matching the pushed tip determines labels', async () => { + const older = mergedPullRequest({ merge_commit_sha: 'older-commit' }); + const tip = mergedPullRequest({ labels: [] }); + assert.equal((await evaluate([older, tip])).publish, false); +}); + +test('ambiguous merged PR matches fail explicitly', async () => { + await assert.rejects( + evaluate([mergedPullRequest(), mergedPullRequest()]), + /Multiple merged pull requests/ + ); +}); + +test('GitHub API failures fail explicitly', async () => { + await assert.rejects( + evaluate([], { apiError: new Error('GitHub API unavailable') }), + /GitHub API unavailable/ + ); +}); diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml deleted file mode 100644 index ab831610..00000000 --- a/.github/workflows/labeler.yml +++ /dev/null @@ -1,16 +0,0 @@ -# workflows do not have same permissions across forks pr. from same repo (branch to branch) -# labeler cant write across forks https://github.com/actions/labeler/issues/12 -# but has now been fixed https://github.blog/2020-08-03-github-actions-improvements-for-fork-and-pull-request-workflows/ -name: Labeler -on: [pull_request_target] - -jobs: - label: - permissions: - contents: read - pull-requests: write - runs-on: windows-latest - steps: - - uses: actions/labeler@8558fd74291d67161a8a78ce36a881fa63b766a9 # v5.0.0 - with: - repo-token: "${{ secrets.GITHUB_TOKEN }}" \ No newline at end of file diff --git a/.github/workflows/workflow.yml b/.github/workflows/workflow.yml index 54462ce5..3d9c0ed1 100644 --- a/.github/workflows/workflow.yml +++ b/.github/workflows/workflow.yml @@ -6,11 +6,10 @@ env: artifacts_path: ${{ github.workspace }}\\src\\bin\\artifacts release_path: ${{ github.workspace }}\\src\\bin\\Release release_config: ${{ github.workspace }}\\configurationFiles\\collectsfdata.options.json - github_owner: ${{ github.event.repository.owner.name }} on: - pull_request_target: - types: [closed, opened] + pull_request: + types: [opened, synchronize, reopened] paths-ignore: - "docs/**" - "configurationFiles/**" @@ -18,18 +17,36 @@ on: branches: - master - main + push: + paths-ignore: + - "docs/**" + - "configurationFiles/**" + - "kusto/**" + branches: + - master + - main + +permissions: {} jobs: build: + permissions: + contents: read runs-on: windows-latest + timeout-minutes: 30 steps: - name: checkout uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 + with: + persist-credentials: false + + - name: Validate release policy + shell: cmd + run: node --test .github\tests\release-policy.test.cjs - name: environment shell: cmd run: | - set dotnet --info dotnet nuget locals all --clear @@ -48,20 +65,18 @@ jobs: - name: dotnet build / pack shell: cmd run: | - set dotnet build %project_root%\%project_name%\%project_name%.csproj -v detailed -c Release + if errorlevel 1 exit /b %errorlevel% dir - name: build output shell: cmd run: | - set dir /s - name: copy artifacts shell: powershell run: | - [environment]::GetEnvironmentVariables() write-host "copy "$($env:release_path)" "$($env:artifacts_path)" -recurse -force" copy "$($env:release_path)" "$($env:artifacts_path)" -recurse -force write-host "copy "$($env:release_config)" "$($env:artifacts_path)" -recurse -force" @@ -77,23 +92,51 @@ jobs: with: name: Release path: ${{ env.artifacts_path }} + if-no-files-found: error + + release_metadata: + if: github.event_name == 'push' + runs-on: windows-latest + timeout-minutes: 5 + permissions: + contents: read + pull-requests: read + outputs: + publish: ${{ steps.release_policy.outputs.publish }} + prerelease: ${{ steps.release_policy.outputs.prerelease }} + steps: + - name: Check merged pull request release labels + id: release_policy + uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7 + with: + script: | + const pullRequests = await github.paginate( + github.rest.repos.listPullRequestsAssociatedWithCommit, + { ...context.repo, commit_sha: context.sha, per_page: 100 } + ); + const branch = context.ref.replace(/^refs\/heads\//, ''); + const mergedPullRequests = pullRequests.filter(pr => + pr.merged_at && + pr.merge_commit_sha === context.sha && + pr.base.repo.id === context.payload.repository.id && + pr.base.ref === branch + ); + if (mergedPullRequests.length > 1) { + throw new Error('Multiple merged pull requests match the pushed commit.'); + } + const labels = mergedPullRequests[0]?.labels.map(label => label.name) ?? []; + core.setOutput('publish', labels.includes('Release') || labels.includes('Pre-release')); + core.setOutput('prerelease', labels.includes('Pre-release')); release: - if: success() && github.event.pull_request.merged == true && github.event.action == 'closed' && (contains(github.event.pull_request.labels.*.name, 'Release') || contains(github.event.pull_request.labels.*.name, 'Pre-release')) - needs: build + if: github.event_name == 'push' && needs.release_metadata.outputs.publish == 'true' + needs: [build, release_metadata] runs-on: windows-latest + timeout-minutes: 10 permissions: contents: write - packages: write steps: - - name: checkout - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 - - - name: environment - shell: cmd - run: set - - name: download artifact uses: actions/download-artifact@65a9edc5881444af0b9093a5e628f2fe47ea3b2e # v4.1.7 with: @@ -130,8 +173,6 @@ jobs: echo "file_version=v$fileVersion" >> $env:GITHUB_OUTPUT write-host "dir $env:release_path -recurse" dir $env:release_path -recurse - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # https://github.com/marketplace/actions/gh-release - name: create release @@ -142,8 +183,9 @@ jobs: **/${{ env.project_name }}.zip **/*${{ env.project_name }}*.nupkg tag_name: ${{ steps.prepare_release_asset.outputs.file_version }} + target_commitish: ${{ github.sha }} name: ${{ env.project_name }} draft: false - token: ${{ secrets.GITHUB_TOKEN }} - prerelease: ${{ contains(github.event.pull_request.labels.*.name, 'Pre-release') }} + token: ${{ github.token }} + prerelease: ${{ needs.release_metadata.outputs.prerelease == 'true' }} generate_release_notes: true diff --git a/docs/contributing.md b/docs/contributing.md index 3de32af1..693c02d0 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -4,6 +4,42 @@ To report issue with collectsfdata, create a new issue in github repo [new issue](https://github.com/microsoft/CollectServiceFabricData/issues/new/choose) +## GitHub Actions and event policy + +[CI CollectSFData](../.github/workflows/workflow.yml) builds pull requests targeting +`main` or `master` on opening, reopening, and subsequent updates with a read-only +contents token and no persisted checkout credentials. The existing documentation, +configuration, and Kusto path exclusions still apply. + +Pushes to `main` or `master` build the exact pushed commit independently of PR +artifacts. A release is published only after that build succeeds and the GitHub +API identifies a merged PR whose merge commit, base repository, and base branch +match the push. The PR must have the `Release` or `Pre-release` label at the time +of the metadata check; `Pre-release` takes precedence if both labels are present. +Direct pushes and unlabelled merges build without publishing. Set release labels +before merging. Squash, merge-commit, and rebase merges rely on GitHub reporting +the pushed commit as the PR's merge commit. Pushes containing multiple merges +consider only the PR matching the pushed tip. + +Only the release job receives `contents: write`. It downloads artifacts from its +own trusted push run, never from a pull request run, and targets the pushed commit +when creating a release tag. + +Automatic PR labeling has been removed. Maintainers apply labels manually. +No workflow uses `pull_request_target`, so the November 2, 2026 restriction on +that event does not require a workflow exception, JIT administrator action, or +the exception-specific CodeQL/security approval process. This does not waive +any other repository security requirements. The changes must be merged into +the upstream repository's default branch to take effect there. + +Actions are pinned to immutable commit SHAs. Dependabot checks action updates +weekly; review those updates before merging. + +For local validation, run `actionlint` against the CI workflow and +`node --test .github\tests\release-policy.test.cjs` to exercise the release +eligibility script directly from the workflow without publishing anything. +These checks do not replace live GitHub validation. + ## Building ### CollectSFData / CollectSFDataDll @@ -234,10 +270,75 @@ todo ## Creating pull requests Fork repo and create pull request as normal across forks. -Labeling will be applied by git actions. +Maintainers apply labels manually; there is no automatic labeler. If executable changes, git actions will build. ## Creating Releases -To create a release, merge into master, and add 'Pre-release' or 'Release' label before merge. -Release will build signed exe and nuget package, and publish release to repo. \ No newline at end of file +### Build without publishing + +1. Open a PR targeting `main` or `master` and include a change outside the + excluded `docs/`, `configurationFiles/`, and `kusto/` paths. +2. In the PR checks, open **CI CollectSFData** and wait for the `build` job to + succeed. It builds with the `Release` configuration and packs the NuGet + package; it cannot publish a GitHub release. +3. Open the run summary under **Actions > CI CollectSFData** and download the + `Release` artifact to inspect the build output. +4. To merge without publishing, leave both release labels off the PR. The + resulting push build also uploads a `Release` artifact. + +A `Release` configuration build or an artifact named `Release` does not by +itself publish a release. + +### Publish a release or prerelease + +1. Ensure the migrated workflow is present on the upstream repository's default + branch and Actions is enabled. Use the upstream repository, not a fork, to + publish the official release. +2. Prepare a PR targeting `main` or `master`, including a change outside the + excluded paths. Documentation-, configuration-, or Kusto-only changes do not + trigger this workflow, even when the PR has a release label. +3. Review and validate the PR. Before merging, use the PR's **Labels** control + to apply exactly one of the following labels (create it under the + repository's **Issues > Labels** page if it does not exist): + - `Release`: publish a stable GitHub release. + - `Pre-release`: publish a GitHub prerelease. + Label names are case-sensitive. If both are present, prerelease takes + precedence. These labels must be applied manually; no labeler is required. +4. Merge the approved PR into `main` or `master`. Do not use a direct push as a + release trigger. For a push containing multiple merged PRs, only the PR + matching the pushed tip is considered. +5. Under **Actions > CI CollectSFData**, open the **push** run for that merge, + not the PR run. Verify: + - `build` succeeds and uploads the `Release` artifact. + - `release_metadata` succeeds and identifies the matching merged, + release-labelled PR. + - `release` succeeds after both jobs complete. +6. Open the repository's **Releases** page. Verify the release/prerelease + designation, commit/tag, generated notes, `CollectSFData.zip`, and NuGet + package attachments. + +The tag is `v` followed by the built executable's file version. That version is +generated from UTC build time by +[CollectSFData.csproj](../src/CollectSFData/CollectSFData.csproj), so rebuilding +the same commit later can produce a different version. The workflow attaches +the NuGet package to the GitHub release; it does not publish to NuGet.org. +The executable is strong-name signed, which is not an Authenticode signature. + +### Troubleshooting a release build + +- **No workflow run:** check the target branch and path exclusions. Adding a + label after merging does not start a workflow. +- **Release skipped:** check that the matching merged PR has the exact release + label and that its merge commit matches the pushed SHA. A successful + unlabelled build or direct push intentionally does not publish. +- **Metadata check failed:** inspect the job's GitHub API error. API failures + and ambiguous merged-PR matches fail explicitly rather than publishing. +- **Build or publication failed:** fix the reported failure and follow the + normal reviewed-PR process. For a transient failure, use GitHub's **Re-run + jobs** control on the original push run after checking the labels and any + existing release/tag. Reruns read current labels, and a full rebuild may + generate a new version; inspect existing assets before retrying publication. + +Live publication must be verified on GitHub after deployment. Local linting and +release-policy tests do not prove a release has been published. \ No newline at end of file