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.

Choose GitHub tools

A tool step must choose one operation, such as issue_write.update.

An agent integration can select a whole family, such as issue_write, or one operation in that family.

The permission fields in this catalog are advisory provider requirements. Backend GitHub agent tools use the full access granted to the GitHub App installation, and GitHub determines whether the requested operation is permitted. Shipfox still checks the caller, selected tool and method, write access, inputs, and declared repository target.

Authorized create_commit calls can write files under .github/workflows/. Those writes reach GitHub, which returns success or denial based on the installation's grants and repository rules. They do not use a separate workflow-file switch.

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

readissue_read

Get information about a specific issue in a GitHub repository.

Requiresissues:read

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

methodstringRequired

The read operation to perform on a single issue

Possible values: get, get_comments, get_sub_issues, get_parent, get_labels

issue_numberintegerRequired

The number of the issue

pageinteger

Page number for pagination

Minimum 1.

per_pageinteger

Results per page for pagination

Minimum 1. Maximum 100.

Methods

readissue_read.get

Get information about a specific issue.

Requiresissues:read

Repository: Declared targets.

No additional required input.

readissue_read.get_comments

Get comments on a specific issue.

Requiresissues:read

Repository: Declared targets.

No additional required input.

readissue_read.get_sub_issues

Get sub-issues for a specific issue.

Requiresissues:read

Repository: Declared targets.

No additional required input.

readissue_read.get_parent

Get the parent issue for a specific issue.

Requiresissues:read

Repository: Declared targets.

No additional required input.

readissue_read.get_labels

Get labels assigned to a specific issue.

Requiresissues:read

Repository: Declared targets.

No additional required input.

Returns

This tool returns the provider response without declared fields.

- key: issue_read
  tool: issue_read.get
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    issue_number: 1

readlist_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.

Requiresissues:read

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

Returns

issue_typesarray of objectRequired

- key: list_issue_types
  tool: list_issue_types
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
  outputs:
    issue_types: ${{ result.issue_types }}

readlist_issues

List issues in a GitHub repository. For pagination, use the 'endCursor' from the previous response's 'pageInfo' in the 'after' parameter.

Requiresissues:read

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

statestring

Filter by state

Possible values: OPEN, CLOSED

labelsarray of string

orderBystring

Order issues by field

Possible values: CREATED_AT, UPDATED_AT, COMMENTS

directionstring

Order direction

Possible values: ASC, DESC

sincestring

Filter by date (ISO 8601 timestamp)

afterstring

Pagination cursor

firstinteger

Number of issues to return

Minimum 1. Maximum 100.

Returns

issuesarray of objectRequired

- key: list_issues
  tool: list_issues
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
  outputs:
    issues: ${{ result.issues }}

readsearch_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.

Requiresissues:read

Repository: 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.

Parameters

querystringRequired

Search query using GitHub issues search syntax. Do not include unquoted repo:, org:, or user: qualifiers; quoted occurrences are treated as literal text.

ownerstringConditional

Optional repository owner. Provide together with repo, or omit both for a connection-scoped search.

repostringConditional

Optional repository name. Provide together with owner, or omit both for a connection-scoped search.

sortstring

Sort field

Possible values: comments, reactions, reactions-+1, reactions--1, reactions-smile, reactions-thinking_face, reactions-heart, reactions-tada, interactions, created, updated

orderstring

Sort order

Possible values: asc, desc

pageinteger

Page number for pagination

Minimum 1.

per_pageinteger

Results per page for pagination

Minimum 1. Maximum 100.

Returns

issuesarray of objectRequired

- key: search_issues
  tool: search_issues
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    query: <query>
  outputs:
    issues: ${{ result.issues }}

writeadd_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.

Requiresissues:write, pull_requests:write

Repository: Declared targets.

Parameters

At least one of these input combinations is required: issue_number and body; issue_number and reaction; comment_id and reaction.

ownerstringRequired

Repository owner

repostringRequired

Repository name

issue_numberintegerConditional

Issue or pull request number to comment on or react to

comment_idintegerConditional

The numeric ID of the issue or pull request comment to react to

bodystringConditional

Comment content. Required unless reaction is provided

reactionstringConditional

Emoji reaction to add. Required unless body is provided

Possible values: +1, -1, laugh, confused, heart, hooray, rocket, eyes

Returns

This tool returns the provider response without declared fields.

- key: add_issue_comment
  tool: add_issue_comment
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    issue_number: 1
    body: <body>

writeupdate_issue_comment

Replace the body of an issue or pull request conversation comment that this GitHub app wrote. Use it to keep one status comment up to date instead of posting a new one. Comments written by anyone else are rejected.

Requiresissues:write, pull_requests:write

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

comment_idintegerRequired

