gerritcodereview Gerrit Task Query
The Gerrit task plugin attaches a task tree to each change. Tasks represent CI checks, review requirements, and dependency gates. This skill shows how to fetch the task tree, find tasks that need action, and determine what to do.
The tools get_task_tree and get_actionable_tasks are provided by the
gerrit_mcp_server_task extension (entry point gerrit_mcp_server.extensions).
They are available whenever gerrit-mcp-server is running with the task
extension installed and a configured Gerrit host that has the task plugin
enabled.
1. Fetch tasks for a change
Task plugin options (task--applicable, task--only, etc.) are Gerrit
DynamicOptions — they are passed as direct HTTP query parameters
(&task--applicable), not as standard Gerrit output options (&o=).
Using the MCP tools (preferred — returns structured task tree JSON):
# All applicable tasks for a change
get_task_tree(change_id="123")
# Scope to one root task
get_task_tree(change_id="123", task_only="Jenkins")
# Convenience: returns only READY and FAIL nodes, pre-walked
get_actionable_tasks(change_id="123")
get_actionable_tasks(change_id="123", task_only="Jenkins")
Using query_changes / get_change_details (plain-text summary only):
# These pass task parameters but only return a text summary — use the task tools above instead
query_changes(query="change:123", parameters={"task--applicable": None})
get_change_details(change_id="123", parameters={"task--applicable": None})
2. Task node fields
| Field | Meaning |
|---|---|
name |
Task name |
status |
Status value (see table below) |
hint |
Human-readable explanation (present on READY and FAIL) |
in_progress |
true if task is currently executing |
has_pass |
true if the task has a terminal pass/fail condition |
exported |
Custom key-value metadata from the task definition |
change |
Change number — only on tasks generated by a change-type tasks-factory |
sub_tasks |
Child task nodes (recursive, arbitrary depth) |
3. Status meanings
| Status | Actionable? | Meaning |
|---|---|---|
READY |
Yes | All prerequisites met; task is waiting to be executed |
FAIL |
Yes | Task executed and failed; workflow is blocked |
WAITING |
No — look inside | Blocked by subtasks not yet passing; dig into subTasks |
PASS |
No | Completed successfully |
DUPLICATE |
No | Same key seen in an ancestor; skipped to prevent loops |
SKIPPED |
No | Evaluation skipped (too expensive) |
UNKNOWN |
No | Insufficient permissions to evaluate |
INVALID |
No — config bug | Bad task definition |
Actionable = status is READY or FAIL.
4. Finding actionable tasks
Use get_actionable_tasks — it walks the tree for you.
If walking manually: go depth-first. Collect every node with status == "READY"
or status == "FAIL". Continue descending into WAITING nodes. Stop at PASS,
DUPLICATE, SKIPPED, UNKNOWN.
def find_actionable(node):
if node.status in (READY, FAIL):
yield node
elif node.status == WAITING:
for child in node.subTasks:
yield from find_actionable(child)
# PASS, DUPLICATE, SKIPPED, UNKNOWN → stop
5. Acting on actionable tasks
The task plugin does not prescribe what action to take — that is determined by
the hint field written by the task config author.
General approach:
- Read
hint— this is the authoritative instruction from the config author - Check
exported— may carry metadata like CI system name, ticket ID, priority - Check
inProgress— iftrue, the task is already being handled; skip it - Check
change— if present, this task represents a blocking dependent change
Common patterns:
| Pattern | How to identify | What to do |
|---|---|---|
| CI verification needed | READY, hint mentions a CI system name |
Trigger the CI system (comment, API call, or re-push — method depends on the system) |
| Label vote missing | hint mentions label:X=+1 or a vote count |
Use post_review_comment with labels (e.g. {"Code-Review": 1}) |
| Dependent change blocking | FAIL + task has a change field |
The blocking change is in .change; resolve or unblock it before this one can pass |
| External/Depends-on issue | hint mentions "Depends-on" or "external dependencies" | Fix the issues with the Depends-on change dependencies (use the depends-on plugin tools and skills if available) or wait for the referenced change to merge |
| Code review needed | hint mentions code review or approval count | Cast a Code-Review vote or request a reviewer |
Use post_review_comment to post comments or cast label votes, and
list_change_comments to read existing ones.
6. Reporting to the user
For each actionable task, report:
- Task name and status (
READYorFAIL) hint— primary actionable signalexportedproperties if presentchangenumber if present (means this task represents a blocking change)- Whether
inProgressistrue(already being handled)