Giving an AI agent GitHub access safely

Do not give an agent your own GitHub token. Give it a credential that is scoped to specific repositories, limited to specific permissions, short-lived, owned by something other than a person, and routed through something that can refuse a call and record it. GitHub already provides three mechanisms with different trade-offs, and picking between them is most of the decision.

What is wrong with just using a personal access token?

Nothing, if it is the right kind and you accept what it carries. Everything, if it is a classic one.

A classic PAT is roughly your whole account. It reaches every repository you can reach, across every organisation you belong to, and its scopes are coarse enough that "read a repo" and "administer an org" sit uncomfortably close together. When an agent holds one, the blast radius of a confused run is your access, not the task's.

GitHub's own fix for this was fine-grained personal access tokens, which are a real improvement: you select individual repositories, grant individual permissions, set an expiry, and organisation owners can require approval before one is issued against their resources. That is a workable agent credential.

What it still is, though, is a person's token. It carries their identity, it expires on a timescale of months rather than hours, and it stops working the day they leave. You have solved least privilege and not solved ownership.

What are the three options, really?

Deploy keys are the narrowest and the most limited. One key, one repository, git over SSH. They cannot open a pull request, post a check or read an issue, which rules them out for most agent work. GitHub's documentation now recommends a GitHub App instead for finer control.

Fine-grained PATs are the pragmatic middle. Full API access, genuinely scoped, easy to issue, and tied to a human account.

GitHub App installations are what mature products land on. The token is decoupled from any user, so it is a service identity rather than a person's; tokens are short-lived and renew automatically; permissions are per-repository and granular; and rate limits scale with the organisation rather than competing with a person's own usage. The cost is real setup: registering an App, holding its private key, and handling the installation callback.

How should the credential be scoped?

Three settings do most of the work, and the first is the important one.

Select repositories explicitly. Never "all repositories". This is the single highest-value decision in the whole flow, and the default is the wrong one for an agent.

Grant permissions per task type, not per agent. An agent that opens pull requests needs contents write and pull requests write. It does not need administration, secrets, webhooks or member management, and those are separate grants precisely so you can decline them.

Set the shortest expiry you can operate. Every credential you cannot rotate in an afternoon becomes permanent by accident.

The mental model that keeps this honest: the credential should express the contract, not the worker. If the task is "fix a bug on this repository", the key should not be able to do anything that is not part of fixing a bug on that repository, no matter how capable the thing holding it turns out to be.

Is a scoped token enough on its own?

No, and this is where most setups stop one step early.

A token defines what is possible. It says nothing about what happened, and it cannot apply judgement in the moment. Two things have to sit around it:

• A path that can refuse. If the agent talks to GitHub directly, the token is your only control, and it is a blunt one. Route calls through a gateway and a refusal becomes possible per call, with a reason, recorded.
• Writes that land somewhere first. Reading a repository is recoverable. Pushing, merging and closing are less so. A staging step turns an agent's write into a proposal that something approves, which is the difference between an agent that helps and an agent that has commit rights.

And log at the gateway, not in the agent. A trace the agent writes about itself is a statement by the party under review. It is usually accurate and it is never evidence.

What should you never do?

• Never put the credential in the agent's context. If it is in the prompt it is in the logs, the traces and the model provider's request history. Mint a short-lived key instead and keep the real one in a vault.
• Never use a shared bot account with a classic PAT. It is the worst combination available: broad reach, no expiry, and an identity nobody owns.
• Never grant admin or org-level permissions for convenience. They are requested when something fails for an unrelated reason, and they are never removed.
• Never let one person's grant silently serve everyone. If a colleague authorises an integration and every agent on the project inherits their access, nobody consented to that, and you will discover it during an incident.

How Cognibl handles it

Two different things, deliberately kept apart.

Tools are personal. A tool connection belongs to the person who authorised it, and an agent inherits the tools of whoever minted its key. Your agent reaches what you granted and nothing else, and a colleague's grants are unreachable rather than merely hidden.

Version control belongs to the project. A repository is a fact about the project, not about whoever happened to connect it, so it is authenticated by a credential the project holds, encrypted at rest and never readable back. Today that is a fine-grained PAT, stored behind a credential-kind field so an App installation is an addition rather than a migration.

Around both: the agent gets a short-lived scoped key rather than your credentials, calls it cannot make are refused and recorded, and write-type tools land in staging instead of in your repository.