The numeric ID of the issue or pull request comment to edit

bodystringRequired

New comment content. Replaces the existing body

Returns

This tool returns the provider response without declared fields.

- key: update_issue_comment
  tool: update_issue_comment
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    comment_id: 1
    body: <body>

writeissue_write

Create a new or update an existing issue in a GitHub repository.

Requiresissues:write

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

methodstringRequired

Write operation to perform on a single issue

Possible values: create, update

issue_numberinteger

Issue number to update

titlestring

Issue title

bodystring

Issue body content

assigneesarray of string

labelsarray of string

milestoneinteger

Milestone number

issue_typestring

Type of this issue

statestring

New state

Possible values: open, closed

state_reasonstring

Reason for the state change

Possible values: completed, not_planned, duplicate

duplicate_ofinteger

Issue number that this issue is a duplicate of

Methods

writeissue_write.create

Create a new issue.

Requiresissues:write

Repository: Declared targets.

No additional required input.

writeissue_write.update

Update an existing issue.

Requiresissues:write

Repository: Declared targets.

No additional required input.

Returns

This tool returns the provider response without declared fields.

writesub_issue_write

Add, remove, or reprioritize a sub-issue under a parent issue in a GitHub repository.

Requiresissues:write

Repository: Declared targets.

Indirect target: The opaque child and ordering IDs may refer to another repository in the GitHub installation.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

methodstringRequired

The action to perform on a single sub-issue

Possible values: add, remove, reprioritize

issue_numberintegerRequired

The number of the parent issue

sub_issue_idintegerRequired

The ID of the sub-issue

replace_parentboolean

Replace the sub-issue's current parent issue

after_idinteger

The ID of the sub-issue to be prioritized after

before_idinteger

The ID of the sub-issue to be prioritized before

Methods

writesub_issue_write.add

Add a sub-issue to a parent issue.

Requiresissues:write

Repository: Declared targets.

Indirect target: The opaque child and ordering IDs may refer to another repository in the GitHub installation.

No additional required input.

writesub_issue_write.remove

Remove a sub-issue from a parent issue.

Requiresissues:write

Repository: Declared targets.

Indirect target: The opaque child and ordering IDs may refer to another repository in the GitHub installation.

No additional required input.

writesub_issue_write.reprioritize

Reprioritize a sub-issue under its parent issue.

Requiresissues:write

Repository: Declared targets.

Indirect target: The opaque child and ordering IDs may refer to another repository in the GitHub installation.

No additional required input.

Returns

This tool returns the provider response without declared fields.

- key: sub_issue_write
  tool: sub_issue_write.add
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    issue_number: 1
    sub_issue_id: 1

Pull requests

readpull_request_read

Get information on a specific pull request in a GitHub repository.

Requirespull_requests:read, contents:read, statuses:read, checks:read

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

methodstringRequired

Action to specify what pull request data needs to be retrieved from GitHub

Possible values: get, get_diff, get_status, get_files, get_commits, get_review_comments, get_review_threads, get_reviews, get_comments, get_check_runs

pull_numberintegerRequired

Pull request number

refstringConditional

Git reference to inspect. Required for get_status and get_check_runs

cursorstring

Cursor for review comment pagination

pageinteger

Page number for pagination

Minimum 1.

per_pageinteger

Results per page for pagination

Minimum 1. Maximum 100.

Methods

readpull_request_read.get

Get information about a specific pull request.

Requirespull_requests:read

Repository: Declared targets.

No additional required input.

readpull_request_read.get_diff

Get the diff for a specific pull request.

Requirescontents:read

Repository: Declared targets.

No additional required input.

readpull_request_read.get_status

Get status information for a specific pull request.

Requiresstatuses:read

Repository: Declared targets.

Required input: ref

readpull_request_read.get_files

Get files changed in a specific pull request.

Requirespull_requests:read

Repository: Declared targets.

No additional required input.

readpull_request_read.get_commits

Get commits in a specific pull request.

Requirespull_requests:read

Repository: Declared targets.

No additional required input.

readpull_request_read.get_review_comments

Get review comments for a specific pull request.

Requirespull_requests:read

Repository: Declared targets.

No additional required input.

readpull_request_read.get_review_threads

Get review threads, their resolution and outdated state, and comments for a specific pull request.

Requirespull_requests:read

Repository: Declared targets.

No additional required input.

readpull_request_read.get_reviews

Get reviews for a specific pull request.

Requirespull_requests:read

Repository: Declared targets.

No additional required input.

readpull_request_read.get_comments

Get conversation comments for a specific pull request.

Requirespull_requests:readOrissues:read

Repository: Declared targets.

No additional required input.

readpull_request_read.get_check_runs

Get check runs for the head commit of a pull request.

Requireschecks:read

