Permissions + Roles

Story

Building-a-house world — same site and crew as every Phase 0 lesson.

Every person who shows up at your construction site wears an ID badge. The badge tells the gate guard exactly what that person is allowed to do.

• A visitor can walk around and look. They can't touch a tool.
• A laborer can move materials, clean up, carry things — but can't lay bricks.
• A tradesperson can actually build: frame walls, tile the floor, run the wiring. They have the skills and the permission to do real work.
• The foreman runs the daily site: assigns jobs, orders supplies, signs off on work — but can't demolish a load-bearing wall without the owner's say-so.
• The owner has the master key. Can restructure the whole house, fire everyone, or demolish it entirely. No one else gets that.

Now imagine your crew includes a robot worker. It's capable — it can tile, wire, build. But you'd never hand it the owner's master key. You'd give it a tradesperson badge. It can do the work. It cannot demolish the house.

GitHub roles are those ID badges + job ranks.

The five repository roles

In a GitHub organization, a repo can grant five roles, smallest to largest. The "Recommended for" descriptions below are verbatim from the GitHub docs:

Each role includes everything the smaller ones can do, plus more. Read can't push code. Write can push and merge PRs. Admin can delete the repo, change branch protection rules, and manage security settings.

source: docs.github.com — Repository roles for an organization · fetched 2026-05-28

The golden rule — least privilege. The docs: "Choose the role that best fits each person or team's function in your project without giving people more access to the project than they need."

Which role for an AI agent? — a concrete example

Give the robot worker a tradesperson badge (Write), never the owner's keys (Admin). Here is what that split looks like:

Combined with branch protection (lesson 0.9), even a Write-level agent still can't merge to main without a human review — the building code stops it at the gate regardless of its badge.

Fine-grained PATs vs GitHub Apps — a quick teaser

Two ways an agent (or a script) can authenticate to GitHub. They are not the same thing.

Fine-grained Personal Access Token (fine-grained PAT)

• A token tied to your GitHub account, but scoped down.
• "Each token can be further limited to only access specific repositories."
• "Each token is granted specific, fine-grained permissions, which offer more control than the scopes granted to personal access tokens (classic)."
• GitHub recommends fine-grained PATs over classic PATs whenever possible.
• Still acts as you — if your account is compromised, the token is too.

source: docs.github.com — Managing your personal access tokens · fetched 2026-05-28

GitHub App

• Its own identity — separate from any human account.
• "GitHub Apps can also act independently of a user."
• "They come with built-in webhooks and narrow, specific permissions."
• "GitHub Apps can be installed… and granted access to specific repositories."
• If the App is compromised, only what it was scoped to is at risk — not your whole account.

source: docs.github.com — About creating GitHub Apps · fetched 2026-05-28

Why this matters for GH-600

This is the guardrail you set before the agent ever runs. Three layers, not one:

1. Give Write, not Admin. The robot worker gets the tradesperson badge. It can push branches and open PRs — it cannot delete the repo or change security settings.
2. Scope the App to only the repos it needs. An agent working on one service doesn't need access to your entire org.
3. Layer it with branch protection (0.9). Even with Write, the agent can't merge to main unreviewed. The building code + the badge work together.

When the exam asks "how do you limit the blast radius of an autonomous agent?" the answer is: least-privilege role (Write, not Admin) + scoped identity (GitHub App) + branch protection.

Check-in — three quick questions

Open-ended. Think first, then peek at the suggested answer.

1. Your team hires a contractor who only needs to fix bugs and open pull requests — no deleting repos, no changing settings. Which role do you give them, and why not the one above it?

   Suggested answer

   Write — it lets them push commits and open PRs, which is all the job needs. The role above it, Maintain, adds the ability to manage repo settings and sign off on certain admin actions — access the contractor doesn't need and shouldn't have. Giving more than needed increases blast radius if their account is ever compromised.

2. You're setting up an AI agent to triage issues and label them, but it should never push code. Which role fits? Walk me through your reasoning.

   Suggested answer

   Triage — it lets the agent manage issues, discussions, and pull requests (apply labels, close/reopen, assign) without any write access to the codebase. Write would be more than needed and would let the agent push commits — a capability it has no business having for a labeling job. Triage is the smallest badge that covers the job.

3. What's the key difference between using a fine-grained PAT and a GitHub App for an agent? Why does GitHub recommend Apps for production agents?

   Suggested answer

   A fine-grained PAT is still tied to your personal account — it acts as you, just with some permissions trimmed. If your account is compromised, the token is too. A GitHub App has its own separate identity, its own narrow permissions, and its own audit trail. If the App is compromised, only what it was scoped to is at risk — not your whole account or org. For a production agent doing real work across repos, that isolation is critical.

Mentor marks this lesson verified after you compare answers and say "got it" in chat.