BootUI in CI/CD

One Action step. A live application assessment in your job Summary.

Example release: BootUI 2.4.0. Use a published copy of this same release for the application and CLI. The Action is pinned to this release's signed v2.4.0 tag. The documentation and starter kit are synchronized during release preparation; a repository can contain them before publication. The documentation website publishes the kit only after the exact CI release is verified as available.

Add BootUI to GitHub Actions

On a Linux runner, include BootUI in the started build for Spring Boot or Quarkus (2.4.0 profile setup), then add this step after your usual checkout and Java setup:

- name: BootUI diagnostics
  uses: jdubois/boot-ui@v2.4.0

That is the default setup. The Action:

Detects and starts your Spring Boot or Quarkus app on loopback.
Runs every available local advisor and gates HIGH/CRITICAL findings.
Adds a readable Markdown report to the job Summary, uploads reports, and stops the app.

What appears in GitHub Actions

Open the workflow run's Summary. An abbreviated failed assessment looks like this:

# BootUI assessment: VIOLATION

| Advisor | Required | Status | Findings | Rules skipped | Reason |
|---|---:|---|---:|---:|---|
| architecture | true | ASSESSED | 1 | 0 | - |
| rest-api | false | ASSESSED | 0 | 0 | - |
| security | false | SKIPPED | 0 | 0 | UNAVAILABLE |

### Retained finding summaries

| Advisor | Rule | Severity | Count | Meets threshold |
|---|---|---|---:|---|
| architecture | ARCH-PKG-001 | HIGH | 1 | yes |

Result	Meaning
PASS	The assessment completed and no finding met the failure threshold.
VIOLATION	A finding met the threshold; the job fails.
NOT_ASSESSED	BootUI could not complete a reliable assessment; the job fails.

The Action also uploads these files for seven days:

summary.md — the Summary shown above.
bundle.json — bounded sanitized machine-readable evidence.
junit.xml — standard JUnit XML for CI test reporters.

Display BootUI as a JUnit test/check

GitHub does not turn uploaded junit.xml into a Tests view. To publish one, feed ${{ steps.bootui.outputs.report-dir }}/junit.xml to a JUnit reporter with checks: write and add id: bootui to the BootUI step. For fork pull requests, use a trusted follow-up workflow because their token is read-only.

For example, with dorny/test-reporter:

- if: ${{ always() && steps.bootui.outputs.report-dir != '' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) }}
  uses: dorny/test-reporter@d1b5dff021aa968b288b02285a8bf47471c5928a # v3.2.0
  with:
    name: BootUI diagnostics
    path: ${{ steps.bootui.outputs.report-dir }}/junit.xml
    reporter: java-junit

The Action runs six CI-capable local advisors: Architecture, Hibernate, Spring, REST API, Security, and Database. Architecture is required; stack-specific advisors can be SKIPPED. HIGH or CRITICAL findings fail the job.

The policy excludes the GitHub advisor and vulnerability-service queries, which need credentials or external services; CI gates advisor findings directly, not the browser's aggregate score.

How startup and verify are handled

The Action detects these long-lived commands:

Framework	Application process
Maven + Spring Boot	`./mvnw spring-boot:run`
Maven + Quarkus	`./mvnw quarkus:dev`
Gradle + Spring Boot	`./gradlew --no-daemon bootRun`
Gradle + Quarkus	`./gradlew --no-daemon quarkusDev`

In 2.4.0, Maven projects with a bootui-ci profile get -Pbootui-ci automatically; other profiles need an explicit command.

spring-boot:run or quarkus:dev starts the app and keeps it running. mvn verify builds and tests, then exits. Most advisors do not need verify, so the Action does not run it by default. Add test-command only when your tests exercise the separately running app and you want runtime evidence from that workload.

The Action forces literal-loopback networking, metadata-only exposure, an isolated dismissal file, and cleans up only the process group it created.

Optional settings

Input	When to set it
`bootui-version`	Pin a version explicitly when the project uses dependency indirection that auto-detection cannot resolve, or when several BootUI versions are present.
`app-command`	Set the foreground command for a custom or multi-module start, or use `none` for an application that another step already started and will stop.
`test-command`	Run a finite command before assessment, such as `./mvnw verify`; it must exercise the running application when runtime evidence is the goal. Use `auto` for Maven `verify` or Gradle `check`.
`startup-timeout`	BootUI needs more than the default 120 seconds to become ready.
`url`	Your app uses a different literal-loopback URL, such as `http://127.0.0.1:8081`.
`policy`	You want to select other checks or thresholds.
`upload-artifact`	Set to `'false'` if you do not want the Action to upload the reports.
`api-path`	You changed the BootUI API mount from `/bootui/api`.

For example, a multi-module project can set a custom startup and workload explicitly:

with:
  app-command: ./mvnw -pl service spring-boot:run
  test-command: ./mvnw -pl integration-tests verify

When omitted, exactly one stable bootui-version is detected from the project's Maven or Gradle files. Managed applications use literal-loopback HTTP; externally managed TLS targets use app-command: none. Quarkus BootUI endpoints are available in DEV/TEST, not production mode. The CI reference covers advanced phases and custom workflows.

Optional complete sample

The starter kit includes runnable Spring MVC, WebFlux, and Quarkus examples. It is not required for the Action.

Download the complete starter kit. It includes the projects, Maven Wrapper, policies, scripts, and selectable workflow files. Extract it into a new repository to try the example, or copy only the diagnostic configuration and workflow you need into an existing project.

Troubleshooting

Symptom	First thing to check
`NOT_ASSESSED` or `ATTACH_FAILED`	The application is ready, bound to loopback, and has BootUI and its CLI endpoint enabled.
Tests pass but BootUI fails	Open the summary for the failing rule or incomplete required check.
The CLI does not recognize `ci`	Use a published CI-capable release, not the older 2.3.0 CLI.
The app starts but BootUI never becomes ready	Check the started build's dependency/profile and API path; see profile setup.
`@SpringBootTest` / `@QuarkusTest` starts and stops its own app	Use the framework-managed test recipe.

An early workflow failure, cancellation, or hard runner timeout can prevent a summary or artifact from being created. Reports contain sanitized diagnostic summaries, not application logs or the attachment witness.