Edit content/en/controller.md on GitHub ↗
Label-only controller
The controller runs .github/scripts/controller.mjs every 30 minutes and on demand. It uses only the built-in GITHUB_TOKEN: no LLM, no secrets, no GitHub App and no stored token.
What it does
It manages labels and nothing else. It never merges, approves, comments on, edits or closes anything, and it never checks out or runs a PR or an issue. Issue and PR text is read as data (a regex for Fixes #N); a PR's changed files are read through the API and judged by the same rules as the risk gate (.github/agent/risk-rules.json).
| Rule | Effect |
|---|---|
Every open PR (50 most recently updated, not hold) |
risk:T0..risk:T3 from the risk gate, replacing a stale label. If the files cannot be read, nothing changes. Advisory only: no merge decision reads the label |
| An agent's PR | Adds agent-pr when the author is in agentAuthors, the branch starts with an agentBranchPrefixes entry (agent/), or a branch in this repository says Fixes #N for an agent-ready/agent-working issue. A fork PR counts by author only. The label is never removed |
agent-ready / agent-working issue |
Removes both when the last agent-ready was set by a non-maintainer, or a non-maintainer edited the text after it. A maintainer re-labeling re-approves it |
A claim (agent-working) |
Removes it after claimTtlHours (6) with no open linked PR activity |
hold on the issue or PR |
Everything is left alone |
| A label that does not exist | The add is skipped and reported, never created; removals still happen |
Maintainers are listed in .github/agent/controller.json; editing it is T3. The controller can never add agent-ready or agent-working; validatePlan refuses it.
Modes
| Switch | Where | Effect |
|---|---|---|
| Default | nothing set | dry run: plan reads and writes the proposed changes to the job summary; apply does not run |
CONTROLLER_LIVE=true |
repository variable | live: apply adds and removes labels; any other value stays dry run |
AGENT_PAUSE=true |
repository variable | stops it completely: nothing is read, proposed or changed |
| Disable or delete the workflow | Actions | off |
Permissions
plan: contents: read, issues: read, pull-requests: read. apply: contents: read, issues: write, pull-requests: write, only when CONTROLLER_LIVE is true and the plan has operations. Workflow-level permissions are {}.
The script's writes are only POST .../issues/N/labels and DELETE .../issues/N/labels/NAME; there is no merge, review, comment, close, eval or extra network access. The plan is passed as a job output (numbers, fixed label names and fixed reason codes); apply validates it again and re-reads each target before acting.