The REST API is now versioned. For more information, see "About API versioning."

REST API endpoints for rules

Use the REST API to manage rulesets for an enterprise. Rulesets control how people can interact with repositories and code.

Create an enterprise repository ruleset

Create a repository ruleset for an enterprise.

Fine-grained access tokens for "Create an enterprise repository ruleset"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Enterprise administration" enterprise permissions (write)

Parameters for "Create an enterprise repository ruleset"

Headers
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
enterprise string Required

The slug version of the enterprise name.

Body parameters
name string Required

The name of the ruleset.

target string

The target of the ruleset

Default: branch

Can be one of: branch, tag, push, repository

enforcement string Required

The enforcement level of the ruleset. evaluate allows admins to test rules before enforcing them. Admins can view insights on the Rule Insights page. evaluate is not available for the repository target.

Can be one of: disabled, active, evaluate

bypass_actors array of objects

The actors that can bypass the rules in this ruleset

actor_id integer or null

The ID of the actor that can bypass a ruleset. Required for Integration, RepositoryRole, Team, and User actor types. If actor_type is OrganizationAdmin, actor_id is ignored. If actor_type is DeployKey, this should be null. If actor_type is EnterpriseOwner, actor_id is ignored. OrganizationAdmin, EnterpriseOwner and EnterpriseRole are not applicable for personal repositories.

actor_type string Required

The type of actor that can bypass a ruleset

Can be one of: Integration, OrganizationAdmin, RepositoryRole, Team, DeployKey, EnterpriseOwner, EnterpriseRole, User

bypass_mode string

When the specified actor can bypass the ruleset. pull_request means that an actor can only bypass rules on pull requests. pull_request is not applicable for the DeployKey actor type. Also, pull_request is only applicable to branch rulesets. When bypass_mode is exempt, rules will not be run for that actor and a bypass audit entry will not be created.

Default: always

Can be one of: always, pull_request, exempt

conditions object

Conditions for an enterprise ruleset. The conditions object supports either of the following combinations: - organization_id and repository_name - organization_id and repository_property - organization_name and repository_name - organization_name and repository_property - organization_property and repository_name - organization_property and repository_property For branch and tag rulesets, the conditions object should also contain the ref_name property.

organization_name_and_repository_name object

Conditions to target organizations by name and all repositories

organization_name object Required
include array of strings

Array of organization names or patterns to include. One of these patterns must match for the condition to pass. Also accepts ~ALL to include all organizations and ~EMUS to target all enterprise managed user accounts.

exclude array of strings

Array of organization names or patterns to exclude. The condition will not pass if any of these patterns match.

repository_name object Required
include array of strings

Array of repository names or patterns to include. One of these patterns must match for the condition to pass. Also accepts ~ALL to include all repositories.

exclude array of strings

Array of repository names or patterns to exclude. The condition will not pass if any of these patterns match.

protected boolean

Whether renaming of target repositories is prevented.

ref_name object
include array of strings

Array of ref names or patterns to include. One of these patterns must match for the condition to pass. Also accepts ~DEFAULT_BRANCH to include the default branch or ~ALL to include all branches.

exclude array of strings

Array of ref names or patterns to exclude. The condition will not pass if any of these patterns match.

organization_name_and_repository_property object

Conditions to target organizations by name and repositories by property

organization_name object Required
include array of strings

Array of organization names or patterns to include. One of these patterns must match for the condition to pass. Also accepts ~ALL to include all organizations and ~EMUS to target all enterprise managed user accounts.

exclude array of strings

Array of organization names or patterns to exclude. The condition will not pass if any of these patterns match.

repository_property object Required
include array of objects

The repository properties and values to include. All of these properties must match for the condition to pass.

name string Required

The name of the repository property to target

property_values array of strings Required

The values to match for the repository property

source string

The source of the repository property. Defaults to 'custom' if not specified.

Can be one of: custom, system

exclude array of objects

The repository properties and values to exclude. The condition will not pass if any of these properties match.

name string Required

The name of the repository property to target

property_values array of strings Required

The values to match for the repository property

source string

The source of the repository property. Defaults to 'custom' if not specified.

Can be one of: custom, system

ref_name object
include array of strings

Array of ref names or patterns to include. One of these patterns must match for the condition to pass. Also accepts ~DEFAULT_BRANCH to include the default branch or ~ALL to include all branches.

exclude array of strings

Array of ref names or patterns to exclude. The condition will not pass if any of these patterns match.

