Docs: System guides

Read GitHub into Maplith

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.

Software development · Also known as GitHub organisation, GitHub repositories · Checked 2026-10-14

On this page

Best path

Recommended: your agent fetches it. Most agents 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:

Your agent fetches it, with the access you already gave it. 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 you name, a few months back, with their state, labels, assignees as user names, which Maplith tries to mask, and when each was opened, reviewed, merged or closed. It only reads; it should not comment, label or merge.
Maplith reads an MCP server you already run. GitHub runs GitHub MCP Server. Its address comes from GitHub’s own setup instructions. Documentation: docs.github.com. 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. Maplith cannot read this server itself, because it offers tools or a personal sign-in to an agent. Connect it to your agent instead, as the first path.
Export files, the fallback that always works. See the export steps below.
Maplith’s own integration. Built, and switched on per workspace. Ask Maplith at [email protected] 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: you decide what goes in.

The access to give

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

Choose the narrowest access that covers the data:

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:

In Maplith, open Data sources › Systems and click Connect GitHub
GitHub opens the install page of Maplith's read-only App: choose the organisation
Choose all repositories, or only the ones Maplith should read, and click Install
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, never in a chat. Maplith asks for one only under Data sources › Systems in the app.

Export steps

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

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

How much data

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.

An agent that reads rows through a chat reads every one of them, about one token per four characters. Above a few thousand rows a dataset, or for a daily refresh, an MCP server or an export is the better path.

Maplith’s integration

Status: Built, and switched on per workspace. Ask Maplith at [email protected] to switch it on for yours.

How to connect

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

The permissions it asks for

Permission	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 sets these up itself. You correct them; you never have to approve them first. If the system is disconnected, the playbooks Maplith set up and nobody changed are taken out of use, and put back when it is connected again.

Signals it raises:

A connected system grew or shrank (checked on a schedule): the connection offers at least a quarter more or fewer resources than at the last check
A step takes much longer than before (checked on a schedule): an issue or a pull request leaves the usual path, such as a merge without a review
New finding (checked on a schedule): a scan finds a stalled queue, an issue with no owner, or work that names a system the map does not have
A CI run failed (as it happens): a workflow run on the default branch fails
A deployment failed (as it happens): a deployment status reports a failure
A security alert is open (as it happens): 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.
Review a stalled pull request. Starts when a pull request leaves the usual path or waits longer than the team's usual review time.
Fix a failed build or deploy. Starts when a workflow run or a deployment fails.

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

Always

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

Sources

Written from public documentation, last checked 2026-10-14:

← All system guides · Markdown version