feat(ci): auto-apply triage labels to issues - #3574

What this PR does

Issues that arrive through the API or gh issue create bypass the issue templates, so they carry no triage/* label and nothing in the repository adds one afterwards. Listing every open issue through the same endpoint the workflow uses, gh api --paginate "/repos/cozystack/cozystack/issues?state=open&per_page=100", returns 567 entries, 171 of them pull requests, at the time of writing. That leaves 396 open issues, and 252 of them carry no triage label at all. Every count in this description is a point-in-time reading of a backlog that keeps moving, so a later run of the same query will differ by a few. The triage queue is impossible to filter on in that state, and there is no way to see how much of the backlog nobody has looked at.

This adds a workflow that labels an issue when it is opened or reopened, plus a daily sweep that backstops labels removed by hand and works through the existing backlog. An issue somebody has assigned, or marked with one of priority/critical-urgent, priority/important-soon, priority/important-longterm or epic, gets triage/accepted, since a maintainer has already looked at it. Everything else gets triage/needs-triage. An issue already carrying any triage/* label is left alone, so the sweep never overwrites a decision someone made by hand, and pull requests returned by the same listing endpoint are skipped. Against the listing above, the sweep applies triage/accepted to 39 issues and triage/needs-triage to 213, and touches none of the 144 that are already triaged.

Deleting a triage label by hand does not undo any of this. An issue left carrying no triage/* label is relabeled by the next sweep, so a triage decision is changed by replacing the label. AGENTS.md's labeling section now says so, because that is the file somebody reads before labeling by hand.

Two conditions decide what counts as a signal. Membership of stale.yaml's exempt-issue-labels is necessary: triage/accepted is itself on that list, so applying it does more than reset a clock, the issue stops being auto-closable, and a signal that is not already exempt would hand out that permanent reprieve as a side effect of being labeled. priority/backlog, the one tier stale.yaml deliberately leaves reapable, is excluded for exactly that reason.

Membership is not sufficient, which is why the signal list is not simply the exempt list. lifecycle/frozen is exempt and still not a signal: a lifecycle/* label states what the stale bot may do with an issue and says nothing about whether anybody reviewed it. Freezing an untriaged issue to keep the bot off it is the case where reading it as accepted is wrong. Of the five open issues whose only signal would have been lifecycle/frozen, one is blocked on an upstream project and carries help wanted, and one is an older feature request that an open epic now covers. Neither is ready to be worked on, and stamping either accepted would have kept it out of triage for good, since the sweep never revisits an issue that already carries a triage label. epic passes the same test from the other side: it is a maintainer-authored planning artifact rather than an inbound report, and all eight open issues whose only signal is epic are roadmap trackers that needs-triage would describe falsely. A contract test pins the rule and not the instance, so no label from the lifecycle/* namespace can quietly become a signal later. security/* stays out on the same grounds, though the case is closer: those labels record what is known about a vulnerability rather than whether anyone triaged the report, and the cost of being wrong runs the cheap way, since a needs-triage on a confirmed report is one click to remove while a wrong accepted is permanent because the sweep never revisits.

One caveat stated plainly: the signals stand for a maintainer decision already recorded on the issue, which is a weaker claim than the one triage/accepted makes in .github/labels.yml, and priority/important-longterm says outright that the work may not be staffed. Of the two labels this workflow can write it is still the closer one, since needs-triage on an issue somebody already prioritised or took asks for a triage that has happened, and a maintainer who disagrees replaces the label in one click. An assignee is the single signal that is neither a label nor already exempt, so an issue whose only signal is an assignee does gain a permanent reprieve. That is the intended reading rather than a side effect: somebody took ownership, which makes it a known long-tail task rather than an abandoned one, and it is the same argument stale.yaml's own comment makes for exempting triage/accepted in the first place.

Three operational details. First, the sweep paces its writes a second apart and caps a run at 400, because GitHub allows 80 content-generating requests a minute and 500 an hour, this client carries no throttling plugin and no retries, and a throttled write answers 403, which is exempt from retry anyway. Unpaced, the first pass over the backlog would not slow down when throttled, it would fail the job partway and leave the backlog half labeled. Whatever a run leaves behind stays unlabeled, so the next one picks it up. Second, adding a label bumps an issue's updated_at, which stale.yaml reads as activity, so the first sweep restarts the 60-day staleness clock on every issue it writes to, all 252 of them, and un-marks the 32 that carry lifecycle/stale today. Both are deliberate and one-time: the backlog gets triaged now and ages again from there, rather than being closed unread while it is still unlabeled. Third, a run writes a job summary with the counts, the issue numbers under each label, and both remainders it can leave behind: the write cap's deferral, and how much of the listing it never reached when a refusal stopped it early. A sweep over the backlog logs a line per issue, and the summary is what makes the outcome readable without paging through the 252 the current backlog produces.

A write that fails does not take the rest of the run with it, but the two failure shapes are told apart rather than counted together. Any status other than a 403 or 429 lets the run carry on, most often a 404 or 410 from an issue transferred or deleted mid-sweep, since a failure about one issue says nothing about the next. A 403 or 429 means the token lost issues: write or the pacing stopped being enough, which applies to every write left in the run, so the sweep stops at the first one and the job fails loudly. Repeating a rejected request up to the cap is what gets an integration throttled harder.

workflow_dispatch takes a dry_run input that logs what would be labeled without writing anything. It is on by default, so a manual run writes nothing until somebody unchecks the box, and schedule is the one event that writes without being asked. The cap applies in dry-run too, so a dry run predicts what a real one would do instead of printing a longer list nobody gets. The job asks for issues: write and everything else is read-only, the action it uses is pinned by digest, and a 20-minute timeout keeps a hung call from holding the queue for the default six hours.

No pull request lane can exercise this workflow, so its first real execution is a sweep over every open issue with nothing having run it before. hack/issue-triage-contract.bats pins the executable lines that bound that blast radius: the pull-request skip, the already-triaged skip, the pacing rate and the write cap, the job timeout, the failure handling, the digest-pinned action, the token scopes, the serialised queue, the dry-run default and the derivation that does not depend on it, the cron ordering against stale.yaml, that both labels it writes exist in .github/labels.yml, that no accepted-signal label sits outside stale.yaml's exempt list or inside the lifecycle/* namespace, and that the summary is written with the await that makes it flush and accounts for every outcome a run can end on. Each assertion was checked against a mutated copy of the workflow to confirm it goes red rather than merely existing, with the mutations run through hack/cozytest.sh rather than bats. The two runners disagree about negated assertions, so a pin that bats reports as live can be dead under the runner CI actually uses, and every negative assertion in the file captures grep's status instead of leading with !.

Suggested first step after merge: run the workflow by hand and read the summary before the 05:53 cron arms itself. The box arrives checked, so that run costs nothing.

Screenshots

Not a UI change, so there is nothing to show.

Downstream repositories

I walked the trigger map in docs/agents/contributing.md against the diff. The diff adds two files, .github/workflows/issue-triage.yaml and hack/issue-triage-contract.bats, and appends one line to AGENTS.md. No row matches: it adds and renames no package, changes no chart values, no schema, no version enum, no ApplicationDefinition, no CRD, no namespace, no variant or bundle, no label or annotation any downstream repository matches on, no metric and no release asset. Its hack/ rows name hack/upload-assets.sh, hack/e2e-prepare-cluster.bats, hack/package.mk, hack/update-crd.sh and hack/common-envs.mk, which downstream repositories copy, anchor on or mirror by hand, plus one row for moving or renaming anything under hack/; a new bats file added next to them is none of those. The map has no row for the agent documentation, and no downstream repository copies AGENTS.md.

• No downstream repository is affected by this change
• cozystack/website - follow-up:
• cozystack/terraform-provider-cozystack - follow-up:
• cozystack/ansible-cozystack - follow-up:
• cozystack/ccp - follow-up:
• cozystack/talm - follow-up:
• cozystack/cozyhr - follow-up:
• cozystack/cozy-proxy - follow-up:
• cozystack/cozystack-telemetry-server - follow-up:
• cozystack/external-apps-example - follow-up:
• cozystack/examples - follow-up:

Release note

feat(ci): new and reopened issues now get a `triage/*` label automatically, and a daily sweep labels any open issue that has none: `triage/accepted` when it is assigned or carries an `epic` or a priority above `priority/backlog`, `triage/needs-triage` otherwise.

Summary by CodeRabbit

• New Features

  • Added automated issue triage triggered by new or reopened issues, scheduled reviews, or manual runs.
  • Issues can be labeled as needing triage or accepted, with pull requests and already-triaged items excluded.
  • Added dry-run support and reporting for triage results.

• Documentation

  • Added guidance for replacing existing triage labels when making decisions.

• Tests

  • Added coverage for workflow behavior, permissions, scheduling, failure handling, and safety limits.