🚀 [Feature]: Track downstream action-version bumps with a central tracking issue and per-consumer sub-issues

[MariusStorhaug]

When a shared PSModule action is released (e.g. GitHub-Script v1.9.0), every downstream repository that pins it needs a follow-up version bump. The v1.9.0 rollout touched 14 repositories — some bumped by Dependabot, some by manually opened PRs — and there was no single place to see how far the rollout had progressed. A maintainer had to open each repository's pull request individually to know what had merged and what was still outstanding.

Request

Desired capability

When an action is updated, open a central tracking issue on the action's own repository that enumerates every downstream consumer and shows live rollout progress (for example "9 of 14 done") that advances on its own as each consumer's bump pull request merges — with no manual checkbox bookkeeping.

A maintainer looking at the action repository should be able to see, for a given release, which consumers still need the bump, which are in review, and which are done — as a native progress bar that updates automatically.

Acceptance criteria

• One tracking issue per action release, on the action repository, listing all known downstream consumers.
• Each consumer's bump is represented as an item that reflects real state (open / merged).
• The tracking issue shows an automatic completion count / progress bar.
• Progress advances without manual checkbox toggling as bump pull requests merge.
• Works whether a bump pull request is opened by Dependabot or by an agent / maintainer.

Note

Motivating rollout: the GitHub-Script v1.9.0 bump across 14 repositories (Debug, Get-IssueFormData, Get-PesterCodeCoverage, Get-PesterTestResults, Get-PSModuleSettings, Initialize-PSModule, Invoke-Pester, Invoke-ScriptAnalyzer, Release-GHRepository, Template-Action, docs, GoogleFonts, NerdFonts, Process-PSModule).

---

Technical decisions

A pull request cannot be a sub-issue — use an issue anchor. Verified 2026-07-10 against the REST API: POST /repos/{owner}/{repo}/issues/{n}/sub_issues with a pull request's REST id returns 404 Not Found; the endpoint accepts only issues. Cross-repository issue sub-issues do work (verified even on a personal account). Each consumer therefore needs a small anchor issue, and the pull request is tied to the rollout indirectly through that anchor.

The flow (one per consumer):

1. Create an anchor issue in the consumer repository (e.g. "Bump <action> to vX.Y.Z").
2. Open the bump pull request in the consumer repository with Closes #<anchor> (same-repository closing keyword — reliable; cross-repository keyword auto-close is not dependable).
3. Add the anchor issue as a cross-repository sub-issue of the central tracking issue: POST /repos/{action-owner}/{action-repo}/issues/{tracker}/sub_issues -F sub_issue_id=<anchor issue REST db id> — the numeric REST id (not the issue number, not the GraphQL node id), sent typed with -F.
4. On merge, the pull request closes its anchor → the tracker's sub_issues_summary ({ total, completed, percent_completed }) advances.

flowchart LR
  subgraph ACTION["Action repo (e.g. GitHub-Script)"]
    R["Release vX.Y.Z"]
    T["Central tracking issue"]
    R --> T
  end

  subgraph CONSA["Consumer repo A"]
    PA["Bump PR"]
    IA["Anchor issue"]
    PA -- "Closes #a" --> IA
  end

  subgraph CONSB["Consumer repo B"]
    PB["Bump PR"]
    IB["Anchor issue"]
    PB -- "Closes #b" --> IB
  end

  T -- "cross-repo sub-issue" --> IA
  T -- "cross-repo sub-issue" --> IB
  IA -. "merged → closed → progress +" .-> T
  IB -. "merged → closed → progress +" .-> T

Loading

Central tracker location = the action repository. The release is the trigger, and keeping the tracker on the action itself makes the action's downstream impact visible from where the change originated. This complements — it does not replace — the existing convention of housing broad framework-migration trackers in Process-PSModule (e.g. #337, #369); those are not tied to a single action release.

Dependabot wrinkle. Dependabot opens many of these bump pull requests and its PR body is not templatable, so it cannot add Closes #<anchor>. Two options:

• a small "close the anchor when a matching bump PR merges" workflow (match by the dependencies + github_actions labels and the action name in the title), or
• agent / maintainer-driven bumps that set Closes directly (the model used by the ai-platform downstream-release-propagation flow).

Recommendation: implement the close-on-merge workflow so the Dependabot-native path also drives progress. Note #359 (stop Dependabot applying semver release labels) affects how the matcher identifies these PRs.

Progress aggregate lags. sub_issues_summary is denormalized and trails actual sub-issue state by a few seconds; any status/report step must re-query rather than trust the first read.

