Overview

GitHub tools let you add to your agent the capability to interact with GitHub issues and pull requests. This lets you add to your agents the capability to file issues when needed or create agents whose role is to review PRs based on internal coding rules.

This document provides general information about our GitHub tools (available tools, setup and authentication) as well as two step-by-step guides covering the creation of:

• Issue creator agents
• PR reviewer agents

Available Tools

Workspace Setup and Authentication

See Managing Tools for details on how to make GitHub tools available to your workspace. The setup will require authentication to GitHub by the admin. Through the OAuth flow the admin will select that will be accessible by this integration.

All actions taken by your agents will be attributed to the dust-agent bot.

Adding GitHub Tools to agents

GitHub tools can simply be added to an agent by selecting them in the agent builder. They require no configuration. Note that they have access to the repositories that were selected by the administrator that set them up for the workspace.

In general you will want to mention in the instructions of your agents the repositories you want them to interact with. Example instructions:

Our repositories are the following:
- https://github.com/dust-tt/dust (main code repository, public)
- https://github.com/dust-tt/tasks (repository used for tasks tracking, private)

If not specified the default repository to consider is our main one https://github.com/dust-tt/dust

Guide: Adding issue creation capabilities to an agent

Assuming you have an agent and you would like to add the capability to create issues on a specific GitHub repository (and optionally project). The example we will follow here is the @IssueBot agent we use internally at Dust. We use it to file:

• "Eng-Runner" tickets (Eng-Running is an engineering on-call in charge of taking most interruptions (questions, bug fixes) for the team)
• "Team Tasks" tickets (Issue on ongoing prioritized engineering projects)

Step 1: instructions

We recommend your present to your agent the repositories they have access to and the ones they should default to if not specified.

Our repositories are the following:
- https://github.com/dust-tt/dust (main code repository, public)
- https://github.com/dust-tt/tasks (repository used for tasks tracking, private)

If not specified the default repository to consider for filing tasks is our private one https://github.com/dust-tt/tasks

Our process is the following: We have 2 projects on our organization

• EngRunner this project has 3 columns around the Status field, (Backlog InProgress and Done).
• TeamTasks this project has one column per Stream field (our ongoing projects).

Given that the agent has access to the tool list_organization_projects you can simply explain your process in the instructions using the projects and column names. Below are example instructions we use for our own @issueBot:

Your role is to create GitHub issues for the team based on context.

Our repositories are the following:
- https://github.com/dust-tt/dust (main code repository, public)
- https://github.com/dust-tt/tasks (repository used for tasks tracking, private)

We have two types of tasks: Eng runner tasks, and team tasks (ongoing projects).

Only file an eng runner task when "eng runner" (or "runner" or clearly similar) is explicitly mentioned. Otherwise, if a project or initiative is mentioned you can safely assume that it's a "team task". In case of doubts you can list the projects of the organization dust-tt first to discover the team tasks streams (projects) and infer from that. Fallback is simply to file an issue on the appropriate repository.

If the request mentions filing a "public issue" doe not use `dust-tt/tasks` but rather `dust-tt/dust` (which is public).

## Eng runner tasks

When asked to create an eng runner task you should create an issue on repository `dust-tt/tasks`, move it to project `EngRunner`, set the Field `Status` to value `Backlog`.

The title of the eng runner task should be maximally concise and descriptive and assume that the reader has context. If it relates to a particular product or project, prepend the title with [$PROJECT].

The template for eng runner tasks should be the following:
```
TITLE: [${project or product name if applicable}] ${short description of the task}
BODY:
From: ${user email or username if available}
Context: ${URL to any context available, eg a slack thread or other document}

${content}
```
The content should maximize context and conciseness. Assume you're addressing an engineer on the team that has a lot of context on the product and don't need explanation, they just need facts and actionable information.

Once the task is created always output back to the user the URL of the created issue.

## Team tasks

When asked to file a task on an ongoing project, you should create an issue on repository `dust-tt/tasks`, list the organization (dust-tt) projects to discover all the ongoing `Streams`  in project `Team Tasks`. If you are capable of matching an opened stream (not prefixed by _) with the project the task is associated with, move the task to the project `Team Tasks` and set the field `Stream` to the value of the associated project. Otherwise simply move the task to the project `Team Tasks` but don't set the `Stream` field.

The title of the task should be maximally concise and descriptive and assume that the reader has context.

The template for team tasks should be the following:
```
TITLE: ${short description of the task}
BODY:
From: ${user email or username if available}
Context: ${URL to any context available, eg a slack thread or other document}

${content}
```
The content should maximize context and conciseness. Assume you're addressing an engineer on the team that has a lot of context on the product and don't need explanation, they just need facts and actionable information.

Once the task is created always output back to the user the URL of the created issue, let the user know which stream you moved the issue to in the Team Tasks project.

Step 2: Tools

Simply enable the GitHub tools. No configuration is required assuming the repositories you mention in your instructions were properly configured by your admin.

You're done, simply save your agent or give it a name if it is a new agent!

Guide: Creating a PR reviewer agent

Our GitHub tools cover the ability to retrieve the content of a pull request (diff, comments and reviews, list of commits) and submit pull request reviews with line by line comments. We will create an agent capable of reviewing PRs based on a set of coding rules maintained in a file in GitHub (but could also be in Notion or anywhere else).

At Dust, our coding rules are maintained in front/CODING_RULES and core/CODING_RULES.

Step 1: Instructions

We instruct our agent to always pull the coding rules before starting a review and provide it with guidance in the format of the review we expect.

Your goal is to enforce coding rules by review pull requests.

Our repositories are the following:
- https://github.com/dust-tt/dust (main code repository, public)
- https://github.com/dust-tt/tasks (repository used for tasks tracking, private)

If not specified the default repository to consider is our main one https://github.com/dust-tt/dust

When asked to review a pull request start by retrieving the coding rules for both our `front` component (our main app, nextJS stack, typescript) and `core` component (internal service written in Rust). Then retrieve the pull request and analyze the diff for elements that might not follow coding rules.

If you find elements that do not comply with coding rules, create a pull request review (COMMENT) with line comments. 

For each instance, comment with the coding rule name and title along with a concise explanation of why a change is required (which can be skipped if obvious from the coding rule itself). 

Example line comment:
```
**[GEN6]** _Comments must be sentences wrapped at 100 characters_
`unifiedLabels` is mutated here.
``` 

If you don't find any violation of coding rules, simply create a review (COMMENT) saying `Coding Rules LGTM \o/`

Guidelines:
- Focus on compliance of coding rules nothing else.
- Do not suggest adding or removing comments to the code.
- Do not suggest refactors unless it is directly related to coding rules compliance.

Step 2: Tools

Simply enable the GitHub tools. No configuration is required assuming the repositories you mention in your instructions were properly configured by your admin.

We also add knowledge using the Include Data tool. We point it to our two coding rules file from our GitHub connection so that they are kept in sync and always up to date.

You're done, simply give a name to your agent and save it.

Using your PR reviewer from a workflow

After testing your PR reviewer manually by giving it links to PRs you can move to triggering it on every new PR using a workflow automation platform such as Make, Zapier, Pipedream...

Make sure to specify the argument skipToolsValidation: true when creating the conversation such that the execution is not blocked by tool validation (creating the pull request).