# GitHub tools (https://www.shipfox.io/docs/integrations/github/tools)

Description: 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](https://www.shipfox.io/docs/integrations/github) for authentication and setup.

## Selectors [#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](https://www.shipfox.io/docs/reference/workflow-schema#tool-step-fields) and [Agent integration
fields](https://www.shipfox.io/docs/reference/workflow-schema#agent-integration-fields).

## Tool catalog [#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](https://www.shipfox.io/docs/integrations/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`](https://www.shipfox.io/docs/integrations/github/tools#issue_read), [`issue_read.*`](https://www.shipfox.io/docs/integrations/github/tools#issue_read), [`issue_read.get`](https://www.shipfox.io/docs/integrations/github/tools#issue_readget), [`issue_read.get_comments`](https://www.shipfox.io/docs/integrations/github/tools#issue_readget_comments), [`issue_read.get_sub_issues`](https://www.shipfox.io/docs/integrations/github/tools#issue_readget_sub_issues), [`issue_read.get_parent`](https://www.shipfox.io/docs/integrations/github/tools#issue_readget_parent), [`issue_read.get_labels`](https://www.shipfox.io/docs/integrations/github/tools#issue_readget_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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#issue_write), [`issue_write.*`](https://www.shipfox.io/docs/integrations/github/tools#issue_write), [`issue_write.create`](https://www.shipfox.io/docs/integrations/github/tools#issue_writecreate), [`issue_write.update`](https://www.shipfox.io/docs/integrations/github/tools#issue_writeupdate)

##### 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`](https://www.shipfox.io/docs/integrations/github/tools#sub_issue_write), [`sub_issue_write.*`](https://www.shipfox.io/docs/integrations/github/tools#sub_issue_write), [`sub_issue_write.add`](https://www.shipfox.io/docs/integrations/github/tools#sub_issue_writeadd), [`sub_issue_write.remove`](https://www.shipfox.io/docs/integrations/github/tools#sub_issue_writeremove), [`sub_issue_write.reprioritize`](https://www.shipfox.io/docs/integrations/github/tools#sub_issue_writereprioritize)

##### 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`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_read), [`pull_request_read.*`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_read), [`pull_request_read.get`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_readget), [`pull_request_read.get_diff`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_readget_diff), [`pull_request_read.get_status`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_readget_status), [`pull_request_read.get_files`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_readget_files), [`pull_request_read.get_commits`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_readget_commits), [`pull_request_read.get_review_comments`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_readget_review_comments), [`pull_request_read.get_review_threads`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_readget_review_threads), [`pull_request_read.get_reviews`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_readget_reviews), [`pull_request_read.get_comments`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_readget_comments), [`pull_request_read.get_check_runs`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_readget_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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_review_write), [`pull_request_review_write.*`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_review_write), [`pull_request_review_write.create`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_review_writecreate), [`pull_request_review_write.submit_pending`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_review_writesubmit_pending), [`pull_request_review_write.delete_pending`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_review_writedelete_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`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_review_thread_write), [`pull_request_review_thread_write.*`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_review_thread_write), [`pull_request_review_thread_write.resolve`](https://www.shipfox.io/docs/integrations/github/tools#pull_request_review_thread_writeresolve)

##### 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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#check_run_write), [`check_run_write.*`](https://www.shipfox.io/docs/integrations/github/tools#check_run_write), [`check_run_write.create`](https://www.shipfox.io/docs/integrations/github/tools#check_run_writecreate), [`check_run_write.update`](https://www.shipfox.io/docs/integrations/github/tools#check_run_writeupdate)

##### 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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#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`](https://www.shipfox.io/docs/integrations/github/tools#actions_list), [`actions_list.*`](https://www.shipfox.io/docs/integrations/github/tools#actions_list), [`actions_list.list_workflows`](https://www.shipfox.io/docs/integrations/github/tools#actions_listlist_workflows), [`actions_list.list_workflow_runs`](https://www.shipfox.io/docs/integrations/github/tools#actions_listlist_workflow_runs), [`actions_list.list_workflow_jobs`](https://www.shipfox.io/docs/integrations/github/tools#actions_listlist_workflow_jobs), [`actions_list.list_workflow_run_artifacts`](https://www.shipfox.io/docs/integrations/github/tools#actions_listlist_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`](https://www.shipfox.io/docs/integrations/github/tools#actions_get), [`actions_get.*`](https://www.shipfox.io/docs/integrations/github/tools#actions_get), [`actions_get.get_workflow`](https://www.shipfox.io/docs/integrations/github/tools#actions_getget_workflow), [`actions_get.get_workflow_run`](https://www.shipfox.io/docs/integrations/github/tools#actions_getget_workflow_run), [`actions_get.get_workflow_job`](https://www.shipfox.io/docs/integrations/github/tools#actions_getget_workflow_job), [`actions_get.download_workflow_run_artifact`](https://www.shipfox.io/docs/integrations/github/tools#actions_getdownload_workflow_run_artifact), [`actions_get.get_workflow_run_usage`](https://www.shipfox.io/docs/integrations/github/tools#actions_getget_workflow_run_usage), [`actions_get.get_workflow_run_logs_url`](https://www.shipfox.io/docs/integrations/github/tools#actions_getget_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`](https://www.shipfox.io/docs/integrations/github/tools#actions_run_trigger), [`actions_run_trigger.*`](https://www.shipfox.io/docs/integrations/github/tools#actions_run_trigger), [`actions_run_trigger.run_workflow`](https://www.shipfox.io/docs/integrations/github/tools#actions_run_triggerrun_workflow), [`actions_run_trigger.rerun_workflow_run`](https://www.shipfox.io/docs/integrations/github/tools#actions_run_triggerrerun_workflow_run), [`actions_run_trigger.rerun_failed_jobs`](https://www.shipfox.io/docs/integrations/github/tools#actions_run_triggerrerun_failed_jobs), [`actions_run_trigger.cancel_workflow_run`](https://www.shipfox.io/docs/integrations/github/tools#actions_run_triggercancel_workflow_run), [`actions_run_trigger.delete_workflow_run_logs`](https://www.shipfox.io/docs/integrations/github/tools#actions_run_triggerdelete_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`](https://www.shipfox.io/docs/integrations/github/tools#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.