# GitHub: how to read it into Maplith

*Software development · also known as GitHub organisation, GitHub repositories · last checked 2026-10-14 · recipe `maplith://systems/github`*

GitHub holds how software work moves: issues opened and closed, pull requests reviewed and merged, the runs that build and deploy it, and the security alerts on the code. Maplith reads the structure and the flow of that work to find the processes and their stalls, never the code itself.

## Best path

**Recommended: your agent fetches it.** Most assistants already reach GitHub, and a first map needs a few months of issues and pull requests. For a daily refresh and GitHub's own events, Maplith's GitHub App reads the same, read-only, once it is installed for the workspace.

Try the paths in this order (ADR-0031):

1. **Your agent fetches it**, with the access your human already gave you. Connectors a vendor or client page confirms: GitHub connector in Claude; GitHub connector in ChatGPT. The agent lists the issues and pull requests of the repositories its human names, a few months back, with their state, labels, assignees as user names the masking tries to mask, and when each was opened, reviewed, merged or closed. It only reads; it should not comment, label or merge.
2. **Maplith reads an MCP server your human already has.** Official: **GitHub MCP Server**. Endpoint: not given here; it comes from the vendor's own setup instructions. Documentation (a page to read, not an address to connect to): https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/use-the-github-mcp-server. Access: A fine-grained personal access token limited to the repositories it should see, with read-only repository permissions. It acts as the person who made it, which is why Maplith's own connector is a read-only App instead. It offers tools, not resources: search and read issues, pull requests and code, and also write them. Use it as path 1, for your own agent. Maplith cannot read this server: it offers tools or a personal sign-in to an agent, not resources Maplith reads. Maplith reads only a server that serves MCP resources and takes a token a person types under Data sources › Systems in the Maplith app, such as the customer-run template for a database (ADR-0028). Your human can connect this server to you instead, as path 1.
3. **Export files**, the fallback that always works: see *Export steps* below.
4. **Maplith's own integration** (built, and switched on per workspace: ask Maplith (suggest_feature) to switch it on for yours): see *Maplith's integration* below.

## Datasets that make a good map

| Dataset | One row is | Key columns | Joins to |
|---|---|---|---|
| Issues | One issue: its number, title, state, labels, who opened it and is assigned (user names), and when it was opened and closed. | repository, number, state, labels | Pull requests that close it; the work and the systems its title and labels name. |
| Pull requests | One pull request: its number, branch, state, reviews, when it was opened, reviewed and merged, and the issues it closes. | repository, number, head branch, merged_at | Issues by the numbers it closes; workflow runs and deployments by its commit. |
| Workflow runs and deployments | One run of a workflow or one deployment status: which workflow or environment, the commit, whether it succeeded, and when. | workflow, head_sha, conclusion, environment | Pull requests by commit; the services the deployments name. |
| Security alerts | One secret-scanning, code-scanning or Dependabot alert: its kind, severity, state and when it was opened and fixed. Never the secret itself. | repository, alert number, kind, state | The repository and the pull request that fixed it. |

Columns are named, never their values. Maplith tries to mask personal data such as email addresses, but that is best effort: your human decides what goes in.

## Read-only access

**Who usually has the rights:** An owner of the GitHub organisation, or an admin of the repositories, who may install GitHub Apps.

**For the key your own agent's client uses, choose only these read permissions:** `metadata: read`, `issues: read`, `pull_requests: read`, `actions: read`, `deployments: read`, `secret_scanning_alerts: read`, `security_events: read`, `vulnerability_alerts: read`, `members: read`

**Where to click:**

1. In Maplith, open Data sources › Systems and click Connect GitHub
2. GitHub opens the install page of Maplith's read-only App: choose the organisation
3. Choose all repositories, or only the ones Maplith should read, and click Install
4. GitHub returns you to Data sources › Systems, where the installation shows as connected

A key or token made here stays in the tool that reads the system for your human, never in a chat. Maplith asks for one only under Data sources › Systems in the app: for an MCP server it can read, or for its own integration below.

## Export steps

**Format:** JSON from the GitHub REST API, or CSV from a project view · **Date range:** The last 6 months

1. For each repository, list its issues and pull requests with state all through the REST API, or export a project view as CSV
2. Keep number, title, state, labels, created, closed and merged dates, and the linked issue numbers
3. Leave out issue and comment bodies unless they describe how work is done
4. Upload the files under Data sources › Scans

## Volume hint

**About 50–2,000 issues and pull requests a month** (an estimate). Estimate for a small software team, not a measured figure: workflow runs add the most rows when every push builds.

Every row an agent reads passes through its context, about one token per four characters. Above a few thousand rows a dataset, or for a daily refresh, prefer an MCP server or an export over fetching through the chat.

