Design a repository ruleset: protections, required checks, and exceptions.
- User
Design a repository ruleset: protections, required checks, and exceptions.
Assistant
I need to design a "repository ruleset" that covers protections, required checks, and exceptions. This is likely for a version control system like GitHub (Repository Rulesets) or GitLab (Push Rules/Protected Branches), but GitHub's specific feature "Repository Rulesets" is the most direct match for the terminology used.
1. Understand the Goal: The user wants a design for a set of rules governing a repository. This isn't just a list of settings; it needs to be a cohesive policy that balances security, code quality, and developer velocity.
2. Target Audience & Context: * Audience: Engineering teams, DevOps, Platform Engineers. * Context: A production-grade repository (or a template for one) containing critical application code.
3. Key Components of a Ruleset: * Target: What does this apply to? (Branches like
main, tags, file paths). * Protections: What actions are restricted? (Force pushes, deletions). * Required Checks (CI/CD): What must pass before merging? (Tests, linters, security scans). * Exceptions (Bypass lists): Who can override these? (Admins, specific teams).4. Drafting the Scenarios (Tiered Approach): It's best to provide a few different "flavors" of rulesets because a startup's needs differ from a bank's. * Scenario A: Standard Production (The "Happy Medium") - High security, decent velocity. * Scenario B: Strict Compliance (High Security) - Sarbanes-Oxley (SOX), HIPAA, etc. * Scenario C: Trunk-Based Development (High Velocity) - Very permissive for short-lived branches, strict for main.
*Decision:* I will focus on a **"Standard Enterprise Production"** model as the primary design, as it's the most useful generic template, but I will structure it modularly so parts can be swapped out.5. Structuring the Design: I'll structure the response into logical sections: * Metadata: Name, Target (Branches/Tags). * Branch Protections: The "Hard" blocks. * Merge Requirements: The "Soft" gates (reviews, CI). * CI/CD Checks: Specific workflows that must pass. * Bypass Permissions: Who is above the law. * Rationale: Why these choices?
6. Fleshing out specific rules (The "Meat"):
* *Protections:* * Restrict deletion? Yes. * Restrict force push? YES. (Essential). * Restrict matching? (e.g., allow force push on `feature/*` but not `main`). *Wait, GitHub Rulesets are usually applied to a specific pattern. Let's design a Ruleset targeting `main`.* * *Required Checks:* * Status checks must pass? Yes. * Status checks must be up to date? Yes (strict). This prevents " merge skew". * Code owners? Yes (for critical paths). * *Reviews:* * Approvals? 1 or 2. Let's suggest 1 for standard, 2 for critical. * Dismiss stale reviews? Yes. * Require review from Code Owners? Yes. * *Exceptions:* * Usually "Repository Admins" or a "Release Engineering" team.7. Refining the "Design" (Adding context and best practices): A list of checkboxes isn't a design. I need to explain how this works in a workflow. * Workflow integration: How do developers interact with this? (PRs/Merge Requests). * The "Emergency" Valve: How to handle hotfixes (Bypass).
8. Drafting the content (Iterative refinement):
* *Name:* "Main Branch Protection". * *Enforcement:* Active. * *Target:* `main`, `master`. * *Rules:* * **Block:** Force pushes, Deletion. * **Pull Request:** * Require PR. * Require review (1 approval). * Dismiss stale reviews. * Require Code Owners (specific directories). * **Status Checks:** * `ci/build`, `ci/unit-tests`, `security/sast`. * Require branches to be up-to-date.9. Adding Nuance (Exceptions & Overrides): This is crucial. Real-world systems break. * Bypass List: "Platform Admins" or "On-Call Engineers". * Exception Logic: "Do not allow specific actors to bypass pull request requirements" (e.g., even admins shouldn't self-merge without CI). Actually, usually admins bypass everything in GitHub Rulesets. I need to clarify that "Bypass" is a specific permission.
10. Formatting for Readability: Use Markdown tables, bold text for emphasis, and clear headers.
11. Review against the Prompt: * Protections? Included. * Required Checks? Included. * Exceptions? Included.
12. Final Polish: I will create a scenario-based design (e.g., "The 'Fort Knox' Production Ruleset") to make it concrete. I'll also include a section on "File Path Specifics" (Code Owners) because that's a common advanced requirement.
(Self-Correction during drafting): GitHub Rulesets are the most likely context. I should use terminology compatible with that (e.g., "Bypass list", "Target branches"). I will mention that this applies to GitHub but the concepts transfer to GitLab/Bitbucket.
Detailed Plan:
- Overview: Define the philosophy (Shift Left + Stability).
- Scope: Which branches/tags.
- The Ruleset Configuration:
- Branch Rules (Deletion, Force Push).
- Merge Rules (Approvals, Staleness).
- Required Checks (CI/CD, Security).
- Exceptions & Bypass: Who and When.
- Implementation Guide: How to roll this out safely.
Let's write it out. Designing a repository ruleset requires balancing stability (protecting the codebase) with developer velocity (not blocking developers with red tape).
Below is a comprehensive design for a Production-Grade Repository Ruleset, structured for a standard Git workflow (using GitHub’s Rulesets or GitLab’s Push Rules as a conceptual model).
1. Overview & Scope
Objective: Protect the
mainbranch (and release branches) while allowing flexible development on feature branches.Target:
- Branches:
main,master,v*(release branches) - Repository State: Non-archived
2. Protections (The "Hard" Blocks)
These are non-negotiable security and integrity rules.
Rule Name Setting Rationale Restrict Deletion EnabledPrevents the branch from being accidentally or maliciously deleted. Force Push BlockCritical. Prevents overwriting commit history, which ensures audit trails and prevents code loss. Linear History Enabled(Optional)Requires merge commits to be fast-forwarded or rebased. Keeps history clean. Code Owners EnabledRequires approval from specific teams for defined file paths (e.g., DBAmust approveschema.sql).
3. Required Checks (The Quality Gates)
These conditions must be met before a merge (Pull Request) is allowed to proceed.
A. Review Requirements
- Required Reviewers: Minimum 1 approval.
- Strict Recommendation: Require 2 approvals if the repository is critical infrastructure.
- Dismiss Stale Reviews:
Enabled.- Logic: If a new commit is pushed to the PR, all previous approvals are reset to prevent "approval drift."
- Require Conversation Resolution:
Enabled.- Logic: All "Comments" (not just blocking reviews) must be marked as resolved.
B. CI/CD Status Checks
The following status checks must return a "Success" (Green) status:
ci/build: Confirms the application compiles without errors.ci/test-unit: Runs the unit test suite.ci/lint: Enforces code style and formatting standards.security/sast: (e.g., SonarQube, CodeQL) Static analysis for vulnerabilities.security/secrets-scan: (e.g., TruffleHog, Gitleaks) Prevents API keys from being committed.
4. Exceptions (The Bypass List)
You must define who is allowed to break the rules in emergency situations (e.g., a production outage requiring a hotfix).
The "Break Glass" List
These users/roles can bypass the Pull Request and Check requirements:
- Repository Role:
MaintainorAdmin. - Specific Team:
platform-on-call(For emergency hotfixes). - Deployment Bots:
deployment-service-account(Only if automated deployment merges are required).
Note: Even if a user is on the bypass list, they usually cannot force push or delete protected branches unless they are specifically exempted in the "Target" configuration.
5. Implementation Strategy (File Path Rules)
A sophisticated ruleset applies different weights to different parts of the codebase.
Scenario: You want to change a typo in the
README.mdbut don't want to wait for a CI build.Configuration:
- Rule: "Require status checks to pass before merging"
- Exception: Create a rule that allows merging if files changed only match:
*.mddocs/*.github/ISSUE_TEMPLATE/*
6. Summary Configuration Template
If configuring this via a UI or YAML definition, it would look like this:
ruleset_name: "Default Production Protection" target: - branch: "main" - branch: "release/*" enforcement: "Active" rules: - type: "PUSH" allow_force_pushes: false allow_deletions: false - type: "PULL_REQUEST" required_approving_review_count: 1 dismiss_stale_reviews: true require_code_owner_review: true required_status_checks: - "ci/build" - "ci/test" - "security/scan" bypass_actors: - role: "REPO_ADMIN" mode: "PULL_REQUEST" # Can merge without approval, but cannot force push - team: "engineering-managers" mode: "PULL_REQUEST"
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.