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 repositories. Rulesets control how people can interact with selected branches and tags in a repository.

Get rules for a branch

Returns all active rules that apply to the specified branch. The branch does not need to exist; rules that would applyto a branch with that name will be returned. All active rules that apply will be returned, regardless of the levelat which they are configured (e.g. repository or organization). Rules in rulesets with "evaluate" or "disabled"enforcement statuses are not returned.

Fine-grained access tokens for "Get rules for a branch"

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

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

"Metadata" repository permissions (read)

This endpoint can be used without authentication or the aforementioned permissions if only public resources are requested.

Parameters for "Get rules for a branch"

Headers
Name, Type, Description
`accept`string Setting to`application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository without the`.git` extension. The name is not case sensitive.
`branch`stringRequired The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, usethe GraphQL API.

Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default:`30`
`page`integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default:`1`

HTTP response status codes for "Get rules for a branch"

Status code	Description
`200`	OK

Code samples for "Get rules for a branch"

Request example

get/repos/{owner}/{repo}/rules/branches/{branch}

curl -L \  -H "Accept: application/vnd.github+json" \  -H "Authorization: Bearer <YOUR-TOKEN>" \  -H "X-GitHub-Api-Version: 2022-11-28" \  https://api.github.com/repos/OWNER/REPO/rules/branches/BRANCH

Response

Status: 200

[  {    "type": "commit_message_pattern",    "ruleset_source_type": "Repository",    "ruleset_source": "monalisa/my-repo",    "ruleset_id": 42,    "parameters": {      "operator": "starts_with",      "pattern": "issue"    }  },  {    "type": "commit_author_email_pattern",    "ruleset_source_type": "Organization",    "ruleset_source": "my-org",    "ruleset_id": 73,    "parameters": {      "operator": "contains",      "pattern": "github"    }  }]

Get all repository rulesets

Get all the rulesets for a repository.

Fine-grained access tokens for "Get all repository rulesets"

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

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

"Metadata" repository permissions (read)

This endpoint can be used without authentication or the aforementioned permissions if only public resources are requested.

Parameters for "Get all repository rulesets"

Headers
Name, Type, Description
`accept`string Setting to`application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository without the`.git` extension. The name is not case sensitive.

Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default:`30`
`page`integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default:`1`
`includes_parents`boolean Include rulesets configured at higher levels that apply to this repository Default:`true`
`targets`string A comma-separated list of rule targets to filter by.If provided, only rulesets that apply to the specified targets will be returned.For example,`branch,tag,push`.

HTTP response status codes for "Get all repository rulesets"

Status code	Description
`200`	OK
`404`	Resource not found
`500`	Internal Error

Code samples for "Get all repository rulesets"

Request example

get/repos/{owner}/{repo}/rulesets

curl -L \  -H "Accept: application/vnd.github+json" \  -H "Authorization: Bearer <YOUR-TOKEN>" \  -H "X-GitHub-Api-Version: 2022-11-28" \  https://api.github.com/repos/OWNER/REPO/rulesets

Response

Status: 200

[  {    "id": 42,    "name": "super cool ruleset",    "source_type": "Repository",    "source": "monalisa/my-repo",    "enforcement": "enabled",    "node_id": "RRS_lACkVXNlcgQB",    "_links": {      "self": {        "href": "https://api.github.com/repos/monalisa/my-repo/rulesets/42"      },      "html": {        "href": "https://github.com/monalisa/my-repo/rules/42"      }    },    "created_at": "2023-07-15T08:43:03Z",    "updated_at": "2023-08-23T16:29:47Z"  },  {    "id": 314,    "name": "Another ruleset",    "source_type": "Repository",    "source": "monalisa/my-repo",    "enforcement": "enabled",    "node_id": "RRS_lACkVXNlcgQQ",    "_links": {      "self": {        "href": "https://api.github.com/repos/monalisa/my-repo/rulesets/314"      },      "html": {        "href": "https://github.com/monalisa/my-repo/rules/314"      }    },    "created_at": "2023-08-15T08:43:03Z",    "updated_at": "2023-09-23T16:29:47Z"  }]

Create a repository ruleset

Create a ruleset for a repository.

Fine-grained access tokens for "Create a repository ruleset"

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

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

"Administration" repository permissions (write)

Parameters for "Create a repository ruleset"

Headers
Name, Type, Description
`accept`string Setting to`application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository without the`.git` extension. The name is not case sensitive.

Name, Type, Description

namestringRequired

The name of the ruleset.

targetstring

The target of the ruleset

Default:branch

Can be one of:branch,tag,push

enforcementstringRequired

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 only available with GitHub Enterprise).

Can be one of:disabled,active,evaluate

bypass_actorsarray of objects

The actors that can bypass the rules in this ruleset

Properties ofbypass_actors

Name, Type, Description
`actor_id`integer or null The ID of the actor that can bypass a ruleset. Required for`Integration`,`RepositoryRole`, and`Team` actor types. If`actor_type` is`OrganizationAdmin`, this should be`1`. If`actor_type` is`DeployKey`, this should be null.`OrganizationAdmin` is not applicable for personal repositories.
`actor_type`stringRequired The type of actor that can bypass a ruleset. Can be one of:`Integration`,`OrganizationAdmin`,`RepositoryRole`,`Team`,`DeployKey`
`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`

conditionsobject

Parameters for a repository ruleset ref name condition

Properties ofconditions

Name, Type, Description

ref_nameobject

Properties ofref_name

Name, Type, Description
`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.

