Setup Java Spring Boot GitHub Workflows

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Creates the three GitHub Actions workflows a Spring Boot service needs: one that builds, tests, analyses, and publishes documentation; one that deploys; and one that stops or destroys an environment.

Purpose

iru-setup-java-springboot-github-workflows is the service-shaped counterpart to Setup Java GitHub Workflows. A service is not published to Maven Central and is not GPG-signed — it is built into a container image and deployed — so the publish, sign, and version-sync stages are replaced by image build, OpenTofu apply, and teardown. The shared stages (test, analyse, Sonar, Antora, GitHub Pages) follow the same house pattern, so the two remain recognisably related.

Workflow Trigger Does

Workflow	Trigger	Does
`build.yml`	Push to the integration/main branch, and every pull request	Build, unit tests (Surefire), Testcontainers integration tests (Failsafe), static analysis, aggregated coverage, Sonar, and — on the main branch only — the Antora site plus the generated OpenAPI, protobuf, GraphQL and AsyncAPI HTML, published to GitHub Pages
`deploy.yml`	`workflow_dispatch` with an environment input, optionally on release published	Build and push the container image, authenticate via keyless OIDC, `tofu plan` then apply that plan file, then a smoke check that fails the deploy if the service never becomes healthy
`undeploy.yml`	`workflow_dispatch` only	Scale to zero (the reversible default) or destroy an environment, behind a typed-confirmation check and a protected GitHub Environment

build.yml

Push to the integration/main branch, and every pull request

Build, unit tests (Surefire), Testcontainers integration tests (Failsafe), static analysis, aggregated coverage, Sonar, and — on the main branch only — the Antora site plus the generated OpenAPI, protobuf, GraphQL and AsyncAPI HTML, published to GitHub Pages

deploy.yml

workflow_dispatch with an environment input, optionally on release published

Build and push the container image, authenticate via keyless OIDC, tofu plan then apply that plan file, then a smoke check that fails the deploy if the service never becomes healthy

undeploy.yml

workflow_dispatch only

Scale to zero (the reversible default) or destroy an environment, behind a typed-confirmation check and a protected GitHub Environment

No credential is ever written into a workflow file: cloud access is keyless via OIDC, and everything else is a repository or environment secret referenced by name. Where the registry supports it, even the registry credential is derived from the OIDC session (amazon-ecr-login, gcloud auth configure-docker) rather than stored.

The guards on undeploy.yml are the feature rather than ceremony: stop is the default and is reversible, data-bearing resources are expected to carry deletion protection so destroy fails on them rather than silently deleting a production database, and the skill recommends restricting prod to required reviewers plus a deployment branch rule — and considering omitting prod from the destroy path entirely.

Purpose group

Spring Boot Service Bootstrap

Invocation

/iru-setup-java-springboot-github-workflows

Inputs

Argument Required Description Default

Argument	Required	Description	Default
`stack-file`	No	`args` `key: value` line giving the manifest path. Read for the cloud, the Java version, and the technologies in play.	`springboot-stack.yml` at the repository root
`integration-branch`, `main-branch`	No	`args` `key: value` lines. Otherwise confirmed against `git branch -a` rather than assumed to be gitflow.	`develop`, `main`
On-disk survey	Yes	The workflows must match reality, so the skill reads: the reactor’s modules and the `boot` directory, where `report-aggregate` writes, whether the Sonar plugin and properties exist, the Antora config and which extensions `docs/package.json` lists, where the API doc generators write, whether `apis/messaging/` and `apis/graphql-server/` hold their contracts and committed `docs/package-lock.json` toolchains (and whether the GraphQL one pins `graphql-voyager` as well as `spectaql`), which `infra/envs/<env>` directories exist, whether GitHub Environments exist, and how heavy the compose stack is.	None — derived
Existing workflow files	No	If any exists, `AskUserQuestion` asks whether to stop or update it, preserving steps this skill doesn’t own (a Slack notification, an extra matrix leg).	None — user must choose

stack-file

args key: value line giving the manifest path. Read for the cloud, the Java version, and the technologies in play.

springboot-stack.yml at the repository root

integration-branch, main-branch

args key: value lines. Otherwise confirmed against git branch -a rather than assumed to be gitflow.

develop, main

On-disk survey

Yes

The workflows must match reality, so the skill reads: the reactor’s modules and the boot directory, where report-aggregate writes, whether the Sonar plugin and properties exist, the Antora config and which extensions docs/package.json lists, where the API doc generators write, whether apis/messaging/ and apis/graphql-server/ hold their contracts and committed docs/package-lock.json toolchains (and whether the GraphQL one pins graphql-voyager as well as spectaql), which infra/envs/<env> directories exist, whether GitHub Environments exist, and how heavy the compose stack is.

