gs-spring-boot: the reference guide behind every Spring Boot tutorial

The guide is the upstream of the tutorial text

gs-spring-boot is the Spring Boot getting started guide, and its own description is precise about its role: it provides a sampling of how Spring Boot helps you accelerate application development, and it is meant to give you a quick taste of Spring Boot.

That last phrase hides the most important fact about the project. This is not a tutorial that someone wrote once. It is the repository the tutorial text is generated from, and the file layout shows the machinery.

The top level is complete-kotlin/, complete/, initial-kotlin/ and initial/, plus a test/ directory, a .github/ directory, CONTRIBUTING.adoc, LICENSE.txt, LICENSE.writing.txt and README.adoc. The four project directories are the same application in two states and two languages: initial/ is the project as Spring Initializr generates it, complete/ is the version with the guide's additions applied, and the two Kotlin directories are the Kotlin equivalents.

The README.adoc is written in AsciiDoc rather than Markdown, and the source uses AsciiDoc directives throughout, including includes of shared macros from a separate getting-started-macros repository. The build tooling variables at the top of the file, things like :spring_boot_version: current and :java_version: 17, are the mechanism that keeps one guide correct across Spring Boot releases: the version is a variable substituted at build time, not a number typed into prose.

The homepage is spring.io/guides/gs/spring-boot/, and the last push to the main branch was on 2026-09-01 with no GitHub releases, since a guide does not need them.

The two project states, and why both are kept

The four directories answer a question that most tutorial repositories ignore. Which files does the reader create, and which files already existed?

The initial/ directory is the state right after you click Generate on start.spring.io, before you write anything. The complete/ directory is the state after you have followed the guide. The guide's source includes the two states as separate listings, and the reader is expected to diff them mentally, which is how the text can say to create a web controller and then show the listing for the finished file rather than for the file that already exists.

The same structure appears in both languages, with the Kotlin variants in their own directories and separate include directives for each. The Java listings are marked as the primary source and the Kotlin ones as the secondary source, which is a small but meaningful convention, since it tells the documentation team which version of a snippet to keep in step when the two languages drift.

The Application class gets the same treatment. The guide notes that Spring Initializr creates a simple application class for you, but that in this case it is too simple and has to be modified to match the listing in complete/, with the Kotlin equivalent in complete-kotlin/.

There is also a test/ directory at the top level, which is the guide's own test content rather than the application's tests, and that distinction is worth noting because the guide also instructs the reader to add a unit test for the endpoint they just wrote.

The automatic configuration the guide exists to demonstrate

The guide's central teaching point is the mechanism behind Spring Boot's promise of minimal configuration, and it explains that mechanism in a way that is more precise than the marketing usually is.

Spring Boot looks at the Spring Boot modules you have added and at the beans you have configured, makes reasonable assumptions about what you are missing, and adds those items. Three examples follow.

If spring-boot-starter-webmvc is on the classpath, there are several specific beans you almost always need and Spring Boot adds them automatically, and because a Spring MVC application needs a servlet container, Spring Boot automatically configures embedded Tomcat. If Jetty is on the classpath but Tomcat is not, Spring Boot configures Jetty instead. And if spring-boot-starter-thymeleaf is on the classpath, the beans that must always be added to your application context are added for you.

Then the part that matters for anyone who has been bitten by a framework before. Spring Boot does not get in your way. If Thymeleaf is on your classpath, Spring Boot adds a SpringTemplateEngine to your context, but if you define your own SpringTemplateEngine with your own settings, Spring Boot does not add one. That leaves you in control with little effort on your part.

And the last note is the one to internalise. Spring Boot does not generate code or make edits to your files. Instead, when you start your application, Spring Boot dynamically wires up beans and settings and applies them to your application context. Nothing in your source tree is rewritten, which is why the guide's final state still looks like code you wrote.

Running the application and reading the bean dump

The run steps are short, and both build systems get the same treatment.

With Gradle:

./gradlew bootRun

And with Maven:

./mvnw spring-boot:run

What the reader should see next is the point of the exercise. The application class gained a CommandLineRunner method marked as a @Bean, and it runs on startup. It retrieves all the beans that were created by the application or that were automatically added by Spring Boot, sorts them and prints them out, and the output the guide shows starts with:

Let's inspect the beans provided by Spring Boot:
application
applicationAvailability
applicationTaskExecutor
applicationTaskExecutorAsyncConfigurer
availabilityProbesHealthEndpointGroupsPostProcessor
basicErrorController
beanNameHandlerMapping
beanNameViewResolver

The guide then points at what is in that list. You can see the org.springframework.boot.<tech>.autoconfigure beans, and there is also a tomcatServletWebServerFactory one. That is the whole automatic configuration story made concrete, because the beans you did not write are visible in a list your own code printed.

The request itself is then checked with curl in a separate terminal:

$ curl http://localhost:8080
Greetings from Spring Boot!

The guide as a house style document, not just a tutorial

The repository is not only the application code, and the extra files at the top level describe a documentation project with conventions.

CONTRIBUTING.adoc sits next to LICENSE.txt and LICENSE.writing.txt, and the two licences are a detail worth noticing. LICENSE.txt is the ordinary software licence for the sample code, Apache-2.0. LICENSE.writing.txt is a separate licence for the writing itself, which tells you that the prose and the code are treated as different assets with different terms, and that the guide is meant to be reused and adapted under stated conditions rather than copied casually.

The AsciiDoc source also shows how the guide assembles itself from shared parts. Several sections are includes of macros from the getting-started-macros repository, including the prerequisites block, the how to complete this guide block, and a macro for the Spring Boot application new path. So the boilerplate that every Spring guide repeats, the JDK and build tools prerequisites, is defined once and pulled in, which is the only sane way to keep thirty guides consistent.

The Java version is a variable too, declared as :java_version: 17, and the Spring Boot version is :spring_boot_version: current. The guide targets Java 17 and picks up whatever Spring Boot version the documentation build is running against.

There is a .github/ directory, and the guide notes that if your IDE has the Spring Initializr integration you can complete the process from the IDE, and that you can also fork the project from GitHub and open it in your IDE or another editor. The fork route matters for a guide that is also a working codebase, because a reader who wants to experiment is expected to fork and run rather than copy files by hand.

Editorial conclusion

Adopt gs-spring-boot as the canonical example when you need a minimal Spring Boot application that is known to work, because the initial/ and complete/ directories give you the before and after of the same application in both Java and Kotlin. Do not adopt it as a starting point for a real service, since it exists to illustrate one controller and one bean. Before you copy from it, read CONTRIBUTING.adoc and the writing licence file, because the guide is maintained as shared documentation with a house style, and check that the Java version matches your runtime, since the guide targets Java 17 and the Spring Boot version is a variable in the source rather than a fixed number.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. spring-guides/gs-spring-boot on GitHub