From 37a7f63dfd56ef60c10e6739332f50187ca3a61e Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Sat, 14 Nov 2026 09:45:53 +0100 Subject: [PATCH 1/2] Rebuild the GitHub Action on the commands and the pull-request report The action ran diff with two provider specs and a free-form args string, and did nothing on the pull request. It now installs the tool, compares the solution's libraries or a package, and runs pull-request: comment, release label, and fail-on with the breaking-allowed label. Inputs are typed and it has outputs. The old first, second and args inputs still run diff in the container image, with a deprecation warning. Co-Authored-By: Claude Opus 5.5 --- README.md | 56 +++++++++-- action.yml | 172 +++++++++++++++++++++++++++++++--- src/assembly-differ/README.md | 2 +- 3 files changed, 208 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 433623c..eae9183 100644 --- a/README.md +++ b/README.md @@ -160,17 +160,57 @@ worktree` recipe above. Its options are `-t`, `-o`, `-f` (default ### GitHub Action +On every pull request, report what it changes in your libraries' public API, label it for release-drafter, and fail +on a breaking change until someone adds the `breaking-allowed` label: + ```yaml -- uses: nullean/assembly-differ@main - with: - first: "previous-nuget|MyLib|1.3.0|net8.0" - second: "directory|src/MyLib/bin/Release/net8.0" - args: --target MyLib --format markdown +name: api-changes +on: + pull_request: + # labeled and unlabeled run the check again when someone adds or removes breaking-allowed + types: [opened, synchronize, reopened, labeled, unlabeled] + +permissions: + contents: read + pull-requests: write # the comment and the labels + +jobs: + api-changes: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-dotnet@v5 + with: + dotnet-version: 10.0.x + - run: dotnet build -c Release + - uses: nullean/assembly-differ@v1 ``` -The action runs `assembly-differ diff ` in the prebuilt, distroless -`ghcr.io/nullean/assembly-differ:edge` container, so the workflow needs no .NET SDK. `args` passes through verbatim. -Container actions run on Linux runners only. +Without `package`, the action compares every library project of the solution with the latest release of its package, +the way running the tool without a command does. Give `package: build/output/MyLib.1.3.0.nupkg` to compare a packed +package with the release before it instead. It installs the tool with `dotnet tool`, so it needs the .NET 10 SDK or +later on the runner, the one your build uses. + +| Input | Default | What | +|---|---|---| +| `package` | | a `.nupkg` to compare with the release before it; empty compares the solution's libraries | +| `projects` | | project files to compare instead, one per line | +| `target` | | only these assemblies, one per line | +| `framework` | | the target framework to compare | +| `fail-on` | `major` | fail when the suggested change is at least this, unless the pull request has `allow-label`; `none` never fails | +| `allow-label` | `breaking-allowed` | the label that lets a change at `fail-on` through | +| `major-label`, `minor-label`, `patch-label` | `breaking`, `feature`, none | the release label for each suggested change | +| `comment`, `labels` | `true` | keep the comment, set the labels | +| `working-directory` | `.` | where the solution is | +| `token` | `github.token` | needs `pull-requests: write` | +| `version` | latest | the assembly-differ version to install | + +Outputs: `suggested-change` (`None`, `Patch`, `Minor` or `Major`), `breaking-changes`, and `report`, the path of +`api-changes.json`. + +On a pull request from a fork the token cannot write, so the action writes the job summary and still applies +`fail-on`, but leaves the comment and labels alone. The deprecated `first`, `second` and `args` inputs still run `diff` +with two provider specs in the container image, as the action did before. ### Container diff --git a/action.yml b/action.yml index 2dc5cca..6da1f91 100644 --- a/action.yml +++ b/action.yml @@ -1,24 +1,170 @@ name: 'assembly-differ' -description: 'Diff assemblies or NuGet packages from different sources and report API changes' +description: 'Report what a pull request changes in your libraries public API, label it for release-drafter, and fail on breaking changes until they are allowed' branding: icon: 'git-pull-request' color: 'blue' + inputs: + package: + description: 'A .nupkg to compare with the release before it. Leave empty to compare every library project of the solution in working-directory with its latest release; build it first.' + required: false + default: '' + projects: + description: 'Project files to compare instead of the libraries the solution holds, one per line.' + required: false + default: '' + target: + description: 'Only compare these assemblies, by file name without extension, one per line.' + required: false + default: '' + framework: + description: 'The target framework to compare, such as net8.0. Defaults to the newest each project or package ships.' + required: false + default: '' + fail-on: + description: 'Fail when the suggested version change is at least this, unless the pull request has the allow-label: none, patch, minor or major.' + required: false + default: 'major' + allow-label: + description: 'The pull request label that allows a change at fail-on, so the check passes.' + required: false + default: 'breaking-allowed' + major-label: + description: 'The label for a Major change, for release-drafter. Empty sets none.' + required: false + default: 'breaking' + minor-label: + description: 'The label for a Minor change. Empty sets none.' + required: false + default: 'feature' + patch-label: + description: 'The label for a Patch change. Empty sets none.' + required: false + default: '' + comment: + description: 'Keep a comment with the report on the pull request.' + required: false + default: 'true' + labels: + description: 'Set the release label on the pull request.' + required: false + default: 'true' + working-directory: + description: 'Where the solution is, and where relative paths start.' + required: false + default: '.' + token: + description: 'The token for comments and labels; it needs pull-requests: write.' + required: false + default: ${{ github.token }} + version: + description: 'The assembly-differ version to install. Defaults to the latest release.' + required: false + default: '' first: - description: 'Old assembly provider, e.g. "nuget|NEST|6.1.0|net46" or "directory|C:\6.1.0"' - required: true + description: 'Deprecated: a provider spec, compared with second through diff. Use package or the solution instead.' + required: false + default: '' second: - description: 'New assembly provider, same format as "first"' - required: true + description: 'Deprecated: the second provider spec, with first.' + required: false + default: '' args: - description: 'Extra arguments passed through to assembly-differ verbatim, e.g. "--target NEST --format markdown"' + description: 'Deprecated: extra arguments for diff, with first and second.' required: false default: '' + +outputs: + suggested-change: + description: 'The suggested version change: None, Patch, Minor or Major.' + value: ${{ steps.report.outputs.suggested-change }} + breaking-changes: + description: 'How many breaking changes were found.' + value: ${{ steps.report.outputs.breaking-changes }} + report: + description: 'The path of api-changes.json.' + value: ${{ steps.report.outputs.report }} + runs: - using: 'docker' - image: 'docker://ghcr.io/nullean/assembly-differ:edge' - args: - - diff - - ${{ inputs.first }} - - ${{ inputs.second }} - - ${{ inputs.args }} + using: 'composite' + steps: + # Before inputs were typed, the action ran diff with two provider specs in the container image; it still does. + - name: Compare provider specs (deprecated inputs) + if: inputs.first != '' + shell: bash + working-directory: ${{ inputs.working-directory }} + env: + FIRST: ${{ inputs.first }} + SECOND: ${{ inputs.second }} + ARGS: ${{ inputs.args }} + run: | + echo "::warning title=assembly-differ::first, second and args are deprecated; compare the solution or a package instead (see the README)" + read -r -a extra <<< "$ARGS" + docker run --rm -v "$PWD:$PWD" -w "$PWD" ghcr.io/nullean/assembly-differ:edge diff "$FIRST" "$SECOND" "${extra[@]}" + + - name: Install assembly-differ + if: inputs.first == '' + shell: bash + env: + VERSION: ${{ inputs.version }} + run: | + tools="$RUNNER_TEMP/assembly-differ-tool" + if [ -n "$VERSION" ]; then + dotnet tool install assembly-differ --tool-path "$tools" --version "$VERSION" + else + dotnet tool install assembly-differ --tool-path "$tools" + fi + + - name: Compare + if: inputs.first == '' + shell: bash + working-directory: ${{ inputs.working-directory }} + env: + PACKAGE: ${{ inputs.package }} + PROJECTS: ${{ inputs.projects }} + TARGETS: ${{ inputs.target }} + FRAMEWORK: ${{ inputs.framework }} + run: | + output="$RUNNER_TEMP/assembly-differ" + mkdir -p "$output" + args=() + if [ -n "$PACKAGE" ]; then + args+=(release "$PACKAGE") + else + args+=(projects) + while IFS= read -r project; do [ -n "$project" ] && args+=(--project "$project"); done <<< "$PROJECTS" + fi + while IFS= read -r target; do [ -n "$target" ] && args+=(--target "$target"); done <<< "$TARGETS" + [ -n "$FRAMEWORK" ] && [ -n "$PACKAGE" ] && args+=(--framework "$FRAMEWORK") + "$RUNNER_TEMP/assembly-differ-tool/assembly-differ" "${args[@]}" --format json --output "$output" + + - name: Report on the pull request + id: report + if: inputs.first == '' + shell: bash + working-directory: ${{ inputs.working-directory }} + env: + GITHUB_TOKEN: ${{ inputs.token }} + FAIL_ON: ${{ inputs.fail-on }} + ALLOW_LABEL: ${{ inputs.allow-label }} + MAJOR_LABEL: ${{ inputs.major-label }} + MINOR_LABEL: ${{ inputs.minor-label }} + PATCH_LABEL: ${{ inputs.patch-label }} + COMMENT: ${{ inputs.comment }} + LABELS: ${{ inputs.labels }} + run: | + report="$RUNNER_TEMP/assembly-differ/api-changes.json" + if [ ! -f "$report" ]; then + # nothing was compared, such as a solution whose libraries have no release yet + echo "suggested-change=None" >> "$GITHUB_OUTPUT" + echo "breaking-changes=0" >> "$GITHUB_OUTPUT" + exit 0 + fi + echo "report=$report" >> "$GITHUB_OUTPUT" + echo "suggested-change=$(jq -r .suggestedVersionChange "$report")" >> "$GITHUB_OUTPUT" + echo "breaking-changes=$(jq -r .breakingChanges "$report")" >> "$GITHUB_OUTPUT" + args=(pull-request "$report" --fail-on "$FAIL_ON" --allow-label "$ALLOW_LABEL" + --major-label "$MAJOR_LABEL" --minor-label "$MINOR_LABEL" --patch-label "$PATCH_LABEL") + [ "$COMMENT" != "true" ] && args+=(--no-comment) + [ "$LABELS" != "true" ] && args+=(--no-labels) + "$RUNNER_TEMP/assembly-differ-tool/assembly-differ" "${args[@]}" diff --git a/src/assembly-differ/README.md b/src/assembly-differ/README.md index 4722c67..57e455c 100644 --- a/src/assembly-differ/README.md +++ b/src/assembly-differ/README.md @@ -58,7 +58,7 @@ overloads, ends with: `diff` with provider specs, such as `"nuget|Proc|0.13.0"`, still works as before for the builds that call it. -It also runs as a GitHub Action (`uses: nullean/assembly-differ@main`) and as a container +It also runs as a GitHub Action (`uses: nullean/assembly-differ@v1`), which comments on and labels pull requests, and as a container (`ghcr.io/nullean/assembly-differ`), both without a .NET SDK. ## Learn more From 58dd0b8d5069f3e91f59161506a592befaca7080 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Sat, 14 Nov 2026 09:46:12 +0100 Subject: [PATCH 2/2] Say only the container needs no .NET SDK Co-Authored-By: Claude Opus 5.5 --- src/assembly-differ/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/assembly-differ/README.md b/src/assembly-differ/README.md index 57e455c..83b8eb1 100644 --- a/src/assembly-differ/README.md +++ b/src/assembly-differ/README.md @@ -58,8 +58,8 @@ overloads, ends with: `diff` with provider specs, such as `"nuget|Proc|0.13.0"`, still works as before for the builds that call it. -It also runs as a GitHub Action (`uses: nullean/assembly-differ@v1`), which comments on and labels pull requests, and as a container -(`ghcr.io/nullean/assembly-differ`), both without a .NET SDK. +It also runs as a GitHub Action (`uses: nullean/assembly-differ@v1`), which comments on and labels pull requests, and as a +container (`ghcr.io/nullean/assembly-differ`) that needs no .NET SDK. ## Learn more