rules

Creates, updates, deletes, gets or lists a rules resource.

Overview

Name	rules
Type	Resource
Id	github.repos.rules

Fields

The following fields are returned by SELECT queries:

get_branch_rules

Response

Name	Datatype	Description
ruleset_id	integer	The ID of the ruleset that includes this rule.
parameters	object
ruleset_source	string	The name of the source of the ruleset that includes this rule.
ruleset_source_type	string	The type of source for the ruleset that includes this rule. (Repository, Organization)
type	string	(creation)

get_repo_ruleset

Response

Name	Datatype	Description
id	integer	The ID of the ruleset
name	string	The name of the ruleset
node_id	string
_links	object
bypass_actors	array	The actors that can bypass the rules in this ruleset
conditions	object	Parameters for a repository ruleset ref name condition (title: Repository ruleset conditions for ref names)
created_at	string (date-time)
current_user_can_bypass	string	The bypass type of the user making the API request for this ruleset. This field is only returned when querying the repository-level endpoint. (always, pull_requests_only, never, exempt)
enforcement	string	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). (disabled, active, evaluate)
rules	array
source	string	The name of the source
source_type	string	The type of the source of the ruleset (Repository, Organization, Enterprise)
target	string	The target of the ruleset (branch, tag, push, repository)
updated_at	string (date-time)

get_org_ruleset

Response

Name	Datatype	Description
id	integer	The ID of the ruleset
name	string	The name of the ruleset
node_id	string
_links	object
bypass_actors	array	The actors that can bypass the rules in this ruleset
conditions	object	Parameters for a repository ruleset ref name condition (title: Repository ruleset conditions for ref names)
created_at	string (date-time)
current_user_can_bypass	string	The bypass type of the user making the API request for this ruleset. This field is only returned when querying the repository-level endpoint. (always, pull_requests_only, never, exempt)
enforcement	string	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). (disabled, active, evaluate)
rules	array
source	string	The name of the source
source_type	string	The type of the source of the ruleset (Repository, Organization, Enterprise)
target	string	The target of the ruleset (branch, tag, push, repository)
updated_at	string (date-time)

get_repo_rulesets

Response

Name	Datatype	Description
id	integer	The ID of the ruleset
name	string	The name of the ruleset
node_id	string
_links	object
bypass_actors	array	The actors that can bypass the rules in this ruleset
conditions	object	Parameters for a repository ruleset ref name condition (title: Repository ruleset conditions for ref names)
created_at	string (date-time)
current_user_can_bypass	string	The bypass type of the user making the API request for this ruleset. This field is only returned when querying the repository-level endpoint. (always, pull_requests_only, never, exempt)
enforcement	string	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). (disabled, active, evaluate)
rules	array
source	string	The name of the source
source_type	string	The type of the source of the ruleset (Repository, Organization, Enterprise)
target	string	The target of the ruleset (branch, tag, push, repository)
updated_at	string (date-time)

get_org_rulesets

Response

