Tooling

The build, CI, and developer-facing tools for the Elasticsearch repo.

Gradle composite build

Three included builds layered under the root project:

• build-conventions/ — shared Gradle plugins applied everywhere. Code style (Spotless via formatterConfig.xml), license header check, basic Java toolchain configuration.
• build-tools/ — public Gradle plugins published to Maven Central for use by external plugin authors.
• build-tools-internal/ — internal-only plugins for distribution packaging, BWC builds, REST API spec validation, fixtures, and CI integrations.

Top-level build.gradle applies a roster of elasticsearch.* plugins (jdk-download, internal-distribution-download, runtime-jdk-provision, ide, fips, etc.) that drive most of the work.

Key Gradle tasks

Task	Purpose
localDistro	Build a tar distribution targeting the current OS.
:run	Start a local dev cluster from source.
:run -PnumNodes=N	Multi-node dev cluster.
:server:test (etc.)	Per-project unit tests.
:server:internalClusterTest	Per-project integration tests.
:rest-api-spec:yamlRestTest	YAML REST tests against a sample cluster.
precommit	Aggregate of all per-project pre-commit checks.
spotlessApply / spotlessJavaCheck	Apply / verify the Java formatter.
forbiddenApis	Block deprecated / unsafe JDK APIs.
thirdPartyAudit	Detect new third-party dependency usage.
generateTransportVersion	Refresh transport-version CSVs.
validateNebulaPom	Validate the published pom for plugin authors.

Code generators

• ANTLR — Painless and ES|QL grammars (modules/lang-painless/src/main/antlr, x-pack/plugin/esql/src/main/antlr). Run ./gradlew :module:regen to refresh generated parsers.
• REST API spec — rest-api-spec/src/main/resources/rest-api-spec/api/*.json defines REST endpoints; consumed by client generators and YAML REST runners.
• Transport version CSVs — server/src/main/resources/transport/upper_bounds/*.csv are generated from TransportVersions.java via ./gradlew generateTransportVersion.

Never edit generated files. Edit the source and regenerate.

CI

• Buildkite — primary CI. Pipelines defined under .buildkite/ with templates in .buildkite/pipelines.
• GitHub Actions — secondary, for repository hygiene (.github/workflows/). Includes the docs-preview job and a few maintenance bots.
• Backport bot — pulled in via .backportrc.json. Opens backport PRs to active branches once a PR merges.
• Dependabot / Renovate — both are present (renovate.json, .github/dependabot.yml-style configs) and cover Gradle, Docker base images, and JDK distributions.

Pre-commit gates

./gradlew precommit (and :precommit per-project) is the convention. It runs:

• Spotless format check.
• Forbidden-APIs (banned JDK and Lucene calls).
• License header check.
• Third-party audit (no new transitive deps without explicit allow-listing).
• JarHell (no duplicated classes on the classpath).
• YAML REST spec validation.
• Test-name conventions check.

Fixtures and infrastructure tests

testfixtures-plugin (build-tools-internal/src/main/groovy/org/elasticsearch/gradle/internal/testfixtures) wires Docker Compose stacks for tests that need real backing services: HDFS, Kerberos, S3 (minio), GCS (fake-gcs-server), Azurite, OIDC providers, LDAP, etc. The fixtures are referenced by qa/ and x-pack/qa/ integration tests.

REST clients used by tests

client/rest/ and client/rest-high-level/ are vestigial and slowly being decommissioned in favor of language clients in separate repos (elasticsearch-java, go-elasticsearch, etc.). Tests use a thin RestClient (HttpAsyncClient) directly.

Developer scripts

• dev-tools/ — assorted maintenance scripts: bumping snapshot versions, building docs, running BWC checks.
• gradlew / gradlew.bat — project Gradle wrapper.
• Vagrantfile — used by packaging tests when running outside CI.

IDE integration

• IntelliJ (recommended) — ./gradlew idea regenerates IntelliJ project files; the elasticsearch.ide plugin in build-tools-internal configures code style, license headers, and run configurations.
• Eclipse — ./gradlew eclipse produces project files.

Custom analysis rules

build-tools-internal/src/main/groovy contains a handful of project-specific Gradle plugins that act as analyzers, e.g. checks that REST handler classes are named Rest*Action, that Writeable round-trip tests exist for transport messages, and that @SuppressWarnings is scoped narrowly. These run as part of precommit.