rules

Subscribe to all “rules” posts via RSS or follow GitHub Changelog on Twitter to stay updated on everything we ship.

~ cd github-changelog
~/github-changelog|main git log main
showing all changes successfully

We’re excited to introduce enhancements to custom properties as well as updates to the push rule public beta.

Custom properties updates!

New property types

  • Multi select allows a repo to have more than one value for a property defined. Now a repository can have a property that defines a compliance requirement with values for FedRamp and SOC2, for example.
  • True/False allows you to set whether a given property is true or false for a given repository.

repository properties with multi select

Target rulesets by repository visibility and more

In addition to targeting repositories with the custom properties you’ve created, we’ve now extended property targeting to include the ability to target by:
Visibility: public, private, or internal
Fork: true, false
Language: select primary repository language.

System property targeting in a ruleset screenshot

Learn more in the custom properties documentation

What do you think? Start a discussion within GitHub Community.

Push rule delegated bypass public beta!

We are expanding on the push rule public beta with a new delegated bypass flow.

Previously to bypass push rules you had to be on the bypass list to push restricted content. Now with delegated bypass, contributors can propose bypassing a push rule and members of the bypass list can review those bypass requests to allow or deny the content.

Learn more about push rule delegated bypass in the repository rules documentation and join the push rule discussion in the GitHub Community.

Delegated bypass screenshot

See more

Starting today, we will begin work towards the sunset of tag protections, with a full deprecation planned for August 30, 2024. See below for a full sunset timeline. You can migrate existing tag protections with the import to ruleset feature.

We launched repository rules last year to meet the needs of tag protection rules, while also scaling support to provide new functionalities like org-wide rules, granular restrictions for creating, reading, and updating events, and a more granular bypass model that does not require repository administrator permissions. As we such, we will sunset tag protections in favor of our ongoing investment in the repository rulesets platform.

You can import existing tag protection rules today with the existing migration feature. If no action is taken before the sunset date, GitHub will migrate all existing tag protections into a corresponding ruleset.

When are changes happening?

GitHub.com Timeline

  • May 30 : Repositories without tag protection rules will no longer be able to add new protection rules via the GitHub.com UI
  • July 24 through August 14 : A series of API brownouts will be run, see below for additional details on dates and times.
  • August 30, 2024: All tag protection rules will be migrated to a new tag ruleset. All REST and GraphQL API endpoints will be deprecated

GitHub.com API Timeline

  • May 30: API responses will include a deprecation notice
  • July 24: 1 hour API brownout
  • August 7: 8 hour API brownout
  • August 14: 24 hour API brownout
  • August 30: The tag protection rule API will begin responding with NULL data
  • The tag protection rules API will be deprecated in the next calendar version

GitHub Enterprise Server Timeline

  • Version 3.14: Tag protection rules will be marked for deprecation with an in-product banner and API responses will include a deprecation notice
  • Version 3.15: No changes will be made
  • Version 3.16: Tag protection rules will be migrated to a ruleset and the tag protection rule feature will no longer be available

Join the discussion within GitHub Community.

See more

Repository Updates April 30th, 2024

  • Deploy keys are now supported as a bypass actor in repository rules, allowing additional granularity for your automations. Previously for deploy keys to bypass a ruleset the Repository Administrator role was required.
  • Webhooks and GitHub Actions will no longer be run for any push that includes over 5000 branches. Clients will now receive the following warning indicating they have reached this limit. remote: warning: No webhooks or actions will be performed for this push as it updates more than 5000 branches.

Join the discussion within GitHub Community.

See more

The code scanning option for repository rules is now available in public beta. Code scanning users can now create a dedicated code scanning rule to block pull request merges, instead of relying on status checks.
Making it easier than ever to prevent new vulnerabilities from being introduced into your code base.

code scanning rule

Configuring code scanning merge protection with rulesets can be done at the repository or organization levels and for repositories configured with either default setup or advanced setup. Additionally you can also use the REST API to set merge protection with rulesets.