rulesarray of objects

An array of rules within the ruleset.

Can be one of these objects:

Name, Type, Description

creationobject

Only allow users with bypass permission to create matching refs.

Properties ofcreation

Name, Type, Description
`type`stringRequired Value:`creation`

updateobject

Only allow users with bypass permission to update matching refs.

Properties ofupdate

Name, Type, Description

typestringRequired

Value:update

parametersobject

Properties ofparameters

Name, Type, Description
`update_allows_fetch_and_merge`booleanRequired Branch can pull changes from its upstream repository

deletionobject

Only allow users with bypass permissions to delete matching refs.

Properties ofdeletion

Name, Type, Description
`type`stringRequired Value:`deletion`

required_linear_historyobject

Prevent merge commits from being pushed to matching refs.

Properties ofrequired_linear_history

Name, Type, Description
`type`stringRequired Value:`required_linear_history`

merge_queueobject

Merges must be performed via a merge queue.

Properties ofmerge_queue

Name, Type, Description

typestringRequired

Value:merge_queue

parametersobject

Properties ofparameters

Name, Type, Description
`check_response_timeout_minutes`integerRequired Maximum time for a required status check to report a conclusion. After this much time has elapsed, checks that have not reported a conclusion will be assumed to have failed
`grouping_strategy`stringRequired When set to ALLGREEN, the merge commit created by merge queue for each PR in the group must pass all required checks to merge. When set to HEADGREEN, only the commit at the head of the merge group, i.e. the commit containing changes from all of the PRs in the group, must pass its required checks to merge. Can be one of:`ALLGREEN`,`HEADGREEN`
`max_entries_to_build`integerRequired Limit the number of queued pull requests requesting checks and workflow runs at the same time.
`max_entries_to_merge`integerRequired The maximum number of PRs that will be merged together in a group.
`merge_method`stringRequired Method to use when merging changes from queued pull requests. Can be one of:`MERGE`,`SQUASH`,`REBASE`
`min_entries_to_merge`integerRequired The minimum number of PRs that will be merged together in a group.
`min_entries_to_merge_wait_minutes`integerRequired The time merge queue should wait after the first PR is added to the queue for the minimum group size to be met. After this time has elapsed, the minimum group size will be ignored and a smaller group will be merged.

required_deploymentsobject

Choose which environments must be successfully deployed to before refs can be pushed into a ref that matches this rule.

Properties ofrequired_deployments

Name, Type, Description

typestringRequired

Value:required_deployments

parametersobject

Properties ofparameters

Name, Type, Description
`required_deployment_environments`array of stringsRequired The environments that must be successfully deployed to before branches can be merged.

required_signaturesobject

Commits pushed to matching refs must have verified signatures.

Properties ofrequired_signatures

Name, Type, Description
`type`stringRequired Value:`required_signatures`

pull_requestobject

Require all commits be made to a non-target branch and submitted via a pull request before they can be merged.

Properties ofpull_request

Name, Type, Description

typestringRequired

Value:pull_request

parametersobject

Properties ofparameters

Name, Type, Description

allowed_merge_methodsarray of strings

Array of allowed merge methods. Allowed values includemerge,squash, andrebase. At least one option must be enabled.Supported values are:merge,squash,rebase

dismiss_stale_reviews_on_pushbooleanRequired

New, reviewable commits pushed will dismiss previous pull request review approvals.

require_code_owner_reviewbooleanRequired

Require an approving review in pull requests that modify files that have a designated code owner.

require_last_push_approvalbooleanRequired

Whether the most recent reviewable push must be approved by someone other than the person who pushed it.

required_approving_review_countintegerRequired

The number of approving reviews that are required before a pull request can be merged.

required_review_thread_resolutionbooleanRequired

All conversations on code must be resolved before a pull request can be merged.

required_reviewersarray of objects

Note

required_reviewers is in beta and subject to change.

A collection of reviewers and associated file patterns. Each reviewer has a list of file patterns which determine the files that reviewer is required to review.

Properties ofrequired_reviewers

Name, Type, Description

file_patternsarray of stringsRequired

Array of file patterns. Pull requests which change matching files must be approved by the specified team. File patterns use fnmatch syntax.

minimum_approvalsintegerRequired

Minimum number of approvals required from the specified team. If set to zero, the team will be added to the pull request but approval is optional.

reviewerobjectRequired

A required reviewing team

Properties ofreviewer

Name, Type, Description
`id`integerRequired ID of the reviewer which must review changes to matching files.
`type`stringRequired The type of the reviewer Value:`Team`

required_status_checksobject

Choose which status checks must pass before the ref is updated. When enabled, commits must first be pushed to another ref where the checks pass.

Properties ofrequired_status_checks

Name, Type, Description

typestringRequired

