GitHub tools
Look up the GitHub tools, selectors, permissions, inputs, and outputs available to tool steps and agent steps.
This reference lists the shipped GitHub tool catalog. See the GitHub overview for authentication and setup.
Selectors
A tool step names one method as family.method, such as issue_write.update,
in its tool field. A family name alone or family.* is rejected on a tool
step, because a tool step calls exactly one operation.
An agent step accepts a family, family.method, or family.* in its
integrations: block. For the field contracts, see Tool step
fields and Agent integration
fields.
Tool catalog
Grant the GitHub App only the repository permissions required by selected tools.
The catalog states each tool's read or write sensitivity and its required GitHub
permissions. An agent step's integrations entry must set allow_write: true
to include a write tool such as merge_pull_request, or Shipfox rejects the
step at validation. A tool step needs no flag: naming the write tool is the
choice.
The generated catalog also states each operation's repository classification:
- Declared targets: Shipfox can check repository coordinates from the tool input against the integration connection's repository-access mode.
- Integration connection: The input does not identify a complete repository target that Shipfox can check locally.
An indirect target note identifies a GitHub-side effect that can reach beyond the declared target. See GitHub repository access for the boundary and its limits.
issues
issue_read
Get information about a specific issue in a GitHub repository.
Sensitivity: read.
Sensitive: No.
Required permissions: issues:read
Repository classification: Declared targets.
Selector tokens: issue_read, issue_read.*, issue_read.get, issue_read.get_comments, issue_read.get_sub_issues, issue_read.get_parent, issue_read.get_labels
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
method | string: get, get_comments, get_sub_issues, get_parent, get_labels | Required | The read operation to perform on a single issue |
issue_number | integer | Required | The number of the issue |
page | integer | Optional | Page number for pagination |
per_page | integer | Optional | Results per page for pagination |
issue_read.get
Get information about a specific issue.
Sensitivity: read.
Sensitive: No.
Required permissions: issues:read
Repository classification: Declared targets.
This method has no additional required input.
issue_read.get_comments
Get comments on a specific issue.
Sensitivity: read.
Sensitive: No.
Required permissions: issues:read
Repository classification: Declared targets.
This method has no additional required input.
issue_read.get_sub_issues
Get sub-issues for a specific issue.
Sensitivity: read.
Sensitive: No.
Required permissions: issues:read
Repository classification: Declared targets.
This method has no additional required input.
issue_read.get_parent
Get the parent issue for a specific issue.
Sensitivity: read.
Sensitive: No.
Required permissions: issues:read
Repository classification: Declared targets.
This method has no additional required input.
issue_read.get_labels
Get labels assigned to a specific issue.
Sensitivity: read.
Sensitive: No.
Required permissions: issues:read
Repository classification: Declared targets.
This method has no additional required input.
Output
This schema accepts an object with provider-defined fields.
list_issue_types
List the issue types available to a GitHub repository. Issue types are defined by the owning organization, so the result also describes the organization.
Sensitivity: read.
Sensitive: No.
Required permissions: issues:read
Repository classification: Declared targets.
Selector tokens: list_issue_types
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
Output
| Field | Type | Required | Description |
|---|---|---|---|
issue_types | array | Required |
list_issues
List issues in a GitHub repository. For pagination, use the 'endCursor' from the previous response's 'pageInfo' in the 'after' parameter.
Sensitivity: read.
Sensitive: No.
Required permissions: issues:read
Repository classification: Declared targets.
Selector tokens: list_issues
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
state | string: OPEN, CLOSED | Optional | Filter by state |
labels | array | Optional | |
orderBy | string: CREATED_AT, UPDATED_AT, COMMENTS | Optional | Order issues by field |
direction | string: ASC, DESC | Optional | Order direction |
since | string | Optional | Filter by date (ISO 8601 timestamp) |
after | string | Optional | Pagination cursor |
first | integer | Optional | Number of issues to return |
Output
| Field | Type | Required | Description |
|---|---|---|---|
issues | array | Required |
search_issues
Search for issues in GitHub repositories using issues search syntax already scoped to is:issue. Provide owner and repo together for a repository-scoped search; omit both for a connection-scoped search. Do not include unquoted repo:, org:, or user: qualifiers; quoted occurrences are treated as literal text.
Sensitivity: read.
Sensitive: No.
Required permissions: issues:read
Repository classification: Declared targets with owner and repo. Selected mode requires both. Without them, all mode uses the integration connection.
Indirect target: The free-form query may match results in repositories other than the declared target.
Selector tokens: search_issues
Input
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Required | Search query using GitHub issues search syntax. Do not include unquoted repo:, org:, or user: qualifiers; quoted occurrences are treated as literal text. |
owner | string | Conditional | Optional repository owner. Provide together with repo, or omit both for a connection-scoped search. |
repo | string | Conditional | Optional repository name. Provide together with owner, or omit both for a connection-scoped search. |
sort | string: comments, reactions, reactions-+1, reactions--1, reactions-smile, reactions-thinking_face, reactions-heart, reactions-tada, interactions, created, updated | Optional | Sort field |
order | string: asc, desc | Optional | Sort order |
page | integer | Optional | Page number for pagination |
per_page | integer | Optional | Results per page for pagination |
Output
| Field | Type | Required | Description |
|---|---|---|---|
issues | array | Required |
add_issue_comment
Add a comment and/or reaction to a specific issue or issue comment in a GitHub repository. Use this tool with pull requests as well, but only if the user is not asking specifically to add or react to review comments. At least one of body or reaction is required.
Sensitivity: write.
Sensitive: No.
Required permissions: issues:write, pull_requests:write
Repository classification: Declared targets.
Selector tokens: add_issue_comment
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
issue_number | integer | Conditional | Issue or pull request number to comment on or react to |
comment_id | integer | Conditional | The numeric ID of the issue or pull request comment to react to |
body | string | Conditional | Comment content. Required unless reaction is provided |
reaction | string: +1, -1, laugh, confused, heart, hooray, rocket, eyes | Conditional | Emoji reaction to add. Required unless body is provided |
At least one of these input combinations is required: issue_number and body; issue_number and reaction; comment_id and reaction.
Output
This schema accepts an object with provider-defined fields.
issue_write
Create a new or update an existing issue in a GitHub repository.
Sensitivity: write.
Sensitive: No.
Required permissions: issues:write
Repository classification: Declared targets.
Selector tokens: issue_write, issue_write.*, issue_write.create, issue_write.update
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
method | string: create, update | Required | Write operation to perform on a single issue |
issue_number | integer | Optional | Issue number to update |
title | string | Optional | Issue title |
body | string | Optional | Issue body content |
assignees | array | Optional | |
labels | array | Optional | |
milestone | integer | Optional | Milestone number |
issue_type | string | Optional | Type of this issue |
state | string: open, closed | Optional | New state |
state_reason | string: completed, not_planned, duplicate | Optional | Reason for the state change |
duplicate_of | integer | Optional | Issue number that this issue is a duplicate of |
issue_write.create
Create a new issue.
Sensitivity: write.
Sensitive: No.
Required permissions: issues:write
Repository classification: Declared targets.
This method has no additional required input.
issue_write.update
Update an existing issue.
Sensitivity: write.
Sensitive: No.
Required permissions: issues:write
Repository classification: Declared targets.
This method has no additional required input.
Output
This schema accepts an object with provider-defined fields.
sub_issue_write
Add, remove, or reprioritize a sub-issue under a parent issue in a GitHub repository.
Sensitivity: write.
Sensitive: No.
Required permissions: issues:write
Repository classification: Declared targets.
Indirect target: The opaque child and ordering IDs may refer to another repository in the GitHub installation.
Selector tokens: sub_issue_write, sub_issue_write.*, sub_issue_write.add, sub_issue_write.remove, sub_issue_write.reprioritize
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
method | string: add, remove, reprioritize | Required | The action to perform on a single sub-issue |
issue_number | integer | Required | The number of the parent issue |
sub_issue_id | integer | Required | The ID of the sub-issue |
replace_parent | boolean | Optional | Replace the sub-issue's current parent issue |
after_id | integer | Optional | The ID of the sub-issue to be prioritized after |
before_id | integer | Optional | The ID of the sub-issue to be prioritized before |
sub_issue_write.add
Add a sub-issue to a parent issue.
Sensitivity: write.
Sensitive: No.
Required permissions: issues:write
Repository classification: Declared targets.
Indirect target: The opaque child and ordering IDs may refer to another repository in the GitHub installation.
This method has no additional required input.
sub_issue_write.remove
Remove a sub-issue from a parent issue.
Sensitivity: write.
Sensitive: No.
Required permissions: issues:write
Repository classification: Declared targets.
Indirect target: The opaque child and ordering IDs may refer to another repository in the GitHub installation.
This method has no additional required input.
sub_issue_write.reprioritize
Reprioritize a sub-issue under its parent issue.
Sensitivity: write.
Sensitive: No.
Required permissions: issues:write
Repository classification: Declared targets.
Indirect target: The opaque child and ordering IDs may refer to another repository in the GitHub installation.
This method has no additional required input.
Output
This schema accepts an object with provider-defined fields.
pull requests
pull_request_read
Get information on a specific pull request in a GitHub repository.
Sensitivity: read.
Sensitive: No.
Required permissions: pull_requests:read, contents:read, statuses:read, checks:read
Repository classification: Declared targets.
Selector tokens: pull_request_read, pull_request_read.*, pull_request_read.get, pull_request_read.get_diff, pull_request_read.get_status, pull_request_read.get_files, pull_request_read.get_commits, pull_request_read.get_review_comments, pull_request_read.get_review_threads, pull_request_read.get_reviews, pull_request_read.get_comments, pull_request_read.get_check_runs
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
method | string: get, get_diff, get_status, get_files, get_commits, get_review_comments, get_review_threads, get_reviews, get_comments, get_check_runs | Required | Action to specify what pull request data needs to be retrieved from GitHub |
pull_number | integer | Required | Pull request number |
ref | string | Conditional | Git reference to inspect. Required for get_status and get_check_runs |
cursor | string | Optional | Cursor for review comment pagination |
page | integer | Optional | Page number for pagination |
per_page | integer | Optional | Results per page for pagination |
pull_request_read.get
Get information about a specific pull request.
Sensitivity: read.
Sensitive: No.
Required permissions: pull_requests:read
Repository classification: Declared targets.
This method has no additional required input.
pull_request_read.get_diff
Get the diff for a specific pull request.
Sensitivity: read.
Sensitive: No.
Required permissions: contents:read
Repository classification: Declared targets.
This method has no additional required input.
pull_request_read.get_status
Get status information for a specific pull request.
Sensitivity: read.
Sensitive: No.
Required permissions: statuses:read
Repository classification: Declared targets.
Required input for this method: ref.
pull_request_read.get_files
Get files changed in a specific pull request.
Sensitivity: read.
Sensitive: No.
Required permissions: pull_requests:read
Repository classification: Declared targets.
This method has no additional required input.
pull_request_read.get_commits
Get commits in a specific pull request.
Sensitivity: read.
Sensitive: No.
Required permissions: pull_requests:read
Repository classification: Declared targets.
This method has no additional required input.
pull_request_read.get_review_comments
Get review comments for a specific pull request.
Sensitivity: read.
Sensitive: No.
Required permissions: pull_requests:read
Repository classification: Declared targets.
This method has no additional required input.
pull_request_read.get_review_threads
Get review threads, their resolution state, and comments for a specific pull request.
Sensitivity: read.
Sensitive: No.
Required permissions: pull_requests:read
Repository classification: Declared targets.
This method has no additional required input.
pull_request_read.get_reviews
Get reviews for a specific pull request.
Sensitivity: read.
Sensitive: No.
Required permissions: pull_requests:read
Repository classification: Declared targets.
This method has no additional required input.
pull_request_read.get_comments
Get conversation comments for a specific pull request.
Sensitivity: read.
Sensitive: No.
Required permissions: pull_requests:read
Accepted instead: issues:read
Repository classification: Declared targets.
This method has no additional required input.
pull_request_read.get_check_runs
Get check runs for the head commit of a pull request.
Sensitivity: read.
Sensitive: No.
Required permissions: checks:read
Repository classification: Declared targets.
Required input for this method: ref.
Output
This schema accepts an object with provider-defined fields.
list_pull_requests
List pull requests in a GitHub repository. If the user specifies an author, then do not use this tool and use the search_pull_requests tool instead.
Sensitivity: read.
Sensitive: No.
Required permissions: pull_requests:read
Repository classification: Declared targets.
Selector tokens: list_pull_requests
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
state | string: open, closed, all | Optional | Filter by state |
head | string | Optional | Filter by head user/org and branch |
base | string | Optional | Filter by base branch |
sort | string: created, updated, popularity, long-running | Optional | Sort by |
direction | string: asc, desc | Optional | Sort direction |
page | integer | Optional | Page number for pagination |
per_page | integer | Optional | Results per page for pagination |
Output
| Field | Type | Required | Description |
|---|---|---|---|
pull_requests | array | Required |
search_pull_requests
Search for pull requests in GitHub repositories using issues search syntax already scoped to is:pr. Provide owner and repo together for a repository-scoped search; omit both for a connection-scoped search. Do not include unquoted repo:, org:, or user: qualifiers; quoted occurrences are treated as literal text.
Sensitivity: read.
Sensitive: No.
Required permissions: pull_requests:read
Repository classification: Declared targets with owner and repo. Selected mode requires both. Without them, all mode uses the integration connection.
Indirect target: The free-form query may match results in repositories other than the declared target.
Selector tokens: search_pull_requests
Input
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Required | Search query using GitHub pull request search syntax. Do not include unquoted repo:, org:, or user: qualifiers; quoted occurrences are treated as literal text. |
owner | string | Conditional | Optional repository owner. Provide together with repo, or omit both for a connection-scoped search. |
repo | string | Conditional | Optional repository name. Provide together with owner, or omit both for a connection-scoped search. |
sort | string: comments, reactions, reactions-+1, reactions--1, reactions-smile, reactions-thinking_face, reactions-heart, reactions-tada, interactions, created, updated | Optional | Sort field |
order | string: asc, desc | Optional | Sort order |
page | integer | Optional | Page number for pagination |
per_page | integer | Optional | Results per page for pagination |
Output
| Field | Type | Required | Description |
|---|---|---|---|
pull_requests | array | Required |
create_pull_request
Create a new pull request in a GitHub repository.
Sensitivity: write.
Sensitive: No.
Required permissions: pull_requests:write
Repository classification: Declared targets.
Selector tokens: create_pull_request
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
title | string | Required | PR title |
body | string | Optional | PR description |
head | string | Required | Branch containing changes |
base | string | Required | Branch to merge into |
draft | boolean | Optional | Create as draft PR |
maintainer_can_modify | boolean | Optional | Allow maintainer edits |
reviewers | array | Optional |
Output
| Field | Type | Required | Description |
|---|---|---|---|
pull_request | object | Required | Created GitHub pull request |
update_pull_request
Update an existing pull request in a GitHub repository.
Sensitivity: write.
Sensitive: No.
Required permissions: pull_requests:write
Repository classification: Declared targets.
Selector tokens: update_pull_request
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
pull_number | integer | Required | Pull request number to update |
title | string | Optional | New title |
body | string | Optional | New description |
state | string: open, closed | Optional | New state |
base | string | Optional | New base branch name |
maintainer_can_modify | boolean | Optional | Allow maintainer edits |
reviewers | array | Optional |
Output
| Field | Type | Required | Description |
|---|---|---|---|
pull_request | object | Required | Updated GitHub pull request |
add_reply_to_pull_request_comment
Add a reply and/or reaction to an existing pull request comment. This can create a new comment linked as a reply to the specified comment, add an emoji reaction to the specified comment, or do both. At least one of body or reaction is required.
Sensitivity: write.
Sensitive: No.
Required permissions: pull_requests:write
Repository classification: Declared targets.
Selector tokens: add_reply_to_pull_request_comment
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
pull_number | integer | Conditional | Pull request number. Required when body is provided |
comment_id | integer | Required | The numeric ID of the pull request review comment to reply or react to |
body | string | Conditional | The text of the reply |
reaction | string: +1, -1, laugh, confused, heart, hooray, rocket, eyes | Conditional | Emoji reaction to add |
At least one of these input combinations is required: pull_number and body; reaction.
Output
This schema accepts an object with provider-defined fields.
merge_pull_request
Merge a pull request in a GitHub repository.
Sensitivity: write.
Sensitive: Yes.
Required permissions: pull_requests:write, contents:write
Repository classification: Declared targets.
Selector tokens: merge_pull_request
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
pull_number | integer | Required | Pull request number |
commit_title | string | Optional | Title for merge commit |
commit_message | string | Optional | Extra detail for merge commit |
merge_method | string: merge, squash, rebase | Optional | Merge method |
Output
| Field | Type | Required | Description |
|---|---|---|---|
merge | object | Required | Merge result |
update_pull_request_branch
Update the branch of a pull request with the latest changes from the base branch.
Sensitivity: write.
Sensitive: No.
Required permissions: pull_requests:write, contents:write
Repository classification: Declared targets.
Indirect target: GitHub can also update the pull request head branch, which may belong to another repository.
Selector tokens: update_pull_request_branch
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
pull_number | integer | Required | Pull request number |
expected_head_sha | string | Optional | The expected SHA of the pull request's HEAD ref |
Output
This schema accepts an object with provider-defined fields.
pull_request_review_write
Stage, submit, or delete a pull request review. create opens a pending review, add_comment_to_pending_review attaches inline comments to it, and submit_pending publishes it with its summary.
Sensitivity: write.
Sensitive: No.
Required permissions: pull_requests:write
Repository classification: Declared targets.
Selector tokens: pull_request_review_write, pull_request_review_write.*, pull_request_review_write.create, pull_request_review_write.submit_pending, pull_request_review_write.delete_pending
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
method | string: create, submit_pending, delete_pending | Required | The write operation to perform on pull request review |
pull_number | integer | Required | Pull request number |
body | string | Optional | Review summary text. Required by submit_pending unless event is APPROVE; not accepted by delete_pending |
event | string: APPROVE, REQUEST_CHANGES, COMMENT | Optional | Review action. Required by submit_pending; not accepted by create or delete_pending |
commit_id | string | Optional | SHA of the commit to review. Only accepted by create |
pull_request_review_write.create
Create a pending pull request review.
Sensitivity: write.
Sensitive: No.
Required permissions: pull_requests:write
Repository classification: Declared targets.
This method has no additional required input.
pull_request_review_write.submit_pending
Submit the latest pending pull request review.
Sensitivity: write.
Sensitive: No.
Required permissions: pull_requests:write
Repository classification: Declared targets.
This method has no additional required input.
pull_request_review_write.delete_pending
Delete the latest pending pull request review.
Sensitivity: write.
Sensitive: No.
Required permissions: pull_requests:write
Repository classification: Declared targets.
This method has no additional required input.
Output
This schema accepts an object with provider-defined fields.
pull_request_review_thread_write
Resolve a pull request review thread by opaque node ID. This operation is connection-scoped because the node ID does not declare a repository.
Sensitivity: write.
Sensitive: No.
Required permissions: pull_requests:write
Repository classification: Integration connection.
Indirect target: The review thread node may belong to any repository reachable by the GitHub installation.
Selector tokens: pull_request_review_thread_write, pull_request_review_thread_write.*, pull_request_review_thread_write.resolve
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
method | string: resolve | Required | The write operation to perform on a pull request review thread |
thread_id | string | Required | The node ID of the review thread |
pull_request_review_thread_write.resolve
Resolve a pull request review thread.
Sensitivity: write.
Sensitive: No.
Required permissions: pull_requests:write
Repository classification: Integration connection.
Indirect target: The review thread node may belong to any repository reachable by the GitHub installation.
This method has no additional required input.
Output
This schema accepts an object with provider-defined fields.
add_comment_to_pending_review
Add a review comment to the requester's latest pending pull request review. The comment remains part of that pending review until it is submitted; a pending review needs to already exist to call this.
Sensitivity: write.
Sensitive: No.
Required permissions: pull_requests:write
Repository classification: Declared targets.
Selector tokens: add_comment_to_pending_review
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
pull_number | integer | Required | Pull request number |
path | string | Required | The relative path to the file that necessitates a comment |
body | string | Required | The text of the review comment |
subject_type | string: LINE, FILE | Optional | The level at which the comment is targeted. LINE (default) requires line and side; FILE accepts no position fields |
line | integer | Optional | The line of the blob in the pull request diff. Required for LINE |
side | string: LEFT, RIGHT | Optional | The side of the diff to comment on. Required for LINE |
start_line | integer | Optional | The first line of a multi-line comment range. Must be lower than line and paired with start_side |
start_side | string: LEFT, RIGHT | Optional | The starting side of a multi-line comment range. Paired with start_line |
Output
This schema accepts an object with provider-defined fields.
checks
check_run_write
Create or update a check run for a commit in a GitHub repository.
Sensitivity: write.
Sensitive: No.
Required permissions: checks:write
Repository classification: Declared targets.
Selector tokens: check_run_write, check_run_write.*, check_run_write.create, check_run_write.update
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
method | string: create, update | Required | The check-run operation to perform |
check_run_id | integer | Conditional | The positive numeric ID of the check run to update |
name | string | Conditional | Stable display name for the check |
head_sha | string | Conditional | Full, non-zero 40- or 64-character hexadecimal commit object ID |
details_url | string | Optional | Absolute HTTP or HTTPS link with more details |
external_id | string | Optional | Caller-owned correlation key |
status | string: queued, in_progress, completed | Optional | Check-run lifecycle status |
started_at | string | Optional | RFC 3339 timestamp when the check started; leap seconds are accepted only when the normalized UTC instant is 23:59:60 on June 30 or December 31 |
conclusion | string: action_required, cancelled, failure, neutral, success, skipped, timed_out | Optional | Final check-run conclusion |
completed_at | string | Optional | RFC 3339 timestamp when the check completed; leap seconds are accepted only when the normalized UTC instant is 23:59:60 on June 30 or December 31 |
output | object | Optional |
check_run_write.create
Create a check run for a commit in a GitHub repository.
Sensitivity: write.
Sensitive: No.
Required permissions: checks:write
Repository classification: Declared targets.
Required input for this method: name, head_sha.
check_run_write.update
Update an existing check run in a GitHub repository.
Sensitivity: write.
Sensitive: No.
Required permissions: checks:write
Repository classification: Declared targets.
Required input for this method: check_run_id.
Output
| Field | Type | Required | Description |
|---|---|---|---|
check_run | object | Required |
repository
create_commit
Create a commit on an existing branch in a GitHub repository. The commit is authored and signed by GitHub on behalf of the Shipfox bot (shipfox-ai[bot]) and shows the Verified badge. Renames are expressed as a deletion of the old path plus an addition of the new path. File contents are validated server-side and limited to a total of about 1 MiB per call; keep edits small and explicit. Text contents are sent as utf8 and transcoded to base64 by the server; binary contents can be provided with encoding base64. The expected_head_oid must be the current head of the branch (compare-and-swap): if the branch moved, the commit is rejected with a stale-head error and the call should be retried with the new head. When issuing several dependent commits, derive each expected_head_oid from the returned oid of the previous commit so the commits land in order. Branch protection rules are the only barrier to writing the default branch. Files under .github/workflows need the workflows permission, which the installation token may not carry; such changes are rejected with access-denied when it is missing.
Sensitivity: write.
Sensitive: No.
Required permissions: contents:write
Repository classification: Declared targets.
Selector tokens: create_commit
Input
| Field | Type | Required | Description |
|---|---|---|---|
repository | string | Required | Repository in owner/name format. Must be a repository the connection can access. |
branch | string | Required | The name of the existing branch to commit to |
expected_head_oid | string | Required | The commit oid (40 or 64 hexadecimal characters) the branch head is expected to point to (compare-and-swap) |
message | object | Required | |
additions | array | Optional | |
deletions | array | Optional |
Output
| Field | Type | Required | Description |
|---|---|---|---|
commit | object | Required |
create_branch
Create a branch in a GitHub repository pointing at a commit. Provide from as a 40- or 64-character commit oid (for example, the checkout commit of a step) or as an existing branch name, which the server resolves to its current head at call time. An existing branch is reused when it already points at the requested commit, and rejected otherwise. Creating a branch fires GitHub push-event workflows from the new ref, so only branch from commits you intend to activate.
Sensitivity: write.
Sensitive: No.
Required permissions: contents:write
Repository classification: Declared targets.
Selector tokens: create_branch
Input
| Field | Type | Required | Description |
|---|---|---|---|
repository | string | Required | The repository in owner/name form |
branch | string | Required | The name of the branch to create, without any refs/ prefix |
from | string | Required | The 40- or 64-character commit oid or existing branch name the new branch points at |
Output
| Field | Type | Required | Description |
|---|---|---|---|
branch | string | Required | The name of the created branch |
oid | string | Required | The commit oid the created branch points at |
url | string | Required | The API URL of the created git ref |
actions
actions_list
Tools for listing GitHub Actions resources. Use this tool to list workflows in a repository, or list workflow runs, jobs, and artifacts for a specific workflow or workflow run.
Sensitivity: read.
Sensitive: No.
Required permissions: actions:read
Repository classification: Declared targets.
Selector tokens: actions_list, actions_list.*, actions_list.list_workflows, actions_list.list_workflow_runs, actions_list.list_workflow_jobs, actions_list.list_workflow_run_artifacts
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
method | string: list_workflows, list_workflow_runs, list_workflow_jobs, list_workflow_run_artifacts | Required | The action to perform |
resource_id | string | Optional | The unique identifier of the resource |
workflow_runs_filter | object | Optional | Filters for workflow runs |
workflow_jobs_filter | object | Optional | Filters for workflow jobs |
page | integer | Optional | Page number for pagination |
per_page | integer | Optional | Results per page for pagination |
actions_list.list_workflows
List workflows in a repository.
Sensitivity: read.
Sensitive: No.
Required permissions: actions:read
Repository classification: Declared targets.
This method has no additional required input.
actions_list.list_workflow_runs
List workflow runs in a repository or for a workflow.
Sensitivity: read.
Sensitive: No.
Required permissions: actions:read
Repository classification: Declared targets.
This method has no additional required input.
actions_list.list_workflow_jobs
List jobs for a workflow run.
Sensitivity: read.
Sensitive: No.
Required permissions: actions:read
Repository classification: Declared targets.
This method has no additional required input.
actions_list.list_workflow_run_artifacts
List artifacts for a workflow run.
Sensitivity: read.
Sensitive: No.
Required permissions: actions:read
Repository classification: Declared targets.
This method has no additional required input.
Output
This schema accepts an object with provider-defined fields.
actions_get
Get details about specific GitHub Actions resources. Use this tool to get details about individual workflows, workflow runs, jobs, and artifacts by their unique IDs.
Sensitivity: read.
Sensitive: No.
Required permissions: actions:read
Repository classification: Declared targets.
Selector tokens: actions_get, actions_get.*, actions_get.get_workflow, actions_get.get_workflow_run, actions_get.get_workflow_job, actions_get.download_workflow_run_artifact, actions_get.get_workflow_run_usage, actions_get.get_workflow_run_logs_url
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
method | string: get_workflow, get_workflow_run, get_workflow_job, download_workflow_run_artifact, get_workflow_run_usage, get_workflow_run_logs_url | Required | The method to execute |
resource_id | string | Required | The unique identifier of the resource |
actions_get.get_workflow
Get details for a workflow.
Sensitivity: read.
Sensitive: No.
Required permissions: actions:read
Repository classification: Declared targets.
This method has no additional required input.
actions_get.get_workflow_run
Get details for a workflow run.
Sensitivity: read.
Sensitive: No.
Required permissions: actions:read
Repository classification: Declared targets.
This method has no additional required input.
actions_get.get_workflow_job
Get details for a workflow job.
Sensitivity: read.
Sensitive: No.
Required permissions: actions:read
Repository classification: Declared targets.
This method has no additional required input.
actions_get.download_workflow_run_artifact
Download a workflow run artifact.
Sensitivity: read.
Sensitive: No.
Required permissions: actions:read
Repository classification: Declared targets.
This method has no additional required input.
actions_get.get_workflow_run_usage
Get workflow run usage.
Sensitivity: read.
Sensitive: No.
Required permissions: actions:read
Repository classification: Declared targets.
This method has no additional required input.
actions_get.get_workflow_run_logs_url
Get a workflow run logs download URL.
Sensitivity: read.
Sensitive: No.
Required permissions: actions:read
Repository classification: Declared targets.
This method has no additional required input.
Output
This schema accepts an object with provider-defined fields.
actions_run_trigger
Trigger GitHub Actions workflow operations, including running, re-running, cancelling workflow runs, and deleting workflow run logs.
Sensitivity: write.
Sensitive: Yes.
Required permissions: actions:write
Repository classification: Declared targets.
Selector tokens: actions_run_trigger, actions_run_trigger.*, actions_run_trigger.run_workflow, actions_run_trigger.rerun_workflow_run, actions_run_trigger.rerun_failed_jobs, actions_run_trigger.cancel_workflow_run, actions_run_trigger.delete_workflow_run_logs
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
method | string: run_workflow, rerun_workflow_run, rerun_failed_jobs, cancel_workflow_run, delete_workflow_run_logs | Required | The method to execute |
workflow_id | string | Conditional | The workflow ID or workflow file name. Required for run_workflow |
ref | string | Conditional | The git reference for the workflow. Required for run_workflow |
inputs | object | Optional | Inputs the workflow accepts. Only used for run_workflow |
run_id | integer | Conditional | The ID of the workflow run. Required for all methods except run_workflow |
actions_run_trigger.run_workflow
Trigger a workflow_dispatch run.
Sensitivity: write.
Sensitive: Yes.
Required permissions: actions:write
Repository classification: Declared targets.
Required input for this method: workflow_id, ref.
actions_run_trigger.rerun_workflow_run
Rerun a workflow run.
Sensitivity: write.
Sensitive: No.
Required permissions: actions:write
Repository classification: Declared targets.
Required input for this method: run_id.
actions_run_trigger.rerun_failed_jobs
Rerun failed jobs in a workflow run.
Sensitivity: write.
Sensitive: No.
Required permissions: actions:write
Repository classification: Declared targets.
Required input for this method: run_id.
actions_run_trigger.cancel_workflow_run
Cancel a workflow run.
Sensitivity: write.
Sensitive: No.
Required permissions: actions:write
Repository classification: Declared targets.
Required input for this method: run_id.
actions_run_trigger.delete_workflow_run_logs
Delete logs for a workflow run.
Sensitivity: write.
Sensitive: Yes.
Required permissions: actions:write
Repository classification: Declared targets.
Required input for this method: run_id.
Output
This schema accepts an object with provider-defined fields.
get_job_logs
Get logs for GitHub Actions workflow jobs. Use this tool to retrieve logs for a specific job or all failed jobs in a workflow run. For single job logs, provide job_id. For all failed jobs in a run, provide run_id with failed_only=true.
Sensitivity: read.
Sensitive: No.
Required permissions: actions:read
Repository classification: Declared targets.
Selector tokens: get_job_logs
Input
| Field | Type | Required | Description |
|---|---|---|---|
owner | string | Required | Repository owner |
repo | string | Required | Repository name |
job_id | number | Optional | The unique identifier of the workflow job. Required when getting logs for a single job. |
run_id | number | Optional | The unique identifier of the workflow run. Required when failed_only is true to get logs for all failed jobs in the run. |
failed_only | boolean | Optional | When true, gets logs for all failed jobs in the workflow run specified by run_id. Requires run_id to be provided. |
return_content | boolean | Optional | Returns actual log content instead of URLs |
tail_lines | number | Optional | Number of lines to return from the end of the log |
Output
This schema accepts an object with provider-defined fields.