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/aws/aws-sdk-ruby 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 all four use cases

• Last commit 1d ago
• 8 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 76% of recent commits
• ⚠ No test directory detected

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

What it runs against: a local clone of aws/aws-sdk-ruby — 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 aws/aws-sdk-ruby | 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 version-3 exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of aws/aws-sdk-ruby. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/aws/aws-sdk-ruby.git
#   cd aws-sdk-ruby
#
# 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 aws/aws-sdk-ruby and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "aws/aws-sdk-ruby(\\.git)?\\b" \\
  && ok "origin remote is aws/aws-sdk-ruby" \\
  || miss "origin remote is not aws/aws-sdk-ruby (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 version-3 >/dev/null 2>&1 \\
  && ok "default branch version-3 exists" \\
  || miss "default branch version-3 no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"
test -f "apis" \\
  && ok "apis" \\
  || miss "missing critical file: apis"
test -f "V3_UPGRADING_GUIDE.md" \\
  && ok "V3_UPGRADING_GUIDE.md" \\
  || miss "missing critical file: V3_UPGRADING_GUIDE.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 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/aws/aws-sdk-ruby"
  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).

The official AWS SDK for Ruby (v3), a modular client library that allows Ruby developers to programmatically interact with 200+ AWS services via generated API bindings. It provides credential management, endpoint resolution, request signing, paginator support, and waiters through a unified Ruby interface, with individual service gems available (aws-sdk-s3, aws-sdk-ec2, etc.) rather than a monolithic dependency. Monorepo structure: aws-sdk-core (gems/aws-sdk-core) provides the base HTTP client, credential chains, endpoint resolution, and middleware. Individual service gems live in gems/aws-sdk-{service} and are code-generated from JSON specifications in apis/{service}/{version}/ (containing api-2.json, docs-2.json, endpoint-rule-set-1.json, paginators-1.json, waiters-2.json). Shared workflows (.github/workflows/) handle CI, benchmarking, changelog generation, and dependency reviews.

Ruby application developers building on AWS infrastructure who need to call AWS APIs from their Ruby code; DevOps engineers automating infrastructure; contributors maintaining AWS service client generation pipelines. Users range from startups using individual service gems to enterprises using the unified aws-sdk gem.

Production-ready and actively maintained. The repo shows 247M lines of Ruby code, comprehensive CI/CD pipelines (.github/workflows/), extensive API coverage (apis/ directory with 200+ services), and clear v3 versioning strategy. Last activity and issue/PR handling indicate active development, though no specific commit date is visible in provided data.

Low technical risk due to AWS ownership and wide adoption, but monorepo complexity means changes to core code (aws-sdk-core) affect all service gems. Service APIs are auto-generated from JSON specs (apis/**/api-2.json), so generation bugs cascade broadly. Single-vendor dependency on AWS API definitions is inherent; breaking changes in AWS API specs could require SDK version bumps.

Active CI/CD with workflows for pull-request builds, benchmarking, changelog generation, stale issue handling, and dependency review. .github/workflows/ shows recent automation additions (closed-issue-message.yml, issue-regression-labeler.yml, depsreview.yaml). Dependabot integration suggests continuous dependency updates. No specific open PR or milestone data visible, but tooling maturity suggests ongoing maintenance.

git clone https://github.com/aws/aws-sdk-ruby.git
cd aws-sdk-ruby
bundle install
# For core development, modify gems/aws-sdk-core/
# For service-specific work, modify gems/aws-sdk-{service}/

Daily commands: No single 'server' to run—this is a client library. After bundle install: run tests with rake spec (inferred from Rakefile); run benchmarks via .github/workflows/benchmark.yml; generate docs with yard. Individual service gems can be tested: cd gems/aws-sdk-s3 && bundle exec rspec.

• README.md — Entry point describing the AWS SDK for Ruby V3 architecture, modularization strategy, and installation instructions that frame all development work.
• Gemfile — Defines core dependencies and build requirements for the entire SDK; changes here affect all service gems.
• .github/workflows/ci.yml — Primary CI/CD pipeline defining test execution, validation, and release criteria for all commits and PRs.
• apis — Root directory containing API definitions (JSON schemas) for all 200+ AWS services; the source-of-truth for code generation.
• V3_UPGRADING_GUIDE.md — Documents the migration strategy from V2 to V3 and breaking changes; essential for understanding the modularized architecture.
• CONTRIBUTING.md — Contributor guidelines covering workflow, testing standards, and submission process for all changes.
• Rakefile — Build automation and task definitions for code generation, testing, and gem packaging.

