Strengthen AGENTS.md image-sync guidance and make drift-issue workflow dispatch-only + configurable

[Copilot]

In PR #445 the coding agent needed multiple maintainer nudges to complete an image-variant sync — it edited only primary templates (missing indirect references) and dismissed a genuinely new version as an alias. This PR hardens the AGENTS.md sync playbook so those failure modes don't recur, and additionally makes the automated drift-tracking issue workflow safer and more flexible.

AGENTS.md sync-playbook hardening

Fan-out to indirect references

Added a "One image change fans out to several templates" section covering the three ways a template references an image, since the checker scans all of them:

• Primary — own options.imageVariant.proposals.
• Dependent — Dockerfile builds FROM devcontainers/<image>:...-${templateOption:imageVariant} (javascript-node-mongo/-postgres → javascript-node; rust-postgres → rust; ruby-rails-postgres → ruby); edit in lockstep.
• Hardcoded pins — static base:<os> with no imageVariant option (docker-in-docker, docker-outside-of-docker, docker-outside-of-docker-compose, kubernetes-helm, kubernetes-helm-minikube, markdown); repoint the literal tag.

UNUSED is not always noise

Reworked the UNUSED guidance to scan for a genuinely new concrete {version}-{os} variant (e.g. Go 1.27) rather than blanket-dismissing the list, with manifest.json cross-checks to separate real versions from floating/OS-only/-jdk aliases.

Reinforced iteration

Editing rule #1 and the validation section now cross-reference the fan-out guidance and require re-running the checker until zero MISSING remain across all templates.

Drift-tracking issue workflow

Configurable assignee

The report-drift-issue.sh script and check-image-tags.yaml workflow now accept an optional assignee input / ASSIGNEE_LOGIN env var — assign the drift issue to a specific GitHub user, defaulting to the Copilot coding agent when empty.

Dispatch-only issue creation

The report-drift-issue job now runs only on workflow_dispatch (previously schedule OR workflow_dispatch). Scheduled runs still detect drift but no longer auto-open issues.

Best-effort, non-fatal assignment

Assignment is now best-effort: the issue is created first, and if the actor id can't be resolved or the assignment mutation fails, the script emits a ::warning:: and exit 0 (issue left unassigned) rather than failing the run.

Files changed

• AGENTS.md — sync-playbook guidance (docs only).
• .github/workflows/check-image-tags.yaml — dispatch-only job + assignee input.
• build/report-drift-issue.sh — configurable assignee + best-effort assignment.

Note: this PR is no longer docs-only — it now also touches the workflow and drift-issue script.

[Copilot]

🟡 Changes recommended

Two moderate script issues and three nit-level documentation/workflow issues remain unresolved.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Strengthens image-sync guidance and makes drift-issue creation dispatch-only, configurable, and best-effort.

Changes:

• Documents indirect references, UNUSED variants, and full-template validation.
• Adds configurable assignees and non-fatal assignment handling.
• Restricts issue creation to manual dispatches.

File summaries

File	Changes and review comments
build/report-drift-issue.sh	Adds configurable assignment and best-effort handling. Moderate (2 votes): update issue text to reflect manual dispatch rather than scheduled creation. Moderate (1 vote): safely pass the login into jq as data.
AGENTS.md	Expands image-sync and validation guidance. Nit (3 votes): correct the scheduled-workflow description. Nit (1 vote): require validation across all templates.
.github/workflows/check-image-tags.yaml	Adds an assignee input and dispatch-only issue reporting. Nit (1 vote): rename the job to avoid implying Copilot is always assigned.

Review details

Suppressed comments (5)

.github/workflows/check-image-tags.yaml:68

• The job's displayed name remains "Report Drift and Assign to Copilot" even though this input now permits a different assignee, so manual runs assigned to another user are mislabeled in the Actions UI. Rename it to a neutral name such as "Report Drift and Assign".

    # Only run on manual dispatch - never on schedule/PRs/pushes, so we don't open
    # issues automatically. Scheduled runs skip this job.
    if: github.event_name == 'workflow_dispatch'

AGENTS.md:177

• The validation instruction immediately above still scopes the requirement to “templates you touched” (lines 165–166). That permits leaving missing indirect or hardcoded references elsewhere, which is the failure mode this new fan-out section is intended to prevent; make the requirement explicitly cover all templates.

A successful sync produces **zero MISSING** tags. Remaining UNUSED tags are expected and
acceptable (they are mostly intentional aliases) — but first confirm none of them is a
genuinely new concrete `{version}-{os}` variant that should have been added. If the checker
still reports MISSING tags, you have not covered every referencing template yet (commonly a
missed dependent or hardcoded pin); fix those and **re-run until MISSING is empty**. Finish

build/report-drift-issue.sh:129

• suggestedActors(first:100) is a bounded suggestion list, not a lookup by login. A valid assignable user supplied through assignee can be outside these 100 nodes and will be treated as unassignable, so the new configuration silently fails. Resolve a custom login directly or paginate until the requested actor is found before warning.

            suggestedActors(capabilities:[CAN_BE_ASSIGNED], first:100) {
                nodes { login __typename ... on Bot { id } ... on User { id } }
            }
        }
    }' --jq ".data.repository.suggestedActors.nodes[] | select(.login==\"${TARGET_ASSIGNEE}\") | .id" || true)"

build/report-drift-issue.sh:141

• The new best-effort handling only wraps the assignment mutation; the issue_id GraphQL lookup immediately above still runs under set -e. If that lookup has a transient failure after issue creation, the script exits nonzero instead of warning and leaving the issue unassigned. Guard this lookup with the same warning/exit 0 behavior.

if ! gh api graphql -f assignableId="$issue_id" -f actorId="$actor_id" -f query='

build/report-drift-issue.sh:129

• The workflow-dispatch value is interpolated directly into the --jq expression. A value containing jq syntax can change the filter and select a different actor (or make resolution fail), so pass the login as data (for example via jq --arg) and compare against that variable instead.

    }' --jq ".data.repository.suggestedActors.nodes[] | select(.login==\"${TARGET_ASSIGNEE}\") | .id" || true)"

• Files reviewed: 3/3 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Kaniska (v-Kaniska244)]

Copilot check the following comments,

In build/report-drift-issue.sh:
The generated issue body still says "The scheduled Compare Templates against Images workflow detected differences" (lines 47–48), but this job now creates issues only from manual dispatch. That makes every newly created issue describe the wrong trigger; update the body to distinguish scheduled detection from manual issue creation.

This issue also appears in the following locations of the same file:

• line 125
• line 141

In AGENTS.md:
The new dispatch-only workflow leaves the description above saying the scheduled workflow opens the tracking issue. Scheduled runs now only perform the checks, while report-drift-issue runs only for workflow_dispatch; please update this sentence so the playbook does not tell agents to expect an issue from a scheduled run.

[Copilot]

Copilot check the following comments,

In build/report-drift-issue.sh:
...

Fixed in fe0ece4: the generated issue body in build/report-drift-issue.sh now says it was opened manually via workflow_dispatch and clarifies that scheduled runs only detect drift, and AGENTS.md no longer implies the scheduled workflow opens the tracking issue.