homelab/.github/prompts/service-standardize.prompt.md

description

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.