Value:required_status_checks

parametersobject

Properties ofparameters

Name, Type, Description

do_not_enforce_on_createboolean

Allow repositories and branches to be created if a check would otherwise prohibit it.

required_status_checksarray of objectsRequired

Status checks that are required.

Properties ofrequired_status_checks

Name, Type, Description
`context`stringRequired The status check context name that must be present on the commit.
`integration_id`integer The optional integration ID that this status check must originate from.

strict_required_status_checks_policybooleanRequired

Whether pull requests targeting a matching branch must be tested with the latest code. This setting will not take effect unless at least one status check is enabled.

non_fast_forwardobject

Prevent users with push access from force pushing to refs.

Properties ofnon_fast_forward

Name, Type, Description
`type`stringRequired Value:`non_fast_forward`

commit_message_patternobject

Parameters to be used for the commit_message_pattern rule

Properties ofcommit_message_pattern

Name, Type, Description

typestringRequired

Value:commit_message_pattern

parametersobject

Properties ofparameters

Name, Type, Description
`name`string How this rule will appear to users.
`negate`boolean If true, the rule will fail if the pattern matches.
`operator`stringRequired The operator to use for matching. Can be one of:`starts_with`,`ends_with`,`contains`,`regex`
`pattern`stringRequired The pattern to match with.

commit_author_email_patternobject

Parameters to be used for the commit_author_email_pattern rule

Properties ofcommit_author_email_pattern

Name, Type, Description

typestringRequired

Value:commit_author_email_pattern

parametersobject

Properties ofparameters

Name, Type, Description
`name`string How this rule will appear to users.
`negate`boolean If true, the rule will fail if the pattern matches.
`operator`stringRequired The operator to use for matching. Can be one of:`starts_with`,`ends_with`,`contains`,`regex`
`pattern`stringRequired The pattern to match with.

committer_email_patternobject

Parameters to be used for the committer_email_pattern rule

Properties ofcommitter_email_pattern

Name, Type, Description

typestringRequired

Value:committer_email_pattern

parametersobject

Properties ofparameters

Name, Type, Description
`name`string How this rule will appear to users.
`negate`boolean If true, the rule will fail if the pattern matches.
`operator`stringRequired The operator to use for matching. Can be one of:`starts_with`,`ends_with`,`contains`,`regex`
`pattern`stringRequired The pattern to match with.

branch_name_patternobject

Parameters to be used for the branch_name_pattern rule

Properties ofbranch_name_pattern

Name, Type, Description

typestringRequired

Value:branch_name_pattern

parametersobject

Properties ofparameters

Name, Type, Description
`name`string How this rule will appear to users.
`negate`boolean If true, the rule will fail if the pattern matches.
`operator`stringRequired The operator to use for matching. Can be one of:`starts_with`,`ends_with`,`contains`,`regex`
`pattern`stringRequired The pattern to match with.

tag_name_patternobject

Parameters to be used for the tag_name_pattern rule

Properties oftag_name_pattern

Name, Type, Description

typestringRequired

Value:tag_name_pattern

parametersobject

Properties ofparameters

Name, Type, Description
`name`string How this rule will appear to users.
`negate`boolean If true, the rule will fail if the pattern matches.
`operator`stringRequired The operator to use for matching. Can be one of:`starts_with`,`ends_with`,`contains`,`regex`
`pattern`stringRequired The pattern to match with.

file_path_restrictionobject

Prevent commits that include changes in specified file and folder paths from being pushed to the commit graph. This includes absolute paths that contain file names.

Properties offile_path_restriction

Name, Type, Description

typestringRequired

Value:file_path_restriction

parametersobject

Properties ofparameters

Name, Type, Description
`restricted_file_paths`array of stringsRequired The file paths that are restricted from being pushed to the commit graph.

max_file_path_lengthobject

Prevent commits that include file paths that exceed the specified character limit from being pushed to the commit graph.

Properties ofmax_file_path_length

Name, Type, Description

typestringRequired

Value:max_file_path_length

parametersobject

Properties ofparameters

Name, Type, Description
`max_file_path_length`integerRequired The maximum amount of characters allowed in file paths.

file_extension_restrictionobject

Prevent commits that include files with specified file extensions from being pushed to the commit graph.

Properties offile_extension_restriction

Name, Type, Description

typestringRequired

Value:file_extension_restriction

parametersobject

Properties ofparameters

Name, Type, Description
`restricted_file_extensions`array of stringsRequired The file extensions that are restricted from being pushed to the commit graph.

max_file_sizeobject

Prevent commits with individual files that exceed the specified limit from being pushed to the commit graph.

Properties ofmax_file_size

Name, Type, Description

typestringRequired

Value:max_file_size

parametersobject

Properties ofparameters

Name, Type, Description
`max_file_size`integerRequired The maximum file size allowed in megabytes. This limit does not apply to Git Large File Storage (Git LFS).

workflowsobject

Require all changes made to a targeted branch to pass the specified workflows before they can be merged.

Properties ofworkflows

Name, Type, Description

typestringRequired

Value:workflows

parametersobject

Properties ofparameters

Name, Type, Description

