GO — Healthy across the board

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

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

GreptimeDB is a unified observability database written in Rust that consolidates metrics, logs, and traces into a single engine, replacing separate Prometheus, Loki, and Elasticsearch deployments. It exposes both SQL and PromQL interfaces and stores data on object storage backends, making it a cost-effective alternative to the traditional three-tool observability stack. Monorepo structure with .cargo/config.toml for workspace configuration. CI/CD is GitHub Actions-centric (.github/actions/ contains reusable custom actions for building, deploying, and testing across Linux/macOS/Windows). Infrastructure testing uses Docker-based setups (setup-greptimedb-cluster/, setup-kafka-cluster/, setup-etcd-cluster/) in CI workflows. Rust is the primary language with supplementary Python/TypeScript for tooling and GitHub scripts (package.json shows @octokit/rest for automation).

DevOps engineers, SREs, and platform teams operating observability systems who want to reduce operational complexity and cost by consolidating metrics, logs, and traces into a single database. Contributors include Rust backend engineers building distributed database systems and observability infrastructure specialists.

Actively developed and approaching production maturity. The codebase is substantial (~24MB Rust, organized CI/CD with GitHub Actions workflows for multi-platform builds), has comprehensive test infrastructure (.config/nextest.toml indicates organized testing), and maintains a public roadmap (see Roadmap 2026 in README). Regular releases occur with Docker image distribution, though the breadth of observability consolidation is still maturing.

Moderate risk from architectural complexity: consolidating three distinct observability domains (metrics, logs, traces) into one engine is inherently complex. No single-maintainer risk visible (team structure via CODEOWNERS), but the rapid evolution of the observability ecosystem means breaking changes are possible. Dependency risk is mitigated by Rust's static compilation, though the heavy use of distributed systems infrastructure (etcd, Kafka, MinIO in CI actions) adds operational complexity.

Active development on distributed clustering (setup-greptimedb-cluster actions), multi-backend storage support (with-minio.yaml, with-disk.yaml), WAL optimization (with-remote-wal.yaml), and chaos/integration testing infrastructure (fuzz-test, setup-cyborg actions). The presence of release artifact workflows and CN-specific release pipelines indicates ongoing multi-region deployment focus.

git clone https://github.com/GreptimeTeam/greptimedb.git
cd greptimedb
cargo build --release
cargo run

For development: cargo build produces debug binaries; tests run via cargo test or the configured nextest runner in .config/nextest.toml. Docker images are built and pushed via the CI pipeline; for local iteration, use cargo build directly.

Daily commands: Development: cargo build && cargo run starts a single instance. Production-like: Use the Docker compose configurations in .github/actions/setup-greptimedb-cluster/ as templates (with-minio.yaml, with-observability.yaml, etc.). The .env.example file likely contains required configuration; copy it to .env and customize. Multi-node clusters require etcd setup (setup-etcd-cluster action shows the pattern).

• Cargo.toml — Root workspace manifest defining all crates, dependencies, and build profiles; essential for understanding the complete project structure and dependency graph.
• .github/workflows/develop.yml — Primary CI/CD pipeline orchestrating builds, tests, and deployments; critical for understanding how code reaches production.
• .github/actions/build-greptime-binary/action.yml — Core binary build action used across all release workflows; defines compilation targets and artifact generation.
• .cargo/config.toml — Cargo build configuration including target-specific settings, linker options, and profiles; affects all compilation steps.
• .config/nextest.toml — Test execution configuration for nextest; defines how the test suite runs, partitioning, and resource allocation.
• Makefile — Development workflow automation and common build targets; entry point for local development and testing.
• .github/CODEOWNERS — Code ownership and review responsibility mapping; essential for understanding who maintains which components.

Add a new CI workflow for a specific integration test

1. Create a new workflow file in .github/workflows following the naming convention (e.g., my-integration-test.yml) (.github/workflows/my-integration-test.yml)
2. Reference existing actions from .github/actions (e.g., setup-greptimedb-cluster) for cluster provisioning (.github/actions/setup-greptimedb-cluster/action.yml)
3. Add test execution steps using sqlness-test action or custom scripts (.github/actions/sqlness-test/action.yml)
4. Reference in .github/workflows/develop.yml if test should run on every commit (.github/workflows/develop.yml)

Add a new cross-platform build target

1. Update Cross.toml with new target architecture configuration if using cross-compilation (Cross.toml)
2. Add build matrix strategy to .github/workflows/release.yml to include new target (.github/workflows/release.yml)
3. Create or update platform-specific action in .github/actions (e.g., build-linux-artifacts/action.yml) (.github/actions/build-linux-artifacts/action.yml)
4. Update artifact upload configuration in .github/actions/upload-artifacts/action.yml (.github/actions/upload-artifacts/action.yml)