You can use rulesets to prevent pull requests from being merged when one of the following conditions is met:
– A required tool found a code scanning alert of a severity that is defined in a ruleset.
– A required code scanning tool’s analysis is still in progress.
– A required code scanning tool is not configured for the repository.

Note: Merge protection with rulesets is not related to status checks. If the code scanning rule is configured for the repository in parallel with an alert threshold and the merge protection rule for the code scanning check run, the two functionalities will work simultaneously. For more information about status checks, see about status checks.

This beta is now available on GitHub.com and will be available on GHES 3.14. The organisation wide rules is only available for GitHub enterprise. For more information, see Configuring merge protection for all repositories in an organization.

We look forward to your feedback on the code scanning option for repository rules in the GitHub community.

See more

Say goodbye to unwanted files cluttering your repos, like *.jar or *.so. And limit who can make updates to sensitive files like your Actions workflows with the public beta of push rules. 🎉

A glimpse of push rules in action

You can now enable a new type of ruleset that allows you to control pushes to repositories based on file extensions, file path lengths, file and folder paths and file sizes. Push rules don’t require any branch targeting as they apply to every push to the repository, and also apply to all forks of the repo to ensure all pushes to the repository network are protected.

Push rules are now available for private and internal repositories for GitHub Teams, and across organizations for GitHub Enterprise Cloud.

Learn more about push rules in our documentation and join the community discussion to leave feedback.

See more

Configuring merge queue in your repo rulesets is now available in public beta!

Screenshot showing the configuration of merge queue inside a ruleset

Merge queue & rule insights

Until now, rule insights would only list one pull request as merged even when multiple pull requests were merged by the queue at the same time. Also in this beta, each pull request in a merge queue will have an individual record in rule insights, linked to the actor that added the pull request to the merge queue.

Example screenshot showing rules insights and all PRs from a queue

Within the additional data of a rule insight dialog you can now see all the pull requests that merged in the same group along with the checks needed for the queue.

Example screenshot of details of a queue in rule insights

Limitations

  • The merge queue rule cannot be configured via an API. This feature will be available in the near future.
  • Merge Queue for branch protections and repository rules do not support wildcard patterns
  • Not supported in organization rulesets.
  • Multiple merge queues configured against a single branch will prevent merging.

Join the discussion within GitHub Community.

See more

repository custom properties banner image

We’re excited to announce the general availability of Repository Custom Properties, a major enhancement to how repositories are managed and classified across GitHub organizations.

Properties offer a flexible way to add meaningful metadata to your repositories that simplifies repository classification, enhances discoverability, and seamlessly integrates with rulesets.

Check out this video from our own Jon Peck for a walk through of a common scenario.

New organization repositories list public beta

Starting today the new repositories list view moves to public beta.

Improvements to Repository Rulesets

Repository Rules now support adding Dependabot to bypass lists. This enables you to let Dependabot merge changes to a repository’s protected branch.

Learn more about managing custom properties for your organization and managing rulesets for your organization.

Head over to community discussions for feedback.

See more

Auto-triage rules are a powerful tool to help you reduce false positives and alert fatigue substantially, while better managing your alerts at scale. We've heard your feedback, which is helping us improve throughout this beta period.

Starting today, you can now create Dependabot auto-triage rules using CVE IDs or GHSA IDs to target subsets of alerts.

How do I learn more?

How do I provide feedback?

Let us know what you think by providing feedback — we’re listening!

See more

Auto-triage rules are a powerful tool to help you reduce alert and pull request fatigue substantially, while better managing your alerts at scale.

What's changing?

Starting today, you can define your own rules to control and enforce Dependabot behaviors across organizations and individual repositories.

  • You can now define which alerts receive pull requests to resolve them, rather than targeting all alerts.
  • You can enable and enforce those Dependabot security update rules across organizations, in addition to individual repositories.
  • You can enable, disable, or enforce how GitHub default rulesets are applied across your organization.
  • You can also now enable and enforce custom auto-dismiss (alert ignore and snooze) rules across organizations.

Dependabot auto-triage rules list

Auto-triage rules are defined by alert targeting criteria, the behaviors you'd like Dependabot to automatically perform for these alerts, as well as how you want the rule to be enabled or enforced across your organization.

