---
description: "Guided, gated workflow to pin/standardize Docker image tags one service at a time, using the repo inventory + update report."
---

# Prompt

When the user types `/standardize-image-tags-one-by-one`, run a *service-by-service* workflow to pin and standardize Docker image tags across this repo’s Compose files.

This repo includes:

- Inventory: `.github/knowledge/inventory.md`
- Latest upstream report: `documentation/reports/service-update-report-2025-12-13.md`

## Non-negotiables

- One service at a time.
- Use explicit confirmation gates. Do **not** proceed past gates without the user typing the required confirmation phrase.
- Never ask for secrets or paste secrets into files.
- Do not add new features or refactor unrelated stacks.

## Definitions

- **Service**: a logical app in the inventory/report (e.g., `traefik`, `dozzle`, `gitea`).
- **Compose service**: an item under `services:` in a specific `compose.yaml`.
- **Pinned**: image uses a specific tag or digest (not `latest`, not an unbounded tag like `stable` unless the user explicitly accepts that).

## Workflow (must follow in order)

### Gate 0 — pick the target service

Ask the user to choose exactly one service to process.

- Offer to suggest candidates prioritized by risk:
  1. `:latest`
  2. env-var driven tags (e.g. `${VAR:-latest}`)
  3. known-outdated tags

**Required confirmation phrase**:

- User must reply exactly: `TARGET: <service-name>`

Do not proceed until this is received.

### Step 1 — locate all relevant Compose definitions

For the selected service:

1. Find where it appears in Compose (`**/compose.y*ml`).
2. Identify all images and tags that correspond to that service.
3. List the exact file paths and the current configured image strings.

Also note if the service is:

- referenced via `.env` / `${VAR}`
- part of an `include:` aggregate

**Gate 1 — confirm current state**

Present a short summary:

- Current image(s)
- File(s) to change
- Whether the current version is pinned or floating

**Required confirmation phrase**:

- User must reply exactly: `CONFIRM CURRENT: <service-name>`

### Step 2 — determine the target tag and risk

Use `documentation/reports/service-update-report-2025-12-13.md` as the default source of “latest upstream”.

- If report lists **unknown upstream** or a **non-GitHub/unparseable** source, stop and ask the user whether to:
  1. leave as-is
  2. pin to an explicit existing tag they choose

Perform a lightweight risk check:

- Major version jumps (e.g., `v3 -> v4`) or large gaps
- Stateful services (databases, identity, git, media libraries)
- Notes in the report (e.g., “uses :latest”, “env-var driven”)

Propose one of these outcomes:

- **Pin** to latest upstream tag
- **Pin** to latest patch in current major/minor line (safer)
- **Keep** current tag (with rationale)

**Gate 2 — approve target**

Show:

- Proposed new image string(s)
- Migration/rollback considerations (1–3 bullets max)

**Required confirmation phrase**:

- User must reply exactly: `APPROVE TARGET: <service-name> -> <new-tag>`

### Step 3 — prepare the minimal change

Implement the smallest possible change.

Preference order:

1. Replace `image: repo/name:latest` with a pinned tag.
2. If the repo uses env-var tags:
   - prefer pinning by setting a default like `${VAR:-<pinned>}`
   - or updating a shared `.env.example` / `group_vars` file (never `.env`)

Do not change unrelated services.

**Gate 3 — apply patch**

Before editing, show the exact file(s) and the exact before/after line(s).

**Required confirmation phrase**:

- User must reply exactly: `APPLY PATCH: <service-name>`

Only then, apply the change.

### Step 4 — bounce and verify (user-run)

After edits, provide copy/paste commands for the user to run on the Docker host.

- Prefer the most specific compose invocation for that stack.
- If the environment lacks `docker compose`, suggest `bash tools/compose.sh ...`.

Verification requires the user to paste back:

- `docker ps --filter name=<container>` (or equivalent)
- `docker logs --tail=200 <container>` for the changed service
- If behind Traefik: a relevant Traefik log excerpt for that router (only if failing)

**Gate 4 — confirm healthy**

Do not proceed until the user replies exactly:

- `CONFIRM HEALTHY: <service-name>`

If it is **not** healthy, stop and troubleshoot *only that service* until it is.

### Step 5 — commit/roll forward

Ask whether to commit the change now.

- If yes, generate a Conventional Commit message (e.g., `chore(<service>): pin image tag to <tag>`).
- Remind to ensure no `.env` files are staged.

**Gate 5 — next service**

Ask if they want to continue.

Required phrase to continue:

- `NEXT`

If not `NEXT`, stop.

## Output format

- Use short headings and compact bullets.
- Put terminal commands in fenced code blocks with `bash`.
- When referencing repo files/symbols, wrap them in backticks.