GitHub Security and Access Management: 2FA, Passkeys, Roles and Branch Protection (GH-900)

Two-factor authentication (2FA) secures a GitHub account by asking for a second proof of identity after the password, so a stolen password alone is not enough to sign in. You set it up under Settings › Password and authentication.

GitHub supports these second factors:

• Authenticator app (TOTP): a time-based one-time code from an app on your phone or computer. This is the recommended starting method.
• SMS: a code sent by text message. It works, but it is the weakest option and is not offered in every country.
• Security keys: FIDO2/WebAuthn hardware keys or built-in authenticators, used with a touch, PIN or biometric.
• GitHub Mobile: approve the sign-in in the GitHub app on a phone you have signed in on.
• Passkeys: covered in the next section; they replace the password and the second factor together.

Other credentials are not second factors. An SSH key authenticates Git operations, and a personal access token authenticates Git over HTTPS and API calls; neither completes a web sign-in. The verification code GitHub emails when you sign in from an unrecognised device is a check for accounts without 2FA, not a 2FA method you can choose.

Recovery codes and recovery methods

When you enable 2FA, GitHub has you download recovery codes. Each code can be used once to finish signing in when your second factor is unavailable, for example after losing the phone that holds your authenticator app. Store them somewhere safe and separate from that device, and add more than one method (a security key or GitHub Mobile as well as the app). A password reset does not remove 2FA, and GitHub Support cannot switch off 2FA or restore access for you without a recovery factor. The last resort is an account recovery request: you prove ownership with a verified device, an SSH key or a personal access token, and GitHub Support reviews the request, which can take a few business days. An account with no working factor, no recovery codes and none of those recovery factors can be lost permanently.

A passkey is a passwordless credential: a public/private key pair held by an authenticator (a laptop, phone, password manager or hardware key) and unlocked with a fingerprint, face, PIN or device password. Signing in with a passkey satisfies both the password step and the 2FA step in one action.

Passkeys are phishing-resistant because each one is bound to the website's domain: the browser will not offer a GitHub passkey to a lookalike site at a different address. Codes from an authenticator app or SMS, by contrast, can be typed into a fake page and relayed to the real one.

GitHub does not sync passkeys itself; syncing (or not) depends on the authenticator that stores the passkey. If you already registered a security key for 2FA, GitHub may offer to upgrade an eligible security key to a passkey so it can also replace your password.

Organization owners can require two-factor authentication for everyone who works in the organization: members, outside collaborators and billing managers. Turning the requirement on treats people without 2FA differently by role:

Owners can also select Only allow secure two-factor methods. With this option, passkeys, security keys, authenticator apps and GitHub Mobile are accepted, but SMS is not: a member whose only second factor is SMS (or who still has SMS configured) is blocked from the organization's resources until they switch to a secure method. Enterprise owners can enforce the same requirement across all of an enterprise's organizations.

Repositories owned by an organization offer five built-in roles, each adding to the one before it. Pick the lowest role that covers the job (least privilege).

The line between Maintain and Admin is a common source of confusion: protecting a branch counts as a sensitive action, so a Maintain user cannot create or change branch protection rules or rulesets. Organization owners have admin access to every repository in the organization. Enterprise Cloud organizations can also define custom repository roles that start from one of these and add specific permissions.

Repositories owned by a personal account

A repository in a personal account has only two levels: the owner and collaborators. Collaborators can push, manage issues and pull requests and more, but only the owner can invite collaborators, change visibility or delete the repository. There is no Triage or read-only collaborator role on a private personal repository. When you need finer roles, create the repository in an organization or transfer it to one.

Organization roles decide what a person can do across the whole organization, separately from their role on any single repository.

Outside collaborators suit contractors and consultants who need one or two repositories for a limited time. Organizations on Enterprise Cloud can also create custom organization roles that bundle selected organization permissions.

Base permissions

The base permission, set by owners under Settings › Member privileges, is the default access every member has to all of the organization's repositories, including repositories created later. The options are No permission, Read, Write and Admin. It is a floor, not a ceiling: if a member gets higher access to a particular repository (directly or through a team), the higher level applies there. Base permissions never apply to outside collaborators. Granting the same access team by team has to be repeated for every new repository, which is the practical difference from a base permission.

