Skip to content

Commit 719e8dd

Browse files
feat(actions): add typed Actions tool outputs
Expose compact method-discriminated outputs for Actions tools while preserving legacy behavior, input coercions, and pagination forwarding. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent e6a4a25 commit 719e8dd

13 files changed

Lines changed: 1397 additions & 2531 deletions

‎README.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -616,13 +616,15 @@ The following sets of tools are available:
616616

617617
## Tools
618618

619-
Repository tools expose output schemas and typed `structuredContent` to clients using MCP protocol `2026-07-28` or later. Older clients, or clients with an unknown protocol version, receive the existing content without an output schema or structured output.
619+
Repository tools expose output schemas and typed `structuredContent` when the negotiated MCP protocol version is a supported version `2026-07-28` or newer. Older clients, clients with an unknown protocol version, and clients omitting the version receive the existing content without an output schema or structured output. Unknown versions are not treated as supported merely because they sort after `2026-07-28`.
620620

621621
For `get_file_contents`, directory results (including field projections) are structured arrays. File downloads and metadata-only responses use a `content` array of typed text, embedded-resource, or resource-link blocks, preserving status messages, text, base64 blobs, empty files, and download links. Text-only repository mutations such as starring and deletion also return a structured `message`; fork responses distinguish a repository reference from an in-progress message. Repository deletion still requires its existing confirmation flow before returning a completed result.
622622

623623
Structured repository results use compact DTOs rather than raw REST objects. Release lookups share the compact release shape with release listings; Git references retain the ref, object type, and SHA; annotated tags retain tag/message/tagger/target information; deletion commits retain SHA, message, authors, tree SHA, parent SHAs, and a human-facing `html_url` when available. Directory entries retain file metadata and useful HTML/download links, but omit API and hypermedia routing URLs even when those fields were requested in a projection. Legacy and unknown protocol versions retain the original text byte-for-byte; modern text-only JSON responses serialize the same compact DTO as `structuredContent`. Non-text resource blocks and tool errors retain their existing content behavior. Structured projections use the same sanitized and filtered source as the legacy formatter.
624624

625-
The issue metadata (`list_issue_types`, `list_issue_fields`), comment (`add_issue_comment`, `update_issue_comment`), dependency (`issue_dependency_read`, `issue_dependency_write`), and duplicate-detection (`find_duplicate`) tools provide typed `outputSchema` and `structuredContent` for protocol `2026-07-28` and newer. Older or unknown protocol versions retain the same text responses without these fields. Tool errors do not return structured content. Dependency and duplicate-detection tools retain their existing feature gates.
625+
The issue metadata (`list_issue_types`, `list_issue_fields`), comment (`add_issue_comment`, `update_issue_comment`), dependency (`issue_dependency_read`, `issue_dependency_write`), and duplicate-detection (`find_duplicate`) tools provide typed `outputSchema` and `structuredContent` for negotiated supported protocol versions `2026-07-28` or newer. Older or unknown protocol versions retain the same text responses without these fields. Tool errors do not return structured content. Dependency and duplicate-detection tools retain their existing feature gates.
626+
627+
For negotiated supported protocol versions `2026-07-28` or newer, the consolidated Actions tools (`actions_list`, `actions_get`, `actions_run_trigger`) return structured objects with a `method` discriminant and a method-specific typed field; JSON text contains the same compact projection. Workflow, job, and artifact projections omit API/hypermedia URLs while retaining browser links and useful identifiers, states, timestamps, and usage durations. Run usage lists billable runner environments in deterministic name order. Older and unknown-protocol text responses remain unchanged; `get_job_logs` retains its typed content, URL, or failed-job collection variants.
626628

