Spring Config Contract

Catch Spring Boot configuration drift before deployment.

Spring Config Contract is an open-source developer tool that checks whether configuration required by a Spring Boot application matches the configuration provided by its deployment environment.

Why?

Configuration drift is easy to miss: an application can require a property that is absent from deployment, while deployment files can retain values that the application no longer uses. This project is about comparing two different sides of that contract—not merely comparing Spring configuration files with each other.

For supported inputs, the v0.1 workflow reports required keys that deployment omits and deployment keys the application does not recognize. See the usage guide for the supported input subset and examples.

Status

Early development. The v0.1 configContractCheck Gradle task is implemented but not yet published; see the usage guide to try it from a source checkout. The future artifact topology and validation boundary are defined in the publication readiness guide.

The completed v0.1.0 scope is recorded in the release tracker. Compatibility claims are defined in the compatibility guide.

v0.1.0 scope

The first release implements:

• Spring-side inputs: supported @ConfigurationProperties, @Value, and application configuration cases on the tested Spring Boot line.
• Deployment-side inputs: .env.example and Docker Compose.
• Contract findings: missing and unused configuration, required/optional behavior, and default-value-aware comparison.
• Developer integration: a Gradle integration with the configContractCheck task and CI-friendly results.

The plugin is not published. It can be used from a source checkout as described in the usage guide.

How it works

Spring Boot
@ConfigurationProperties / @Value / application.yml
                    │
                    ▼
             Requirements
                    │
                    ▼
             Contract Engine
                    ▲
                    │
           Provided Config
                    ▲
                    │
      .env.example / Docker Compose

This is the v0.1 data flow for the supported inputs.

The configContractCheck task

The Gradle plugin io.github.inryeok-office.config-contract is implemented on main but not yet published, so it can only be used from a source build. It adds a configContract extension and a configContractCheck task:

plugins {
    java
    id("io.github.inryeok-office.config-contract")
}

configContract {
    activeProfiles.set(listOf("prod"))        // optional; empty analyzes the default profile
    dotenvExampleFiles.from(".env.example")   // optional
    composeFiles.from("compose.yml")          // optional
    // applicationConfigurationFiles defaults to top-level application*.properties|yml|yaml in main resources
}

./gradlew configContractCheck compiles the main source set, discovers its requirements, reads the deployment files, and prints one line per finding, ordered by key. The task fails when any MISSING or UNUSED finding exists; Spring discovery diagnostics are listed but do not fail the build. Every path in the output is relative to the root project, and deployment files must live inside it. The task is not attached to check.

Architecture

• config-contract-core: framework-independent domain models and comparison rules.
• config-contract-spring: Spring-specific interpretation and discovery.
• config-contract-deployment: deployment-format parsers and adapters.
• config-contract-gradle-plugin: Gradle orchestration and integration.
• config-contract-test: shared fixtures and test utilities.

See the architecture guide for dependency boundaries and invariants.

Roadmap

See the roadmap, v0.1.0 milestone, and release tracker.

Development

JDK 21 is required. The implemented workflow and repository verification can be run with the Gradle Wrapper:

./gradlew check
./gradlew build

On Windows, use gradlew.bat. See the development guide and testing guide for contributor commands and expectations.

Contributing

The project is early-stage, and focused contributions and design discussions are welcome. Start with CONTRIBUTING.md, then review the contribution workflow and governance policy.

License

Spring Config Contract is licensed under the Apache License 2.0.