A team is a group of organization members that you can grant repository access to, @mention, and request reviews from as one unit. Teams belong to a single organization and contain members only; outside collaborators cannot be added to them.

• Visible teams can be seen and @mentioned by every member of the organization.
• Secret teams are visible only to their own members and to organization owners, which suits confidential work.
• Nested teams: a team can have one parent and several child teams. Child teams inherit the parent's repository access, and mentioning a parent also notifies the members of its children. Secret teams cannot be nested: they can have neither a parent nor children.
• Team maintainers can change the team's name, description and visibility, add and remove organization members, and manage team review settings, all without being organization owners.

Because a secret team cannot sit under a parent, hiding a team and giving it inherited access are mutually exclusive: a secret team gets repository access only through direct grants.

A repository's visibility decides who can see it at all, before any role applies.

Internal visibility supports InnerSource: code shared across every organization in a company without being public. A private repository cannot do the same job, because its base permission covers only its own organization and teams from other organizations cannot be added to it.

Changing visibility

Changing a public repository to private controls who sees it from now on, but cannot recall copies already made: stars and watchers are erased, and existing public forks stay public and are detached into a separate network. People with explicit access keep it, and the commit history is unchanged. On GitHub Free, a published GitHub Pages site is unpublished. Only repository admins (or owners) can change visibility, and organization owners can restrict this to owners.

Restricting repository creation

Under Member privileges, owners choose whether members can create repositories and of which visibility, for example private only, so members cannot accidentally publish sensitive code. Owners can always create any type. Base permissions, branch protection and rulesets act on repositories that already exist, so they do not control this.

A branch protection rule enforces how changes reach an important branch, such as main. Repository admins create rules under Settings › Branches, matching a branch name or pattern. Protected branches are available in public repositories on GitHub Free and in public and private repositories on GitHub Pro, Team and Enterprise Cloud.

A rule can require:

• a pull request before merging, with a number of approving reviews (and optionally review from code owners, or dismissal of stale approvals);
• status checks, such as a CI build, to pass;
• conversation resolution before merging;
• signed commits or a linear history;
• a locked (read-only) branch, or restrictions on who can push.

Two defaults matter. First, once a rule matches a branch, force pushes and branch deletion are blocked even though you did not select anything for them; you can choose to allow them. Every other requirement, such as status checks or signed commits, is off until selected. Second, administrators bypass the rule by default. To make the rule bind admins too, enable Do not allow bypassing the above settings. Only one branch protection rule applies to a given branch. A CODEOWNERS file only requests reviews from owners; it enforces nothing unless a rule requires code owner review.

A ruleset is a named collection of rules for branches or tags in a repository, offered alongside branch protection. Rulesets cover the same kinds of rules but work differently:

Because rules aggregate to the most restrictive, a second, looser ruleset can never relax a stricter one. To exempt a release bot, add it to the bypass list; giving it more repository permission does not exempt it. Creating and editing rulesets, like branch protection, requires the Admin role.

Enterprise Managed Users (EMU) is a type of GitHub Enterprise Cloud enterprise in which the company's identity provider (IdP) creates and controls every user account. The IdP provisions accounts through SCIM, sets their usernames, profile data and email, controls organization and team membership, and handles sign-in through SAML or OIDC. Deactivating someone in the IdP removes their GitHub access.

The trade-off is isolation. Managed user accounts can only create private or internal content inside the enterprise. Outside it they can view public repositories, but cannot push, open issues or pull requests, comment, react, star, watch or fork, and cannot create public repositories or create gists of any visibility. A developer who also contributes to open source needs a separate personal account.

Organization-wide Copilot policy management

For Copilot Business and Copilot Enterprise, organization owners decide which members receive a Copilot seat and set the organization's Copilot policies (which features, models and settings are allowed). Repository admins and billing managers do not control these. In an enterprise, enterprise owners set each policy first: they can enable or disable it for every organization, or choose to let organizations decide, which hands that choice to each organization's owners. When a user receives Copilot from organizations with different settings, GitHub generally applies the least restrictive setting. Choosing between Copilot plans and features is covered in the GH-900 lesson on GitHub Actions, Copilot and Codespaces; account types are covered in the accounts lesson.