Repository: Declared targets.

Required input: ref

Returns

This tool returns the provider response without declared fields.

- key: pull_request_read
  tool: pull_request_read.get
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    pull_number: 1

readlist_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.

Requirespull_requests:read

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

statestring

Filter by state

Possible values: open, closed, all

headstring

Filter by head user/org and branch

basestring

Filter by base branch

sortstring

Sort by

Possible values: created, updated, popularity, long-running

directionstring

Sort direction

Possible values: asc, desc

pageinteger

Page number for pagination

Minimum 1.

per_pageinteger

Results per page for pagination

Minimum 1. Maximum 100.

Returns

pull_requestsarray of objectRequired

- key: list_pull_requests
  tool: list_pull_requests
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
  outputs:
    pull_requests: ${{ result.pull_requests }}

readsearch_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.

Requirespull_requests:read

Repository: 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.

Parameters

querystringRequired

Search query using GitHub pull request search syntax. Do not include unquoted repo:, org:, or user: qualifiers; quoted occurrences are treated as literal text.

ownerstringConditional

Optional repository owner. Provide together with repo, or omit both for a connection-scoped search.

repostringConditional

Optional repository name. Provide together with owner, or omit both for a connection-scoped search.

sortstring

Sort field

Possible values: comments, reactions, reactions-+1, reactions--1, reactions-smile, reactions-thinking_face, reactions-heart, reactions-tada, interactions, created, updated

orderstring

Sort order

Possible values: asc, desc

pageinteger

Page number for pagination

Minimum 1.

per_pageinteger

Results per page for pagination

Minimum 1. Maximum 100.

Returns

pull_requestsarray of objectRequired

- key: search_pull_requests
  tool: search_pull_requests
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    query: <query>
  outputs:
    pull_requests: ${{ result.pull_requests }}

writecreate_pull_request

Create a new pull request in a GitHub repository. Reviewers, labels, assignees, and the milestone are applied after the pull request is created. When one of them fails, the call still succeeds and the result lists the failure under warnings, because the pull request already exists and a retry would open a duplicate. On failure, the error reason is one of: pull-request-exists, no-commits-between, branch-not-found, permission-denied, unprocessable.

Requirespull_requests:write

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

titlestringRequired

PR title

bodystring

PR description

headstringRequired

Branch containing changes

basestringRequired

Branch to merge into

draftboolean

Create as draft PR

maintainer_can_modifyboolean

Allow maintainer edits

reviewersarray of string

labelsarray of string

assigneesarray of string

milestoneinteger

Number of the milestone to set

Minimum 1.

Returns

pull_requestobjectRequired

Created GitHub pull request

warningsarray of string

- key: create_pull_request
  tool: create_pull_request
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    title: <title>
    head: <head>
    base: <base>
  outputs:
    pull_request: ${{ result.pull_request }}

writeupdate_pull_request

Update an existing pull request in a GitHub repository. add_labels and add_assignees add to what the pull request already has and remove nothing. milestone sets the milestone. draft true converts an open pull request to a draft, and draft false marks it ready for review. These and reviewers are applied after the update itself. When one of them fails, the call still succeeds and the result lists the failure under warnings. On failure, the error reason is one of: permission-denied, unprocessable.

Requirespull_requests:write

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

pull_numberintegerRequired

Pull request number to update

titlestring

New title

bodystring

New description

statestring

New state

Possible values: open, closed

basestring

New base branch name

maintainer_can_modifyboolean

Allow maintainer edits

reviewersarray of string

add_labelsarray of string

add_assigneesarray of string

milestoneinteger

Number of the milestone to set

Minimum 1.

draftboolean

Convert to a draft (true) or mark ready for review (false)

Returns

pull_requestobjectRequired

Updated GitHub pull request

warningsarray of string

- key: update_pull_request
  tool: update_pull_request
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    pull_number: 1
  outputs:
    pull_request: ${{ result.pull_request }}

writeadd_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.

Requirespull_requests:write

Repository: Declared targets.

Parameters

At least one of these input combinations is required: pull_number and body; reaction.

ownerstringRequired

Repository owner

repostringRequired

Repository name

pull_numberintegerConditional

Pull request number. Required when body is provided

comment_idintegerRequired

The numeric ID of the pull request review comment to reply or react to

bodystringConditional

The text of the reply

reactionstringConditional

Emoji reaction to add

Possible values: +1, -1, laugh, confused, heart, hooray, rocket, eyes

Returns

This tool returns the provider response without declared fields.

- key: add_reply_to_pull_request_comment
  tool: add_reply_to_pull_request_comment
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    pull_number: 1
    comment_id: 1
    body: <body>

writemerge_pull_request

Merge a pull request in a GitHub repository.

