agent-output.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://github.com/github/gh-aw-copilots/schemas/agent-output.json",
  "title": "GitHub Agentic Workflows Agent Output",
  "description": "Schema for the agent output file generated by the collect_output step in GitHub Agentic Workflows. This file contains the validated output from AI agents, structured as SafeOutput items with any validation errors. The actual business logic validation (such as ensuring update-issue has at least one updateable field) is handled by the JavaScript validation code.",
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "description": "Array of validated safe output items",
      "items": {
        "$ref": "#/$defs/SafeOutput"
      }
    },
    "errors": {
      "type": "array",
      "description": "Array of validation errors encountered during processing",
      "items": {
        "type": "string"
      }
    }
  },
  "required": ["items", "errors"],
  "additionalProperties": false,
  "$defs": {
    "SafeOutput": {
      "title": "Safe Output Item",
      "description": "Union type of all supported safe output entries",
      "oneOf": [
        { "$ref": "#/$defs/CreateIssueOutput" },
        { "$ref": "#/$defs/AddCommentOutput" },
        { "$ref": "#/$defs/CreatePullRequestOutput" },
        { "$ref": "#/$defs/AddLabelsOutput" },
        { "$ref": "#/$defs/AddReviewerOutput" },
        { "$ref": "#/$defs/UpdateIssueOutput" },
        { "$ref": "#/$defs/UpdatePullRequestOutput" },
        { "$ref": "#/$defs/PushToPullRequestBranchOutput" },
        { "$ref": "#/$defs/CreatePullRequestReviewCommentOutput" },
        { "$ref": "#/$defs/CreateDiscussionOutput" },
        { "$ref": "#/$defs/UpdateDiscussionOutput" },
        { "$ref": "#/$defs/CloseDiscussionOutput" },
        { "$ref": "#/$defs/CloseIssueOutput" },
        { "$ref": "#/$defs/ClosePullRequestOutput" },
        { "$ref": "#/$defs/MarkPullRequestAsReadyForReviewOutput" },
        { "$ref": "#/$defs/MissingToolOutput" },
        { "$ref": "#/$defs/CreateCodeScanningAlertOutput" },
        { "$ref": "#/$defs/UpdateProjectOutput" },
        { "$ref": "#/$defs/UpdateReleaseOutput" },
        { "$ref": "#/$defs/AssignMilestoneOutput" },
        { "$ref": "#/$defs/AssignToAgentOutput" },
        { "$ref": "#/$defs/NoOpOutput" },
        { "$ref": "#/$defs/LinkSubIssueOutput" },
        { "$ref": "#/$defs/HideCommentOutput" },
        { "$ref": "#/$defs/DispatchWorkflowOutput" },
        { "$ref": "#/$defs/AutofixCodeScanningAlertOutput" },
        { "$ref": "#/$defs/SubmitPullRequestReviewOutput" },
        { "$ref": "#/$defs/ReplyToPullRequestReviewCommentOutput" },
        { "$ref": "#/$defs/ResolvePullRequestReviewThreadOutput" }
      ]
    },
    "CreateIssueOutput": {
      "title": "Create Issue Output",
      "description": "Output for creating a GitHub issue",
      "type": "object",
      "properties": {
        "type": {
          "const": "create_issue"
        },
        "title": {
          "type": "string",
          "description": "Title of the issue to create",
          "minLength": 1
        },
        "body": {
          "type": "string",
          "description": "Body content of the issue",
          "minLength": 1
        },
        "labels": {
          "type": "array",
          "description": "Optional labels to add to the issue",
          "items": {
            "type": "string"
          }
        },
        "fields": {
          "type": "array",
          "description": "Optional issue fields to set after creating the issue",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Issue field name"
              },
              "value": {
                "oneOf": [{ "type": "string" }, { "type": "number" }],
                "description": "Issue field value"
              }
            },
            "required": ["name", "value"],
            "additionalProperties": false
          }
        }
      },
      "required": ["type", "title", "body"],
      "additionalProperties": false
    },
    "AddCommentOutput": {
      "title": "Add Issue Comment Output",
      "description": "Output for adding a comment to an issue or pull request",
      "type": "object",
      "properties": {
        "type": {
          "const": "add_comment"
        },
        "body": {
          "type": "string",
          "description": "Comment body content",
          "minLength": 1
        }
      },
      "required": ["type", "body"],
      "additionalProperties": false
    },
    "CreatePullRequestOutput": {
      "title": "Create Pull Request Output",
      "description": "Output for creating a GitHub pull request",
      "type": "object",
      "properties": {
        "type": {
          "const": "create_pull_request"
        },
        "title": {
          "type": "string",
          "description": "Title of the pull request",
          "minLength": 1
        },
        "body": {
          "type": "string",
          "description": "Body content of the pull request",
          "minLength": 1
        },
        "branch": {
          "type": "string",
          "description": "Optional branch name for the pull request"
        },
        "labels": {
          "type": "array",
          "description": "Optional labels to add to the pull request",
          "items": {
            "type": "string"
          }
        }
      },
      "required": ["type", "title", "body"],
      "additionalProperties": false
    },
    "AddLabelsOutput": {
      "title": "Add Issue Label Output",
      "description": "Output for adding labels to an issue or pull request",
      "type": "object",
      "properties": {
        "type": {
          "const": "add_labels"
        },
        "labels": {
          "type": "array",
          "description": "Array of label names to add",
          "items": {
            "type": "string"
          },
          "minItems": 1
        }
      },
      "required": ["type", "labels"],
      "additionalProperties": false
    },
    "AddReviewerOutput": {
      "title": "Add Reviewer Output",
      "description": "Output for adding reviewers to a pull request",
      "type": "object",
      "properties": {
        "type": {
          "const": "add_reviewer"
        },
        "reviewers": {
          "type": "array",
          "description": "Array of GitHub usernames to add as reviewers",
          "items": {
            "type": "string"
          },
          "minItems": 1
        },
        "pull_request_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Pull request number (optional - uses triggering PR if not provided)"
        }
      },
      "required": ["type", "reviewers"],
      "additionalProperties": false
    },
    "UpdateIssueOutput": {
      "title": "Update Issue Output",
      "description": "Output for updating an existing issue. Note: The JavaScript validation ensures at least one of status, title, or body is provided.",
      "type": "object",
      "properties": {
        "type": {
          "const": "update_issue"
        },
        "status": {
          "type": "string",
          "description": "New status for the issue",
          "enum": ["open", "closed"]
        },
        "title": {
          "type": "string",
          "description": "New title for the issue"
        },
        "body": {
          "type": "string",
          "description": "New body content for the issue"
        },
        "issue_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Issue number to update (for target '*')"
        }
      },
      "required": ["type"],
      "additionalProperties": false
    },
    "UpdatePullRequestOutput": {
      "title": "Update Pull Request Output",
      "description": "Output for updating an existing pull request's title and/or body. Supports replace, append, or prepend operations for body updates. Note: The JavaScript validation ensures at least one of title or body is provided.",
      "type": "object",
      "properties": {
        "type": {
          "const": "update_pull_request"
        },
        "title": {
          "type": "string",
          "description": "New title for the pull request (always replaces existing title)"
        },
        "body": {
          "type": "string",
          "description": "Body content for the pull request (behavior depends on operation field)"
        },
        "operation": {
          "type": "string",
          "description": "Update operation for body: 'replace' (default), 'append', or 'prepend'",
          "enum": ["replace", "append", "prepend"]
        },
        "pull_request_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Pull request number to update (for target '*')"
        }
      },
      "required": ["type"],
      "additionalProperties": false
    },
    "PushToPullRequestBranchOutput": {
      "title": "Push to Branch Output",
      "description": "Output for pushing changes directly to a branch",
      "type": "object",
      "properties": {
        "type": {
          "const": "push_to_pull_request_branch"
        },
        "message": {
          "type": "string",
          "description": "Optional commit message"
        },
        "pull_request_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Pull request number (for target '*')"
        }
      },
      "required": ["type"],
      "additionalProperties": false
    },
    "CreatePullRequestReviewCommentOutput": {
      "title": "Create Pull Request Review Comment Output",
      "description": "Output for creating a review comment on a specific line of code",
      "type": "object",
      "properties": {
        "type": {
          "const": "create_pull_request_review_comment"
        },
        "path": {
          "type": "string",
          "description": "File path for the comment",
          "minLength": 1
        },
        "line": {
          "oneOf": [
            { "type": "number", "minimum": 1 },
            { "type": "string", "pattern": "^[1-9][0-9]*$" }
          ],
          "description": "Line number for the comment"
        },
        "body": {
          "type": "string",
          "description": "Comment body content",
          "minLength": 1
        },
        "start_line": {
          "oneOf": [
            { "type": "number", "minimum": 1 },
            { "type": "string", "pattern": "^[1-9][0-9]*$" }
          ],
          "description": "Optional start line for multi-line comments"
        },
        "side": {
          "type": "string",
          "description": "Side of the diff to comment on",
          "enum": ["LEFT", "RIGHT"]
        }
      },
      "required": ["type", "path", "line", "body"],
      "additionalProperties": false
    },
    "SubmitPullRequestReviewOutput": {
      "title": "Submit Pull Request Review Output",
      "description": "Output for submitting a PR review with a status (APPROVE, REQUEST_CHANGES, COMMENT). All create_pull_request_review_comment outputs are collected and submitted as part of this review. If omitted, comments are submitted as a COMMENT review.",
      "type": "object",
      "properties": {
        "type": {
          "const": "submit_pull_request_review"
        },
        "body": {
          "type": "string",
          "description": "Review body text summarizing the review. Required for REQUEST_CHANGES; optional for APPROVE and COMMENT."
        },
        "event": {
          "type": "string",
          "description": "Review decision: APPROVE to approve the PR, REQUEST_CHANGES to request changes, or COMMENT for general feedback. Defaults to COMMENT when omitted.",
          "enum": ["APPROVE", "REQUEST_CHANGES", "COMMENT"],
          "default": "COMMENT"
        }
      },
      "required": ["type"],
      "additionalProperties": false,
      "allOf": [
        {
          "if": {
            "properties": {
              "event": { "const": "REQUEST_CHANGES" }
            },
            "required": ["event"]
          },
          "then": {
            "required": ["type", "event", "body"],
            "properties": {
              "body": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        }
      ]
    },
    "ReplyToPullRequestReviewCommentOutput": {
      "title": "Reply to Pull Request Review Comment Output",
      "description": "Output for replying to an existing review comment on a pull request",
      "type": "object",
      "properties": {
        "type": {
          "const": "reply_to_pull_request_review_comment"
        },
        "comment_id": {
          "type": ["number", "string"],
          "description": "The numeric ID of the review comment to reply to"
        },
        "body": {
          "type": "string",
          "description": "The reply body text",
          "minLength": 1
        },
        "pull_request_number": {
          "type": ["number", "string"],
          "description": "Pull request number (optional - uses triggering PR if not provided)"
        }
      },
      "required": ["type", "comment_id", "body"],
      "additionalProperties": false
    },
    "ResolvePullRequestReviewThreadOutput": {
      "title": "Resolve Pull Request Review Thread Output",
      "description": "Output for resolving a review thread on a pull request. Marks a review conversation as resolved after the feedback has been addressed.",
      "type": "object",
      "properties": {
        "type": {
          "const": "resolve_pull_request_review_thread"
        },
        "thread_id": {
          "type": "string",
          "minLength": 1,
          "description": "The node ID of the review thread to resolve (e.g., 'PRRT_kwDOABCD...'). This is the GraphQL node ID, not a numeric ID."
        }
      },
      "required": ["type", "thread_id"],
      "additionalProperties": false
    },
    "CreateDiscussionOutput": {
      "title": "Create Discussion Output",
      "description": "Output for creating a GitHub discussion",
      "type": "object",
      "properties": {
        "type": {
          "const": "create_discussion"
        },
        "title": {
          "type": "string",
          "description": "Title of the discussion",
          "minLength": 1
        },
        "body": {
          "type": "string",
          "description": "Body content of the discussion",
          "minLength": 1
        }
      },
      "required": ["type", "title", "body"],
      "additionalProperties": false
    },
    "UpdateDiscussionOutput": {
      "title": "Update Discussion Output",
      "description": "Output for updating an existing GitHub discussion's title, body, and/or labels. Note: The JavaScript validation ensures at least one of title, body, or labels is provided.",
      "type": "object",
      "properties": {
        "type": {
          "const": "update_discussion"
        },
        "title": {
          "type": "string",
          "description": "New discussion title to replace the existing title"
        },
        "body": {
          "type": "string",
          "description": "New discussion body to replace the existing content"
        },
        "labels": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Array of label names to set on the discussion (replaces existing labels)"
        },
        "discussion_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Discussion number to update (for target '*')"
        }
      },
      "required": ["type"],
      "additionalProperties": false
    },
    "CloseDiscussionOutput": {
      "title": "Close Discussion Output",
      "description": "Output for closing a GitHub discussion with an optional comment and resolution reason",
      "type": "object",
      "properties": {
        "type": {
          "const": "close_discussion"
        },
        "body": {
          "type": "string",
          "description": "Comment body to add when closing the discussion",
          "minLength": 1
        },
        "reason": {
          "type": "string",
          "description": "Optional resolution reason",
          "enum": ["RESOLVED", "DUPLICATE", "OUTDATED", "ANSWERED"]
        },
        "discussion_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Discussion number to close (optional - uses triggering discussion if not provided)"
        }
      },
      "required": ["type", "body"],
      "additionalProperties": false
    },
    "CloseIssueOutput": {
      "title": "Close Issue Output",
      "description": "Output for closing a GitHub issue with a comment",
      "type": "object",
      "properties": {
        "type": {
          "const": "close_issue"
        },
        "body": {
          "type": "string",
          "description": "Comment body to add when closing the issue",
          "minLength": 1
        },
        "issue_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Issue number to close (optional - uses triggering issue if not provided)"
        }
      },
      "required": ["type", "body"],
      "additionalProperties": false
    },
    "ClosePullRequestOutput": {
      "title": "Close Pull Request Output",
      "description": "Output for closing a GitHub pull request without merging, with a comment",
      "type": "object",
      "properties": {
        "type": {
          "const": "close_pull_request"
        },
        "body": {
          "type": "string",
          "description": "Comment body to add when closing the pull request",
          "minLength": 1
        },
        "pull_request_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Pull request number to close (optional - uses triggering PR if not provided)"
        }
      },
      "required": ["type", "body"],
      "additionalProperties": false
    },
    "MarkPullRequestAsReadyForReviewOutput": {
      "title": "Mark Pull Request as Ready for Review Output",
      "description": "Output for marking a draft pull request as ready for review with a comment",
      "type": "object",
      "properties": {
        "type": {
          "const": "mark_pull_request_as_ready_for_review"
        },
        "reason": {
          "type": "string",
          "description": "Comment explaining why the PR is ready for review",
          "minLength": 1
        },
        "pull_request_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Pull request number to mark as ready (optional - uses triggering PR if not provided)"
        }
      },
      "required": ["type", "reason"],
      "additionalProperties": false
    },
    "MissingToolOutput": {
      "title": "Missing Tool Output",
      "description": "Output for reporting missing tools or functionality",
      "type": "object",
      "properties": {
        "type": {
          "const": "missing_tool"
        },
        "tool": {
          "type": "string",
          "description": "Optional: Name of the missing tool",
          "minLength": 1
        },
        "reason": {
          "type": "string",
          "description": "Reason why the tool is needed or information about the limitation",
          "minLength": 1
        },
        "alternatives": {
          "type": "string",
          "description": "Optional alternative suggestions"
        }
      },
      "required": ["type", "reason"],
      "additionalProperties": false
    },
    "CreateCodeScanningAlertOutput": {
      "title": "Create Code Scanning Alert Output",
      "description": "Output for generating SARIF repository security advisories",
      "type": "object",
      "properties": {
        "type": {
          "const": "create_code_scanning_alert"
        },
        "sarif": {
          "oneOf": [{ "type": "object" }, { "type": "string" }],
          "description": "SARIF content as object or string"
        },
        "category": {
          "type": "string",
          "description": "Optional category for the code scanning alert"
        }
      },
      "required": ["type", "sarif"],
      "additionalProperties": false
    },
    "UpdateProjectOutput": {
      "title": "Update Project Output",
      "description": "Output for unified project operations: create projects, add items (issues/PRs/drafts), and update item fields",
      "type": "object",
      "properties": {
        "type": {
          "const": "update_project"
        },
        "project": {
          "type": "string",
          "description": "Project title, number, or GitHub project URL",
          "minLength": 1
        },
        "content_type": {
          "type": "string",
          "enum": ["issue", "pull_request", "draft_issue"],
          "description": "Type of content to add to the project board. Use 'issue' or 'pull_request' to add existing repo content, or 'draft_issue' to create a draft item inside the project."
        },
        "content_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Issue or PR number (preferred field)"
        },
        "issue": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Issue number (legacy field, use content_number instead)"
        },
        "pull_request": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "PR number (legacy field, use content_number instead)"
        },
        "draft_title": {
          "type": "string",
          "description": "Title for a Projects v2 draft issue. Required when content_type is 'draft_issue'."
        },
        "draft_body": {
          "type": "string",
          "description": "Optional body for a Projects v2 draft issue (markdown). Only used when content_type is 'draft_issue'."
        },
        "fields": {
          "type": "object",
          "description": "Custom project field values to set/update. Creates fields if missing.",
          "additionalProperties": true
        },
        "create_if_missing": {
          "type": "boolean",
          "description": "Opt-in: allow creating the project board if it does not exist. Default behavior is update-only."
        }
      },
      "required": ["type", "project"],
      "additionalProperties": false
    },
    "UpdateReleaseOutput": {
      "title": "Update Release Output",
      "description": "Output for updating a GitHub release description",
      "type": "object",
      "properties": {
        "type": {
          "const": "update_release"
        },
        "tag": {
          "type": "string",
          "description": "Tag name of the release to update",
          "minLength": 1
        },
        "operation": {
          "type": "string",
          "description": "Update operation: 'replace', 'append', or 'prepend'",
          "enum": ["replace", "append", "prepend"]
        },
        "body": {
          "type": "string",
          "description": "Content to set or append to the release body",
          "minLength": 1
        }
      },
      "required": ["type", "tag", "operation", "body"],
      "additionalProperties": false
    },
    "AssignMilestoneOutput": {
      "title": "Assign Milestone Output",
      "description": "Output for assigning an issue to a milestone",
      "type": "object",
      "properties": {
        "type": {
          "const": "assign_milestone"
        },
        "issue_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Issue number to assign milestone to"
        },
        "milestone_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Milestone number to assign (required)"
        }
      },
      "required": ["type", "issue_number", "milestone_number"],
      "additionalProperties": false
    },
    "AssignToAgentOutput": {
      "title": "Assign to Agent Output",
      "description": "Output for assigning a GitHub Copilot coding agent to an issue or pull request",
      "type": "object",
      "oneOf": [
        {
          "required": ["type", "issue_number"]
        },
        {
          "required": ["type", "pull_number"]
        }
      ],
      "properties": {
        "type": {
          "const": "assign_to_agent"
        },
        "issue_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Issue number to assign agent to. Either issue_number or pull_number must be provided, but not both."
        },
        "pull_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Pull request number to assign agent to. Either issue_number or pull_number must be provided, but not both."
        },
        "agent": {
          "type": "string",
          "description": "Agent name or slug (defaults to 'copilot' if not provided)"
        }
      },
      "additionalProperties": false
    },
    "NoOpOutput": {
      "title": "No-Op Output",
      "description": "Output for logging a message without taking any GitHub actions. Always available as a fallback to ensure human-visible artifacts.",
      "type": "object",
      "properties": {
        "type": {
          "const": "noop"
        },
        "message": {
          "type": "string",
          "description": "Message to log for transparency",
          "minLength": 1
        }
      },
      "required": ["type", "message"],
      "additionalProperties": false
    },
    "LinkSubIssueOutput": {
      "title": "Link Sub-Issue Output",
      "description": "Output for linking an issue as a sub-issue of a parent issue",
      "type": "object",
      "properties": {
        "type": {
          "const": "link_sub_issue"
        },
        "parent_issue_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Parent issue number to link the sub-issue to"
        },
        "sub_issue_number": {
          "oneOf": [{ "type": "number" }, { "type": "string" }],
          "description": "Issue number to link as a sub-issue"
        }
      },
      "required": ["type", "parent_issue_number", "sub_issue_number"],
      "additionalProperties": false
    },
    "HideCommentOutput": {
      "title": "Hide Comment Output",
      "description": "Output for hiding a comment on a GitHub issue, pull request, or discussion",
      "type": "object",
      "properties": {
        "type": {
          "const": "hide_comment"
        },
        "comment_id": {
          "type": "string",
          "description": "Node ID of the comment to hide (e.g., 'IC_kwDOABCD123456')",
          "minLength": 1
        },
        "reason": {
          "type": "string",
          "enum": ["SPAM", "ABUSE", "OFF_TOPIC", "OUTDATED", "RESOLVED"],
          "description": "Optional reason for hiding the comment (default: SPAM). Valid values: SPAM, ABUSE, OFF_TOPIC, OUTDATED, RESOLVED"
        }
      },
      "required": ["type", "comment_id"],
      "additionalProperties": false
    },
    "DispatchWorkflowOutput": {
      "title": "Dispatch Workflow Output",
      "description": "Output for dispatching a workflow_dispatch event to trigger another workflow",
      "type": "object",
      "properties": {
        "type": {
          "const": "dispatch_workflow"
        },
        "workflow_name": {
          "type": "string",
          "description": "Name of the workflow to dispatch (without .md or .lock.yml extension)",
          "minLength": 1
        },
        "inputs": {
          "type": "object",
          "description": "Input parameters for the workflow_dispatch event, matching the workflow's input schema",
          "additionalProperties": true
        }
      },
      "required": ["type", "workflow_name"],
      "additionalProperties": false
    },
    "AutofixCodeScanningAlertOutput": {
      "title": "Add Code Scanning Autofix Output",
      "description": "Output for creating an autofix for a code scanning alert using the GitHub REST API",
      "type": "object",
      "properties": {
        "type": {
          "const": "autofix_code_scanning_alert"
        },
        "alert_number": {
          "oneOf": [
            { "type": "number", "minimum": 1 },
            { "type": "string", "pattern": "^[1-9][0-9]*$" }
          ],
          "description": "The security alert number to create an autofix for"
        },
        "fix_description": {
          "type": "string",
          "description": "Description of the fix being applied",
          "minLength": 1
        },
        "fix_code": {
          "type": "string",
          "description": "The code changes to apply as the autofix",
          "minLength": 1
        }
      },
      "required": ["type", "alert_number", "fix_description", "fix_code"],
      "additionalProperties": false
    }
  }
}