> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meetsquad.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Run an agent when an issue opens or a pull request merges, and open or comment on issues from a flow.

GitHub connects the work to the evidence. An [agent](/agents) can start when an issue opens or a pull request merges, read either one, and write back an issue or a comment.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/squad/O_98Wy8uNjlYcgBb/images/integrations-github-light.png?fit=max&auto=format&n=O_98Wy8uNjlYcgBb&q=85&s=a7bd4b623a95cba432a16c2c74335867" alt="GitHub integration settings" width="2880" height="1800" data-path="images/integrations-github-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/squad/O_98Wy8uNjlYcgBb/images/integrations-github-dark.png?fit=max&auto=format&n=O_98Wy8uNjlYcgBb&q=85&s=af5e29f7f86e33f6716ab0d4fb05950a" alt="GitHub integration settings" width="2880" height="1800" data-path="images/integrations-github-dark.png" />
</Frame>

## Connect

<Warning>
  GitHub connects through a GitHub App install, not an OAuth consent screen. Clicking **Connect** sends you to GitHub's **install app** screen.
</Warning>

<Steps>
  <Step title="Start the install" icon="https://mintcdn.com/squad/O_98Wy8uNjlYcgBb/icons/github.svg?fit=max&auto=format&n=O_98Wy8uNjlYcgBb&q=85&s=8446aeb4abeb46581cfeb5491316dd8f" width="24" height="24" data-path="icons/github.svg">
    Click **Connect** on the GitHub card. GitHub's **install app** screen opens.
  </Step>

  <Step title="Pick the account and the repositories" icon="folder-git-2">
    That screen asks which account or organisation to install Squad on, and which repositories it may access: all of them, or a list you choose.
  </Step>
</Steps>

That repository choice is the whole of Squad's access. To change it later, manage the Squad installation in your GitHub settings rather than reconnecting in Squad.

## What it brings in

<Note>
  Nothing from GitHub becomes a signal. Issues and pull requests are things an agent reads and writes on demand. They don't enter the evidence pipeline.
</Note>

## Triggers

* **Issue opened.** An issue is opened in an installed repository.
* **Pull request merged.** A pull request is merged in an installed repository.

Both fire across every repository in the installation. Closed issues, opened pull requests and review comments are not triggers.

## Tools

<Tabs>
  <Tab title="Read">
    | Tool                 | What it does                                                                                          |
    | -------------------- | ----------------------------------------------------------------------------------------------------- |
    | **Get issue**        | Takes a reference in the form `owner/repo#number` and returns the number, title, state, body and URL. |
    | **Get pull request** | Takes a reference in the form `owner/repo#number` and returns the number, title, state, body and URL. |

    In a triggered run each one defaults to the issue or pull request that started the run, so the agent doesn't have to guess an ID.
  </Tab>

  <Tab title="Write">
    | Tool                    | What it does                                                                                             |
    | ----------------------- | -------------------------------------------------------------------------------------------------------- |
    | **Create issue**        | Opens a real issue in a repository you name as `owner/repo`, with a title and an optional markdown body. |
    | **Comment on issue/PR** | Posts a markdown comment on an issue or pull request, defaulting to whichever one triggered the run.     |

    <Warning>
      Both act on your repositories, so they are opt-in per agent and carry the **Outbound** badge in the agent builder.
    </Warning>
  </Tab>
</Tabs>

## A worked example

Build an agent triggered on **Issue opened**. It reads the issue, checks the description against recent [signals](/signals) to see whether customers have hit the same thing, and comments with what it found: how many customers, how recently, and which insight it belongs to. Engineering gets the demand context on the issue itself, before anyone picks it up.

## Limits

Squad reads issues and pull requests. It does not read code, files, diffs or commits. The two triggers are the only GitHub events available. Repository access is set in the GitHub install, not in Squad.