Requirespull_requests:write, contents:writeSensitive

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

pull_numberintegerRequired

Pull request number

commit_titlestring

Title for merge commit

commit_messagestring

Extra detail for merge commit

merge_methodstring

Merge method

Possible values: merge, squash, rebase

Returns

mergeobjectRequired

Merge result

- key: merge_pull_request
  tool: merge_pull_request
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    pull_number: 1
  outputs:
    merge: ${{ result.merge }}

writeupdate_pull_request_branch

Update the branch of a pull request with the latest changes from the base branch.

Requirespull_requests:write, contents:write

Repository: Declared targets.

Indirect target: GitHub can also update the pull request head branch, which may belong to another repository.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

pull_numberintegerRequired

Pull request number

expected_head_shastring

The expected SHA of the pull request's HEAD ref

Returns

This tool returns the provider response without declared fields.

- key: update_pull_request_branch
  tool: update_pull_request_branch
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    pull_number: 1

writepull_request_auto_merge

Enable or disable auto-merge on a pull request. enable makes GitHub merge the pull request once its required reviews and checks pass. When nothing blocks the merge, GitHub does not accept auto-merge, so enable merges the pull request right away: pull_request.merged is then true and auto_merge is null. enable also succeeds on a pull request that is already merged, so it is safe to retry. The repository must allow auto-merge. disable cancels a pending auto-merge and succeeds when none is enabled.

Requirespull_requests:write, contents:writeSensitive

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

methodstringRequired

The auto-merge operation to perform

Possible values: enable, disable

pull_numberintegerRequired

Pull request number

merge_methodstring

Merge method (default merge). Only used by enable

Possible values: merge, squash, rebase

commit_titlestring

Title for the merge commit. Only used by enable

commit_messagestring

Extra detail for the merge commit. Only used by enable

Methods

writepull_request_auto_merge.enable

Merge a pull request once its requirements are met, or right away when nothing blocks it.

Requirespull_requests:write, contents:writeSensitive

Repository: Declared targets.

No additional required input.

writepull_request_auto_merge.disable

Cancel auto-merge on a pull request.

Requirespull_requests:write

Repository: Declared targets.

No additional required input.

Returns

pull_requestobjectRequired

Show 5 attributes

numberintegerRequired

Pull request number

urlstringRequired

Pull request URL

statestringRequired

Pull request state

Possible values: open, closed, merged

mergedbooleanRequired

Whether the pull request is merged

merge_commit_oidstring | nullRequired

The oid of the merge commit, or null when not merged

auto_mergeobject | nullRequired

The pending auto-merge, or null when none is enabled

Show 2 attributes

merge_methodstringRequired

Merge method GitHub will use

Possible values: merge, squash, rebase

enabled_atstring | nullRequired

When auto-merge was enabled

- key: pull_request_auto_merge
  tool: pull_request_auto_merge.enable
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    pull_number: 1
  outputs:
    pull_request: ${{ result.pull_request }}

writepull_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.

Requirespull_requests:write

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

methodstringRequired

The write operation to perform on pull request review

Possible values: create, submit_pending, delete_pending

pull_numberintegerRequired

Pull request number

bodystring

Review summary text. Required by submit_pending unless event is APPROVE; not accepted by delete_pending

eventstring

Review action. Required by submit_pending; not accepted by create or delete_pending

Possible values: APPROVE, REQUEST_CHANGES, COMMENT

commit_idstring

SHA of the commit to review. Only accepted by create

Methods

writepull_request_review_write.create

Create a pending pull request review.

Requirespull_requests:write

Repository: Declared targets.

No additional required input.

writepull_request_review_write.submit_pending

Submit the latest pending pull request review.

Requirespull_requests:write

Repository: Declared targets.

No additional required input.

writepull_request_review_write.delete_pending

Delete the latest pending pull request review.

Requirespull_requests:write

Repository: Declared targets.

No additional required input.

Returns

This tool returns the provider response without declared fields.

- key: pull_request_review_write
  tool: pull_request_review_write.create
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    pull_number: 1

writepull_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.

Requirespull_requests:write

Repository: Integration connection.

Indirect target: The review thread node may belong to any repository reachable by the GitHub installation.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

methodstringRequired

The write operation to perform on a pull request review thread

Possible values: resolve

thread_idstringRequired

The node ID of the review thread

Methods

writepull_request_review_thread_write.resolve

Resolve a pull request review thread.

Requirespull_requests:write

Repository: Integration connection.

Indirect target: The review thread node may belong to any repository reachable by the GitHub installation.

No additional required input.

Returns

This tool returns the provider response without declared fields.

- key: pull_request_review_thread_write
  tool: pull_request_review_thread_write.resolve
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    thread_id: <thread_id>

writeadd_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.

