Labor0 Docs

Issue watcher

Issue watcher turns a narrowly defined GitHub issue change into reviewable planning work. It does not copy issue content into the submitted prompt; when a transition creates planning work, that work may inspect the linked issue through the authorized GitHub connection.

Installing Issue watcher, collecting and evaluating issue updates, and sending notifications do not add a Labor0 usage charge. Accepted planning work follows the ordinary task usage and pricing terms; see Pricing and usage.

Before you begin

You need a project with a project-bound repository, an active GitHub event automation connection for that repository, and a failure-notification UserGroup. This same UserGroup is also the audience for blocking planning questions and review-ready notifications created by matching issues. The UserGroup must be active in the same tenant and include at least one current member authorized to operate this project. If the project and repository already have GitHub event automation, use the exact connection that established that automation target. You also need a name, a bounded GitHub issue query, and a required bounded Go prompt template. Installation names must be unique across the entire project, including other configured templates and repositories. Preview does not check whether the name is already in use; if installation is rejected because of a name collision, choose another name or remove the conflicting installation. A Workspace Operator or equivalent project-configuration permission is required to install or change the watcher. Workspace Viewers can inspect the watcher and its history.

For Prompt template, use only the fields shown by the form. For example:

Review the issue at {{ .issue.url }} and propose a concise documentation plan.

This example uses an issue URL only; it does not include an issue title, body, comments, or other issue content. The template must be bounded, valid Go template text, produce non-whitespace output on every path, end with a non-whitespace character, and remain within the form’s size limit. Remove any trailing spaces or newlines.

Install the watcher

  1. Open the project and choose Automation.
  2. Select Add template, then choose Issue watcher.
  3. Complete Watcher details with the name and failure-notification UserGroup.
  4. Complete GitHub source with the project-bound repository and active GitHub event automation connection. Use a query such as is:open label:documentation. The watcher adds the repository and issue qualifiers when it shows Effective query. The query must remain issue-focused. The watcher rejects unquoted OR, a terminal unquoted NOT, explicit repo:, org:, or user: qualifiers, pull-request qualifiers such as is:pr, is:pull-request, or type:pr (including quoted forms), and comment-dependent qualifiers such as in:comments, commenter:, comments:, or involves:. Remove those qualifiers and use supported issue filters such as is:open, label:documentation, or other issue fields instead.
  5. Complete Prompt template with the bounded template.
  6. Optionally expand Optional runtime settings. Runtime, Model, Reasoning effort, Runner selection, Plan mode, Fast mode, and Graph-change auto-approval use the Project default unless you select an override. An explicit Model is trimmed and must not be blank.
  7. Select Preview query. Check Effective query, Matches, Validity, and the prompt preview. Runtime settings do not affect this preview.
  8. Select Install template.
  9. Wait until the installation status becomes Active, then confirm the active entry under Configured templates.

Installation establishes a no-work baseline. Existing matches are not backfilled. After a later supported GitHub issue update, allow the initial evaluation and the supplemental evaluation about two minutes later to complete before starting recovery; the supplemental evaluation allows for GitHub search indexing delay. A later update can create reviewable planning work only when that issue newly enters the configured result. Replacing the query establishes a new no-work baseline; issues already matching the replacement are not backfilled, including matches from a paused period.

What triggers work

The watcher responds to supported GitHub issue updates. Comments, reactions, pull-request events, polling, and historical backfill do not trigger work. More than 100 matches fails closed rather than selecting an incomplete result. Up to ten watchers for the same project workspace and repository may be activating or active at once; paused watchers do not consume this capacity. The repository and GitHub connection remain fixed after installation. A runtime-only edit saves immediately without another provider preview. A mixed runtime and prompt/source edit remains unavailable until the preview-relevant values have a current successful preview, then saves atomically. A transition snapshots its effective runtime and Graph-approval submission options before its first planning handoff, so retries keep those options after later installation edits; the next independent transition uses the newly saved configuration.

Expected result

The watcher is active under Configured templates. Its installation detail shows the configured status and available generic event history. When a later issue update makes an issue newly match, the resulting planning work is reviewable in the project; existing matches remain the no-work baseline.

Permissions and lifecycle

Workspace Viewers can inspect the watcher, status, and history. Workspace Operators can install, update, pause, resume, retry, and uninstall it. A notification UserGroup does not expand project access; notifications are limited to people who still have the required project permission.

Recover safely

  • Invalid query or more than 100 matches during setup: narrow the query, run Preview query again, and install only after Validity, Effective query, and Matches are acceptable.
  • More than 100 matches or an invalid query after installation: the installed query is read-only. Uninstall the watcher, then add a new Issue watcher with a narrowed valid query; select Preview query and confirm Validity, Effective query, and Matches before selecting Install template. The new installation establishes a no-work baseline and does not backfill existing matches.
  • Watcher capacity reached: if ten watchers for the same workspace and repository are activating or active, pause or remove an existing watcher, then retry installation or resume. Watchers in other projects in the workspace count toward this limit, so an authorized operator in another project may need to pause or remove one. Paused watchers do not count toward the limit.
  • Prompt validation or preview failure: use only the displayed bounded fields and supported template syntax; remove issue content and retry the preview. Do not paste provider payloads or unrestricted diagnostics.
  • Lost GitHub access or unavailable repository: reconnect the exact GitHub event automation connection that established the project and repository automation target, or restore the project-bound repository, then run a fresh preview. The installed repository and connection cannot be changed in place; uninstall and reinstall only when a different source is required.
  • Authorization or billing block: ask a Workspace Operator or administrator to restore the required project permission or billing readiness. If setup has not created an installation, select Install template after recovery; if an installation is paused, select Resume; if a failed active operation is shown, select Retry. Do not create a duplicate watcher while the status is uncertain.
  • Automatic pause caused by a prompt-template render failure: edit the prompt using only the displayed bounded fields and supported syntax, select Preview changes, then select Save changes to persist the corrected template. After the saved correction, select Pause followed by Resume on the installation if needed to reactivate the watcher. Do not resume the watcher with the old failing template.
  • Automatic pause: inspect the visible watcher status, correct the named dependency, then select Pause followed by Resume on the installation to reactivate the managed watcher. Do not use Retry or an episode control for this recovery.
  • Missing notifications while the watcher remains active: correct the notification UserGroup or its delivery dependency. Do not pause and resume a healthy watcher; that does not retry the failed notification and would interrupt evaluation while establishing a new no-work baseline. The watcher state still controls work while notification delivery is unavailable.