Skip to main content

GitHub

A connector to the GitHub platform for repository, issue, and pull request management.

📝 Note: This connector gives agents GitHub API tools. To use git and gh in a chat sandbox, see Work with GitHub from chat.

What you can ask​

  • Triage open issues across our org. Assign me to anything labeled priority:high and post a daily digest in Slack.
  • Open a pull request from feature/billing-refactor into main with the changelog as the description and request review from the platform team.
  • Find every open PR that hasn't had a review in three days and DM the assigned reviewer.
  • Summarize what landed in our production repos this week. Group by author.

Set up​

GitHub connects with credentials from your GitHub account. Have these values ready:

  • Access token
  1. Go to Organization > Connectors and find GitHub.
  2. Click Enable and choose which tools to allow.
  3. Each member enters their own values the first time they use it.

To use one account for the whole organization, turn on Share one connection with everyone. Every member's agents then act as that account, with exactly the access it has.

Tools​

GitHub offers 154 tools. Admins choose which ones agents can use. See Tool permission groups.

Read (83)​

View and search information without changing it.

ToolWhat it does
check_followingCheck whether one user follows another user.
check_if_mergedCheck if a pull request has been merged and get merge details if applicable
check_starredCheck if the authenticated user has starred a repository
check_team_membershipCheck a user's membership in a team, including its state (active vs pending invitation) and role
compare_commitsCompare two commits, branches, or tags. basehead uses 'BASE...HEAD' syntax, e.g. 'main...my-feature' or 'v1.0.0...v2.0.0' (cross-fork: 'owner:branch').
get_artifact_download_urlGet a short-lived download URL for a workflow run artifact's zip archive (the URL expires after about 1 minute).
get_authenticated_userGet the authenticated user's profile information including public and private details
get_blobRead a file's raw content by its blob SHA.
get_branch_protectionGet effective branch protection: classic branch protection, falling back to repository and organization rulesets. protection_source says which applies ('classic', 'ruleset', 'none'); protected=false only when neither does.
get_branchesGet repository branches with optional filtering by protection status.
get_check_run_annotationsGet a check run's annotations: the file, line range and message for each problem the check reported.
get_check_runsGet check runs for a specific commit or ref (Checks API).
get_check_suite_runsList the check runs inside one check suite.
get_check_suitesList the check suites for a commit or ref.
get_commitGet a single commit by SHA with detailed information including file changes, statistics, and parent commits.
get_commit_statusGet the combined status for a specific commit or ref (legacy statuses API).
get_commitsGet repository commits with filtering options by author, date range, file path, and branch/SHA
get_discussionGet a discussion by number including body, category, author, comment count, and answer info.
get_discussion_commentsGet a discussion's comments and their threaded replies, flattened with each reply after its parent (reply_to_node_id links them).
get_file_contentsGet file or directory contents from a repository.
get_followersGet a list of users who follow a specific user.
get_followingGet a list of users that a specific user follows.
get_gistGet a specific gist by ID including all file contents
get_issueGet a single issue by number from a specific repository.
get_issue_commentsGet comments for a specific issue.
get_issuesGet a list of issues from a repository with filtering by state, labels, assignee, creator, and more.
get_job_logsGet log content for a workflow job.
get_labelGet a single repository label by name.
get_latest_releaseGet the latest release for a repository.
get_notificationGet details for a specific notification thread by ID.
get_organizationGet detailed information about a GitHub organization by its name
get_organization_membersGet members of an organization with filtering options by role and 2FA status
get_organization_teamsGet teams in an organization.
get_pull_requestGet a single pull request by number from a specific repository.
get_pull_request_checksGet an overall CI status summary for a PR's head commit, including checks and legacy status
get_pull_request_commitsGet commits in a pull request showing the individual changes that make up the PR.
get_pull_request_diffGet the unified diff for a pull request as plain text.
get_pull_request_filesGet the files changed in a pull request with additions, deletions, and change counts.
get_pull_request_reviewsGet reviews for a pull request including approval status, comments, and reviewer information
get_pull_requestsGet a list of pull requests from a repository with filtering options by state, head/base branches, and sorting.
get_release_by_tagGet a release by its tag name (e.g. 'v1.0.0').
get_releasesGet repository releases including tags, assets, and release notes.
get_repositoriesList ONLY the authenticated user's repositories (owned, collaborator, or org member).
get_repositoryGet a single repository by owner and name.
get_repository_archive_urlGet a short-lived download URL for a repository archive (zip or tar) at a branch, tag or commit.
get_repository_treeGet the file tree for a repository.
get_team_membersGet members of a specific team with filtering by role (member or maintainer)
get_userGet detailed information about any GitHub user by their username
get_user_eventsGet public events for a user showing their recent GitHub activity.
get_user_membershipsGet the authenticated user's organization memberships including private memberships.
get_user_organizationsGet organizations that a user is publicly a member of
get_user_starred_reposGet repositories starred by a user, sorted by star time (created) or last push (updated), with pagination
get_workflowGet a specific workflow by ID or filename (e.g. 'ci.yml').
get_workflow_runGet details for a specific workflow run including status, conclusion, and timing.
list_assigneesList users who can be assigned to issues in a repository.
list_deployment_statusesList the statuses recorded against one deployment, newest first.
list_deploymentsList a repository's deployments, optionally filtered by commit SHA, ref or environment.
list_discussion_categoriesList discussion categories in a repository.
list_discussionsList discussions in a repository with server-side filters: category (node ID or slug, use list_discussion_categories first), answered, state (OPEN/CLOSED), and sort by created/updated time.
list_environment_secretsList the names of secrets configured on a repository environment.
list_environmentsList the deployment environments configured on a repository.
list_gistsList gists for the authenticated user or a specific user.
list_issue_typesList an organization's issue types (e.g. Bug, Task). Use the returned 'name' values as the type in create_issue/update_issue. Only available for organization-owned repositories
list_labelsList labels for a repository with pagination
list_milestonesList a repository's milestones with state, sort, and pagination options.
list_notificationsList notifications for the authenticated user.
list_pull_request_review_threadsList review threads on a pull request with resolution status, file path, and comments.
list_repository_collaboratorsList collaborators for a repository.
list_sub_issuesList an issue's sub-issues with pagination.
list_tagsList tags for a repository with pagination
list_user_issuesList issues across ALL repositories accessible to the authenticated user (assigned/created/mentioned/subscribed), unlike get_issues which is scoped to one repository.
list_workflow_jobsList jobs for a workflow run.
list_workflow_run_artifactsList artifacts produced by a workflow run, optionally filtered by exact artifact name.
list_workflow_runsList workflow runs for a repository or specific workflow.
list_workflowsList all workflows in a repository's .github/workflows directory.
search_codeSearch code across GitHub repositories.
search_commitsSearch commits across GitHub repositories.
search_issuesSearch for issues across all accessible repositories using GitHub's search syntax.
search_orgsSearch for organizations on GitHub.
search_pull_requestsSearch pull requests across GitHub repositories.
search_repositoriesSearch GitHub repositories using search syntax.
search_usersSearch GitHub users and organizations.
validate_credentialValidate GitHub credentials.

