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/line/armeria 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.

GO — Healthy across the board

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

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "line/armeria(\\.git)?\\b" \\
  && ok "origin remote is line/armeria" \\
  || miss "origin remote is not line/armeria (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"

# 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/line/armeria"
  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).

Armeria is a reactive microservice framework built on Netty that lets you build gRPC, Thrift, REST, and WebSocket services with Java/Kotlin/Scala using a unified API. It handles protocol bridging, load balancing, circuit breaking, and request/response transformation out of the box—solving the fragmentation problem of choosing between different RPC frameworks for each service. Monorepo organized by feature domains: core Armeria server runtime, multiple transport modules (gRPC, Thrift, HTTP/2), client libraries (Retrofit integration), Spring Boot/Dropwizard plugins, and an AI/MCP module (ai/mcp/src/main/java/com/linecorp/armeria/server/ai/). Build uses Gradle with Gradle Enterprise integration (.github/workflows/gradle-enterprise-postjob.yml) for distributed caching.

Backend engineers and platform teams building microservices at scale who want to support multiple RPC protocols (gRPC, Thrift, REST) without rewriting core business logic, and who need production-grade observability and resilience patterns without vendor lock-in.

Production-ready and actively maintained. The repo shows 25M+ lines of Java code, extensive CI/CD workflows (.github/workflows/ contains 8+ active pipelines), and contributors from LINE Corporation (creator of Netty). Maven Central releases and Gradle Enterprise integration indicate mature release practices.

Low risk for core framework usage. However, the monorepo is large with many integrations (Spring Boot, Dropwizard, gRPC, Thrift, Kotlin, Reactive Streams) meaning breaking changes in one subsystem could affect dependent code; check CHANGELOG carefully before minor version upgrades. The .github/workflows/xds-*.yml files suggest active XDS API syncing which could introduce compatibility shifts.

Active development visible in: (1) XDS API sync workflows (xds-sync-apis.yml, xds-compare-versions.yml, xds-apply-updates.yml) suggesting gRPC load balancing improvements, (2) AI/MCP module under ai/mcp/ for Claude integration, (3) Regular dependency updates via Dependabot (.github/dependabot.yml), (4) Release automation with tag-new-release.yml and publish-release.yml workflows.

Clone and build with Gradle: git clone https://github.com/line/armeria.git && cd armeria && ./gradlew build. Requires Java 8+. See CONTRIBUTING.md for developer guide link at https://armeria.dev/community/developer-guide/

Daily commands: This is a framework library, not a runnable service. Build with ./gradlew build. Run tests with ./gradlew test. For examples, check example directories referenced in the file structure (implied by the mention of 'examples/' in the README snippet). The .post-release-msg and release automation suggest using Maven Central: add com.linecorp.armeria:armeria to your pom.xml or build.gradle.

• .github/workflows/publish-release.yml: Defines the release pipeline; understanding this is critical for cutting releases and understanding version management.
• README.md: Entry point documenting the project's purpose, links to armeria.dev, community chat, and contributor list.
• CONTRIBUTING.md: Developer onboarding guide; points to the official developer guide and contribution workflow.
• .github/CODEOWNERS: Defines code ownership by module; essential for knowing who reviews which subsystems.
• ai/mcp/build.gradle: Represents the newest module (AI/MCP integration); inspect for cutting-edge build patterns and dependencies.
• .github/mergify.yml: Configures automated PR merging rules; understanding merge criteria is important for PR workflow.
• .github/dependabot.yml: Defines automated dependency update strategy; critical for understanding how the project manages transitive dependencies.

For protocol support: modify files under core/ and language-specific modules (grpc/, thrift/, kotlin/). For server features: edit server/ modules. For client features: client/ modules. For Spring/Dropwizard integration: spring/ and dropwizard/ directories. For documentation: files in root and site/ (implied by publish-site.yml workflow). Start by examining .claude/skills/ for existing patterns in release-notes and dependency upgrades.

No obvious required environment variables detected in the file list, but: (1) Gradle Enterprise features are integrated (.github/workflows/gradle-enterprise-postjob.yml) and may require GE credentials for full caching; (2) XDS API sync workflows suggest you need gRPC ecosystem tools installed locally if working on load balancing features; (3) The monorepo is large—Gradle builds can be slow without proper JVM tuning; (4) .scalafmt.conf presence means Scala code requires scalafmt for formatting; (5) Multiple test suites including e2e-chaos-tests.yml may require Docker or Kubernetes local setup.