Alerts can be targeted based on metadata related to the advisory, dependency, and how it's used. For this public beta, currently supported attributes at the organization level are: severity, scope, package-name, cwe, and ecosystem. At the repository level, you can also target specific manifest files.

Create a stacked Dependabot auto-triage ruleset

For any existing or future alerts that match a custom rule, Dependabot will perform the selected behavior accordingly. You can proactively filter out false positives, snooze alerts until patch release, choose which alerts open Dependabot security updates, and – as rules apply to both future and current alerts – manage existing alerts in bulk.

This feature is free for open source (all public repositories) and available for use in private repositories through GitHub Advanced Security.

Frequently asked questions

Why is GitHub making this change?

At GitHub, we’ve been thinking deeply about how to responsibly address long-running issues around alert fatigue and false positives. Rather than over-indexing on one criterion like reachability or dependency scope, we believe that a responsibly-designed solution should be able to detect and reason on a rich set of complex, contextual alert metadata.

That’s why, moving forward, we’re releasing a series of ships powered by a flexible and powerful alert rules engine. Our first ship – Dependabot presets – leveraged our rules engine with GitHub-curated vulnerability patterns and has helped millions of repositories filter out false positive alerts. Today’s ship exposes our rules engine at the organization and repository levels, so you can create and enforce custom rules, too.

How do I create a rule?

From your organization or repository settings page, admins and security managers can navigate to Code security and analysis settings. Under Dependabot, select Dependabot rules to add or modify your own custom rules or modify GitHub presets.

How do I enforce rules for my organization?

Enforce a Dependabot auto-triage rule

At the organization level, rules can be set with the following states.

State Description
Enabled This rule will be enabled across all eligible repositories in your organization. It will be on by default (new repositories are included). Any individual repository can choose to disable the rule.
Enforced This rule will be enabled across all eligible repositories in your organization. It will be on by default (new repositories are included). Individual repositories cannot override this setting.
Disabled This rule will be disabled and hidden across your organization.

At the repository level, rules can be set to enabled or disabled if they're not enforced.

Which criteria are supported?

Rules can be created across the following attributes:

Attribute Description
severity Alert severity, based on CVSS base score, across the following values: low, medium, high, and critical.
scope Scope of the dependency: development (devDependency) or runtime (production).
package-name Packages, listed by package name.
cwe CWEs, listed by CWE ID.
ecosystem Ecosystems, listed by ecosystem name.
manifest Manifest files, listed by manifest path.

Note: manifest is only available at the repository level.

Target alerts based on attributes

How do I control how Dependabot automatically generates pull requests for alerts?

You can use the alert criteria (above) to indicate which alerts Dependabot will attempt to open pull requests to resolve. To use auto-triage rules with Dependabot updates, you must disable Dependabot's option to always open pull requests to resolve all open alerts from the repository Code security and analysis settings.

How do I control how Dependabot automatically closes or reopens alerts?

Similar to Dependabot pull request rules, you can control how Dependabot filters out false postives (with dismiss indefinitely) or snoozes alerts (with dismiss until patch).

How many custom rules can I create?

At the time of public beta, you can create 20 rules per organization and 10 rules for each repository. Want more? Let us know!

How will this activity be reported?

Auto-dismissal activity is shown in webhooks, REST, GraphQL, and the audit log for Dependabot alerts. Alerts are dismissed without a notification or new pull request and appear as a special timeline event. As these alerts are closed, you’ll still be able to review any auto-dismissed alerts with the resolution:auto-dismissed filter.

Who can create and modify rules?

Auto-triage rules are free for open source repositories. Anyone who can enable Dependabot alerts for a public repository will be able to create custom rules for it. Customers of GitHub Advanced Security can create and manage custom rules across private repositories and at the organization level.

How do I reopen an automatically dismissed alert?

Like any manually dismissed alert, you can reopen an auto-dismissed alert from the alert list view or details page. This specific alert won’t be auto-dismissed again (by any other auto-dismiss rule).

What happens if alert metadata changes or advisory information is withdrawn?

