Summary

The workflow YAML emitted for agentics maintenance (scheduled close of expired entities + maintenance workflow_dispatch operations) is fully generated and, on regeneration / compiler upgrade, can emit runs-on values aimed at GitHub-hosted-style runner labels (e.g. ubuntu-slim).

Downstream repositories that only allow self-hosted runners must manually patch the generated file after every regeneration to restore self-hosted labels. That is repetitive, easy to miss in review, and conflicts with how markdown-sourced workflows can steer framework jobs via runs-on-slim and the self-hosted runners guide.

This issue asks for either a supported configuration path or first-class documentation so self-hosted-only fleets are not dependent on undocumented manual edits.

Analysis

1. Two generation paths

   • Markdown-defined agentic workflows expose top-level runs-on-slim (and related runner controls) so compiled runs-on matches org runner fleets.
   • The maintenance workflow is produced by a separate code path (see pkg/workflow/maintenance_workflow.go and tests in pkg/workflow/maintenance_workflow_test.go) and does not go through the same frontmatter knobs as typical .md workflows.

2. Operational gap

   • After gh aw upgrade or compile, teams that require self-hosted-only may see runs-on revert to defaults that do not match their runner labels. There is no documented, generator-level knob analogous to runs-on-slim for this file.

3. Request type

   • This is primarily an enhancement (config or generator behavior), with a documentation fallback if the project intentionally requires manual edits.

Proposed behavior

Minimum: Document the regeneration pitfall and a clear post-upgrade checklist for self-hosted-only orgs.

Ideal: Provide a supported way to emit runs-on for all jobs in the generated maintenance workflow that is stable across regenerations, for example:

• Reuse the same runs-on-slim (or successor) semantics as other framework workflows; or
• A small config surface (CLI flag, project config file, or documented env) read by maintenance_workflow generation; or
• Emit runs-on: [self-hosted, <label>] when a documented condition is met.

Exact shape is up to maintainers; the goal is no silent revert to GitHub-hosted-only labels for fleets that forbid them.

Implementation plan (for core team / agent)

1. Confirm current behavior

   • Trace pkg/workflow/maintenance_workflow.go (and call sites) to see how runs-on is set today and what defaults apply after compile / upgrade.

2. Compare with existing runner UX

   • Align behavior or documentation with runs-on-slim / framework job behavior documented under docs/src/content/docs/guides/self-hosted-runners.md so one mental model applies.

3. Choose an approach

   • Option A — Code: Add a generator input (or reuse an existing global runner setting) so maintenance workflow jobs use the same runner policy as the rest of a repo’s gh-aw config.
   • Option B — Docs only: If manual edit remains required, document why, add an upgrade checklist, and optionally emit a header comment in the generated file warning self-hosted-only users.

4. Tests

   • Extend pkg/workflow/maintenance_workflow_test.go (or adjacent tests) so a configured runner label / mode appears in generated YAML and does not regress on regen.

5. Documentation

   • Update the self-hosted runners guide and any “maintenance workflow” / upgrade docs so operators can discover the behavior without reading source.

6. Quality

   • Follow repo conventions (make agent-finish, validation, error-message style if user-facing strings are added).

Acceptance criteria

• Self-hosted-only adopters have a documented path that does not rely on tribal knowledge or a configurable generator path that survives compile / upgrade without manual YAML surgery.
• Regenerated maintenance workflow output is covered by tests for the chosen behavior.

Non-goals

• Prescribing a specific org’s runner label names (solution should remain generic).