Group push rules API

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use push rules to control the content and format of Git commits your repository accepts. The push rules endpoints are only available to group Owners and administrators.

Get the push rules of a group

Gets the push rules of a group.

GET /groups/:id/push_rule

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID of the group or URL-encoded path of the group.

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`author_email_regex`	string	Allow only commit author emails that match this regular expression.
`branch_name_regex`	string	Allow only branch names that match this regular expression.
`commit_committer_check`	boolean	If `true`, allows commits from users only if the committer email is one of their own verified emails.
`commit_committer_name_check`	boolean	If `true`, allows commits from users only if the commit author name is consistent with their GitLab account name.
`commit_message_negative_regex`	string	Reject commit messages matching this regular expression.
`commit_message_regex`	string	Allow only commit messages that match this regular expression.
`created_at`	string	Date and time when the push rule was created.
`deny_delete_tag`	boolean	If `true`, denies deleting a tag.
`file_name_regex`	string	Reject filenames matching this regular expression.
`id`	integer	The ID of the push rule.
`max_file_size`	integer	Maximum file size (MB) allowed.
`member_check`	boolean	If `true`, allows only GitLab users to author commits.
`prevent_secrets`	boolean	If `true`, rejects files that are likely to contain secrets.
`reject_non_dco_commits`	boolean	If `true`, rejects a commit when it’s not DCO certified.
`reject_unsigned_commits`	boolean	If `true`, rejects a commit when it’s not signed.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/2/push_rule"

Example response when push rules are configured with all settings disabled:

{
  "id": 1,
  "created_at": "2020-08-17T19:09:19.580Z",
  "commit_message_regex": "[a-zA-Z]",
  "commit_message_negative_regex": "[x+]",
  "branch_name_regex": "[a-z]",
  "author_email_regex": "^[A-Za-z0-9.]+@gitlab.com$",
  "file_name_regex": "(exe)$",
  "deny_delete_tag": false,
  "member_check": false,
  "prevent_secrets": false,
  "max_file_size": 0,
  "commit_committer_check": null,
  "commit_committer_name_check": false,
  "reject_unsigned_commits": null,
  "reject_non_dco_commits": null
}

If push rules were never configured for the group, returns 404 Not Found:

{
  "message": "404 Not Found"
}

This differs from the project push rules API, which returns HTTP 200 OK with the literal string "null" when no push rules are configured.

When disabled, some boolean attributes return null instead of false. For example:

commit_committer_check
reject_unsigned_commits
reject_non_dco_commits

Add push rules to a group

Adds push rules to the group. Use only if you haven’t defined any push rules so far.

POST /groups/:id/push_rule

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the group.
`author_email_regex`	string	No	Allow only commit author emails that match the regular expression provided in this attribute, for example, `@my-company.com$`.
`branch_name_regex`	string	No	Allow only branch names that match the regular expression provided in this attribute, for example, `(feature\|hotfix)\/.*`.
`commit_committer_check`	boolean	No	If `true`, allows commits from users only if the committer email is one of their own verified emails.
`commit_committer_name_check`	boolean	No	If `true`, allows commits from users only if the commit author name is consistent with their GitLab account name.
`commit_message_negative_regex`	string	No	Reject commit messages matching the regular expression provided in this attribute, for example, `ssh\:\/\/`.
`commit_message_regex`	string	No	If `true`, allows only commit messages that match the regular expression provided in this attribute, for example, `Fixed \d+\..*`.
`deny_delete_tag`	boolean	No	Deny deleting a tag.
`file_name_regex`	string	No	Reject filenames matching the regular expression provided in this attribute, for example, `(jar\|exe)$`.
`max_file_size`	integer	No	Maximum file size (MB) allowed.
`member_check`	boolean	No	If `true`, allows only GitLab users to author commits.
`prevent_secrets`	boolean	No	If `true`, rejects files that are likely to contain secrets.
`reject_non_dco_commits`	boolean	No	If `true`, rejects a commit when it’s not DCO certified.
`reject_unsigned_commits`	boolean	No	If `true`, rejects a commit when it’s not signed.

If successful, returns 201 Created and the following response attributes:

Attribute	Type	Description
`author_email_regex`	string	Allow only commit author emails that match this regular expression.
`branch_name_regex`	string	Allow only branch names that match this regular expression.
`commit_committer_check`	boolean	If `true`, allows commits from users only if the committer email is one of their own verified emails.
`commit_committer_name_check`	boolean	If `true`, allows commits from users only if the commit author name is consistent with their GitLab account name.
`commit_message_negative_regex`	string	Reject commit messages matching this regular expression.
`commit_message_regex`	string	If `true`, allows only commit messages that match this regular expression.
`created_at`	string	Date and time when the push rule was created.
`deny_delete_tag`	boolean	If `true`, denies deleting a tag.
`file_name_regex`	string	Reject filenames matching this regular expression.
`id`	integer	The ID of the push rule.
`max_file_size`	integer	Maximum file size (MB) allowed.
`member_check`	boolean	If `true`, allows only GitLab users to author commits.
`prevent_secrets`	boolean	If `true`, rejects files that are likely to contain secrets.
`reject_non_dco_commits`	boolean	If `true`, rejects a commit when it’s not DCO certified.
`reject_unsigned_commits`	boolean	If `true`, rejects a commit when it’s not signed.

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/19/push_rule?prevent_secrets=true"

