1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
|
---
stage: Create
group: Source Code
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments"
---
# Push rules **(PREMIUM)**
Push rules are [pre-receive Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) you
can enable in a user-friendly interface. Push rules give you more control over what
can and can't be pushed to your repository. While GitLab offers
[protected branches](../protected_branches.md), you may need more specific rules, such as:
- Evaluating the contents of a commit.
- Confirming commit messages match expected formats.
- Enforcing [branch name rules](branches/index.md#name-your-branch).
- Evaluating the details of files.
- Preventing Git tag removal.
GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions
in push rules. You can test them at the [regex101 regex tester](https://regex101.com/).
Each regular expression is limited to 255 characters.
For custom push rules use [server hooks](../../../administration/server_hooks.md).
## Enable global push rules
You can create push rules for all new projects to inherit, but they can be overridden
at the project level or the [group level](../../group/access_and_permissions.md#group-push-rules).
All projects created after you configure global push rules inherit this
configuration. However, each existing project must be updated manually, using the
process described in [Override global push rules per project](#override-global-push-rules-per-project).
Prerequisite:
- You must be an administrator.
To create global push rules:
1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
1. Select **Admin Area**.
1. Select **Push Rules**.
1. Expand **Push rules**.
1. Set the rule you want.
1. Select **Save push rules**.
## Override global push rules per project
The push rule of an individual project overrides the global push rule.
To override global push rules for a specific project, or to update the rules
for an existing project to match new global push rules:
1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project.
1. Select **Settings > Repository**.
1. Expand **Push rules**.
1. Set the rule you want.
1. Select **Save push rules**.
## Verify users
Use these rules to validate users who make commits.
- **Reject unverified users**: Users must have a [confirmed email address](../../../security/user_email_confirmation.md).
- **Check whether the commit author is a GitLab user**: The commit author and committer must have an email address that's been verified by GitLab.
- **Commit author's email**: Both the author's and committer's email addresses must match the regular expression.
To allow any email address, leave empty.
## Validate commit messages
Use these rules for your commit messages.
- **Require expression in commit messages**: Messages must match the
expression. To allow any commit message, leave empty.
Uses multiline mode, which can be disabled by using `(?-m)`.
For example, if every commit should reference a Jira issue
(like `Refactored css. Fixes JIRA-123.`), the regular expression would be
`JIRA\-\d+`.
- **Reject expression in commit messages**: Commit messages must not match
the expression. To allow any commit message, leave empty.
Uses multiline mode, which can be disabled by using `(?-m)`.
## Reject commits that aren't DCO certified
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98810) in GitLab 15.5.
Commits signed with the [Developer Certificate of Origin](https://developercertificate.org/) (DCO)
certify the contributor wrote, or has the right to submit, the code contributed in that commit.
You can require all commits to your project to comply with the DCO. This push rule requires a
`Signed-off-by:` trailer in every commit message, and rejects any commits that lack it.
## Validate branch names
To validate your branch names, enter a regular expression for **Branch name**.
To allow any branch name, leave empty. Your [default branch](branches/default.md)
is always allowed. Certain formats of branch names are restricted by default for
security purposes. Names with 40 hexadecimal characters, similar to Git commit hashes,
are prohibited.
Some validation examples:
- Branches must start with `JIRA-`.
```plaintext
`^JIRA-`
```
- Branches must end with `-JIRA`.
```plaintext
`-JIRA$`
```
- Branches must be between `4` and `15` characters long,
accepting only lowercase letters, numbers and dashes.
```plaintext
`^[a-z0-9\\-]{4,15}$`
```
## Prevent unintended consequences
Use these rules to prevent unintended consequences.
- **Reject unsigned commits**: Commit must be signed through [GPG](gpg_signed_commits/index.md). This rule
can block some legitimate commits [created in the Web IDE](#reject-unsigned-commits-push-rule-disables-web-ide),
and allow [unsigned commits created in the GitLab UI](#unsigned-commits-created-in-the-gitlab-ui).
- **Do not allow users to remove Git tags with `git push`**: Users cannot use `git push` to remove Git tags.
Users can still delete tags in the UI.
## Validate files
Use these rules to validate files contained in the commit.
- **Prevent pushing secret files**: Files must not contain [secrets](#prevent-pushing-secrets-to-the-repository).
- **Prohibited file names**: Files that do not exist in the repository
must not match the regular expression. To allow all file names, leave empty. See [common examples](#prohibit-files-by-name).
- **Maximum file size**: Added or updated files must not exceed this
file size (in MB). To allow files of any size, set to `0`. Files tracked by Git LFS are exempted.
### Prevent pushing secrets to the repository
> Moved to GitLab Premium in 13.9.
Never commit secrets, such as credential files and SSH private keys, to a version control
system. In GitLab, you can use a predefined list of files to block those files from a
repository. Merge requests that contain a file that matches the list are blocked.
This push rule does not restrict files already committed to the repository.
You must update the configuration of existing projects to use the rule, using the
process described in [Override global push rules per project](#override-global-push-rules-per-project).
Files blocked by this rule are listed below. For a complete list of criteria, refer to
[`files_denylist.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml).
- AWS CLI credential blobs:
- `.aws/credentials`
- `aws/credentials`
- `homefolder/aws/credentials`
- Private RSA SSH keys:
- `/ssh/id_rsa`
- `/.ssh/personal_rsa`
- `/config/server_rsa`
- `id_rsa`
- `.id_rsa`
- Private DSA SSH keys:
- `/ssh/id_dsa`
- `/.ssh/personal_dsa`
- `/config/server_dsa`
- `id_dsa`
- `.id_dsa`
- Private ED25519 SSH keys:
- `/ssh/id_ed25519`
- `/.ssh/personal_ed25519`
- `/config/server_ed25519`
- `id_ed25519`
- `.id_ed25519`
- Private ECDSA SSH keys:
- `/ssh/id_ecdsa`
- `/.ssh/personal_ecdsa`
- `/config/server_ecdsa`
- `id_ecdsa`
- `.id_ecdsa`
- Private ECDSA_SK SSH keys (GitLab 14.8 and later):
- `/ssh/id_ecdsa_sk`
- `/.ssh/personal_ecdsa_sk`
- `/config/server_ecdsa_sk`
- `id_ecdsa_sk`
- `.id_ecdsa_sk`
- Private ED25519_SK SSH keys (GitLab 14.8 and later):
- `/ssh/id_ed25519_sk`
- `/.ssh/personal_ed25519_sk`
- `/config/server_ed25519_sk`
- `id_ed25519_sk`
- `.id_ed25519_sk`
- Any files ending with these suffixes:
- `*.pem`
- `*.key`
- `*.history`
- `*_history`
### Prohibit files by name
> Moved to GitLab Premium in 13.9.
In Git, filenames include both the file's name, and all directories preceding the name.
When you `git push`, each filename in the push is compared to the regular expression
in **Prohibited file names**.
The regular expression in your **Prohibited file names** push rule can contain multiple,
independent matches to exclude. You can match file names broadly to any location in
your repository, or restrict only in certain locations. Filename matches can also
be partial, and exclude file types by extension.
These examples use regex (regular expressions) string boundary characters to match
the beginning of a string (`^`), and its end (`$`). They also include instances
where either the directory path or the filename can include `.` or `/`. Both of
these special regex characters must be escaped with a backslash `\\` if you want
to use them as normal characters in a match condition.
- **Prevent pushing `.exe` files to any location in the repository** - This regex
matches any filename that contains `.exe` at the end:
```plaintext
\.exe$
```
- **Prevent pushing a specific configuration file in the repository root**
```plaintext
^config\.yml$
```
- **Prevent pushing a specific configuration file in a known directory**
```plaintext
^directory-name\/config\.yml$
```
- **Prevent pushing a specific file to any location in the repository** - This example tests
for any file named `install.exe`. The parenthesized expression `(^|\/)` matches either
a file following a directory separator, or a file in the root directory of the repository:
```plaintext
(^|\/)install\.exe$
```
- **Combine all previous expressions into one expression** - The preceding expressions rely
on the end-of-string character `$`. We can move that part of each expression to the
end of the grouped collection of match conditions, where it is appended to all matches:
```plaintext
(\.exe|^config\.yml|^directory-name\/config\.yml|(^|\/)install\.exe)$
```
## Related topics
- [Git server hooks](../../../administration/server_hooks.md) (previously called server hooks), to create complex custom push rules
- [Signing commits with GPG](gpg_signed_commits/index.md)
- [Protected branches](../protected_branches.md)
## Troubleshooting
### Reject unsigned commits push rule disables Web IDE
In GitLab 13.10, if a project has the **Reject unsigned commits** push rule, the user cannot
create commits through the GitLab Web IDE.
To allow committing through the Web IDE on a project with this push rule, a GitLab administrator
must disable the feature flag `reject_unsigned_commits_by_gitlab`. [with a flag](../../../administration/feature_flags.md)
```ruby
Feature.disable(:reject_unsigned_commits_by_gitlab)
```
### Unsigned commits created in the GitLab UI
The **Reject unsigned commits** push rule ignores commits that are authenticated
and created by GitLab (either through the UI or API). When this push rule is
enabled, unsigned commits may still appear in the commit history if a commit was
created in GitLab itself. As expected, commits created outside GitLab and
pushed to the repository are rejected. For more information about this issue,
read [issue #19185](https://gitlab.com/gitlab-org/gitlab/-/issues/19185).
### Bulk update push rules for _all_ projects
To update the push rules to be the same for all projects,
you need to use [the rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session),
or write a script to update each project using the [Push Rules API endpoint](../../../api/projects.md#push-rules).
For example, to enable **Check whether the commit author is a GitLab user** and **Do not allow users to remove Git tags with `git push`** checkboxes,
and create a filter for allowing commits from a specific email domain only through rails console:
WARNING:
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
``` ruby
Project.find_each do |p|
pr = p.push_rule || PushRule.new(project: p)
# Check whether the commit author is a GitLab user
pr.member_check = true
# Do not allow users to remove Git tags with `git push`
pr.deny_delete_tag = true
# Commit author's email
pr.author_email_regex = '@domain\.com$'
pr.save!
end
```
|