None — derived

Existing workflow files

If any exists, AskUserQuestion asks whether to stop or update it, preserving steps this skill doesn’t own (a Slack notification, an extra matrix leg).

None — user must choose

Outputs

.github/workflows/build.yml — a build job (checkout with full history for Sonar blame, JDK with Maven cache, mvn clean verify, the site report, the Sonar scan skipped on fork pull requests, and test reports uploaded even on failure) plus a docs job gated to main-branch pushes. The docs job generates the Maven site and the OpenAPI/protobuf documentation, then runs the two npm-driven generators as their own steps against the toolchains committed in apis/messaging/docs and apis/graphql-server/docs — validating and rendering the AsyncAPI specification, and rendering the GraphQL SDL through SpectaQL and (optionally) Voyager. It then builds the Antora site and merges everything: a "Merge documentation" step copies the contents of every target/generated-docs directory in the reactor under doc/api/, so rest-server/, grpc-server/, graphql-server/ and messaging/ land side by side without the workflow needing to know which module produced which. The published result includes doc/api/messaging/v1/index.html and doc/api/graphql-server/v1/index.html with the Voyager graph beneath it. Both npm generators are skipped in Maven (-Dasyncapi.docs.skip=true -Dgraphql.docs.skip=true) in this job so the work isn’t done twice — the build job’s mvn clean verify still exercises the frontend-maven-plugin wiring — and each step is guarded by hashFiles(…), so deleting a contract directory doesn’t require a workflow edit. Their loops over -async-api-v.yaml and -v.graphqls mean a new contract version needs no workflow change either.
```
  One detail the merge step protects by accident and would break if simplified: Voyager's page loads
  `voyager.standalone.js` and `voyager.css` by relative path, so those files must travel with `index.html`. Copying
  whole directories preserves that; copying only `index.html` files would publish a blank graph.
* `.github/workflows/deploy.yml` — with `id-token: write`, a concurrency group per environment that never cancels
  in progress, the GitHub Environment as the approval gate, buildpack image build and push, and `tofu apply` of the
  previously produced plan file.
* `.github/workflows/undeploy.yml` — with the typed-confirmation check, the same concurrency group as `deploy.yml`
  so the two can never run at once, and separate `stop` and `destroy` paths.
* A report including the full table of required repository secrets, environment secrets, environment variables, and
  GitHub Environments — plus the two settings that are easy to miss: GitHub Pages served from `gh-pages`, and an
  OIDC trust policy scoped to the repository *and* the environment.
```

Execution flow

flowchart TD A["Start /iru-setup-java-springboot-github-workflows"] --> B["Step 0: Read the manifest; survey the reactor,\nSonar config, Antora setup, infra/envs,\nGitHub Environments, compose stack weight"] B -- compose stack too heavy for a standard runner --> C["Flag now; offer a larger runner\nor a per-module IT matrix"] B -- a workflow already exists --> D{"Stop or update?"} D -- stop --> STOP[Report which exist; stop] D -- update --> E B --> E["Step 1: Write build.yml\n(build job + main-branch-only docs job:\nMaven site, OpenAPI/protobuf docs, AsyncAPI\nand GraphQL html, Antora, merge into ./doc)"] C --> E E --> F["Step 2: Write deploy.yml\n(OIDC, image build, plan then apply, smoke check)"] F --> G["Step 3: Write undeploy.yml\n(typed confirmation, stop vs destroy)"] G --> H["Step 4: Assemble the secrets,\nvariables, and environments table"] H --> I["Step 5: Validate — YAML parses,\naction versions current, secret names consistent;\nMaven commands verified locally via iru-gate-runner"] I --> J["Step 6: Report files, gaps,\nand review warnings"]

deploy.yml and undeploy.yml are deliberately never triggered as a test. The skill instead recommends a dry run of build.yml on a throwaway branch, and a first deploy.yml run against dev only, watched to completion.

Dependencies

Invokes

None. It reads springboot-stack.yml and surveys the repository, then writes workflow YAML. It may offer to add the sonar-maven-plugin and sonar.* properties to the root pom.xml if the survey finds them missing.

Invoked by

Setup Java Spring Boot — Step 8, sixth of seven sub-skills, via the iru-isolated-skill-executor agent. Runs late because it surveys what is actually on disk — the reactor, the Antora setup, and the infra/envs/ directories from Setup Java Spring Boot Platform.

Also runs standalone (/iru-setup-java-springboot-github-workflows).

Related agents

iru-gate-runner — spawned in Step 5 to run the workflow’s Maven commands locally first, on the principle that a workflow whose commands were never run locally is a guess.

Source

SKILL.md on GitHub — the file this page was generated from.