Add a new container image to the release pipeline

1. Create Dockerfile in the root or appropriate subdirectory (.dockerignore)
2. Add image build configuration to .github/actions/build-greptime-images/action.yml (.github/actions/build-greptime-images/action.yml)
3. Update .github/workflows/release.yml to call the image build action (.github/workflows/release.yml)
4. Add registry push steps for artifact distribution (.github/actions/publish-github-release/action.yml)

Extend the development environment setup

1. Update Makefile with new development targets for local setup (Makefile)
2. Add required dependencies to Cargo.toml workspace (Cargo.toml)
3. Document new setup steps in CONTRIBUTING.md (CONTRIBUTING.md)
4. Update .github/actions/setup-greptimedb-cluster with any new services needed (.github/actions/setup-greptimedb-cluster/action.yml)

• Rust + Cargo — High-performance compiled language with strong type safety and memory safety; essential for a database handling metrics, logs, and traces at scale
• GitHub Actions — Native CI/CD deeply integrated with repository; enables complex multi-platform builds, testing, and deployments without external services
• Docker & Kubernetes — Containerization and orchestration for reproducible deployments and cluster management in distributed observability scenarios
• nextest — Parallel test runner for Rust projects optimizing test execution time and providing better diagnostics than cargo test
• OpenTelemetry backend — Standard for collecting metrics, logs, and traces; unifies Prometheus, Loki, and Elasticsearch use cases

• Unified database for metrics, logs, and traces

  • Why: Reduces operational complexity of running three separate systems (Prometheus, Loki, ES)
  • Consequence: Increased architectural complexity to handle three different data models efficiently; potential performance optimization trade-offs

• Multi-platform CI/CD with cross-compilation

  • Why: Enables single binary distribution across Linux, macOS, Windows, and ARM architectures
  • Consequence: Increased CI/CD pipeline complexity and longer build times; requires maintaining cross-compilation configurations

• Kubernetes-first orchestration strategy

  • Why: Aligns with cloud-native observability workflows and scalability requirements
  • Consequence: Requires additional operational expertise for deployment; standalone or simpler deployment scenarios require custom configuration

• SQL + PromQL dual query interface

  • Why: Provides compatibility with existing Prometheus workflows while enabling powerful SQL analytics
  • Consequence: Must maintain two query engines with consistent semantics; increased codebase complexity

• Does not provide authentication or RBAC (authentication responsibility delegated to proxy/ingress layer)
• Not designed as a real-time streaming database (optimized for observability timeseries patterns, not general-purpose streaming)
• Does not handle client-side SDKs or agent deployment (assumes OpenTelemetry collectors pre-deployed)

Distributed system complexity: Running tests locally requires etcd, Kafka, and MinIO services (see setup-*-cluster actions); .env.example should document these. Multi-backend storage abstraction: The codebase supports local disk, S3, and MinIO simultaneously; configuration is non-trivial—check examples in .github/actions/setup-greptimedb-cluster/. Cross-language CI: Rust core plus TypeScript GitHub automation scripts (package.json) with @octokit/rest; ensure Node.js is installed for running GitHub actions locally. Breaking changes in observability: PromQL and SQL compatibility modes may diverge; test coverage expectations are high. Platform-specific builds: Dockerignore and multi-platform GitHub Actions (build-linux-artifacts, build-windows-artifacts, build-macos-artifacts) indicate platform-specific logic; test locally on your target platform if modifying binaries.

• Time-Series Data Model — GreptimeDB unifies metrics, logs, and traces into a single time-series backend; understanding the underlying data model (timestamps, tags, fields, cardinality) is critical for query optimization and schema design.
• Columnar Storage (Arrow/Parquet) — GreptimeDB likely uses columnar formats for efficient compression and OLAP-style analytical queries on observability data; knowledge of Arrow or Parquet is essential for understanding storage layer performance.
• Write-Ahead Logging (WAL) — WAL (evidenced by with-remote-wal.yaml in CI) ensures durability in a distributed database; understanding WAL semantics is critical for operational decisions about crash recovery and data safety.
• Distributed Consensus (etcd, Raft) — GreptimeDB uses etcd for cluster coordination (setup-etcd-cluster action); understanding consensus algorithms is necessary for debugging cluster formation, leader election, and split-brain scenarios.
• Object Storage Backend Abstraction — GreptimeDB abstracts multiple storage backends (local disk, S3, MinIO); understanding how to add or optimize a new backend requires knowing storage interface patterns and trade-offs.
• PromQL Query Dialect — GreptimeDB exposes PromQL compatibility (per README); contributors need to understand PromQL semantics, aggregation functions, and range vectors to implement or fix query functionality.
• Chaos Engineering & Observability Testing — The presence of setup-chaos and fuzz-test actions indicates systematic testing of failure modes; understanding chaos patterns helps validate robustness of the distributed system.

