GitHub

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, 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.

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:

- 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 and Connect your estate.

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.