diff options
Diffstat (limited to 'doc')
22 files changed, 345 insertions, 337 deletions
diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 80c3f173763..9945d330db0 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -53,8 +53,8 @@ are already logged in or are using Git over SSH are be able to access GitLab for up to one hour. Manually block the user in the GitLab Admin Area to immediately block all access. -GitLab Enterprise Edition Starter supports a -[configurable sync time](#adjusting-ldap-user-sync-schedule). **(STARTER)** +GitLab Enterprise Edition Premium supports a +[configurable sync time](#adjusting-ldap-user-sync-schedule). **(PREMIUM)** ## Git password authentication **(FREE SELF)** @@ -205,7 +205,7 @@ LDAP attributes that GitLab uses to create an account for the LDAP user. The spe | `first_name` | LDAP attribute for user first name. Used when the attribute configured for `name` does not exist. | no | `'givenName'` | | `last_name` | LDAP attribute for user last name. Used when the attribute configured for `name` does not exist. | no | `'sn'` | -### LDAP Sync Configuration Settings **(STARTER ONLY)** +### LDAP Sync Configuration Settings **(PREMIUM SELF)** | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | @@ -254,7 +254,7 @@ group, you can use the following syntax: For more information about this "LDAP_MATCHING_RULE_IN_CHAIN" filter, see the following [Microsoft Search Filter Syntax](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) document. Support for nested members in the user filter should not be confused with -[group sync nested groups support](#supported-ldap-group-typesattributes). **(STARTER ONLY)** +[group sync nested groups support](#supported-ldap-group-typesattributes). **(PREMIUM SELF)** Please note that GitLab does not support the custom filter syntax used by OmniAuth LDAP. @@ -467,7 +467,7 @@ You should disable anonymous LDAP authentication and enable simple or SASL authentication. The TLS client authentication setting in your LDAP server cannot be mandatory and clients cannot be authenticated with the TLS protocol. -## Multiple LDAP servers **(STARTER ONLY)** +## Multiple LDAP servers **(PREMIUM SELF)** With GitLab Enterprise Edition Starter, you can configure multiple LDAP servers that your GitLab instance connects to. @@ -515,7 +515,7 @@ gitlab_rails['ldap_servers'] = { If you configure multiple LDAP servers, use a unique naming convention for the `label` section of each entry. That label is used as the display name of the tab shown on the sign-in page. -## User sync **(STARTER ONLY)** +## User sync **(PREMIUM SELF)** Once per day, GitLab runs a worker to check and update GitLab users against LDAP. @@ -546,7 +546,7 @@ The LDAP sync process: - Updates existing users. - Creates new users on first sign in. -### Adjusting LDAP user sync schedule **(STARTER ONLY)** +### Adjusting LDAP user sync schedule **(PREMIUM SELF)** By default, GitLab runs a worker once per day at 01:30 a.m. server time to check and update GitLab users against LDAP. @@ -579,7 +579,7 @@ sync to run once every 12 hours at the top of the hour. 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -## Group Sync **(STARTER ONLY)** +## Group Sync **(PREMIUM SELF)** If your LDAP supports the `memberof` property, when the user signs in for the first time GitLab triggers a sync for groups the user should be a member of. @@ -629,11 +629,11 @@ following. To take advantage of group sync, group owners or maintainers need to [create one or more LDAP group links](#adding-group-links). -### Adding group links **(STARTER ONLY)** +### Adding group links **(PREMIUM SELF)** For information on adding group links via CNs and filters, refer to [the GitLab groups documentation](../../../user/group/index.md#manage-group-memberships-via-ldap). -### Administrator sync **(STARTER ONLY)** +### Administrator sync **(PREMIUM SELF)** As an extension of group sync, you can automatically manage your global GitLab administrators. Specify a group CN for `admin_group` and all members of the @@ -677,7 +677,7 @@ group, as opposed to the full DN. 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -### Global group memberships lock **(STARTER ONLY)** +### Global group memberships lock **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1793) in GitLab 12.0. @@ -696,7 +696,7 @@ To enable it you need to: 1. Navigate to **(admin)** **Admin Area > Settings -> Visibility and access controls**. 1. Make sure the "Lock memberships to LDAP synchronization" checkbox is enabled. -### Adjusting LDAP group sync schedule **(STARTER ONLY)** +### Adjusting LDAP group sync schedule **(PREMIUM SELF)** By default, GitLab runs a group sync process every hour, on the hour. The values shown are in cron format. If needed, you can use a @@ -735,7 +735,7 @@ sync to run once every 2 hours at the top of the hour. 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -### External groups **(STARTER ONLY)** +### External groups **(PREMIUM SELF)** Using the `external_groups` setting will allow you to mark all users belonging to these groups as [external users](../../../user/permissions.md#external-users). diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 1976bab03c6..5640e938651 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -52,7 +52,7 @@ main: # 'main' is the GitLab 'provider ID' of this LDAP server admin_group: 'my_admin_group' ``` -#### Query LDAP **(STARTER ONLY)** +#### Query LDAP **(PREMIUM SELF)** The following allows you to perform a search in LDAP using the rails console. Depending on what you're trying to do, it may make more sense to query [a @@ -210,7 +210,7 @@ ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt -b "$ba port. - We are assuming the password for the `bind_dn` user is in `bind_dn_password.txt`. -#### Sync all users **(STARTER ONLY)** +#### Sync all users **(PREMIUM SELF)** The output from a manual [user sync](index.md#user-sync) can show you what happens when GitLab tries to sync its users against LDAP. Enter the [rails console](#rails-console) @@ -225,7 +225,7 @@ LdapSyncWorker.new.perform Next, [learn how to read the output](#example-console-output-after-a-user-sync). -##### Example console output after a user sync **(STARTER ONLY)** +##### Example console output after a user sync **(PREMIUM SELF)** The output from a [manual user sync](#sync-all-users) will be very verbose, and a single user's successful sync can look like this: @@ -316,9 +316,9 @@ adapter = Gitlab::Auth::Ldap::Adapter.new('ldapmain') # If `main` is the LDAP pr Gitlab::Auth::Ldap::Person.find_by_uid('<uid>', adapter) ``` -### Group memberships **(STARTER ONLY)** +### Group memberships **(PREMIUM SELF)** -#### Membership(s) not granted **(STARTER ONLY)** +#### Membership(s) not granted **(PREMIUM SELF)** Sometimes you may think a particular user should be added to a GitLab group via LDAP group sync, but for some reason it's not happening. There are several @@ -376,7 +376,7 @@ group sync](#sync-all-groups) in the rails console and [look through the output](#example-console-output-after-a-group-sync) to see what happens when GitLab syncs the `admin_group`. -#### Sync all groups **(STARTER ONLY)** +#### Sync all groups **(PREMIUM SELF)** NOTE: To sync all groups manually when debugging is unnecessary, [use the Rake @@ -394,7 +394,7 @@ LdapAllGroupsSyncWorker.new.perform Next, [learn how to read the output](#example-console-output-after-a-group-sync). -##### Example console output after a group sync **(STARTER ONLY)** +##### Example console output after a group sync **(PREMIUM SELF)** Like the output from the user sync, the output from the [manual group sync](#sync-all-groups) will also be very verbose. However, it contains lots @@ -484,7 +484,7 @@ stating as such: No `admin_group` configured for 'ldapmain' provider. Skipping ``` -#### Sync one group **(STARTER ONLY)** +#### Sync one group **(PREMIUM SELF)** [Syncing all groups](#sync-all-groups) can produce a lot of noise in the output, which can be distracting when you're only interested in troubleshooting the memberships of @@ -506,7 +506,7 @@ EE::Gitlab::Auth::Ldap::Sync::Group.execute_all_providers(group) The output will be similar to [that you'd get from syncing all groups](#example-console-output-after-a-group-sync). -#### Query a group in LDAP **(STARTER ONLY)** +#### Query a group in LDAP **(PREMIUM SELF)** When you'd like to confirm that GitLab can read a LDAP group and see all its members, you can run the following: @@ -562,7 +562,7 @@ emails.each do |username, email| end ``` -You can then [run a UserSync](#sync-all-users) **(STARTER ONLY)** to sync the latest DN +You can then [run a UserSync](#sync-all-users) **(PREMIUM SELF)** to sync the latest DN for each of these users. ## Debugging Tools diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md index 7fa158178dc..37598fa99d8 100644 --- a/doc/administration/raketasks/ldap.md +++ b/doc/administration/raketasks/ldap.md @@ -34,7 +34,7 @@ limit by passing a number to the check task: rake gitlab:ldap:check[50] ``` -## Run a group sync **(STARTER ONLY)** +## Run a group sync **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/14735) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.2. diff --git a/doc/api/groups.md b/doc/api/groups.md index 1497dd0a98b..25571af9874 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -764,8 +764,8 @@ Parameters: | `request_access_enabled` | boolean | no | Allow users to request member access. | | `parent_id` | integer | no | The parent group ID for creating nested group. | | `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). Default to the global level default branch protection setting. | -| `shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | -| `extra_shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | +| `shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | +| `extra_shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | ### Options for `default_branch_protection` @@ -838,8 +838,8 @@ PUT /groups/:id | `request_access_enabled` | boolean | no | Allow users to request member access. | | `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). | | `file_template_project_id` | integer | no | **(PREMIUM)** The ID of a project to load custom file templates from. | -| `shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | -| `extra_shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | +| `shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | +| `extra_shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | | `prevent_forking_outside_group` | boolean | no | **(PREMIUM)** When enabled, users can **not** fork projects from this group to external namespaces | `shared_runners_setting` | string | no | See [Options for `shared_runners_setting`](#options-for-shared_runners_setting). Enable or disable shared runners for a group's subgroups and projects. | @@ -1135,7 +1135,7 @@ DELETE /groups/:id/hooks/:hook_id Group audit events can be accessed via the [Group Audit Events API](audit_events.md#group-audit-events) -## Sync group with LDAP **(STARTER ONLY)** +## Sync group with LDAP **(PREMIUM SELF)** Syncs the group with its linked LDAP group. Only available to group owners and administrators. @@ -1155,7 +1155,7 @@ Please consult the [Group Members](members.md) documentation. List, add, and delete LDAP group links. -### List LDAP group links **(STARTER ONLY)** +### List LDAP group links **(PREMIUM SELF)** Lists LDAP group links. @@ -1167,7 +1167,7 @@ GET /groups/:id/ldap_group_links | --------- | -------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -### Add LDAP group link with CN or filter **(STARTER ONLY)** +### Add LDAP group link with CN or filter **(PREMIUM SELF)** Adds an LDAP group link using a CN or filter. Adding a group link by filter is only supported in the Premium tier and above. @@ -1186,7 +1186,7 @@ POST /groups/:id/ldap_group_links NOTE: To define the LDAP group link, provide either a `cn` or a `filter`, but not both. -### Delete LDAP group link **(STARTER ONLY)** +### Delete LDAP group link **(PREMIUM SELF)** Deletes an LDAP group link. Deprecated. Scheduled for removal in a future release. @@ -1211,7 +1211,7 @@ DELETE /groups/:id/ldap_group_links/:provider/:cn | `cn` | string | yes | The CN of an LDAP group | | `provider` | string | yes | LDAP provider for the LDAP group link | -### Delete LDAP group link with CN or filter **(STARTER ONLY)** +### Delete LDAP group link with CN or filter **(PREMIUM SELF)** Deletes an LDAP group link using a CN or filter. Deleting by filter is only supported in the Premium tier and above. diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index adcf3175c45..48179f3acc7 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -226,6 +226,22 @@ you should fully roll out the feature by enabling the flag **globally** by runni This changes the feature flag state to be **enabled** always, which overrides the existing gates (e.g. `--group=gitlab-org`) in the above processes. +##### Disabling feature flags + +To disable a feature flag that has been globally enabled you can run: + +```shell +/chatops run feature set some_feature false +``` + +To disable a feature flag that has been enabled for a specific project you can run: + +```shell +/chatops run feature set --group=gitlab-org some_feature false +``` + +You cannot selectively disable feature flags for a specific project/group/user without applying a [specific method of implementing](development.md#selectively-disable-by-actor) the feature flags. + ### Feature flag change logging #### Chatops level diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 46190b347f9..d8297ac87b3 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, how-to --- -# Kerberos integration **(STARTER ONLY)** +# Kerberos integration **(PREMIUM SELF)** GitLab can integrate with [Kerberos](https://web.mit.edu/kerberos/) as an authentication mechanism. diff --git a/doc/integration/saml.md b/doc/integration/saml.md index ad7f59f9a97..c2da839d547 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -187,7 +187,7 @@ The name of the attribute can be anything you like, but it must contain the grou to which a user belongs. In order to tell GitLab where to find these groups, you need to add a `groups_attribute:` element to your SAML settings. -### Required groups **(STARTER ONLY)** +### Required groups **(PREMIUM SELF)** Your IdP passes Group Information to the SP (GitLab) in the SAML Response. You need to configure GitLab to identify: @@ -213,7 +213,7 @@ Example: } } ``` -### External Groups **(STARTER ONLY)** +### External groups **(PREMIUM SELF)** SAML login supports automatic identification on whether a user should be considered an [external](../user/permissions.md) user. This is based on the user's group membership in the SAML identity provider. @@ -231,7 +231,7 @@ SAML login supports automatic identification on whether a user should be conside } } ``` -### Admin Groups **(STARTER ONLY)** +### Admin groups **(PREMIUM SELF)** The requirements are the same as the previous settings, your IdP needs to pass Group information to GitLab, you need to tell GitLab where to look for the groups in the SAML response, and which group(s) should be @@ -251,7 +251,7 @@ considered admin users. } } ``` -### Auditor Groups **(STARTER ONLY)** +### Auditor groups **(PREMIUM SELF)** > Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 11.4. diff --git a/doc/user/discussions/img/resolve_thread_open_issue.png b/doc/user/discussions/img/resolve_thread_open_issue.png Binary files differdeleted file mode 100644 index 2dd4ea3cb1b..00000000000 --- a/doc/user/discussions/img/resolve_thread_open_issue.png +++ /dev/null diff --git a/doc/user/discussions/img/resolve_thread_open_issue_v13_9.png b/doc/user/discussions/img/resolve_thread_open_issue_v13_9.png Binary files differnew file mode 100644 index 00000000000..6611ca7b1ff --- /dev/null +++ b/doc/user/discussions/img/resolve_thread_open_issue_v13_9.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 33ced680c54..5924db3b2c9 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -115,7 +115,7 @@ are resolved](#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolve there will be an **open an issue to resolve them later** link in the merge request widget. - + This will prepare an issue with its content referring to the merge request and the unresolved threads. @@ -161,7 +161,7 @@ box and hit **Save** for the changes to take effect. From now on, you will not be able to merge from the UI until all threads are resolved. - + ### Automatically resolve merge request diff threads when they become outdated diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 0cad3c24fa0..96e3f8250f6 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -327,7 +327,7 @@ A group's **Details** page includes tabs for: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab [Starter](https://about.gitlab.com/pricing/) 12.10 as a [beta feature](https://about.gitlab.com/handbook/product/#beta) -The group details view also shows the number of the following items created in the last 90 days: **(STARTER)** +The group details view also shows the number of the following items created in the last 90 days: **(PREMIUM)** - Merge requests. - Issues. @@ -389,7 +389,7 @@ To share a given group, for example, 'Frontend' with another group, for example, All the members of the 'Engineering' group will have been added to 'Frontend'. -## Manage group memberships via LDAP **(STARTER ONLY)** +## Manage group memberships via LDAP **(PREMIUM SELF)** Group syncing allows LDAP groups to be mapped to GitLab groups. This provides more control over per-group user management. To configure group syncing edit the `group_base` **DN** (`'OU=Global Groups,OU=GitLab INT,DC=GitLab,DC=org'`). This **OU** contains all groups that will be associated with GitLab groups. @@ -400,7 +400,7 @@ For more information on the administration of LDAP and group sync, refer to the NOTE: If an LDAP user is a group member when LDAP Synchronization is added, and they are not part of the LDAP group, they will be removed from the group. -### Creating group links via CN **(STARTER ONLY)** +### Creating group links via CN **(PREMIUM SELF)** To create group links via CN: @@ -428,7 +428,7 @@ To create group links via filter:  -### Overriding user permissions **(STARTER ONLY)** +### Overriding user permissions **(PREMIUM SELF)** In GitLab [8.15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/822) and later, LDAP user permissions can now be manually overridden by an admin user. To override a user's permissions: @@ -616,7 +616,7 @@ To enable this feature, navigate to the group settings page. Select  -#### Member Lock **(STARTER)** +#### Member Lock **(PREMIUM)** Member lock lets a group owner prevent any new project membership to all of the projects within a group, allowing tighter control over project membership. @@ -814,11 +814,11 @@ To enable prevent project forking: - **Webhooks**: Configure [webhooks](../project/integrations/webhooks.md) for your group. - **Kubernetes cluster integration**: Connect your GitLab group with [Kubernetes clusters](clusters/index.md). - **Audit Events**: View [Audit Events](../../administration/audit_events.md) - for the group. **(STARTER ONLY)** + for the group. **(PREMIUM SELF)** - **Pipelines quota**: Keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group. - **Integrations**: Configure [integrations](../admin_area/settings/project_integration_management.md) for your group. -#### Group push rules **(STARTER)** +#### Group push rules **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/224129) in GitLab 13.4. @@ -839,7 +839,7 @@ When set, new subgroups have push rules set for them based on either: For information about setting a maximum artifact size for a group, see [Maximum artifacts size](../admin_area/settings/continuous_integration.md#maximum-artifacts-size). -## User contribution analysis **(STARTER)** +## User contribution analysis **(PREMIUM)** With [GitLab Contribution Analytics](contribution_analytics/index.md), you have an overview of the contributions (pushes, merge requests, diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 63ea84e42c9..e0947c182c0 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -7,9 +7,8 @@ type: reference # Code Owners **(STARTER)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) -in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. -> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in GitLab 11.3. +> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9. ## Introduction @@ -18,7 +17,7 @@ to find out who should review or approve merge requests. Additionally, if you have a question over a specific file or code block, it may be difficult to know who to find the answer from. -GitLab Code Owners is a feature to define who owns specific +The GitLab Code Owners feature defines who owns specific files or paths in a repository, allowing other users to understand who is responsible for each file or path. @@ -32,7 +31,7 @@ the process of finding the right reviewers and approvers for a given merge request. In larger organizations or popular open source projects, Code Owners -can also be useful to understand who to contact if you have +can help you understand who to contact if you have a question that may not be related to code review or a merge request approval. @@ -49,12 +48,12 @@ You can choose to add the `CODEOWNERS` file in three places: - Inside the `docs/` directory The `CODEOWNERS` file is valid for the branch where it lives. For example, if you change the code owners -in a feature branch, they won't be valid in the main branch until the feature branch is merged. +in a feature branch, the changes aren't valid in the main branch until the feature branch is merged. If you introduce new files to your repository and you want to identify the code owners for that file, -you have to update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same -branch), GitLab will count the owners as soon as the branch is merged. If -you don't, you can do that later, but your new files will not belong to anyone until you update your +you must update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same +branch), GitLab counts the owners as soon as the branch is merged. If +you don't, you can do that later, but your new files don't belong to anyone until you update your `CODEOWNERS` file in the TARGET branch. When a file matches multiple entries in the `CODEOWNERS` file, @@ -73,29 +72,32 @@ The user that would show for `README.md` would be `@user2`. ## Approvals by Code Owners -Once you've added Code Owners to a project, you can configure it to +After you've added Code Owners to a project, you can configure it to be used for merge request approvals: - As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers). - As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** -Developer or higher [permissions](../permissions.md) are required in order to +Developer or higher [permissions](../permissions.md) are required to approve a merge request. -Once set, Code Owners are displayed in merge requests widgets: +After it's set, Code Owners are displayed in merge request widgets:  -While the `CODEOWNERS` file can be used in addition to Merge Request [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules), -it can also be used as the sole driver of merge request approvals -(without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)). -To do so, create the file in one of the three locations specified above and -set the code owners as required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). -Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) -to specify the actual owners and granular permissions. +While you can use the `CODEOWNERS` file in addition to Merge Request +[Approval Rules](merge_requests/merge_request_approvals.md#approval-rules), +you can also use it as the sole driver of merge request approvals +without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules): + +1. Create the file in one of the three locations specified above. +1. Set the code owners as required approvers for + [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). +1. Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) + to specify the actual owners and granular permissions. Using Code Owners in conjunction with [Protected Branches](protected_branches.md#protected-branches-approval-by-code-owners) -will prevent any user who is not specified in the `CODEOWNERS` file from pushing +prevents any user who is not specified in the `CODEOWNERS` file from pushing changes for the specified files/paths, except those included in the **Allowed to push** column. This allows for a more inclusive push strategy, as administrators don't have to restrict developers from pushing directly to the @@ -114,13 +116,13 @@ in the `.gitignore` file followed by one or more of: - The `@name` of one or more groups that should be owners of the file. - Lines starting with `#` are ignored. -The order in which the paths are defined is significant: the last pattern that -matches a given path will be used to find the code owners. +The path definition order is significant: the last pattern +matching a given path is used to find the code owners. ### Groups as Code Owners -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab Starter 12.1. -> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1. +> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. Groups and subgroups members are inherited as eligible Code Owners to a project, as long as the hierarchy is respected. @@ -131,7 +133,7 @@ suppose you have a project called "Project A" within the group and a "Project B" within the subgroup. The eligible Code Owners to Project B are both the members of the Group X and -the Subgroup Y. And the eligible Code Owners to the Project A are just the +the Subgroup Y. The eligible Code Owners to the Project A are just the members of the Group X, given that Project A doesn't belong to the Subgroup Y:  @@ -142,9 +144,9 @@ Code Owners:  -Once invited, any member (`@user`) of the group or subgroup can be set -as Code Owner to files of the Project A or B, as well as the entire Group X -(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as exemplified below: +After being invited, any member (`@user`) of the group or subgroup can be set +as Code Owner to files of the Project A or B, and the entire Group X +(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as follows: ```plaintext # A member of the group or subgroup as Code Owner to a file @@ -162,7 +164,7 @@ file.md @group-x @group-x/subgroup-y ### Code Owners Sections **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2 behind a feature flag, enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab Premium 13.2 behind a feature flag, enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Code Owner rules can be grouped into named sections. This allows for better @@ -185,8 +187,8 @@ changes, to set their own independent patterns by specifying discrete sections i teams can be added as reviewers. Sections can be added to `CODEOWNERS` files as a new line with the name of the -section inside square brackets. Every entry following it is assigned to that -section. The following example would create 2 Code Owner rules for the "README +section inside square brackets. Every entry following is assigned to that +section. The following example would create two Code Owner rules for the "README Owners" section: ```plaintext @@ -196,7 +198,7 @@ internal/README.md @user2 ``` Multiple sections can be used, even with matching file or directory patterns. -Reusing the same section name will group the results together under the same +Reusing the same section name groups the results together under the same section, with the most specific rule or last matching pattern being used. For example, consider the following entries in a `CODEOWNERS` file: @@ -213,7 +215,7 @@ model/db @gl-database README.md @gl-docs ``` -This will result in 3 entries under the "Documentation" section header, and 2 +This results in three entries under the "Documentation" section header, and two entries under "Database". Case is not considered when combining sections, so in this example, entries defined under the sections "Documentation" and "DOCUMENTATION" would be combined into one, using the case of the first instance @@ -227,9 +229,10 @@ the rules for "Groups" and "Documentation" sections: #### Optional Code Owners Sections **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.8 behind a feature flag, enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8 behind a feature flag, enabled by default. -When you want to make a certain section optional, you can do so by adding a code owners section prepended with the caret `^` character. Approvals from owners listed in the section will **not** be required. For example: +To make a certain section optional, add a code owners section prepended with the +caret `^` character. Approvals from owners listed in the section are **not** required. For example: ```plaintext [Documentation] @@ -242,13 +245,13 @@ When you want to make a certain section optional, you can do so by adding a code *.go @root ``` -The optional code owners section will be displayed in merge requests under the **Approval Rules** area: +The optional code owners section displays in merge requests under the **Approval Rules** area:  -If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails. +If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails. -For example, the code owners of the "Documentation" section below will still be required to approve merge requests: +For example, the code owners of the "Documentation" section below is still required to approve merge requests: ```plaintext [Documentation] @@ -264,12 +267,12 @@ For example, the code owners of the "Documentation" section below will still be *.txt @root ``` -Optional sections in the code owners file are currently treated as optional only -when changes are submitted via merge requests. If a change is submitted directly -to the protected branch, approval from code owners will still be required, even if the -section is marked as optional. We plan to change this in a +Optional sections in the code owners file are treated as optional only +when changes are submitted by using merge requests. If a change is submitted directly +to the protected branch, approval from code owners is still required, even if the +section is marked as optional. We plan to change this behavior in a [future release](https://gitlab.com/gitlab-org/gitlab/-/issues/297638), -where direct pushes to the protected branch will be allowed for sections marked as optional. +and allow direct pushes to the protected branch for sections marked as optional. ## Example `CODEOWNERS` file diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index a49a942ab75..5ffc2878269 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -7,7 +7,7 @@ type: reference # Syntax Highlighting -GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It will try to guess what language to use based on the file extension, which most of the time is sufficient. +GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language to use based on the file extension, which most of the time is sufficient. NOTE: The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/) @@ -25,10 +25,10 @@ you can add the following to your `.gitattributes` file: ``` <!-- vale gitlab.Spelling = NO --> -When you check in and push that change, all `*.pl` files in your project will be highlighted as Prolog. +When you check in and push that change, all `*.pl` files in your project are highlighted as Prolog. <!-- vale gitlab.Spelling = YES --> -The paths here are simply Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is: +The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is: ``` conf /Nicefile gitlab-language=ruby @@ -44,7 +44,8 @@ To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shen /other-file gitlab-language=text?token=Error ``` -Please note that these configurations will only take effect when the `.gitattributes` file is in your default branch (usually `master`). +Please note that these configurations only take effect when the `.gitattributes` +file is in your default branch (usually `master`). NOTE: The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). diff --git a/doc/user/project/index.md b/doc/user/project/index.md index c092738b01c..607049b512e 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -17,12 +17,12 @@ the number of private projects you create. ## Project features -When you create a project in GitLab, you'll have access to a large number of +When you create a project in GitLab, you receive access to a large number of [features](https://about.gitlab.com/features/): **Repositories:** -- [Issue tracker](issues/index.md): Discuss implementations with your team within issues +- [Issue tracker](issues/index.md): Discuss implementations with your team in issues - [Issue Boards](issue_board.md): Organize and prioritize your workflow - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project - [Repositories](repository/index.md): Host your code in a fully @@ -42,13 +42,13 @@ When you create a project in GitLab, you'll have access to a large number of **Issues and merge requests:** -- [Issue tracker](issues/index.md): Discuss implementations with your team within issues +- [Issue tracker](issues/index.md): Discuss implementations with your team in issues - [Issue Boards](issue_board.md): Organize and prioritize your workflow - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project - [Merge Requests](merge_requests/index.md): Apply your branching strategy and get reviewed by your team - [Merge Request Approvals](merge_requests/merge_request_approvals.md): Ask for approval before - implementing a change **(STARTER)** + implementing a change - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): Your Git diff tool right from the GitLab UI - [Review Apps](../../ci/review_apps/index.md): Live preview the results @@ -108,7 +108,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Conan packages](../packages/conan_repository/index.md): your private Conan repository in GitLab. - [Maven packages](../packages/maven_repository/index.md): your private Maven repository in GitLab. - [NPM packages](../packages/npm_registry/index.md): your private NPM package registry in GitLab. -- [Code owners](code_owners.md): specify code owners for certain files **(STARTER)** +- [Code owners](code_owners.md): specify code owners for certain files - [License Compliance](../compliance/license_compliance/index.md): approve and deny licenses for projects. **(ULTIMATE)** - [Dependency List](../application_security/dependency_list/index.md): view project dependencies. **(ULTIMATE)** - [Requirements](requirements/index.md): Requirements allow you to create criteria to check your products against. **(ULTIMATE)** @@ -192,7 +192,7 @@ To delete a project, first navigate to the home page for that project. 1. Click **Delete project** 1. Confirm this action by typing in the expected text. -Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects within a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). +Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects in a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). ## CI/CD for external repositories **(PREMIUM)** @@ -214,11 +214,11 @@ filtered by **Push events**, **Merge events**, **Issue events**, **Comments**, ### Leave a project -**Leave project** will only display on the project's dashboard +**Leave project** only displays on the project's dashboard when a project is part of a group (under a [group namespace](../group/index.md#namespaces)). -If you choose to leave a project you will no longer be a project -member, therefore, unable to contribute. +If you choose to leave a project you are no longer a project +member, and cannot contribute. ## Project's landing page @@ -230,15 +230,15 @@ with [permissions to view the project's code](../permissions.md#project-members- - The content of a [`README` or an index file](repository/#repository-readme-and-index-files) - is displayed (if any), followed by the list of directories within the + is displayed (if any), followed by the list of directories in the project's repository. - If the project doesn't contain either of these files, the - visitor will see the list of files and directories of the repository. + visitor sees the list of files and directories of the repository. -For users without permissions to view the project's code: +For users without permissions to view the project's code, GitLab displays: -- The wiki homepage is displayed, if any. -- The list of issues within the project is displayed. +- The wiki homepage, if any. +- The list of issues in the project. ## GitLab Workflow - VS Code extension @@ -259,15 +259,15 @@ Depending on the situation, different things apply. When [renaming a user](../profile/index.md#changing-your-username), [changing a group path](../group/index.md#changing-a-groups-path) or [renaming a repository](settings/index.md#renaming-a-repository): -- Existing web URLs for the namespace and anything under it (e.g., projects) will +- Existing web URLs for the namespace and anything under it (such as projects) will redirect to the new URLs. - Starting with GitLab 10.3, existing Git remote URLs for projects under the - namespace will redirect to the new remote URL. Every time you push/pull to a + namespace redirect to the new remote URL. Every time you push/pull to a repository that has changed its location, a warning message to update - your remote will be displayed instead of rejecting your action. - This means that any automation scripts, or Git clients will continue to + your remote is displayed instead of rejecting your action. + This means that any automation scripts, or Git clients continue to work after a rename, making any transition a lot smoother. -- The redirects will be available as long as the original path is not claimed by +- The redirects are available as long as the original path is not claimed by another group, user or project. ## Use your project as a Go package @@ -278,11 +278,11 @@ and `godoc.org` discovery requests, including the [`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) meta tags. Private projects, including projects in subgroups, can be used as a Go package, -but may require configuration to work correctly. GitLab will respond correctly +but may require configuration to work correctly. GitLab responds correctly to `go get` discovery requests for projects that *are not* in subgroups, regardless of authentication or authorization. [Authentication](#authenticate-go-requests) is required to use a private project -in a subgroup as a Go package. Otherwise, GitLab will truncate the path for +in a subgroup as a Go package. Otherwise, GitLab truncates the path for private projects in subgroups to the first two segments, causing `go get` to fail. @@ -302,10 +302,10 @@ queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching) `GOPRIVATE`, `GONOPROXY`, and `GONOSUMDB` are comma-separated lists of Go modules and Go module prefixes. For example, -`GOPRIVATE=gitlab.example.com/my/private/project` will disable queries for that -one project, but `GOPRIVATE=gitlab.example.com` will disable queries for *all* -projects on GitLab.com. Go will not query module proxies if the module name or a -prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go will not query checksum +`GOPRIVATE=gitlab.example.com/my/private/project` disables queries for that +one project, but `GOPRIVATE=gitlab.example.com` disables queries for *all* +projects on GitLab.com. Go does not query module proxies if the module name or a +prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go does not query checksum databases if the module name or a prefix of it appears in `GONOPRIVATE` or `GONOSUMDB`. @@ -315,8 +315,8 @@ To authenticate requests to private projects made by Go, use a [`.netrc` file](https://ec.haxx.se/usingcurl-netrc.html) and a [personal access token](../profile/personal_access_tokens.md) in the password field. **This only works if your GitLab instance can be accessed with HTTPS.** The `go` command -will not transmit credentials over insecure connections. This will authenticate -all HTTPS requests made directly by Go but will not authenticate requests made +does not transmit credentials over insecure connections. This authenticates +all HTTPS requests made directly by Go, but does not authenticate requests made through Git. For example: @@ -332,16 +332,18 @@ On Windows, Go reads `~/_netrc` instead of `~/.netrc`. ### Authenticate Git fetches -If a module cannot be fetched from a proxy, Go will fall back to using Git (for -GitLab projects). Git will use `.netrc` to authenticate requests. Alternatively, -Git can be configured to embed specific credentials in the request URL, or to -use SSH instead of HTTPS (as Go always uses HTTPS to fetch Git repositories): +If a module cannot be fetched from a proxy, Go falls back to using Git (for +GitLab projects). Git uses `.netrc` to authenticate requests. You can also +configure Git to either: + +- Embed specific credentials in the request URL. +- Use SSH instead of HTTPS, as Go always uses HTTPS to fetch Git repositories. ```shell -# embed credentials in any request to GitLab.com: +# Embed credentials in any request to GitLab.com: git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" -# use SSH instead of HTTPS: +# Use SSH instead of HTTPS: git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" ``` @@ -354,7 +356,7 @@ visit the `/projects/:id` URL in your browser or other tool accessing the projec ## Project aliases **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab Premium 12.1. When migrating repositories to GitLab and they are being accessed by other systems, it's very useful to be able to access them using the same name especially when @@ -369,9 +371,9 @@ A project alias can be only created via API and only by GitLab administrators. Follow the [Project Aliases API documentation](../../api/project_aliases.md) for more details. -Once an alias has been created for a project (e.g., an alias `gitlab` for the -project `https://gitlab.com/gitlab-org/gitlab`), the repository can be cloned -using the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of +After an alias has been created for a project (such as an alias `gitlab` for the +project `https://gitlab.com/gitlab-org/gitlab`), you can clone the repository +with the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of `git clone git@gitlab.com:gitlab-org/gitlab.git`). ## Project activity analytics overview **(ULTIMATE SELF)** diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 4e87876b036..36fb5cea4b0 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -13,12 +13,13 @@ with introducing a **Cherry-pick** button in merge requests and commit details. ## Cherry-picking a merge request -After the merge request has been merged, a **Cherry-pick** button will be available +After the merge request has been merged, a **Cherry-pick** button displays to cherry-pick the changes introduced by that merge request.  -After you click that button, a modal will appear showing a [branch filter search box](../repository/branches/index.md#branch-filter-search-box) +After you click that button, a modal displays a +[branch filter search box](../repository/branches/index.md#branch-filter-search-box) where you can choose to either: - Cherry-pick the changes directly into the selected branch. @@ -28,12 +29,12 @@ where you can choose to either: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2675) in GitLab 12.9. -When you cherry-pick a merge commit, GitLab will output a system note to the related merge -request thread crosslinking the new commit and the existing merge request. +When you cherry-pick a merge commit, GitLab displays a system note to the related merge +request thread. It crosslinks the new commit and the existing merge request.  -Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) will include cherry-picked merge commits. +Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. NOTE: We only track cherry-pick executed from GitLab (both UI and API). Support for [tracking cherry-picked commits through the command line](https://gitlab.com/gitlab-org/gitlab/-/issues/202215) is planned for a future release. @@ -44,15 +45,15 @@ You can cherry-pick a commit from the commit details page:  -Similar to cherry-picking a merge request, you can opt to cherry-pick the changes +Similar to cherry-picking a merge request, you can cherry-pick the changes directly into the target branch or create a new merge request to cherry-pick the changes. -Please note that when cherry-picking merge commits, the mainline will always be the -first parent. If you want to use a different mainline then you need to do that +When cherry-picking merge commits, the mainline is always the +first parent. If you want to use a different mainline, you need to do that from the command line. -Here is a quick example to cherry-pick a merge commit using the second parent as the +Here's a quick example to cherry-pick a merge commit using the second parent as the mainline: ```shell diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 71bdd92cb06..41cc0506a3f 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -10,8 +10,8 @@ type: reference, concepts > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580) in GitLab Enterprise Edition 7.2. Available in GitLab Core and higher tiers. > - Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. -Code review is an essential practice of every successful project, and giving your -approval once a merge request is in good shape is an important part of the review +Code review is an essential practice of every successful project. Approving a +merge request is an important part of the review process, as it clearly communicates the ability to merge the change. ## Optional Approvals @@ -19,8 +19,8 @@ process, as it clearly communicates the ability to merge the change. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. Any user with Developer or greater [permissions](../../permissions.md) can approve a merge request in GitLab Core and higher tiers. -This provides a consistent mechanism for reviewers to approve merge requests, and makes it easy for -maintainers to know when a change is ready to merge. Approvals in Core are optional and do +This provides a consistent mechanism for reviewers to approve merge requests, and ensures +maintainers know a change is ready to merge. Approvals in Core are optional, and do not prevent a merge request from being merged when there is no approval. ## Required Approvals **(STARTER)** @@ -50,8 +50,9 @@ be merged, and optionally which users should do the approving. Approvals can be - [As project defaults](#adding--editing-a-default-approval-rule). - [Per merge request](#editing--overriding-approval-rules-per-merge-request). -If no approval rules are defined, any user can approve a merge request, though the default -minimum number of required approvers can still be set in the [project settings for merge request approvals](#merge-request-approvals-project-settings). +If no approval rules are defined, any user can approve a merge request. However, the default +minimum number of required approvers can still be set in the +[project settings for merge request approvals](#merge-request-approvals-project-settings). You can opt to define one single rule to approve a merge request among the available rules or choose more than one with [multiple approval rules](#multiple-approval-rules). @@ -81,20 +82,21 @@ A group of users can also be added as approvers. In the future, group approvers [restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). If a user is added as an individual approver and is also part of a group approver, -then that user is just counted once. The merge request author, as well as users who have committed +then that user is just counted once. The merge request author, and users who have committed to the merge request, do not count as eligible approvers, if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) (enabled by default) and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default) are enabled on the project settings. -When an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget, -indicating who has engaged in the merge request review. Authors and reviewers can also easily identify who they should reach out -to if they have any questions or inputs about the content of the merge request. +When an eligible approver comments on a merge request, it displays in the +**Commented by** column of the Approvals widget. It indicates who participated in +the merge request review. Authors and reviewers can also identify who they should reach out +to if they have any questions about the content of the merge request. ##### Implicit Approvers If the number of required approvals is greater than the number of assigned approvers, -approvals from other users will count towards meeting the requirement. These would be +approvals from other users counts towards meeting the requirement. These would be users with developer [permissions](../../permissions.md) or higher in the project who were not explicitly listed in the approval rules. @@ -103,7 +105,7 @@ were not explicitly listed in the approval rules. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5. If you add [Code Owners](../code_owners.md) to your repository, the owners to the -corresponding files will become eligible approvers, together with members with Developer +corresponding files become eligible approvers, together with members with Developer or higher [permissions](../../permissions.md). To enable this merge request approval rule: @@ -115,7 +117,7 @@ To enable this merge request approval rule:  Once set, merge requests can only be merged once approved by the -number of approvals you've set. GitLab will accept approvals from +number of approvals you've set. GitLab accepts approvals from users with Developer or higher permissions, as well as by Code Owners, indistinguishably. @@ -154,27 +156,27 @@ To add or edit the default merge request approval rule: 1. Click **Add approval rule**, or **Edit**. - Add or change the **Rule name**. - Set the number of required approvals in **Approvals required**. The minimum value is `0`. - - (Optional) Search for users or groups that will be [eligible to approve](#eligible-approvers) + - (Optional) Search for users or groups that are [eligible to approve](#eligible-approvers) merge requests and click the **Add** button to add them as approvers. Before typing - in the search field, approvers will be suggested based on the previous authors of + in the search field, approvers are suggested based on the previous authors of the files being changed by the merge request. - (Optional) Click the **{remove}** **Remove** button next to a group or user to delete it from the rule. 1. Click **Add approval rule** or **Update approval rule**. When [approval rule overrides](#prevent-overriding-default-approvals) are allowed, -changes to these default rules will **not** be applied to existing merge +changes to these default rules are not applied to existing merge requests, except for changes to the [target branch](#scoped-to-protected-branch) of the rule. When approval rule overrides are not allowed, all changes to these default rules -will be applied to existing merge requests. Any approval rules that had previously been +are applied to existing merge requests. Any approval rules that had previously been manually [overridden](#editing--overriding-approval-rules-per-merge-request) during a -period when approval rule overrides where allowed, will not be modified. +period when approval rule overrides where allowed, are not modified. NOTE: If a merge request targets a different project, such as from a fork to the upstream project, -the default approval rules will be taken from the target (upstream) project, not the +the default approval rules are taken from the target (upstream) project, not the source (fork). ##### Editing / overriding approval rules per merge request @@ -193,8 +195,8 @@ the same steps as [Adding / editing a default approval rule](#adding--editing-a- #### Set up an optional approval rule -MR approvals can be configured to be optional. -This can be useful if you're working on a team where approvals are appreciated, but not required. +MR approvals can be configured to be optional, which can help if you're working +on a team where approvals are appreciated, but not required. To configure an approval to be optional, set the number of required approvals in **Approvals required** to `0`. @@ -209,16 +211,16 @@ as well as multiple default approval rules per project. Adding or editing multiple default rules is identical to [adding or editing a single default approval rule](#adding--editing-a-default-approval-rule), -except the **Add approval rule** button will be available to add more rules, even after +except the **Add approval rule** button is available to add more rules, even after a rule is already defined. Similarly, editing or overriding multiple approval rules per merge request is identical to [editing or overriding approval rules per merge request](#editing--overriding-approval-rules-per-merge-request), -except the **Add approval rule** button will be available to add more rules, even after +except the **Add approval rule** button is available to add more rules, even after a rule is already defined. -When an [eligible approver](#eligible-approvers) approves a merge request, it will -reduce the number of approvals left for all rules that the approver belongs to. +When an [eligible approver](#eligible-approvers) approves a merge request, it +reduces the number of approvals left for all rules that the approver belongs to.  @@ -267,7 +269,7 @@ The merge request author is not allowed to approve their own merge request if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) is enabled in the project settings. -Once the approval rules have been met, the merge request can be merged if there is nothing +After the approval rules have been met, the merge request can be merged if there is nothing else blocking it. Note that the merge request could still be blocked by other conditions, such as merge conflicts, [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). @@ -289,7 +291,7 @@ To prevent that from happening: #### Resetting approvals on push You can force all approvals on a merge request to be removed when new commits are -pushed to the source branch of the merge request. If disabled, approvals will persist +pushed to the source branch of the merge request. If disabled, approvals persist even if there are changes added to the merge request. To enable this feature: 1. Check the **Require new approvals when new commits are added to an MR.** @@ -298,7 +300,7 @@ even if there are changes added to the merge request. To enable this feature: NOTE: Approvals do not get reset when [rebasing a merge request](fast_forward_merge.md) -from the UI. However, approvals will be reset if the target branch is changed. +from the UI. However, approvals are reset if the target branch is changed. #### Allowing merge request authors to approve their own merge requests @@ -330,7 +332,7 @@ enable this feature: NOTE: To require authentication when approving a merge request, you must enable **Password authentication enabled for web interface** under [sign-in restrictions](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). -in the Admin area. +in the Admin Area. You can force the approver to enter a password in order to authenticate before adding the approval. This enables an Electronic Signature for approvals such as the one defined diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index 99e70f35d6d..b2aedb7d95f 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -10,13 +10,13 @@ type: reference, concepts Merge conflicts occur when two branches have different changes that cannot be merged automatically. -Git is able to automatically merge changes between branches in most cases, but -there are situations where Git will require your assistance to resolve the +Git can merge changes between branches in most cases, but +occasionally Git requires your assistance to resolve the conflicts manually. Typically, this is necessary when people change the same parts of the same files. -GitLab will prevent merge requests from being merged until all conflicts are -resolved. Conflicts can be resolved locally, or in many cases within GitLab +GitLab prevents merge requests from being merged until all conflicts are +resolved. Conflicts can be resolved locally, or in many cases in GitLab (see [conflicts available for resolution](#conflicts-available-for-resolution) for information on when this is available). @@ -24,35 +24,30 @@ for information on when this is available). NOTE: GitLab resolves conflicts by creating a merge commit in the source branch that -is not automatically merged into the target branch. This allows the merge -commit to be reviewed and tested before the changes are merged, preventing +is not automatically merged into the target branch. The merge +commit can be reviewed and tested before the changes are merged. This prevents unintended changes entering the target branch without review or breaking the build. ## Resolve conflicts: interactive mode -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5479) in GitLab 8.11. - -Clicking this will show a list of files with conflicts, with conflict sections +Clicking **Resolve Conflicts** displays a list of files with conflicts, with conflict sections highlighted:  -Once all conflicts have been marked as using 'ours' or 'theirs', the conflict -can be resolved. This will perform a merge of the target branch of the merge -request into the source branch, resolving the conflicts using the options +After all conflicts have been marked as using 'ours' or 'theirs', the conflict +can be resolved. Resolving conflicts merges the target branch of the merge +request into the source branch, using the options chosen. If the source branch is `feature` and the target branch is `master`, this is similar to performing `git checkout feature; git merge master` locally. ## Resolve conflicts: inline editor -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6374) in GitLab 8.13. - -The merge conflict resolution editor allows for more complex merge conflicts, -which require the user to manually modify a file in order to resolve a conflict, -to be solved right form the GitLab interface. Use the **Edit inline** button -to open the editor. Once you're sure about your changes, hit the -**Commit to source branch** button. +Some merge conflicts are more complex, requiring you to manually modify a file to +resolve them. Use the merge conflict resolution editor to resolve complex +conflicts in the GitLab interface. Click **Edit inline** to open the editor. +After you're sure about your changes, click **Commit to source branch**.  @@ -66,13 +61,16 @@ GitLab allows resolving conflicts in a file where all of the below are true: - The file, with conflict markers added, is not over 200 KB in size - The file exists under the same path in both branches -If any file with conflicts in that merge request does not meet all of these -criteria, the conflicts for that merge request cannot be resolved in the UI. +If any file in your merge request containing conflicts can't meet all of these +criteria, you can't resolve the merge conflict in the UI. Additionally, GitLab does not detect conflicts in renames away from a path. For -example, this will not create a conflict: on branch `a`, doing `git mv file1 -file2`; on branch `b`, doing `git mv file1 file3`. Instead, both files will be -present in the branch after the merge request is merged. +example, this does not create a conflict: + +1. On branch `a`, doing `git mv file1 file2` +1. On branch `b`, doing `git mv file1 file3`. + +Instead, both files are present in the branch after the merge request is merged. <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index 893a917d31f..b611a4f850c 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -13,10 +13,10 @@ which is then reviewed, and accepted (or rejected). ## View project merge requests -View all the merge requests within a project by navigating to **Project > Merge Requests**. +View all the merge requests in a project by navigating to **Project > Merge Requests**. -When you access your project's merge requests, GitLab will present them in a list, -and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists). +When you access your project's merge requests, GitLab displays them in a list. +Use the tabs to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists).  @@ -32,7 +32,7 @@ You can [search and filter the results](../../search/index.md#filtering-issue-an A merge commit is created for every merge, but the branch is only merged if a fast-forward merge is possible. This ensures that if the merge request build -succeeded, the target branch build will also succeed after merging. +succeeded, the target branch build also succeeds after the merge. Navigate to a project's settings, select the **Merge commit with semi-linear history** option under **Merge Requests: Merge method** and save your changes. @@ -80,12 +80,15 @@ Click **Expand file** on any file to view the changes for that file. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. -For larger merge requests it might sometimes be useful to review single files at a time. To enable, -from your avatar on the top-right navigation bar, click **Settings**, and go to **Preferences** on the left -sidebar. Scroll down to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. -Click **Save changes** to apply. +For larger merge requests, consider reviewing one file at a time. To enable this feature: -From there, when reviewing merge requests' **Changes** tab, you will see only one file at a time. You can then click the buttons **Prev** and **Next** to view the other files changed. +1. In the top right corner of the navigation bar, click your user avatar. +1. Click **Settings**. +1. In the left sidebar, go to **Preferences**. +1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. +1. Click **Save changes** to apply. + +After you enable this setting, GitLab displays only one file at a time in the **Changes** tab when you review merge requests. You can click **Prev** and **Next** to view other changed files.  @@ -104,10 +107,14 @@ browser's cookies or change this behavior again. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. -To seamlessly navigate among commits in a merge request, from the **Commits** tab, click one of -the commits to open the single-commit view. From there, you can navigate among the commits -by clicking the **Prev** and **Next** buttons on the top-right of the page or by using the -<kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. +To seamlessly navigate among commits in a merge request: + +1. Click the **Commits** tab. +1. Click a commit to open it in the single-commit view. +1. Navigate through the commits by either: + + - Clicking **Prev** and **Next** buttons on the top-right of the page. + - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts.  @@ -120,7 +127,7 @@ to expand the entire file.  -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205401) in GitLab 13.1, when viewing a +In GitLab [versions 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205401), when viewing a merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the entire content by clicking **Show file contents**. @@ -145,7 +152,7 @@ whitespace changes. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-views). **(FREE SELF)** When reviewing a merge request with many files multiple times, it may be useful to the reviewer -to focus on new changes and ignore the files that they have already reviewed and don't want to +to focus on new changes and ignore the files that they have already reviewed and don't want to see anymore unless they are changed again. To mark a file as viewed: @@ -154,7 +161,7 @@ To mark a file as viewed: 1. On the right-top of the file, locate the **Viewed** checkbox. 1. Check it to mark the file as viewed. -Once checked, the file will remain marked for that reviewer unless there are newly introduced +Once checked, the file remains marked for that reviewer unless there are newly introduced changes to its content or the checkbox is unchecked. ### Enable or disable file views **(FREE SELF)** @@ -180,8 +187,9 @@ Feature.disable(:local_file_reviews) > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. -GitLab provides a way of leaving comments in any part of the file being changed -in a Merge Request. To do so, click the **{comment}** **comment** icon in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line. +In a merge request, you can leave comments in any part of the file being changed. +In the Merge Request Diff UI, click the **{comment}** **comment** icon in the gutter +to expand the diff lines and leave a comment, just as you would for a changed line.  @@ -231,31 +239,30 @@ Feature.enable(:multiline_comments) ## Pipeline status in merge requests widgets If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, -you will be able to see: +you can see: - Both pre-merge and post-merge pipelines and the environment information if any. - Which deployments are in progress. -If there's an [environment](../../../ci/environments/index.md) and the application is -successfully deployed to it, the deployed environment and the link to the -Review App will be shown as well. +If an application is successfully deployed to an +[environment](../../../ci/environments/index.md), the deployed environment and the link to the +Review App are both shown. NOTE: -When the default branch (for example, `main`) is red due to a failed CI pipeline, the `merge` button -When the pipeline fails in a merge request but it can be merged nonetheless, -the **Merge** button will be colored in red. +When the pipeline fails in a merge request but it can still be merged, +the **Merge** button is colored red. ### Post-merge pipeline status When a merge request is merged, you can see the post-merge pipeline status of the branch the merge request was merged into. For example, when a merge request -is merged into the master branch and then triggers a deployment to the staging +is merged into the `master` branch and then triggers a deployment to the staging environment. -Deployments that are ongoing will be shown, as well as the deploying/deployed state +Ongoing deployments are shown, and the state (deploying or deployed) for environments. If it's the first time the branch is deployed, the link -will return a `404` error until done. During the deployment, the stop button will -be disabled. If the pipeline fails to deploy, the deployment information will be hidden. +returns a `404` error until done. During the deployment, the stop button is +disabled. If the pipeline fails to deploy, the deployment information is hidden.  @@ -263,14 +270,15 @@ For more information, [read about pipelines](../../../ci/pipelines/index.md). ### Merge when pipeline succeeds (MWPS) -Set a merge request that looks ready to merge to [merge automatically when CI pipeline succeeds](merge_when_pipeline_succeeds.md). +Set a merge request that looks ready to merge to +[merge automatically when CI pipeline succeeds](merge_when_pipeline_succeeds.md). ### Live preview with Review Apps If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, -you can preview the changes submitted to a feature-branch through a merge request -in a per-branch basis. No need to checkout the branch, install and preview locally; -all your changes will be available to preview by anyone with the Review Apps link. +you can preview the changes submitted to a feature branch through a merge request +on a per-branch basis. You don't need to checkout the branch, install, and preview locally. +All your changes are available to preview by anyone with the Review Apps link. With GitLab [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the merge request widget takes you directly to the pages changed, making it easier and @@ -280,21 +288,26 @@ faster to preview proposed modifications. ## Associated features -There is also a large number of features to associated to merge requests: - -| Feature | Description | -|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Bulk editing merge requests](../../project/bulk_editing.md) | Update the attributes of multiple merge requests simultaneously. | -| [Cherry-pick changes](cherry_pick_changes.md) | Cherry-pick any commit in the UI by simply clicking the **Cherry-pick** button in a merged merge requests or a commit. | -| [Fast-forward merge requests](fast_forward_merge.md) | For a linear Git history and a way to accept merge requests without creating merge commits | -| [Find the merge request that introduced a change](versions.md) | When viewing the commit details page, GitLab will link to the merge request(s) containing that commit. | -| [Merge requests versions](versions.md) | Select and compare the different versions of merge request diffs | -| [Resolve conflicts](resolve_conflicts.md) | GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. | -| [Revert changes](revert_changes.md) | Revert changes from any commit from within a merge request. | +These features are associated with merge requests: + +- [Bulk editing merge requests](../../project/bulk_editing.md): + Update the attributes of multiple merge requests simultaneously. +- [Cherry-pick changes](cherry_pick_changes.md): + Cherry-pick any commit in the UI by clicking the **Cherry-pick** button in a merged merge requests or a commit. +- [Fast-forward merge requests](fast_forward_merge.md): + For a linear Git history and a way to accept merge requests without creating merge commits +- [Find the merge request that introduced a change](versions.md): + When viewing the commit details page, GitLab links to the merge request(s) containing that commit. +- [Merge requests versions](versions.md): + Select and compare the different versions of merge request diffs +- [Resolve conflicts](resolve_conflicts.md): + GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. +- [Revert changes](revert_changes.md): + Revert changes from any commit from a merge request. ## Troubleshooting -Sometimes things don't go as expected in a merge request, here are some +Sometimes things don't go as expected in a merge request. Here are some troubleshooting steps. ### Merge request cannot retrieve the pipeline status @@ -304,7 +317,7 @@ This can occur if Sidekiq doesn't pick up the changes fast enough. #### Sidekiq Sidekiq didn't process the CI state change fast enough. Please wait a few -seconds and the status will update automatically. +seconds and the status should update automatically. #### Bug @@ -320,12 +333,9 @@ Merge Request again. ## Tips -Here are some tips that will help you be more efficient with merge requests in +Here are some tips to help you be more efficient with merge requests in the command line. -NOTE: -This section might move in its own document in the future. - ### Copy the branch name for local checkout > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. @@ -334,7 +344,7 @@ The merge request sidebar contains the branch reference for the source branch used to contribute changes for this merge request. To copy the branch reference into your clipboard, click the **Copy branch name** button -(**{copy-to-clipboard}**) in the right sidebar. You can then use it to checkout the branch locally +(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally via command line by running `git checkout <branch-name>`. ### Checkout merge requests locally through the `head` ref @@ -343,7 +353,7 @@ A merge request contains all the history from a repository, plus the additional commits added to the branch associated with the merge request. Here's a few ways to checkout a merge request locally. -Please note that you can checkout a merge request locally even if the source +You can checkout a merge request locally even if the source project is a fork (even a private fork) of the target project. This relies on the merge request `head` ref (`refs/merge-requests/:iid/head`) @@ -352,10 +362,10 @@ request via its ID instead of its branch. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223156) in GitLab 13.4, 14 days after a merge request gets closed or merged, the merge request -`head` ref will be deleted. This means that the merge request will not be available +`head` ref is deleted. This means that the merge request is not available for local checkout via the merge request `head` ref anymore. The merge request -can still be re-opened. Also, as long as the merge request's branch -exists, you can still check out the branch as it won't be affected. +can still be re-opened. If the merge request's branch +exists, you can still check out the branch, as it isn't affected. #### Checkout locally by adding a Git alias @@ -374,7 +384,7 @@ from the `origin` remote, do: git mr origin 5 ``` -This will fetch the merge request into a local `mr-origin-5` branch and check +This fetches the merge request into a local `mr-origin-5` branch and check it out. #### Checkout locally by modifying `.git/config` for a given repository diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index 3d84be802ec..43ab03114fa 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -9,8 +9,8 @@ type: reference, concepts If a merge request is not yet ready to be merged, perhaps due to continued development or open threads, you can prevent it from being accepted before it's ready by flagging -it as a **Draft**. This will disable the "Merge" button, preventing it from -being merged, and it will stay disabled until the "Draft" flag has been removed. +it as a **Draft**. This disables the **Merge** button, preventing it from +being merged. It stays disabled until the **Draft** flag has been removed.  @@ -22,7 +22,7 @@ To run pipelines for merged results, you must [remove the draft status](#removin ## Adding the "Draft" flag to a merge request -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** will be removed in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** is scheduled for removal in GitLab 14.0. > - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. There are several ways to flag a merge request as a Draft: @@ -30,15 +30,15 @@ There are several ways to flag a merge request as a Draft: - Click the **Mark as draft** button on the top-right corner of the merge request's page. - Add `[Draft]`, `Draft:` or `(Draft)` to the start of the merge request's title. Clicking on **Start the title with Draft:**, under the title box, when editing the merge request's - description will have the same effect. + description has the same effect. - **Deprecated** Add `[WIP]` or `WIP:` to the start of the merge request's title. - **WIP** still works but was deprecated in favor of **Draft**. It will be removed in the next major version (GitLab 14.0). + **WIP** still works but was deprecated in favor of **Draft**. It is scheduled for removal in the next major version (GitLab 14.0). - Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) in a comment in the merge request. This is a toggle, and can be repeated - to change the status back. Note that any other text in the comment will be discarded. + to change the status back. Note that any other text in the comment is discarded. - Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the merge request's source branch. This is not a toggle, and doing it again in another - commit will have no effect. + commit has no effect. ## Removing the "Draft" flag from a merge request @@ -48,10 +48,10 @@ Similar to above, when a Merge Request is ready to be merged, you can remove the - Click the **Mark as ready** button on the top-right corner of the merge request's page. - Remove `[Draft]`, `Draft:` or `(Draft)` from the start of the merge request's title. Clicking on **Remove the Draft: prefix from the title**, under the title box, when editing the merge - request's description, will have the same effect. + request's description, has the same effect. - Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) in a comment in the merge request. This is a toggle, and can be repeated - to change the status back. Note that any other text in the comment will be discarded. + to change the status back. Note that any other text in the comment is discarded. - Click on the **Resolve Draft status** button near the bottom of the merge request description, next to the **Merge** button (see [image above](#draft-merge-requests)). Must have at least Developer level permissions on the project for the button to @@ -60,8 +60,8 @@ Similar to above, when a Merge Request is ready to be merged, you can remove the ## Including/excluding WIP merge requests when searching When viewing/searching the merge requests list, you can choose to include or exclude -WIP merge requests by adding a "WIP" filter in the search box, and choosing "Yes" -(to include) or "No" (to exclude). +WIP merge requests. Add a **WIP** filter in the search box, and choose **Yes** +to include, or **No** to exclude.  diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 5754a3b7a9d..ede130513bc 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -13,7 +13,7 @@ further restrictions on certain branches, they can be protected. ## Overview -By default, a protected branch does four simple things: +By default, a protected branch does these things: - It prevents its creation, if not already created, from everybody except users with Maintainer permission. @@ -30,49 +30,47 @@ The default branch protection level is set in the [Admin Area](../admin_area/set ## Configuring protected branches -To protect a branch, you need to have at least Maintainer permission level. Note -that the `master` branch is protected by default. +To protect a branch, you need to have at least Maintainer permission level. +The `master` branch is protected by default. -1. Navigate to your project's **Settings ➔ Repository** +1. In your project, go to **Settings > Repository**. 1. Scroll to find the **Protected branches** section. 1. From the **Branch** dropdown menu, select the branch you want to protect and click **Protect**. In the screenshot below, we chose the `develop` branch.  -1. Once done, the protected branch will appear in the "Protected branches" list. +1. Once done, the protected branch displays in the **Protected branches** list.  ## Using the Allowed to merge and Allowed to push settings -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in GitLab 8.11. - In GitLab 8.11 and later, we added another layer of branch protection which provides -more granular management of protected branches. The "Developers can push" -option was replaced by an "Allowed to push" setting which can be set to -allow/prohibit Maintainers and/or Developers to push to a protected branch. +more granular management of protected branches. The **Developers can push** +option was replaced by **Allowed to push**. You can set this value to allow +or prohibit Maintainers and/or Developers to push to a protected branch. -Using the "Allowed to push" and "Allowed to merge" settings, you can control +Using the **Allowed to push** and **Allowed to merge** settings, you can control the actions that different roles can perform with the protected branch. -For example, you could set "Allowed to push" to "No one", and "Allowed to merge" -to "Developers + Maintainers", to require _everyone_ to submit a merge request for +For example, you could set **Allowed to push** to "No one", and **Allowed to merge** +to "Developers + Maintainers", to require everyone to submit a merge request for changes going into the protected branch. This is compatible with workflows like the [GitLab workflow](../../topics/gitlab_flow.md). However, there are workflows where that is not needed, and only protecting from force pushes and branch removal is useful. For those workflows, you can allow everyone with write access to push to a protected branch by setting -"Allowed to push" to "Developers + Maintainers". +**Allowed to push** to "Developers + Maintainers". -You can set the "Allowed to push" and "Allowed to merge" options while creating +You can set the **Allowed to push** and **Allowed to merge** options while creating a protected branch or afterwards by selecting the option you want from the -dropdown list in the "Already protected" area. +dropdown list in the **Already protected** area.  If you don't choose any of those options while creating a protected branch, -they are set to "Maintainers" by default. +they are set to Maintainers by default. ### Allow Deploy Keys to push to a protected branch @@ -88,7 +86,7 @@ Deploy keys can be selected in the **Allowed to push** dropdown when: - Defining a protected branch. - Updating an existing branch. -Select a deploy key to allow the owner of the key to push to the chosen protected branch, +Select a deploy key to allow the key's owner to push to the chosen protected branch, even if they aren't a member of the related project. The owner of the selected deploy key must have at least read access to the given project. @@ -103,24 +101,20 @@ Deploy Keys are not available in the **Allowed to merge** dropdown. ## Restricting push and merge access to certain users **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.11. - With GitLab Enterprise Edition you can restrict access to protected branches -by choosing a role (Maintainers, Developers) as well as certain users. From the +by choosing a role (Maintainers, Developers) and certain users. From the dropdown menu select the role and/or the users you want to have merge or push access.  -Click **Protect** and the branch will appear in the "Protected branch" list. +Click **Protect** and the branch displays in the **Protected branch** list.  ## Wildcard protected branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4665) in GitLab 8.10. - -You can specify a wildcard protected branch, which will protect all branches +You can specify a wildcard protected branch, which protects all branches matching the wildcard. For example: | Wildcard Protected Branch | Matching Branches | @@ -129,15 +123,15 @@ matching the wildcard. For example: | `production/*` | `production/app-server`, `production/load-balancer` | | `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` | -Protected branch settings (like "Developers can push") apply to all matching +Protected branch settings, like **Developers can push**, apply to all matching branches. Two different wildcards can potentially match the same branch. For example, `*-stable` and `production-*` would both match a `production-stable` branch. In that case, if _any_ of these protected branches have a setting like -"Allowed to push", then `production-stable` will also inherit this setting. +"Allowed to push", then `production-stable` also inherit this setting. -If you click on a protected branch's name, you will be presented with a list of +If you click on a protected branch's name, GitLab displays a list of all matching branches:  @@ -151,41 +145,36 @@ When a protected branch or wildcard protected branches are set to Developers (and users with higher [permission levels](../permissions.md)) are allowed to create a new protected branch as long as they are [**Allowed to merge**](#using-the-allowed-to-merge-and-allowed-to-push-settings). -This can only be done via the UI or through the API (to avoid creating protected -branches accidentally from the command line or from a Git client application). +This can only be done by using the UI or through the API, to avoid creating protected +branches accidentally from the command line or from a Git client application. To create a new branch through the user interface: -1. Visit **Repository > Branches**. +1. Go to **Repository > Branches**. 1. Click on **New branch**. -1. Fill in the branch name and select an existing branch, tag, or commit that - the new branch will be based off. Only existing protected branches and commits - that are already in protected branches will be accepted. +1. Fill in the branch name and select an existing branch, tag, or commit to + base the new branch on. Only existing protected branches and commits + that are already in protected branches are accepted. ## Deleting a protected branch -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393) in GitLab 9.3. - -From time to time, it may be required to delete or clean up branches that are -protected. +From time to time, you may need to delete or clean up protected branches. +User with [Maintainer permissions](../permissions.md) and greater can manually delete protected +branches by using the GitLab web interface: -User with [Maintainer permissions](../permissions.md) and up can manually delete protected -branches via the GitLab web interface: - -1. Visit **Repository > Branches** -1. Click on the delete icon next to the branch you wish to delete -1. In order to prevent accidental deletion, an additional confirmation is - required +1. Go to **Repository > Branches**. +1. Click on the delete icon next to the branch you wish to delete. +1. To prevent accidental deletion, an additional confirmation is required.  -Deleting a protected branch is only allowed via the web interface, not via Git. +Deleting a protected branch is allowed only by using the web interface; not from Git. This means that you can't accidentally delete a protected branch from your command line or a Git client application. ## Protected Branches approval by Code Owners **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4. It is possible to require at least one approval by a [Code Owner](code_owners.md) to a file changed by the @@ -208,7 +197,7 @@ To enable Code Owner's approval to branches already protected:  -When enabled, all merge requests targeting these branches will require approval +When enabled, all merge requests targeting these branches require approval by a Code Owner per matched rule before they can be merged. Additionally, direct pushes to the protected branch are denied if a rule is matched. @@ -224,26 +213,9 @@ for details about the pipelines security model. ## Changelog -**13.5** - -- [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). - -**11.9** - -- [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) by Developers (and users with higher permission levels) through the API and the user interface. - -**9.2** - -- Allow deletion of protected branches via the web interface ([issue #21393](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393)). - -**8.11** - -- Allow creating protected branches that can't be pushed to ([merge request !5081](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081)). - -**8.10** - -- Allow developers without push access to merge into a protected branch ([merge request !4892](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4892)). -- Allow specifying protected branches using wildcards ([merge request !4665](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4665)). +- **13.5**: [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). +- **11.9**: [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) + by Developers (and users with higher permission levels) through the API and the user interface. <!-- ## Troubleshooting diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 7e09c526312..a6f2d645198 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -15,11 +15,13 @@ This feature evolved out of [protected branches](protected_branches.md) ## Overview -Protected tags will prevent anyone from updating or deleting the tag, and will prevent creation of matching tags based on the permissions you have selected. By default, anyone without Maintainer permission will be prevented from creating tags. +Protected tags prevent anyone from updating or deleting the tag, and prevent +creation of matching tags based on the permissions you have selected. By default, +anyone without Maintainer [permissions](../permissions.md) is prevented from creating tags. ## Configuring protected tags -To protect a tag, you need to have at least Maintainer permission level. +To protect a tag, you need to have at least Maintainer [permissions](../permissions.md). 1. Navigate to the project's **Settings > Repository**: @@ -29,17 +31,18 @@ To protect a tag, you need to have at least Maintainer permission level.  -1. From the **Allowed to create** dropdown, select who will have permission to create matching tags and then click **Protect**: +1. From the **Allowed to create** dropdown, select users with permission to create + matching tags, and click **Protect**:  -1. Once done, the protected tag will appear in the **Protected tags** list: +1. After done, the protected tag displays in the **Protected tags** list:  ## Wildcard protected tags -You can specify a wildcard protected tag, which will protect all tags +You can specify a wildcard protected tag, which protects all tags matching the wildcard. For example: | Wildcard Protected Tag | Matching Tags | @@ -52,9 +55,9 @@ matching the wildcard. For example: Two different wildcards can potentially match the same tag. For example, `*-stable` and `production-*` would both match a `production-stable` tag. In that case, if _any_ of these protected tags have a setting like -**Allowed to create**, then `production-stable` will also inherit this setting. +**Allowed to create**, then `production-stable` also inherit this setting. -If you click on a protected tag's name, you will be presented with a list of +If you click on a protected tag's name, GitLab displays a list of all matching tags:  diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 68f69f3ac8b..590f549577e 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -8,7 +8,7 @@ type: reference, howto # Project access tokens NOTE: -Project access tokens are supported for self-managed instances on Core and above. They are also supported on GitLab.com Bronze and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). +Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. > - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5 for paid groups only. |