Requirespull_requests:write

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

pull_numberintegerRequired

Pull request number

pathstringRequired

The relative path to the file that necessitates a comment

bodystringRequired

The text of the review comment

subject_typestring

The level at which the comment is targeted. LINE (default) requires line and side; FILE accepts no position fields

Possible values: LINE, FILE

lineinteger

The line of the blob in the pull request diff. Required for LINE

sidestring

The side of the diff to comment on. Required for LINE

Possible values: LEFT, RIGHT

start_lineinteger

The first line of a multi-line comment range. Must be lower than line and paired with start_side

start_sidestring

The starting side of a multi-line comment range. Paired with start_line

Possible values: LEFT, RIGHT

Returns

This tool returns the provider response without declared fields.

- key: add_comment_to_pending_review
  tool: add_comment_to_pending_review
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    pull_number: 1
    path: <path>
    body: <body>

Checks

writecheck_run_write

Create or update a check run for a commit in a GitHub repository.

Requireschecks:write

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

methodstringRequired

The check-run operation to perform

Possible values: create, update

check_run_idintegerConditional

The positive numeric ID of the check run to update

Minimum 1.

namestringConditional

Stable display name for the check

head_shastringConditional

Full, non-zero 40- or 64-character hexadecimal commit object ID

details_urlstring

Absolute HTTP or HTTPS link with more details

external_idstring

Caller-owned correlation key

statusstring

Check-run lifecycle status

Possible values: queued, in_progress, completed

started_atstring

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

conclusionstring

Final check-run conclusion

Possible values: action_required, cancelled, failure, neutral, success, skipped, timed_out

completed_atstring

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

outputobject

Show 3 attributes

titlestringRequired

Check output title

summarystringRequired

Check output summary in GitHub Markdown

textstring

Optional check output text in GitHub Markdown

Methods

writecheck_run_write.create

Create a check run for a commit in a GitHub repository.

Requireschecks:write

Repository: Declared targets.

Required input: name, head_sha

writecheck_run_write.update

Update an existing check run in a GitHub repository.

Requireschecks:write

Repository: Declared targets.

Required input: check_run_id

Returns

check_runobjectRequired

Show 10 attributes

idintegerRequired

Positive numeric check-run ID

Minimum 1.

namestringRequired

Check-run display name

head_shastringRequired

Non-zero 40- or 64-character hexadecimal commit object ID

external_idstring | nullRequired

Caller-owned correlation key

details_urlstring | nullRequired

Absolute HTTP or HTTPS details link

html_urlstringRequired

GitHub check-run URL

statusstringRequired

GitHub check-run lifecycle status

Possible values: queued, in_progress, completed, waiting, requested, pending

conclusionstring | nullRequired

GitHub check-run conclusion

Possible values: action_required, cancelled, failure, neutral, success, skipped, timed_out, stale, null

started_atstring | nullRequired

RFC 3339 start timestamp; leap seconds are accepted only when the normalized UTC instant is 23:59:60 on June 30 or December 31

completed_atstring | nullRequired

RFC 3339 completion timestamp; leap seconds are accepted only when the normalized UTC instant is 23:59:60 on June 30 or December 31

- key: check_run_write
  tool: check_run_write.create
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    name: <name>
    head_sha: <head_sha>
  outputs:
    check_run: ${{ result.check_run }}

Repository

writecreate_commit

Create a commit on a branch of a GitHub repository from a list of tree entries, with file modes, symbolic links, and submodules. The commit is signed by GitHub on behalf of the Shipfox bot (shipfox-ai[bot]) and shows the Verified badge. Entries are applied on top of the tree of parent_oid, which becomes the commit's only parent and must be a commit GitHub already has. Each entry names a path and exactly one of: contents (inline text), oid (a blob from create_blob, an existing blob, or a submodule commit), or delete. A rename is a delete of the old path plus an entry for the new path. A symbolic link uses mode 120000 with the link target as contents. The branch is created when it does not exist. Otherwise it must fast-forward to the new commit: if it moved, the commit is rejected with a stale-head error and the call should be retried from the new head. With force, the branch is reset to the new commit whatever it pointed at. Set expected_head_oid to the head you saw to guard either move: the call fails with a stale-head error when the branch points elsewhere or does not exist. GitHub offers no atomic compare for a ref update, so a push that lands between that check and the update is not detected, and a forced move overwrites it. Branch protection rules are the only barrier to writing the default branch. On failure, the error reason is one of: stale-head, protected-branch, permission-denied, unprocessable.

Requirescontents:write

Repository: Declared targets.

Parameters

repositorystringRequired

Repository in owner/name format. Must be a repository the connection can access.

branchstringRequired

The name of the branch to move, without any refs/ prefix

parent_oidstringRequired

