Raise concerns with scheduled workflow being mandated during AW upgrade

[radiantspace]

Summary

When attempting to upgrade the AW (automation workflow) version, the upgrade process seems to require adoption of compiler upgrades, which in turn enforces the inclusion of a scheduled agentics-maintenance.yml workflow.

Concerns

• The scheduled workflow is added automatically and is not optional during upgrade, which is confusing and breaks expectations for many users who were not expecting scheduled workflows to be added for a tooling update.
• This increases CI usage and may result in unnecessary consumption of GitHub tokens and rate limits, particularly for teams sensitive to usage and cost.
• Lack of transparency/clarity regarding the motivation and necessity of the scheduled workflow, and what it actually accomplishes.

Questions/Impact

• Why is the scheduled workflow a required part of upgrading the version?
• What is the intended benefit, and can it be achieved in other ways by opt-in?
• Do external customers (particularly those with strict auditing or resource controls) have a migration path or way to reject the scheduled workflow?

Context
This feedback is based on an internal upgrade attempt (see dx-automation PR #728) and follow-up questions in internal support threads. Experience was surprising and not documented, and it would help to clarify guidance for all customers using AW and automate upgrades.

View original Slack conversation

[pelikhan]

/scout answer questions

[github-actions]

🏕️ Lost in the wilderness! Scout failed to deliver outputs. Sending search party...

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan via /scout answer questions

Executive Summary

The core premise — that agentics-maintenance.yml is unconditionally mandated by an upgrade — is not quite accurate. The maintenance workflow is feature-gated: the compiler only generates it when one or more of your workflows opt into features that require a scheduler to function (auto-expiring issues/discussions/PRs, or no-op issue reporting). gh aw upgrade recompiles all workflows, so if those features are present, the file is (re)generated as a side effect. It is not added for a pure tooling bump where no workflow uses these features, and it can be fully disabled with a one-line maintenance: false in aw.json. Findings below are sourced directly from this repo (compiler source, ADR-26382, reference docs), not the web.

Click to expand detailed findings

Research Findings

Q1: Why is the scheduled workflow generated during upgrade?

It is not the upgrade itself that mandates it — it is recompilation. GenerateMaintenanceWorkflow (pkg/workflow/maintenance_workflow.go:138) scans every compiled workflow and only emits agentics-maintenance.yml when scanWorkflowsForExpires finds at least one of:

• safe_outputs.create_issues.expires > 0
• safe_outputs.create_discussions.expires > 0
• safe_outputs.create_pull_requests.expires > 0
• a no-op safe output with issue reporting enabled (default 30-day expiration)

If none are present, the function logs No workflows use expires field, skipping maintenance workflow generation and deletes any stale agentics-maintenance.yml (maintenance_workflow.go:185-196). So the trigger is a workflow feature, not the upgrade.

The schedule is structurally required for those features: auto-closing an expired issue/discussion/PR is impossible without something running on a cron. The cron frequency scales to the shortest expiration across all workflows (pkg/workflow/maintenance_cron.go):

• ≤ 1 day → every 2 hours
• 2 days → every 6 hours
• 3–4 days → every 12 hours
• 5+ days → daily (at minute :37 to avoid :00 load spikes)

The workflow also doubles as the safe-output replay / recovery mechanism (manual workflow_dispatch), per the safe-outputs reference docs.

Q2: Intended benefit, and can it be opt-in?

Benefit: it executes the deferred lifecycle operations the expires/no-op features promise (closing expired entities, replaying failed safe outputs, creating labels). Per ADR-26382, automating generation replaced an error-prone manual process that drifted out of sync on every upgrade.

It is effectively opt-in already — three ways to avoid it:

1. Do not use expires (or set expires: false) on create-issue/create-discussion/create-pull-request, and avoid no-op issue reporting. No feature → no file (and any existing file is auto-removed on next compile).
2. Hard-disable globally: add {"maintenance": false} to .github/workflows/aw.json. handleMaintenanceDisabled then deletes the file and warns that expires becomes a no-op (maintenance_workflow.go:287).
3. Tune, don't remove: the aw.json maintenance object supports runs_on (e.g. self-hosted/slim runners), label_triggers (off by default), and action_failure_issue_expires.

Q3: Migration path for audit / resource-controlled customers

• Reject it cleanly: "maintenance": false in aw.json is the documented, supported opt-out — committed to the repo, auditable, and survives upgrades.
• Cost profile is modest: default runner is ubuntu-slim; for 5+ day expirations it runs once daily. Frequency only increases if a workflow asks for short (≤4 day) expirations.
• Trade-off to document: disabling maintenance silently turns expires into a no-op (expired entities stay open) and removes the safe-output replay path. Teams should disable it and drop expires usage together, rather than leaving orphaned expires fields.

Recommendations

• Treat this primarily as a documentation/UX gap, not a defect — the behavior is intentional and configurable, but the upgrade flow does not clearly surface why the file appeared or how to decline it.
• Add an upgrade-time notice (or upgrade-doc callout): "a maintenance workflow was (re)generated because workflow X uses expires/no-op reporting; set maintenance: false in aw.json to opt out."
• For the dx-automation case, confirm which workflow(s) set expires — that is the actual source of the requirement, and removing/false-ing it avoids the schedule without touching aw.json.
• Document the maintenance: false opt-out and the daily-cron cost profile prominently in the upgrade guide for audit-sensitive customers.

Key Sources

• pkg/workflow/maintenance_workflow.go (generation gate, opt-out handling)
• pkg/workflow/maintenance_cron.go (schedule frequency logic)
• pkg/workflow/repo_config.go (maintenance: false / object config in aw.json)
• docs/adr/26382-auto-generate-side-repo-maintenance-workflows.md (design rationale)
• docs/src/content/docs/reference/safe-outputs.md and ephemerals.md (user-facing behavior)

Suggested Next Steps

1. Identify the expires/no-op usage in the dx-automation workflows that triggered generation.
2. Decide per-team: keep expires (accept maintenance cron) or set maintenance: false + drop expires.
3. File a docs/UX issue to make maintenance generation transparent during gh aw upgrade.

🔭 Intelligence gathered by Scout · 100.1 AIC · ⌖ 9.07 AIC · ◷

[pelikhan]

https://github.com/github/gh-aw/tasks/a5e5a99d-251f-46c2-9a34-08b699dc51c9

[pelikhan]

Header updated on why it is generated #40706