do_not_enforce_on_createboolean

Allow repositories and branches to be created if a check would otherwise prohibit it.

workflowsarray of objectsRequired

Workflows that must pass for this rule to pass.

Properties ofworkflows

Name, Type, Description
`path`stringRequired The path to the workflow file
`ref`string The ref (branch or tag) of the workflow file to use
`repository_id`integerRequired The ID of the repository where the workflow is defined
`sha`string The commit SHA of the workflow file to use

code_scanningobject

Choose which tools must provide code scanning results before the reference is updated. When configured, code scanning must be enabled and have results for both the commit and the reference being updated.

Properties ofcode_scanning

Name, Type, Description

typestringRequired

Value:code_scanning

parametersobject

Properties ofparameters

Name, Type, Description

code_scanning_toolsarray of objectsRequired

Tools that must provide code scanning results for this rule to pass.

Properties ofcode_scanning_tools

Name, Type, Description
`alerts_threshold`stringRequired The severity level at which code scanning results that raise alerts block a reference update. For more information on alert severity levels, see "About code scanning alerts." Can be one of:`none`,`errors`,`errors_and_warnings`,`all`
`security_alerts_threshold`stringRequired The severity level at which code scanning results that raise security alerts block a reference update. For more information on security severity levels, see "About code scanning alerts." Can be one of:`none`,`critical`,`high_or_higher`,`medium_or_higher`,`all`
`tool`stringRequired The name of a code scanning tool

copilot_code_reviewobject

Request Copilot code review for new pull requests automatically if the author has access to Copilot code review and their premium requests quota has not reached the limit.

Properties ofcopilot_code_review

Name, Type, Description

typestringRequired

Value:copilot_code_review

parametersobject

Properties ofparameters

Name, Type, Description
`review_draft_pull_requests`boolean Copilot automatically reviews draft pull requests before they are marked as ready for review.
`review_on_push`boolean Copilot automatically reviews each new push to the pull request.

HTTP response status codes for "Create a repository ruleset"

Status code	Description
`201`	Created
`404`	Resource not found
`500`	Internal Error

Code samples for "Create a repository ruleset"

Request example

post/repos/{owner}/{repo}/rulesets

curl -L \  -X POST \  -H "Accept: application/vnd.github+json" \  -H "Authorization: Bearer <YOUR-TOKEN>" \  -H "X-GitHub-Api-Version: 2022-11-28" \  https://api.github.com/repos/OWNER/REPO/rulesets \  -d '{"name":"super cool ruleset","target":"branch","enforcement":"active","bypass_actors":[{"actor_id":234,"actor_type":"Team","bypass_mode":"always"}],"conditions":{"ref_name":{"include":["refs/heads/main","refs/heads/master"],"exclude":["refs/heads/dev*"]}},"rules":[{"type":"commit_author_email_pattern","parameters":{"operator":"contains","pattern":"github"}}]}'

Response

Status: 201

{  "id": 42,  "name": "super cool ruleset",  "target": "branch",  "source_type": "Repository",  "source": "monalisa/my-repo",  "enforcement": "active",  "bypass_actors": [    {      "actor_id": 234,      "actor_type": "Team",      "bypass_mode": "always"    }  ],  "conditions": {    "ref_name": {      "include": [        "refs/heads/main",        "refs/heads/master"      ],      "exclude": [        "refs/heads/dev*"      ]    }  },  "rules": [    {      "type": "commit_author_email_pattern",      "parameters": {        "operator": "contains",        "pattern": "github"      }    }  ],  "node_id": "RRS_lACkVXNlcgQB",  "_links": {    "self": {      "href": "https://api.github.com/repos/monalisa/my-repo/rulesets/42"    },    "html": {      "href": "https://github.com/monalisa/my-repo/rules/42"    }  },  "created_at": "2023-07-15T08:43:03Z",  "updated_at": "2023-08-23T16:29:47Z"}

Get a repository ruleset

Get a ruleset for a repository.

Note: To prevent leaking sensitive information, thebypass_actors property is only returned if the usermaking the API request has write access to the ruleset.

Fine-grained access tokens for "Get a repository ruleset"

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

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

"Metadata" repository permissions (read)

This endpoint can be used without authentication or the aforementioned permissions if only public resources are requested.

Parameters for "Get a repository ruleset"

