[downstream] add downstream updates-needed internal workflow draft

[github-actions]

Summary

This PR adds an internal downstream update-check workflow that reviews data/downstream-users.json entries for elastic/* and strawgate/*, compares workflow refs to the latest elastic/ai-github-actions release, and reports required updates by repository.

It also updates the downstream inventory workflow prompt so collected entries retain structured workflow_file, uses_target, and ref metadata, adds a scheduled/dispatch trigger workflow for the updates-needed check, and updates docs to list gh-aw-downstream-updates-needed as an internal-only workflow under .github/workflows/.

Context

Fixes #245.

---

What is this? | From workflow: PR Body Update Agent

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

Summary by CodeRabbit

• New Features

  • Automated system to check and report when downstream repositories require updates; runs on a weekday schedule and creates issues with recommendations.

• Documentation

  • Updated documentation to reflect new internal workflows for downstream update tracking.

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Adds a scheduled trigger and an analyzer workflow that reads downstream repository workflow entries (elastic/, strawgate/), validates a new object-based data model including explicit refs, compares refs against recommended/latest versions, and files per-repo issues listing required updates.

Changes

Cohort / File(s)	Summary
New Downstream Update Workflows .github/workflows/gh-aw-downstream-updates-needed.md, .github/workflows/trigger-downstream-updates-needed.yml	Adds an analyzer workflow that validates downstream data, determines per-entry update status (floating major, pinned semver, branch, SHA, other), and files issues; adds a scheduled/dispatch trigger that calls the analyzer.
Downstream Data Capture .github/workflows/gh-aw-downstream-users.md	Changes downstream data model from a flat string list to objects with workflow_file, uses_target, and ref; updates extraction, sorting, deduplication, and UTC timestamp/output formatting.
Documentation / Developer Notes DEVELOPING.md, gh-agent-workflows/DEVELOPING.md	Marks the new workflow as internal-only and documents fragment locations and internal-only workflow shims; updates references to two internal workflows.

Sequence Diagram

sequenceDiagram
    actor Scheduler
    participant Trigger as Trigger Workflow
    participant Analyzer as Downstream Analyzer
    participant Data as data/downstream-users.json
    participant Registry as Action Registry (latest/recommended)
    participant Issues as GitHub Issues

    Scheduler->>Trigger: scheduled/dispatch
    Trigger->>Analyzer: workflow_call + COPILOT_GITHUB_TOKEN
    Analyzer->>Data: read downstream repos (elastic/*, strawgate/*)
    Analyzer->>Analyzer: validate object model (workflow_file, uses_target, ref)
    Analyzer->>Registry: fetch latest_version & recommended_floating_major per uses_target
    Analyzer->>Analyzer: compute recommended_ref and reason per entry
    Analyzer->>Issues: create repo-scoped issue with table of findings (or noop if all up to date)
    Issues-->>Analyzer: issue created / noop acknowledged

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• Workflow Drift for gh-aw-release-update and gh-aw-downstream-users #235: The gh-aw-downstream-users data model change (capturing explicit refs) and internal workflow adjustments align with this issue's concerns about downstream data extraction and internal workflow placement.

Possibly related PRs

• Upgrade gh-aw compiler to v0.47.4 with inline prompts #240: Overlaps changes to gh-aw downstream workflows and the downstream-users schema; likely touching the same workflow files and data model.

Poem

🐇 I hopped through workflows, neat and spry,
Found refs and versions, gave them a try,
I nudged a polite issue, left a carrot note,
Repos now tidy — on nimble feet I float,
Hooray for updates! 🌿

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch main-ea5419f6b2f26abd

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Verdict: request changes.

---

What is this? | From workflow: PR Review Agent

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not. for issue #253

[github-actions]

🟠 HIGH: Insufficient issue permission for configured output

This workflow enables safe-outputs.create-issue, but the declared permission is issues: read, which prevents issue creation at runtime.

Suggested change

	issues: read
	issues: write

[github-actions]

🟠 HIGH: Trigger points to a missing reusable workflow

This job references .github/workflows/gh-aw-downstream-updates-needed.lock.yml, but that file is not present in this PR. As written, scheduled/dispatch runs will fail immediately because the called workflow cannot be resolved.

Please include the compiled lock file in this change (or defer adding this trigger until the lock file exists).

[github-actions]

CI run 22246424487 failed in Verify compiled workflows during make compile for .github/workflows/gh-aw-downstream-updates-needed.md.

Root cause from logs: generated lock YAML had a duplicate key (GH_AW_GITHUB_REPOSITORY) at lines 428 and 429, which caused generated lock file is not valid YAML and compile failure (make: *** [Makefile:137: compile] Error 1).

I did not push a fix because this PR is already closed; recommended remediation is to edit .github/workflows/gh-aw-downstream-updates-needed.md to avoid duplicate $\{\{ github.repository }} env emission (e.g., replace one occurrence with a different expression source) and re-run make compile && make lint-workflows.

---

What is this? | From workflow: PR Checks Fixer

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.