GO — Healthy across the board

• Last commit today
• 46+ active contributors
• Distributed ownership (top contributor 9% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

OpenSearch is an Apache 2.0-licensed fork of Elasticsearch that provides a distributed, RESTful search and observability engine for indexing and querying unstructured data at scale. It powers enterprise search, log analytics, and application performance monitoring with a focus on open governance and avoiding vendor lock-in. Gradle-based monorepo with core server engine in a 'server' subproject, benchmarking suite under 'benchmarks' (using JMH), CI infrastructure in .ci/ and .github/workflows/, and plugin architecture evident from Groovy build configs. Build system uses opensearch.gradle plugin (apply plugin: 'opensearch.build') providing consistent compilation, testing, and packaging across modules.

DevOps engineers, data platform teams, and search infrastructure maintainers who need self-hosted, open-source alternatives to Elasticsearch for building search applications, log aggregation systems (like ELK stack replacements), and observability platforms without licensing restrictions.

Production-ready and actively developed. The project has 100M+ lines of Java code, comprehensive CI/CD via GitHub Actions (.github/workflows/), extensive test infrastructure, and is governed as an OpenSearch Foundation project with clear maintenance responsibilities (MAINTAINERS.md, ADMINS.md). Recent activity shows ongoing feature development and release management (auto-release.yml, version.yml workflows).

Standard open source risks apply.

Active development across multiple areas: Lucene and Calcite snapshot integrations (lucene-snapshots.yml, calcite-snapshots.yml), performance benchmarking infrastructure (benchmark-pull-request.yml, add-performance-comment.yml), breaking change detection (detect-breaking-change.yml), automated dependency management (dependabot.yml), and version management (version.yml, auto-release.yml). Recent additions include sandbox checking (sandbox-check.yml) and nightly precommit validation.

Clone and build with: git clone https://github.com/opensearch-project/OpenSearch.git && cd OpenSearch && ./gradlew build. Requires JDK (version specified in .ci/java-versions.properties). Run local instance with: ./gradlew run (debug config available in .idea/runConfigurations/Debug_OpenSearch.xml).

Daily commands: Development: ./gradlew run (starts OpenSearch node). Testing: ./gradlew test (unit tests), ./gradlew integTest (integration tests). Benchmarking: ./gradlew benchmarks:jmh (runs JMH benchmarks). Docker: ./gradlew docker builds container image. CI simulates via .ci/jenkins/gradle-check.sh or GitHub Actions.

• README.md — Project overview and entry point for understanding OpenSearch as a distributed search engine and architecture fundamentals
• DEVELOPER_GUIDE.md — Essential guide covering build process, testing, contribution workflow, and development environment setup
• build.gradle — Root Gradle build configuration defining project structure, dependencies, and compilation for the entire OpenSearch distribution
• .github/workflows/gradle-check.yml — Primary CI/CD pipeline validating all code changes through automated testing and compilation checks
• CONTRIBUTING.md — Contribution guidelines establishing code standards, PR process, and community expectations for all contributors
• TESTING.md — Testing strategy and frameworks used across benchmarks and test suites essential for validating changes
• benchmarks/build.gradle — JMH benchmark configuration used to measure performance impact of core components across allocation, search, and storage systems

• Gradle Build System (Gradle 7+, Java 11+, custom build plugins) — Orchestrates compilation, testing, and packaging; manages dependency resolution and plugin lifecycle
  • Failure mode: Build failure blocks PR merge; requires developer to resolve compilation or test errors
• GitHub Actions CI (GitHub Actions YAML, shell scripts, gradle-check.sh) — Executes automated testing, quality checks, and release workflows on every commit/PR; gates PRs with required status checks
  • Failure mode: Failed job blocks PR merge; requires manual retry or fix-and-push cycle
• CodeQL Security Scanner (CodeQL database generation, GitHub Actions integration) — Performs semantic analysis on compiled code to detect SQL injection, XSS, unsafe reflection, and other vulnerabilities
  • Failure mode: High-severity findings block PR; developers must refactor code or add security exclusions

Add a new performance benchmark for a subsystem

1. Create a new Java class in benchmarks/src/main/java/org/opensearch/benchmark/{domain}/ annotated with @Fork, @Measurement, @Warmup using JMH framework (benchmarks/src/main/java/org/opensearch/benchmark/search/aggregations/TermsReduceBenchmark.java)
2. Implement @Benchmark methods measuring specific operations; use BenchmarkState for setup/teardown (benchmarks/src/main/java/org/opensearch/benchmark/routing/allocation/AllocationBenchmark.java)
3. Add build dependencies in benchmarks/build.gradle if new libraries are required (benchmarks/build.gradle)
4. Run benchmark via gradle :benchmarks:jmh and commit results to PERFORMANCE_BENCHMARKS.md (PERFORMANCE_BENCHMARKS.md)

Add a new GitHub Actions CI workflow

1. Create new YAML workflow file in .github/workflows/ with proper trigger conditions (on: [push, pull_request]) (.github/workflows/gradle-check.yml)
2. Define jobs using ubuntu-latest runners; integrate with existing gradle-check.sh patterns for consistency (.ci/jenkins/scripts/gradle-check.sh)
3. Add workflow to issue template or documentation for visibility to contributors (.github/ISSUE_TEMPLATE/config.yml)

Update project documentation for contributors

1. Update DEVELOPER_GUIDE.md with new setup steps or build instructions (DEVELOPER_GUIDE.md)
2. Document code conventions and patterns in CONTRIBUTING.md (CONTRIBUTING.md)
3. Add testing requirements to TESTING.md if new test categories exist (TESTING.md)
4. Reference changelog entry following semantic versioning in CHANGELOG.md (CHANGELOG.md)

• Gradle — Multi-module polyglot build system enabling modular architecture, dependency isolation, and incremental compilation for large Java projects
• GitHub Actions — Native CI/CD integration for automated testing, quality gates, and release workflows without external infrastructure dependencies
• JMH (Java Microbenchmarks) — Standard framework for measuring performance of JVM code components under realistic conditions before merging to main
• CodeQL — Automated semantic code analysis detecting security vulnerabilities and code quality issues before production deployment

• Gradle build system requires JVM and significant memory for incremental builds

  • Why: Gradle enables fine-grained caching, parallel task execution, and cross-project dependency management at scale
  • Consequence: Higher local development memory footprint (~4GB) but faster CI pipelines and reduced build times for developers

• JMH benchmarks run separately from unit tests, requiring explicit invocation and infrastructure

  • Why: JMH requires warm-up iterations and statistical averaging to produce accurate performance measurements
  • Consequence: Benchmark results not continuously validated but more reliable when explicitly run; must be manually integrated into release gates

• Multiple GitHub Actions workflows instead of single monolithic CI job

  • Why: Parallel execution and modularity enable faster feedback and independent failure isolation per concern
  • Consequence: Complex workflow orchestration but reduced critical path (PR feedback <5min) and easier debugging of specific failures

• Does not support Windows as primary development platform (Vagrant for Unix-based development only)
• Not a single-server solution; requires distributed cluster infrastructure for production deployment
• Does not provide GUI administration interface; REST API and command-line tooling only
• Not a real-time analytics engine; batch and near-real-time indexing/search latency of 100ms+

1. Gradle daemon and incremental compilation can cause stale artifacts; use ./gradlew clean build if seeing unexpected failures. 2) Build requires significant heap; may need to set JAVA_OPTS='-Xmx2g' or increase Gradle memory in gradle.properties. 3) Lucene/Calcite snapshot builds (lucene-snapshots.yml, calcite-snapshots.yml) must succeed or core features break; check CI status before major refactors. 4) The jopt-simple conflict in benchmarks/build.gradle is intentional (exclude directive); do not remove without checking JMH compatibility. 5) .ci/bwcVersions controls backward compatibility testing matrix; adding new versions requires careful coordination.

