# GitHub

> Connect GitHub to LightHouse: the ways to connect, the read-only scopes, where the credential is held, and what is indexed.

**Built.** The engine reads GitHub repositories (GitHub.com or GitHub Enterprise Server), and GitHub connects from LightHouse.

## Connect in LightHouse

You need the `client_admin` role. Go to **Setup and admin → Connectors → GitHub** and enter what to read: the repositories (`owner/name`, comma-separated) and, optionally, the organisation.

### One-click approval

1. Choose **Approve in GitHub**. GitHub shows the LightHouse GitHub App’s install screen.
2. Choose the repositories, or the organisation, and install.
3. GitHub returns you to LightHouse, which checks the grant and shows the connection.

The approval is valid for 15 minutes. If Atlantic’s GitHub App is not yet registered for your LightHouse, the card says so and offers the token route instead.

### Access token

1. Create a fine-grained personal access token at [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new), limited to the repositories you want read, with only the read permissions below.
2. Paste it into the card and choose **Connect**.

LightHouse calls `GET https://api.github.com/user` with it. A token whose scopes include any write is refused.

### From a terminal \[Coming]

`lighthouse connect github` will open the same approval with a device code, or, with your explicit yes, reuse your `gh` sign-in. The routes behind it are built; the CLI is not yet published. See [The CLI](/cli/).

## Connect in code

Add a source card to your deployment’s catalogue, and give the engine the token from your own secret store as `GITHUB_TOKEN`:

```yaml
- id: github-docs
  purpose: Read our service repositories' issues and docs into the knowledge base.
  executor: python
  target: aal_engine.ingest.connector:run_card
  overseer: platform-lead@example.com
  budget_usd: 0
  effect: internal
  source:
    kind: github
    repos: [example-org/payments-service, example-org/handbook]
    label: standard               # a document class in your pack's label scheme
    doc_paths: [docs/]             # optional: only Markdown under these paths
    requires:
      reads: [issues, pull requests and Markdown files in the two repositories]
      reason: the support agents answer from the service docs
```

| Setting                      | Default                  | Notes                                                                                  |
| ---------------------------- | ------------------------ | -------------------------------------------------------------------------------------- |
| `repos`                      | (required)               | `owner/name`. An organisation is never read by default                                 |
| `base_url`                   | `https://api.github.com` | GitHub Enterprise Server: `https://<host>/api/v3`                                      |
| `credential_env`             | `GITHUB_TOKEN`           | The environment variable holding the token. `""` reads public repositories without one |
| `issues`, `comments`, `docs` | `true`                   | Turn off what you do not want read                                                     |
| `doc_paths`                  | all                      | Limit Markdown to these paths                                                          |

The source runs on its card’s schedule. See [In code](/build/code/) and [Connect your estate](/connect/#where-every-credential-is-held).

## Permissions

| Permission          | Why                                                                        |
| ------------------- | -------------------------------------------------------------------------- |
| Metadata: read      | The repository and its default branch                                      |
| Contents: read      | The Markdown files on the default branch                                   |
| Issues: read        | Issues and their comments                                                  |
| Pull requests: read | Pull requests, which GitHub lists with issues                              |
| Actions: read       | Asked for by LightHouse’s approval; the engine does not read Actions today |

Nothing with write access is accepted.

The engine calls only these endpoints, all `GET`:

- `/repos/{repo}/issues?state=all&sort=updated` and each issue’s comments
- `/repos/{repo}` and `/repos/{repo}/git/trees/{branch}?recursive=1`
- `/repos/{repo}/contents/{path}` for each Markdown file

## Where the credential is held

- **For your deployment**: in your own secret store, passed to the engine as `GITHUB_TOKEN`. Rotate it there; the engine reads it when the source’s job starts.
- **For the LightHouse connection**: sealed under your tenant’s own key, never shown again. LightHouse tracks the token’s expiry and warns 14 days before it lapses. Connecting again with the same target replaces the old connection.

## What is indexed

| Item                     | What is kept                                                          |
| ------------------------ | --------------------------------------------------------------------- |
| Issues and pull requests | Title, body and comments, with the repository, kind, state and labels |
| Markdown files (`*.md`)  | Each file on the default branch, optionally only under `doc_paths`    |

**Never read:** other files (code included), wikis, and Actions or CI results.

**How often:** on the card’s schedule. Each pull reads issues updated since the last one, and only Markdown files whose content changed. A Markdown file deleted from the branch is removed from the corpus. A repository tree too large for GitHub to return whole fails the pull rather than miss files.

## Check it worked

- The source’s run note: `written 12, unchanged 0, quarantined 0, removed 0`. A `quarantined` count means documents whose label your scheme does not know; they are kept unreadable.
- On the GitHub card in LightHouse: the reads, items written and failures over the last 7 days, from your deployment’s telemetry. This matches when the card’s source keeps its default name, `github`.
- **Agents → Knowledge**: documents from `github` in the knowledge base.

## Removing the connection

- **In LightHouse**: **Disconnect** on the card (`DELETE /api/v1/connections/{cid}`). LightHouse revokes the grant at GitHub where it can, clears the sealed credential, and keeps the connection’s record and fingerprint for the audit trail.
- **In your deployment**: remove the source card and delete the token from your secret store. The documents it wrote stay in the corpus until you delete them; removing a card does not.

Source: https://docs.atlanticagenticlabs.com/connect/github/