The commit oid (40 or 64 hexadecimal characters) the new commit is built on

messagestringRequired

Commit message. The first line is the headline.

entriesarray of objectRequired

Show 5 attributes

pathstringRequired

Repository-relative file path

modestring

Git file mode: 100644 file (default), 100755 executable, 120000 symbolic link, 160000 submodule

Possible values: 100644, 100755, 120000, 160000

contentsstring

Inline text contents, or the target of a symbolic link

oidstring

The oid of a blob, or of the commit a submodule points at

deleteboolean

Remove the path from the tree

expected_head_oidstring

The commit oid the branch is expected to point at before it moves. Checked just before the update.

forceboolean

Reset the branch to the new commit instead of requiring a fast-forward (default false)

Returns

commitobjectRequired

Show 3 attributes

oidstringRequired

The oid of the created commit

urlstringRequired

The URL of the created commit

verifiedbooleanRequired

Whether GitHub signed the commit

branchstringRequired

The branch that now points at the commit

- key: create_commit
  tool: create_commit
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    repository: <repository>
    branch: <branch>
    parent_oid: <parent_oid>
    message: <message>
    entries:
      -       path: <path>
        mode: 100644
        contents: <contents>
        oid: <oid>
        delete: true
  outputs:
    commit: ${{ result.commit }}

writecreate_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. On failure, the error reason is one of: branch-exists, branch-not-found, protected-branch, permission-denied, unprocessable.

Requirescontents:write

Repository: Declared targets.

Parameters

repositorystringRequired

The repository in owner/name form

branchstringRequired

The name of the branch to create, without any refs/ prefix

fromstringRequired

The 40- or 64-character commit oid or existing branch name the new branch points at

Returns

branchstringRequired

The name of the created branch

oidstringRequired

The commit oid the created branch points at

urlstringRequired

The API URL of the created git ref

- key: create_branch
  tool: create_branch
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    repository: <repository>
    branch: <branch>
    from: <from>
  outputs:
    branch: ${{ result.branch }}

writecreate_blob

Upload the contents of one file to a GitHub repository as a Git blob and return its oid. The blob is not part of any commit until create_commit references it. Use it for binary files and for files too large to send inline; text is sent as utf8 and binary contents as base64. One file may hold up to 40 MiB.

Requirescontents:write

Repository: Declared targets.

Parameters

repositorystringRequired

Repository in owner/name format. Must be a repository the connection can access.

contentsstringRequired

File contents

encodingstring

Contents encoding (default utf8)

Possible values: utf8, base64

Returns

oidstringRequired

The oid of the created blob

- key: create_blob
  tool: create_blob
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    repository: <repository>
    contents: <contents>
  outputs:
    oid: ${{ result.oid }}

writedelete_branch

Delete a branch of a GitHub repository. A branch that is already gone is a success with existed false, so the call is safe to retry. The repository's default branch is refused. Set expected_head_oid to delete the branch only while it points at that commit: the call fails with a stale-head error when it points elsewhere. GitHub offers no atomic compare for a ref deletion, so a push that lands between that check and the deletion is lost. Deleting the head branch of an open pull request closes the pull request. On failure, the error reason is one of: stale-head, protected-branch, permission-denied, unprocessable.

Requirescontents:write

Repository: Declared targets.

Parameters

repositorystringRequired

Repository in owner/name format. Must be a repository the connection can access.

branchstringRequired

The name of the branch to delete, without any refs/ prefix

expected_head_oidstring

The commit oid the branch is expected to point at. Checked just before the deletion.

Returns

branchstringRequired

The name of the branch

existedbooleanRequired

Whether the branch existed and was deleted by this call

oidstring | nullRequired

The commit oid the branch pointed at, or null when it was gone

- key: delete_branch
  tool: delete_branch
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    repository: <repository>
    branch: <branch>
  outputs:
    branch: ${{ result.branch }}

readget_repository

Get a GitHub repository: its full name, its default branch, and bot_login, the GitHub login of the Shipfox bot on this connection. Commits made by create_commit carry that login as their author, so compare it with the author login of a commit to tell bot commits from others.

Requirescontents:read

Repository: Declared targets.

Parameters

repositorystringRequired

Repository in owner/name format. Must be a repository the connection can access.

Returns

full_namestringRequired

Repository in owner/name format

default_branchstringRequired

The name of the default branch

privatebooleanRequired

Whether the repository is private

urlstring

The URL of the repository

bot_loginstringRequired

The GitHub login of the Shipfox bot, for example shipfox-ai[bot]

- key: get_repository
  tool: get_repository
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    repository: <repository>
  outputs:
    full_name: ${{ result.full_name }}

readget_branch

Get the head of a branch in a GitHub repository. A branch that does not exist is a success with exists false, so it can be told apart from a failed call.