Name	Datatype	Description
id	integer	The ID of the ruleset
name	string	The name of the ruleset
node_id	string
_links	object
bypass_actors	array	The actors that can bypass the rules in this ruleset
conditions	object	Parameters for a repository ruleset ref name condition (title: Repository ruleset conditions for ref names)
created_at	string (date-time)
current_user_can_bypass	string	The bypass type of the user making the API request for this ruleset. This field is only returned when querying the repository-level endpoint. (always, pull_requests_only, never, exempt)
enforcement	string	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). (disabled, active, evaluate)
rules	array
source	string	The name of the source
source_type	string	The type of the source of the ruleset (Repository, Organization, Enterprise)
target	string	The target of the ruleset (branch, tag, push, repository)
updated_at	string (date-time)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_branch_rules	select	owner, repo, branch	per_page, page	Returns all active rules that apply to the specified branch. The branch does not need to exist; rules that would apply to a branch with that name will be returned. All active rules that apply will be returned, regardless of the level at which they are configured (e.g. repository or organization). Rules in rulesets with "evaluate" or "disabled" enforcement statuses are not returned.
get_repo_ruleset	select	owner, repo, ruleset_id	includes_parents	Get a ruleset for a repository. Note: To prevent leaking sensitive information, the bypass_actors property is only returned if the user making the API request has write access to the ruleset.
get_org_ruleset	select	org, ruleset_id		Get a repository ruleset for an organization. Note: To prevent leaking sensitive information, the bypass_actors property is only returned if the user making the API request has write access to the ruleset.
get_repo_rulesets	select	owner, repo	per_page, page, includes_parents, targets	Get all the rulesets for a repository.
get_org_rulesets	select	org	per_page, page, targets	Get all the repository rulesets for an organization.
create_repo_ruleset	insert	owner, repo, name, enforcement		Create a ruleset for a repository.
create_org_ruleset	insert	org, name, enforcement		Create a repository ruleset for an organization.
update_repo_ruleset	replace	owner, repo, ruleset_id		Update a ruleset for a repository.
update_org_ruleset	replace	org, ruleset_id		Update a ruleset for an organization.
delete_repo_ruleset	delete	owner, repo, ruleset_id		Delete a ruleset for a repository.
delete_org_ruleset	delete	org, ruleset_id		Delete a ruleset for an organization.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
branch	string	The name of the branch. Cannot contain wildcard characters. To use wildcard characters in branch names, use the GraphQL API.
org	string	The organization name. The name is not case sensitive.
owner	string	The account owner of the repository. The name is not case sensitive.
repo	string	The name of the repository without the .git extension. The name is not case sensitive.
ruleset_id	integer	The ID of the ruleset.
includes_parents	boolean	Include rulesets configured at higher levels that apply to this repository
page	integer	The page number of the results to fetch. For more information, see "Using pagination in the REST API."
per_page	integer	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
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.

SELECT examples

get_branch_rules

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

SELECT
ruleset_id,
parameters,
ruleset_source,
ruleset_source_type,
type
FROM github.repos.rules
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND branch = '{{ branch }}' -- required
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
;

get_repo_ruleset

Get a ruleset for a repository.

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

SELECT
id,
name,
node_id,
_links,
bypass_actors,
conditions,
created_at,
current_user_can_bypass,
enforcement,
rules,
source,
source_type,
target,
updated_at
FROM github.repos.rules
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND ruleset_id = '{{ ruleset_id }}' -- required
AND includes_parents = '{{ includes_parents }}'
;

get_org_ruleset

Get a repository ruleset for an organization.

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

SELECT
id,
name,
node_id,
_links,
bypass_actors,
conditions,
created_at,
current_user_can_bypass,
enforcement,
rules,
source,
source_type,
target,
updated_at
FROM github.repos.rules
WHERE org = '{{ org }}' -- required
AND ruleset_id = '{{ ruleset_id }}' -- required
;

get_repo_rulesets

Get all the rulesets for a repository.

SELECT
id,
name,
node_id,
_links,
bypass_actors,
conditions,
created_at,
current_user_can_bypass,
enforcement,
rules,
source,
source_type,
target,
updated_at
FROM github.repos.rules
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
AND includes_parents = '{{ includes_parents }}'
AND targets = '{{ targets }}'
;

get_org_rulesets

Get all the repository rulesets for an organization.

SELECT
id,
name,
node_id,
_links,
bypass_actors,
conditions,
created_at,
current_user_can_bypass,
enforcement,
rules,
source,
source_type,
target,
updated_at
FROM github.repos.rules
WHERE org = '{{ org }}' -- required
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
AND targets = '{{ targets }}'
;

INSERT examples

create_repo_ruleset

Create a ruleset for a repository.

INSERT INTO github.repos.rules (
name,
target,
enforcement,
bypass_actors,
conditions,
rules,
owner,
repo
)
SELECT 
'{{ name }}' /* required */,
'{{ target }}',
'{{ enforcement }}' /* required */,
'{{ bypass_actors }}',
'{{ conditions }}',
'{{ rules }}',
'{{ owner }}',
'{{ repo }}'
RETURNING
id,
name,
node_id,
_links,
bypass_actors,
conditions,
created_at,
current_user_can_bypass,
enforcement,
rules,
source,
source_type,
target,
updated_at
;

create_org_ruleset

Create a repository ruleset for an organization.

