mirror of
https://github.com/imjasonh/apidiff-action
synced 2026-07-06 22:52:43 +00:00
142 lines
4.2 KiB
Markdown
142 lines
4.2 KiB
Markdown
# apidiff-action
|
|
|
|
A GitHub Action that detects breaking API changes in Go code and comments on pull requests. This action uses the official [`golang.org/x/exp/cmd/apidiff`](https://pkg.go.dev/golang.org/x/exp/cmd/apidiff) tool to analyze API compatibility.
|
|
|
|
## Features
|
|
|
|
- 🔍 Automatically detects breaking API changes in pull requests
|
|
- 💬 Comments on PRs with detailed change reports
|
|
- ✅ Identifies both breaking and compatible changes
|
|
- 🚫 Can fail CI builds when breaking changes are detected
|
|
- 📊 Provides summary statistics in action outputs
|
|
|
|
## Usage
|
|
|
|
Add this action to your workflow:
|
|
|
|
```yaml
|
|
name: API Compatibility Check
|
|
on:
|
|
pull_request:
|
|
types: [opened, synchronize]
|
|
|
|
jobs:
|
|
apidiff:
|
|
runs-on: ubuntu-latest
|
|
permissions:
|
|
contents: read
|
|
pull-requests: write # Required for commenting on PRs
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
with:
|
|
fetch-depth: 0 # Required to access base commit
|
|
|
|
- uses: actions/setup-go@v5
|
|
with:
|
|
go-version: 'stable'
|
|
|
|
- uses: imjasonh/apidiff-action@v1
|
|
with:
|
|
fail-on-breaking: true
|
|
```
|
|
|
|
## Inputs
|
|
|
|
| Input | Description | Default |
|
|
| ------------------- | ----------------------------------------------------------- | --------------------- |
|
|
| `working-directory` | Directory to run apidiff in | `.` |
|
|
| `fail-on-breaking` | Whether to fail the action if breaking changes are detected | `true` |
|
|
| `comment-on-pr` | Whether to comment on the PR with results | `true` |
|
|
| `token` | GitHub token for commenting on PRs | `${{ github.token }}` |
|
|
|
|
## Outputs
|
|
|
|
| Output | Description |
|
|
| ---------------------- | ------------------------------------------------------- |
|
|
| `has-breaking-changes` | Whether breaking changes were detected (`true`/`false`) |
|
|
| `breaking-count` | Number of breaking changes found |
|
|
| `compatible-count` | Number of compatible changes found |
|
|
|
|
## Example PR Comment
|
|
|
|
The action will comment on your PR with a formatted report:
|
|
|
|
> # API Compatibility Check Results
|
|
>
|
|
> ## Summary
|
|
>
|
|
> | Type | Count |
|
|
> | ------------------ | ----- |
|
|
> | Breaking changes | 1 |
|
|
> | Compatible changes | 3 |
|
|
>
|
|
> ⚠️ **This PR contains breaking API changes!**
|
|
>
|
|
> ## Details
|
|
>
|
|
> ### `github.com/example/mypackage`
|
|
>
|
|
> #### ❌ Breaking changes
|
|
>
|
|
> - (\*Client).DoSomething: changed from func(string) error to func(context.Context, string) error
|
|
>
|
|
> #### ✅ Compatible changes
|
|
>
|
|
> - NewOption: added
|
|
> - WithTimeout: added
|
|
> - DefaultTimeout: added
|
|
|
|
Example in action: https://github.com/imjasonh/apidiff-action/pull/3
|
|
|
|
## Advanced Usage
|
|
|
|
### Continue on breaking changes
|
|
|
|
To get notified about breaking changes without failing the build:
|
|
|
|
```yaml
|
|
- uses: imjasonh/apidiff-action@v1
|
|
with:
|
|
fail-on-breaking: false
|
|
```
|
|
|
|
### Check specific directory
|
|
|
|
To check a specific package or module:
|
|
|
|
```yaml
|
|
- uses: imjasonh/apidiff-action@v1
|
|
with:
|
|
working-directory: ./api
|
|
```
|
|
|
|
### Use outputs in subsequent steps
|
|
|
|
```yaml
|
|
- uses: imjasonh/apidiff-action@v1
|
|
id: apidiff
|
|
with:
|
|
fail-on-breaking: false
|
|
|
|
- name: Handle breaking changes
|
|
if: steps.apidiff.outputs.has-breaking-changes == 'true'
|
|
run: |
|
|
echo "Found ${{ steps.apidiff.outputs.breaking-count }} breaking changes"
|
|
# Add custom handling here
|
|
```
|
|
|
|
## How it works
|
|
|
|
This action:
|
|
|
|
1. Installs the official `apidiff` tool from `golang.org/x/exp/cmd/apidiff`
|
|
2. Runs it to compare the base and head commits of your PR
|
|
3. Parses the output to identify breaking and compatible changes
|
|
4. Creates or updates a comment on the PR with the results
|
|
5. Optionally fails the build if breaking changes are detected
|
|
|
|
The underlying `apidiff` tool implements the compatibility rules from the [Go 1 compatibility guarantee](https://golang.org/doc/go1compat), checking for changes that would cause client code to stop compiling.
|
|
|
|
## License
|
|
|
|
This action is available under the [Apache License 2.0](LICENSE).
|