• Inverted Index — Fundamental data structure used by Lucene (OpenSearch's search core) to map terms to documents; critical for understanding query performance and tuning
• Distributed Consensus (Raft-like) — OpenSearch clusters coordinate state across nodes; understanding cluster state management and split-brain prevention is essential for production deployments
• Shard & Replica Architecture — Data is split into shards and replicated across nodes for scalability and fault tolerance; core concept affecting indexing throughput and query latency trade-offs
• Lucene Segment Merging — OpenSearch uses Lucene's segment merging strategy to optimize read/write trade-offs; impacts indexing performance and memory usage
• REST API Gateway Pattern — OpenSearch exposes all functionality via REST; understanding request routing, serialization, and action handlers is essential for API extensions
• JMH Microbenchmarking — Benchmarks subproject uses JMH to measure performance; critical for understanding performance regressions and validating optimizations
• Plugin Architecture — OpenSearch extensibility model allows custom analyzers, search plugins, and transport handlers; understanding plugin lifecycle is needed for contributions

• opensearch-project/opensearch-cli — Official CLI tool for managing OpenSearch clusters; companion project for users of this engine
• opensearch-project/OpenSearch-Dashboards — Visualization and exploration UI for OpenSearch; the 'Kibana fork' users typically pair with this search engine
• elastic/elasticsearch — Upstream Elasticsearch codebase from which OpenSearch forked; understanding version divergence matters for migration decisions
• opensearch-project/data-prepper — Log/metric processing pipeline that ingests data into OpenSearch; common component of observability stacks using this engine
• lucene/lucene — Core indexing library dependency; understanding Lucene changes is critical for troubleshooting search relevance and performance

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive JMH benchmark test coverage and documentation in benchmarks/ module

The benchmarks/build.gradle references JMH setup but benchmarks/src/main appears empty or incomplete. New contributors could add example benchmark classes demonstrating performance testing patterns for core OpenSearch components (indexing, search, aggregations) and create BENCHMARK_GUIDE.md in benchmarks/ explaining how to write and run benchmarks. This directly supports the repo's PERFORMANCE_BENCHMARKS.md goals.

• [ ] Create benchmarks/src/main/java/org/opensearch/benchmark/ directory structure
• [ ] Implement 3-5 example JMH benchmark classes (e.g., IndexingBenchmark, SearchBenchmark)
• [ ] Create benchmarks/BENCHMARK_GUIDE.md documenting benchmark patterns, execution, and result interpretation
• [ ] Add sample benchmark runner configuration in benchmarks/ directory
• [ ] Reference new benchmarks in main PERFORMANCE_BENCHMARKS.md

Add GitHub Actions workflow for automated benchmark regression detection

While .github/workflows/benchmark-pull-request.yml exists, there's no dedicated workflow for detecting performance regressions against baseline metrics. Create a new workflow that runs JMH benchmarks on PRs and comments with regression analysis. This prevents performance degradation from reaching main and adds value for performance-conscious contributors.

• [ ] Create .github/workflows/benchmark-regression-detection.yml
• [ ] Implement baseline benchmark storage strategy (GitHub artifacts or external service)
• [ ] Add regression threshold configuration (e.g., 5% deviation triggers comment)
• [ ] Generate comparison comment showing before/after metrics with visualization
• [ ] Document workflow in .github/BENCHMARK_WORKFLOWS.md or similar

Create CODEOWNERS entry and validation workflow for benchmarks/ directory

.github/CODEOWNERS exists but likely doesn't cover the benchmarks/ directory or has it assigned too broadly. Add specific CODEOWNERS for benchmarks/src and create a CI validation step that ensures benchmark PRs are reviewed by performance experts. This improves code quality for performance-critical code and provides clear contribution pathways.

• [ ] Update .github/CODEOWNERS to add specific @team/performance-maintainers entry for benchmarks/**
• [ ] Create .github/workflows/benchmark-ownership-check.yml to validate CODEOWNERS coverage
• [ ] Add validation in .github/workflows/gradle-check.yml to require benchmark maintainer approval
• [ ] Document benchmark contribution requirements in CONTRIBUTING.md with cross-reference to CODEOWNERS

• Add missing unit tests for error handling in REST API layer under server/src/main/java/org/opensearch/rest/; current test coverage has gaps for edge cases in status code mapping: REST API is user-facing, well-documented, and test failures are immediately obvious
• Improve CI documentation: create .ci/documentation/ file explaining the gradle-check.sh workflow, JMH benchmark triggers, and how to run CI locally for new contributors: File structure suggests documentation is incomplete (.ci/documentation/ exists but is minimal); low-risk contribution that helps future onboarding
• Add GitHub Action workflow to detect and warn on unused dependencies in build.gradle files (similar to dependabot.yml but for Gradle dependency bloat); wire it into gradle-check.yml: 100M+ LOC monorepo likely has accumulated unused transitive dependencies; auditing tool can be implemented without modifying core code

The OpenSearch project demonstrates a reasonable security baseline with a dedicated security contact and open source licensing. However, there are moderate concerns with outdated dependencies (jopt-simple 5.0.4, commons-math3 3.6.1) that should be addressed. The codebase lacks visible supply chain security measures like SBOM generation and artifact signing. Implementing dependency locking via Gradle lock files and automated vulnerability scanning would significantly improve the security posture. The project shows good CI/CD infrastructure but could strengthen security policy documentation and artifact provenance verification.

• Medium · Outdated jopt-simple Dependency — benchmarks/build.gradle (runtimeOnly 'net.sf.jopt-simple:jopt-simple:5.0.4'). The benchmarks module pins jopt-simple to version 5.0.4, which is outdated and may contain known vulnerabilities. This dependency is used at runtime and could expose the application to security risks. The comment indicates JMH ships with version 4.6, but pinning to an old 5.0.4 version is not ideal. Fix: Update jopt-simple to the latest stable version (currently 5.0.4 is from 2015). Consider using dependency scanning tools like OWASP Dependency-Check or Snyk to identify and remediate vulnerable dependencies automatically.
• Medium · Outdated commons-math3 Dependency — benchmarks/build.gradle (runtimeOnly 'org.apache.commons:commons-math3:3.6.1'). The benchmarks module uses Apache Commons Math 3.6.1, which is an older version from 2016. While not critical, older versions may have unpatched vulnerabilities. Commons Math 4.x versions are available and should be evaluated for compatibility. Fix: Evaluate upgrading to Commons Math 4.x or implement a dependency management strategy that regularly updates transitive and direct dependencies. Use automated dependency scanning in the CI/CD pipeline.
• Low · Missing Dependency Version Pinning — benchmarks/build.gradle (api "org.openjdk.jmh:jmh-core:$versions.jmh"). Many dependencies reference version variables (e.g., $versions.jmh) which are defined elsewhere. While this promotes consistency, it makes security auditing harder. There's no visible lockfile (like gradle.lock) shown in the provided structure. Fix: Enable Gradle's dependency locking feature with dependencyLocking.lockAllConfigurations() to generate and commit gradle.lock files. This ensures reproducible builds and makes dependency versions auditable.
• Low · Incomplete Security Documentation — SECURITY.md and .github/. While SECURITY.md exists with vulnerability reporting instructions, there's no evidence of a security policy file (.github/SECURITY.md) or disclosure timeline details. The README suggests the project follows best practices but specific security commitments are unclear. Fix: Create .github/SECURITY.md with more detailed security policy including: responsible disclosure timeline, supported versions for security updates, security headers configuration, and SBOM generation.
• Low · No Visible Supply Chain Security Measures — .github/workflows/ (all workflow files). The codebase lacks visible evidence of supply chain security controls such as SBOM (Software Bill of Materials) generation, signature verification, or artifact attestation in the CI/CD workflows shown. Fix: Implement SBOM generation using tools like syft or cyclonedx-maven-plugin. Sign releases with GPG keys. Add provenance attestation using tools like sigstore/cosign for artifact verification.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/opensearch-project/OpenSearch shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live opensearch-project/OpenSearch repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/opensearch-project/OpenSearch.

What it runs against: a local clone of opensearch-project/OpenSearch — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in opensearch-project/OpenSearch | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of opensearch-project/OpenSearch. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/opensearch-project/OpenSearch.git
#   cd OpenSearch
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of opensearch-project/OpenSearch and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "opensearch-project/OpenSearch(\\.git)?\\b" \\
  && ok "origin remote is opensearch-project/OpenSearch" \\
  || miss "origin remote is not opensearch-project/OpenSearch (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "DEVELOPER_GUIDE.md" \\
  && ok "DEVELOPER_GUIDE.md" \\
  || miss "missing critical file: DEVELOPER_GUIDE.md"
test -f "build.gradle" \\
  && ok "build.gradle" \\
  || miss "missing critical file: build.gradle"
test -f ".github/workflows/gradle-check.yml" \\
  && ok ".github/workflows/gradle-check.yml" \\
  || miss "missing critical file: .github/workflows/gradle-check.yml"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/opensearch-project/OpenSearch"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.