INSERT INTO github.repos.rules (
name,
target,
enforcement,
bypass_actors,
conditions,
rules,
org
)
SELECT 
'{{ name }}' /* required */,
'{{ target }}',
'{{ enforcement }}' /* required */,
'{{ bypass_actors }}',
'{{ conditions }}',
'{{ rules }}',
'{{ org }}'
RETURNING
id,
name,
node_id,
_links,
bypass_actors,
conditions,
created_at,
current_user_can_bypass,
enforcement,
rules,
source,
source_type,
target,
updated_at
;

Manifest

# Description fields are for documentation purposes
- name: rules
props:
  - name: owner
    value: "{{ owner }}"
    description: Required parameter for the rules resource.
  - name: repo
    value: "{{ repo }}"
    description: Required parameter for the rules resource.
  - name: org
    value: "{{ org }}"
    description: Required parameter for the rules resource.
  - name: name
    value: "{{ name }}"
    description: |
      The name of the ruleset.
  - name: target
    value: "{{ target }}"
    description: |
      The target of the ruleset
    valid_values: ['branch', 'tag', 'push', 'repository']
    default: branch
  - name: enforcement
    value: "{{ enforcement }}"
    description: |
      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).
    valid_values: ['disabled', 'active', 'evaluate']
  - name: bypass_actors
    description: |
      The actors that can bypass the rules in this ruleset
    value:
      - actor_id: {{ actor_id }}
        actor_type: "{{ actor_type }}"
        bypass_mode: "{{ bypass_mode }}"
  - name: conditions
    description: |
      Conditions for an organization ruleset.
      The branch and tag rulesets conditions object should contain both `repository_name` and `ref_name` properties, or both `repository_id` and `ref_name` properties, or both `repository_property` and `ref_name` properties.
      The push rulesets conditions object does not require the `ref_name` property.
      For repository policy rulesets, the conditions object should only contain the `repository_name`, the `repository_id`, or the `repository_property`.
    value:
      ref_name:
        include:
          - "{{ include }}"
        exclude:
          - "{{ exclude }}"
      repository_name:
        include:
          - "{{ include }}"
        exclude:
          - "{{ exclude }}"
        protected: {{ protected }}
      repository_id:
        repository_ids:
          - {{ repository_ids }}
      repository_property:
        include:
          - name: "{{ name }}"
            property_values: "{{ property_values }}"
            source: "{{ source }}"
        exclude:
          - name: "{{ name }}"
            property_values: "{{ property_values }}"
            source: "{{ source }}"
  - name: rules
    description: |
      An array of rules within the ruleset.
    value:
      - type: "{{ type }}"
        parameters:
          update_allows_fetch_and_merge: {{ update_allows_fetch_and_merge }}

REPLACE examples

update_repo_ruleset

Update a ruleset for a repository.

REPLACE github.repos.rules
SET 
name = '{{ name }}',
target = '{{ target }}',
enforcement = '{{ enforcement }}',
bypass_actors = '{{ bypass_actors }}',
conditions = '{{ conditions }}',
rules = '{{ rules }}'
WHERE 
owner = '{{ owner }}' --required
AND repo = '{{ repo }}' --required
AND ruleset_id = '{{ ruleset_id }}' --required
RETURNING
id,
name,
node_id,
_links,
bypass_actors,
conditions,
created_at,
current_user_can_bypass,
enforcement,
rules,
source,
source_type,
target,
updated_at;

update_org_ruleset

Update a ruleset for an organization.

REPLACE github.repos.rules
SET 
name = '{{ name }}',
target = '{{ target }}',
enforcement = '{{ enforcement }}',
bypass_actors = '{{ bypass_actors }}',
conditions = '{{ conditions }}',
rules = '{{ rules }}'
WHERE 
org = '{{ org }}' --required
AND ruleset_id = '{{ ruleset_id }}' --required
RETURNING
id,
name,
node_id,
_links,
bypass_actors,
conditions,
created_at,
current_user_can_bypass,
enforcement,
rules,
source,
source_type,
target,
updated_at;

DELETE examples

delete_repo_ruleset

Delete a ruleset for a repository.

DELETE FROM github.repos.rules
WHERE owner = '{{ owner }}' --required
AND repo = '{{ repo }}' --required
AND ruleset_id = '{{ ruleset_id }}' --required
;

delete_org_ruleset

Delete a ruleset for an organization.

DELETE FROM github.repos.rules
WHERE org = '{{ org }}' --required
AND ruleset_id = '{{ ruleset_id }}' --required
;