Project push rules API

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

Use the project push rules API to manage push rules for projects.

GitLab uses RE2 syntax for all regular expressions in push rules.

Get project push rules

Get the push rules of a project.

GET /projects/:id/push_rule

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.

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

AttributeTypeDescription
author_email_regexstringAll commit author emails must match this regular expression.
branch_name_regexstringAll branch names must match this regular expression.
commit_committer_checkbooleanIf true, users can only push commits to this repository if the committer email is one of their own verified emails.
commit_committer_name_checkbooleanIf true, users can only push commits to this repository if the commit author name is consistent with their GitLab account name.
commit_message_negative_regexstringNo commit message is allowed to match this regular expression.
commit_message_regexstringAll commit messages must match this regular expression.
created_atstringDate and time when the push rule was created.
deny_delete_tagbooleanIf true, denies deleting a tag.
file_name_regexstringAll committed filenames must not match this regular expression.
idintegerID of the push rule.
max_file_sizeintegerMaximum file size (MB).
member_checkbooleanIf true, restricts commits by author (email) to existing GitLab users.
prevent_secretsbooleanIf true, GitLab rejects any files that are likely to contain secrets.
project_idintegerID of the project.
reject_non_dco_commitsbooleanIf true, rejects commits when not DCO certified.
reject_unsigned_commitsbooleanIf true, rejects commits when not signed.

If push rules were never configured for the project, this endpoint returns a response with value null instead of a 404 error.

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

  • commit_committer_check
  • reject_unsigned_commits
  • reject_non_dco_commits

Example request:

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

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

{
  "id": 1,
  "project_id": 3,
  "created_at": "2012-10-12T17:04:47Z",
  "commit_message_regex": "Fixes \\d+\\..*",
  "commit_message_negative_regex": "ssh\\:\\/\\/",
  "branch_name_regex": "",
  "deny_delete_tag": false,
  "member_check": false,
  "prevent_secrets": false,
  "author_email_regex": "",
  "file_name_regex": "",
  "max_file_size": 0,
  "commit_committer_check": null,
  "commit_committer_name_check": false,
  "reject_unsigned_commits": null,
  "reject_non_dco_commits": null
}

Add a project push rule

Add a push rule to a specified project.

POST /projects/:id/push_rule

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.
author_email_regexstringNoAll commit author emails must match this regular expression.
branch_name_regexstringNoAll branch names must match this regular expression.
commit_committer_checkbooleanNoIf true, users can only push commits to this repository if the committer email is one of their own verified emails.
commit_committer_name_checkbooleanNoIf true, users can only push commits to this repository if the commit author name is consistent with their GitLab account name.
commit_message_negative_regexstringNoNo commit message is allowed to match this regular expression.
commit_message_regexstringNoAll commit messages must match this regular expression.
deny_delete_tagbooleanNoIf true, denies deleting a tag.
file_name_regexstringNoAll committed filenames must not match this regular expression.
max_file_sizeintegerNoMaximum file size (MB).
member_checkbooleanNoIf true, restricts commits by author (email) to existing GitLab users.
prevent_secretsbooleanNoIf true, GitLab rejects any files that are likely to contain secrets.
reject_non_dco_commitsbooleanNoIf true, rejects commits when not DCO certified.
reject_unsigned_commitsbooleanNoIf true, rejects commits when not signed.

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

AttributeTypeDescription
author_email_regexstringAll commit author emails must match this regular expression.
branch_name_regexstringAll branch names must match this regular expression.
commit_committer_checkbooleanIf true, users can only push commits to this repository if the committer email is one of their own verified emails.
commit_committer_name_checkbooleanIf true, users can only push commits to this repository if the commit author name is consistent with their GitLab account name.
commit_message_negative_regexstringNo commit message is allowed to match this regular expression.
commit_message_regexstringAll commit messages must match this regular expression.
created_atstringDate and time when the push rule was created.
deny_delete_tagbooleanIf true, denies deleting a tag.
file_name_regexstringAll committed filenames must not match this regular expression.
idintegerID of the push rule.
max_file_sizeintegerMaximum file size (MB).
member_checkbooleanIf true, restricts commits by author (email) to existing GitLab users.
prevent_secretsbooleanIf true, GitLab rejects any files that are likely to contain secrets.
project_idintegerID of the project.
reject_non_dco_commitsbooleanIf true, rejects commits when not DCO certified.
reject_unsigned_commitsbooleanIf true, rejects commits when not signed.

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/3/push_rule" \
  --data "commit_message_regex=Fixes \\d+\\..*" \
  --data "deny_delete_tag=false"

