New runner-images job and CLI command

Author: kdeldycke

.github/workflows/autofix.yaml

@@ -65,6 +65,29 @@ jobs:
           HAS_VIRUSTOTAL_API_KEY: ${{ secrets.VIRUSTOTAL_API_KEY && 'true' || '' }}
         run: uv --no-progress run --frozen -- repomatic setup-guide
 
+  runner-images:
+    name: 🖥️ Runner images
+    # Schedule-only: the announcements come from actions/runner-images, so they
+    # change on GitHub's clock rather than on any push here, and a weekly read
+    # is well inside the months of notice a deprecation carries. Not gated
+    # against workflow_call: called that way the job runs in the caller's
+    # context and manages the caller's own issue. See
+    # repomatic/runner_images.py for why the announcement feed is the source.
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-slim
+    permissions:
+      issues: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.12.1"
+      - name: Manage runner images issue
+        env:
+          GH_TOKEN: ${{ secrets.REPOMATIC_PAT || github.token }}
+          REPOMATIC_PAT: ${{ secrets.REPOMATIC_PAT }}
+        run: uv --no-progress run --frozen -- repomatic runner-images
+
   metadata:
     name: 🧬 Project metadata
     # Skipping this job propagates to every `needs: metadata` job below, so the

changelog.md

@@ -8,6 +8,7 @@
 - Teach the `repomatic-ship` skill to reconcile bundled skills and agents as a third pass, judge a false-positive autofix PR against current `main` before writing a lint rule for it, and tell a superseded intra-cycle measurement from a genuine contradiction.
 - **Breaking:** the `update-dep-graph` job moved from `autofix.yaml` into the release engine, its only firing moment being a release push. A required check or `needs:` edge naming it under Autofix must follow.
 - **Breaking:** manual version-bump commits now read `` [changelog] Bump minor version to `vX.Y.0` ``: every version-machinery commit carries the `[changelog] ` prefix, and anything matching the old unprefixed titles must follow.
+- New `runner-images` job and CLI command, opening an issue that lists GitHub's open runner-image announcements and flags the ones retiring or affecting an image the repo runs on.
 - Autofix jobs no longer run on version-bump pushes: the 16 remaining jobs only re-checked machine-generated, ship-gated commits, and drift stays covered by the next push and the weekly sweep.
 - The tool runner now retries a download up to 3 times on transient network failures, instead of failing the job on a one-off TLS or truncation error.
 - Standalone binary tests now run for every healthy target when a sibling build fails, instead of being skipped wholesale.

docs/repomatic.md

@@ -326,6 +326,15 @@
    :undoc-members:
 ```
 
+## `repomatic.runner_images` module
+
+```{eval-rst}
+.. automodule:: repomatic.runner_images
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```
+
 ## `repomatic.setup_guide` module
 
 ```{eval-rst}

docs/tests.md

@@ -405,6 +405,15 @@
    :undoc-members:
 ```
 
+## `tests.test_runner_images` module
+
+```{eval-rst}
+.. automodule:: tests.test_runner_images
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```
+
 ## `tests.test_setup_guide` module
 
 ```{eval-rst}

docs/workflows.md

@@ -71,6 +71,14 @@ This workflow runs on every push to `main` and on a **weekly schedule** so quiet
   - upstream `kdeldycke/repomatic` repo, `workflow_call` events
   - `setup-guide = false` in `[tool.repomatic]`
 
+#### 🖥️ Runner images (`runner-images`)
+
+- Reads the open `Announcement`-labelled issues of [`actions/runner-images`](https://github.com/actions/runner-images/issues?q=is%3Aissue+is%3Aopen+label%3AAnnouncement), which cover both newly available images and images entering deprecation, and maintains a single issue listing them
+- Sorts an announcement to the top and names the image in an **Affects** column when it acts on a runner the repo runs on, read from the announcement's `Possible impact` section so a migration *destination* is never reported as affected
+- Nothing bumps a `runs-on:` value automatically (Dependabot rewrites `uses:` references, `sync-workflow-pins` rewrites version literals), so a retirement otherwise arrives as a failing build with no warning
+- Automatically closes the issue once GitHub has closed every open announcement
+- **Runs on**: the weekly schedule and manual `workflow_dispatch` only, since the feed changes on GitHub's clock rather than on any push here
+
 *Formatters* — rewrite files to enforce canonical style:
 
 #### 🐍 Format Python (`format-python`)

repomatic/cli.py

@@ -160,6 +160,7 @@
 from .init_project import run_init
 from .labels import apply_labels
 from .lint_repo import (
+    KNOWN_RUNNERS,
     run_repo_lint,
 )
 from .mailmap import Mailmap, remove_header
@@ -188,6 +189,7 @@
     parse_component_entries,
     valid_file_ids,
 )
+from .runner_images import manage_runner_images_issue
 from .setup_guide import manage_setup_guide
 from .sync_ops import (
     OPERATIONS_BY_NAME,
@@ -2008,6 +2010,30 @@ def broken_links(
     )
 
 
+@repomatic.command(
+    short_help="Manage runner image announcements issue", section=_section_github
+)
+@_require_token(_token_mod, "validate_gh_token_env")
+def runner_images() -> None:
+    """Report GitHub's open runner image announcements as an issue.
+
+    Reads the Announcement-labelled issues of actions/runner-images, which cover
+    both newly available images and images entering deprecation, and maintains a
+    single issue listing them. Announcements naming an image this repository
+    runs on are sorted first and flagged.
+
+    Nothing bumps a runs-on: value automatically, so a retirement otherwise
+    lands as a failing build with no warning.
+
+    Requires the gh CLI to be installed and authenticated.
+
+    \b
+    Example:
+        repomatic runner-images
+    """
+    manage_runner_images_issue(KNOWN_RUNNERS)
+
+
 @repomatic.command(
     short_help="Manage setup guide issue lifecycle", section=_section_github
 )