Headers
Name, Type, Description
`accept`string Setting to`application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository without the`.git` extension. The name is not case sensitive.
`ruleset_id`integerRequired The ID of the ruleset.

Query parameters
Name, Type, Description
`includes_parents`boolean Include rulesets configured at higher levels that apply to this repository Default:`true`

HTTP response status codes for "Get a repository ruleset"

Status code	Description
`200`	OK
`404`	Resource not found
`500`	Internal Error

Code samples for "Get a repository ruleset"

Request example

get/repos/{owner}/{repo}/rulesets/{ruleset_id}

curl -L \  -H "Accept: application/vnd.github+json" \  -H "Authorization: Bearer <YOUR-TOKEN>" \  -H "X-GitHub-Api-Version: 2022-11-28" \  https://api.github.com/repos/OWNER/REPO/rulesets/RULESET_ID

Response

Status: 200

{  "id": 42,  "name": "super cool ruleset",  "target": "branch",  "source_type": "Repository",  "source": "monalisa/my-repo",  "enforcement": "active",  "bypass_actors": [    {      "actor_id": 234,      "actor_type": "Team",      "bypass_mode": "always"    }  ],  "conditions": {    "ref_name": {      "include": [        "refs/heads/main",        "refs/heads/master"      ],      "exclude": [        "refs/heads/dev*"      ]    }  },  "rules": [    {      "type": "commit_author_email_pattern",      "parameters": {        "operator": "contains",        "pattern": "github"      }    }  ],  "node_id": "RRS_lACkVXNlcgQB",  "_links": {    "self": {      "href": "https://api.github.com/repos/monalisa/my-repo/rulesets/42"    },    "html": {      "href": "https://github.com/monalisa/my-repo/rules/42"    }  },  "created_at": "2023-07-15T08:43:03Z",  "updated_at": "2023-08-23T16:29:47Z"}

Update a repository ruleset

Update a ruleset for a repository.

Fine-grained access tokens for "Update a repository ruleset"

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

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

"Administration" repository permissions (write)

Parameters for "Update a repository ruleset"

Headers
Name, Type, Description
`accept`string Setting to`application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository without the`.git` extension. The name is not case sensitive.
`ruleset_id`integerRequired The ID of the ruleset.

Name, Type, Description

namestring

The name of the ruleset.

targetstring

The target of the ruleset

Can be one of:branch,tag,push

enforcementstring

Can be one of:disabled,active,evaluate

bypass_actorsarray of objects

The actors that can bypass the rules in this ruleset

Properties ofbypass_actors

Name, Type, Description
`actor_id`integer or null The ID of the actor that can bypass a ruleset. Required for`Integration`,`RepositoryRole`, and`Team` actor types. If`actor_type` is`OrganizationAdmin`, this should be`1`. If`actor_type` is`DeployKey`, this should be null.`OrganizationAdmin` is not applicable for personal repositories.
`actor_type`stringRequired The type of actor that can bypass a ruleset. Can be one of:`Integration`,`OrganizationAdmin`,`RepositoryRole`,`Team`,`DeployKey`
`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`

conditionsobject

Parameters for a repository ruleset ref name condition

Properties ofconditions

Name, Type, Description

ref_nameobject

Properties ofref_name