• Protocol Bridging — Armeria's core innovation is allowing a single service to speak multiple RPC protocols (gRPC, Thrift, REST) simultaneously; understanding how requests are translated between wire formats is essential for debugging protocol-level issues.
• Async/Reactive Request Handling — Armeria is built on Netty and Reactive Streams, meaning all handlers are asynchronous; blocking calls in handlers will degrade performance—you must understand CompletableFuture and Publisher semantics.
• Decorator Pattern for Cross-Cutting Concerns — Armeria uses decorators extensively for auth, metrics, tracing, and logging; learning this pattern is critical for adding observability or custom middleware to services.
• gRPC Load Balancing with XDS — The active XDS sync workflows indicate Armeria is tracking gRPC's evolving load balancing API; understanding xDS (Service Discovery) is important for production deployments using Armeria's load balancer.
• Thrift IDL Code Generation — Armeria supports Thrift services; understanding how Thrift IDL compiles to Java stubs and how Armeria wraps them is necessary for Thrift integrations.
• Circuit Breaker & Resilience Patterns — Armeria includes built-in circuit breaking and retry logic for client calls; understanding failure modes and how to configure them prevents cascade failures in microservice architectures.
• Gradle Build Caching & Daemon Tuning — The Gradle Enterprise integration and large monorepo mean build performance is a real concern; understanding Gradle caching and daemon configuration is necessary to keep local development fast.

• grpc/grpc-java — Armeria wraps and extends gRPC; understanding grpc-java internals is essential for protocol-level debugging.
• apache/thrift — Armeria provides first-class Thrift protocol support; familiarity with Thrift IDL and code generation helps with Thrift service integration.
• netty/netty — Armeria is built on Netty; the creator of Armeria also created Netty, and understanding Netty's channel pipeline and lifecycle is crucial for performance tuning.
• spring-projects/spring-boot — Armeria has dedicated Spring Boot integration modules; teams using Armeria with Spring will reference spring-boot for dependency and auto-configuration patterns.
• ReactiveX/RxJava — Armeria uses Reactive Streams patterns extensively; RxJava knowledge helps understand async request/response handling in Armeria.

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 integration tests for ArmeriaStatelessServerTransport with various gRPC/Thrift protocols

The ai/mcp module has test coverage for stateless and streamable transports, but there are no cross-protocol integration tests. Given Armeria's multi-protocol support (gRPC, Thrift, etc.), adding tests that verify MCP server transport works correctly with different protocol implementations would ensure robustness across the framework's primary use cases.

• [ ] Create ai/mcp/src/test/java/com/linecorp/armeria/server/ai/mcp/ArmeriaGrpcProtocolIntegrationTests.java
• [ ] Create ai/mcp/src/test/java/com/linecorp/armeria/server/ai/mcp/ArmeriaThriftProtocolIntegrationTests.java
• [ ] Test ArmeriaStatelessServerTransport and ArmeriaStreamableServerTransport against both protocol stacks
• [ ] Verify serialization/deserialization of MCP messages across protocol boundaries

Implement GitHub Actions workflow for automated MCP server transport compliance testing

The .github/workflows directory has workflows for release, e2e-chaos-tests, and xds operations, but there's no dedicated CI workflow for the new ai/mcp module. Adding a specific workflow would ensure MCP transport changes are validated against the Model Context Protocol specification before merging.

