GitHub MCP Permissions: Start Your AI Agent Read-Only

A GitHub connection is not a job description. The same authenticated surface can expose repository reads, issue comments, pull-request changes, workflow reruns, secret administration, branch protection, organization settings, and destructive operations. An agent that needs to summarize five issues should not inherit a maintainer role just because the account can.

The safest default is simple: keep the agent read-only, expose only the tool family required for one named job, and move every write into a separate reviewed step.

That rule applies whether you use GitHub's official MCP server or Aident Loadout's GitHub integration. The controls differ, but the authorization question is the same: which identity may run which operation, against which repository, with which inputs and consequence?

The Audit Result

On September 21, 2026, an integration-scoped search of Aident Loadout's staging catalog reported 872 GitHub Action hits. Nine pages returned 871 rows, but rank overlap left 862 distinct Action names in the observed set. That mismatch matters: capability search is a discovery surface, not a stable contract enumeration endpoint.

The bounded name audit still shows why connection-level permission is too broad.

The prefix method treated get, list, find, search, check, compare, download, retrieve, view, and read as read-oriented. It treated verbs such as create, update, delete, remove, add, close, merge, approve, rerun, enable, and transfer as explicit writes. This is a naming audit, not proof of HTTP method, GitHub scope, or business consequence.

The useful conclusion is not that GitHub has one precise number of tools forever. It is that a ranked discovery catalog, an MCP tool list, a token scope, and a user's repository role are four different boundaries. A safe policy must reconcile all four.

Use Four Permission Layers

1. Provider identity and repository access

GitHub remains the authority for what the credential can access. A fine-grained personal access token can be limited to selected repositories and permissions. A GitHub App has installation and permission boundaries. OAuth access is constrained by the approved scopes plus the user's own privileges.

Choose the smallest provider identity that can complete the job. Do not give an organization-wide token to an agent that needs one repository. Do not use an administrator's credential to avoid learning which read permission an endpoint requires.

GitHub's REST API can return X-Accepted-GitHub-Permissions for an endpoint. Preserve that evidence when a request fails rather than widening the token speculatively.

2. Server-side tool exposure

GitHub's official MCP server supports toolsets, individual-tool inclusion, exclusions, and a strict read-only mode. The read-only setting takes precedence over explicitly requested write tools. For a local server, GitHub documents the --read-only flag and GITHUB_READ_ONLY environment variable. For its remote server, GitHub documents a read-only URL form and request header.

Start with one or two read toolsets rather than the default surface. If the job is issue review, repository administration, workflow controls, secrets, deployments, and write tools do not belong in the agent context.

Scope filtering is not uniform across credentials. GitHub currently filters tools at startup for classic personal access tokens, uses dynamic challenges for remote OAuth, and leaves fine-grained token and GitHub App permission enforcement to the API. Seeing a tool therefore does not prove that the credential may use it, and hiding a tool is not the only authorization control you need.

3. Agent allowlist and exact input

The client or workflow should allow one exact operation, not every tool the server exposes. Bind that operation to the approved repository, state, result limit, and fields.

For a first issue-review test, the policy can allow one search such as:

repo:OWNER/REPOSITORY is:issue state:open label:bug

Limit the first page to five records. Return only number, title, labels, update time, and canonical URL. Do not retrieve bodies, comments, code, private vulnerability details, or other repositories until a human chooses a specific next question.

4. Separate write execution

An agent can recommend a label, comment, closure, assignment, pull-request change, or workflow rerun without receiving permission to perform it. GitHub Agentic Workflows formalizes this pattern with read-only agent jobs and safe outputs: the agent produces a structured request, then a separate job with the narrow write permission validates and applies it.

Use the same separation outside GitHub Agentic Workflows. The reviewing step should see the exact repository, target object, proposed payload, expected effect, duplicate-prevention rule, and read-back before one write is approved.

A Permission Ladder for GitHub Agents

This ladder separates authentication from authorization. A connected account proves that a credential exists. It does not prove that the agent may inspect every private repository, read every issue body, rerun workflows, merge pull requests, or change settings.

A Safe First Test With Aident Loadout

Install the public CLI from the Aident setup guide, then confirm the account and GitHub connection:

aident account auth status
aident vault vault --action status --integrationId "github_tools"

If the intended GitHub account is not ready, stop after catalog and schema inspection. Do not paste a token into the prompt.

Discover the current read Action by job:

aident capabilities search \
  --query "GitHub search issues read only" \
  --types '["action"]' \
  --scope '{"integrationId":"github_tools"}' \
  --targetEnv staging

Copy the exact returned name into a temporary variable and inspect the current contract:

GITHUB_ISSUE_SEARCH_ACTION="<PASTE_RETURNED_GITHUB_ISSUE_SEARCH_ACTION>"

aident capabilities get \
  --name "$GITHUB_ISSUE_SEARCH_ACTION"

Then preflight one bounded public-repository read:

aident capabilities preflight \
  --name "$GITHUB_ISSUE_SEARCH_ACTION" \
  --input '{
    "q":"repo:openai/codex is:issue state:open label:bug",
    "page":1,
    "per_page":5,
    "sort":"updated",
    "order":"desc"
  }'

That exact September 21 input passed Aident preflight at $0.00. It was not executed during this audit. The exact schema statement lookup returned no output on two attempts, so the audit stopped rather than treating a successful preflight as permission to read GitHub data.

A free quote is not a safety verdict. Before execution, confirm the connected identity, repository, query, record limit, returned data, wrapper risk, and absence of any write from the plan.

Direct GitHub MCP vs Aident Loadout Controls

This is not a claim that one route is universally safer. A broad token behind a read-only server is still broader than necessary at the provider layer. A narrow credential behind a client that exposes every mutation is still missing an agent policy. Use both provider controls and operation-level controls.

For the route-selection decision, read GitHub MCP Server vs Aident Loadout for Codex. For untrusted repository content, use How to Secure GitHub Agentic Workflows Against Prompt Injection. For the approval record around any later mutation, use AI Agent Approval Workflow: Separate Risk From Spend.

Seven Checks Before a GitHub Write

1. Identity: which user, App installation, or token is in scope?

2. Repository: which exact owner and repository may change?

3. Operation: which single tool or Action may run?

4. Target: which issue, pull request, ref, workflow run, setting, or member is affected?

5. Payload: what exact fields will be created, replaced, or removed?

6. Consequence: can it trigger workflows, notifications, deployments, reviews, or irreversible loss?

7. Read-back: what smallest provider-owned state proves the intended result?

If any answer changes, preflight and approval are stale. A successful comment does not grant permission to label the issue. A successful label does not grant permission to close it. A merged pull request does not grant permission to rerun a workflow or alter branch protection.

Common Permission Mistakes

Treating read-only mode as repository scoping

Read-only mode removes write tools. It does not necessarily stop a credential from reading every repository and data class available to it. Restrict the credential and the approved inputs too.

Treating tool visibility as authorization

Tool visibility depends on server configuration and authentication type. Some token types show tools that the API later rejects. Review the provider permission and the exact call.

Treating lockdown mode as an access-control boundary

GitHub describes lockdown as a best-effort content filter for untrusted public-repository content, not an authorization boundary. It does not change what the credential can read or write.

Approving a category of writes

"Manage issues" can mean comment, label, assign, close, reopen, lock, transfer, or delete. Approve the one consequence the job requires.

Letting a read become a write in the same agent turn

A useful analysis may recommend a change. Return that recommendation as structured evidence and wait for a separate reviewed operator step.

Inspect One GitHub Reader Before Enabling Writes

Set up Aident Loadout and inspect one bounded GitHub read

Start with a public repository, five metadata records, and no issue bodies. Record the identity, Action, input, consequence, and read-back. Expand only after the first boundary is observable and reviewed.

Method and Limitations

This audit inspected the Aident staging catalog on September 21, 2026. It paged an integration-scoped GitHub search at 100 results per page, deduplicated returned canonical names, classified names by documented verb prefixes, reviewed wrapper operation metadata, and preflighted one five-result public issue search. The search endpoint reported 872 hits, while ranked-page overlap produced 862 distinct observed names. The result is therefore a bounded discovery audit, not an exhaustive GitHub API or MCP tool inventory.

The audit did not execute a GitHub Action, inspect private repositories, verify every Action schema, test every credential type, compare latency, or certify a security policy. GitHub connection readiness did not return during the broad Vault check, and exact schema inspection returned no output twice. Ahrefs was not connected, so current keyword volume, difficulty, traffic potential, and SERP composition are unknown.

Google Search Console recorded 15 impressions and zero clicks for five current GitHub-MCP route-selection variants on the existing comparison canonical, with an impression-weighted average position of 13.67. That supports keeping route selection on the existing page. It does not establish demand for this permissions query, whose baseline starts after publication.

Sources

• GitHub MCP Server configuration, reviewed September 21, 2026.

• GitHub MCP Server scope filtering, reviewed September 21, 2026.

• GitHub MCP policies and governance, reviewed September 21, 2026.

• GitHub App permission selection, reviewed September 21, 2026.

• GitHub fine-grained token permission reference, reviewed September 21, 2026.

• GitHub Agentic Workflows read permissions, reviewed September 21, 2026.

• GitHub Agentic Workflows safe outputs, reviewed September 21, 2026.

• Aident Loadout setup, reviewed September 21, 2026.

• GitHub for Aident Loadout, reviewed September 21, 2026.

• Live Aident Loadout staging capability search and exact free preflight, inspected September 21, 2026.

Refresh this audit when GitHub changes MCP read-only behavior, scope filtering, toolsets, safe outputs, token models, or governance controls, or when Aident changes the GitHub Action catalog, schemas, risk metadata, Vault behavior, pricing, or approval flow.