Name, Type, Description
`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.

rulesarray of objects

An array of rules within the ruleset.

Can be one of these objects:

Name, Type, Description

creationobject

Only allow users with bypass permission to create matching refs.

Properties ofcreation

Name, Type, Description
`type`stringRequired Value:`creation`

updateobject

Only allow users with bypass permission to update matching refs.

Properties ofupdate

Name, Type, Description

typestringRequired

Value:update

parametersobject

Properties ofparameters

Name, Type, Description
`update_allows_fetch_and_merge`booleanRequired Branch can pull changes from its upstream repository

deletionobject

Only allow users with bypass permissions to delete matching refs.

Properties ofdeletion

Name, Type, Description
`type`stringRequired Value:`deletion`

required_linear_historyobject

Prevent merge commits from being pushed to matching refs.

Properties ofrequired_linear_history

Name, Type, Description
`type`stringRequired Value:`required_linear_history`

merge_queueobject

Merges must be performed via a merge queue.

Properties ofmerge_queue

Name, Type, Description

typestringRequired

Value:merge_queue

parametersobject

Properties ofparameters

Name, Type, Description
`check_response_timeout_minutes`integerRequired Maximum time for a required status check to report a conclusion. After this much time has elapsed, checks that have not reported a conclusion will be assumed to have failed
`grouping_strategy`stringRequired When set to ALLGREEN, the merge commit created by merge queue for each PR in the group must pass all required checks to merge. When set to HEADGREEN, only the commit at the head of the merge group, i.e. the commit containing changes from all of the PRs in the group, must pass its required checks to merge. Can be one of:`ALLGREEN`,`HEADGREEN`
`max_entries_to_build`integerRequired Limit the number of queued pull requests requesting checks and workflow runs at the same time.
`max_entries_to_merge`integerRequired The maximum number of PRs that will be merged together in a group.
`merge_method`stringRequired Method to use when merging changes from queued pull requests. Can be one of:`MERGE`,`SQUASH`,`REBASE`
`min_entries_to_merge`integerRequired The minimum number of PRs that will be merged together in a group.
`min_entries_to_merge_wait_minutes`integerRequired The time merge queue should wait after the first PR is added to the queue for the minimum group size to be met. After this time has elapsed, the minimum group size will be ignored and a smaller group will be merged.

required_deploymentsobject

Choose which environments must be successfully deployed to before refs can be pushed into a ref that matches this rule.

Properties ofrequired_deployments

Name, Type, Description

typestringRequired

Value:required_deployments

parametersobject

Properties ofparameters

Name, Type, Description
`required_deployment_environments`array of stringsRequired The environments that must be successfully deployed to before branches can be merged.

required_signaturesobject

Commits pushed to matching refs must have verified signatures.

Properties ofrequired_signatures

Name, Type, Description
`type`stringRequired Value:`required_signatures`

pull_requestobject

Require all commits be made to a non-target branch and submitted via a pull request before they can be merged.

Properties ofpull_request

Name, Type, Description

typestringRequired

Value:pull_request

parametersobject

Properties ofparameters

Name, Type, Description

allowed_merge_methodsarray of strings

Array of allowed merge methods. Allowed values includemerge,squash, andrebase. At least one option must be enabled.Supported values are:merge,squash,rebase

dismiss_stale_reviews_on_pushbooleanRequired

New, reviewable commits pushed will dismiss previous pull request review approvals.

require_code_owner_reviewbooleanRequired

Require an approving review in pull requests that modify files that have a designated code owner.

require_last_push_approvalbooleanRequired

Whether the most recent reviewable push must be approved by someone other than the person who pushed it.

required_approving_review_countintegerRequired

The number of approving reviews that are required before a pull request can be merged.

required_review_thread_resolutionbooleanRequired

All conversations on code must be resolved before a pull request can be merged.

required_reviewersarray of objects

Note

required_reviewers is in beta and subject to change.

A collection of reviewers and associated file patterns. Each reviewer has a list of file patterns which determine the files that reviewer is required to review.

Properties ofrequired_reviewers

Name, Type, Description

file_patternsarray of stringsRequired

Array of file patterns. Pull requests which change matching files must be approved by the specified team. File patterns use fnmatch syntax.

minimum_approvalsintegerRequired

Minimum number of approvals required from the specified team. If set to zero, the team will be added to the pull request but approval is optional.

reviewerobjectRequired

A required reviewing team

Properties ofreviewer

Name, Type, Description
`id`integerRequired ID of the reviewer which must review changes to matching files.
`type`stringRequired The type of the reviewer Value:`Team`

required_status_checksobject

Choose which status checks must pass before the ref is updated. When enabled, commits must first be pushed to another ref where the checks pass.

Properties ofrequired_status_checks

Name, Type, Description

typestringRequired

Value:required_status_checks

parametersobject

Properties ofparameters

Name, Type, Description

do_not_enforce_on_createboolean

Allow repositories and branches to be created if a check would otherwise prohibit it.

required_status_checksarray of objectsRequired

Status checks that are required.

Properties ofrequired_status_checks

Name, Type, Description
`context`stringRequired The status check context name that must be present on the commit.
`integration_id`integer The optional integration ID that this status check must originate from.

strict_required_status_checks_policybooleanRequired

Whether pull requests targeting a matching branch must be tested with the latest code. This setting will not take effect unless at least one status check is enabled.

non_fast_forwardobject

Prevent users with push access from force pushing to refs.

Properties ofnon_fast_forward

Name, Type, Description
`type`stringRequired Value:`non_fast_forward`

commit_message_patternobject

Parameters to be used for the commit_message_pattern rule

Properties ofcommit_message_pattern

Name, Type, Description

typestringRequired

Value:commit_message_pattern

parametersobject

Properties ofparameters

Name, Type, Description
`name`string How this rule will appear to users.
`negate`boolean If true, the rule will fail if the pattern matches.
`operator`stringRequired The operator to use for matching. Can be one of:`starts_with`,`ends_with`,`contains`,`regex`
`pattern`stringRequired The pattern to match with.

commit_author_email_patternobject

Parameters to be used for the commit_author_email_pattern rule

Properties ofcommit_author_email_pattern

Name, Type, Description

typestringRequired

Value:commit_author_email_pattern

parametersobject

Properties ofparameters

Name, Type, Description
`name`string How this rule will appear to users.
`negate`boolean If true, the rule will fail if the pattern matches.
`operator`stringRequired The operator to use for matching. Can be one of:`starts_with`,`ends_with`,`contains`,`regex`
`pattern`stringRequired The pattern to match with.

committer_email_patternobject

Parameters to be used for the committer_email_pattern rule

Properties ofcommitter_email_pattern

Name, Type, Description

typestringRequired

Value:committer_email_pattern

parametersobject

Properties ofparameters

Name, Type, Description
`name`string How this rule will appear to users.
`negate`boolean If true, the rule will fail if the pattern matches.
`operator`stringRequired The operator to use for matching. Can be one of:`starts_with`,`ends_with`,`contains`,`regex`
`pattern`stringRequired The pattern to match with.

branch_name_patternobject

Parameters to be used for the branch_name_pattern rule

Properties ofbranch_name_pattern

Name, Type, Description

typestringRequired

Value:branch_name_pattern

parametersobject

Properties ofparameters

Name, Type, Description
`name`string How this rule will appear to users.
`negate`boolean If true, the rule will fail if the pattern matches.
`operator`stringRequired The operator to use for matching. Can be one of:`starts_with`,`ends_with`,`contains`,`regex`
`pattern`stringRequired The pattern to match with.

tag_name_patternobject

Parameters to be used for the tag_name_pattern rule

Properties oftag_name_pattern

Name, Type, Description

typestringRequired

Value:tag_name_pattern

parametersobject

Properties ofparameters

Name, Type, Description
`name`string How this rule will appear to users.
`negate`boolean If true, the rule will fail if the pattern matches.
`operator`stringRequired The operator to use for matching. Can be one of:`starts_with`,`ends_with`,`contains`,`regex`
`pattern`stringRequired The pattern to match with.

file_path_restrictionobject

Prevent commits that include changes in specified file and folder paths from being pushed to the commit graph. This includes absolute paths that contain file names.

Properties offile_path_restriction

Name, Type, Description

typestringRequired

Value:file_path_restriction

parametersobject

Properties ofparameters

Name, Type, Description
`restricted_file_paths`array of stringsRequired The file paths that are restricted from being pushed to the commit graph.

max_file_path_lengthobject

Prevent commits that include file paths that exceed the specified character limit from being pushed to the commit graph.

Properties ofmax_file_path_length

Name, Type, Description

typestringRequired

Value:max_file_path_length

parametersobject

Properties ofparameters

Name, Type, Description
`max_file_path_length`integerRequired The maximum amount of characters allowed in file paths.

file_extension_restrictionobject

Prevent commits that include files with specified file extensions from being pushed to the commit graph.

Properties offile_extension_restriction

Name, Type, Description

typestringRequired

Value:file_extension_restriction

parametersobject

Properties ofparameters

Name, Type, Description
`restricted_file_extensions`array of stringsRequired The file extensions that are restricted from being pushed to the commit graph.

max_file_sizeobject

Prevent commits with individual files that exceed the specified limit from being pushed to the commit graph.

Properties ofmax_file_size

Name, Type, Description

typestringRequired

Value:max_file_size

parametersobject

Properties ofparameters

Name, Type, Description
`max_file_size`integerRequired The maximum file size allowed in megabytes. This limit does not apply to Git Large File Storage (Git LFS).

workflowsobject

Require all changes made to a targeted branch to pass the specified workflows before they can be merged.

Properties ofworkflows

Name, Type, Description

typestringRequired

Value:workflows

parametersobject

Properties ofparameters

Name, Type, Description

do_not_enforce_on_createboolean

Allow repositories and branches to be created if a check would otherwise prohibit it.

workflowsarray of objectsRequired

Workflows that must pass for this rule to pass.

Properties ofworkflows

Name, Type, Description
`path`stringRequired The path to the workflow file
`ref`string The ref (branch or tag) of the workflow file to use
`repository_id`integerRequired The ID of the repository where the workflow is defined
`sha`string The commit SHA of the workflow file to use

code_scanningobject

Properties ofcode_scanning

Name, Type, Description

typestringRequired

Value:code_scanning

parametersobject

Properties ofparameters

Name, Type, Description

code_scanning_toolsarray of objectsRequired

Tools that must provide code scanning results for this rule to pass.

Properties ofcode_scanning_tools

Name, Type, Description
`alerts_threshold`stringRequired The severity level at which code scanning results that raise alerts block a reference update. For more information on alert severity levels, see "About code scanning alerts." Can be one of:`none`,`errors`,`errors_and_warnings`,`all`
`security_alerts_threshold`stringRequired The severity level at which code scanning results that raise security alerts block a reference update. For more information on security severity levels, see "About code scanning alerts." Can be one of:`none`,`critical`,`high_or_higher`,`medium_or_higher`,`all`
`tool`stringRequired The name of a code scanning tool

copilot_code_reviewobject

Request Copilot code review for new pull requests automatically if the author has access to Copilot code review and their premium requests quota has not reached the limit.

Properties ofcopilot_code_review

Name, Type, Description

typestringRequired

Value:copilot_code_review

parametersobject

Properties ofparameters

Name, Type, Description
`review_draft_pull_requests`boolean Copilot automatically reviews draft pull requests before they are marked as ready for review.
`review_on_push`boolean Copilot automatically reviews each new push to the pull request.

HTTP response status codes for "Update a repository ruleset"

Status code	Description
`200`	OK
`404`	Resource not found
`500`	Internal Error

Code samples for "Update a repository ruleset"

Request example

put/repos/{owner}/{repo}/rulesets/{ruleset_id}

curl -L \  -X PUT \  -H "Accept: application/vnd.github+json" \  -H "Authorization: Bearer <YOUR-TOKEN>" \  -H "X-GitHub-Api-Version: 2022-11-28" \  https://api.github.com/repos/OWNER/REPO/rulesets/RULESET_ID \  -d '{"name":"super cool ruleset","target":"branch","enforcement":"active","bypass_actors":[{"actor_id":234,"actor_type":"Team","bypass_mode":"always"}],"conditions":{"ref_name":{"include":["refs/heads/main","refs/heads/master"],"exclude":["refs/heads/dev*"]}},"rules":[{"type":"commit_author_email_pattern","parameters":{"operator":"contains","pattern":"github"}}]}'

Response

Status: 200

{  "id": 42,  "name": "super cool ruleset",  "target": "branch",  "source_type": "Repository",  "source": "monalisa/my-repo",  "enforcement": "active",  "bypass_actors": [    {      "actor_id": 234,      "actor_type": "Team",      "bypass_mode": "always"    }  ],  "conditions": {    "ref_name": {      "include": [        "refs/heads/main",        "refs/heads/master"      ],      "exclude": [        "refs/heads/dev*"      ]    }  },  "rules": [    {      "type": "commit_author_email_pattern",      "parameters": {        "operator": "contains",        "pattern": "github"      }    }  ],  "node_id": "RRS_lACkVXNlcgQB",  "_links": {    "self": {      "href": "https://api.github.com/repos/monalisa/my-repo/rulesets/42"    },    "html": {      "href": "https://github.com/monalisa/my-repo/rules/42"    }  },  "created_at": "2023-07-15T08:43:03Z",  "updated_at": "2023-08-23T16:29:47Z"}

Delete a repository ruleset

Delete a ruleset for a repository.

Fine-grained access tokens for "Delete a repository ruleset"

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

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

"Administration" repository permissions (write)

Parameters for "Delete a repository ruleset"

Headers
Name, Type, Description
`accept`string Setting to`application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository without the`.git` extension. The name is not case sensitive.
`ruleset_id`integerRequired The ID of the ruleset.