Write (25)​

Create or send data.

ToolWhat it does
add_labels_to_issueAdd labels to an issue.
add_reply_to_pull_request_commentReply to an existing review comment on a pull request.
add_sub_issueAdd an existing issue as a sub-issue of a parent issue. sub_issue_id is the child issue's ID, NOT its number — get_issue returns it as 'id'.
add_team_membershipAdd a user to a team with specified role (member or maintainer).
create_branchCreate a new branch from an existing commit.
create_discussionCreate a discussion in a repository.
create_discussion_commentAdd a comment to a discussion by number.
create_gistCreate a new gist with one or more files.
create_issueCreate a new issue with title, body, labels, assignees, milestone, and type.
create_issue_commentCreate a new comment on an issue.
create_labelCreate a new label in a repository.
create_organization_repositoryCreate a new repository in an organization.
create_pull_requestCreate a pull request from head into base.
create_pull_request_commentCreate a review comment on a pull request for code review.
create_pull_request_reviewCreate a pull request review.
create_releaseCreate a release. tag_name is required: use an existing tag from list_tags, or a new tag name (created from target_commitish, default branch if omitted).
create_repositoryCreate a new repository.
create_teamCreate a team in an organization.
follow_userFollow a user as the authenticated user.
fork_repositoryFork a repository into the authenticated user's account or a specified organization.
request_reviewersRequest specific users or teams to review a pull request.
rerun_failed_jobsRe-run only the failed jobs of a workflow run (and their dependents), optionally with debug logging enabled.
rerun_workflowRe-run all jobs in a workflow run, optionally with debug logging enabled.
star_repositoryStar a repository for the authenticated user
trigger_workflowTrigger a workflow dispatch event to manually run a workflow (it must have a workflow_dispatch trigger).

