Skip to content
Merged
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
56 changes: 48 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <first> <second> <args>` 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

Expand Down
172 changes: 159 additions & 13 deletions action.yml
Original file line number Diff line number Diff line change
@@ -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[@]}"
4 changes: 2 additions & 2 deletions src/assembly-differ/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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@main`) 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

Expand Down
Loading