HTTP response status codes for "Delete a repository ruleset"

Status code	Description
`204`	No Content
`404`	Resource not found
`500`	Internal Error

Code samples for "Delete a repository ruleset"

Request example

delete/repos/{owner}/{repo}/rulesets/{ruleset_id}

curl -L \  -X DELETE \  -H "Accept: application/vnd.github+json" \  -H "Authorization: Bearer <YOUR-TOKEN>" \  -H "X-GitHub-Api-Version: 2022-11-28" \  https://api.github.com/repos/OWNER/REPO/rulesets/RULESET_ID

Response

Status: 204

Get repository ruleset history

Get the history of a repository ruleset.

Fine-grained access tokens for "Get repository ruleset history"

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

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

"Administration" repository permissions (write)

Parameters for "Get repository ruleset history"

Headers
Name, Type, Description
`accept`string Setting to`application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository without the`.git` extension. The name is not case sensitive.
`ruleset_id`integerRequired The ID of the ruleset.

Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default:`30`
`page`integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default:`1`

HTTP response status codes for "Get repository ruleset history"

Status code	Description
`200`	OK
`404`	Resource not found
`500`	Internal Error

Code samples for "Get repository ruleset history"

Request example

get/repos/{owner}/{repo}/rulesets/{ruleset_id}/history

curl -L \  -H "Accept: application/vnd.github+json" \  -H "Authorization: Bearer <YOUR-TOKEN>" \  -H "X-GitHub-Api-Version: 2022-11-28" \  https://api.github.com/repos/OWNER/REPO/rulesets/RULESET_ID/history

Response

Status: 200

[  {    "version_id": 3,    "actor": {      "id": 1,      "type": "User"    },    "updated_at": "2024-010-23T16:29:47Z"  },  {    "version_id": 2,    "actor": {      "id": 2,      "type": "User"    },    "updated_at": "2024-09-23T16:29:47Z"  },  {    "version_id": 1,    "actor": {      "id": 1,      "type": "User"    },    "updated_at": "2024-08-23T16:29:47Z"  }]

Get repository ruleset version

Get a version of a repository ruleset.

Fine-grained access tokens for "Get repository ruleset version"

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

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

"Administration" repository permissions (write)

Parameters for "Get repository ruleset version"

Headers
Name, Type, Description
`accept`string Setting to`application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository without the`.git` extension. The name is not case sensitive.
`ruleset_id`integerRequired The ID of the ruleset.
`version_id`integerRequired The ID of the version