• [ ] Create .github/workflows/mcp-compliance-tests.yml that runs on PRs targeting ai/mcp/**
• [ ] Configure the workflow to run all tests in ai/mcp/src/test/java with Gradle
• [ ] Add validation step to verify ArmeriaStatelessServerTransport and ArmeriaStreamableServerTransportProvider build correctly
• [ ] Integrate with existing gradle-cache-check.yml pattern for consistency

Add comprehensive JavaDoc and package-level documentation for ai/mcp module

The ai/mcp module has a package-info.java file but lacks detailed API documentation explaining the stateless vs streamable transport patterns, builder patterns, and integration examples. Given Armeria's focus on being a 'go-to microservice framework,' this module needs clear guidance for users adopting MCP support.

• [ ] Expand ai/mcp/src/main/java/com/linecorp/armeria/server/ai/mcp/package-info.java with architectural overview and code examples
• [ ] Add detailed JavaDoc to ArmeriaStatelessServerTransport explaining when to use stateless vs streamable patterns
• [ ] Add JavaDoc to ArmeriaStatelessServerTransportBuilder and ArmeriaStreamableServerTransportProviderBuilder with builder pattern examples
• [ ] Create ai/mcp/README.md with setup instructions, configuration options, and migration guide from standard MCP servers

• Add missing JavaDoc to public methods in the ai/mcp/ module (ai/mcp/src/main/java/) since this is a newly integrated component and likely lacks comprehensive API documentation compared to core modules.
• Update CONTRIBUTING.md with concrete examples of running a single test suite and debugging a specific protocol (gRPC vs Thrift) to match the Developer Guide link referenced but not expanded in the repo.
• Expand the .claude/skills/release-note/references/style-guide.md with Armeria-specific examples of good release notes (referencing actual recent releases) to make it more actionable for new contributors doing release notes.

The Armeria microservice framework demonstrates a generally secure development posture with established CI/CD workflows and dependency management via Dependabot. However, there are moderate concerns regarding unpinned dependency versions in GitHub Actions (which could allow uncontrolled updates), and TypeScript scripts that execute GitHub API operations without explicit security documentation. The framework itself appears well-maintained with security-conscious design (supporting multiple protocols like gRPC and Thrift). Primary recommendations include pinning exact dependency versions, implementing stricter governance around GitHub Actions scripts, and ensuring default security headers are configured. The overall security score reflects a mature project with proper governance structures but minor areas for hardening.

• Medium · Outdated TypeScript and ts-node Dependencies — .github/actions/package.json. The GitHub Actions workflow uses ts-node ^10.9.1 and dependencies without pinned versions. ts-node and related dependencies may have known vulnerabilities. The caret (^) allows minor and patch updates which could introduce breaking changes or security issues. Fix: Pin exact versions of dependencies (remove ^) or use npm audit to identify vulnerable versions. Regularly update and audit dependencies using npm audit fix. Consider using Dependabot for automated updates.
• Medium · GitHub Actions Using Octokit Without Version Pin — .github/actions/package.json. The octokit dependency (^3.1.2) is specified with a caret, allowing any minor/patch version. This could introduce breaking changes or security vulnerabilities when automatically updated. Fix: Pin the octokit version to a specific version (e.g., 3.1.2 without ^). Regularly audit and test dependency updates before deploying.
• Low · Potential Script Injection in GitHub Actions — .github/actions/package.json, .github/actions/post-release.ts, .github/actions/comment-build-scan.ts. The package.json contains scripts that execute TypeScript files (post-release.ts and comment-build-scan.ts) from the .github/actions directory. These scripts interact with GitHub APIs and could potentially be exploited if source code is compromised or dependencies are hijacked. Fix: Implement strict code review processes for workflow scripts. Use GitHub branch protection rules to require reviews before merging to main. Consider using GitHub's official actions instead of custom TypeScript scripts where possible. Implement least-privilege access for GitHub tokens used in actions.
• Low · Missing Security Headers Configuration — Core framework configuration (not visible in provided files). While the codebase structure shows a microservice framework (Armeria), there is no visible default security headers configuration in the provided file structure. Common security headers (CSP, HSTS, X-Frame-Options) may not be enforced by default. Fix: Ensure that Armeria server configurations include security headers by default. Document security best practices for framework users, including how to configure headers like Content-Security-Policy, Strict-Transport-Security, X-Frame-Options, and X-Content-Type-Options.
• Low · No Evidence of SBOM or Dependency Tracking — Root directory / Build configuration. The provided file structure shows a complex microservice framework with multiple dependencies (gRPC, Thrift, Spring Boot, Dropwizard, Netty). However, no SBOM (Software Bill of Materials) file is visible, which could make vulnerability tracking difficult. Fix: Generate and maintain a Software Bill of Materials (SBOM) using tools like CycloneDX or SPDX. Include this in CI/CD pipelines and security scanning workflows.

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

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

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