Dependabot recognizes and immediately responds to any changes to metadata which void auto-dismissal logic. For example, if you change the dependency scope and the alert no longer meets the criteria to be auto-dismissed, the alert will automatically reopen.

How do I learn more?

How do I provide feedback?

Let us know what you think by providing feedback — we’re listening!

See more

We’ve now made migrating existing tag protection rules into repository rules easy. With a few clicks, you can take multiple tag protection rules and turn them into a single ruleset or turn each rule into corresponding rulesets for more granular control.

GIF of importing tag protection rules to repo rules.

Tag protection rules control who can create, update, and delete tags. Moving your tag protections to repository rules allows you to require status checks, deployments to pass, and signed commits. You also get the rest of the repository rules power, with configurable enforcement status, bypass lists, and flexible targeting.

For GitHub Enterprise Cloud customers, you can pair metadata restrictions with your tag protection to manage commit messages and control the names of your tags. 

Click here to learn more. If you have feedback, please share and let us know in our community discussion.

See more

Need to roll back a change to a ruleset? How about easily moving your ruleset around?

With today’s public beta you now have new tools to manage your ruleset.

Import and Export

Rulesets are now easier to share and reuse, with the ability to import and export rulesets as JSON files. Giving you the ability to share rules across repositories and organizations or to share your favorite rules with the community. Which is what we’re doing. The ruleset-recipes repository is home to a collection of pre-baked rulesets covering a number of popular scenarios ready for you to use.

Gif walking through the steps outline above to import a ruleset from a JSON file.

History

If you are a repository or organization administrator of GitHub Enterprise cloud, we’re adding a history experience so you can track changes and revert rulesets. Now, it’s easy in the ruleset UI to see who changed a ruleset, when it happened, and what changed. Then, quickly get back to a known good state.

Only changes made to a ruleset after the public beta are included in ruleset history.

Gif walking through the step of using history, and selecting a ruleset version to restore.Screenshot of Ruleset history comparison screen.

Click here to learn more. If you have feedback, please share and let us know in our community discussion.

See more

PNG Custom Properties Header.

Starting today, organization administrators can create custom properties to enrich repositories with valuable information. Using these properties, you can dynamically target repository rules to apply protections on just your production repositories or to a business unit or any other way you want to classify your repositories.

Only organization administrators can configure custom properties; you can be confident knowing that they are not accidentally removed by a repository administrator, ensuring your branch and tag rules are consistently applied. Property values can also be automatically applied with default values at repository creation, ensuring every new repository is classified, and its first commit is protected.

Today, organization administrators can only use custom properties for dynamically targeting rulesets. But soon, you can use properties to filter and search in an updated repository list and other experiences across GitHub.

Learn more about managing custom properties for your organization and managing rulesets for your organization.

Head over to community discussions for feedback

See more

Requiring Actions workflows with Repository Rules is now generally available on GitHub.com!
Screenshot showing the add required workflow modal overtop the enabled rule inside a ruleset

Through Repository Rules, GitHub Enterprise Cloud customers can now set up organization-wide rules to enforce their CI/CD workflows, ensuring workflows pass before pull requests can be merged into target repositories. Additional settings allow for fine-tuning how the workflow file can be selected — either from a specific branch, tag, or SHA — and provide maximum control over the version expected to run.

Applying a newly created workflow policy across an organization can feel risky. To ensure confidence when enabling a workflow rule across targeted repositories, workflow rules can be put into “evaluate” mode which will validate the rule is working correctly. And don’t worry, organization administrators can even allow select roles to “break the glass” and bypass a rule when necessary.

Learn more about this release and how requiring workflows with Repository Rules can protect your repositories.

To share feedback or ask questions, join our Community Discussion!

See more

Repository rule insights now make finding more details about how someone merged specific code into your repos even easier.

🔍 Filter by status

If you want only to see bypassed rules, you can now filter rule insight by the status of the results.

No more scrolling through and sorting through all the insight activity to find that one bypass situation. You can now filter by All Statuses, Pass, Fail, and Bypass.

Overview of selecting different rule insights status types. And showing the change between pass, fail, and bypass

