GitHub repository governance: rules and access
Once more than a few people push to a repository, you need answers to some basic questions. Who may push to main? Which changes need which reviewers? What should a pull request description contain? Who has write access, and why? GitHub answers them with five features that work together: rulesets (and the older branch protection rules), branch name restrictions, CODEOWNERS, issue and pull request templates, and organization teams with repository roles.
This page covers each feature with the settings that matter and a realistic configuration for an invented OrdersPortal repository in an invented orders-portal organization. Facts and availability were checked against the GitHub Docs source in November 2026. Configuration files are fragments to commit to your repository; the ruleset JSON matches the GitHub REST API schema but was not sent to a live repository here.
Topics on this page
Section titled “Topics on this page”| Topic | Answers |
|---|---|
| Rulesets and branch protection | Who can push, merge, force push or delete on important branches. |
| Branch naming rules | How to reject branches that do not follow the convention. |
| Code owners | Who must review changes to which paths. |
| Pull request and issue templates | What contributors are asked for when they open a pull request or issue. |
| Teams and permissions | How people get the right level of access. |
Rulesets and branch protection
Section titled “Rulesets and branch protection”A ruleset is a named list of rules that targets branches or tags by name pattern. Typical rules are Restrict deletions (on by default), Block force pushes (on by default), Require a pull request before merging (with a required number of approvals, dismissal of stale approvals, approval of the most recent push by someone else, required conversation resolution and code owner review), Require status checks to pass, Require linear history, Require signed commits and Require merge queue. Each ruleset has an enforcement status (Active or Disabled; Enterprise plans add Evaluate, which only reports what would have been blocked) and a bypass list of roles, teams or GitHub Apps.
Several rulesets can apply to the same branch; their rules are aggregated and the most restrictive version of each rule wins. Anyone with read access can see the active rulesets, which helps developers understand why a push was rejected. Classic branch protection rules (Settings > Branches) still work and are layered with rulesets, but only one protection rule applies per branch, so new setups should prefer rulesets. Rulesets and protected branches are available for public repositories on GitHub Free and for public and private repositories on Pro, Team and Enterprise Cloud; rulesets that target many repositories at organization level need a Team or Enterprise plan (up to 75 rulesets per repository and 75 organization-wide).
The ruleset for OrdersPortal’s default branch, in the JSON format used by ruleset import/export and the REST API (POST /repos/{owner}/{repo}/rulesets):
{ "name": "main protection", "target": "branch", "enforcement": "active", "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } }, "rules": [ { "type": "deletion" }, { "type": "non_fast_forward" }, { "type": "pull_request", "parameters": { "required_approving_review_count": 1, "dismiss_stale_reviews_on_push": true, "require_code_owner_review": true, "require_last_push_approval": true, "required_review_thread_resolution": true } }, { "type": "required_status_checks", "parameters": { "strict_required_status_checks_policy": true, "required_status_checks": [{ "context": "build-and-test" }] } } ], "bypass_actors": []}Pitfalls:
- An empty bypass list means nobody, including admins. That is usually what you want for
main, but plan how emergency fixes get merged (a second approver on call, not a bypass). - Status check names must match exactly. The
contextis the job name the check reports; renaming the CI job silently blocks every merge until the ruleset is updated. - Branch patterns use
fnmatch.*does not cross/, sorelease/*matchesrelease/2.4but notrelease/2.4/hotfix; userelease/**/*for nested names.
Branch naming rules
Section titled “Branch naming rules”A branch protection rule with the pattern feature/* does not enforce naming: it protects branches that already match and ignores everything else. To reject badly named branches you need a rule about creation. There are two ways.
On any plan with rulesets, create a ruleset that targets all branches (~ALL), excludes the allowed patterns and the default branch, and enables Restrict creations. Only bypass actors can create a branch whose name matches the targets, which here means “any name that is not on the allowed list”:
{ "name": "branch naming", "target": "branch", "enforcement": "active", "conditions": { "ref_name": { "include": ["~ALL"], "exclude": ["~DEFAULT_BRANCH", "refs/heads/feature/**/*", "refs/heads/fix/**/*", "refs/heads/release/**/*", "refs/heads/dependabot/**/*"] } }, "rules": [{ "type": "creation" }], "bypass_actors": []}On GitHub Enterprise plans, metadata restrictions add a branch name rule (branch_name_pattern) that accepts starts_with, ends_with, contains or a regular expression, for example ^(feature|fix|release)/[A-Z]+-[0-9]+ to require an issue key. The same family of rules can require commit message formats such as Conventional Commits; GitHub recommends applying metadata rules to a few branches such as main rather than to every topic branch.
Pitfalls:
- Bots create branches too. Dependabot, release tooling and the Copilot cloud agent use their own prefixes; exclude them or add the apps as bypass actors.
- Existing branches are not renamed. Rules apply to new refs; clean up old branches separately.
- Document the convention. Put the allowed patterns in
CONTRIBUTING.mdso the rejection message is not the first time people see them.
Code owners
Section titled “Code owners”A CODEOWNERS file maps path patterns to the users or teams responsible for them. GitHub automatically requests a review from the owners when a pull request changes their files, and with Require review from Code Owners in a ruleset or branch protection rule, the pull request cannot merge until one of the owners approves. The file can live in .github/, the repository root or docs/; GitHub uses the first one it finds in that order. It must be under 3 MB.
The syntax follows most .gitignore rules. Each line is a pattern followed by one or more @username or @org/team-name owners (email addresses work for users). The last matching pattern wins, so put broad rules first and specific ones after. Owners must have write access, and teams must be visible.
# .github/CODEOWNERS for OrdersPortal
# Default owners for everything not matched below* @orders-portal/maintainers
# Payment and authentication code needs specialist review/src/payments/ @orders-portal/payments/src/auth/ @orders-portal/security
# Docs: writers own Markdown anywhere under docs//docs/**/*.md @orders-portal/tech-writers
# Protect governance files themselves/.github/ @orders-portal/platformPitfalls:
- Any one owner is enough. If a line lists two owners, an approval from either satisfies the requirement. If you need two specific approvals, use separate rules or the required reviewers rule in rulesets.
- Unprotected CODEOWNERS files can be edited away. Own
/.github/(or the file itself) with a trusted team so nobody can remove an owner in the same pull request. - Invalid entries are skipped. A misspelled team or a team without write access silently stops requesting reviews; GitHub shows errors in the file view.
Pull request and issue templates
Section titled “Pull request and issue templates”Templates prefill the description so contributors include what reviewers need. A single pull request template goes in .github/pull_request_template.md (the root and docs/ also work). Multiple templates go in .github/PULL_REQUEST_TEMPLATE/ and are selected with the template query parameter in the compare URL. Templates must be on the default branch.
## SummaryWhat changed and why. Link the issue: Closes #123
## How to test- [ ] `npm test`- [ ] Manual check:
## Risk- [ ] Database migration- [ ] Changes to payments or auth (CODEOWNERS review required)Issue templates live in .github/ISSUE_TEMPLATE/. Markdown templates use YAML front matter for name and labels; issue forms are YAML files that render real form fields with validation. A config.yml in the same folder controls the chooser: blank_issues_enabled: false hides the blank issue option from contributors with Read or Triage access, and contact_links send people elsewhere, such as a support portal.
name: Bug reportdescription: Something in OrdersPortal does not work as expectedlabels: ["bug", "needs-triage"]body: - type: input id: order-id attributes: label: Order ID placeholder: ORD-100234 - type: textarea id: what-happened attributes: label: What happened, and what did you expect? validations: required: true - type: dropdown id: environment attributes: label: Environment options: [Production, Staging, Local] validations: required: truePitfalls:
- Templates are suggestions. Contributors can delete the text. If a field matters (an order ID, a risk checkbox), use an issue form with
required: trueor check the description in CI. - Organization defaults. A
.githubrepository in the organization provides default templates and community health files for repositories that have none.
Teams and permissions
Section titled “Teams and permissions”Organization access works in layers. Organization roles (owner, member, moderator, billing manager, security manager, plus custom roles on Enterprise) control the organization itself. Base permissions set a default repository role for every member. Repository roles grant access to a specific repository; from least to most: Read, Triage, Moderate, Write, Maintain and Admin. Maintain is for project managers who manage the repository without sensitive or destructive actions; Admin includes security settings and deleting the repository. Enterprise Cloud adds custom repository roles.
Teams group members so you grant access once per team instead of per person. Teams can be visible or secret, can be @mentioned and requested as reviewers, and can be nested: a child team inherits its parent’s repository access, so put broad, safe access high in the tree and sensitive access on narrow child teams (secret teams cannot be nested). With team synchronization, membership can follow your identity provider’s groups.
A sensible OrdersPortal layout:
| Team | Repository role | Why |
|---|---|---|
@orders-portal/engineering (parent) |
Read on all repositories | Everyone can read and review |
@orders-portal/orders-team (child) |
Write on orders-portal |
Day-to-day development |
@orders-portal/maintainers |
Maintain on orders-portal |
Settings, labels, releases |
@orders-portal/platform |
Admin on orders-portal |
Rulesets, secrets, integrations |
| Support staff | Triage | Label and close issues without code access |
Pitfalls:
- Individual grants pile up. People change teams but keep direct access. Grant through teams and review access (and outside collaborators) regularly using the organization’s people and audit log views.
- Admin is broader than it looks. Repository admins can change rulesets and bypass lists; keep that role to a small platform team.
- Base permission “Write” defeats the model. Keep base permissions at Read or No permission and grant more through teams.
Choosing between them
Section titled “Choosing between them”| Goal | Feature |
|---|---|
Nobody pushes straight to main |
Ruleset with pull request and status check rules |
| Expert review for sensitive paths | CODEOWNERS plus “Require review from Code Owners” |
| Consistent branch names | Ruleset with Restrict creations, or a branch name pattern on Enterprise |
| Useful pull request and issue descriptions | Templates and issue forms |
| Least-privilege access | Teams, repository roles and low base permissions |
Interview questions
Section titled “Interview questions”What is the difference between a ruleset and a branch protection rule? Both protect branches and both are enforced. Rulesets are named, can be layered (several can target one branch and the strictest rule wins), have enforcement states and bypass lists, are visible to anyone with read access, can target tags, and can be defined for many repositories at organization level on Team and Enterprise plans. Only one branch protection rule applies per branch.
How does GitHub decide which code owner applies to a file?
It reads the first CODEOWNERS file found in .github/, the root, then docs/, and uses the last pattern in the file that matches the path. Any one listed owner can approve.
How would you enforce a branch naming convention on GitHub? A ruleset targeting all branches, excluding the allowed patterns and the default branch, with Restrict creations, so only bypass actors can create non-conforming names. On Enterprise plans, a branch name metadata rule with a regular expression is more direct.
What is the difference between the Maintain and Admin repository roles? Maintain can manage the repository (settings such as issues, labels, branches) without sensitive or destructive actions. Admin adds security settings, access management and deleting or transferring the repository.
Senior scenario: an audit finds that several engineers pushed directly to main last quarter, and one CODEOWNERS entry pointed to a deleted team. How do you fix it for 40 repositories?
Move protection to an organization ruleset targeting the default branch of all repositories, with pull requests, code owner review and required checks, and an empty or tightly scoped bypass list; on Enterprise, start in Evaluate mode to find workflows that would break, then switch to Active. Own /.github/ in every repository with the platform team, add a CI check that validates CODEOWNERS entries, and move access to team-based grants so leavers and reorganizations do not leave stale owners. Report bypass usage from the audit log each month.
Related pages
Section titled “Related pages”- GitHub administration overview: where governance fits with Actions administration.
- GitHub Actions and automation: secrets, runners, packages and webhooks.
- Git branching strategies: conventions that these rules enforce.
- GitLab protected branches, approvals and code owners: the GitLab equivalents.
- Copilot best practices: governance for AI-assisted pull requests.