627629
<!-- START AUTOMATED TOOLS -->
628630
<details>
@@ -631,7 +633,7 @@ The issue metadata (`list_issue_types`, `list_issue_fields`), comment (`add_issu
631633

632634
- **actions_get** - Get details of GitHub Actions resources (workflows, workflow runs, jobs, and artifacts)
633635
- **OAuth Challenge Scopes**: `repo`
634-
- `method`: The method to execute Supported values: get_workflow, get_workflow_run, get_workflow_job, download_workflow_run_artifact, get_workflow_run_usage, get_workflow_run_logs_url. (string, required)
636+
- `method`: The method to execute (string, required)
635637
- `owner`: Repository owner (string, required)
636638
- `repo`: Repository name (string, required)
637639
- `resource_id`: The unique identifier of the resource. This will vary based on the "method" provided, so ensure you provide the correct ID:
@@ -643,7 +645,7 @@ The issue metadata (`list_issue_types`, `list_issue_fields`), comment (`add_issu
643645

644646
- **actions_list** - List GitHub Actions workflows in a repository
645647
- **OAuth Challenge Scopes**: `repo`
646-
- `method`: The action to perform Supported values: list_workflows, list_workflow_runs, list_workflow_jobs, list_workflow_run_artifacts. (string, required)
648+
- `method`: The action to perform (string, required)
647649
- `owner`: Repository owner (string, required)
648650
- `page`: Page number for pagination (default: 1) (number, optional)
649651
- `perPage`: Results per page for pagination (default: 30, max: 100) (number, optional)
@@ -653,13 +655,13 @@ The issue metadata (`list_issue_types`, `list_issue_fields`), comment (`add_issu
653655
- Provide a workflow ID or workflow file name (e.g. ci.yaml) for 'list_workflow_runs' method, or omit to list all workflow runs in the repository.
654656
- Provide a workflow run ID for 'list_workflow_jobs' and 'list_workflow_run_artifacts' methods.
655657
(string, optional)
656-
- `workflow_jobs_filter`: Filters for workflow jobs. **ONLY** used when method is 'list_workflow_jobs' (object | any, optional)
657-
- `workflow_runs_filter`: Filters for workflow runs. **ONLY** used when method is 'list_workflow_runs' (object | any, optional)
658+
- `workflow_jobs_filter`: Filters for workflow jobs. **ONLY** used when method is 'list_workflow_jobs' (object, optional)
659+
- `workflow_runs_filter`: Filters for workflow runs. **ONLY** used when method is 'list_workflow_runs' (object, optional)
658660

659661
- **actions_run_trigger** - Trigger GitHub Actions workflow actions
660662
- **OAuth Challenge Scopes**: `repo`
661663
- `inputs`: Inputs the workflow accepts. Only used for 'run_workflow' method. (object, optional)
662-
- `method`: The method to execute Supported values: run_workflow, rerun_workflow_run, rerun_failed_jobs, cancel_workflow_run, delete_workflow_run_logs. (string, required)
664+
- `method`: The method to execute (string, required)
663665
- `owner`: Repository owner (string, required)
664666
- `ref`: The git reference for the workflow. The reference can be a branch or tag name. Required for 'run_workflow' method. (string, optional)
665667
- `repo`: Repository name (string, required)

‎docs/error-handling.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -60,10 +60,12 @@ return ghErrors.NewGitHubGraphQLErrorResponse(ctx, message, err), nil
6060
### Typed Tool Results
6161

6262
Tools registered with concrete `NewTool[In, Out]` types expose output schemas and
63-
`structuredContent` only when the negotiated protocol is `2026-07-28` or newer.
64-
Older or unknown protocols retain the original text responses without these
65-
typed-output additions. Ordinary API and validation errors never expose the
66-
SDK-generated zero-value structured output.
63+
`structuredContent` when the negotiated protocol version is a supported version
64+
`2026-07-28` or newer. Older, unknown, or omitted protocol versions retain the
65+
original text responses without these typed-output additions. Unknown versions
66+
are not treated as supported merely because they sort after `2026-07-28`.
67+
Ordinary API and validation errors never expose the SDK-generated zero-value
68+
structured output.
6769

6870
Handler-provided structured statuses are distinct from generated error output.
6971
For example, `issue_write` can return `IsError: true` with

0 commit comments

Comments
 (0)