Skip to content

docs: describe the four agent tools as pinned, not always-latest #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gatezh merged 3 commits into from
Aug 14, 2026
Merged

docs: describe the four agent tools as pinned, not always-latest #120

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dc4ae52
docs: describe the four agent tools as pinned, not always-latest
gatezh Aug 14, 2026
5e3e203
docs: note the Mend Interactive-mode requirement for Renovate
gatezh Aug 14, 2026
06b5275
docs: name the actual Mend portal toggles, not "Interactive mode"
gatezh Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,32 @@ Images from this repository are built and published to GitHub Container Registry

## Updating Image Versions

### Automatically, via Renovate

The agent tooling in the `claude-code` and `ralphex-fe` images — `rtk`, `ralphex`, the Claude Code
CLI, and `agent-browser` — is pinned as `ARG`s carrying `# renovate:` annotations. Renovate watches
their releases and opens a single grouped bump PR when one ships; CI verifies it, it auto-merges, and
that merge rebuilds the affected images. No upstream release means no PR and no rebuild. Scope and
grouping live in [`.github/renovate.json5`](./.github/renovate.json5); the Dependency Dashboard
issue tracks what is pending. Everything else — including base images and Bun/Hugo — stays manual.

> **Setup requirement — Mend portal toggles.** Installing the Renovate app with "All repositories"
> makes Mend default the repo to **Silent mode** (`dryRun=lookup`), where it scans and shows updates
> in the [developer portal](https://developer.mend.io/) but opens no PRs and creates no issues — not
> even the Dependency Dashboard, and not even a config-warning issue. The symptom is a correct
> config that appears to do nothing. In the portal, under *Repo Engine Settings → Dependency
> Updates*, set:
>
> | Toggle | Value |
> |--------|-------|
> | Silent mode | **off** |
> | Automated PRs | **on** |
> | Require config file | on — with an all-repositories install, this is what keeps Renovate off repos that have no config |
> | Create onboarding PRs | off — this repo already has a config, so no onboarding PR is needed |
>
> Setting `mode` in `renovate.json5` cannot substitute for the Silent-mode toggle, because `dryRun`
> takes precedence over `mode` and is admin-level.

### Via GitHub UI

Some images have automated update workflows that allow you to update dependency versions without manually editing Dockerfiles:
Expand Down
12 changes: 9 additions & 3 deletions claude-code/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Projects consume these pre-built images and control their own tool versions via
| Shell | Fish, Starship, fzf | Built-in syntax highlighting, autosuggestions, completions |
| Tools | git-delta, gh CLI, jq, nano, vim, wget, unzip, less, man-db, procps, openssh-client | Standard dev utilities (`openssh-client` provides `ssh`/`ssh-keygen` — enables SSH-format commit signing) |
| Mise | The tool manager itself (not the tools) | Projects run `mise install` at container creation for their tool versions |
| rtk, ralphex | Always-latest from GitHub Releases | Dev infrastructure (like Claude Code) — no version pinning needed in projects |
| rtk, ralphex | Pinned `ARG`s, bumped by Renovate on each GitHub release | Dev infrastructure (like Claude Code) — the image tracks the versions so projects don't have to |
| Claude Code | npm global install | npm avoids rate limiting that affects the native installer in parallel CI builds |

**Both targets:** system Chromium + `fonts-freefont-ttf` (used by Playwright and the Playwright MCP plugin via `/usr/bin/chromium`)
Expand Down Expand Up @@ -76,7 +76,7 @@ Projects consuming these images need the following files in their repository.

### Required: `.mise.toml` (project root)

Only pin tools that affect project stability — dev infrastructure (rtk, ralphex, Claude Code) is pre-installed in the image at latest. See [`mise.toml`](mise.toml) for a template.
Only pin tools that affect project stability — dev infrastructure (rtk, ralphex, Claude Code) is pre-installed in the image, which tracks their releases for you. See [`mise.toml`](mise.toml) for a template.

### Optional: `.devcontainer/init-plugins.sh`

Expand Down Expand Up @@ -405,7 +405,13 @@ cat ~/.claude/plugins/cache/claude-plugins-official/playwright/*/.mcp.json
| Arg | Default | Description |
|-----|---------|-------------|
| `GIT_DELTA_VERSION` | `0.18.2` | git-delta version |
| `AGENT_BROWSER_VERSION` | `latest` | agent-browser version (default target only) |
| `RTK_VERSION` | `0.43.0` | rtk version (Renovate-managed) |
| `RALPHEX_VERSION` | `1.6.0` | ralphex version (Renovate-managed) |
| `CLAUDE_CODE_VERSION` | `2.1.216` | Claude Code CLI version (Renovate-managed) |
| `AGENT_BROWSER_VERSION` | `0.32.3` | agent-browser version, default target only (Renovate-managed) |

The four Renovate-managed args carry `# renovate:` annotations in the Dockerfile; edit them by
hand only for a local build. Bumps land as auto-merged PRs — see [Automatic Rebuilds](#automatic-rebuilds).

## Building Locally / Local Fallback

Expand Down
22 changes: 19 additions & 3 deletions ralphex-fe/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,15 @@ This is a standalone image, not a devcontainer.
| Go | for Hugo Modules |
| Python 3 | system |
| Playwright + Chromium | native Debian |
| Claude Code CLI | latest |
| RTK | latest (GitHub Releases) |
| Ralphex | latest (GitHub Releases) |
| Claude Code CLI | 2.1.216 (pinned) |
| RTK | 0.43.0 (pinned) |
| Ralphex | 1.6.0 (pinned) |
| Git, ripgrep, jq, curl, wget | system |

The pinned versions live as `ARG`s in the Dockerfile and are kept current by Renovate — see
[Automatic Rebuilds](#automatic-rebuilds). Bun and Hugo are bumped manually via the
`update-and-build-ralphex-fe.yml` workflow.

## Usage

### Via ralphex docker-wrapper
Expand Down Expand Up @@ -63,6 +67,18 @@ docker build -t ralphex-fe:test ralphex-fe/

Note: this image deviates from the standalone convention of a single primary version tag because it bundles multiple independently-versioned tools.

## Automatic Rebuilds

The image rebuilds when one of its pinned tools — Claude Code, rtk, or ralphex — publishes a
new release: Renovate opens a version-bump PR against the `ARG`s in the Dockerfile, CI verifies
it, it auto-merges, and that merge triggers the build. No upstream release means no rebuild —
there is no longer a daily cron. Manual rebuilds run from the "Run workflow" button on
**Build ralphex-fe** in the Actions tab.

Because the version tag is derived from Bun and Hugo only, an agent-tool bump refreshes
`latest` and *overwrites* the existing `bun{VERSION}-hugo{VERSION}` tag rather than creating a
new one. Pull `latest` if you want the current agent tools.

## Architecture / Provenance

| File / Pattern | Source |
Expand Down