Requirescontents:read

Repository: Declared targets.

Parameters

repositorystringRequired

Repository in owner/name format. Must be a repository the connection can access.

branchstringRequired

The name of the branch, without any refs/ prefix

Returns

branchstringRequired

The name of the branch

existsbooleanRequired

Whether the branch exists

oidstring | nullRequired

The commit oid the branch points at, or null when missing

protectedbooleanRequired

Whether branch protection applies to the branch

- key: get_branch
  tool: get_branch
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    repository: <repository>
    branch: <branch>
  outputs:
    branch: ${{ result.branch }}

readget_commit

Get one commit of a GitHub repository by oid, branch, or tag: its parents, message, author, committer, and whether GitHub verified its signature. The author and committer login is the GitHub account matching the commit email, or null when no account matches.

Requirescontents:read

Repository: Declared targets.

Parameters

repositorystringRequired

Repository in owner/name format. Must be a repository the connection can access.

refstringRequired

A commit oid, branch name, or tag name

Returns

commitobjectRequired

Show 7 attributes

oidstringRequired

The oid of the commit

urlstring

The URL of the commit

messagestringRequired

The commit message

parentsarray of stringRequired

authorobjectRequired

Show 4 attributes

loginstring | nullRequired

GitHub login of the matching account, or null

namestring | nullRequired

Name recorded in the commit

emailstring | nullRequired

Email recorded in the commit

datestring | nullRequired

RFC 3339 timestamp recorded in the commit

committerobjectRequired

Show 4 attributes

loginstring | nullRequired

GitHub login of the matching account, or null

namestring | nullRequired

Name recorded in the commit

emailstring | nullRequired

Email recorded in the commit

datestring | nullRequired

RFC 3339 timestamp recorded in the commit

verifiedbooleanRequired

Whether GitHub verified the commit signature

- key: get_commit
  tool: get_commit
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    repository: <repository>
    ref: <ref>
  outputs:
    commit: ${{ result.commit }}

readcompare_commits

List the commits a head has on top of a base in a GitHub repository, oldest first, with how far the head is ahead and behind and the merge base. Base and head are commit oids, branch names, or tag names. A page holds up to 100 commits: when truncated is true, call again with the next page.

Requirescontents:read

Repository: Declared targets.

Parameters

repositorystringRequired

Repository in owner/name format. Must be a repository the connection can access.

basestringRequired

The commit oid, branch, or tag to compare from

headstringRequired

The commit oid, branch, or tag to compare to

pageinteger

Page of commits to return (default 1)

Minimum 1.

Returns

statusstringRequired

How the head relates to the base

Possible values: ahead, behind, identical, diverged

ahead_byintegerRequired

Commits the head has that the base lacks

behind_byintegerRequired

Commits the base has that the head lacks

merge_base_oidstring | nullRequired

The oid of the merge base commit

total_commitsintegerRequired

Commits between the base and the head, on every page

commitsarray of objectRequired

Show 7 attributes

oidstringRequired

The oid of the commit

urlstring

The URL of the commit

messagestringRequired

The commit message

parentsarray of stringRequired

authorobjectRequired

Show 4 attributes

loginstring | nullRequired

GitHub login of the matching account, or null

namestring | nullRequired

Name recorded in the commit

emailstring | nullRequired

Email recorded in the commit

datestring | nullRequired

RFC 3339 timestamp recorded in the commit

committerobjectRequired

Show 4 attributes

loginstring | nullRequired

GitHub login of the matching account, or null

namestring | nullRequired

Name recorded in the commit

emailstring | nullRequired

Email recorded in the commit

datestring | nullRequired

RFC 3339 timestamp recorded in the commit

verifiedbooleanRequired

Whether GitHub verified the commit signature

truncatedbooleanRequired

Whether later pages hold more commits

- key: compare_commits
  tool: compare_commits
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    repository: <repository>
    base: <base>
    head: <head>
  outputs:
    status: ${{ result.status }}

Actions

readactions_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.

Requiresactions:read

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

methodstringRequired

The action to perform

Possible values: list_workflows, list_workflow_runs, list_workflow_jobs, list_workflow_run_artifacts

resource_idstring

The unique identifier of the resource

workflow_runs_filterobject

Filters for workflow runs

workflow_jobs_filterobject

Filters for workflow jobs

pageinteger

Page number for pagination

Minimum 1.

per_pageinteger

Results per page for pagination

Minimum 1. Maximum 100.

Methods

readactions_list.list_workflows

List workflows in a repository.

Requiresactions:read

Repository: Declared targets.

No additional required input.

readactions_list.list_workflow_runs

List workflow runs in a repository or for a workflow.

Requiresactions:read

Repository: Declared targets.