HTTP response status codes for "Get repository ruleset version"

Status code	Description
`200`	OK
`404`	Resource not found
`500`	Internal Error

Code samples for "Get repository ruleset version"

Request example

get/repos/{owner}/{repo}/rulesets/{ruleset_id}/history/{version_id}

curl -L \  -H "Accept: application/vnd.github+json" \  -H "Authorization: Bearer <YOUR-TOKEN>" \  -H "X-GitHub-Api-Version: 2022-11-28" \  https://api.github.com/repos/OWNER/REPO/rulesets/RULESET_ID/history/VERSION_ID

Response

Status: 200

[  {    "version_id": 3,    "actor": {      "id": 1,      "type": "User"    },    "updated_at": "2024-010-23T16:29:47Z",    "state": {      "id": 42,      "name": "super cool ruleset",      "target": "branch",      "source_type": "Repository",      "source": "monalisa/my-repo",      "enforcement": "active",      "bypass_actors": [        {          "actor_id": 234,          "actor_type": "Team",          "bypass_mode": "always"        }      ],      "conditions": {        "ref_name": {          "include": [            "refs/heads/main",            "refs/heads/master"          ],          "exclude": [            "refs/heads/dev*"          ]        }      },      "rules": [        {          "type": "commit_author_email_pattern",          "parameters": {            "operator": "contains",            "pattern": "github"          }        }      ]    }  }]

Movatterモバイル変換

REST API endpoints for rules

Request example

Response

Request example

Response

Request example

Response

Request example

Response

Request example

Response

Request example

Response

Request example

Response

Request example

Response