👀 Clamoring for more insight into your rule insights?

Well, now you have access to way more information, including who ✅ approved and ❌ denied a pull request. As well as having access to the results of all required status checks and deployment status states right in rule insights.

Rule insight instance showing a specific passed status check.

👩‍💻 REST API Endpoint

Want to look for ruleset failures for a specific app programmatically?
With the new REST endpoint, you can now view and query rule insights via your favorite API tools.

Repository Endpoint

All repo insight activity

–  GET http://api.github.com/repos/{owner}/{repo}/rulesets/rule-suites

Specific insight rule suite for a repository ruleset
–  GET http://api.github.com/repos/{owner}/{repo}/rulesets/rule-suites/{rule _suite_id}

Organization Endpoint

All org insight activity
–  GET http://api.github.com/orgs/{org}/rulesets/rule-suites

Specific insight rule suite for an organization ruleset
–  GET http://api.github.com/orgs/{org}/rulesets/rule-suites/{rule_suite_id}

Click here to learn more. If you have feedback, please share and let us know in our feedback discussion.

See more

Auto-triage rules are a powerful tool to help you reduce false positives and alert fatigue substantially, while better managing your alerts at scale.

Starting today, you can now create your own custom rules to control how Dependabot auto-dismisses and reopens alerts – so you can focus on the alerts that matter, without worrying about the alerts that don’t.

What’s changing?

For any existing or future alerts that match a custom rule, Dependabot will perform the selected behavior accordingly. You can proactively filter out false positives, snooze alerts until patch release, and – as rules apply to both future and current alerts – manage existing alerts in bulk.

Frequently asked questions

Why is GitHub making this change?

At GitHub, we’ve been thinking deeply about how to responsibly address long-running issues around alert fatigue and false positives. Rather than over-indexing on one criterion like reachability or dependency scope, we believe that a responsibly-designed solution should be able to detect and reason on a rich set of complex, contextual alert metadata.

That’s why, moving forward, we’re releasing a series of ships powered by an underlying, all-new, flexible and powerful alert rules engine. Our first ship – Dependabot presets – leveraged our rules engine with GitHub-curated vulnerability patterns. Today’s ship exposes our rules engine so you can create your own rules, too.

Which criteria are supported?

Rules can be created across the following attributes:

Attribute Description
severity Alert severity, based on CVSS base score, across the following values: low, medium, high, and critical.
scope Scope of the dependency: development (devDependency) or runtime (production).
package-name Packages, listed by package name.
cwe CWEs, listed by CWE ID.
ecosystem Ecosystems, listed by ecosystem name.
manifest Manifest files, listed by manifest path.

What behaviors are supported?

Create or edit a custom rule

Today’s ship covers support for auto-dismissing alerts indefinitely as well as snoozing alerts until patch. Auto-dismissing ensures all activity is easily visible and can be caught by existing reporting systems and workflows, while also ensuring that alerts can be reintroduced if metadata across the alert changes.

How will this activity be reported?

Auto-dismissal activity is shown in webhooks, REST, GraphQL, and the audit log for Dependabot alerts. Alerts are dismissed without a notification or new pull request and appear as a special timeline event. As these alerts are closed, you’ll still be able to review any auto-dismissed alerts with the resolution:auto-dismissed filter.

Who can create and modify rules?

Auto-triage rules are free for open source repositories. Anyone who can enable Dependabot alerts for a public repository will be able to create custom rules for it. Customers of GitHub Advanced Security can create and manage custom rules across private repositories.

How do I reopen an automatically dismissed alert?

Like any manually dismissed alert, you can reopen an auto-dismissed alert from the alert list view or details page. This specific alert won’t be auto-dismissed again (by any other auto-dismiss rule).

What happens if alert metadata changes or advisory information is withdrawn?

Dependabot recognizes and immediately responds to any changes to metadata which void auto-dismissal logic. For example, if you change the dependency scope and the alert no longer meets the criteria to be auto-dismissed, the alert will automatically reopen.

How do I learn more?

How do I provide feedback?

Let us know what you think by providing feedback — we’re listening!

See more