Example response:

{
  "id": 1,
  "project_id": 3,
  "created_at": "2012-10-12T17:04:47Z",
  "commit_message_regex": "Fixes \\d+\\..*",
  "commit_message_negative_regex": "",
  "branch_name_regex": "",
  "deny_delete_tag": false,
  "member_check": false,
  "prevent_secrets": false,
  "author_email_regex": "",
  "file_name_regex": "",
  "max_file_size": 0,
  "commit_committer_check": false,
  "commit_committer_name_check": false,
  "reject_unsigned_commits": false,
  "reject_non_dco_commits": false
}

Edit project push rule

Edit a push rule for a specified project.

PUT /projects/:id/push_rule

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.
author_email_regexstringNoAll commit author emails must match this regular expression.
branch_name_regexstringNoAll branch names must match this regular expression.
commit_committer_checkbooleanNoIf true, users can only push commits to this repository if the committer email is one of their own verified emails.
commit_committer_name_checkbooleanNoIf true, users can only push commits to this repository if the commit author name is consistent with their GitLab account name.
commit_message_negative_regexstringNoNo commit message is allowed to match this regular expression.
commit_message_regexstringNoAll commit messages must match this regular expression.
deny_delete_tagbooleanNoIf true, denies deleting a tag.
file_name_regexstringNoAll committed filenames must not match this regular expression.
max_file_sizeintegerNoMaximum file size (MB).
member_checkbooleanNoIf true, restricts commits by author (email) to existing GitLab users.
prevent_secretsbooleanNoIf true, GitLab rejects any files that are likely to contain secrets.
reject_non_dco_commitsbooleanNoIf true, rejects commits when not DCO certified.
reject_unsigned_commitsbooleanNoIf true, rejects commits when not signed.

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

AttributeTypeDescription
author_email_regexstringAll commit author emails must match this regular expression.
branch_name_regexstringAll branch names must match this regular expression.
commit_committer_checkbooleanIf true, users can only push commits to this repository if the committer email is one of their own verified emails.
commit_committer_name_checkbooleanIf true, users can only push commits to this repository if the commit author name is consistent with their GitLab account name.
commit_message_negative_regexstringNo commit message is allowed to match this regular expression.
commit_message_regexstringAll commit messages must match this regular expression.
created_atstringDate and time when the push rule was created.
deny_delete_tagbooleanIf true, denies deleting a tag.
file_name_regexstringAll committed filenames must not match this regular expression.
idintegerID of the push rule.
max_file_sizeintegerMaximum file size (MB).
member_checkbooleanIf true, restricts commits by author (email) to existing GitLab users.
prevent_secretsbooleanIf true, GitLab rejects any files that are likely to contain secrets.
project_idintegerID of the project.
reject_non_dco_commitsbooleanIf true, rejects commits when not DCO certified.
reject_unsigned_commitsbooleanIf true, rejects commits when not signed.

Example request:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/3/push_rule" \
  --data "commit_message_regex=Fixes \\d+\\..*" \
  --data "deny_delete_tag=true"

Example response:

{
  "id": 1,
  "project_id": 3,
  "created_at": "2012-10-12T17:04:47Z",
  "commit_message_regex": "Fixes \\d+\\..*",
  "commit_message_negative_regex": "",
  "branch_name_regex": "",
  "deny_delete_tag": true,
  "member_check": false,
  "prevent_secrets": false,
  "author_email_regex": "",
  "file_name_regex": "",
  "max_file_size": 0,
  "commit_committer_check": false,
  "commit_committer_name_check": false,
  "reject_unsigned_commits": false,
  "reject_non_dco_commits": false
}

Delete project push rule

Delete a push rule from a project.

DELETE /projects/:id/push_rule

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.

If successful, returns 204 No Content.

Example request:

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