@guildai-services/guildai~github package provides agents with access to the GitHub REST API through Guild’s GitHub App integration.
Authentication
- Type: GitHub App
- Token management: Generated on-demand and refreshed automatically
- Scoping: Limited to repositories where the Guild GitHub App is installed
Setup
1
Open Credentials
Go to Credentials in Guild.
2
Connect GitHub
Click GitHub and authorize the Guild app on your organization or repository.
3
Select repositories
Choose which repositories to grant access to.
Usage
import { gitHubTools } from "@guildai-services/guildai~github"
import { llmAgent } from "@guildai/agents-sdk"
export default llmAgent({
description: "An agent that manages GitHub issues",
tools: { ...gitHubTools },
})
Selecting specific tools
Agents perform better with fewer tools. Usepick() to include only what your agent needs. Tools are named with the github_ prefix — for example, pulls_get becomes github_pulls_get.
import { gitHubTools } from "@guildai-services/guildai~github"
import { llmAgent, pick } from "@guildai/agents-sdk"
export default llmAgent({
description: "An agent that reviews pull requests",
tools: {
...pick(gitHubTools, [
"github_pulls_list",
"github_pulls_get",
"github_pulls_list_reviews",
"github_pulls_create_review",
]),
},
})
Trimming responses
GitHub API responses can be large. UseguildServiceTool() with githubSchemasLite to strip unnecessary fields before the LLM sees them.
import {
githubSchemas as gh,
githubSchemasLite as ghlite,
gitHubEndpoints,
} from "@guildai-services/guildai~github"
import { guildServiceTool, llmAgent } from "@guildai/agents-sdk"
import { z } from "zod"
const github_issues_list_for_repo = guildServiceTool("github", {
description: gitHubEndpoints["issues_list_for_repo"].description,
inputSchema: gitHubEndpoints["issues_list_for_repo"].parameterSchema,
outputSchema: z
.array(gh.IssueSchema)
.transform((issues) => issues.map((x) => ghlite.IssueSchema.parse(x))),
})
export default llmAgent({
description: "An agent that triages GitHub issues",
tools: { github_issues_list_for_repo },
})
API endpoints
Gists
Gists
| Operation | Method | Path |
|---|---|---|
gists_list | GET | /gists |
gists_create | POST | /gists |
gists_list_public | GET | /gists/public |
gists_get | GET | /gists/{gist_id} |
gists_update | PATCH | /gists/{gist_id} |
gists_delete | DELETE | /gists/{gist_id} |
gists_list_comments | GET | /gists/{gist_id}/comments |
gists_create_comment | POST | /gists/{gist_id}/comments |
Organizations
Organizations
| Operation | Method | Path |
|---|---|---|
orgs_list_issue_types | GET | /orgs/{org}/issue-types |
orgs_create_issue_type | POST | /orgs/{org}/issue-types |
orgs_list_members | GET | /orgs/{org}/members |
repos_list_for_org | GET | /orgs/{org}/repos |
repos_create_in_org | POST | /orgs/{org}/repos |
Repositories
Repositories
| Operation | Method | Path |
|---|---|---|
repos_get | GET | /repos/{owner}/{repo} |
repos_update | PATCH | /repos/{owner}/{repo} |
repos_delete | DELETE | /repos/{owner}/{repo} |
repos_list_activities | GET | /repos/{owner}/{repo}/activity |
repos_list_contributors | GET | /repos/{owner}/{repo}/contributors |
repos_list_languages | GET | /repos/{owner}/{repo}/languages |
repos_get_readme | GET | /repos/{owner}/{repo}/readme |
repos_list_tags | GET | /repos/{owner}/{repo}/tags |
Branches
Branches
| Operation | Method | Path |
|---|---|---|
repos_list_branches | GET | /repos/{owner}/{repo}/branches |
repos_get_branch | GET | /repos/{owner}/{repo}/branches/{branch} |
Commits
Commits
| Operation | Method | Path |
|---|---|---|
repos_list_commits | GET | /repos/{owner}/{repo}/commits |
repos_get_commit | GET | /repos/{owner}/{repo}/commits/{ref} |
repos_compare_commits | GET | /repos/{owner}/{repo}/compare/{basehead} |
repos_list_commit_comments_for_repo | GET | /repos/{owner}/{repo}/comments |
repos_get_commit_comment | GET | /repos/{owner}/{repo}/comments/{comment_id} |
repos_update_commit_comment | PATCH | /repos/{owner}/{repo}/comments/{comment_id} |
repos_delete_commit_comment | DELETE | /repos/{owner}/{repo}/comments/{comment_id} |
repos_create_commit_comment | POST | /repos/{owner}/{repo}/commits/{commit_sha}/comments |
repos_get_combined_status_for_ref | GET | /repos/{owner}/{repo}/commits/{ref}/status |
repos_list_pull_requests_associated_with_commit | GET | /repos/{owner}/{repo}/commits/{commit_sha}/pulls |
Contents
Contents
| Operation | Method | Path |
|---|---|---|
repos_get_content | GET | /repos/{owner}/{repo}/contents/{path} |
repos_create_or_update_file_contents | PUT | /repos/{owner}/{repo}/contents/{path} |
repos_delete_file | DELETE | /repos/{owner}/{repo}/contents/{path} |
Issues
Issues
| Operation | Method | Path |
|---|---|---|
issues_list_for_repo | GET | /repos/{owner}/{repo}/issues |
issues_create | POST | /repos/{owner}/{repo}/issues |
issues_get | GET | /repos/{owner}/{repo}/issues/{issue_number} |
issues_update | PATCH | /repos/{owner}/{repo}/issues/{issue_number} |
issues_lock | PUT | /repos/{owner}/{repo}/issues/{issue_number}/lock |
issues_unlock | DELETE | /repos/{owner}/{repo}/issues/{issue_number}/lock |
issues_get_parent | GET | /repos/{owner}/{repo}/issues/{issue_number}/parent |
issues_list_sub_issues | GET | /repos/{owner}/{repo}/issues/{issue_number}/sub_issues |
issues_add_sub_issue | POST | /repos/{owner}/{repo}/issues/{issue_number}/sub_issues |
issues_remove_sub_issue | DELETE | /repos/{owner}/{repo}/issues/{issue_number}/sub_issues |
issues_list_assignees | GET | /repos/{owner}/{repo}/assignees |
issues_add_assignees | POST | /repos/{owner}/{repo}/issues/{issue_number}/assignees |
issues_remove_assignees | DELETE | /repos/{owner}/{repo}/issues/{issue_number}/assignees |
issues_list_comments_for_repo | GET | /repos/{owner}/{repo}/issues/comments |
issues_get_comment | GET | /repos/{owner}/{repo}/issues/comments/{comment_id} |
issues_update_comment | PATCH | /repos/{owner}/{repo}/issues/comments/{comment_id} |
issues_delete_comment | DELETE | /repos/{owner}/{repo}/issues/comments/{comment_id} |
issues_list_comments | GET | /repos/{owner}/{repo}/issues/{issue_number}/comments |
issues_create_comment | POST | /repos/{owner}/{repo}/issues/{issue_number}/comments |
issues_list_labels_for_repo | GET | /repos/{owner}/{repo}/labels |
issues_create_label | POST | /repos/{owner}/{repo}/labels |
issues_get_label | GET | /repos/{owner}/{repo}/labels/{name} |
issues_update_label | PATCH | /repos/{owner}/{repo}/labels/{name} |
issues_delete_label | DELETE | /repos/{owner}/{repo}/labels/{name} |
issues_add_labels | POST | /repos/{owner}/{repo}/issues/{issue_number}/labels |
issues_list_dependencies_blocked_by | GET | /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by |
issues_add_blocked_by_dependency | POST | /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by |
Pull requests
Pull requests
| Operation | Method | Path |
|---|---|---|
pulls_list | GET | /repos/{owner}/{repo}/pulls |
pulls_create | POST | /repos/{owner}/{repo}/pulls |
pulls_get | GET | /repos/{owner}/{repo}/pulls/{pull_number} |
pulls_update | PATCH | /repos/{owner}/{repo}/pulls/{pull_number} |
pulls_merge | PUT | /repos/{owner}/{repo}/pulls/{pull_number}/merge |
pulls_list_commits | GET | /repos/{owner}/{repo}/pulls/{pull_number}/commits |
pulls_list_files | GET | /repos/{owner}/{repo}/pulls/{pull_number}/files |
pulls_list_reviews | GET | /repos/{owner}/{repo}/pulls/{pull_number}/reviews |
pulls_create_review | POST | /repos/{owner}/{repo}/pulls/{pull_number}/reviews |
pulls_submit_review | POST | /repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/events |
pulls_list_review_comments | GET | /repos/{owner}/{repo}/pulls/{pull_number}/comments |
pulls_create_review_comment | POST | /repos/{owner}/{repo}/pulls/{pull_number}/comments |
pulls_list_requested_reviewers | GET | /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers |
pulls_request_reviewers | POST | /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers |
Check runs
Check runs
| Operation | Method | Path |
|---|---|---|
checks_create | POST | /repos/{owner}/{repo}/check-runs |
checks_get | GET | /repos/{owner}/{repo}/check-runs/{check_run_id} |
checks_update | PATCH | /repos/{owner}/{repo}/check-runs/{check_run_id} |
checks_list_annotations | GET | /repos/{owner}/{repo}/check-runs/{check_run_id}/annotations |
checks_list_for_ref | GET | /repos/{owner}/{repo}/commits/{ref}/check-runs |
Workflows & actions
Workflows & actions
| Operation | Method | Path |
|---|---|---|
actions_list_repo_workflows | GET | /repos/{owner}/{repo}/actions/workflows |
actions_get_workflow | GET | /repos/{owner}/{repo}/actions/workflows/{workflow_id} |
actions_list_workflow_runs_for_repo | GET | /repos/{owner}/{repo}/actions/runs |
actions_get_workflow_run | GET | /repos/{owner}/{repo}/actions/runs/{run_id} |
actions_list_workflow_runs | GET | /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs |
actions_list_jobs_for_workflow_run | GET | /repos/{owner}/{repo}/actions/runs/{run_id}/jobs |
actions_list_workflow_run_artifacts | GET | /repos/{owner}/{repo}/actions/runs/{run_id}/artifacts |
actions_download_job_logs_for_workflow_run | GET | /repos/{owner}/{repo}/actions/jobs/{job_id}/logs |
actions_re_run_workflow | POST | /repos/{owner}/{repo}/actions/runs/{run_id}/rerun |
actions_re_run_workflow_failed_jobs | POST | /repos/{owner}/{repo}/actions/runs/{run_id}/rerun-failed-jobs |
actions_force_cancel_workflow_run | POST | /repos/{owner}/{repo}/actions/runs/{run_id}/force-cancel |
Releases
Releases
| Operation | Method | Path |
|---|---|---|
repos_list_releases | GET | /repos/{owner}/{repo}/releases |
repos_create_release | POST | /repos/{owner}/{repo}/releases |
repos_get_release | GET | /repos/{owner}/{repo}/releases/{release_id} |
repos_update_release | PATCH | /repos/{owner}/{repo}/releases/{release_id} |
repos_delete_release | DELETE | /repos/{owner}/{repo}/releases/{release_id} |
repos_get_latest_release | GET | /repos/{owner}/{repo}/releases/latest |
repos_generate_release_notes | POST | /repos/{owner}/{repo}/releases/generate-notes |
Deployments
Deployments
| Operation | Method | Path |
|---|---|---|
repos_list_deployments | GET | /repos/{owner}/{repo}/deployments |
repos_create_deployment | POST | /repos/{owner}/{repo}/deployments |
repos_get_deployment | GET | /repos/{owner}/{repo}/deployments/{deployment_id} |
repos_delete_deployment | DELETE | /repos/{owner}/{repo}/deployments/{deployment_id} |
repos_create_deployment_status | POST | /repos/{owner}/{repo}/deployments/{deployment_id}/statuses |
Search
Search
| Operation | Method | Path |
|---|---|---|
search_code | GET | /search/code |
search_commits | GET | /search/commits |
search_issues_and_pull_requests | GET | /search/issues |
search_repos | GET | /search/repositories |
search_users | GET | /search/users |
Users
Users
| Operation | Method | Path |
|---|---|---|
users_get_by_username | GET | /users/{username} |
repos_list_for_user | GET | /users/{username}/repos |
Webhook events
GitHub uses an app-scoped webhook model — a single webhook receives all events and Guild routes them to matching triggers.| Event | Description |
|---|---|
issues | Issue opened, closed, edited, assigned, or labeled |
issue_comment | Comment created, edited, or deleted on an issue |
pull_request | PR opened, closed, merged, edited, or review requested |
pull_request_review | Review submitted, edited, or dismissed |
pull_request_review_comment | Review comment created, edited, or deleted |
push | Commits pushed to a branch |
release | Release published, created, edited, or deleted |
check_run | Check run created, completed, or rerequested |
workflow_job | Workflow job queued, in progress, or completed |
workflow_run | Workflow run requested, completed, or in progress |
Limitations
- Access is scoped to repositories where the GitHub App is installed
- Rate limits follow GitHub’s standard limits (5,000 requests/hour for authenticated apps)