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

# GitHub

> Connect the repositories your engineering team works in, so Zudo can follow the work behind a customer request.

<Note>
  **Early access.** Zudo links pull requests to requests and shows what is happening to them. It does not yet change a
  request's status when work merges or ships — that is still being built. This page says exactly what works now. Ask
  your Zudo contact to turn the integration on for your organization.
</Note>

Zudo connects to GitHub through a GitHub App you install on your own account or organization. You choose which repositories it can see, on GitHub's own install screen, and the app only ever reads.

## Connect

<Steps>
  <Step title="Start from Zudo">
    Go to **Settings → Connections**, click **Add Connection**, and choose **GitHub**. Only owners and admins can add a
    connection.
  </Step>

  <Step title="Pick the account">
    Zudo sends you to GitHub to install the app. Choose the personal account or organization whose repositories you want
    to connect. If you are not an owner of that organization, GitHub asks an owner to approve the install instead, and
    nothing is connected until they do.
  </Step>

  <Step title="Choose the repositories">
    Grant access to **All repositories** or **Only select repositories**. This is the access boundary, and it stays
    under your control on GitHub — Zudo cannot widen it.
  </Step>

  <Step title="Come back to Zudo">
    GitHub returns you to Settings → Connections. The connection appears with the repositories it can see.
  </Step>
</Steps>

You can connect more than one GitHub account to the same Zudo organization. A GitHub App is installed per account, so a company with repositories under two GitHub organizations needs one installation for each, and both appear as separate connections.

## What Zudo reads

The app requests read-only access to five things, and nothing else:

| Permission    | What it is for                                       |
| ------------- | ---------------------------------------------------- |
| Metadata      | Repository names and basic details. Always required. |
| Pull requests | Pull request titles, state, branches and merges.     |
| Contents      | Branch names, and which commits a deploy contained.  |
| Deployments   | Deployment status, for knowing when work shipped.    |
| Actions       | Workflow runs, as an alternative deploy signal.      |

**Zudo never writes to GitHub.** It posts no comments, sets no labels, and creates no status checks. It has no permission to do any of those.

## Watching repositories

Two different things decide whether Zudo looks at a repository.

**Access** is set on GitHub, under the installation. It is what the app can see at all. Change it with **Manage access on GitHub** on the connection card.

**Watch** is set in Zudo, per repository. Every repository you grant is watched by default, because you already chose them on the install screen. Turning Watch off stops Zudo looking at that repository without changing anything on GitHub — useful for a repository that is noisy or irrelevant to customer work.

If the list in Zudo disagrees with what you granted on GitHub, press **Refresh** on the connection card to rebuild it.

## Connecting work to a request

Open any request and you will find a **Development** card. It shows the branches being followed for that request, the pull requests that satisfy it, and a branch name you can copy.

### Follow a branch

**Follow a branch** is the most direct option, and the earliest: pick a watched repository, find the branch, and select it. You do not need the developer to have named anything.

From then on Zudo follows that branch. A pull request opened from it is linked automatically, and its merge — and later its deploy — follow from there. If a pull request is already open from that branch when you start following it, that one is picked up too.

This works **regardless of your linking settings**. Choosing a branch is a decision you already made, so Zudo does not second-guess it.

### Copy the branch name

Press **Copy branch name** on the request. You get something like `zudo-441-export-times-out`. Start a branch with that name and everything links itself — nothing to remember and nothing to type.

### Let Zudo work it out

If automatic linking is on, Zudo works down a ladder and uses the first thing that matches. It records which one it used and shows it on the card, so you can always see why a link exists.

| Shown as                     | Where it comes from                                                                 |
| ---------------------------- | ----------------------------------------------------------------------------------- |
| **From a branch you follow** | A pull request opened from a branch being followed for this request                 |
| **Named this request**       | `ZUDO-441` in the branch name, the pull request title, or its description           |
| **Linked to this request**   | The request's Zudo URL pasted into the pull request description                     |
| **Named an account**         | `!acme-42!` in the pull request description — the same convention Linear issues use |
| **Linked by hand**           | Somebody pasted the pull request's GitHub URL into the Development card             |

A link, once made, stays until you remove it. Editing a description to fix a typo will not silently unlink anything.

## Choosing how linking works

**Settings → Connections → GitHub → Linking** controls what Zudo will infer. Owners and admins can change it.

* **Link pull requests automatically** — the master switch. Off means Zudo links only what a person links by hand, and the rules below stop applying. Following a branch still works.
* **A request key in the branch, title or description** — the `ZUDO-441` convention.
* **A link to the request in the description** — a pasted Zudo URL.
* **An account's External ID in the description** — the `!acme-42!` convention.
* **Let an account reference open a new request** — separate from the rule above, and worth thinking about on its own. On, a pull request naming accounts with no matching request **creates one**, with those accounts attached, exactly as a Linear issue does. Off, engineering can link to requests that already exist but cannot raise customer-facing ones unattended.
* **Request key prefix** — `ZUDO` by default. Change it if your issue tracker already owns that prefix. Changing it does not unlink anything already linked.

### What Zudo will not do

Zudo only links requests in **your** organization. A request number typed in your repository that belongs to another Zudo customer matches nothing at all.

## What appears on a request

The **Development** card shows each linked pull request with its state — open, draft, merged, or closed — the repository and number, and who opened it.

The request **timeline** gains an entry when a branch carrying a request key is pushed, and when a pull request is opened, marked ready for review, merged, closed without merging, or reopened.

Individual commits are not shown. Pushing more to an open branch adds nothing to the timeline: it fires constantly, and "someone pushed again" is harder to read than silence.

## Pull request descriptions

Zudo always **reads** a pull request's description, because that is where request keys and account references live. It does not **store** it unless your organization asks it to.

Reading and keeping are separate decisions. Linking works either way; storing the text puts a copy of your repository's prose in Zudo, which some teams want for context and others would rather avoid. Ask your Zudo contact to turn it on.

Titles, branch names and authors are always stored — they are what the Development card shows.

## What works today

* Installing the app and connecting one or more GitHub accounts
* Choosing which repositories Zudo watches
* Following a branch from a request, and picking up the pull requests opened from it
* Linking pull requests by branch name, key, URL, account reference, or by hand
* Choosing which of those rules apply, per connection
* Creating a request from a pull request that names accounts, if you allow it
* Showing pull request state and history on the request

## What does not work yet

* **A request's status does not change when a pull request merges.** Someone still closes it.
* Nothing knows when a merge has actually been deployed
* Linear issues and pull requests are not yet connected to each other, so a request linked to both counts them separately

These are being built in order.

## Disconnecting

Deleting the connection in Zudo removes the repository list and stops Zudo reading anything.

**It does not uninstall the app from GitHub.** That is deliberate — Zudo should not be able to change your GitHub account's settings. To revoke access fully, remove the Zudo app from your GitHub account or organization under **Settings → Applications → Installed GitHub Apps**.

If you uninstall the app on GitHub without deleting the connection in Zudo, the connection is disabled automatically and its history is kept.

## Troubleshooting

* **"That installation does not belong to your GitHub account"** — you were signed in to a different GitHub account than the one that owns the installation. Sign in as the right account and try again.
* **"That installation link has expired"** — the install link is valid for ten minutes. Start again from **Add Connection**.
* **The repository list looks wrong** — press **Refresh** on the connection card. If a repository is still missing, check it is granted under **Manage access on GitHub**.
* **Nothing happened after approving** — if you are not an owner of the GitHub organization, your request goes to an owner for approval. The connection appears once they approve it, and you will need to complete the install again.