Add support for a new AWS service or service version

1. Create service directory under apis/ with subdirectory for API version date (e.g., apis/newservice/2024-01-15/) (apis)
2. Add api-2.json containing the complete API definition with operations, shapes, metadata, and error definitions (apis/newservice/2024-01-15/api-2.json)
3. Add docs-2.json with human-readable documentation strings for all operations and shapes (apis/newservice/2024-01-15/docs-2.json)
4. Add paginators-1.json if service supports pagination; define output tokens, input tokens, and result keys (apis/newservice/2024-01-15/paginators-1.json)
5. Add waiters-2.json if service has long-running operations; define waiter conditions and polling behavior (apis/newservice/2024-01-15/waiters-2.json)
6. Add endpoint-rule-set-1.json defining regional endpoints and endpoint discovery rules (apis/newservice/2024-01-15/endpoint-rule-set-1.json)
7. Run rake task (via Rakefile) to generate service client gem from these API definitions (Rakefile)

Update service API definition for new operations or shapes

1. Locate the service's api-2.json file (e.g., apis/ec2/2016-11-15/api-2.json) (apis)
2. Add new operation shape and definition to the api-2.json operations section; include input/output references (apis/ec2/2016-11-15/api-2.json)
3. Add corresponding documentation string in service's docs-2.json for the new operation (apis/ec2/2016-11-15/docs-2.json)
4. If operation supports pagination, add pagination config to paginators-1.json (apis/ec2/2016-11-15/paginators-1.json)
5. Run code generation via Rakefile to regenerate the service client gem with the new operation (Rakefile)

Release a new version of the SDK

1. Update version strings in gem specifications and gemspec files (Gemfile)
2. Create or update CHANGELOG entries documenting new features, fixes, and breaking changes (README.md)
3. Run full test suite via CI pipeline (ci.yml) to validate all changes across all service gems (.github/workflows/ci.yml)
4. Automated changelog workflow processes git history and PR labels to generate release notes (.github/workflows/changelog.yml)
5. Rake release task (Rakefile) tags the release, builds gems, and publishes to RubyGems (Rakefile)

• Ruby — Primary language for the SDK; enables idiomatic Ruby API design for AWS service clients
• JSON API schemas (api-2.json) — Declarative, versioned API definitions sourced from AWS service specs; enables code generation and API consistency
• Modularized gem structure — Allows users to install only required service gems (aws-sdk-s3, aws-sdk-ec2) rather than monolithic SDK; reduces dependency bloat
• GitHub Actions workflows — Provides CI/CD automation for testing, building, publishing, and managing dependency updates
• RuboCop static analysis — Enforces consistent code quality and style across generated service clients

• V3 modularization (separate gems per service vs. monolithic SDK)

  • Why: Users complained about bloated dependencies in V2; V3 separates concerns into individual service gems
  • Consequence: Reduced memory footprint and faster load times for applications using few services, but increased complexity for management tooling and version coordination

• Code generation from JSON schemas rather than hand-written clients

  • Why: AWS has 200+ services with frequent API updates; generation ensures consistency and reduces maintenance burden
  • Consequence: Generated code may be less optimized per-service; custom logic difficult to embed without re-generation

• RubyGems as distribution mechanism

  • Why: Standard Ruby package distribution; seamless integration with Bundler and existing Ruby workflows
  • Consequence: Dependency version conflicts possible; requires careful semver management across interdependent gems

• Does not implement AWS service logic; only provides client interface to call AWS APIs
• Does not handle authentication or credential management directly (delegated to aws-sdk-core gem)
• Not a real-time event streaming SDK (request/response only, no WebSocket support)
• Does not provide CLI tools; focus is programmatic SDK only