organization_id_and_repository_name object

Conditions to target organizations by id and all repositories

organization_id object Required
organization_ids array of integers

The organization IDs that the ruleset applies to. One of these IDs must match for the condition to pass.

repository_name object Required
include array of strings

Array of repository names or patterns to include. One of these patterns must match for the condition to pass. Also accepts ~ALL to include all repositories.

exclude array of strings

Array of repository names or patterns to exclude. The condition will not pass if any of these patterns match.

protected boolean

Whether renaming of target repositories is prevented.

ref_name object
include array of strings

Array of ref names or patterns to include. One of these patterns must match for the condition to pass. Also accepts ~DEFAULT_BRANCH to include the default branch or ~ALL to include all branches.

exclude array of strings

Array of ref names or patterns to exclude. The condition will not pass if any of these patterns match.

organization_id_and_repository_property object

Conditions to target organization by id and repositories by property

organization_id object Required
organization_ids array of integers

The organization IDs that the ruleset applies to. One of these IDs must match for the condition to pass.

repository_property object Required
include array of objects

The repository properties and values to include. All of these properties must match for the condition to pass.

name string Required

The name of the repository property to target

property_values array of strings Required

The values to match for the repository property

source string

The source of the repository property. Defaults to 'custom' if not specified.

Can be one of: custom, system

exclude array of objects

The repository properties and values to exclude. The condition will not pass if any of these properties match.

name string Required

The name of the repository property to target

property_values array of strings Required

The values to match for the repository property

source string

The source of the repository property. Defaults to 'custom' if not specified.

Can be one of: custom, system

ref_name object
include array of strings

Array of ref names or patterns to include. One of these patterns must match for the condition to pass. Also accepts ~DEFAULT_BRANCH to include the default branch or ~ALL to include all branches.

exclude array of strings

Array of ref names or patterns to exclude. The condition will not pass if any of these patterns match.

organization_property_and_repository_name object

Conditions to target organizations by property and all repositories

organization_property object Required
include array of objects

The organization properties and values to include. All of these properties must match for the condition to pass.

name string Required

The name of the organization property to target

property_values array of strings Required

The values to match for the organization property

exclude array of objects

The organization properties and values to exclude. The condition will not pass if any of these properties match.

name string Required

The name of the organization property to target

property_values array of strings Required

The values to match for the organization property

repository_name object Required
include array of strings

Array of repository names or patterns to include. One of these patterns must match for the condition to pass. Also accepts ~ALL to include all repositories.

exclude array of strings

Array of repository names or patterns to exclude. The condition will not pass if any of these patterns match.

protected boolean

Whether renaming of target repositories is prevented.

ref_name object
include array of strings

Array of ref names or patterns to include. One of these patterns must match for the condition to pass. Also accepts ~DEFAULT_BRANCH to include the default branch or ~ALL to include all branches.

exclude array of strings

Array of ref names or patterns to exclude. The condition will not pass if any of these patterns match.

organization_property_and_repository_property object

Conditions to target organizations by property and repositories by property

organization_property object Required
include array of objects

The organization properties and values to include. All of these properties must match for the condition to pass.

name string Required

The name of the organization property to target

property_values array of strings Required

The values to match for the organization property

exclude array of objects

The organization properties and values to exclude. The condition will not pass if any of these properties match.

name string Required

The name of the organization property to target

property_values array of strings Required

The values to match for the organization property

repository_property object Required
include array of objects

The repository properties and values to include. All of these properties must match for the condition to pass.

name string Required

The name of the repository property to target

property_values array of strings Required

The values to match for the repository property

source string

The source of the repository property. Defaults to 'custom' if not specified.

Can be one of: custom, system

exclude array of objects

The repository properties and values to exclude. The condition will not pass if any of these properties match.

name string Required

The name of the repository property to target

property_values array of strings Required

The values to match for the repository property

source string

The source of the repository property. Defaults to 'custom' if not specified.

Can be one of: custom, system

ref_name object
include array of strings

Array of ref names or patterns to include. One of these patterns must match for the condition to pass. Also accepts ~DEFAULT_BRANCH to include the default branch or ~ALL to include all branches.

exclude array of strings

Array of ref names or patterns to exclude. The condition will not pass if any of these patterns match.

rules array of objects

An array of rules within the ruleset.

creation object

Only allow users with bypass permission to create matching refs.

type string Required

Value: creation

update object

Only allow users with bypass permission to update matching refs.