• prometheus/prometheus — The metrics component that GreptimeDB aims to replace; understanding Prometheus' data model and PromQL dialect is essential for validating GreptimeDB's metrics compatibility.
• grafana/loki — The log aggregation system GreptimeDB consolidates; knowing Loki's architecture and query language helps contextualize GreptimeDB's log storage approach.
• elastic/elasticsearch — The trace/log search engine GreptimeDB replaces; architectural understanding helps justify GreptimeDB's design decisions around cost and unified querying.
• open-telemetry/opentelemetry — GreptimeDB is a unified OpenTelemetry backend (per README); understanding OTel's data model (metrics, logs, traces, spans) is fundamental to the project's purpose.
• GreptimeTeam/greptimedb-python — Official Python client library for GreptimeDB; understanding how clients interact with the database is important for API design and integration testing.

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 GitHub Actions workflow validation and documentation for custom actions

The repo has 20+ custom GitHub Actions in .github/actions/ but lacks a dedicated CI workflow to validate their syntax, references, and outputs. This prevents breaking changes when actions are modified. New contributors could add a workflow that lints action.yml files, validates composite action steps, and checks for unused actions.

• [ ] Create .github/workflows/validate-actions.yml to run yamllint on all action.yml files
• [ ] Add step to validate that all actions referenced in main workflows exist in .github/actions/
• [ ] Add step to check for unused custom actions by scanning .github/workflows/
• [ ] Document the custom action patterns in .github/actions/README.md (currently missing)
• [ ] Add validation for required fields (name, description, runs) in each action.yml

Create GitHub Actions test suite for build and deployment actions

The build actions (.github/actions/build-greptime-images/, build-linux-artifacts/, build-macos-artifacts/, build-windows-artifacts/) have no integration tests. Adding a test workflow that validates these actions with mock inputs/outputs would catch errors early and serve as documentation for new contributors.

• [ ] Create .github/workflows/test-build-actions.yml workflow
• [ ] Add test cases for .github/actions/build-greptime-binary/action.yml with various platform inputs
• [ ] Add test cases for .github/actions/build-greptime-images/ validating Docker image metadata
• [ ] Add test cases for artifact upload/download actions with sample artifacts
• [ ] Document expected inputs/outputs for each build action in action-specific README files

Add comprehensive setup guide for GitHub Actions cluster configurations

The .github/actions/setup-greptimedb-cluster/ directory has 5 different YAML configurations (with-disk.yaml, with-minio.yaml, with-remote-wal.yaml, etc.) with no documentation explaining when to use each. New contributors cannot easily understand the cluster topology variations or add new configurations.

• [ ] Create .github/actions/setup-greptimedb-cluster/README.md documenting each configuration file
• [ ] Add decision tree/flowchart for selecting appropriate cluster config
• [ ] Document the differences between with-minio.yaml, with-minio-and-cache.yaml, and with-minio-repartition-gc.yaml
• [ ] Add examples showing how to reference each config variant in workflows
• [ ] Add troubleshooting section for common cluster setup failures

• Add missing integration tests for the MinIO storage backend. The .github/actions/setup-greptimedb-cluster/with-minio.yaml configuration exists but likely lacks automated test coverage; write tests that verify read/write semantics for metrics and logs stored on MinIO.: Improves reliability of a key production backend without requiring deep understanding of the entire query layer.
• Document the WAL (Write-Ahead Logging) configuration in a new docs/wal-configuration.md file. The .github/actions/setup-greptimedb-cluster/with-remote-wal.yaml suggests WAL support, but there's no visible user documentation. Create a guide covering local vs. remote WAL setup, performance implications, and tuning.: Documentation contributions are lower-risk and help clarify operational concerns for new users without requiring code changes.
• Extend the fuzz testing setup (.github/actions/fuzz-test/action.yaml exists) to cover SQL query parsing. Add property-based tests (using proptest or quickcheck) that generate random SQL inputs and verify the parser handles edge cases gracefully.: Increases robustness of a critical public API (SQL interface) and uses existing CI infrastructure; good way to learn the parser codebase.

