Managing repositories at scale

Scenario overview

Adopting GitHub’s general platform best practices is crucial for effectively managing repositories at scale. Rulesets and custom properties are crucial to enforcing repository rules from your enterprise, organization, and repository entry points. These practices provide a structured framework that enforces repository compliance with branch, push, and tag rules at the organization and repository levels.

These practices provide a structured framework that ensures projects are secure,maintainable, and scalable. By fostering a collaborative and efficient environment, these guidelines help organizations avoid common pitfalls, maintain high-quality codebases, and streamline project workflows. Ultimately, adhering to these best practices leads to successful and sustainable software projects.

Key design strategies

Determine if repository rulesets will be managed at the organization or the repository level.
1. If managing at the repository level, consider which users will be managing the rulesets. To delegate beyond repository admins, consider creating custom roles with the Edit repository rules permission.
As a GitHub organization administrator review the following:
1. Consistency with your branch, tag, and push rulesets for the GitHub organization
2. Consult with your developer community to review repository rulesets for feedback, education, and implementation details
3. Delegated bypass for push rulesets lets you control who can bypass push protection and which blocked pushes should be allowed. For example:
  - Repository admins, organization owners, and enterprise owners
  - The Maintain or Write role, or custom repository roles that you have defined in your organization.
  - Specific organization teams
  - Deploy keys for the repository
  - GitHub Apps installed in your organization
Ruleset testing, history, and insights
1. Test rulesets using “Evaluate” mode before enforcing them
  1. This can be done at the organization or repository level depending on where the ruleset was added
2. Using ruleset history
  1. You can view all the changes to a ruleset and revert back to a specific iteration
  2. You can also download a JSON file containing the ruleset’s configuration at a specific iteration
  3. The bypass list of a ruleset is excluded from the exported JSON file
3. Viewing insights for rulesets
  1. You can use the “Rule Insights” page to see if the contribution would have violated the rule
Leverage pre-baked rulesets maintained by GitHub github/ruleset-recipes
1. branch-rulesets
2. tag-rulesets
3. push-rulesets
  Note: Only import rulesets from reliable sources
Search and review audit log events for repository_ruleset
Custom properties
1. Are managed and set at the organization level but can be set at the repository level.
2. Custom properties ensure “code” is secure/governed by default. With a default custom property and a ruleset attached you can make sure every repository going to production has reviews and required workflows. Or you can start every repo to a high security standard and let them back down after creation.
3. Organization settings
4. Repository settings
5. Types: text, single select, multi select, and true/false
  1. Popular use cases:
  - True/False - “Production”
  - Single Select - “Severity” or “Security Tier” (e.g. High, Medium, Low, None)
  - Multi-Select - “Compliance” (e.g. HiTrust, SOC2, ISO20071, FedRAMP)
  - Text - “Application ID”
6. “Type” text you can match regular expressions
7. “Allow repository actors to set this property”
  Repository users and apps with the repository level “custom properties” fine-grained permission can set and update the value for their repository.
8. “Require this property for all repositories”
  Repositories that don’t have an explicit value for this property will inherit the default value.

Best practices

1. Organization rulesets

2. Branch rulesets

3. Tag rulesets

Prevent Tag Deletions

4. Push rulesets

Keep it secret keep it safe

Assumptions and preconditions

Rulesets are available with one the following plans

Permissions

Rulesets

Anyone with read access to a repository can view the repository’s rulesets. People with admin access to a repository, or a custom role with the “edit repository rules” permission, can create, edit, and delete rulesets for a repository and view ruleset insights.

Custom properties

Organization owners and users with the “Manage the organization’s custom properties definitions” permission can add and set a custom property schema at the organization level.

Implementation Activities

Ruleset Implementation Checklist

1. Branch rulesets

2. Tag rulesets

3. Push rulesets

ℹ️

Organization owners and users with the “Manage organization ref update rules and rulesets” permission can manage rulesets at the organization level.
Anyone with read access to a repository can view the repository’s rulesets. People with admin access to a repository, or a custom role with the “edit repository rules” permission, can create, edit, and delete rulesets for a repository and view ruleset insights.
Organization rules and insights are only on the enterprise level.
Rulesets are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, and GitHub Enterprise Cloud.
Push rulesets are available for the GitHub Enterprise Cloud plan in internal and private repositories, forks of repositories that have push rulesets enabled, and organizations in your enterprise.

Seeking further assistance

GitHub Support

Visit the GitHub Support Portal for a comprehensive collection of articles, tutorials, and guides on using GitHub features and services.

Can’t find what you’re looking for? You can contact GitHub Support by opening a ticket.

GitHub Expert Services

GitHub’s Expert Services Team is here to help you architect, implement, and optimize a solution that meets your unique needs. Contact us to learn more about how we can help you.

GitHub Partners

GitHub partners with the world’s leading technology and service providers to help our customers achieve their end-to-end business objectives. Find a GitHub Partner that can help you with your specific needs here.

GitHub Community

Join the GitHub Community Forum to ask questions, share knowledge, and connect with other GitHub users. It’s a great place to get advice and solutions from experienced users.