Protected branches have been around for a while, and have made numerous improvements over time. GitHub added new rules to protect multiple branches and introduced additional permissions. However, it’s still challenging to consistently protect branches and tags throughout organizations. Managing scripts, cron jobs, various API calls, or third-party tooling to have consistent branch protections is not only annoying but also time-consuming.
It’s time for a new approach
GitHub announced the general availability of repository rules. Repository rules enable easily defined branch protections in public repositories. With flexible targeting options, it can protect multiple branch patterns using a single ruleset. Layering makes bypass scenarios dynamic; a GitHub App can skip status checks with no additional permissions, and administrators can bypass pull requests while still requiring the important CodeQL checks to run.
In line with GitHub’s mission to be the home for all developers, they have integrated GitHub Repository Rules to ensure that everyone collaborating on a repository knows the rules in play for them. An overview page provides visibility on rules applicable to a branch. Relevant information about rule enforcement is available at multiple touchpoints on GitHub.com, Git, and the GitHub CLI. There are also helpful prompts on ensuring the responsible use of bypass permissions.
Twilio has been using GitHub Repository Rules to balance developer experience and security.
“At Twilio, we value the autonomy of our engineering teams, including the ability to manage their own GitHub repositories. However, this autonomy makes compliance and security more challenging. We have successfully used GitHub Repository Rules to help us meet our compliance and security requirements while maintaining team autonomy.”
– David Betts, Senior Engineering Manager, Twilio
GitHub Enterprise Cloud customers can enforce these rules across all or a subset of their repositories in an organization. No more tedious audits checking to see if a rule existed; now ensure consistency in one location. If one is not ready to commit to a ruleset, they can trial them in evaluate mode. Rule insights allows us to see what could happen if dismisses stale reviews or enables linear merge history. No more guessing and no more testing in “production.”
Policy enforcement is a big reason Thomson Reuters has been an early adopter of repository rules across their organization.
“Compliance and security controls are fundamental to keeping applications safe. At Thomson Reuters, it’s important we properly enforce these policies. With repository rules, GitHub gives us the confidence to know we are enforcing our policies across an organization effectively, keeping our applications safe for end customers.” – Darren Trzynka. Senior Cloud Architect,Thomson Reuters
Regarding consistency, repository rules can deliver that with new metadata rules. Branch names, commit messages, and author email addresses of the commit can be governed to help ensure organizational standards. So, set all those protected tags to use SemVer and commit messages on the Emoji-Log standard.
Typical rules for production repositories
Setting up repository rules can help maintain code quality, prevent mistakes, and improve collaboration. There are numerous decisions to make about the security goals of a repository, let alone multiple repositories. GitHub wants to share best practices that are broadly applicable. Adding rules can create friction for developers contributing to the repository. Therefore, articulate the goals for repository and limit the number of rules necessary to achieve these goals. A production repository will have a few well-known branches. These branches should require peer-reviewed pull requests, use CI/CD for running unit tests and controlling releases, and support certain namespaces of topic branches with minimal restrictions. Here’s how you’d implement that with the repository rules REST API for a single repository.
Rules for governance across an organization
Setting review standards across all repositories, such as requiring “two sets of eyes” on pull requests, can help ensure that repositories more readily meet regulatory or compliance standards.
One area to consider is how to handle exceptions and bypasses. Having a designated team on the bypass list for organization rulesets ensures that someone can always intervene in “break-glass” scenarios. Another option is to carefully craft organization rules to limit situations when an exception is needed. Using a ruleset in evaluate mode allows model potential scenarios requiring exceptions. It can be tried out in a dry run and then review those events in ruleset insights.
Bypass with ease—or how I learned to stop worrying and love the bot
GitHub Apps may not need to run status checks when committing for various reasons, but they should not have admin access. This was the only option in branch protections and led to scenarios with overpowered bots. Repository rules support layering, meaning they can write a couple of rulesets, one with a bypass list narrowly scoped, layered with another ruleset containing an empty bypass list. A bot can skip status checks but can’t delete branches or force push. In this case two rulesets are created in the repository. Rulesets have been named as “Bots and Friends” and the other “For all.”
- “For all ruleset”
- “Bots and Friends” ruleset
