Skip to content

Support configurable runs-on for the generated agentics-maintenance workflow #26481

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 3 commits into from
Apr 15, 2026
+31 −1
Merged

Support configurable runs-on for the generated agentics-maintenance workflow #26481

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
96c045d
Initial plan
Copilot Apr 15, 2026
7e36fb7
docs: document aw.json runs_on for maintenance workflow in self-hoste…
Copilot Apr 15, 2026
0331e50
Merge branch 'main' into copilot/support-configurable-runs-on-again
pelikhan Apr 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/src/content/docs/guides/ephemerals.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ You can customize the maintenance workflow runner or disable maintenance entirel
}
```

The `runs_on` field accepts a single string or an array of strings for multi-label runners (e.g., `["self-hosted", "linux"]`). The default runner is `ubuntu-slim`.
The `runs_on` field accepts a single string or an array of strings for multi-label runners (e.g., `["self-hosted", "linux"]`). The default runner is `ubuntu-slim`. See [Self-Hosted Runners](/gh-aw/guides/self-hosted-runners/#configuring-the-maintenance-workflow-runner) for more details.
Copy link

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line states the default maintenance runner is ubuntu-slim, but the generated workflow defaults validate_workflows to ubuntu-latest (unless maintenance.runs_on is set). Please update the documentation to reflect the actual defaults so users understand why they may still see ubuntu-latest in the workflow.

Suggested change
The `runs_on` field accepts a single string or an array of strings for multi-label runners (e.g., `["self-hosted", "linux"]`). The default runner is `ubuntu-slim`. See [Self-Hosted Runners](/gh-aw/guides/self-hosted-runners/#configuring-the-maintenance-workflow-runner) for more details.
The `runs_on` field accepts a single string or an array of strings for multi-label runners (e.g., `["self-hosted", "linux"]`). If you do not set `maintenance.runs_on`, generated maintenance workflows may still use `ubuntu-latest` for `validate_workflows`, which is why you may see that runner in emitted workflow files. Set `maintenance.runs_on` to override the maintenance workflow runner explicitly. See [Self-Hosted Runners](/gh-aw/guides/self-hosted-runners/#configuring-the-maintenance-workflow-runner) for more details.

Copilot uses AI. Check for mistakes.

**Disable maintenance entirely:**

Expand Down
30 changes: 30 additions & 0 deletions docs/src/content/docs/guides/self-hosted-runners.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,10 +107,40 @@ safe-outputs:
> [!NOTE]
> `runs-on` controls only the main agent job. `runs-on-slim` controls all framework/generated jobs. `safe-outputs.runs-on` still takes precedence over `runs-on-slim` for safe-output jobs specifically.

## Configuring the maintenance workflow runner

The generated `agentics-maintenance.yml` workflow defaults to `ubuntu-slim` for all its jobs. To use a self-hosted runner for maintenance jobs, set `runs_on` in `.github/workflows/aw.json`:
Copy link

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docs say agentics-maintenance.yml defaults to ubuntu-slim for all jobs, but the generator uses ubuntu-latest as the default for the validate_workflows job (see pkg/workflow/maintenance_workflow_yaml.go where it falls back to ubuntu-latest). Please adjust this wording to reflect the mixed defaults (or explicitly call out validate_workflows), while still noting that maintenance.runs_on overrides all jobs when configured.

Suggested change
The generated `agentics-maintenance.yml` workflow defaults to `ubuntu-slim` for all its jobs. To use a self-hosted runner for maintenance jobs, set `runs_on` in `.github/workflows/aw.json`:
The generated `agentics-maintenance.yml` workflow uses mixed defaults: most jobs default to `ubuntu-slim`, while `validate_workflows` defaults to `ubuntu-latest`. To use a self-hosted runner for maintenance jobs, set `runs_on` in `.github/workflows/aw.json`; when configured, it overrides the runner for all maintenance workflow jobs:

Copilot uses AI. Check for mistakes.

**Single label:**

```json
{
"maintenance": {
"runs_on": "self-hosted"
}
}
```

**Multiple labels** (runner must match all):

```json
{
"maintenance": {
"runs_on": ["self-hosted", "linux", "x64"]
}
}
```

This setting applies to every job in `agentics-maintenance.yml` (close-expired-entities, cleanup-cache-memory, run_operation, apply_safe_outputs, create_labels, and validate_workflows). Re-run `gh aw compile` after changing `aw.json` to regenerate the workflow.

> [!NOTE]
> `aw.json` is separate from individual workflow frontmatter. It provides repository-level settings for generated infrastructure workflows.

## Related documentation

- [Frontmatter](/gh-aw/reference/frontmatter/#run-configuration-run-name-runs-on-runs-on-slim-timeout-minutes) — `runs-on` and `runs-on-slim` syntax reference
- [Imports](/gh-aw/reference/imports/) — importable fields and merge semantics
- [Threat Detection](/gh-aw/reference/threat-detection/) — detection job configuration
- [Network Access](/gh-aw/reference/network/) — configuring outbound network permissions
- [Sandbox](/gh-aw/reference/sandbox/) — container and Docker requirements
- [Ephemerals](/gh-aw/guides/ephemerals/#maintenance-configuration) — full `aw.json` maintenance configuration reference
Loading