Repository permissions and roles

At the Thursday session on March 4, Rosa put a question on the boardroom screen that nobody could answer with confidence: "Who can change the TrailCheck website today?" The organization had grown over the winter. Some people had been added to repositories directly when something was urgent, a few teams had been given access, and the base permission had been changed once and changed back. The aim of the session was to understand exactly how GitHub decides what one person may do in one repository, and then to run Tidewater's first access review.

Permissions belong to repositories

An organization role, covered in lesson 1, says what someone can do to the organization as a whole. A repository role says what someone can do inside one repository: read it, comment on it, push to it, merge into it, change its settings. Repository roles are given to people in three ways: through the organization's base permission, which every member has on every repository; through teams that have been given access to the repository; and directly, to an individual member or an outside collaborator. GitHub combines these sources, and the person gets the highest level any of them gives.

The five repository roles

Organization repositories have five built-in roles, each including everything in the role below it.

Two of the roles are easy to confuse with their neighbors. Triage exists for people who look after the issue list but should not change content, such as a volunteer coordinator who sorts incoming reports. They can label, assign and close issues, but they cannot push a commit or create new labels. Maintain exists for someone who runs a repository day to day without holding the most sensitive powers: they can change the description, topics, merge settings and Pages settings, but they cannot change who has access, edit branch protection or rulesets, or delete the repository. Those remain with Admin.

How the sources combine

When a person has access to a repository from more than one source, GitHub gives them the highest of the levels, never the lowest and never a total. If the base permission is Read, a team gives Write and an individual grant gives Triage, the person has Write. Access cannot be reduced below the base permission by anything else: if the base permission were Write, there would be no way to make one member Read-only in one repository, short of removing them from the organization. That is one more reason to keep the base permission low.

Where to see and change access

A repository's Collaborators and teams page (under the Access section of its settings) lists every team and individual with access and the role each has, and lets an administrator add or remove them. A team's own page lists the repositories it can reach. An organization owner can open a member's page to see every repository the member can access and why, which is the quickest way to answer a question like Rosa's. People with read access can also see which rulesets apply to a branch, but only administrators see the full list of who has access.

When an organization member invites someone who is not yet in the organization to a repository, the person becomes an outside collaborator; organization owners can restrict who may do that. Tidewater allows only owners to add outside collaborators, so the partner publisher's editor was added by Rosa, to the style-guide repository only, with Write access.

Repositories in personal accounts

A repository owned by a personal account works more simply. It has one owner, the account holder, who has full control. The owner can invite collaborators, who can push, merge and manage issues, but there is only one collaborator level; the five roles exist only in organization repositories. Collaborators cannot change settings, add other collaborators or delete the repository. This is fine for a hobby project, but it is a weak fit for a company, because it offers no Triage or Maintain level, no teams and no organization-wide settings. Malik's original trail-report format began in his personal account, and lesson 12 follows its move into an organization.

Custom repository roles and fine-grained access

On GitHub Enterprise Cloud, organization owners can create custom repository roles that start from one of the built-in roles and add specific permissions, for example a role based on Triage that can also manage GitHub Pages settings, or one based on Write that can also manage webhooks. Custom roles are not available on the Free and Team plans, which Tidewater uses, so the team stays with the five built-in roles. It is still useful to know that they exist, because the GH-900 exam expects you to recognize the idea.

Access does not only come from people. Deploy keys are SSH keys attached to one repository, used by a server to pull or push without a person's account; they can be read-only or read-write. GitHub Apps receive their own fine-grained permissions when installed, which lesson 6 covers. Personal access tokens act on behalf of a person with whatever access that person has, limited by the token's scopes; GitHub recommends fine-grained personal access tokens, which can be limited to particular repositories and permissions and given an expiry date, and organizations can require approval before such tokens can reach their resources.

Visibility and roles are different questions

Visibility, covered in MSBA-160, answers who can see a repository; roles answer who can change it. The two interact in ways that surprise newcomers. In a public repository, anyone on the internet can read the code, open issues, comment and fork it, so the Read role adds little for ordinary visitors; the roles that matter are Triage and above. In a private repository, nobody without a role can see anything at all, so even Read is a real grant. In an internal repository, available in enterprises, every enterprise member gets Read automatically. Changing a repository from private to public therefore changes who can read it, but does not change who can push: the same roles still control writing.

Two further points come up in practice. First, archiving a repository makes it read-only for everyone, including administrators, until it is unarchived; it is the right way to retire a finished project without deleting its history. Second, roles do not stop someone from copying what they can already read. Anyone with Read on a repository can clone it, so a low role limits changes, not disclosure. When something must not be seen by a person, the answer is not to give them access to that repository at all, which is why Tidewater keeps the unpublished trail notes in a repository that the partner publisher's editor cannot reach.

The principle of least privilege

The idea that runs through every choice in this lesson is least privilege: each person or system gets the lowest access that lets them do their work, for as long as they need it. It limits the damage a mistake can do, it limits what an attacker gains from a stolen account, and it makes the question "who can change this?" easy to answer. In GitHub, least privilege looks like a low base permission, access through teams rather than individuals, Write instead of Admin for most contributors, outside collaborators instead of members for temporary helpers, read-only deploy keys where possible, and tokens with expiry dates.

Running an access review

An access review is a regular check that the access people have still matches what they need. Rosa scheduled one every three months and wrote down the steps so anyone could repeat them.

Owen pointed out the change in the answer to Rosa's first question. Before the review, the honest answer to "who can change the website?" was "nine people, one of whom can also change the protection rules." Afterward it was "the web team and Priya", which anyone could check on the team page.