Example response:

{
  "id": 1,
  "created_at": "2020-08-31T15:53:00.073Z",
  "commit_committer_check": false,
  "commit_committer_name_check": false,
  "reject_unsigned_commits": false,
  "reject_non_dco_commits": false,
  "commit_message_regex": "[a-zA-Z]",
  "commit_message_negative_regex": "[x+]",
  "branch_name_regex": null,
  "deny_delete_tag": false,
  "member_check": false,
  "prevent_secrets": true,
  "author_email_regex": "^[A-Za-z0-9.]+@gitlab.com$",
  "file_name_regex": null,
  "max_file_size": 100
}

Edit the push rules of a group

Edits the push rules for the group.

PUT /groups/:id/push_rule

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the group.
`author_email_regex`	string	No	Allow only commit author emails that match the regular expression provided in this attribute, for example, `@my-company.com$`.
`branch_name_regex`	string	No	Allow only branch names that match the regular expression provided in this attribute, for example, `(feature\|hotfix)\/.*`.
`commit_committer_check`	boolean	No	If `true`, allows commits from users only if the committer email is one of their own verified emails.
`commit_committer_name_check`	boolean	No	If `true`, allows commits from users only if the commit author name is consistent with their GitLab account name.
`commit_message_negative_regex`	string	No	Reject commit messages matching the regular expression provided in this attribute, for example, `ssh\:\/\/`.
`commit_message_regex`	string	No	If `true`, allows only commit messages that match the regular expression provided in this attribute, for example, `Fixed \d+\..*`.
`deny_delete_tag`	boolean	No	If `true`, denies deleting a tag.
`file_name_regex`	string	No	Reject filenames matching the regular expression provided in this attribute, for example, `(jar\|exe)$`.
`max_file_size`	integer	No	Maximum file size (MB) allowed.
`member_check`	boolean	No	If `true`, allows only GitLab users to author commits.
`prevent_secrets`	boolean	No	If `true`, rejects files that are likely to contain secrets.
`reject_non_dco_commits`	boolean	No	If `true`, rejects a commit when it’s not DCO certified.
`reject_unsigned_commits`	boolean	No	If `true`, rejects a commit when it’s not signed.

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`author_email_regex`	string	Allow only commit author emails that match this regular expression.
`branch_name_regex`	string	Allow only branch names that match this regular expression.
`commit_committer_check`	boolean	If `true`, allows commits from users only if the committer email is one of their own verified emails.
`commit_committer_name_check`	boolean	If `true`, allows commits from users only if the commit author name is consistent with their GitLab account name.
`commit_message_negative_regex`	string	Reject commit messages matching this regular expression.
`commit_message_regex`	string	If `true`, allows only commit messages that match this regular expression.
`created_at`	string	Date and time when the push rule was created.
`deny_delete_tag`	boolean	If `true`, denies deleting a tag.
`file_name_regex`	string	Reject filenames matching this regular expression.
`id`	integer	The ID of the push rule.
`max_file_size`	integer	Maximum file size (MB) allowed.
`member_check`	boolean	If `true`, allows only GitLab users to author commits.
`prevent_secrets`	boolean	If `true`, rejects files that are likely to contain secrets.
`reject_non_dco_commits`	boolean	If `true`, rejects a commit when it’s not DCO certified.
`reject_unsigned_commits`	boolean	If `true`, rejects a commit when it’s not signed.

Example request:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/19/push_rule?member_check=true"

Example response:

{
  "id": 19,
  "created_at": "2020-08-31T15:53:00.073Z",
  "commit_committer_check": false,
  "commit_committer_name_check": false,
  "reject_unsigned_commits": false,
  "reject_non_dco_commits": false,
  "commit_message_regex": "[a-zA-Z]",
  "commit_message_negative_regex": "[x+]",
  "branch_name_regex": null,
  "deny_delete_tag": false,
  "member_check": true,
  "prevent_secrets": false,
  "author_email_regex": "^[A-Za-z0-9.]+@staging.gitlab.com$",
  "file_name_regex": null,
  "max_file_size": 100
}

Delete the push rules of a group

Deletes all the push rules of a group.

DELETE /groups/:id/push_rule

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	The ID or URL-encoded path of the group.

If successful, returns 204 No Content with no response body.

Example request:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/19/push_rule"