Delete or overwrite (46)​

Remove or replace existing data.

ToolWhat it does
cancel_workflow_runCancel a workflow run that is queued or in progress.
close_issueClose an issue by setting its state to closed.
close_pull_requestClose a pull request without merging it.
convert_to_draftConvert a pull request to draft status, preventing it from being merged until marked ready for review (mark_ready_for_review)
create_or_update_fileCreate or update a single file in a repository.
delete_fileDelete a file from a repository.
delete_gistDelete a gist permanently.
delete_issue_commentDelete an issue comment.
delete_labelDelete a label from a repository.
delete_pending_reviewDelete a PENDING (unsubmitted) pull request review and its draft comments.
delete_releaseDelete a release by release_id (from get_releases or get_release_by_tag).
delete_repositoryDelete a repository permanently.
dismiss_notificationUnsubscribe from a notification thread so you no longer receive future notifications for it.
dismiss_pull_request_reviewDismiss a submitted pull request review with a required message explaining why.
lock_issueLock an issue to prevent new comments.
manage_notification_subscriptionMute or unmute a notification thread.
manage_repo_notification_subscriptionManage repository-level notification subscription.
mark_all_notifications_readMark all notifications as read.
mark_notification_doneMark a notification thread as done, removing it from the inbox.
mark_notification_readMark a notification thread as read.
mark_ready_for_reviewMark a draft pull request as ready for review, allowing it to be merged once approved.
merge_pull_requestMerge a pull request using the specified merge method (merge, squash, or rebase).
push_filesPush multiple files in a single commit using the Git Data API (atomic).
remove_all_labels_from_issueRemove all labels from an issue
remove_label_from_issueRemove a specific label from an issue
remove_review_requestRemove review requests from specific users or teams for a pull request
remove_sub_issueRemove a sub-issue from its parent issue. sub_issue_id is the child issue's ID, NOT its number — get_issue or list_sub_issues return it as 'id'.
remove_team_membershipRemove a user from a team.
reopen_issueReopen a closed issue by setting its state to open
reopen_pull_requestReopen a closed pull request.
resolve_review_threadResolve a pull request review thread, marking the conversation as addressed.
set_issue_labelsSet labels on an issue, replacing all existing labels with the new set
submit_pull_request_reviewSubmit a PENDING pull request review with APPROVE, REQUEST_CHANGES, or COMMENT.
unfollow_userUnfollow a user as the authenticated user.
unlock_issueUnlock an issue to allow new comments from all users
unresolve_review_threadReopen (unresolve) a resolved pull request review thread.
unstar_repositoryUnstar a repository for the authenticated user
update_discussion_commentUpdate the body of an existing discussion comment. comment_id is the comment node ID (e.g. 'DC_...') returned by get_discussion_comments or create_discussion_comment
update_gistUpdate a gist's description or file contents.
update_issueUpdate an issue's title, body, state, labels, assignees, milestone, or type. labels and assignees REPLACE the full existing set.
update_issue_commentUpdate an existing issue comment's content.
update_labelUpdate an existing repository label's name, color, or description.
update_pull_requestUpdate an existing pull request's title, body, state, base branch, and other properties
update_pull_request_branchUpdate the head branch of a pull request to include the latest changes from the base branch
update_releaseUpdate a release by release_id (from get_releases, get_release_by_tag, or create_release).
update_repositoryUpdate an existing repository's settings, description, visibility, and other properties
⌘J