Enforcing code governance in your enterprise with rulesets

Introduction

You can create rulesets to control how users can interact with code in repositories across your enterprise. You can:

• Create a branch or tag ruleset to control things like who can push commits to a certain branch, how commits must be formatted, or who can delete or rename a tag.
• Create a push ruleset to block pushes to a private or internal repository and the repository's entire fork network. Push rulesets allow you to block pushes based on file extensions, file path lengths, file and folder paths, and file sizes.

To learn more, see Sobre os conjuntos de regras.

Importing prebuilt rulesets

To import a prebuilt ruleset created by GitHub, see github/ruleset-recipes.

Você pode importar um conjunto de regras de outro repositório ou organização usando um arquivo JSON. Isso pode ser útil se você quiser aplicar o mesmo conjunto de regras a vários repositórios ou organizações. For more information, see "Como gerenciar conjuntos de regras para repositórios na sua organização."

How will I define where my ruleset applies?

Rulesets allow you to flexibly target the organizations, repositories, and branches where you want rules to apply.

• To target organizations, you can select all, choose from a list, or define a dynamic pattern for organization names using fnmatch syntax. For syntax details, see Criar conjuntos de regras para um repositório.
• Within those organizations, you can target all repositories, or target a dynamic list by custom property. See Como gerenciar propriedades personalizadas para repositórios na sua organização.
• Within the repositories, you can target certain branches or tags: all branches, the default branch, or a dynamic list using fnmatch syntax.

When you create a ruleset that targets branches in a repository, repository administrators can no longer rename branches or change the default branch in the targeted repository. They can still create and delete branches if they have the appropriate permissions.

How can I control the format of commits?

In branch or tag rulesets, you can add a rule that restricts the format of commit metadata such as commit message or author email.

If you select Must match a given regex pattern restriction, you can use regular expression syntax to define patterns that the metadata must or must not match. For syntax details and examples, see Criar conjuntos de regras para um repositório.

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.

Creating a branch or tag ruleset

1. No canto superior direito do GitHub, selecione sua foto de perfil.

2. Dependendo do ambiente, selecione Sua empresa ou Suas empresas e escolha a empresa que deseja ver.

3. Do lado esquerdo da página, na barra lateral da conta empresarial, clique em Políticas.

4. Under "Policies", click Code.

5. Clique em Novo conjunto de regras.

6. Para criar um conjunto de regras direcionado a branches, clique em Novo conjunto de regras de branch.

7. Como alternativa, para criar um conjunto de regras segmentando tags, clique em Novo conjunto de regras de tags.

8. Em "Nome do conjunto de regras", digite um nome para o conjunto de regras.

9. Opcionalmente, para alterar o status de imposição padrão, clique em Desabilitado e selecione um status de imposição. Para obter mais informações sobre os status de imposição, confira Sobre os conjuntos de regras.

Granting bypass permissions for your branch or tag ruleset

You can grant certain roles, teams, or apps bypass permissions as well as the ability to approve bypass requests for your ruleset.

The following are eligible for bypass access:

• Repository admins, organization owners, and enterprise owners
• The maintain or write role, or deploy keys.

1. To grant bypass permissions for the ruleset, in the "Bypass list" section, click Add bypass.

2. In the "Add bypass" modal dialog that appears, search for the role, team, or app you would like to grant bypass permissions, then select the role, team, or app from the "Suggestions" section and click Add Selected.

3. Opcionalmente, para conceder bypass a um ator sem permitir que ele envie diretamente para um repositório, à direita de "Sempre permitir", clique em e, em seguida, clique em Somente para pull requests.

   O ator selecionado agora é obrigado a abrir uma pull request para fazer alterações em um repositório, criando uma trilha digital clara com suas alterações no pull request e no log de auditoria. Em seguida, o ator pode optar por ignorar quaisquer proteções de branch e mesclar essa pull request.

Choosing which organizations to target in your enterprise

Select all organizations, choose a selection of existing organizations, or set a dynamic list by name. If you use Enterprise Managed Users, you can also choose to target all repositories owned by users in your enterprise.

If you set a dynamic list, you'll add one or more naming patterns using fnmatch syntax. For example, the string *open-source would match any organization with a name that ends with open-source. For syntax details, see "Criar conjuntos de regras para um repositório."

Choosing which repositories to target in your enterprise

Within the selected organizations, you can target all repositories or target a dynamic list by custom property. See Como gerenciar propriedades personalizadas para repositórios na sua organização.

Choosing which branches or tags to target

Para direcionar branches ou tags na seção "Branches de destino" ou "Tags de destino", selecione Adicionar um destino e escolha como deseja incluir ou excluir branches ou tags. Use a sintaxe fnmatch para incluir ou excluir branches ou tags com base em um padrão. Para obter mais informações, confira Como usar a sintaxe de fnmatch.

Você pode adicionar vários critérios de direcionamento ao mesmo conjunto de regras. Por exemplo, você pode incluir o branch padrão, incluir os branches que correspondam ao padrão *feature* e excluir especificamente um branch que corresponda ao padrão not-a-feature.

Selecting branch or tag protections