Code generation is non-obvious: Service gem code is NOT hand-written—never edit gems/aws-sdk-{service}/lib/aws-sdk-{service}/client.rb directly; changes are overwritten on next generation. Credential chain complexity: SDK auto-detects credentials from ENV, ~/.aws/credentials, ~/.aws/config, EC2 instance metadata, ECS container credentials, and Web Identity tokens in order; test credential loading carefully. Endpoint resolution is rule-based: endpoints are derived from endpoint-rule-set-1.json files, not hardcoded; regional variants and custom endpoints require understanding Smithy endpoint rules. Breaking changes between v2 and v3: V3_UPGRADING_GUIDE.md exists for good reason—method signatures, error handling, and plugin architecture changed substantially. Monorepo release cadence: All service gems version together; a bug fix in one service requires bumping all gems.

• Middleware/Plugin Architecture — The SDK chains middleware for request signing, retry logic, logging, and validation; understanding Aws::Plugins and the middleware stack is essential for customizing SDK behavior without patching core code
• Credential Precedence Chain — The SDK auto-detects credentials from multiple sources (env vars, config files, instance metadata, Web Identity) in a specific order; developers must understand precedence to avoid credential leaks or unexpected auth failures
• Smithy Service Specifications — Service gems are code-generated from JSON specifications (api-2.json, paginators-1.json, waiters-2.json) in apis/; understanding Smithy models is critical for understanding why the SDK is structured as it is
• Endpoint Resolution Rules — Endpoints are determined dynamically via endpoint-rule-set-1.json, not hardcoded; this enables cross-region failover, partition awareness, and custom endpoints without SDK updates
• Async Request Signing — AWS request signing (SigV4) must happen after body serialization but before transmission; the SDK's middleware handles this transparently but custom middleware must respect signing order
• Paginators and Waiters — Pagination and polling logic is service-specific and generated from paginators-1.json and waiters-2.json; understanding how the SDK auto-generates these helpers vs. hand-coded ones affects API usage patterns
• Code Generation from Specifications — Service gems are auto-generated artifacts, not hand-maintained; this enables rapid AWS API releases but means changes must flow through the generation pipeline (Rakefile, code-generator) not direct file edits

• aws/aws-sdk-go — Official AWS SDK for Go; parallel implementation in different language, shares same API specifications (apis/) and service model generation approach
• aws/aws-sdk-python — Official AWS SDK for Python (Boto3); similar modular structure and uses same underlying Smithy service specifications
• aws/smithy — AWS's service specification framework and code generator; aws-sdk-ruby service gems are generated from Smithy models in the apis/ directory
• hashicorp/aws-sdk-ruby-rails — Rails integration for AWS SDK; commonly paired with aws-sdk-ruby in Rails applications for S3, SQS, SNS, and other AWS service integration
• aws/aws-cdk-examples — AWS CDK examples often pair with aws-sdk-ruby for infrastructure provisioning (CDK) + runtime operations (SDK)

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 integration tests for endpoint resolution across all AWS services

The repo contains endpoint-rule-set-1.json and endpoint-tests-1.json files for every service in the apis/ directory, but there's no evidence of a unified test suite validating endpoint resolution logic. Given the complexity of endpoint selection (regions, dual-stack, FIPS compliance), a new integration test harness would ensure consistency across 200+ AWS services and catch regressions when endpoint rules are updated.

• [ ] Create spec/integration/endpoint_resolution_spec.rb to load and validate endpoint-tests-1.json files from apis///
• [ ] Implement test case generator that parses endpoint-tests-1.json test cases and verifies endpoint resolution matches expected outputs
• [ ] Add CI workflow step in .github/workflows/ci.yml to run endpoint integration tests and fail if any service's endpoint rules fail validation
• [ ] Document the new test pattern in CONTRIBUTING.md for maintainers updating service APIs

Create a smoke test validation framework for example-1.json service examples

