# GitHub connector (https://docs.ctxpipe.ai/docs/connections/source-connectors/github)

GitHub is the first connector to set up. The ctxpipe GitHub App gives ctxpipe
access to your [Workspace](/docs/workspaces) repositories and to the code
repositories that you link. The other connectors, including Buildkite, write
their content into a Workspace repository on GitHub, so they need it too.

<Callout title="Self-hosted deployments">
  Hosted ctxpipe supplies the GitHub App. A self-hosted deployment creates and
  owns its own App. The operator completes
  [Self-host GitHub](/docs/self-hosting/github) first.
</Callout>

## Connect GitHub

<Steps>
  <Step>
    ### Start the connection

    Choose **Connect GitHub** in the **Get started** guide on Home, or open
    **Connectors** and choose GitHub. If your ctxpipe user has no linked GitHub
    account, sign in to GitHub first.
  </Step>

  <Step>
    ### Install the App

    Install the ctxpipe GitHub App on the GitHub account or organization that
    owns your repositories. If you cannot install apps there, GitHub sends a
    request to an organization owner.
  </Step>

  <Step>
    ### Choose the repositories

    Give the App access to the repository for the knowledge and to the code
    repositories that you want to link. You can start with a few repositories,
    and add more later in GitHub.
  </Step>

  <Step>
    ### Create a Workspace and link code

    [Create a Workspace](/docs/workspaces/create-workspace), then
    [link code repositories](/docs/workspaces/linked-repositories) in its
    **Settings**.
  </Step>
</Steps>

A GitHub account can belong to one ctxpipe user only. If another ctxpipe user
has your GitHub account, sign in as that user and unlink it (**User account →
OAuth Providers → Unlink OAuth**), or use a different GitHub account.

## What GitHub enables

* Workspace repositories that ctxpipe can read and write.
* Code search and extraction across the linked repositories.
* The docs, ADRs, `AGENTS.md`, and skills in linked repositories, as context
  for agents.
* Pull requests for source changes, upgrades, and Workspace chat.
* A mirror of the issues and the closed pull requests of each linked
  repository.

## Closed pull requests

When you link a GitHub repository, ctxpipe also mirrors its closed pull
requests, merged or not, into `github/pulls/<owner>/<repo>/` in the Workspace
repository. Each file holds the conversation, the reviews, and the changed
paths, but not the diff. It records `merged` and `mergedAt`.

* **When you link** the repository, ctxpipe backfills up to 200 of its most
  recently updated closed pull requests.
* **After that**, each pull request that closes, and each later review or
  comment, arrives when GitHub reports it.
* **Each Workspace** that links the repository gets its own copy.
* **When you unlink**, new pull requests stop. The mirrored files stay until
  you delete them.

Draft and open pull requests are not mirrored. There is no setting for this.

## Issues

ctxpipe also mirrors the issues of each linked repository, open and closed. Each
issue is one file at `github/issues/<owner>/<repo>/<number>.md`, with its
description, labels, assignees, state, and its 100 most recent comments.

* **When you link** the repository, ctxpipe backfills up to 200 of its most
  recently updated issues.
* **After that**, each change to an issue, and each comment on it, arrives
  when GitHub reports it. When someone deletes an issue or moves it to another
  repository, ctxpipe removes its file.

The GitHub App needs the **Issues: Read-only** permission. Until the owner of
your GitHub installation accepts that permission, ctxpipe does not mirror
issues. Pull requests and code continue to work. When the owner accepts it,
ctxpipe backfills the issues of each linked repository of that account.

## In the graph

A pull request links to its repository, to the GitHub issues whose URL it
contains, and to the Linear issues that it names. A merged pull request also links to each file that it added,
changed, removed, or renamed. It **resolves** an issue when its branch names the
issue, or when a closing word such as `fixes` or `closes` comes before the
issue identifier. A GitHub issue links to the pull requests that closed it.

<Cards>
  <Card title="Create a Workspace" href="/docs/workspaces/create-workspace" description="Choose or create the Workspace repository." />

  <Card title="Linked repositories" href="/docs/workspaces/linked-repositories" description="Add code repositories for search and extraction." />
</Cards>