In the "Branch protections" or "Tag protections" section, select the rules you want to include in the ruleset. When you select a rule, you may be able to enter additional settings for the rule. For more information on the rules, see "Regras disponíveis para conjuntos de regras"

Adding metadata restrictions

As restrições de metadados devem se destinar a aumentar a consistência entre os commits no seu repositório. Elas não se destinam a substituir medidas de segurança, como exigir uma revisão de código por meio de solicitações de pull.

1. Para adicionar uma regra para controlar metadados de commit ou nomes de branches, na seção “Restrições” ao criar ou editar um conjunto de regras, selecione Restringir metadados de commit ou Restringir nomes de branches.

2. Defina as configurações para a restrição e, em seguida, clique em Adicionar. Você pode adicionar várias restrições ao mesmo conjunto de regras.

3. Para corresponder a um determinado padrão regex, na lista suspensa "Requisito", selecione Deve corresponder a um determinado padrão regex.

   Para a maioria dos requisitos, como "Precisa começar com um padrão correspondente", o padrão inserido é interpretado literalmente e não há suporte para curingas. Por exemplo, o caractere * representa apenas o caractere literal *.

   Para padrões mais complexos, você pode selecionar "Precisa corresponder a determinado padrão regex" ou "Não precisa corresponder a determinado padrão regex" e usar a sintaxe de expressão regular para definir o padrão correspondente. Para obter mais informações, confira Sobre expressões regulares para metadados de commit."

   Qualquer pessoa que visualizar os conjuntos de regras de um repositório poderá ver a descrição fornecida por você.

4. Opcionalmente, antes de aplicar o conjunto de regras com as restrições de metadados, escolha o status de imposição “Avaliar” para o conjunto de regras, a fim de testar os efeitos de todas as restrições de metadados sem afetar os colaboradores. Para obter mais informações sobre as restrições de metadados, confira Regras disponíveis para conjuntos de regras.

Finalizing your branch or tag ruleset and next steps

Para concluir a criação do conjunto de regras, clique em Criar. Se o status de imposição do conjunto de regras for definido como "Ativo", o conjunto de regras entrará em vigor imediatamente.

Você pode exibir insights para o conjunto de regras para ver como as regras estão afetando seus colaboradores. Se o status de imposição estiver definido como "Avaliar", você poderá ver quais ações teriam passado ou falhado se o conjunto de regras estivesse ativo. Para obter mais informações sobre insights para conjuntos de regras, confira Gerenciar conjuntos de regras para um repositório.

Creating a push ruleset

You can create a push ruleset for private or internal repositories in your enterprise.

1. No canto superior direito do GitHub, selecione sua foto de perfil.
2. Dependendo do ambiente, selecione Sua empresa ou Suas empresas e escolha a empresa que deseja ver.
3. In the left sidebar, in the "Policies" section, click Code.
4. Click New ruleset.
5. Click New push ruleset.
6. Under "Ruleset name," type a name for the ruleset.
7. Optionally, to change the default enforcement status, click Disabled and select an enforcement status. For more information about enforcement statuses, see Sobre os conjuntos de regras

Granting bypass permissions for your push ruleset

You can grant certain roles, teams, or apps bypass permissions as well as the ability to approve bypass requests for your ruleset. The following are eligible for bypass access:

• Repository admins, organization owners, and enterprise owners
• The maintain or write role, or deploy keys

1. To grant bypass permissions for the ruleset, in the "Bypass list" section, click Add bypass.
2. In the "Add bypass" modal dialog that appears, search for the role, team, or app you would like to grant bypass permissions, then select the role, team, or app from the "Suggestions" section and click Add Selected.

Choosing which organizations to target in your enterprise

Select all organizations, choose a selection of existing organizations, or set a dynamic list by name. If you use Enterprise Managed Users, you can also choose to target all repositories owned by users in your enterprise.

If you set a dynamic list, you'll add one or more naming patterns using fnmatch syntax. For example, the string *open-source would match any organization with a name that ends with open-source. For syntax details, see "Criar conjuntos de regras para um repositório."

Choosing which repositories to target in your enterprise

Within your chosen organizations, you can target all repositories, or target a dynamic list using custom properties. See Como gerenciar propriedades personalizadas para repositórios na sua organização.

Selecting push protections

É possível bloquear envios por push para este repositório e 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.

Qualquer proteção por push que você configurar bloqueará pushes nesse repositório e em toda a rede de bifurcação desse repositório.

1. Em "Proteções por push", clique nas restrições que você deseja aplicar. Em seguida, preencha os detalhes das restrições selecionadas.

   Para restrições de caminho de arquivo, é possível usar caminhos parciais ou completos. É 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.

Finalizing your push ruleset and next steps

Para concluir a criação do conjunto de regras, clique em Criar. Se o status de imposição do conjunto de regras for definido como "Ativo", o conjunto de regras entrará em vigor imediatamente.

Você pode exibir insights para o conjunto de regras para ver como as regras estão afetando seus colaboradores. Se o status de imposição estiver definido como "Avaliar", você poderá ver quais ações teriam passado ou falhado se o conjunto de regras estivesse ativo. Para obter mais informações sobre insights para conjuntos de regras, confira Gerenciar conjuntos de regras para um repositório.