diff options
Diffstat (limited to 'doc/user/project/repository/push_rules.md')
-rw-r--r-- | doc/user/project/repository/push_rules.md | 299 |
1 files changed, 147 insertions, 152 deletions
diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index bb473a2830b..994cf78d98a 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -6,148 +6,136 @@ info: "To determine the technical writer assigned to the Stage/Group associated # Push rules **(PREMIUM)** -Gain additional control over what can and can't be pushed to your repository by using -regular expressions to reject pushes based on commit contents, branch names or file details. - -GitLab already offers [protected branches](../protected_branches.md), but there are -cases when you need some specific rules. Some common scenarios: preventing Git tag removal, or -enforcing a special format for commit messages. - 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. They are defined either: +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: -- Globally if you are an administrator. -- Per project, so you can have different rules applied to different - projects depending on your needs. +- Evaluating the contents of a commit. +- Confirming commit messages match expected formats. +- Enforcing branch name rules. +- Evaluating the details of files. +- Preventing Git tag removal. -## Use cases +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/). -Every push rule could have its own use case, but let's consider some examples. +For custom push rules use [server hooks](../../../administration/server_hooks.md). -### Commit messages with a specific reference +## Enable global push rules -Let's assume you have the following requirements for your workflow: +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/index.md#group-push-rules). -- every commit should reference a Jira issue, for example: `Refactored css. Fixes JIRA-123.` -- users should not be able to remove Git tags with `git push` +Prerequisite: -Write a regular expression that requires the mention -of a Jira issue in the commit message, like `JIRA\-\d+`. +- You must be an administrator. -Now when a user tries to push a commit with a message `Bugfix`, their push is -declined. Only pushing commits with messages like `Bugfix according to JIRA-123` -is accepted. +To create global push rules: -### Restrict branch names +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Push Rules**. +1. Expand **Push rules**. +1. Set the rule you want. +1. Select **Save push rules**. -If your company has a strict policy for branch names, you may want the branches to start -with a certain name. This approach enables different -GitLab CI/CD jobs (such as `feature`, `hotfix`, `docker`, `android`) that rely on the -branch name. +## Override global push rules per project -Your developers may not remember that policy, so they might push to -various branches, and CI pipelines might not work as expected. By restricting the -branch names globally in Push Rules, such mistakes are prevented. -All branch names that don't match your push rule are rejected. +The push rule of an individual project overrides the global push rule. +To override global push rules for a specific project: -Note that the name of your default branch is always allowed, regardless of the branch naming -regular expression (regex) specified. GitLab is configured this way -because merges typically have the default branch as their target. -If you have other target branches, include them in your regex. (See [Enabling push rules](#enabling-push-rules)). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Push rules**. +1. Set the rule you want. +1. Select **Save push rules**. -The default branch also defaults to being a [protected branch](../protected_branches.md), -which already limits users from pushing directly. +## Verify users -Some example regular expressions you can use in push rules: +Use these rules to validate users who make commits. -- `^JIRA-` Branches must start with `JIRA-`. -- `-JIRA$` Branches must end with `-JIRA`. -- `^[a-z0-9\\-]{4,15}$` Branches must be between `4` and `15` characters long, - accepting only lowercase letters, numbers and dashes. +- **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. -#### Default restricted branch names +## Validate commit messages -> Introduced in GitLab 12.10. +Use these rules for your commit messages. -By default, GitLab restricts certain formats of branch names for security purposes. -40-character hexadecimal names, similar to Git commit hashes, are prohibited. +- **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)`. -### Custom Push Rules **(PREMIUM SELF)** + 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)`. -It's possible to create custom push rules rather than the push rules available in -**Admin Area > Push Rules** by using more advanced server hooks. +## Validate branch names -See [server hooks](../../../administration/server_hooks.md) for more information. +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. -## Enabling push rules +Examples: -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/index.md#group-push-rules). +- Branches must start with `JIRA-`. -To create global push rules: + ```plaintext + `^JIRA-` + ``` -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Push Rules**. +- Branches must end with `-JIRA`. -To override global push rules in a project's settings: + ```plaintext + `-JIRA$` + ``` -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. -1. Expand **Push rules**. -1. Set the rule you want. -1. Select **Save push rules**. +- Branches must be between `4` and `15` characters long, + accepting only lowercase letters, numbers and dashes. -The following options are available: + ```plaintext + `^[a-z0-9\\-]{4,15}$` + ``` -| Push rule | Description | -|---------------------------------|-------------| -| Removal of tags with `git push` | Forbid users to remove Git tags with `git push`. Tags can be deleted through the web UI. | -| Check whether the commit author is a GitLab user | Restrict commits to existing GitLab users (checked against their emails). <sup>1</sup> | -| Reject unverified users | GitLab rejects any commit that was not committed by the same user as the user who pushed it, or where the committer's email address is not [confirmed](../../../security/user_email_confirmation.md). | -| Check whether commit is signed through GPG | Reject commit when it is not signed through GPG. Read [signing commits with GPG](gpg_signed_commits/index.md). | -| Prevent pushing secret files | GitLab rejects any files that are likely to contain secrets. See the [forbidden file names](#prevent-pushing-secrets-to-the-repository). | -| Require expression in commit messages | Only commit messages that match this regular expression are allowed to be pushed. <sup>2</sup> Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. | -| Reject expression in commit messages | Only commit messages that do not match this regular expression are allowed to be pushed. <sup>2</sup> Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. | -| Restrict by branch name | Only branch names that match this regular expression are allowed to be pushed. <sup>2</sup> Leave empty to allow all branch names. | -| Restrict by commit author's email | Only commit author's email that match this regular expression are allowed to be pushed. <sup>1</sup> <sup>2</sup> Leave empty to allow any email. | -| Prohibited file names | Any committed filenames that match this regular expression and do not already exist in the repository are not allowed to be pushed. <sup>2</sup> Leave empty to allow any filenames. See [common examples](#prohibited-file-names). | -| Maximum file size | Pushes that contain added or updated files that exceed this file size (in MB) are rejected. Set to 0 to allow files of any size. Files tracked by Git LFS are exempted. | +NOTE: +In GitLab 12.10 and later, certain formats of branch names are restricted by +default for security purposes. 40-character hexadecimal names, similar to Git +commit hashes, are prohibited. -1. Checks both the commit author and committer. -1. GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions in push rules, and you can test them at the [regex101 regex tester](https://regex101.com/). +## Prevent unintended consequences -### Caveat to "Reject unsigned commits" push rule +Use these rules to prevent unintended consequences. -This push rule ignores commits that are authenticated and created by GitLab -(either through the UI or API). When the **Reject unsigned commits** push rule is -enabled, unsigned commits may still show up 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 how GitLab -plans to fix this issue, read [issue #19185](https://gitlab.com/gitlab-org/gitlab/-/issues/19185). +- **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. -#### "Reject unsigned commits" push rule disables Web IDE +## Validate files -In 13.10, if a project has the "Reject unsigned commits" push rule, the user is not allowed to -commit through GitLab Web IDE. +Use these rules to validate files contained in the commit. -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`. This can be done through a -[rails console](../../../administration/operations/rails_console.md) and running: +- **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. -```ruby -Feature.disable(:reject_unsigned_commits_by_gitlab) -``` - -## Prevent pushing secrets to the repository +### Prevent pushing secrets to the repository > Moved to GitLab Premium in 13.9. -Secrets, such as credential files and SSH private keys, should never be committed to a version control +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. Any merge request containing a file matching the list is blocked from being merged. -Files already committed to the repository are not restricted by this push rule. +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. -Files blocked by this rule are listed below. For a complete list of criteria, see +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: @@ -211,78 +199,85 @@ Files blocked by this rule are listed below. For a complete list of criteria, se - `*.history` - `*_history` -### Prevent pushing secrets to all projects +### Prohibit files by name -To set a global push rule to prevent pushing secrets to all projects: +> Moved to GitLab Premium in 13.9. -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Push Rules**. -1. Expand **Push rules**. -1. Select **Prevent pushing secret files**. -1. Select **Save push rules**. +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**. -### Prevent pushing secrets to a project +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. -The push rule of a project overrides the global push rule. +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. -To prevent pushing secrets to a project: +- **Prevent pushing `.exe` files to any location in the repository** - This regex + matches any filename that contains `.exe` at the end: -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. -1. Expand **Push rules**. -1. Select **Prevent pushing secret files**. -1. Select **Save push rules**. + ```plaintext + \.exe$ + ``` -## Prohibited file names +- **Prevent pushing a specific configuration file in the repository root** -> Moved to GitLab Premium in 13.9. + ```plaintext + ^config\.yml$ + ``` -Each filename contained in a Git push is compared to the regular expression in this field. Filenames in Git consist of both the file's name and any directory that may precede it. A singular regular expression can contain multiple independent matches used as exclusions. File names can be broadly matched to any location in the repository, or restricted to specific locations. Filenames can also be partial matches used to exclude file types by extension. +- **Prevent pushing a specific configuration file in a known directory** -The following examples make use of regex string boundary characters which match the beginning of a string (`^`), and the end (`$`). They also include instances where either the directory path or the filename can include `.` or `/`. Both of these special regex characters have to be escaped with a backslash `\\` to be used as normal characters in a match condition. + ```plaintext + ^directory-name\/config\.yml$ + ``` -Example: prevent pushing any `.exe` files to any location in the repository. This uses a partial match, which matches any filename that contains `.exe` at the end: +- **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 -\.exe$ -``` + ```plaintext + (^|\/)install\.exe$ + ``` -Example: prevent a specific configuration file in the repository root from being pushed: +- **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 -^config\.yml$ -``` + ```plaintext + (\.exe|^config\.yml|^directory-name\/config\.yml|(^|\/)install\.exe)$ + ``` -Example: prevent a specific configuration file in a known directory from being pushed: +## Related topics -```plaintext -^directory-name\/config\.yml$ -``` +- [Server hooks](../../../administration/server_hooks.md), to create complex custom push rules +- [Signing commits with GPG](gpg_signed_commits/index.md) +- [Protected branches](../protected_branches.md) -Example: prevent the specific file named `install.exe` from being pushed to any -location in the repository. The parenthesized expression `(^|\/)` matches either -a file following a directory separator or a file in the root directory of the repository: +## Troubleshooting -```plaintext -(^|\/)install\.exe$ -``` +### Reject unsigned commits push rule disables Web IDE -Example: combining all of the above in a single 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: +In GitLab 13.10, if a project has the **Reject unsigned commits** push rule, the user cannot +create commits through the GitLab Web IDE. -```plaintext -(\.exe|^config\.yml|^directory-name\/config\.yml|(^|\/)install\.exe)$ -``` +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) -<!-- ## Troubleshooting +```ruby +Feature.disable(:reject_unsigned_commits_by_gitlab) +``` -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### Unsigned commits created in the GitLab UI -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +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). |