Alternative considered — a task list of PR references (- [ ] owner/repo#PR in the tracker body): lighter (no anchor issues) but gives no reliable auto-updating progress bar, and cross-repository PR references render inconsistently. Rejected in favor of sub-issues.

Input — which consumers need bumping. Reuse the enumeration proven during the v1.9.0 rollout: scan every non-archived org repository's action.yml and .github/workflows/** for PSModule/<action>@<sha> (a deterministic GraphQL HEAD:-tree scan; plain code search has index gaps). Related: #329 (pinned-SHA drift detection) can feed this consumer list.

Validation evidence (throwaway test repos)

Verified end-to-end in MariusStorhaug/verprop-test-action (tracking issue #1) and MariusStorhaug/verprop-test-consumer:

Attempt	Result
Same-repo issue as sub-issue	✅ works
Cross-repo issue as sub-issue (personal account)	✅ works
Cross-repo pull request as sub-issue	❌ 404 Not Found

After a consumer pull request carrying Closes #<anchor> merged, the tracker reported { "total": 2, "completed": 1, "percent_completed": 50 }.

Related to the dependency-management epic #356.

---

Implementation plan

Enumeration

• Add a reusable step that lists downstream consumers of an action by scanning action.yml + .github/workflows/** for PSModule/<action>@<sha> across non-archived org repositories.

Tracking issue + anchors

• On action release, open the central tracking issue on the action repository (title includes action name + version).
• For each consumer, create an anchor issue in the consumer repository and attach it as a cross-repository sub-issue (sub_issue_id = anchor REST db id, sent with -F).

Bump pull requests

• Ensure agent / maintainer-opened bump PRs include Closes #<anchor>.
• Add a workflow that closes the matching anchor issue when a Dependabot bump PR for the action merges (match by title + dependencies/github_actions labels), so Dependabot-origin bumps also drive progress.

Progress + closeout

• Use sub_issues_summary for status reporting, allowing for aggregation lag (re-query).
• Close the central tracking issue automatically when all anchors are closed.

Documentation

• Document the pattern (anchor-issue model, why PRs cannot be sub-issues, the Dependabot close-on-merge workflow). Port to the ai-platform downstream-release-propagation specification once its release-management restructuring settles.

[MariusStorhaug]

Reworked the architecture diagram: nodes are now grouped into per-repository subgraph boxes (Action repo, Consumer repo A / B) so it is visually clear what lives where, instead of encoding the repo in each node label. Only the diagram changed.

[MariusStorhaug]

Finding from applying this to the GitHub-Script v1.9.0 rollout

I tried to apply this pattern to the v1.9.0 rollout (tracker: PSModule/GitHub-Script#99) and hit a prerequisite the spec does not currently call out.

The anchor-issue model requires GitHub Issues to be enabled on every consumer repo — but 4 of the 14 consumers have Issues disabled.

hasIssuesEnabled across the 14 consumers:

Issues enabled (10)	Issues disabled (4)
Debug, Get-IssueFormData, Invoke-Pester, Invoke-ScriptAnalyzer, Release-GHRepository, Template-Action, docs, GoogleFonts, NerdFonts, Process-PSModule	Get-PesterCodeCoverage, Get-PesterTestResults, Get-PSModuleSettings, Initialize-PSModule

Consequences:

• POST /repos/{consumer}/issues returns "repository has disabled issues", so no anchor can be created in those repos.
• Closes #<anchor> only auto-closes an issue in the same repo as the PR, so the anchor must live in the consumer repo; hosting it elsewhere loses the auto-close.
• Most awkwardly, the single outstanding bump in this rollout (Bump PSModule/GitHub-Script from 1.7.10 to 1.9.0 Initialize-PSModule#50) is in an Issues-disabled repo — the item that most needs live tracking is exactly the one the pattern cannot anchor.

Recommendation

Add an explicit step to the implementation plan: verify/enable Issues on each consumer before creating its anchor (PATCH /repos/{owner}/{repo} with has_issues=true), or define a fallback for Issues-disabled consumers (host the anchor in the action repo and drive it via the close-on-merge workflow rather than Closes #). Note that 10/14 consumers have Issues enabled and 4 do not, so some leaf repos may keep Issues disabled deliberately — whether to auto-enable is a policy decision worth recording here.

What I did for now

I did not change any repo settings (asked, but unavailable to confirm). Tracker PSModule/GitHub-Script#99 records the rollout as a task list (13/14 done; Initialize-PSModule outstanding via #50). Once enabling Issues on those 4 repos is confirmed, #99 can be converted to the full cross-repository sub-issue model with the native progress bar.