About rulesets

About rulesets

A ruleset is a named list of rules that applies to a repository, or to multiple repositories in an organization. You can have up to 75 rulesets per repository, and 75 organization-wide rulesets.

When you create a ruleset, you can allow certain users to bypass the rules in the ruleset. This can be users with a certain role, such as repository administrator, or it can be specific teams or GitHub Apps. For more information about granting bypass permissions, see Criar conjuntos de regras para um repositório.

For organizations on the GitHub Enterprise plan, you can set up rulesets at the enterprise or organization level to target multiple repositories in your organization. See Como gerenciar conjuntos de regras para repositórios na sua organização.

You can use rulesets to target branches or tags in a repository or to block pushes to a repository and the repository's entire fork network.

O bypass delegado para conjuntos de regras de push permite que você controle quem pode ignorar a proteção push e quais pushes bloqueados devem ser permitidos.

Com o bypass delegado, os colaboradores de um repositório devem solicitar "privilégios de bypass" ao enviar confirmações por push que contenham conteúdo restrito. A solicitação é enviada a um grupo designado de revisores, que aprovam ou negam a solicitação para ignorar regras de push.

Se a solicitação para ignorar as regras de envio for aprovada, o colaborador poderá fazer push do commit com conteúdo restrito. Se a solicitação for negada, o contribuidor deverá remover o conteúdo do commit (ou commits) com o conteúdo restrito antes de enviar por push novamente.

Para configurar o bypass delegado, os proprietários da organização ou os administradores do repositório primeiro criam uma "lista de bypass". A lista de desvio inclui funções e equipes específicas, como administradores de equipe ou de repositório, que supervisionam as solicitações de bypass da proteção de push. Para saber mais, confira Como gerenciar conjuntos de regras para repositórios na sua organização e Sobre os conjuntos de regras.

Branch and tag rulesets

You can create rulesets to control how people can interact with selected branches and tags in a repository. You can control things like who can push commits to a certain branch and how the commits must be formatted, or who can delete or rename a tag. For example, you could set up a ruleset for your repository's feature branch that requires signed commits and blocks force pushes for all users except repository administrators.

For each ruleset you create, you specify which branches or tags in your repository, or which repositories in your organization, the ruleset applies to. You can use fnmatch syntax to define a pattern to target specific branches, tags, and repositories. For example, you could use the pattern releases/**/* to target all branches in your repository whose name starts with the string releases/. For more information on fnmatch syntax, see Criar conjuntos de regras para um repositório.

Push rulesets

Com os conjunto de regras por push, é possível bloquear envios por push para um repositório privado ou interno e para toda a rede de bifurcação desse repositório com base em extensões de arquivo, comprimentos de caminho de arquivo, caminhos de arquivo e pasta e tamanhos de arquivo.

As regras de push não exigem nenhum direcionamento de branch porque se aplicam a cada envio por push para o repositório.

Os conjuntos de regras por push permitem:

• Restringir caminhos de arquivo: impedir que confirmações que incluam alterações em caminhos de arquivo especificados sejam enviadas.

  É possível usar a sintaxe fnmatch para essa finalidade. Por exemplo, uma segmentação de restrição test/demo/**/* impede qualquer envio por push para arquivos ou pastas no diretório test/demo/. Uma segmentação de restrição test/docs/pushrules.md impede envios por push especificamente para o arquivo pushrules.md no diretório test/docs/. Para saber mais, confira Criar conjuntos de regras para um repositório.

• Restringir o comprimento do caminho do arquivo: impedir que confirmações que incluam caminhos de arquivo que excedam um limite de caracteres especificado sejam enviadas.

• Restringir extensões de arquivo: impedir que confirmações que incluam arquivos com extensões de arquivo especificadas sejam enviadas.

• Restringir o tamanho do arquivo: impedir que confirmações que excedam um limite de tamanho de arquivo especificado sejam enviadas.

Sobre os conjuntos de regras por push para repositórios bifurcados

As regras de push se aplicam a toda a rede de bifurcação de um repositório, garantindo que cada ponto de entrada do repositório esteja protegido. Por exemplo, se você bifurcar um repositório que tenha conjuntos de regras por push habilitados, os mesmos conjuntos de regras por push também se aplicarão ao repositório bifurcado.

Para um repositório bifurcado, as únicas pessoas que têm permissões de bypass para uma regra de push são as pessoas que têm permissões de bypass no repositório raiz.

About rulesets and protected branches

Rulesets work alongside any branch protection rules in a repository. Many of the rules you can define in rulesets are similar to protection rules, and you can start using rulesets without overriding any of your existing protection rules.

Rulesets have the following advantages over branch protection rules.

• Unlike protection rules, multiple rulesets can apply at the same time, so you can be confident that every rule targeting a branch in your repository will be evaluated when someone interacts with that branch. See About rule layering.
• Rulesets have statuses, so you can easily manage which rulesets are active in a repository without needing to delete rulesets.
• Anyone with read access to a repository can view the active rulesets for the repository. This means a developer can understand why they have hit a rule, or an auditor can check the security constraints for the repository, without requiring admin access to the repository.
• You can create additional rules to control the metadata of commits entering a repository, such as the commit message and the author's email address. See Regras disponíveis para conjuntos de regras."

Using ruleset enforcement statuses

Ao criar ou editar seu conjunto de regras, você pode usar status de imposição para configurar como seu conjunto de regras será imposto.

Você pode selecionar qualquer um dos seguintes status de imposição para seu conjunto de regras.

• Active: seu conjunto de regras será imposto após a criação.
• Evaluate: seu conjunto de regras não será aplicado, mas você poderá monitorar quais ações violariam ou não as regras na página "Insights de regras".
• Disabled: seu conjunto de regras não será imposto ou avaliado.

Usar o modo "Avaliar" é uma ótima opção para testar seu conjunto de regras sem impô-lo. É possível usar a página "Insights da regra" para ver se a contribuição teria violado a regra. Para saber mais, confira Gerenciar conjuntos de regras para um repositório.

About rule layering

A ruleset does not have a priority. Instead, if multiple rulesets target the same branch or tag in a repository, the rules in each of these rulesets are aggregated. If the same rule is defined in different ways across the aggregated rulesets, the most restrictive version of the rule applies. As well as layering with each other, rulesets also layer with protection rules targeting the same branch or tag.

For example, consider the following situation for the my-feature branch of the octo-org/octo-repo repository.

• An administrator of the repository has set up a ruleset targeting the my-feature branch. This ruleset requires signed commits, and three reviews on pull requests before they can be merged.
• An existing branch protection rule for the my-feature branch requires a linear commit history, and two reviews on pull requests before they can be merged.
• An administrator of the octo-org organization has also set up a ruleset targeting the my-feature branch of the octo-repo repository. The ruleset blocks force pushes, and requires one review on pull requests before they can be merged.

The rules from each source are aggregated, and all rules apply. Where multiple different versions of the same rule exist, the result is that the most restrictive version of the rule applies. Therefore, the my-feature branch requires signed commits and a linear commit history, force pushes are blocked, and pull requests targeting the branch will require three reviews before they can be merged.

Next steps

Next, learn how to communicate important information with members of your enterprise using READMEs. See Create a README for your enterprise.