No additional required input.

readactions_list.list_workflow_jobs

List jobs for a workflow run.

Requiresactions:read

Repository: Declared targets.

No additional required input.

readactions_list.list_workflow_run_artifacts

List artifacts for a workflow run.

Requiresactions:read

Repository: Declared targets.

No additional required input.

Returns

This tool returns the provider response without declared fields.

- key: actions_list
  tool: actions_list.list_workflows
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>

readactions_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.

Requiresactions:read

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

methodstringRequired

The method to execute

Possible values: get_workflow, get_workflow_run, get_workflow_job, download_workflow_run_artifact, get_workflow_run_usage, get_workflow_run_logs_url

resource_idstringRequired

The unique identifier of the resource

Methods

readactions_get.get_workflow

Get details for a workflow.

Requiresactions:read

Repository: Declared targets.

No additional required input.

readactions_get.get_workflow_run

Get details for a workflow run.

Requiresactions:read

Repository: Declared targets.

No additional required input.

readactions_get.get_workflow_job

Get details for a workflow job.

Requiresactions:read

Repository: Declared targets.

No additional required input.

readactions_get.download_workflow_run_artifact

Download a workflow run artifact.

Requiresactions:read

Repository: Declared targets.

No additional required input.

readactions_get.get_workflow_run_usage

Get workflow run usage.

Requiresactions:read

Repository: Declared targets.

No additional required input.

readactions_get.get_workflow_run_logs_url

Get a workflow run logs download URL.

Requiresactions:read

Repository: Declared targets.

No additional required input.

Returns

This tool returns the provider response without declared fields.

- key: actions_get
  tool: actions_get.get_workflow
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    resource_id: <resource_id>

writeactions_run_trigger

Trigger GitHub Actions workflow operations, including running, re-running, cancelling workflow runs, and deleting workflow run logs.

Requiresactions:writeSensitive

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

methodstringRequired

The method to execute

Possible values: run_workflow, rerun_workflow_run, rerun_failed_jobs, cancel_workflow_run, delete_workflow_run_logs

workflow_idstringConditional

The workflow ID or workflow file name. Required for run_workflow

refstringConditional

The git reference for the workflow. Required for run_workflow

inputsobject

Inputs the workflow accepts. Only used for run_workflow

run_idintegerConditional

The ID of the workflow run. Required for all methods except run_workflow

Methods

writeactions_run_trigger.run_workflow

Trigger a workflow_dispatch run. Returns the workflow_run_id, run_url, and html_url of the run it started.

Requiresactions:writeSensitive

Repository: Declared targets.

Required input: workflow_id, ref

writeactions_run_trigger.rerun_workflow_run

Rerun a workflow run.

Requiresactions:write

Repository: Declared targets.

Required input: run_id

writeactions_run_trigger.rerun_failed_jobs

Rerun failed jobs in a workflow run.

Requiresactions:write

Repository: Declared targets.

Required input: run_id

writeactions_run_trigger.cancel_workflow_run

Cancel a workflow run.

Requiresactions:write

Repository: Declared targets.

Required input: run_id

writeactions_run_trigger.delete_workflow_run_logs

Delete logs for a workflow run.

Requiresactions:writeSensitive

Repository: Declared targets.

Required input: run_id

Returns

This tool returns the provider response without declared fields.

- key: actions_run_trigger
  tool: actions_run_trigger.run_workflow
  connection: github_acme # Replace with the slug of your integration connection.
  with:
    owner: <owner>
    repo: <repo>
    workflow_id: <workflow_id>
    ref: <ref>

readget_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.

Requiresactions:read

Repository: Declared targets.

Parameters

ownerstringRequired

Repository owner

repostringRequired

Repository name

job_idnumber

The unique identifier of the workflow job. Required when getting logs for a single job.

run_idnumber

The unique identifier of the workflow run. Required when failed_only is true to get logs for all failed jobs in the run.

failed_onlyboolean

When true, gets logs for all failed jobs in the workflow run specified by run_id. Requires run_id to be provided.

return_contentboolean

Returns actual log content instead of URLs

tail_linesnumber

Number of lines to return from the end of the log

Default 500.

Returns

This tool returns the provider response without declared fields.

Was this page helpful?

Edit this page on GitHub

Choose GitHub toolsCopy Anchor Link

Tool catalogCopy Anchor Link

Issues

Parameters

Methods

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Methods

Returns

Parameters

Methods

Returns

Pull requests

Parameters

Methods

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Methods

Returns

Parameters

Methods

Returns

Parameters

Methods

Returns

Parameters

Returns

Checks

Parameters

Methods

Returns

Repository

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Actions

Parameters

Methods

Returns

Parameters

Methods

Returns

Choose GitHub tools

Tool catalog