GitHub Integration
Relevant source files
The following files were used as context for generating this wiki page:
The GitHub integration for Quix enables the AI-powered Slack agent to interact directly with GitHub. It allows users to manage repositories, issues, pull requests, and more using natural language commands within Slack. This integration is designed as a modular package within the Quix monorepo, providing a set of tools that the core LLM can leverage to perform actions on behalf of the user.
The integration is defined as a supported platform within the main application, requiring specific OAuth scopes for authentication and functionality. It is a key component for developers and teams who use GitHub for their code management and want to streamline their workflows without leaving Slack.
Sources: README.md, src/lib/constants.ts:36-47
Architecture and Configuration
The GitHub integration is a self-contained package located at agent-packages/packages/github. It exposes a set of tools that are dynamically loaded by the main application. The connection is established via OAuth and requires the repo, user, and read:org scopes to function correctly.
Sources: README.md:25-33, src/lib/constants.ts:27
Configuration
The integration is configured using the GitHubConfig interface. This configuration is passed to the createGitHubToolsExport function to initialize the GitHubService and the associated tools.
// agent-packages/packages/github/src/types/index.ts:10-14
export interface GitHubConfig extends BaseConfig {
token: string;
owner?: string;
repo?: string;
}
| Field | Type | Description |
|---|---|---|
token | string | The GitHub personal access token or OAuth token for authentication. |
owner | string | (Optional) The default repository owner (user or organization). If set, users don't need to specify it. |
repo | string | (Optional) The default repository name. If set, users don't need to specify it. |
Sources: agent-packages/packages/github/src/types/index.ts:10-14
Component Interaction Flow
The diagram below illustrates how a user request from Slack flows through the Quix system to the GitHub API via the integration package.
This diagram represents the general flow of information based on the project structure and tool definitions.
Sources: README.md:19-33, agent-packages/packages/github/src/tools.ts:70-75
Tool Factory
The primary entry point for the GitHub package is the createGitHubToolsExport function. This asynchronous function initializes the GitHubService with the provided configuration and constructs a ToolConfig object containing all available GitHub tools and agent-specific prompts.
This diagram shows the process of creating the GitHub tools and configuration.
Agent Prompts
To guide the LLM, the integration provides two specific prompts:
GITHUB_TOOL_SELECTION_PROMPT: This prompt helps the agent decide when to use the GitHub tools. It instructs the agent to consider these tools for actions related to searching repositories/issues, viewing PRs, checking commits, and managing issues.GITHUB_RESPONSE_GENERATION_PROMPT: This prompt provides guidelines on how to format the responses after a tool has been executed. It ensures that the output is clear, readable, and contains relevant information like repository names, issue numbers, and formatted code snippets.
Sources: agent-packages/packages/github/src/tools.ts:49-66
Data Schemas (Zod)
All tools use zod schemas for input validation. These schemas define the expected parameters, their types, and descriptions, which are also used by the LLM to understand how to call the functions.
A key helper function, createConditionalDefaultSchema, is used to make owner and repo parameters optional if they are already defined in the global GitHubConfig. This provides flexibility for the user.
Sources: agent-packages/packages/github/src/schema.ts:4-8
Example Schema: searchIssuesOrPullRequestsSchema
This schema is used for the search_issues_or_pull_requests tool. It combines a base schema with the conditional owner and repo fields.
This diagram shows the structure of the schema for searching issues and pull requests.
| Field | Type | Description |
|---|---|---|
type | enum('issue', 'pr') | Whether to search for issues or pull requests. |
keyword | string (optional) | Text to search for in titles and descriptions. |
reporter | string (optional) | GitHub username of the creator. |
assignee | string (optional) | GitHub username of the person assigned. |
status | enum('open', 'closed') (optional) | Filter by status. |
sort | enum('comments', 'reactions', 'created', 'updated') | Sort results by a specific metric. |
order | enum('asc', 'desc') (optional) | Sort order (ascending or descending). |
label | string (optional) | Filter by labels (comma-separated). |
page | number | Page number for pagination. |
repo | string | Repository name. (Required if not in config). |
owner | string | Repository owner. (Required if not in config). |
Sources: agent-packages/packages/github/src/schema.ts:10-58
Available Tools
The integration provides a comprehensive set of tools for interacting with GitHub. Each tool is defined with a name, description, schema for its arguments, and the underlying service function to execute.
Sources: agent-packages/packages/github/src/tools.ts:72-304
Issues and Pull Requests
| Tool Name | Description | Operations |
|---|---|---|
search_issues_or_pull_requests | Search issues or PRs within a specific repository. | READ |
search_issues_global | Search for issues and pull requests across all GitHub repositories. | READ |
get_github_issue | Get detailed information about a specific GitHub issue or PR by number. | READ |
create_github_issue | Creates an issue in a GitHub repository. | CREATE |
update_issue | Update an existing issue in a GitHub repository. | UPDATE |
add_github_assignee | Add an assignee to a GitHub issue or PR. | UPDATE |
remove_github_assignee | Remove an assignee from a GitHub issue or PR. | UPDATE |
add_issue_comment | Add a comment to an existing issue or pull request. | CREATE |
create_pull_request | Create a new pull request. | CREATE |
get_pull_request | Get details of a specific pull request. | READ |
get_pull_request_status | Get the combined status of all status checks for a pull request. | READ |
get_pull_request_files | Get the list of files changed in a pull request. | READ |
get_pull_request_comments | Get the review comments on a pull request. | READ |
get_pull_request_reviews | Get the reviews on a pull request. | READ |
create_pull_request_review | Create a review on a pull request with comments and approval status. | CREATE |
merge_pull_request | Merge a pull request into its base branch. | UPDATE |
update_pull_request_branch | Update a pull request branch with the latest changes from the base branch. | UPDATE |
Repositories and Code
| Tool Name | Description | Operations |
|---|---|---|
search_repositories | Search for GitHub repositories. | READ |
create_repository | Create a new GitHub repository. | CREATE |
search_repository_code | Search for code within a specific repository. | READ |
search_code_global | Search for code across all public GitHub repositories. | READ |
create_or_update_file | Create a new file or update an existing file in a GitHub repository. | CREATE, UPDATE |
get_file_contents | Get contents of a file or directory from a GitHub repository. | READ |
create_branch | Create a new branch in a GitHub repository. | CREATE |
list_commits | Get list of commits of a branch. | READ |
Users and Organizations
| Tool Name | Description | Operations |
|---|---|---|
get_organization_users | Get all users in a GitHub organization. | READ |
search_github_users | Search for GitHub users by username, name, or other criteria. | READ |
Sources: agent-packages/packages/github/src/tools.ts:72-304
Sequence Diagram: Creating a GitHub Issue
This diagram shows the sequence of events when a user asks Quix to create a GitHub issue.
This sequence illustrates the tool-calling process for creating a new issue.