## Maplith's integration

**Status:** built, and switched on per workspace: ask Maplith (suggest_feature) to switch it on for yours.

**How to connect:**

1. In Maplith, open Data sources › Systems and click Connect GitHub
2. Install Maplith's read-only GitHub App on the organisation, for all repositories or the ones it should read
3. GitHub returns you to Data sources › Systems: Maplith checks that you own or administer the installation before it binds it to the workspace
4. To let agents act in GitHub as well, install Maplith Agents separately; the read-only App never writes

**The permissions it needs, and why:**

- `metadata: read`: lists the repositories the installation covers
- `issues: read`: reads issues and their labels, the work queue the map follows
- `pull_requests: read`: reads pull requests and their reviews, to see where work stalls
- `actions: read`: reads workflow runs, so a failed build becomes a signal
- `deployments: read`: reads deployment statuses, so a failed deploy becomes a signal
- `secret_scanning_alerts: read`: reads that a secret-scanning alert exists, never the secret
- `security_events: read`: reads code-scanning alerts
- `vulnerability_alerts: read`: reads Dependabot alerts on the dependencies
- `members: read`: checks that the person connecting administers the organisation

**What it reads:**

- Issues and pull requests of the repositories the installation covers: numbers, titles, states, labels, dates and reviews
- GitHub's own events as they happen: new issues and pull requests, failed workflow runs and deployments, and security alerts
- What reaches the map: the repositories as a source, the processes the issues and pull requests show, and where they stall; user names are personal data the masking tries to mask

**What it never reads or does:**

- The code: the read-only App has no contents permission
- Writing anything in GitHub: no comment, label, merge or commit; GitHub refuses every write made with its token
- Repositories the installation does not cover

**Choosing what is read:** The installation decides: all repositories of the organisation, or only the ones chosen when it was installed. A person changes it in GitHub, under the organisation's installed GitHub Apps, and Maplith reads what the installation covers from the next scan.

## What Maplith sets up once it is connected

Maplith builds these itself; a person corrects them, and never has to approve them first (ADR-0038). If the system is disconnected, Maplith takes the playbooks it set up and nobody changed out of use, and puts them back when the system is connected again; a playbook a person changed stays as they left it.

**Signals:**

| Kind | Delivery | When |
|---|---|---|
| `structure_changed` | poll | the connection offers at least a quarter more or fewer resources than at the last check |
| `process_deviation` | poll | an issue or a pull request leaves the usual path, such as a merge without a review |
| `finding_added` | poll | a scan finds a stalled queue, an issue with no owner, or work that names a system the map does not have |
| `ci_failed` | push | a workflow run on the default branch fails |
| `deploy_failed` | push | a deployment status reports a failure |
| `security_alert` | push | a secret-scanning, code-scanning or Dependabot alert is opened |

**Checks:**

- **Installation binding** (every scan): checks that the installation is still bound to the workspace and covers at least one repository
- **Event receipt** (on every delivery): verifies each delivery from GitHub with the App's webhook secret before anything is kept

**Suggested playbooks:**

- **Triage a new issue.** Starts when a scan finds an issue with no owner or no label. Steps: Read the issue and decide what kind of work it is; Label it, and assign the team or person who owns that kind of work; If it duplicates another issue, link the two and close one; Record what was decided on the signal.
- **Review a stalled pull request.** Starts when a pull request leaves the usual path or waits longer than the team's usual review time. Steps: Open the pull request and read why it waits: no reviewer, a failing check, or an open question; Ask the reviewer it waits on, or assign one; If it is no longer needed, ask its author to close it; Record the outcome on the signal.
- **Fix a failed build or deploy.** Starts when a workflow run or a deployment fails. Steps: Open the failed run or deployment and read the first error; Decide whether it is the change, the environment or a flaky test; Fix it or revert the change, and run it again; Record what failed and what fixed it on the signal.

**Schedules:**

- **Weekly look at stalled pull requests** (weekly, Monday 09:00): a review that waits a week is a process that has stopped, even when no event says so

**What setup integrity expects:**

- The GitHub installation is bound to the workspace
- The github source has an owner and a refresh cadence (Maplith states them from the workspace owner and the scan schedule; a person corrects them)
- Each suggested playbook exists, or a person removed it

## Always

- Read-only, and never a credential sent to Maplith through the chat.
- The same recent period, a few months, from every system.
- Your human decides what goes in.

## Sources

Written from the vendor's public documentation, last checked 2026-10-14:

- https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/use-the-github-mcp-server
- https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app
- https://docs.github.com/en/rest/issues/issues
- https://docs.github.com/en/rest/pulls/pulls
- https://docs.github.com/en/webhooks/webhook-events-and-payloads