aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
RFC: Automated toolchain version monitoring and upgrade workflow
- Dominant language
- TypeScript
- Stars
- 143
- Forks
- 46
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 20
Description
## Problem
Several runtime dependencies in the agent Dockerfile and `pyproject.toml` are manually pinned with no automated notification when new versions are available:
| Dependency | Current Pin | Update Frequency | Risk of Stale |
|---|---|---|---|
| Node.js | `setup_24.x` (LTS) | ~6 months (LTS cycle) | Medium |
| Claude Code CLI | `@anthropic-ai/claude-code@2.1.142` | Weekly+ | High |
| claude-agent-sdk | `claude-agent-sdk==0.2.82` | Weekly+ (bundles CLI) | **High** |
| boto3 | `boto3==1.43.6` | Weekly (AWS SDK releases) | **High** |
| Go (gh builder) | `golang:1.26.3-bookworm` | ~6 months | Low |
| gh CLI | `GH_VERSION=2.92.0` | Monthly | Low |
| Python base | `python:3.13-slim` | ~12 months | Low |
| uv | `ghcr.io/astral-sh/uv:0.11.14` | Multiple times/week | Medium |
### Key coupling: claude-agent-sdk ↔ Claude Code CLI
The `claude-agent-sdk` Python package **bundles** the Claude Code CLI binary inside its wheel. The Dockerfile also installs the CLI separately via npm. These versions **must stay in sync**:
- `pyproject.toml`: `claude-agent-sdk==0.2.82` → bundles CLI 2.1.142
- `Dockerfile`: `@anthropic-ai/claude-code@2.1.142`
When upgrading either, check the [SDK release notes](https://github.com/anthropics/claude-agent-sdk-python/releases) to find which CLI version it bundles, then update both.
### boto3 releases frequently
AWS releases `boto3` multiple times per week. Each release adds new service APIs and bug fixes. Falling behind risks missing security patches and new features needed for AgentCore/Bedrock.
## Proposal
### Option A: Dependabot (recommended)
Dependabot is GitHub-native (no license concerns) and covers the ecosystems that matter most:
| Ecosystem | Directory | What it monitors | Value |
|---|---|---|---|
| `github-actions` | `/.github/workflows/` | SHA-pinned action versions (7 actions) | **Highest** — nothing else does this |
| `docker` | `/agent/` | `FROM` image tags (golang, python) | **High** — Trivy flags CVEs but doesn't propose base-image bumps |
| `npm` | `/` | Yarn workspace dependencies | **Moderate** — osv-scanner/Retire cover CVEs but not freshness |
| `pip` | `/agent/` | pyproject.toml + uv.lock ([supported](https://docs.github.com/en/code-security/reference/supply-chain-security/supported-ecosystems-and-repositories)) | **High** — covers boto3, claude-agent-sdk, fastapi, etc. |
### Option B: Scheduled GitHub Action (for Dockerfile pin gaps)
Dependabot cannot parse version strings inside `RUN` commands or `ARG` values. A weekly Action would cover:
1. **Claude Code CLI**: compare `@anthropic-ai/claude-code@X` vs `npm view @anthropic-ai/claude-code version`
2. **claude-agent-sdk**: compare pinned vs latest [SDK release](https://github.com/anthropics/claude-agent-sdk-python/releases) and extract bundled CLI version
3. **gh CLI**: compare `GH_VERSION` ARG vs latest `cli/cli` release
4. **uv**: compare pinned COPY tag vs latest `astral-sh/uv` release
5. Opens an issue when versions drift, noting the coupling between SDK and CLI
### What each tool covers
| Dependency | Dependabot? | Custom Action? | Notes |
|---|---|---|---|
| claude-agent-sdk | Yes (pip) | Yes (coupling check) | Dependabot bumps the pin; Action verifies CLI alignment |
| Claude Code CLI (Dockerfile) | No | Yes | Inside `RUN` command, not parseable |
| boto3 | Yes (pip) | No | Standard Dependabot pip coverage |
| Node.js (Dockerfile) | No | Possible | Inside `curl` command, not parseable |
| Go builder image | Yes (docker) | No | `FROM golang:X` tag |
| Python base image | Yes (docker) | No | `FROM python:X` tag |
| gh CLI (ARG) | No | Yes | `ARG GH_VERSION=X` not parseable |
| uv (COPY --from) | Yes (docker) | No | `COPY --from=ghcr.io/astral-sh/uv:X` is a docker ref |
| GitHub Actions | Yes (github-actions) | No | SHA pins auto-bumped |
| npm deps (CDK, CLI, docs) | Yes (npm) | No | Yarn workspace coverage |
## Implementation Plan
- [ ] Add `.github/dependabot.yml` with `github-actions`, `docker`, `npm`, and `pip` ecosystems
- [ ] Configure grouping (e.g., group minor/patch boto3 updates, group AWS SDK updates)
- [ ] Set `open-pull-requests-limit` per ecosystem to manage PR noise
- [ ] Create scheduled Action for Dockerfile pin monitoring (Claude Code CLI ↔ SDK coupling, gh, Node)
- [ ] Document the SDK ↔ CLI coupling in AGENTS.md or CONTRIBUTING.md
## Related Issues
- #105 — Upgrade Python 3.13 → 3.14
- #106 — Upgrade Debian bookworm → trixie
- PR #103 — Node.js 20→24, Claude Code 2.1.142, pin uv 0.11.14, claude-agent-sdk 0.2.82
## References
- [Node.js release schedule](https://nodejs.org/en/about/previous-releases)
- [claude-agent-sdk releases](https://github.com/anthropics/claude-agent-sdk-python/releases)
- [Dependabot Docker support](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#docker-ecosystem)
- [Dependabot GitHub Actions support](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#github-actions)
- [Dependabot pip/uv.lock support](https://docs.github.com/en/code-security/reference/supply-chain-security/supported-ecosystems-and-repositories)
Contributor guide
Research direction
Start by inspecting the agent Dockerfile, pyproject.toml, existing workflows under /.github/workflows/, and the dependency layout under /agent/. Review the Dependabot ecosystem coverage and the planned scheduled Action, especially the claude-agent-sdk and Claude Code CLI coupling. Done means the Dependabot configuration, monitoring workflow, and coupling documentation are implemented as described in the checklist.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, docker, github-actions, node.js, python
- Domain
- ci-cd, devops, security, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100