• High · Sensitive Credentials Exposed in .env.example — .env.example. The .env.example file contains template variables for sensitive credentials including AWS S3 access keys, OSS access keys, Azure Blob Storage account keys, and GCS credentials. While these are examples, the presence of this file in the repository could serve as a guide for attackers on what credentials to target. Additionally, if developers copy this file without proper renaming or gitignore configuration, actual secrets could be committed. Fix: 1) Ensure .env.example and .env are in .gitignore. 2) Document credential management practices in CONTRIBUTING.md. 3) Use a secrets management tool (e.g., HashiCorp Vault, AWS Secrets Manager) for production credentials. 4) Implement pre-commit hooks to prevent credential commits. 5) Regularly audit Git history for accidentally committed secrets using tools like git-secrets or TruffleHog.
• High · Dependency Version Constraints Are Too Permissive — .github/scripts/package.json. The package.json uses caret (^) version constraints for dependencies like '@octokit/rest': '^21.0.0' and 'axios': '^1.13.5'. This allows automatic minor and patch version updates without explicit review, which could introduce security vulnerabilities or breaking changes. Axios has had multiple security vulnerabilities in the past. Fix: 1) Use exact version pinning (remove ^ and ~) for production dependencies. 2) Implement automated dependency scanning with tools like Dependabot or Snyk. 3) Regularly audit dependencies with 'npm audit'. 4) Consider using npm shrinkwrap or lock files to ensure reproducible builds. 5) Establish a process for reviewing and testing dependency updates before deployment.
• Medium · Missing Security.md Implementation Details — SECURITY.md. While SECURITY.md exists and provides a vulnerability reporting process (email to info@greptime.com), it lacks specific details on security practices, patch timelines, and supported versions beyond v0.1.0. The security policy is minimal and doesn't address key security concerns or development practices. Fix: Expand SECURITY.md to include: 1) Specific timeframes for security patch releases. 2) Details on the security review process for contributions. 3) Information about security scanning in CI/CD pipeline. 4) Guidelines for secure coding practices. 5) Expected response times for vulnerability reports. 6) Historical security advisories if any exist.
• Medium · GitHub Actions Workflow Security Configuration — .github/actions/. Multiple custom GitHub Actions are defined in .github/actions/ directory. While not visible in full detail, custom actions can pose security risks if they execute untrusted code, use insecure checkout practices, or handle secrets improperly. The presence of actions like 'deploy-greptimedb' and 'build-and-push-ci-image' suggest privileged operations. Fix: 1) Audit all custom GitHub Actions for secure practices (avoid 'run' with untrusted input). 2) Use 'pull_request_target' carefully to prevent credential exposure in PRs from forks. 3) Implement branch protection rules requiring approval before deployment. 4) Rotate any credentials used in CI/CD immediately if exposed. 5) Review GitHub Actions permissions in .github/workflows files - use least privilege principle. 6) Consider using OIDC for authentication instead of long-lived credentials.
• Medium · Docker Build Configuration Not Fully Visible — Dockerfile(s) - not provided in analysis. The repository contains multiple Docker-related files and actions (.dockerignore, build-greptime-images, build-dev-builder-images) but the actual Dockerfile content and Docker build configurations are not provided for analysis. This could hide security issues like running as root, using untrusted base images, or including sensitive files. Fix: 1) Ensure Dockerfile runs processes as non-root user. 2) Use specific base image versions (avoid 'latest' tags). 3) Implement multi-stage builds to minimize final image size. 4) Scan Docker images for vulnerabilities using tools like Trivy or Grype. 5) Exclude sensitive files via .dockerignore. 6) Remove build dependencies from final image. 7) Implement image signing and verification.
• Low · Incomplete .env.example File — undefined. The .env.example file appears to be truncated (ends with 'GT_FUZ' without completion), which could indicate incomplete documentation or a copy-paste error. Fix: undefined

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/GreptimeTeam/greptimedb 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 GreptimeTeam/greptimedb repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/GreptimeTeam/greptimedb.

What it runs against: a local clone of GreptimeTeam/greptimedb — 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 GreptimeTeam/greptimedb | 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 GreptimeTeam/greptimedb. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/GreptimeTeam/greptimedb.git
#   cd greptimedb
#
# 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 GreptimeTeam/greptimedb and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "GreptimeTeam/greptimedb(\\.git)?\\b" \\
  && ok "origin remote is GreptimeTeam/greptimedb" \\
  || miss "origin remote is not GreptimeTeam/greptimedb (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 "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f ".github/workflows/develop.yml" \\
  && ok ".github/workflows/develop.yml" \\
  || miss "missing critical file: .github/workflows/develop.yml"
test -f ".github/actions/build-greptime-binary/action.yml" \\
  && ok ".github/actions/build-greptime-binary/action.yml" \\
  || miss "missing critical file: .github/actions/build-greptime-binary/action.yml"
test -f ".cargo/config.toml" \\
  && ok ".cargo/config.toml" \\
  || miss "missing critical file: .cargo/config.toml"
test -f ".config/nextest.toml" \\
  && ok ".config/nextest.toml" \\
  || miss "missing critical file: .config/nextest.toml"

# 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/GreptimeTeam/greptimedb"
  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.