Collaborators, permissions, visibility
Beginner GitHub UI
Why this matters
"I can't push" and "I can't see it" are the two most common blockers for someone new to a team, and both are one sentence to fix if you know the vocabulary. Roles are also the reason a merge button is greyed out, which is worth understanding before assuming something is broken.
The five roles
| Role | Adds |
|---|---|
| Read | Clone and pull, open issues and pull requests, comment, view rulesets |
| Triage | Label, assign, close and reopen issues and pull requests, mark duplicates; still cannot push |
| Write | Push branches, merge pull requests, create releases, manage Actions runs |
| Maintain | Edit the repository description and topics, push to protected branches, manage some settings |
| Admin | Manage rulesets, collaborators and teams, security features, transfer or delete the repository |
Two boundaries are worth memorising because they surprise people:
- Write is the contributor role. Pushing a branch, opening a pull request and merging one all sit here. A writer, tester or analyst who contributes changes needs Write, not Admin.
- Maintain is not Admin. Maintain can push to protected branches but cannot manage branch protection or rulesets, manage collaborators, or delete the repository. Those are Admin only.
Enterprise organizations can define custom roles built on one of these, so a real organization may show a name that is not in the table. It still inherits from one of the five.
Asking for access
Say what you need to do, not which button you want:
"I'm documenting the installation guide. Could I have Write on
trailguide, ideally through thedocsteam? I don't need to push tomain; a branch and a pull request is all I need."
That sentence gets a fast yes because it names a role, a reason, a route and a limit. Compare with "can you give me admin", which gets a slow no.
If Write is refused, the fork route works with Read alone: fork, push to your fork, open a pull request from it (lesson 7.7). That is how open-source contribution works and it is a perfectly good answer.
Visibility
| Visibility | Who can see it |
|---|---|
| Public | Anyone on the internet, signed in or not |
| Private | Only people and teams given access |
| Internal | Every member of the enterprise, but nobody outside; enterprise accounts only |
Changing visibility is an Admin action with consequences worth knowing: making a repository private removes existing forks from public view but does not delete them, and making one public exposes its whole history, including anything committed and later removed (lesson 8.7).
Where access comes from
Four routes into one repository, and it is worth knowing which one is yours:
- Organization owner, who has Admin everywhere.
- A team's role, the usual route in a healthy organization.
- A direct collaborator, added to that repository alone.
- Base permissions, an organization-wide default role every member has on every repository.
When routes disagree, the most permissive wins, which is why an organization's base permission set to Write is a bigger decision than it looks.
How to do it
Git tells you what you have the moment you try to use it:
remote: Permission to northwind-trails/trailguide.git denied to chloe.
fatal: unable to access 'https://github.com/northwind-trails/trailguide.git/': The requested URL returned error: 403That is a permissions answer, not an authentication one: you signed in successfully and were told no. A Repository not found message on a repository you know exists usually means the opposite, that your credentials are wrong or the repository is private and invisible to you (lesson 8.4).
Nothing in VS Code shows your role. What it shows is the failure: a push that returns 403 opens an error notification with the same text as the terminal.
Same: the Git tool window shows the push rejection with GitHub's message. The Pull Requests window will list pull requests you can read even when you cannot push.
GitLab's ladder is Guest, Planner, Reporter, Developer, Maintainer, Owner, and its visibility levels are Private, Internal and Public. Developer is the equivalent of Write; Maintainer is closer to GitHub's Admin than to Maintain. See lesson 9.3 and the terminology map.
- Settings → Collaborators and teams lists everyone with access and their role; it is Admin-only, so if you cannot open it, you are not an Admin.
- Add people or Add teams grants a role; prefer the team.
- Settings → General → Danger Zone holds Change repository visibility, Transfer and Delete.
- Organization-wide defaults are at organization Settings → Member privileges → Base permissions.
- Anyone with Read can see the rules that apply to a branch under Settings → Rules → Rulesets, or on the branch itself.
Common mistakes
- Asking for Admin when Write is what the work needs. It slows the request and widens the blast radius.
- Assuming Maintain can change branch protection. It cannot; that is Admin.
- Adding people directly to repositories instead of to teams, so access is invisible in aggregate.
- Treating private as secret. Everyone with Read has the entire history.
- Making a repository public without an audit of what is in its history.
Try it yourself
Goal: know your own access and practise asking for the right thing.
- On a repository you contribute to, work out your role: try Settings (Admin only), look for the Edit pencil on a file, and check whether Merge appears on a pull request.
- Write the one-sentence access request from this lesson for a repository where you would need more, naming the role, the reason and the limit.
- On your own practice repository, invite a second account (or a colleague) as Read, then change it to Write, and watch what appears for them.
- Look at Settings → Rules and note that a Read user can see the rules but not change them.
Expected result: you can name your role from what the interface offers you, and you have a request written in terms of work rather than buttons.
Show solution
Step 1 works because the interface is the permission model made visible: Settings means Admin, an Edit pencil means Write or better, a Merge button on a protected branch means the rules allow you. This is faster than asking, and it is how you diagnose "why can't I do this" without a ticket.