{"id":48313121,"url":"https://github.com/alien-tools/breakbot","last_synced_at":"2026-04-05T00:25:21.871Z","repository":{"id":38846772,"uuid":"372436202","full_name":"alien-tools/breakbot","owner":"alien-tools","description":"BreakBot tracks the introduction of breaking changes in Java libraries on GitHub and their impact on client projects.","archived":false,"fork":false,"pushed_at":"2023-12-16T00:54:39.000Z","size":1888,"stargazers_count":6,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-09T04:01:35.895Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alien-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-05-31T08:30:09.000Z","updated_at":"2023-12-15T16:19:44.000Z","dependencies_parsed_at":"2025-09-09T03:42:35.191Z","dependency_job_id":"d0981ec0-5cfc-4635-b11a-39c2a0722db2","html_url":"https://github.com/alien-tools/breakbot","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/alien-tools/breakbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Fbreakbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Fbreakbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Fbreakbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Fbreakbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alien-tools","download_url":"https://codeload.github.com/alien-tools/breakbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Fbreakbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31419699,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T00:25:07.052Z","status":"ssl_error","status_checked_at":"2026-04-05T00:25:05.923Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-05T00:25:21.415Z","updated_at":"2026-04-05T00:25:21.856Z","avatar_url":"https://github.com/alien-tools.png","language":"TypeScript","readme":"# BreakBot\n\n\u003e If we make this change to our code, how will it impact our clients?\n\n\u003e What if I remove this type? What if I deprecate this method? What if I change this field's type? What if I introduce this new method?\n\nIt is difficult for library maintainers to answer these simple—yet essential!—questions when evolving their libraries.\nUnderstanding the impact of a change on your own codebase is complicated enough, so how can you understand its impact on code that you've never even heard of?\n\nBreakBot is a GitHub App, built with [Probot](https://github.com/probot/probot), which automatically tracks the introduction of breaking changes in Java libraries and their impact on client projects.\nOnce installed on a repository, BreakBot listens to all pull requests and creates [GitHub check runs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). These checks highlight the breaking changes introduced by the pull requests and the impact they have on a selected set of client projects.\nThis information feeds the code review process and helps maintainers to decide whether the changes should be accepted in their current form or not.\n\n## Content\n1. [About BreakBot](#about-breakbot)\n2. [Configuration](#configurations)\n3. [Installation](#installation)\n4. [Other Resources](#other-resources)\n5. [Future Work](#future-work)\n\n\n## About BreakBot\n\n### Reports\nBreakBot reports consist of a summary that summarizes the list and impact of breaking changes, e.g.:\n\n\u003e This pull request introduces **3 breaking changes**, causing **22 detections** in client code.\n\u003e **3 of 30 clients** are impacted by the changes (10%).\n\n![A BreakBot report](./breakbot-report.png)\n\n### Completion Status\nBreakBot ends its analysis with either of these status:\n  - _Success_ when no breaking change is detected\n  - _Neutral_ when breaking changes are detected\n  - _Skipped_ when the analysis is skipped (e.g., no Java files affected by the pull request)\n\n### Supported Breaking Changes\n\nThe underlying analysis is realized using [Maracas](https://github.com/alien-tools/maracas), which in turn relies on [japicmp](https://github.com/siom79/japicmp).\n\nOnce installed on a repository, it will publish a report as a check on each new pull request. This report contains a list of the breaking changes created by this PR, compared to the base branch, and a list of the clients impacted for each PR.\n\n## Configuration\nSimilar to other GitHub Apps, BreakBot configuration must be hosted in a file `.github/breakbot.yml` directly within the repository.\n\n### Build\nTo conduct the analyses, BreakBot needs to be able to build the library and produce a JAR file for both the `base` and `head` branches of the pull requests. Currently, only Maven and Gradle are supported. By default, BreakBot autodetects a build file (`pom.xml` for Maven and `gradlew` for Gradle) in repository's root and runs a `mvn package` or `./gradlew` accordingly.\nIt is however possible to configure specific sub-directory, source directories, goals, and properties:\n\n```yaml\nbuild:\n  # Only build a sub-directory\n  module: core/\n  # Sources directory, if non-standard\n  sources: src/main/customjava\n  # Custom goals\n  goals: [clean jar-goal]\n  # Skipping tests and assemblies to speed un the build\n  properties:\n    maven.test.skip: true\n    assembly.skipAssembly: true\n```\n\n### Clients\nBreakBot needs to know about a list of clients to analyze. Currently, they have to be supplied manually as a list of GitHub repositories (denoted `owner/repo`).\nBy default, BreakBot looks for client code in the latest version (HEAD) of the repository's default branch, but this can be configured. [TODO: This part is not completely clear. What do you mean by client code here (e.g. tests)? ]\nNote that, in contrast to the library itself, BreakBot does not need to build and produce a JAR for client projects.\nInstead, BreakBot needs to know where the source files to analyze are located (by default, `src` or `src/main/java`).\nIf the source files are located elsewhere (e.g., in a particular submodule), this can be specified using the `sources` property.\n\n```yaml\nclients:\n  # Analyze the latest version (HEAD) of the default branch of user1/repo1\n  - repository: user1/repo1\n  # Analyze a particular module from user1/repo2, at a particular commit\n  - repository: user1/repo2\n    sources: module/src/main/java\n    sha: a3b98f\n  # Analyze a particular branch of user2/repo1\n  - repository: user2/repo1\n    branch: dev\n```\n\n### Exclude some APIs from the analysis\nSome parts of your APIs may be exempt from compatibility guarantees: types annotated with a `@Beta` annotation, everything within a `*.internal.*` package, etc. This can also be configured in the `breakbot.yml` file. All the elements matching the given patterns will be excluded from the analysis: no breaking change will be reported. The patterns are given in the `excludes` section: patterns starting with `@` denote annotations (every element tagged with this annotation is excluded from the analysis), while other regex-like patterns specify that any element whose name matches the regex should be excluded from the analysis.\n\n```yaml\nexcludes:\n  - '@Beta'\n  - '*internal*'\n```\n\n## Installation\n\n\n## Other Resources\n\n### Contributing\n\nIf you have suggestions for how BreakBot could be improved, or want to report a bug, open an issue! We'd love all and any contributions.\n\nFor more information, check out the [Contributing guide](CONTRIBUTING.md).\n\n### Contributors\n\n  - Léonard Rizzo\n  - Lina Ochoa\n  - Thomas Degueule\n  - Jean-Rémy Falleri\n\n\n## Future Work\n\n  - Automatically discover the clients to analyze, e.g. using Maven's dependency graph or GitHub's dependents list.\n  - Build the list of breaking changes between two versions of a library from source code only, avoiding the need for building JARs and using japicmp.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falien-tools%2Fbreakbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falien-tools%2Fbreakbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falien-tools%2Fbreakbot/lists"}