Every service has examples-1.json files (200+ services visible in apis/*/), but there's no automated validation that these examples are syntactically correct and match actual SDK method signatures. A smoke test framework would catch stale examples when APIs are updated and ensure documentation examples work.

• [ ] Create lib/aws-sdk/tools/example_validator.rb to parse examples-1.json files and validate JSON structure
• [ ] Build spec/unit/example_validator_spec.rb with tests ensuring examples have required fields (service, operation, input, output)
• [ ] Add Rake task in Rakefile: task :validate_examples that runs validator against all apis/*/ directories
• [ ] Integrate into .github/workflows/ci.yml to fail PR if any service examples are malformed

Add waiter and paginator implementation coverage gaps analyzer

The apis/ directory shows waiters-2.json and paginators-1.json files exist for many services, but without a manifest, it's unclear which services are missing implementations. A coverage report would help prioritize which service generators need waiter/paginator support added to lib/aws-sdk/

• [ ] Create tools/coverage_analyzer.rb script to inventory all services with waiters-2.json and paginators-1.json in apis/
• [ ] Compare against generated gem files in gems/aws-sdk-*/ to identify services with spec files but no implementation
• [ ] Generate COVERAGE_REPORT.md documenting waiter/paginator implementation gaps (e.g., '45 services have waiters spec but no gem implementation')
• [ ] Add documentation to CONTRIBUTING.md explaining how to implement missing waiters/paginators using the analyzer report

• Add missing documentation for Aws::Credentials loaders in gems/aws-sdk-core/lib/aws-sdk-core/credential*. Currently no inline YARD docs for SSO credential provider chain steps—document the order of precedence and ENV var overrides.
• Write integration tests (in features/) validating Smithy endpoint rule evaluation against endpoint-tests-1.json for 3-5 services; currently endpoint-rule-set-1.json is generated but not systematically validated in SDK tests.
• Audit and document required environment variables for CI workflows (.github/workflows/ci.yml, pull-request-build.yaml): which ones need AWS_* credentials, which are GitHub-specific? Create a CONTRIBUTING.md section for local development setup.

The AWS SDK for Ruby repository demonstrates good security practices with automated dependency management via Dependabot and CI/CD workflows. However, several areas require attention: (1) A formal security policy document is missing, (2) GitHub Actions workflows need audit for credential handling, (3) Regular dependency vulnerability scanning should be enforced, (4) API definition files should be reviewed to ensure no sensitive data exposure. The codebase shows no obvious hardcoded credentials in the visible file structure, and the use of JSON configuration files for APIs is standard practice. Overall security posture is good but could be strengthened with documented security policies and enhanced SCA practices.

• Medium · Dependency Management via Dependabot — .github/dependabot.yml, Gemfile. While Dependabot is configured (.github/dependabot.yml), there is no visible evidence of dependency pinning strategies or security audit mechanisms in the provided file structure. The SDK depends on external packages that may introduce vulnerabilities. Fix: Ensure all dependencies are regularly audited using 'bundle audit' or 'bundler-audit'. Implement strict version pinning for critical dependencies and maintain a security vulnerability policy.
• Low · API JSON Files Exposure — apis/ directory structure. The repository contains numerous API definition JSON files (apis///api-2.json) that may contain endpoint information, parameter definitions, and service specifications. While not directly sensitive, this information could aid attackers in reconnaissance. Fix: Review API definition files to ensure no credentials, API keys, or sensitive endpoint configurations are hardcoded. Ensure documentation doesn't expose internal implementation details that could be exploited.
• Low · Missing Security Policy Documentation — Repository root. No visible SECURITY.md file was found in the repository structure, which is important for vulnerability reporting and security best practices disclosure. Fix: Create a SECURITY.md file following GitHub's recommended format (https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository) to establish a responsible disclosure policy.
• Low · Workflow Security - GitHub Actions — .github/workflows/ directory. Multiple GitHub Actions workflows are configured (.github/workflows/). Without visibility into their content, there's potential risk of credential exposure, insecure checkout practices, or privilege escalation. Fix: Audit all GitHub Actions workflows for: (1) Use of secrets management, (2) Principle of least privilege in permissions, (3) Pinned action versions, (4) Secure artifact handling.
• Low · Third-party Integration Dependencies — Gemfile, gem dependencies. The SDK integrates with AWS services and depends on multiple dependencies. Transitive dependency vulnerabilities could affect the SDK without direct detection. Fix: Implement Software Composition Analysis (SCA) tools. Use 'bundle outdated' and 'bundle audit' regularly. Monitor security advisories for all direct and transitive dependencies.

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.