diff options
Diffstat (limited to 'doc/user')
266 files changed, 3070 insertions, 2495 deletions
diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md index 935fca8209f..e2f2038f240 100644 --- a/doc/user/abuse_reports.md +++ b/doc/user/abuse_reports.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Abuse reports +# Abuse reports **(FREE)** You can report abuse from other GitLab users to GitLab administrators. @@ -12,7 +12,7 @@ A GitLab administrator [can then choose](admin_area/abuse_reports.md) to: - Remove the user, which deletes them from the instance. - Block the user, which denies them access to the instance. -- Or remove the report, which retains the users access to the instance. +- Or remove the report, which retains the user's access to the instance. You can report a user through their: diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index 5cf5e33f2d2..bea22745e7b 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -14,4 +14,3 @@ There are several kinds of statistics: - [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. **(FREE)** - [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how that is changing. **(FREE)** -- [User Cohorts](user_cohorts.md): Display the monthly cohorts of new users and their activities over time. **(FREE)** diff --git a/doc/user/admin_area/analytics/instance_statistics.md b/doc/user/admin_area/analytics/instance_statistics.md deleted file mode 100644 index e44dd891029..00000000000 --- a/doc/user/admin_area/analytics/instance_statistics.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'usage_trends.md' ---- - -This document was moved to [another location](usage_trends.md). - -<!-- This redirect file can be deleted after <2022-03-20>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index 0c0cae09c16..38cd2dee4e9 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -40,22 +40,3 @@ in the categories shown in [Total counts](#total-counts). These charts help you visualize how rapidly these records are being created on your instance.  - -### Enable or disable Usage Trends - -In GitLab version 13.5 only, Usage Trends was under development and not ready for production use. -It was deployed behind a feature flag that was **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to enable it. - -To enable it: - -```ruby -Feature.enable(:instance_statistics) -``` - -To disable it: - -```ruby -Feature.disable(:instance_statistics) -``` diff --git a/doc/user/admin_area/analytics/user_cohorts.md b/doc/user/admin_area/analytics/user_cohorts.md index a7c93160b69..ca5dff85757 100644 --- a/doc/user/admin_area/analytics/user_cohorts.md +++ b/doc/user/admin_area/analytics/user_cohorts.md @@ -1,36 +1,8 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../user_cohorts.md' --- -# Cohorts **(FREE)** +This document was moved to [another location](../user_cohorts.md). -As a benefit of having the [usage ping active](../settings/usage_statistics.md), -you can analyze your users' GitLab activities over time. - -To see user cohorts, go to **Admin Area > Overview > Users**. - -## Overview - -How do you interpret the user cohorts table? Let's review an example with the -following user cohorts: - - - -For the cohort of March 2020, three users were added to this server and have -been active since this month. One month later (April 2020), two users are still -active. Five months later (August 2020), one user from this cohort is still -active, or 33% of the original cohort of three that joined in March. - -The **Inactive users** column shows the number of users who were added during -the month, but who never had any activity in the instance. - -How do we measure the activity of users? GitLab considers a user active if: - -- The user signs in. -- The user has Git activity (whether push or pull). -- The user visits pages related to dashboards, projects, issues, or merge - requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54947) in GitLab 11.8). -- The user uses the API. -- The user uses the GraphQL API. +<!-- This redirect file can be deleted after <2021-06-01>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/approving_users.md b/doc/user/admin_area/approving_users.md index af4d4e86e69..9141d7f488d 100644 --- a/doc/user/admin_area/approving_users.md +++ b/doc/user/admin_area/approving_users.md @@ -7,30 +7,49 @@ type: howto # Users pending approval -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5. +A user in _pending approval_ state requires action by an administrator. A user sign up can be in a +pending approval state because an administrator has enabled either, or both, of the following +options: -When [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) is enabled, any user that signs up for an account using the registration form is placed under a **Pending approval** state. +- [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) setting. +- [User cap](settings/sign_up_restrictions.md#user-cap). -A user pending approval is functionally identical to a [blocked](blocking_unblocking_users.md) user. +When a user registers for an account while this setting is enabled: + +- The user is placed in a **Pending approval** state. +- The user sees a message telling them their account is awaiting approval by an administrator. A user pending approval: -- Will not be able to sign in. -- Cannot access Git repositories or the API. -- Will not receive any notifications from GitLab. +- Is functionally identical to a [blocked](blocking_unblocking_users.md) user. +- Cannot sign in. +- Cannot access Git repositories or the GitLab API. +- Does not receive any notifications from GitLab. - Does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). -## Approving a user +An administrator must [approve their sign up](#approve-or-reject-a-user-sign-up) to allow them to +sign in. + +## View user sign ups pending approval + +To view user sign ups pending approval: + +1. Go to **Admin Area > Overview > Users**. +1. Select the **Pending approval** tab. + +## Approve or reject a user sign up + +A user sign up pending approval can be approved or rejected from the Admin Area. -A user that is pending approval can be approved from the Admin Area. To do this: +To approve or reject a user sign up: -1. Navigate to **Admin Area > Overview > Users**. -1. Click on the **Pending approval** tab. -1. Select a user. -1. Under the **Account** tab, click **Approve user**. +1. Go to **Admin Area > Overview > Users**. +1. Select the **Pending approval** tab. +1. In the user's row select settings (**{settings}**). +1. Select **Approve** or **Reject**. Approving a user: -1. Activates their account. -1. Changes the user's state to active and it consumes a -[seat](../../subscriptions/self_managed/index.md#billable-users). +- Activates their account. +- Changes the user's state to active. +- Consumes a subscription [seat](../../subscriptions/self_managed/index.md#billable-users). diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index 02659276b53..053cee82634 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -11,7 +11,9 @@ type: howto GitLab administrators are responsible for the overall security of their instance. To assist, GitLab provides a Credentials inventory to keep track of all the credentials that can be used to access their self-managed instance. -Using Credentials inventory, you can see all the personal access tokens (PAT) and SSH keys that exist in your GitLab instance. In addition, you can [revoke](#revoke-a-users-personal-access-token) and [delete](#delete-a-users-ssh-key) and see: +Using Credentials inventory, you can see all the personal access tokens (PAT), SSH keys, and GPG keys +that exist in your GitLab instance. In addition, you can [revoke](#revoke-a-users-personal-access-token) +and [delete](#delete-a-users-ssh-key) and see: - Who they belong to. - Their access scope. @@ -23,7 +25,7 @@ To access the Credentials inventory, navigate to **Admin Area > Credentials**. The following is an example of the Credentials inventory page: - + ## Revoke a user's personal access token @@ -31,7 +33,7 @@ The following is an example of the Credentials inventory page: If you see a **Revoke** button, you can revoke that user's PAT. Whether you see a **Revoke** button depends on the token state, and if an expiration date has been set. For more information, see the following table: -| Token state | [Token expiry enforced?](settings/account_and_limit_settings.md#optional-enforcement-of-personal-access-token-expiry) | Show Revoke button? | Comments | +| Token state | [Token expiration enforced?](settings/account_and_limit_settings.md#optional-non-enforcement-of-personal-access-token-expiration) | Show Revoke button? | Comments | |-------------|------------------------|--------------------|----------------------------------------------------------------------------| | Active | Yes | Yes | Allows administrators to revoke the PAT, such as for a compromised account | | Active | No | Yes | Allows administrators to revoke the PAT, such as for a compromised account | @@ -50,3 +52,39 @@ You can **Delete** a user's SSH key by navigating to the credentials inventory's The instance then notifies the user.  + +## Review existing GPG keys + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/282429) in GitLab 13.10. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-the-gpg-keys-view). + +You can view all existing GPG in your GitLab instance by navigating to the +credentials inventory GPG Keys tab, as well as the following properties: + +- Who the GPG key belongs to. +- The ID of the GPG key. +- Whether the GPG key is [verified or unverified](../project/repository/gpg_signed_commits/index.md) + + + +### Enable or disable the GPG keys view + +Enabling or disabling the GPG keys view is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:credential_inventory_gpg_keys) +``` + +To disable it: + +```ruby +Feature.disable(:credential_inventory_gpg_keys) +``` diff --git a/doc/user/admin_area/analytics/img/cohorts_v13_9.png b/doc/user/admin_area/img/cohorts_v13_9.png Binary files differindex 6a616b201c9..6a616b201c9 100644 --- a/doc/user/admin_area/analytics/img/cohorts_v13_9.png +++ b/doc/user/admin_area/img/cohorts_v13_9.png diff --git a/doc/user/admin_area/img/credentials_inventory_gpg_keys_v13_10.png b/doc/user/admin_area/img/credentials_inventory_gpg_keys_v13_10.png Binary files differnew file mode 100644 index 00000000000..2486332c477 --- /dev/null +++ b/doc/user/admin_area/img/credentials_inventory_gpg_keys_v13_10.png diff --git a/doc/user/admin_area/img/credentials_inventory_v13_10.png b/doc/user/admin_area/img/credentials_inventory_v13_10.png Binary files differnew file mode 100644 index 00000000000..e41bbf35a8e --- /dev/null +++ b/doc/user/admin_area/img/credentials_inventory_v13_10.png diff --git a/doc/user/admin_area/img/credentials_inventory_v13_4.png b/doc/user/admin_area/img/credentials_inventory_v13_4.png Binary files differdeleted file mode 100644 index 06925ea2f6f..00000000000 --- a/doc/user/admin_area/img/credentials_inventory_v13_4.png +++ /dev/null diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index b5e51e8d4c0..40e0e2856bd 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -33,7 +33,7 @@ The Admin Area is made up of the following sections: | **{cloud-gear}** Kubernetes | Create and manage instance-level [Kubernetes clusters](../instance/clusters/index.md). | | **{push-rules}** Push rules **(STARTER ONLY)** | Configure pre-defined Git [push rules](../../push_rules/push_rules.md) for projects. Also, configure [merge requests approvers rules](merge_requests_approvals.md). **(PREMIUM SELF)** | | **{location-dot}** Geo **(PREMIUM SELF)** | Configure and maintain [Geo nodes](geo_nodes.md). | -| **{key}** Deploy keys | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys). | +| **{key}** Deploy keys | Create instance-wide [SSH deploy keys](../project/deploy_keys/index.md). | | **{lock}** Credentials **(ULTIMATE SELF)** | View [credentials](credentials_inventory.md) that can be used to access your instance. | | **{template}** Service Templates | Create [service templates](../project/integrations/services_templates.md) for projects. | | **{labels}** Labels | Create and maintain [labels](labels.md) for your GitLab instance. | @@ -157,6 +157,22 @@ All impersonation activities are [captured with audit events](../../administrati  +#### User Permission Export **(PREMIUM SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1772) in GitLab 13.8. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292436) in GitLab 13.9. + +An administrator can export user permissions for all users in the GitLab instance from the Admin Area's Users page. +The export lists direct membership the users have in groups and projects. + +The following data is included in the export: + +- Username +- Email +- Type +- Path +- Access level ([Project](../permissions.md#project-members-permissions) and [Group](../permissions.md#group-members-permissions)) + #### Users statistics The **Users statistics** page provides an overview of user accounts by role. These statistics are @@ -170,6 +186,10 @@ The following totals are also included: GitLab billing is based on the number of [**Billable users**](../../subscriptions/self_managed/index.md#billable-users). +### User cohorts + +The [Cohorts](user_cohorts.md) tab displays the monthly cohorts of new users and their activities over time. + ### Administering Groups You can administer all groups in the GitLab instance from the Admin Area's Groups page. @@ -187,7 +207,7 @@ sort order is by **Last created**. To search for groups by name, enter your criteria in the search field. The group search is case insensitive, and applies partial matching. -To [Create a new group](../group/index.md#create-a-new-group) click **New group**. +To [Create a new group](../group/index.md#create-a-group) click **New group**. ### Administering Jobs diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 505f54e9ae9..89417de4bab 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Activate GitLab EE with a license **(STARTER ONLY)** +# Activate GitLab EE with a license **(PREMIUM SELF)** To activate all GitLab Enterprise Edition (EE) functionality, you need to upload a license. It's only possible to activate GitLab Enterprise Edition, so first verify which edition diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 70416c224c7..0f391118215 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -152,20 +152,20 @@ To set a limit on how long these sessions are valid: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab Ultimate 12.6. -Users can optionally specify an expiration date for +Users can optionally specify a lifetime for [personal access tokens](../../profile/personal_access_tokens.md). -This expiration date is not a requirement, and can be set to any arbitrary date. +This lifetime is not a requirement, and can be set to any arbitrary number of days. Personal access tokens are the only tokens needed for programmatic access to GitLab. However, organizations with security requirements may want to enforce more protection by requiring the regular rotation of these tokens. -### Setting a limit +### Setting a lifetime -Only a GitLab administrator can set a limit. Leaving it empty means +Only a GitLab administrator can set a lifetime. Leaving it empty means there are no restrictions. -To set a limit on how long personal access tokens are valid: +To set a lifetime on how long personal access tokens are valid: 1. Navigate to **Admin Area > Settings > General**. 1. Expand the **Account and limit** section. @@ -180,24 +180,28 @@ Once a lifetime for personal access tokens is set, GitLab: allowed lifetime. Three hours is given to allow administrators to change the allowed lifetime, or remove it, before revocation takes place. -## Enforcement of SSH key expiration **(ULTIMATE SELF)** +## Optional enforcement of SSH key expiration **(ULTIMATE SELF)** -GitLab administrators can choose to enforce the expiration of SSH keys after their expiration dates. -If you enable this feature, this disables all _expired_ SSH keys. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250480) in GitLab 13.9. -To do this: +By default, expired SSH keys **can still be used**. +You can prevent the use of expired SSH keys with the following steps: 1. Navigate to **Admin Area > Settings > General**. 1. Expand the **Account and limit** section. 1. Select the **Enforce SSH key expiration** checkbox. -## Optional enforcement of Personal Access Token expiry **(ULTIMATE SELF)** +Enforcing SSH key expiration immediately disables all expired SSH keys. + +For more information, see the following issue on [SSH key expiration](https://gitlab.com/gitlab-org/gitlab/-/issues/320970). + +## Optional non-enforcement of Personal Access Token expiration **(ULTIMATE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214723) in GitLab Ultimate 13.1. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/296881) in GitLab 13.9. -GitLab administrators can choose to prevent personal access tokens from expiring -automatically. The tokens are usable after the expiry date, unless they are revoked explicitly. +By default, expired personal access tokens (PATs) cannot be used. +You can allow the use of expired PATs with the following steps: To do this: diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 761fc6477d6..3d19bde9a26 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -27,7 +27,7 @@ From now on, every existing project and newly created ones that don't have a `.gitlab-ci.yml`, will use the Auto DevOps pipelines. If you want to disable it for a specific project, you can do so in -[its settings](../../../topics/autodevops/index.md#enablingdisabling-auto-devops). +[its settings](../../../topics/autodevops/index.md#enable-or-disable-auto-devops). ## Maximum artifacts size **(FREE SELF)** @@ -50,15 +50,15 @@ To change it at the: 1. Change the value of maximum artifacts size (in MB). 1. Click **Save changes** for the changes to take effect. -- [Group level](../../group/index.md#group-settings) (this will override the instance setting): +- Group level (this will override the instance setting): - 1. Go to the group's **Settings > CI / CD > General Pipelines**. + 1. Go to the group's **Settings > CI/CD > General Pipelines**. 1. Change the value of **maximum artifacts size (in MB)**. 1. Click **Save changes** for the changes to take effect. -- [Project level](../../../ci/pipelines/settings.md) (this will override the instance and group settings): +- Project level (this will override the instance and group settings): - 1. Go to the project's **Settings > CI / CD > General Pipelines**. + 1. Go to the project's **Settings > CI/CD > General Pipelines**. 1. Change the value of **maximum artifacts size (in MB)**. 1. Click **Save changes** for the changes to take effect. @@ -99,6 +99,13 @@ are allowed to expire. This setting takes precedence over the [project level setting](../../../ci/pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). If disabled at the instance level, you cannot enable this per-project. +To disable the setting: + +1. Go to **Admin Area > Settings > CI/CD**. +1. Expand **Continuous Integration and Deployment**. +1. Clear the **Keep the latest artifacts for all jobs in the latest successful pipelines** checkbox. +1. Click **Save changes** + When you disable the feature, the latest artifacts do not immediately expire. A new pipeline must run before the latest artifacts can expire and be deleted. diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 3377b1674db..cbdc617d7d9 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -35,7 +35,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | ------ | ----------- | | [Elasticsearch](../../../integration/elasticsearch.md#enabling-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. | | [Kroki](../../../administration/integration/kroki.md#enable-kroki-in-gitlab) | Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). | -| [PlantUML](../../../administration/integration/plantuml.md#gitlab) | Allow rendering of PlantUML diagrams in AsciiDoc and Markdown documents. | +| [PlantUML](../../../administration/integration/plantuml.md) | Allow rendering of PlantUML diagrams in documents. | | [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) **(FREE SAAS)** | Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). | | [Third party offers](third_party_offers.md) | Control the display of third party offers. | | [Snowplow](../../../development/snowplow.md) | Configure the Snowplow integration. | diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 7630f0c2fbd..600d99934aa 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -5,9 +5,9 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Instance template repository **(PREMIUM SELF)** **(FREE)** +# Instance template repository **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in GitLab Premium 11.3. In hosted systems, enterprises often have a need to share their own templates across teams. This feature allows an administrator to pick a project to be the @@ -23,7 +23,7 @@ select the project to serve as the custom template repository.  After that, you can add custom templates to the selected repository and use them for the entire instance. -They will be available on the [Web Editor's dropdown](../../project/repository/web_editor.md#template-dropdowns) +They are available in the [Web Editor's dropdown](../../project/repository/web_editor.md#template-dropdowns) and through the [API settings](../../../api/settings.md). Templates must be added to a specific subdirectory in the repository, @@ -60,12 +60,12 @@ extension and not be empty. So, the hierarchy should look like this: |-- another_metrics-dashboard.yml ``` -Your custom templates will be displayed on the dropdown menu when a new file is added through the GitLab UI: +Your custom templates are displayed on the dropdown menu when a new file is added through the GitLab UI:  -If this feature is disabled or no templates are present, there will be -no "Custom" section in the selection dropdown. +If this feature is disabled or no templates are present, +no **Custom** section displays in the selection dropdown. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index 18491f92650..0b9f039880a 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project integration management +# Project integration management **(FREE)** Project integrations can be configured and enabled by project administrators. As a GitLab instance administrator, you can set default configuration parameters for a given integration that all projects diff --git a/doc/user/admin_area/settings/push_event_activities_limit.md b/doc/user/admin_area/settings/push_event_activities_limit.md index 1d6424face0..7032c1031a9 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.md @@ -14,7 +14,7 @@ allowed at once. If the number of events is greater than this, GitLab creates bulk push event instead. For example, if 4 branches are pushed and the limit is currently set to 3, -you'll see the following in the activity feed: +the activity feed displays:  diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 0945471b11b..0078db286a8 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -30,7 +30,7 @@ To disable sign ups: > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/267568) in GitLab 13.6. -When this setting is enabled, any user visiting your GitLab domain and signing up for a new account must be explicitly [approved](../approving_users.md#approving-a-user) by an administrator before they can start using their account. This setting is enabled by default for newly created instances. This setting is only applicable if sign ups are enabled. +When this setting is enabled, any user visiting your GitLab domain and signing up for a new account must be explicitly [approved](../approving_users.md#approve-or-reject-a-user-sign-up) by an administrator before they can start using their account. In GitLab 13.6 and later, this setting is enabled by default for new GitLab instances. It is only applicable if sign ups are enabled. To require administrator approval for new sign ups: @@ -56,10 +56,29 @@ To enforce confirmation of the email address used for new sign ups: > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292600) in GitLab 13.9. When the number of billable users reaches the user cap, any user who is added or requests access must be -[approved](../approving_users.md#approving-a-user) by an administrator before they can start using +[approved](../approving_users.md#approve-or-reject-a-user-sign-up) by an administrator before they can start using their account. -If an administrator increases or removes the user cap, the users in pending approval state are +If an administrator [increases](#set-the-user-cap-number) or [removes](#remove-the-user-cap) the +user cap, the users in pending approval state are automatically approved in a background job. + +### Set the user cap number + +1. Go to **Admin Area > Settings > General**. +1. Expand **Sign-up restrictions**. +1. Enter a number in **User cap**. +1. Select **Save changes**. + +New user sign ups are subject to the user cap restriction. + +## Remove the user cap + +1. Go to **Admin Area > Settings > General**. +1. Expand **Sign-up restrictions**. +1. Remove the number from **User cap**. +1. Select **Save changes**. + +New users sign ups are not subject to the user cap restriction. Users in pending approval state are automatically approved in a background job. ## Soft email confirmation diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 2bb6adbc32b..ada44115cec 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -61,7 +61,7 @@ sequenceDiagram ## Usage Ping **(FREE SELF)** -See [Usage Ping guide](../../../development/usage_ping.md). +See [Usage Ping guide](../../../development/usage_ping/index.md). ## Instance-level analytics availability diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index 0fcdbf3ca90..e335a9031d5 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -29,7 +29,7 @@ To change the default branch protection: For more details, see [Protected branches](../../project/protected_branches.md). -To change this setting for a specific group, see [Default branch protection for groups](../../group/index.md#changing-the-default-branch-protection-of-a-group) +To change this setting for a specific group, see [Default branch protection for groups](../../group/index.md#change-the-default-branch-protection-of-a-group) ### Disable group owners from updating default branch protection **(PREMIUM SELF)** @@ -55,7 +55,7 @@ To change the default project creation protection: 1. Select the desired option. 1. Click **Save changes**. -For more details, see [Default project-creation level](../../group/index.md#default-project-creation-level). +For more details, see [Specify who can add projects to a group](../../group/index.md#specify-who-can-add-projects-to-a-group). ## Default project deletion protection **(PREMIUM SELF)** @@ -79,7 +79,7 @@ The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org [Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. Projects in a group (but not a personal namespace) can be deleted after a delayed period, by -[configuring in Group Settings](../../group/index.md#enabling-delayed-project-removal). +[configuring in Group Settings](../../group/index.md#enable-delayed-project-removal). The default period is seven days, and can be changed. Setting this period to `0` enables immediate removal of projects or groups. diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md new file mode 100644 index 00000000000..f3c913b409a --- /dev/null +++ b/doc/user/admin_area/user_cohorts.md @@ -0,0 +1,36 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Cohorts **(FREE)** + +As a benefit of having the [usage ping active](settings/usage_statistics.md), +you can analyze your users' GitLab activities over time. + +To see user cohorts, go to **Admin Area > Overview > Users**. + +## Overview + +How do you interpret the user cohorts table? Let's review an example with the +following user cohorts: + + + +For the cohort of March 2020, three users were added to this server and have +been active since this month. One month later (April 2020), two users are still +active. Five months later (August 2020), one user from this cohort is still +active, or 33% of the original cohort of three that joined in March. + +The **Inactive users** column shows the number of users who were added during +the month, but who never had any activity in the instance. + +How do we measure the activity of users? GitLab considers a user active if: + +- The user signs in. +- The user has Git activity (whether push or pull). +- The user visits pages related to dashboards, projects, issues, or merge + requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54947) in GitLab 11.8). +- The user uses the API. +- The user uses the GraphQL API. diff --git a/doc/user/analytics/img/mr_mean_time_to_merge_metric_v13_9.png b/doc/user/analytics/img/mr_mean_time_to_merge_metric_v13_9.png Binary files differnew file mode 100644 index 00000000000..ad108dabf73 --- /dev/null +++ b/doc/user/analytics/img/mr_mean_time_to_merge_metric_v13_9.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index f5da373ee6d..fe35d575373 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -61,6 +61,6 @@ The following analytics features are available at the project level: - [Insights](../project/insights/index.md). **(ULTIMATE)** - [Issue](../group/issues_analytics/index.md). **(PREMIUM)** - [Merge Request](merge_request_analytics.md), enabled with the `project_merge_request_analytics` - [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development). **(PREMIUM)** + [feature flag](../../development/feature_flags/index.md#enabling-a-feature-flag-locally-in-development). **(PREMIUM)** - [Repository](repository_analytics.md). **(FREE)** - [Value Stream](value_stream_analytics.md). **(FREE)** diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 3edbe3e8aa4..909eb7e585f 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -39,6 +39,15 @@ Merge Request Analytics could be used when: The following visualizations and data are available, representing all merge requests that were merged in the given date range. +### Mean time to merge + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229389) in GitLab 13.9. + +The mean time to merge (MTTM) metric shows the average time between when a merge request is created, +and when it is merged. To view how the MTTM changes over time, compare MTTM across different date ranges. + + + ### Throughput chart The throughput chart shows the number of merge requests merged per month. diff --git a/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_collection_edit_variable.png b/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_collection_edit_variable.png Binary files differnew file mode 100644 index 00000000000..3a2799ecdc1 --- /dev/null +++ b/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_collection_edit_variable.png diff --git a/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_environment_edit_variable.png b/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_environment_edit_variable.png Binary files differnew file mode 100644 index 00000000000..656ba7652cd --- /dev/null +++ b/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_environment_edit_variable.png diff --git a/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_request_edit.png b/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_request_edit.png Binary files differnew file mode 100644 index 00000000000..3750af8f455 --- /dev/null +++ b/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_request_edit.png diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 49311ccc7cd..f2b43e0abd9 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -25,7 +25,7 @@ you can run fuzz tests as part your CI/CD workflow. - GraphQL - Form bodies, JSON, or XML - One of the following assets to provide APIs to test: - - OpenAPI v2 API definition + - OpenAPI v2 or v3 API definition - HTTP Archive (HAR) of API requests to test - Postman Collection v2.0 or v2.1 @@ -54,7 +54,7 @@ changes, other pipelines, or other scanners) during a scan could cause inaccurat There are three ways to perform scans. See the configuration section for the one you wish to use: -- [OpenAPI v2 specification](#openapi-specification) +- [OpenAPI v2 or v3 specification](#openapi-specification) - [HTTP Archive (HAR)](#http-archive-har) - [Postman Collection v2.0 or v2.1](#postman-collection) @@ -64,13 +64,29 @@ Examples of both configurations can be found here: - [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/har) - [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/postman-api-fuzzing-example) +WARNING: +GitLab 14.0 will require that you place API fuzzing configuration files (for example, +`gitlab-api-fuzzing-config.yml`) in your repository's `.gitlab` directory instead of your +repository's root. You can continue using your existing configuration files as they are, but +starting in GitLab 14.0, GitLab will not check your repository's root for configuration files. + ### OpenAPI Specification +> Support for OpenAPI Specification v3 was +> [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228652) in GitLab 13.9. + The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. This section shows you how to configure API fuzzing by using an OpenAPI specification to provide information about the target API to test. OpenAPI specifications are provided as a file system resource or URL. +API fuzzing uses an OpenAPI document to generate the request body. When a request body is required, +the body generation is limited to these body types: + +- `application/x-www-form-urlencoded` +- `multipart/form-data` +- `application/json` + Follow these steps to configure API fuzzing in GitLab with an OpenAPI specification: 1. To use API fuzzing, you must [include](../../../ci/yaml/README.md#includetemplate) @@ -100,7 +116,7 @@ Follow these steps to configure API fuzzing in GitLab with an OpenAPI specificat FUZZAPI_PROFILE: Quick-10 ``` -1. Provide the location of the OpenAPI v2 specification. You can provide the specification as a file +1. Provide the location of the OpenAPI specification. You can provide the specification as a file or URL. Specify the location by adding the `FUZZAPI_OPENAPI` variable: ```yaml @@ -327,6 +343,60 @@ WARNING: the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run fuzzing against a test server. +#### Postman variables + +Postman allows the developer to define placeholders that can be used in different parts of the +requests. These placeholders are called variables, as explained in [Using variables](https://learning.postman.com/docs/sending-requests/variables/). +You can use variables to store and reuse values in your requests and scripts. For example, you can +edit the collection to add variables to the document: + + + +You can then use the variables in sections such as URL, headers, and others: + + + +Variables can be defined at different [scopes](https://learning.postman.com/docs/sending-requests/variables/#variable-scopes) +(for example, Global, Collection, Environment, Local, and Data). In this example, they're defined at +the Environment scope: + + + +When you export a Postman collection, only Postman collection variables are exported into the +Postman file. For example, Postman does not export environment-scoped variables into the Postman +file. + +By default, the API fuzzer uses the Postman file to resolve Postman variable values. If a JSON file +is set in a GitLab CI environment variable `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`, then the JSON +file takes precedence to get Postman variable values. + +Although Postman can export environment variables into a JSON file, the format is not compatible +with the JSON expected by `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`. + +Here is an example of using `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`: + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_POSTMAN_COLLECTION_VARIABLES: variable-collection-dictionary.json +``` + +The file `variable-collection-dictionary.json` is a JSON document. This JSON is an object with +key-value pairs for properties. The keys are the variables' names, and the values are the variables' +values. For example: + + ```json + { + "base_url": "http://127.0.0.1/", + "token": "Token 84816165151" + } + ``` + ### Authentication Authentication is handled by providing the authentication token as a header or cookie. You can @@ -502,6 +572,7 @@ repository's root as `.gitlab-api-fuzzing.yml`. |[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | |[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | +|[`FUZZAPI_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract postman variable values. | |[`FUZZAPI_OVERRIDES_FILE`](#overrides) | Path to a JSON file containing overrides. | |[`FUZZAPI_OVERRIDES_ENV`](#overrides) | JSON string containing headers to override. | |[`FUZZAPI_OVERRIDES_CMD`](#overrides) | Overrides command. | @@ -523,11 +594,19 @@ repository's root as `.gitlab-api-fuzzing.yml`. ### Overrides -API Fuzzing provides a method to add or override headers and cookies for all outbound HTTP requests. +API Fuzzing provides a method to add or override specific items in your request, for example: + +- Headers +- Cookies +- Query string +- Form data +- JSON nodes +- XML nodes + You can use this to inject semantic version headers, authentication, and so on. The [authentication section](#authentication) includes examples of using overrides for that purpose. -Overrides use a JSON document to define the headers and cookies: +Overrides use a JSON document, where each type of override is represented by a JSON object: ```json { @@ -538,6 +617,22 @@ Overrides use a JSON document to define the headers and cookies: "cookies": { "cookie1": "value", "cookie2": "value" + }, + "query": { + "query-string1": "value", + "query-string2": "value" + }, + "body-form": { + "form-param1": "value", + "form-param1": "value", + }, + "body-json": { + "json-path1": "value", + "json-path2": "value", + }, + "body-xml" : { + "xpath1": "value", + "xpath2": "value", } } ``` @@ -565,7 +660,94 @@ Example of setting both a header and cookie: } ``` -You can provide this JSON document as a file or CI/CD variable. You may also provide a command +Example usage for setting a `body-form` override: + +```json +{ + "body-form": { + "username": "john.doe" + } +} +``` + +The override engine uses `body-form` when the request body has only form-data content. + +Example usage for setting a `body-json` override: + +```json +{ + "body-json": { + "$.credentials.access-token": "iddqd!42.$" + } +} +``` + +Note that each JSON property name in the object `body-json` is set to a [JSON Path](https://goessner.net/articles/JsonPath/) +expression. The JSON Path expression `$.credentials.access-token` identifies the node to be +overridden with the value `iddqd!42.$`. The override engine uses `body-json` when the request body +has only [JSON](https://www.json.org/json-en.html) content. + +For example, if the body is set to the following JSON: + +```json +{ + "credentials" : { + "username" :"john.doe", + "access-token" : "non-valid-password" + } +} +``` + +It is changed to: + +```json +{ + "credentials" : { + "username" :"john.doe", + "access-token" : "iddqd!42.$" + } +} +``` + +Here's an example for setting a `body-xml` override. The first entry overrides an XML attribute and +the second entry overrides an XML element: + +```json +{ + "body-xml" : { + "/credentials/@isEnabled": "true", + "/credentials/access-token/text()" : "iddqd!42.$" + } +} +``` + +Note that each JSON property name in the object `body-xml` is set to an +[XPath v2](https://www.w3.org/TR/xpath20/) +expression. The XPath expression `/credentials/@isEnabled` identifies the attribute node to override +with the value `true`. The XPath expression `/credentials/access-token/text()` identifies the +element node to override with the value `iddqd!42.$`. The override engine uses `body-xml` when the +request body has only [XML](https://www.w3.org/XML/) +content. + +For example, if the body is set to the following XML: + +```xml +<credentials isEnabled="false"> + <username>john.doe</username> + <access-token>non-valid-password</access-token> +</credentials> +``` + +It is changed to: + +```xml +<credentials isEnabled="true"> + <username>john.doe</username> + <access-token>iddqd!42.$</access-token> +</credentials> +``` + +You can provide this JSON document as a file or environment variable. You may also provide a command to generate the JSON document. The command can run at intervals to support values that expire. #### Using a file @@ -762,7 +944,7 @@ pipelines. For more information, see the [Security Dashboard documentation](../s Fuzzing faults show up as vulnerabilities with a severity of Unknown. Once a fault is found, you can interact with it. Read more on how to -[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +[address the vulnerabilities](../index.md#addressing-vulnerabilities). ## Handling False Positives diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index fe21fdc1f15..4f00f228da8 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -5,14 +5,22 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Security Configuration **(ULTIMATE)** +# Security Configuration **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. -> - SAST configuration was [enabled](https://gitlab.com/groups/gitlab-org/-/epics/3659) in 13.3 and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in 13.4. -> - DAST Profiles feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40474) in 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. **(ULTIMATE)** +> - SAST configuration was [enabled](https://gitlab.com/groups/gitlab-org/-/epics/3659) in 13.3 and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in 13.4. **(ULTIMATE)** +> - DAST Profiles feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40474) in 13.4. **(ULTIMATE)** +> - A simplified version was made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/294076) in GitLab 13.9. **(FREE)** +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [enable it](#enable-or-disable-security-configuration). **(FREE SELF)** +> - It can be enabled or disabled for a single project. + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. -The Security Configuration page displays the configuration state of each security control in the -current project. +The Security Configuration page displays what security scans are available, links to documentation and also simple enablement tools for the current project. To view a project's security configuration, go to the project's home page, then in the left sidebar go to **Security & Compliance > Configuration**. @@ -20,10 +28,11 @@ then in the left sidebar go to **Security & Compliance > Configuration**. For each security control the page displays: - **Security Control:** Name, description, and a documentation link. -- **Status:** The security control's status (enabled, not enabled, or available). - **Manage:** A management option or a documentation link. -## Status +## Status **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. The status of each security control is determined by the project's latest default branch [CI pipeline](../../../ci/pipelines/index.md). @@ -35,7 +44,7 @@ all security features are configured by default. For SAST, click **View history** to see the `.gitlab-ci.yml` file's history. -## Manage +## Manage **(ULTIMATE)** You can configure the following security controls: @@ -45,3 +54,25 @@ You can configure the following security controls: - Click either **Enable** or **Configure** to use SAST for the current project. For more details, see [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). - DAST Profiles - Click **Manage** to manage the available DAST profiles used for on-demand scans. For more details, see [DAST on-demand scans](../dast/index.md#on-demand-scans). + +### Enable or disable Security Configuration **(FREE SELF)** + +Security Configuration is under development but ready for production use. +It is deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to enable it. + +NOTE: +This does not apply to GitLab Ultimate. + +To enable it: + +```ruby +Feature.enable(:secure_security_and_compliance_configuration_page_on_ce) +``` + +To disable it: + +```ruby +Feature.disable(:secure_security_and_compliance_configuration_page_on_ce) +``` diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 6eec1418ef0..909065d7907 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -32,7 +32,7 @@ To integrate security scanners other than Clair and Klar into GitLab, see You can enable container scanning by doing one of the following: - [Include the CI job](#configuration) in your existing `.gitlab-ci.yml` file. -- Implicitly use [Auto Container Scanning](../../../topics/autodevops/stages.md#auto-container-scanning) +- Implicitly use [Auto Container Scanning](../../../topics/autodevops/stages.md#auto-container-scanning), provided by [Auto DevOps](../../../topics/autodevops/index.md). GitLab compares the found vulnerabilities between the source and target branches, and shows the @@ -455,7 +455,7 @@ For more information about the vulnerabilities database update, check the ## Interacting with the vulnerabilities -After a vulnerability is found, you can [interact with it](../index.md#interacting-with-the-vulnerabilities). +After a vulnerability is found, you can [address it](../index.md#addressing-vulnerabilities). ## Solutions for vulnerabilities (auto-remediation) @@ -469,7 +469,7 @@ file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/README.m your `.gitlab-ci.yml` file by following the instructions described in this document's [overriding the container scanning template](#overriding-the-container-scanning-template) section. -Read more about the [solutions for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities). +Read more about the [solutions for vulnerabilities](../index.md#apply-an-automatic-remediation-for-a-vulnerability). ## Troubleshooting diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 9e42b3e403a..94a7d5268b7 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -237,7 +237,7 @@ The `covfuzz-ci.yml` is the same as that in the [original synchronous example](h ## Interacting with the vulnerabilities -After a vulnerability is found, you can [interact with it](../index.md#interacting-with-the-vulnerabilities). +After a vulnerability is found, you can [address it](../index.md#addressing-vulnerabilities). The merge request widget lists the vulnerability and contains a button for downloading the fuzzing artifacts. By clicking one of the detected vulnerabilities, you can see its details. diff --git a/doc/user/application_security/dast/img/dast_single_v13_0.png b/doc/user/application_security/dast/img/dast_single_v13_0.png Binary files differdeleted file mode 100644 index 1d528fa0ace..00000000000 --- a/doc/user/application_security/dast/img/dast_single_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 3950c856b40..209dd7ad251 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -9,98 +9,82 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4348) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -Running [static checks](../sast/index.md) on your code is the first step to detect -vulnerabilities that can put the security of your code at risk. Yet, once -deployed, your application is exposed to a new category of possible attacks, -such as cross-site scripting or broken authentication flaws. This is where -Dynamic Application Security Testing (DAST) comes into place. +Your application may be exposed to a new category of attacks once deployed into a new environment. For +example, application server misconfigurations or incorrect assumptions about security controls may +not be visible from source code alone. Dynamic Application Security Testing (DAST) checks an +application for these types of vulnerabilities in a deployed environment. GitLab DAST uses the +popular open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) to analyze your running +web application. NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your organization. -## Overview - -If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web applications -for known vulnerabilities using Dynamic Application Security Testing (DAST). -You can take advantage of DAST by either [including the CI job](#configuration) in -your existing `.gitlab-ci.yml` file or by implicitly using -[Auto DAST](../../../topics/autodevops/stages.md#auto-dast), -provided by [Auto DevOps](../../../topics/autodevops/index.md). - -GitLab checks the DAST report, compares the found vulnerabilities between the source and target -branches, and shows the information on the merge request. +In GitLab, DAST is commonly initiated by a merge request and runs as a job in the CI/CD pipeline. +You can also run a DAST scan on demand, outside the CI/CD pipeline. Your running web application is +analyzed for known vulnerabilities. GitLab checks the DAST report, compares the vulnerabilities +found between the source and target branches, and shows any relevant findings on the merge request. Note that this comparison logic uses only the latest pipeline executed for the target branch's base commit. Running the pipeline on any other commit has no effect on the merge request. - + -By clicking on one of the detected linked vulnerabilities, you can -see the details and the URL(s) affected. +## Enable DAST - +### Prerequisites -[Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_Application_Security_Testing) -uses the popular open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) -to perform an analysis on your running web application. +- GitLab Runner with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). -By default, DAST executes [ZAP Baseline Scan](https://www.zaproxy.org/docs/docker/baseline-scan/) -and performs passive scanning only. It doesn't actively attack your application. -However, DAST can be [configured](#full-scan) -to also perform an *active scan*: attack your application and produce a more extensive security report. -It can be very useful combined with [Review Apps](../../../ci/review_apps/index.md). +To enable DAST, either: -Note that a pipeline may consist of multiple jobs, including SAST and DAST scanning. If any job -fails to finish for any reason, the security dashboard doesn't show DAST scanner output. For -example, if the DAST job finishes but the SAST job fails, the security dashboard doesn't show DAST -results. On failure, the analyzer outputs an -[exit code](../../../development/integrations/secure.md#exit-code). +- Enable [Auto DAST](../../../topics/autodevops/stages.md#auto-dast), provided by + [Auto DevOps](../../../topics/autodevops/index.md). +- [Include the DAST template](#dast-cicd-template) in your existing `.gitlab-ci.yml` file. -## Use cases +### DAST CI/CD template -It helps you automatically find security vulnerabilities in your running web -applications while you're developing and testing your applications. +The DAST job is defined in a CI/CD template file you reference in your CI/CD configuration file. The +template is included with GitLab. Updates to the template are provided with GitLab upgrades. You +benefit from any improvements and additions. -## Requirements +The following templates are available: -To run a DAST job, you need GitLab Runner with the -[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). +- [`DAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml): + Stable version of the DAST CI/CD template. +- [`DAST.latest.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST.latest.gitlab-ci.yml): + Latest version of the DAST template. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254325) + in GitLab 13.8). Please note that the latest version may include breaking changes. Check the + [DAST troubleshooting guide](#troubleshooting) if you experience problems. -## Configuration +Use the stable template unless you need a feature provided only in the latest template. -For GitLab 11.9 and later, to enable DAST, you must -[include](../../../ci/yaml/README.md#includetemplate) the -[`DAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml) -that's provided as a part of your GitLab installation. For GitLab versions earlier -than 11.9, you can copy and use the job as defined in that template. +See the CI/CD [documentation](../../../development/cicd/templates.md#latest-version) +on template versioning for more information. -Add the following to your `.gitlab-ci.yml` file: +#### Include the DAST template -```yaml -include: - - template: DAST.gitlab-ci.yml +The method of including the DAST template depends on the GitLab version: -variables: - DAST_WEBSITE: https://example.com -``` +- In GitLab 11.9 and later, [include](../../../ci/yaml/README.md#includetemplate) the + `DAST.gitlab-ci.yml` template. -### Latest template + Add the following to your `.gitlab-ci.yml` file: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254325) in GitLab 13.8 + ```yaml + include: + - template: DAST.gitlab-ci.yml -To use the latest version of the DAST template, include -`DAST.latest.gitlab-ci.yml` instead of `DAST.gitlab-ci.yml`. -See the CI/CD [documentation](../../../development/cicd/templates.md#latest-version) -on template versioning for more information. + variables: + DAST_WEBSITE: https://example.com + ``` -Please note that the latest version may include breaking changes. Check the -[DAST troubleshooting guide](#troubleshooting) if you experience problems. +- In GitLab 11.8 and earlier, copy the template's content into your `.gitlab_ci.yml` file. -### Template options +#### Template options -There are two ways to define the URL to be scanned by DAST: +Running a DAST scan requires a URL. There are two ways to define the URL to be scanned by DAST: 1. Set the `DAST_WEBSITE` [CI/CD variable](../../../ci/yaml/README.md#variables). @@ -125,7 +109,7 @@ There are two ways to define the URL to be scanned by DAST: If both values are set, the `DAST_WEBSITE` value takes precedence. The included template creates a `dast` job in your CI/CD pipeline and scans -your project's source code for possible vulnerabilities. +your project's running application for possible vulnerabilities. The results are saved as a [DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast) @@ -143,9 +127,93 @@ image. Using the `DAST_VERSION` variable, you can choose how DAST updates: Find the latest DAST versions on the [Releases](https://gitlab.com/gitlab-org/security-products/dast/-/releases) page. -### When DAST scans run +## Deployment options + +Depending on the complexity of the target application, there are a few options as to how to deploy and configure +the DAST template. A set of example applications with their configurations have been made available in our +[DAST demonstrations](https://gitlab.com/gitlab-org/security-products/demos/dast/) project. + +### Review Apps + +Review Apps are the most involved method of deploying your DAST target application. To assist in the process, +we created a Review App deployment using Google Kubernetes Engine (GKE). This example can be found in our +[Review Apps - GKE](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke) project along with detailed +instructions in the [README.md](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke/-/blob/master/README.md) +on how to configure Review Apps for DAST. + +### Docker Services + +If your application utilizes Docker containers you have another option for deploying and scanning with DAST. +After your Docker build job completes and your image is added to your container registry, you can utilize the image as a +[service](../../../ci/docker/using_docker_images.md#what-is-a-service). + +By using service definitions in your `gitlab-ci.yml`, you can scan services with the DAST analyzer. + +```yaml +stages: + - build + - dast + +include: + - template: DAST.gitlab-ci.yml + +# Deploys the container to the GitLab container registry +deploy: + services: + - name: docker:dind + alias: dind + image: docker:19.03.5 + stage: build + script: + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker pull $CI_REGISTRY_IMAGE:latest || true + - docker build --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest . + - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + - docker push $CI_REGISTRY_IMAGE:latest + +services: # use services to link your app container to the dast job + - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + alias: yourapp + +variables: + DAST_FULL_SCAN_ENABLED: "true" # do a full scan + DAST_ZAP_USE_AJAX_SPIDER: "true" # use the ajax spider +``` + +Most applications depend on multiple services such as databases or caching services. By default, services defined in the services fields cannot communicate +with each another. To allow communication between services, enable the `FF_NETWORK_PER_BUILD` [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags). + +```yaml +variables: + FF_NETWORK_PER_BUILD: "true" # enable network per build so all services can communicate on the same network + +services: # use services to link the container to the dast job + - name: mongo:latest + alias: mongo + - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + alias: yourapp +``` + +### DAST application analysis + +DAST can analyze applications in two ways: + +- Passive scan only (DAST default). DAST executes + [ZAP's Baseline Scan](https://www.zaproxy.org/docs/docker/baseline-scan/) and doesn't + actively attack your application. +- Passive and active scan. DAST can be [configured](#full-scan) to also perform an active scan + to attack your application and produce a more extensive security report. It can be very + useful when combined with [Review Apps](../../../ci/review_apps/index.md). + +Note that a pipeline may consist of multiple jobs, including SAST and DAST scanning. If any job +fails to finish for any reason, the security dashboard doesn't show DAST scanner output. For +example, if the DAST job finishes but the SAST job fails, the security dashboard doesn't show DAST +results. On failure, the analyzer outputs an +[exit code](../../../development/integrations/secure.md#exit-code). + +#### DAST job order -When using `DAST.gitlab-ci.yml` template, the `dast` job is run last as shown in +When using the `DAST.gitlab-ci.yml` template, the `dast` job is run last as shown in the example below. To ensure DAST is scanning the latest code, your CI pipeline should deploy changes to the web server in one of the jobs preceding the `dast` job. @@ -247,6 +315,9 @@ tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/20 #### Domain validation +WARNING: +In GitLab 13.8, domain validation, outside of the new on-demand scan site profile validation, was deprecated. In GitLab 14.0, domain validation in CI/CD jobs will be permanently removed. + The DAST job can be run anywhere, which means you can accidentally hit live web servers and potentially damage them. You could even take down your production environment. For that reason, you should use domain validation. @@ -472,7 +543,7 @@ URLs to scan can be specified by either of the following methods: To define the URLs to scan in a file, create a plain text file with one path per line. -```txt +```plaintext page1.html /page2.html category/shoes/page1.html @@ -676,7 +747,7 @@ successfully run. For more information, see [Offline environments](../offline_de To use DAST in an offline environment, you need: -- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). +- GitLab Runner with the [`docker` or `kubernetes` executor](#prerequisites). - Docker Container Registry with a locally available copy of the DAST [container image](https://gitlab.com/gitlab-org/security-products/dast), found in the [DAST container registry](https://gitlab.com/gitlab-org/security-products/dast/container_registry). @@ -831,7 +902,7 @@ To delete an on-demand scan: 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Delete**. 1. Select **Delete** to confirm the deletion. -## Site profile +### Site profile A site profile describes the attributes of a web site to scan on demand with DAST. A site profile is required for an on-demand DAST scan. @@ -841,7 +912,7 @@ A site profile contains the following: - **Profile name**: A name you assign to the site to be scanned. - **Target URL**: The URL that DAST runs against. -### Site profile validation +#### Site profile validation > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. @@ -858,7 +929,7 @@ follows: Both methods are equivalent in functionality. Use whichever is feasible. -### Create a site profile +#### Create a site profile To create a site profile: @@ -869,7 +940,7 @@ To create a site profile: The site profile is created. -### Edit a site profile +#### Edit a site profile To edit an existing site profile: @@ -881,7 +952,7 @@ To edit an existing site profile: The site profile is updated with the edited details. -### Delete a site profile +#### Delete a site profile To delete an existing site profile: @@ -893,7 +964,7 @@ To delete an existing site profile: The site profile is deleted. -### Validate a site profile +#### Validate a site profile Prerequisites: @@ -921,7 +992,7 @@ The site is validated and an active scan can run against it. If a validated site profile's target URL is edited, the site's validation status is revoked. -### Revoke a site profile's validation status +#### Revoke a site profile's validation status Note that all site profiles with the same URL have their validation status revoked. @@ -977,7 +1048,7 @@ app.get('/dast-website-target', function(req, res) { }) ``` -## Scanner profile +### Scanner profile > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222767) in GitLab 13.4. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/225804) in GitLab 13.5: scan mode, AJAX spider, debug messages. @@ -992,7 +1063,7 @@ A scanner profile defines the scanner settings used to run an on-demand scan: - **AJAX spider:** Run the AJAX spider, in addition to the traditional spider, to crawl the target site. - **Debug messages:** Include debug messages in the DAST console output. -### Create a scanner profile +#### Create a scanner profile To create a scanner profile: @@ -1002,7 +1073,7 @@ To create a scanner profile: 1. Complete the form. For details of each field, see [Scanner profile](#scanner-profile). 1. Click **Save profile**. -### Edit a scanner profile +#### Edit a scanner profile To edit a scanner profile: @@ -1015,7 +1086,7 @@ To edit a scanner profile: The scanner profile is updated with the edited details. -### Delete a scanner profile +#### Delete a scanner profile To delete a scanner profile: @@ -1099,7 +1170,7 @@ variables: ## Interacting with the vulnerabilities Once a vulnerability is found, you can interact with it. Read more on how to -[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +[address the vulnerabilities](../index.md#addressing-vulnerabilities). ## Vulnerabilities database update diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 11d27140e42..f87ea8edc7b 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -19,10 +19,13 @@ vulnerable. You can then take action to protect your application. If you're using [GitLab CI/CD](../../../ci/README.md), you can use dependency scanning to analyze your dependencies for known vulnerabilities. GitLab scans all dependencies, including transitive dependencies (also known as nested dependencies). You can take advantage of dependency scanning by -either [including the dependency scanning template](#configuration) -in your existing `.gitlab-ci.yml` file, or by implicitly using -the [auto dependency scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning) -provided by [Auto DevOps](../../../topics/autodevops/index.md). +either: + +- [Including the dependency scanning template](#configuration) + in your existing `.gitlab-ci.yml` file. +- Implicitly using + the [auto dependency scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning) + provided by [Auto DevOps](../../../topics/autodevops/index.md). GitLab checks the dependency scanning report, compares the found vulnerabilities between the source and target branches, and shows the information on the @@ -59,16 +62,16 @@ The following languages and dependency managers are supported: | Package Managers | Languages | Supported files | Scan tools | | ------------------- | --------- | --------------- | ------------ | -| [Bundler](https://bundler.io/) | Ruby | `Gemfile.lock`, `gems.locked` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) | -| [Composer](https://getcomposer.org/) | PHP | `composer.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [Conan](https://conan.io/) | C, C++ | [`conan.lock`](https://docs.conan.io/en/latest/versioning/lockfiles.html) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [Golang](https://golang.org/) | Go | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | Java | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [Bundler](https://bundler.io/) | Ruby | `Gemfile.lock`, `gems.locked` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) | +| [Composer](https://getcomposer.org/) | PHP | `composer.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | +| [Conan](https://conan.io/) | C, C++ | [`conan.lock`](https://docs.conan.io/en/latest/versioning/lockfiles.html) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | +| [Golang](https://golang.org/) | Go | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | +| [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | Java | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | +| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | | [npm](https://www.npmjs.com/) (7 and earlier), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package.json` | [Retire.js](https://retirejs.github.io/retire.js/) | -| [NuGet](https://www.nuget.org/) 4.9+ | .NET, C# | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [`setuptools`](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) (*1*) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile`, `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [sbt](https://www.scala-sbt.org/) (*2*) | Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [NuGet](https://www.nuget.org/) 4.9+ | .NET, C# | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | +| [`setuptools`](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) (*1*) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile`, `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | +| [sbt](https://www.scala-sbt.org/) (*2*) | Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | 1. [Pipenv](https://pipenv.pypa.io/en/latest/) projects are scanned when a `Pipfile` is present. 1. Support for [sbt](https://www.scala-sbt.org/) 1.3 and above was added in GitLab 13.9. @@ -77,7 +80,7 @@ Plans are underway for supporting the following languages, dependency managers, | Package Managers | Languages | Supported files | Scan tools | Issue | | ------------------- | --------- | --------------- | ---------- | ----- | -| [Poetry](https://python-poetry.org/) | Python | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/-/issues/7006) | +| [Poetry](https://python-poetry.org/) | Python | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/-/issues/7006) | ## Contribute your scanner @@ -223,13 +226,13 @@ Read more on [how to use private Maven repositories](../index.md#using-private-m ## Interacting with the vulnerabilities Once a vulnerability is found, you can interact with it. Read more on how to -[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +[address the vulnerabilities](../index.md#addressing-vulnerabilities). ## Solutions for vulnerabilities (auto-remediation) Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. Read more about the -[solutions for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities). +[solutions for vulnerabilities](../index.md#apply-an-automatic-remediation-for-a-vulnerability). ## Security Dashboard @@ -507,7 +510,7 @@ ensure that it can reach your private repository. Here is an example configurati ### Referencing local dependencies using a path in JavaScript projects The [Retire.js](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js) analyzer -doesn't support dependency references made with [local paths](https://docs.npmjs.com/cli/v6/configuring-npm/package-json#local-paths) +doesn't support dependency references made with [local paths](https://docs.npmjs.com/cli/v6/configuring-npm/package-json/#local-paths) in the `package.json` of JavaScript projects. The dependency scan outputs the following error for such references: diff --git a/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png b/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png Binary files differindex a914c2996f7..54ccfa24374 100644 --- a/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png +++ b/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png diff --git a/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png b/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png Binary files differdeleted file mode 100644 index a3034a7db04..00000000000 --- a/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/img/vulnerability_related_issues_add_button_v13_2.png b/doc/user/application_security/img/vulnerability_related_issues_add_button_v13_2.png Binary files differdeleted file mode 100644 index 10d9effb811..00000000000 --- a/doc/user/application_security/img/vulnerability_related_issues_add_button_v13_2.png +++ /dev/null diff --git a/doc/user/application_security/img/vulnerability_related_issues_remove_v13_2.gif b/doc/user/application_security/img/vulnerability_related_issues_remove_v13_2.gif Binary files differdeleted file mode 100644 index 22acba5fe1e..00000000000 --- a/doc/user/application_security/img/vulnerability_related_issues_remove_v13_2.gif +++ /dev/null diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 4a23cd874be..b0457ec0690 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -5,17 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# GitLab Secure **(ULTIMATE)** +# Application security **(ULTIMATE)** GitLab can check your application for security vulnerabilities that may lead to unauthorized access, data leaks, denial of services, and more. GitLab reports vulnerabilities in the merge request so you -can fix them before merging. The [Security Dashboard](security_dashboard/index.md) provides a -high-level view of vulnerabilities detected in your projects, pipeline, and groups. The [Threat Monitoring](threat_monitoring/index.md) -page provides runtime security metrics for application environments. With the information provided, -you can immediately begin risk analysis and remediation. +can fix them before you merge. + +- The [Security Dashboard](security_dashboard/index.md) provides a + high-level view of vulnerabilities detected in your projects, pipeline, and groups. +- The [Threat Monitoring](threat_monitoring/index.md) page provides runtime security metrics + for application environments. With the information provided, + you can immediately begin risk analysis and remediation. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview of application security with GitLab, see +For an overview of GitLab application security, see [Security Deep Dive](https://www.youtube.com/watch?v=k4vEJnGYy84). ## Quick start @@ -123,7 +126,7 @@ latest versions of the scanning tools without having to do anything. There are s with this approach, however, and there is a [plan to resolve them](https://gitlab.com/gitlab-org/gitlab/-/issues/9725). -## Viewing security scan information in merge requests **(FREE)** +## View security scan information in merge requests **(FREE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Free 13.5. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/273205) in 13.6. @@ -136,25 +139,7 @@ reports are available to download. To download a report, click on the  -## Interacting with the vulnerabilities - -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.8. - -Each security vulnerability in the merge request report or the -[Vulnerability Report](vulnerability_report/index.md) is actionable. Click an entry to view detailed -information with several options: - -- [Dismiss vulnerability](#dismissing-a-vulnerability): Dismissing a vulnerability styles it in - strikethrough. -- [Create issue](vulnerabilities/index.md#create-a-gitlab-issue-for-a-vulnerability): Create a new issue with the title and - description pre-populated with information from the vulnerability report. By default, such issues - are [confidential](../project/issues/confidential_issues.md). -- [Automatic Remediation](#automatic-remediation-for-vulnerabilities): For some vulnerabilities, - a solution is provided for how to fix the vulnerability. - - - -### View details of a DAST vulnerability +## View details of a DAST vulnerability > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. @@ -165,11 +150,10 @@ investigate and rectify the underlying cause. To view details of DAST vulnerabilities: 1. To see all vulnerabilities detected: - - In a project, go to the project's **{shield}** **Security & Compliance** page. - Only in a merge request, go the merge request's **Security** tab. -1. Click on the vulnerability's description. The following details are provided: +1. Select the vulnerability's description. The following details are provided: | Field | Description | |:-----------------|:------------------------------------------------------------------ | @@ -187,14 +171,14 @@ To view details of DAST vulnerabilities: | Links | Links to further details of the detected vulnerability. | | Solution | Details of a recommended solution to the vulnerability (optional). | -#### Hide sensitive information in headers +### Hide sensitive information in headers HTTP request and response headers may contain sensitive information, including cookies and authorization credentials. By default, content of specific headers are masked in DAST vulnerability reports. You can specify the list of all headers to be masked. For details, see [Hide sensitive information](dast/index.md#hide-sensitive-information). -### View details of an API Fuzzing vulnerability +## View details of an API Fuzzing vulnerability > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. @@ -231,65 +215,79 @@ Follow these steps to view details of a fuzzing fault: | Severity | Severity of the finding is always Unknown. | | Scanner Type | Scanner used to perform testing. | -### Dismissing a vulnerability +## Addressing vulnerabilities -To dismiss a vulnerability, you must set its status to Dismissed. This dismisses the vulnerability -for the entire project. Follow these steps to do so: +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.8. -1. Select the vulnerability in the Security Dashboard. -1. Select **Dismissed** from the **Status** selector menu at the top-right. +For each security vulnerability in a merge request or [Vulnerability Report](vulnerability_report/index.md), +you can: + +- [Dismiss the vulnerability](#dismiss-a-vulnerability). +- Create a [confidential](../project/issues/confidential_issues.md) + [issue](vulnerabilities/index.md#create-a-gitlab-issue-for-a-vulnerability). +- Apply an [automatically remediation](#apply-an-automatic-remediation-for-a-vulnerability). -You can undo this action by selecting a different status from the same menu. +### Dismiss a vulnerability -#### Adding a dismissal reason +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0, a dismissal reason. -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +You can dismiss a vulnerability for the entire project. -When dismissing a vulnerability, it's often helpful to provide a reason for doing so. Upon setting a -vulnerability's status to Dismissed, a text box appears for you to add a comment with your -dismissal. Once added, you can edit or delete it. This allows you to add and update context for a -vulnerability as you learn more over time. +1. Select the vulnerability in the Security Dashboard. +1. In the top-right, from the **Status** selector menu, select **Dismissed**. +1. Optional. Add a reason for the dismissal and select **Save comment**. - +To undo this action, select a different status from the same menu. -#### Dismissing multiple vulnerabilities +#### Dismiss multiple vulnerabilities > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. -You can dismiss multiple vulnerabilities at once, providing an optional reason. -Selecting the checkboxes on the side of each vulnerability in the list selects that individual vulnerability. -Alternatively, you can select all the vulnerabilities in the list by selecting the checkbox in the table header. -Deselecting the checkbox in the header deselects all the vulnerabilities in the list. -After you have selected some vulnerabilities, a menu appears at the top of the table that allows you to select a dismissal reason. -Pressing the "Dismiss Selected" button dismisses all the selected vulnerabilities at once, with the reason you chose. +You can dismiss multiple vulnerabilities at once. - +1. In the list of vulnerabilities, select the checkbox for each vulnerability you want to dismiss. + To select all, select the checkbox in the table header. +1. Above the table, select a dismissal reason. +1. Select **Dismiss Selected**. ### Create an issue for a vulnerability -You can create a GitLab issue, or a Jira issue (if it's enabled) for a vulnerability. For more -details, see [Vulnerability Pages](vulnerabilities/index.md). +You can create a GitLab or Jira issue for a vulnerability. For details, see [Vulnerability Pages](vulnerabilities/index.md). + +#### Link to an existing issue + +If you already have an open issue, you can link to it from the vulnerability. + +- The vulnerability page shows related issues, but the issue page doesn't show the vulnerability it's related to. +- An issue can only be related to one vulnerability at a time. +- Issues can be linked across groups and projects. + +To link to an existing issue: + +1. Open the vulnerability. +1. In the **Related Issues** section, select the plus (**{plus}**) icon. +1. In the text box that appears, type an issue number or paste an issue link. + - Type `#` followed by a number to show an autocomplete menu. + - You can enter multiple issues at once. Press the space bar after each issue number or link to converts them to tags. +1. Select **Add**. -### Automatic remediation for vulnerabilities +To remove an issue, to the right of the issue number, select **{close}**. + + + +### Apply an automatic remediation for a vulnerability > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. -Although the feature name is Automatic Remediation, this feature is also commonly called -Auto-Remediation, Auto Remediation, or Suggested Solutions. The following scanners are supported: +The following scanners are supported: -- [Dependency Scanning](dependency_scanning/index.md): +- [Dependency Scanning](dependency_scanning/index.md). Automatic Patch creation is only available for Node.js projects managed with `yarn`. -- [Container Scanning](container_scanning/index.md) - -When an automatic solution is available, the button in the header shows **Resolve with merge request**: +- [Container Scanning](container_scanning/index.md). - - -Selecting the button creates a merge request with the solution. - -#### Manually applying the suggested patch +#### Manually apply the suggested patch To manually apply the patch that GitLab generated for a vulnerability: @@ -301,49 +299,22 @@ To manually apply the patch that GitLab generated for a vulnerability: 1. Run `git apply remediation.patch`. 1. Verify and commit the changes to your branch. -#### Creating a merge request from a vulnerability +#### Create a merge request with the suggested patch > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. -In certain cases, GitLab allows you to create a merge request that automatically remediates the +In some cases, you can create a merge request that automatically remediates the vulnerability. Any vulnerability that has a -[solution](#automatic-remediation-for-vulnerabilities) can have a merge +[solution](#apply-an-automatic-remediation-for-a-vulnerability) can have a merge request created to automatically solve the issue. -If this action is available, the vulnerability page or modal contains a **Create merge request** button. -Click this button to create a merge request to apply the solution onto the source branch. - - - -### Managing related issues for a vulnerability - -Issues can be linked to a vulnerability using the related issues block on the vulnerability page. -The relationship is uni-directional. The vulnerability page shows related issues, but the issue page -doesn't show the vulnerability it's related to. An issue can only be related to one vulnerability at -a time. Issues can be linked across groups and projects. - -#### Adding a related issue - -You can link an issue by clicking the **{plus}** button in the **Related Issues** block. - - - -A text box appears that lets you type an issue number or paste an issue link. You can enter multiple -issues at once. Pressing the space bar after each issue number or link converts them to tags that -you can remove by clicking the **{close}** icon to the tag's right. Typing `#` followed by a number -shows an autocomplete menu. Click an issue in the menu to add it as a tag. When you're finished -entering issues, click the **Add** button to link the issues to the vulnerability. Alternatively, -click **Cancel** to exit without linking any issues. - - - -### Removing a related issue +If this action is available: -Click the **{close}** icon to right of an issue to remove it as a related issue. Note that this only -removes it as a related issue of the vulnerability; it doesn't modify or remove the issue itself. -You can link it to the vulnerability again if desired. +1. Select the **Resolve with merge request** dropdown, then select **Resolve with merge request**. + +  - +A merge request is created. It that applies the solution to the source branch. ## Security approvals in merge requests diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 9d16fb75410..7c013a2a9de 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -59,14 +59,14 @@ mirroring the packages inside your own offline network. ### Interacting with the vulnerabilities Once a vulnerability is found, you can interact with it. Read more on how to -[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +[address the vulnerabilities](../index.md#addressing-vulnerabilities). Please note that in some cases the reported vulnerabilities provide metadata that can contain external links exposed in the UI. These links might not be accessible within an offline environment. ### Automatic remediation for vulnerabilities -The [automatic remediation for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities) feature is available for offline Dependency Scanning and Container Scanning, but may not work +The [automatic remediation for vulnerabilities](../index.md#apply-an-automatic-remediation-for-a-vulnerability) feature is available for offline Dependency Scanning and Container Scanning, but may not work depending on your instance's configuration. We can only suggest solutions, which are generally more current versions that have been patched, when we are able to access up-to-date registry services hosting the latest versions of that dependency or image. diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 880edebfeda..091dc2f5d36 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -83,8 +83,9 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | Objective-C (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8 | | Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | -| Python | [semgrep](https://semgrep.dev) | 13.9 | +| Python | [Semgrep](https://semgrep.dev) | 13.9 | | React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | +| Ruby | [brakeman](https://brakemanscanner.org) | 13.9 | | Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | | Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | | Swift (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | @@ -130,16 +131,16 @@ All open source (OSS) analyzers have been moved to the GitLab Free tier as of Gi Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Free | In Ultimate | -|:-----------------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | -| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | -| [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](#security-dashboard) | **{dotted-circle}** | **{check-circle}** | -| [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | -| [Customize SAST Rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | +| Capability | In Free | In Ultimate | +|:-------------------------------------------------------------------------------------------------------------|:--------------------|:-------------------| +| [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | +| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | +| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | +| [Address vulnerabilities](../../application_security/index.md#addressing-vulnerabilities) | **{dotted-circle}** | **{check-circle}** | +| [Access to Security Dashboard](../../application_security/security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | +| [Customize SAST Rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -149,7 +150,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) To configure SAST for a project you can: -- Use [Auto SAST](../../../topics/autodevops/stages.md#auto-sast) provided by +- Use [Auto SAST](../../../topics/autodevops/stages.md#auto-sast), provided by [Auto DevOps](../../../topics/autodevops/index.md). - [Configure SAST manually](#configure-sast-manually). - [Configure SAST using the UI](#configure-sast-in-the-ui) (introduced in GitLab 13.3). @@ -610,31 +611,6 @@ Here's an example SAST report: } ``` -## Secret detection - -Learn more about [Secret Detection](../secret_detection). - -## Security Dashboard **(ULTIMATE)** - -The Security Dashboard is a good place to get an overview of all the security -vulnerabilities in your groups, projects and pipelines. Read more about the -[Security Dashboard](../security_dashboard/index.md). - -## Interacting with the vulnerabilities **(ULTIMATE)** - -Once a vulnerability is found, you can interact with it. Read more on how to -[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). - -## Vulnerabilities database - -Vulnerabilities contained in the vulnerability database can be searched -and viewed at the [GitLab vulnerability advisory database](https://advisories.gitlab.com). - -### Vulnerabilities database update - -For more information about the vulnerabilities database update, check the -[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). - ## Running SAST in an offline environment For self-managed GitLab instances in an environment with limited, restricted, or intermittent access diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 98177e804f3..d2a576e9e03 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -5,7 +5,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Secret Detection +# Secret Detection **(FREE)** > - [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) in 13.3. @@ -102,8 +102,7 @@ as shown in the following table: Secret Detection is performed by a [specific analyzer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Secret-Detection.gitlab-ci.yml) during the `secret-detection` job. It runs regardless of your app's programming language. -The Secret Detection analyzer includes [Gitleaks](https://github.com/zricethezav/gitleaks) and -[TruffleHog](https://github.com/dxa4481/truffleHog) checks. +The Secret Detection analyzer includes [Gitleaks](https://github.com/zricethezav/gitleaks) checks. Note that the Secret Detection analyzer ignores Password-in-URL vulnerabilities if the password begins with a dollar sign (`$`), as this likely indicates the password is an environment variable. @@ -112,7 +111,7 @@ For example, `https://username:$password@example.com/path/to/repo` isn't detecte NOTE: You don't have to configure Secret Detection manually as shown in this section if you're using -[Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection) +[Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection), provided by [Auto DevOps](../../../topics/autodevops/index.md). To enable Secret Detection for GitLab 13.1 and later, you must include the @@ -200,7 +199,7 @@ Secret Detection can be customized by defining available CI/CD variables: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. You can customize the default secret detection rules provided with GitLab. -Customization allows you to exclude rules and add new rules. +Customization allows replace the default secret detection rules with rules that you define. To create a custom ruleset: @@ -258,7 +257,7 @@ want to perform a full secret scan. Running a secret scan on the full history ca especially for larger repositories with lengthy Git histories. We recommend not setting this CI/CD variable as part of your normal job definition. -A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](../sast/#vulnerability-filters)) +A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](#available-variables)) can be set to change the behavior of the GitLab Secret Detection scan to run on the entire Git history of a repository. We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showcasing how you can perform a full history secret scan. diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_10.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_10.png Binary files differnew file mode 100644 index 00000000000..72b24a3fd28 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_10.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index b08c19bee47..a708f72b6fc 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -35,9 +35,7 @@ The security dashboard and vulnerability report displays information about vulne - [Static Application Security Testing](../sast/index.md) - And [others](../index.md#security-scanning-tools)! -## Requirements - -To use the security dashboards and vulnerability reports: +## Prerequisites 1. At least one project inside a group must be configured with at least one of the [supported reports](#supported-reports). @@ -52,7 +50,7 @@ To use the security dashboards and vulnerability reports: At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline ran against. - + Visit the page for any pipeline that ran any of the [supported reports](#supported-reports). To view the pipeline's security findings, select the **Security** tab when viewing the pipeline. @@ -63,13 +61,21 @@ job finishes but the DAST job fails, the security dashboard doesn't show SAST re the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code). +### Scan details + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. + +The **Scan details** section lists the scans run in the pipeline and the total number of +vulnerabilities per scan. For the DAST scan, select **Download scanned resources** to download a +CSV file containing details of the resources scanned. + ## Project Security Dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. At the project level, the Security Dashboard displays a chart with the number of vulnerabilities over time. Access it by navigating to **Security & Compliance > Security Dashboard**. We display historical -data up to 365 days. +data up to 365 days. The chart's data is updated daily.  @@ -175,7 +181,7 @@ lock files. Python projects can have lock files, but GitLab Secure tools don't s ## Security scans using Auto DevOps When using [Auto DevOps](../../../topics/autodevops/index.md), use -[special environment variables](../../../topics/autodevops/customize.md#environment-variables) +[special environment variables](../../../topics/autodevops/customize.md#cicd-variables) to configure daily security scans. <!-- ## Troubleshooting @@ -190,4 +196,4 @@ Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> -Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +Read more on how to [address the vulnerabilities](../index.md#addressing-vulnerabilities). diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 13bde2ed38b..747d31df356 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -186,7 +186,7 @@ There are two ways to create policy alerts: Once added, the UI updates and displays a warning about the dangers of too many alerts. -#### Enable or disable Policy Alerts **(FREE SELF)** +#### Enable or disable Policy Alerts **(ULTIMATE)** Policy Alerts is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. @@ -223,4 +223,6 @@ checkbox **Hide dismissed alerts**.  +Clicking an alert's name takes the user to the [alert details page](../../../operations/incident_management/alerts.md#alert-details-page). + For information on work in progress for the alerts dashboard, see [this epic](https://gitlab.com/groups/gitlab-org/-/epics/5041). diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 50f05b687f7..416db5b07fc 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -19,8 +19,7 @@ Each security vulnerability in a project's [Vulnerability Report](../vulnerabili On the vulnerability's page, you can: - [Change the vulnerability's status](#change-vulnerability-status). -- [Create a GitLab issue](#create-a-gitlab-issue-for-a-vulnerability). -- [Create a Jira issue](#create-a-jira-issue-for-a-vulnerability). +- [Create an issue](#create-an-issue-for-a-vulnerability). - [Link issues to the vulnerability](#link-gitlab-issues-to-the-vulnerability). - [Automatically remediate the vulnerability](#automatically-remediate-the-vulnerability), if an automatic solution is available. @@ -40,7 +39,21 @@ the following values: A timeline shows you when the vulnerability status has changed and allows you to comment on a change. -## Create a GitLab issue for a vulnerability +## Create an issue for a vulnerability + +From a vulnerability's page you can create an issue to track all action taken to resolve or +mitigate it. + +From a vulnerability you can create either: + +- [A GitLab issue](#create-a-gitlab-issue-for-a-vulnerability) (default). +- [A Jira issue](#create-a-jira-issue-for-a-vulnerability). + +Creating a Jira issue requires that +[Jira integration](../../project/integrations/jira_integrations.md) is enabled on the project. Note +that when Jira integration is enabled, the GitLab issue feature is not available. + +### Create a GitLab issue for a vulnerability To create a GitLab issue for a vulnerability: @@ -50,7 +63,7 @@ To create a GitLab issue for a vulnerability: An issue is created in the project, prepopulated with information from the vulnerability report. The issue is then opened so you can take further action. -## Create a Jira issue for a vulnerability +### Create a Jira issue for a vulnerability > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4677) in GitLab 13.9. > - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. @@ -64,16 +77,18 @@ This feature might not be available to you. Check the **version history** note a Prerequisites: -- [Enable Jira integration for vulnerabilities](../../project/integrations/jira.md). Select - **Enable Jira issues creation from vulnerabilities** when configuring the integration. +- [Enable Jira integration](../../project/integrations/jira.md). + The **Enable Jira issues creation from vulnerabilities** option must be selected as part of the configuration. +- Each user must have a personal Jira user account with permission to create issues in the target project. To create a Jira issue for a vulnerability: 1. Go to the vulnerability's page. 1. Select **Create Jira issue**. +1. If you're not already logged in to Jira, log in. -An issue is created in the linked Jira project, with the **Summary** and **Description** fields -pre-populated. The Jira issue is then opened in a new browser tab. +The Jira issue is created and opened in a new browser tab. The **Summary** and **Description** +fields are pre-populated from the vulnerability's details. ### Enable or disable Jira integration for vulnerabilities **(ULTIMATE SELF)** @@ -108,4 +123,4 @@ Linked issues are shown in the Vulnerability Report and the vulnerability's page ## Automatically remediate the vulnerability You can fix some vulnerabilities by applying the solution that GitLab automatically -generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#automatic-remediation-for-vulnerabilities). +generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#apply-an-automatic-remediation-for-a-vulnerability). diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_9.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_9.png Binary files differdeleted file mode 100644 index ef96cf31fa4..00000000000 --- a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_9.png +++ /dev/null diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_9.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_9.png Binary files differnew file mode 100644 index 00000000000..f9f60810f20 --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_9.png diff --git a/doc/user/application_security/vulnerability_report/img/vulnerability_details_create_issue_v13_7.png b/doc/user/application_security/vulnerability_report/img/vulnerability_details_create_issue_v13_7.png Binary files differdeleted file mode 100644 index 5184ad85fa9..00000000000 --- a/doc/user/application_security/vulnerability_report/img/vulnerability_details_create_issue_v13_7.png +++ /dev/null diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 28083e09f1c..33d92f5e461 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -5,51 +5,107 @@ group: Threat Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Vulnerability Reports **(ULTIMATE)** +# Vulnerability Report **(ULTIMATE)** -Each vulnerability report contains vulnerabilities from the scans of the most recent branch merged into the default branch. +The Vulnerability Report provides information about vulnerabilities from scans of the branch most +recently merged into the default branch. It is available at the instance, group, and project level. -The vulnerability reports display the total number of vulnerabilities by severity (for example, -Critical, High, Medium, Low, Info, Unknown). Below this, a table shows each vulnerability's detected date, status, severity, description, identifier, the scanner where it was detected, and activity (including related issues or available solutions). By default, the vulnerability report is filtered to display all detected and confirmed vulnerabilities. +The Vulnerability Report contains: + +- Totals of vulnerabilities per severity level. +- Filters for common vulnerability attributes. +- Details of each vulnerability, presented in tabular layout. + +The project-level Vulnerability Report also contains: + +- A time stamp showing when it was updated, including a link to the latest pipeline. +- The number of failures that occurred in the most recent pipeline. Select the failure + notification to view the **Failed jobs** tab of the pipeline's page.  -You can filter which vulnerabilities display by: +From the Vulnerability Report you can: + +- [Filter the list of vulnerabilities](#filter-the-list-of-vulnerabilities). +- [View more details about a vulnerability](#view-details-of-a-vulnerability). +- [View an issue raised for a vulnerability](#view-issues-raised-for-a-vulnerability). +- [Change the status of vulnerabilities](#change-status-of-vulnerabilities). +- [Export details of vulnerabilities](#export-vulnerability-details). + +## Vulnerability filters + +You can filter the vulnerabilities table by: + +| Filter | Available options | +|:---------|:------------------| +| Status | Detected, Confirmed, Dismissed, Resolved. | +| Severity | Critical, High, Medium, Low, Info, Unknown. | +| Scanner | [Available scanners](../index.md#security-scanning-tools). | +| Project | For more details, see [Project filter](#project-filter). | +| Activity | For more details, see [Activity filter](#activity-filter). | + +### Filter the list of vulnerabilities + +To filter the list of vulnerabilities: + +1. Select a filter. +1. Select values from the dropdown. +1. Repeat the above steps for each desired filter. + +The vulnerability table is applied immediately. The vulnerability severity totals are also updated. + +The filters' criteria are combined to show only vulnerabilities matching all criteria. +An exception to this behavior is the Activity filter. For more details about how it works, see +[Activity filter](#activity-filter). + +### Project filter + +The content of the Project filter depends on the current level: + +| Level | Content of the Project filter | +|:---------------|:------------------------------| +| Instance level | Only projects you've [added to the instance-level Security Center](../security_dashboard/index.md#adding-projects-to-the-security-center). | +| Group level | All projects in the group. | +| Project level | Not applicable. | -| Filter | Available Options | -| --- | --- | -| Status | Detected, Confirmed, Dismissed, Resolved | -| Severity | Critical, High, Medium, Low, Info, Unknown | -| Scanner | [Available Scanners](../index.md#security-scanning-tools) | -| Project | Projects configured in the Security Center settings, or all projects in the group for the group level report. This filter is not displayed on the project level vulnerability report | -| Activity | Vulnerabilities with issues and vulnerabilities that are no longer detected in the default branch | +### Activity filter -The Activity filter behaves differently from the other Vulnerability Report filters. The other filter options all OR together to show results from any vulnerability matching one of the filter criteria. With the Activity filter, the selected values form mutually exclusive sets to allow for precisely locating the desired vulnerability records. Additionally, not all options can be selected in combination. Selection behavior when using the Activity filter: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259255) in GitLab 13.9 -| Activity Selection | Results Displayed | -| --- | --- | -| All | Vulnerabilities with any Activity status (same as ignoring this filter). Selecting this will deselect any other Activity filter options. | -| No activity | Only vulnerabilities without either an associated Issue or that are no longer detected. Selecting this will deselect any other Activity filter options. | -| With issues | Only vulnerabilities with one or more associated issues. Does not include vulnerabilities that also are no longer detected. | -| No longer detected | Only vulnerabilities that are no longer detected in the latest pipeline scan of the `default` branch. Does not include vulnerabilities with one or more associated issues. | +The Activity filter behaves differently from the other filters. The selected values form mutually +exclusive sets to allow for precisely locating the desired vulnerability records. Additionally, not +all options can be selected in combination. + +Selection behavior when using the Activity filter: + +| Activity selection | Results displayed | +|:------------------------------------|:------------------| +| All | Vulnerabilities with any Activity status (same as ignoring this filter). Selecting this will deselect any other Activity filter options. | +| No activity | Only vulnerabilities without either an associated Issue or that are no longer detected. Selecting this will deselect any other Activity filter options. | +| With issues | Only vulnerabilities with one or more associated issues. Does not include vulnerabilities that also are no longer detected. | +| No longer detected | Only vulnerabilities that are no longer detected in the latest pipeline scan of the `default` branch. Does not include vulnerabilities with one or more associated issues. | | With issues and No longer detected | Only vulnerabilities that have one or more associated issues and also are no longer detected in the latest pipeline scan of the `default` branch. | -Clicking any vulnerability in the table takes you to its -[vulnerability details](../vulnerabilities) page to see more information on that vulnerability. +## View details of a vulnerability + +To view more details of a vulnerability, select the vulnerability's **Description**. The +[vulnerability's details](../vulnerabilities) page is opened. + +## View issues raised for a vulnerability The **Activity** column indicates the number of issues that have been created for the vulnerability. Hover over an **Activity** entry and select a link go to that issue.  -Contents of the unfiltered vulnerability report can be exported using our [export feature](#export-vulnerabilities). +## Change status of vulnerabilities -You can also dismiss vulnerabilities in the table: +To change the status of vulnerabilities in the table: -1. Select the checkbox for each vulnerability you want to dismiss. -1. In the menu that appears, select the reason for dismissal and click **Dismiss Selected**. +1. Select the checkbox for each vulnerability you want to update the status of. +1. In the dropdown that appears select the desired status, then select **Change status**. - + ## Project Vulnerability Report @@ -66,30 +122,37 @@ the **Failed jobs** tab of the pipeline page.  -## Export vulnerabilities +## Export vulnerability details -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in the Security Center (previously known as the Instance Security Dashboard) and project-level Vulnerability Report (previously known as the Project Security Dashboard) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213013) to the group-level Vulnerability Report in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. -You can export all your vulnerabilities in CSV (comma separated values) format by clicking the -**{upload}** **Export** button located at top right of the Security Dashboard. When the report is -ready, the CSV report downloads to your local machine. The report contains all vulnerabilities for -the projects defined in the Security Dashboard, as filters don't apply to the export function. - -NOTE: -It may take several minutes for the download to start if your project contains -thousands of vulnerabilities. Don't close the page until the download finishes. +You can export details of the vulnerabilities listed in the Vulnerability Report. The export format +is CSV (comma separated values). Note that all vulnerabilities are included because filters don't +apply to the export. -The fields in the export include: +Fields included are: -- Group Name -- Project Name -- Scanner Type -- Scanner Name +- Group name +- Project name +- Scanner type +- Scanner name - Status - Vulnerability - Details -- Additional Information +- Additional information - Severity - [CVE](https://cve.mitre.org/) (Common Vulnerabilities and Exposures) - [CWE](https://cwe.mitre.org/) (Common Weakness Enumeration) -- Other Identifiers +- Other identifiers + +### Export details in CSV format + +To export details of all vulnerabilities listed in the Vulnerability Report, select **Export**. + +The details are retrieved from the database, then the CSV file is downloaded to your local +computer. + +NOTE: +It may take several minutes for the download to start if your project contains +thousands of vulnerabilities. Don't close the page until the download finishes. diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index 07593c98da9..6d6460ca50f 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -30,7 +30,7 @@ Line comments, which are lines that start with `//`, are skipped: A blank line separates paragraphs. -A paragraph with the `[%hardbreaks]` option will preserve line breaks: +A paragraph with the `[%hardbreaks]` option preserves line breaks: ```plaintext [%hardbreaks] @@ -381,7 +381,7 @@ Supported formats (named colors are not supported): - RGB: `` `RGB[A](R, G, B[, A])` `` - HSL: `` `HSL[A](H, S, L[, A])` `` -Color written inside backticks will be followed by a color "chip": +Color written inside backticks is followed by a color "chip": ```plaintext - `#F00` @@ -399,7 +399,7 @@ Color written inside backticks will be followed by a color "chip": To activate equation and formula support, set the `stem` attribute in the document's header to `latexmath`. -Equations and formulas will be rendered using [KaTeX](https://katex.org/): +Equations and formulas are rendered using [KaTeX](https://katex.org/): ```plaintext :stem: latexmath diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 6f3d1e197f5..9af339b20c6 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -21,6 +21,7 @@ tasks in a secure and cloud-native way. It enables: - Pull-based GitOps deployments by leveraging the [GitOps Engine](https://github.com/argoproj/gitops-engine). - Real-time access to API endpoints in a cluster. +- Alert generation based on [Container network policy](../../application_security/threat_monitoring/index.md#container-network-policy). Many more features are planned. Please review [our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) and [our development documentation](../../../development/agent/index.md). @@ -36,7 +37,7 @@ sequenceDiagram participant D as Developer participant A as Application code repository participant M as Manifest repository - participant K as Kubernetes agent + participant K as Kubernetes Agent participant C as Agent configuration repository K->C: Grab the configuration D->>+A: Pushing code changes @@ -49,19 +50,17 @@ sequenceDiagram There are several components that work in concert for the Agent to accomplish GitOps deployments: -- A properly-configured Kubernetes cluster. +- A properly-configured Kubernetes cluster where the Agent is running. - A configuration repository that contains a `config.yaml` file, which tells the - Agent which repositories to synchronize with. -- A manifest repository that contains a `manifest.yaml`, which is tracked by the - Agent and can be auto-generated. Any changes to `manifest.yaml` are applied to the cluster. + Agent which repositories to synchronize with the cluster. +- A manifest repository that contains manifest files. Any changes to manifest files are applied to the cluster. -These repositories might be the same GitLab project or separate projects. +You can use the same GitLab project or separate projects for configuration and manifest files, as follows: -NOTE: -GitLab recommends you use the same GitLab project for the agent configuration -and manifest repositories. Our backlog contains issues for adding support for +- Single GitLab project (recommended): when you use a single repository to hold both the manifest and the configuration files, these projects can be either private or public, as you prefer. +- Two GitLab projects: when you opt to use two different GitLab projects, one for manifest files, and another for configuration files, the manifests project must be private, while the configuration project can be either private or public. Our backlog contains issues for adding support for [private manifest repositories outside of the configuration project](https://gitlab.com/gitlab-org/gitlab/-/issues/220912) and -[group level agents](https://gitlab.com/gitlab-org/gitlab/-/issues/283885). +[group level agents](https://gitlab.com/gitlab-org/gitlab/-/issues/283885) in the future. For more details, please refer to our [full architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture) in the Agent project. @@ -69,12 +68,12 @@ For more details, please refer to our [full architecture documentation](https:// The setup process involves a few steps to enable GitOps deployments: -1. [Install the Agent server](#install-the-kubernetes-agent-server). +1. [Install the Agent server](#install-the-kubernetes-agent-server) for your GitLab instance. 1. [Define a configuration repository](#define-a-configuration-repository). 1. [Create an Agent record in GitLab](#create-an-agent-record-in-gitlab). 1. [Generate and copy a Secret token used to connect to the Agent](#create-the-kubernetes-secret). 1. [Install the Agent into the cluster](#install-the-agent-into-the-cluster). -1. [Create a `manifest.yaml`](#create-a-manifestyaml). +1. [Create manifest files](#create-manifest-files). ### Upgrades and version compatibility @@ -92,7 +91,13 @@ Upgrade your agent installations together with GitLab upgrades. To decide which The available `agentk` and `kas` versions can be found in [the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). -### Install the Kubernetes Agent Server +### Install the Kubernetes Agent Server **(FREE SELF)** + +[Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.10, +the GitLab Kubernetes Agent Server (KAS) is available on GitLab.com under `wss://kas.gitlab.com`. +If you are a GitLab.com user, skip this step and directly +[set up the configuration repository](#define-a-configuration-repository) +for your agent. The GitLab Kubernetes Agent Server (KAS) can be deployed using [Omnibus GitLab](https://docs.gitlab.com/omnibus/) or the [GitLab @@ -100,9 +105,6 @@ chart](https://gitlab.com/gitlab-org/charts/gitlab). If you don't already have GitLab installed, please refer to our [installation documentation](https://docs.gitlab.com/ee/install/README.html). -NOTE: -GitLab plans to include the KAS on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834). - #### Install with Omnibus When using the [Omnibus GitLab](https://docs.gitlab.com/omnibus/) package: @@ -205,7 +207,13 @@ the Agent in subsequent steps. You can create an Agent record either: } mutation createToken { - clusterAgentTokenCreate(input: { clusterAgentId: <cluster-agent-id-taken-from-the-previous-mutation> }) { + clusterAgentTokenCreate( + input: { + clusterAgentId: "<cluster-agent-id-taken-from-the-previous-mutation>" + description: "<optional-description-of-token>" + name: "<required-name-given-to-token>" + } + ) { secret # This is the value you need to use on the next step token { createdAt @@ -223,7 +231,34 @@ the Agent in subsequent steps. You can create an Agent record either: [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md), or the [GraphQL Explorer](https://gitlab.com/-/graphql-explorer). -### Create the Kubernetes secret +### Install the Agent into the cluster + +Next, install the in-cluster component of the Agent. + +NOTE: +For GitLab.com users, the KAS is available at `wss://kas.gitlab.com`. + +#### One-liner installation + +Replace the value of `agent-token` below with the token received from the previous step. Also, replace `kas-address` with the configured access of the Kubernetes Agent Server: + +```shell +docker run --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:latest generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version latest | kubectl apply -f - +``` + +To find out the various options the above Docker container supports, run: + +```shell +docker run --rm -it registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:latest generate --help +``` + +#### Advanced installation + +For more advanced configurations, we recommend to use [the `kpt` based installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). + +Otherwise, you can follow below for fully manual, detailed installation steps. + +##### Create the Kubernetes secret After generating the token, you must apply it to the Kubernetes cluster. @@ -239,9 +274,7 @@ After generating the token, you must apply it to the Kubernetes cluster. kubectl create secret generic -n <YOUR-DESIRED-NAMESPACE> gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN' ``` -### Install the Agent into the cluster - -Next, install the in-cluster component of the Agent. This example file contains the +The following example file contains the Kubernetes resources required for the Agent to be installed. You can modify this example [`resources.yml` file](#example-resourcesyml-file) in the following ways: @@ -253,7 +286,7 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways after you install the `gitlab-kas` sub-chart, or enable `gitlab-kas` for Omnibus GitLab. When using the sub-chart, you must set `wss://kas.host.tld:443` as `kas-address`, where `host.tld` is the domain you've setup for your GitLab installation. - When using Omnibus GitLab, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent` as + When using Omnibus GitLab, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent/` as `kas-address`, where `GitLab.host.tld` is your GitLab hostname. - When using the sub-chart, specify the `ws` scheme (such as `ws://kas.host.tld:80`) to use an unencrypted WebSockets connection. @@ -288,7 +321,7 @@ NAMESPACE NAME READY STATUS RESTARTS AG gitlab-agent gitlab-agent-77689f7dcb-5skqk 1/1 Running 0 51s ``` -#### Example `resources.yml` file +##### Example `resources.yml` file ```yaml apiVersion: v1 @@ -318,7 +351,7 @@ spec: - --token-file=/config/token - --kas-address - wss://kas.host.tld:443 # change this line for the one below if using Omnibus GitLab - # - wss://gitlab.host.tld:443/-/kubernetes-agent + # - wss://gitlab.host.tld:443/-/kubernetes-agent/ volumeMounts: - name: token-volume mountPath: /config @@ -388,11 +421,10 @@ subjects: namespace: gitlab-agent ``` -### Create a `manifest.yaml` +### Create manifest files In a previous step, you configured a `config.yaml` to point to the GitLab projects -the Agent should synchronize. In each of those projects, you must create a `manifest.yaml` -file for the Agent to monitor. You can auto-generate this `manifest.yaml` with a +the Agent should synchronize. Agent monitors each of those projects for changes to the manifest files it contains. You can auto-generate manifest files with a templating engine or other means. The agent is authorized to download manifests for the configuration @@ -400,13 +432,13 @@ project, and public projects. Support for other private projects is planned in the issue [Agent authorization for private manifest projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). -Each time you commit and push a change to this file, the Agent logs the change: +Each time you push a change to a monitored manifest repository, the Agent logs the change: ```plaintext 2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea ``` -#### Example `manifest.yaml` file +#### Example manifest file This file creates an NGINX deployment. @@ -443,7 +475,52 @@ The following example projects can help you get started with the Kubernetes Agen ### Deploying GitLab Runner with the Agent You can use the Kubernetes Agent to -[deploy GitLab Runner in a Kubernetes cluster](http://docs.gitlab.com/runner/install/kubernetes-agent.html). +[deploy GitLab Runner in a Kubernetes cluster](https://docs.gitlab.com/runner/install/kubernetes-agent.html). + +## Kubernetes Network Security Alerts + +The GitLab Agent also provides an integration with Cilium. This integration provides a simple way to +generate network policy-related alerts and to surface those alerts in GitLab. + +There are several components that work in concert for the Agent to generate the alerts: + +- A working Kubernetes cluster. +- Cilium integration through either of these options: + - Installation through [GitLab Managed Apps](../applications.md#install-cilium-using-gitlab-cicd). + - Enablement of [hubble-relay](https://docs.cilium.io/en/v1.8/concepts/overview/#hubble) on an + existing installation. +- One or more network policies through any of these options: + - Use the [Container Network Policy editor](../../application_security/threat_monitoring/index.md#container-network-policy-editor) to create and manage policies. + - Use an [AutoDevOps](../../application_security/threat_monitoring/index.md#container-network-policy-management) configuration. + - Add the required labels and annotations to existing network policies. +- Use a configuration repository to inform the Agent through a `config.yaml` file, which + repositories can synchronize with. This repository might be the same, or a separate GitLab + project. + +The setup process follows the same steps as [GitOps](#get-started-with-gitops-and-the-gitlab-agent), +with the following differences: + +- When you define a configuration repository, you must do so with [Cilium settings](#define-a-configuration-repository-with-cilium-settings). +- You do not need to create a `manifest.yaml`. + +### Define a configuration repository with Cilium settings + +You need a GitLab repository to contain your Agent configuration. The minimal repository layout +looks like this: + +```plaintext +.gitlab/agents/<agent-name>/config.yaml +``` + +Your `config.yaml` file must specify the `host` and `port` of your Hubble Relay service. If your +Cilium integration was performed through [GitLab Managed Apps](../applications.md#install-cilium-using-gitlab-cicd), +you can use `hubble-relay.gitlab-managed-apps.svc.cluster.local:80`: + +```yaml +cilium: + hubble_relay_address: "<hubble-relay-host>:<hubble-relay-port>" + ... +``` ## Management interfaces @@ -497,15 +574,15 @@ This error is shown if there are some connectivity issues between the address specified as `kas-address`, and your Agent pod. To fix it, make sure that you specified the `kas-address` correctly. -### Agent logs - ValidationError(Deployment.metadata +### Agent logs - ValidationError(Deployment.metadata) ```plaintext {"level":"info","time":"2020-10-30T08:56:54.329Z","msg":"Synced","project_id":"root/kas-manifest001","resource_key":"apps/Deployment/kas-test001/nginx-deployment","sync_result":"error validating data: [ValidationError(Deployment.metadata): unknown field \"replicas\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"selector\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"template\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta]"} ``` -This error is shown if your `manifest.yaml` file is malformed, and Kubernetes can't -create specified objects. Make sure that your `manifest.yaml` file is valid. You -may try using it to create objects in Kubernetes directly for more troubleshooting. +This error is shown if a manifest file is malformed, and Kubernetes can't +create specified objects. Make sure that your manifest files are valid. You +may try using them to create objects in Kubernetes directly for more troubleshooting. ### Agent logs - Error while dialing failed to WebSocket dial: failed to send handshake request @@ -531,3 +608,72 @@ issue is in progress, directly edit the deployment with the This error is shown if the version of the agent is newer that the version of KAS. To fix it, make sure that both `agentk` and KAS use the same versions. + +### Agent logs - Certificate signed by unknown authority + +```plaintext +{"level":"error","time":"2021-02-25T07:22:37.158Z","msg":"Reverse tunnel","mod_name":"reverse_tunnel","error":"Connect(): rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent/\\\": x509: certificate signed by unknown authority\""} +``` + +This error is shown if your GitLab instance is using a certificate signed by an internal CA that +is unknown to the agent. One approach to fixing it is to present the CA certificate file to the agent +via a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it +will be picked up automatically. + +For example, if your internal CA certifciate is `myCA.pem`: + +```plaintext +kubectl -n gitlab-agent create configmap ca-pemstore --from-file=myCA.pem +``` + +Then in `resources.yml`: + +```plaintext + spec: + serviceAccountName: gitlab-agent + containers: + - name: agent + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:latest" + args: + - --token-file=/config/token + - --kas-address + - wss://kas.host.tld:443 # change this line for the one below if using Omnibus GitLab + # - wss://gitlab.host.tld:443/-/kubernetes-agent + volumeMounts: + - name: token-volume + mountPath: /config + - name: ca-pemstore-volume + mountPath: /etc/ssl/certs/myCA.pem + subPath: myCA.pem + volumes: + - name: token-volume + secret: + secretName: gitlab-agent-token + - name: ca-pemstore-volume + configMap: + name: ca-pemstore + items: + - key: myCA.pem + path: myCA.pem +``` + +Alternatively, you can mount the certificate file at a different location and include it using the +`--ca-cert-file` agent parameter: + +```plaintext + containers: + - name: agent + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:latest" + args: + - --ca-cert-file=/tmp/myCA.pem + - --token-file=/config/token + - --kas-address + - wss://kas.host.tld:443 # change this line for the one below if using Omnibus GitLab + # - wss://gitlab.host.tld:443/-/kubernetes-agent + volumeMounts: + - name: token-volume + mountPath: /config + - name: ca-pemstore-volume + mountPath: /tmp/myCA.pem + subPath: myCA.pem +``` diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index ad92cf9b4ed..5c3b276b90c 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -86,10 +86,9 @@ is saved as a [CI job artifact](../../ci/pipelines/job_artifacts.md). #### Usage in GitLab versions earlier than 13.5 -For GitLab versions 13.5 and below, the Ingress, Fluentd, Prometheus, -and Sentry apps are fetched from the central Helm -[stable repository](https://kubernetes-charts.storage.googleapis.com/). This repository -[was deleted](https://github.com/helm/charts#deprecation-timeline) +For GitLab versions 13.5 and earlier, the Ingress, Fluentd, Prometheus, and Sentry +apps were fetched from the central Helm stable repository (`https://kubernetes-charts.storage.googleapis.com/`). +This repository [was deleted](https://github.com/helm/charts#deprecation-timeline) on November 13, 2020. This causes the installation CI/CD pipeline to fail. Upgrade to GitLab 13.6, or alternatively, you can use the following `.gitlab-ci.yml`, which has been tested on GitLab 13.5: @@ -372,7 +371,7 @@ For GitLab Runner to function, you _must_ specify the following: - `runnerRegistrationToken`: The registration token for adding new runners to GitLab. This must be [retrieved from your GitLab instance](../../ci/runners/README.md). -These values can be specified using [CI variables](../../ci/variables/README.md): +These values can be specified using [CI/CD variables](../../ci/variables/README.md): - `GITLAB_RUNNER_GITLAB_URL` is used for `gitlabUrl`. - `GITLAB_RUNNER_REGISTRATION_TOKEN` is used for `runnerRegistrationToken` @@ -730,7 +729,7 @@ Set: - "Redirect URI" to `http://<JupyterHub Host>/hub/oauth_callback`. - "Scope" to `api read_repository write_repository`. -In addition, the following variables must be specified using [CI variables](../../ci/variables/README.md): +In addition, the following variables must be specified using [CI/CD variables](../../ci/variables/README.md): - `JUPYTERHUB_PROXY_SECRET_TOKEN` - Secure string used for signing communications from the hub. Read [`proxy.secretToken`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#proxy-secrettoken). @@ -1469,7 +1468,7 @@ Kubernetes API, giving you access to more advanced querying capabilities. Log data is deleted after 30 days, using [Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/5.5/about.html). The Elastic Stack cluster application is intended as a log aggregation solution -and is not related to our [Advanced Search](../search/advanced_global_search.md) +and is not related to our [Advanced Search](../search/advanced_search.md) functionality, which uses a separate Elasticsearch cluster. To enable log shipping: @@ -1655,3 +1654,17 @@ Error: Could not get apiVersions from Kubernetes: unable to retrieve the complet This is a bug that was introduced in Helm `2.15` and fixed in `3.0.2`. As a workaround, ensure [`cert-manager`](#cert-manager) is installed successfully prior to installing Prometheus. + +### Unable to create a Persistent Volume Claim with DigitalOcean + +Trying to create additional block storage volumes might lead to the following error when using DigitalOcean: + +```plaintext +Server requested +[Warning] pod has unbound immediate PersistentVolumeClaims (repeated 2 times) +[Normal] pod didn't trigger scale-up (it wouldn't fit if a new node is added): +Spawn failed: Timeout +``` + +This is due to DigitalOcean imposing a few limits with regards to creating additional block storage volumes. +[Learn more about DigitalOcean Block Storage Volumes limits.](https://www.digitalocean.com/docs/volumes/#limits) diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 74c608fcc38..6c734a76059 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -14,10 +14,13 @@ project's dependencies for their licenses. You can then decide whether to allow each license. For example, if your application uses an external (open source) library whose license is incompatible with yours, then you can deny the use of that license. -You can take advantage of License Compliance by either [including the job](#configuration) -in your existing `.gitlab-ci.yml` file or by implicitly using -[Auto License Compliance](../../../topics/autodevops/stages.md#auto-license-compliance) -that is provided by [Auto DevOps](../../../topics/autodevops/index.md). +You can take advantage of License Compliance by either: + +- [Including the job](#configuration) + in your existing `.gitlab-ci.yml` file. +- Implicitly using + [Auto License Compliance](../../../topics/autodevops/stages.md#auto-license-compliance), + provided by [Auto DevOps](../../../topics/autodevops/index.md). The [License Finder](https://github.com/pivotal/LicenseFinder) scan tool runs as part of the CI/CD pipeline, and detects the licenses in use. GitLab checks the License Compliance report, compares the @@ -76,7 +79,7 @@ The reported licenses might be incomplete or inaccurate. | Elixir | [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) | | C++/C | [Conan](https://conan.io/) | | Scala | [sbt](https://www.scala-sbt.org/) | -| Rust | [Cargo](https://crates.io/) | +| Rust | [Cargo](https://crates.io) | | PHP | [Composer](https://getcomposer.org/) | ## Requirements diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 9320dbba1b8..0ac79a011ca 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -38,27 +38,26 @@ There is a limit of 5,000 comments for every object, for example: issue, epic, a > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5022) in GitLab 8.11. > - Resolvable threads can be added only to merge request diffs. +> - Resolving comments individually was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/28750) in GitLab 13.6. Thread resolution helps keep track of progress during planning or code review. -Every standard comment or thread in merge requests, commits, commit diffs, and +Every thread in merge requests, commits, commit diffs, and snippets is initially displayed as unresolved. They can then be individually resolved by anyone with at least Developer access to the project or by the author of the change being reviewed. If the thread has been resolved and a non-member un-resolves their own response, -this will also unresolve the discussion thread. -If the non-member then resolves this same response, this will resolve the discussion thread. +this also unresolves the discussion thread. +If the non-member then resolves this same response, this resolves the discussion thread. -The need to resolve all standard comments or threads prevents you from forgetting -to address feedback and lets you hide threads that are no longer relevant. +The need to resolve threads prevents you from forgetting to address feedback and lets you +hide threads that are no longer relevant.  ### Commit threads in the context of a merge request -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/31847) in GitLab 10.3. - For reviewers with commit-based workflow, it may be useful to add threads to -specific commit diffs in the context of a merge request. These threads will +specific commit diffs in the context of a merge request. These threads persist through a commit ID change when: - force-pushing after a rebase @@ -67,27 +66,27 @@ persist through a commit ID change when: To create a commit diff thread: 1. Navigate to the merge request **Commits** tab. A list of commits that - constitute the merge request will be shown. + constitute the merge request are shown.  -1. Navigate to a specific commit, click on the **Changes** tab (where you - will only be presented diffs from the selected commit), and leave a comment. +1. Navigate to a specific commit, select the **Changes** tab (where you + are only be presented diffs from the selected commit), and leave a comment.  -1. Any threads created this way will be shown in the merge request's +1. Any threads created this way are shown in the merge request's **Discussions** tab and are resolvable.  -Threads created this way will only appear in the original merge request +Threads created this way only appear in the original merge request and not when navigating to that commit under your project's **Repository > Commits** page. NOTE: When a link of a commit reference is found in a thread inside a merge -request, it will be automatically converted to a link in the context of the +request, it is automatically converted to a link in the context of the current merge request. ### Marking a comment or thread as resolved @@ -103,8 +102,6 @@ Alternatively, you can mark each comment as resolved individually. ### Move all unresolved threads in a merge request to an issue -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8266) in GitLab 9.1 - To continue all open threads from a merge request in a new issue, click the **Resolve all threads in new issue** button. @@ -112,17 +109,17 @@ To continue all open threads from a merge request in a new issue, click the Alternatively, when your project only accepts merge requests [when all threads are resolved](#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), -there will be an **open an issue to resolve them later** link in the merge +an **open an issue to resolve them later** link displays in the merge request widget.  -This will prepare an issue with its content referring to the merge request and +This prepares an issue with its content referring to the merge request and the unresolved threads.  -Hitting **Submit issue** will cause all threads to be marked as resolved and +Hitting **Submit issue** causes all threads to be marked as resolved and add a note referring to the newly created issue.  @@ -131,24 +128,20 @@ You can now proceed to merge the merge request from the UI. ### Moving a single thread to a new issue -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8266) in GitLab 9.1 - To create a new issue for a single thread, you can use the **Resolve this thread in a new issue** button.  -This will direct you to a new issue prefilled with the content of the +This directs you to a new issue prefilled with the content of the thread, similar to the issues created for delegating multiple -threads at once. Saving the issue will mark the thread as resolved and +threads at once. Saving the issue marks the thread as resolved and add a note to the merge request thread referencing the new issue.  ### Only allow merge requests to be merged if all threads are resolved -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7125) in GitLab 8.14. - You can prevent merge requests from being merged until all threads are resolved. @@ -158,15 +151,13 @@ 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 +From now on, you can't merge from the UI until all threads are resolved.  ### Automatically resolve merge request diff threads when they become outdated -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14053) in GitLab 10.0. - You can automatically resolve merge request diff threads on lines modified with a new push. @@ -176,7 +167,7 @@ merge request diffs threads on lines changed with a push** check box and hit  -From now on, any threads on a diff will be resolved by default if a push +From now on, any threads on a diff are resolved by default if a push makes that diff section outdated. Threads on lines that don't change and top-level resolvable threads are not automatically resolved. @@ -186,33 +177,29 @@ You can add comments and threads to a particular commit under your project's **Repository > Commits**. WARNING: -Threads created this way will be lost if the commit ID changes after a +Threads created this way are lost if the commit ID changes after a force push. ## Threaded discussions -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7527) in GitLab 9.1. - While resolvable threads are only available to merge request diffs, threads can also be added without a diff. You can start a specific -thread which will look like a thread, on issues, commits, snippets, and +thread which looks like a thread, on issues, commits, snippets, and merge requests. -To start a threaded discussion, click on the **Comment** button toggle dropdown, -select **Start thread** and click **Start thread** when you're ready to +To start a threaded discussion, select the **Comment** button toggle dropdown, +select **Start thread**, and then select **Start thread** when you're ready to post the comment.  -This will post a comment with a single thread to allow you to discuss specific +This posts a comment with a single thread to allow you to discuss specific comments in greater detail.  ## Image threads -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14061) in GitLab 10.1. - Sometimes a thread is revolved around an image. With image threads, you can easily target a specific coordinate of an image and start a thread around it. Image threads are available in merge requests and commit detail views. @@ -223,33 +210,31 @@ Simply click anywhere on the image to create a new thread.  -After you click on the image, a comment form will be displayed that would be the start -of your thread. Once you save your comment, you will see a new badge displayed on +After you select the image, a comment form is displayed that would be the start +of your thread. After you save your comment, a new badge is displayed on top of your image. This badge represents your thread. NOTE: This thread badge is typically associated with a number that is only used as a visual reference for each thread. In the merge request thread tab, -this badge will be indicated with a comment icon since each thread will render a new +this badge is indicated with a comment icon, because each thread renders a new image section. Image threads also work on diffs that replace an existing image. In this diff view mode, you can toggle the different view modes and still see the thread point badges. -| 2-up | Swipe | Onion Skin | -| :-----------: | :----------: | :----------: | +| 2-up | Swipe | Onion Skin | +|:-----------:|:----------:|:----------:| |  |  |  | Image threads also work well with resolvable threads. Resolved threads -on diffs (not on the merge request discussion tab) will appear collapsed on page -load and will have a corresponding badge counter to match the counter on the image. +on diffs (not on the merge request discussion tab) appear collapsed on page +load and have a corresponding badge counter to match the counter on the image.  ## Lock discussions -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14531) in GitLab 10.1. - For large projects with many contributors, it may be useful to stop threads in issues or merge requests in these scenarios: @@ -279,7 +264,7 @@ edit existing comments. Non-team members are restricted from adding or editing c | :-----------: | :----------: | |  |  | -Additionally, locked issues and merge requests can not be reopened. +Additionally, locked issues and merge requests can't be reopened. ## Confidential Comments @@ -292,29 +277,29 @@ Additionally, locked issues and merge requests can not be reopened. WARNING: This feature might not be available to you. Check the **version history** note above for details. -When creating a comment, you can decide to make it visible only to the project members (users with Reporter and higher permissions). +When creating a comment, you can make it visible only to the project members (users with Reporter and higher permissions). -To create a confidential comment, select the **Make this comment confidential** checkbox before you submit it. +To create a confidential comment, select the **Make this comment confidential** check box before you submit it.  -## Merge Request Reviews +## Merge request reviews > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Free in 13.1. -When looking at a Merge Request diff, you are able to start a review. -This allows you to create comments inside a Merge Request that are **only visible to you** until published, +When looking at a merge request diff, you are able to start a review. +This allows you to create comments inside a merge request that are **only visible to you** until published, in order to allow you to submit them all as a single action. ### Starting a review -In order to start a review, simply write a comment on a diff as normal under the **Changes** tab -in an MR and click on the **Start a review** button. +To start a review, write a comment on a diff as normal under the **Changes** tab +in a merge request, and then select **Start a review**.  -Once a review is started, you will see any comments that are part of this review marked `Pending`. +After a review is started, any comments that are part of this review are marked `Pending`. All comments that are part of a review show two buttons: - **Finish review**: Submits all comments that are part of the review, making them visible to other users. @@ -322,7 +307,7 @@ All comments that are part of a review show two buttons:  -You can use [quick actions](../project/quick_actions.md) inside review comments. The comment will show the actions that will be performed once published. +You can use [quick actions](../project/quick_actions.md) inside review comments. The comment shows the actions to perform after publication.  @@ -330,19 +315,19 @@ To add more comments to a review, start writing a comment as normal and click th  -This will add the comment to the review. +This adds the comment to the review.  ### Resolving/Unresolving threads Review comments can also resolve/unresolve [resolvable threads](#resolvable-comments-and-threads). -When replying to a comment, you will see a checkbox that you can click in order to resolve or unresolve -the thread once published. +When replying to a comment, a checkbox is displayed that you can click to resolve or unresolve +the thread after publication.  -If a particular pending comment will resolve or unresolve the thread, this will be shown on the pending +If a particular pending comment resolves or unresolves the thread, this is shown on the pending comment itself.  @@ -351,12 +336,12 @@ comment itself. ### Submitting a review -If you have any comments that have not been submitted, you will see a bar at the +If you have any comments that have not been submitted, a bar displays at the bottom of the screen with two buttons: - **Discard**: Discards all comments that have not been submitted. - **Finish review**: Opens a list of comments ready to be submitted for review. - Clicking **Submit review** will publish all comments. Any quick actions + Clicking **Submit review** publishes all comments. Any quick actions submitted are performed at this time. Alternatively, to finish the entire review from a pending comment: @@ -366,14 +351,14 @@ Alternatively, to finish the entire review from a pending comment:  -Submitting the review will send a single email to every notifiable user of the +Submitting the review sends a single email to every notifiable user of the merge request with all the comments associated to it. Replying to this email will, consequentially, create a new comment on the associated merge request. ## Filtering notes -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26723) in GitLab 11.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26723) in GitLab 11.5. For issues with many comments like activity notes and user comments, sometimes finding useful information can be hard. There is a way to filter comments from single notes and threads for merge requests and issues. @@ -387,24 +372,21 @@ From a merge request's **Discussion** tab, or from an epic/issue overview, find  -After you select one of the filters in a given issue or MR, GitLab will save -your preference, so that it will persist when you visit the same page again +After you select one of the filters in a given issue or merge request, GitLab saves +your preference, so that it persists when you visit the same page again from any device you're logged into. ## Suggest Changes > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. -> - Custom commit messages for suggestions was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9. -> - Custom commit messages for suggestions was deployed behind a [feature flag](../feature_flags.md), disabled by default. -> - Custom commit messages for suggestions became enabled by default on GitLab 13.9. -> - Custom commit messages for suggestions is enabled on GitLab.com and is recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disabled it](#enable-or-disable-custom-commit-messages-for-suggestions). **(FREE SELF)** - -As a reviewer, you're able to suggest code changes with a simple -Markdown syntax in Merge Request Diff threads. Then, the -Merge Request author (or other users with appropriate +> - Custom commit messages for suggestions was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9 behind a [feature flag](../feature_flags.md), disabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. + +As a reviewer, you're able to suggest code changes with a +Markdown syntax in merge request diff threads. Then, the +merge request author (or other users with appropriate [permission](../permissions.md)) is able to apply these -Suggestions with a click, which will generate a commit in +Suggestions with a click, which generates a commit in the merge request authored by the user that applied them. 1. Choose a line of code to be changed, add a new comment, then click @@ -425,19 +407,18 @@ the merge request authored by the user that applied them. 1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9, you can opt to add a custom commit message to describe your change. If you don't - specify it, the default commit message will be used. Note that [this feature may not be available to you](#enable-or-disable-custom-commit-messages-for-suggestions). - Also, it is not supported for [batch suggestions](#batch-suggestions). + specify it, the default commit message is used. It is not supported for [batch suggestions](#batch-suggestions).  -After the author applies a Suggestion, it will be marked with the **Applied** label, -the thread will be automatically resolved, and GitLab will create a new commit +After the author applies a Suggestion, it is marked with the **Applied** label, +the thread is automatically resolved, and GitLab creates a new commit and push the suggested change directly into the codebase in the merge request's branch. [Developer permission](../permissions.md) is required to do so. ### Multi-line Suggestions -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. Reviewers can also suggest changes to multiple lines with a single Suggestion within merge request diff threads by adjusting the range offsets. The @@ -469,12 +450,12 @@ instead of the usual three. ### Configure the commit message for applied Suggestions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13086) in GitLab 12.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13086) in GitLab 12.7. GitLab uses a default commit message when applying Suggestions: `Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)` -For example, consider that a user applied 3 suggestions to 2 different files, the default commit message will be: **Apply 3 suggestion(s) to 2 file(s)** +For example, consider that a user applied 3 suggestions to 2 different files, the default commit message is: **Apply 3 suggestion(s) to 2 file(s)** These commit messages can be customized to follow any guidelines you might have. To do so, expand the **Merge requests** tab within your project's **General** settings and change the @@ -484,23 +465,23 @@ tab within your project's **General** settings and change the You can also use following variables besides static text: -| Variable | Description | Output example | -|---|---|---| -| `%{branch_name}` | The name of the branch the Suggestion(s) was(were) applied to. | `my-feature-branch` | -| `%{files_count}` | The number of file(s) to which Suggestion(s) was(were) applied.| **2** | -| `%{file_paths}` | The path(s) of the file(s) Suggestion(s) was(were) applied to. Paths are separated by commas.| `docs/index.md, docs/about.md` | -| `%{project_path}` | The project path. | `my-group/my-project` | -| `%{project_name}` | The human-readable name of the project. | **My Project** | +| Variable | Description | Output example | +|------------------------|-------------|----------------| +| `%{branch_name}` | The name of the branch the Suggestion(s) was(were) applied to. | `my-feature-branch` | +| `%{files_count}` | The number of file(s) to which Suggestion(s) was(were) applied.| **2** | +| `%{file_paths}` | The path(s) of the file(s) Suggestion(s) was(were) applied to. Paths are separated by commas.| `docs/index.md, docs/about.md` | +| `%{project_path}` | The project path. | `my-group/my-project` | +| `%{project_name}` | The human-readable name of the project. | **My Project** | | `%{suggestions_count}` | The number of Suggestions applied.| **3** | -| `%{username}` | The username of the user applying Suggestion(s). | `user_1` | -| `%{user_full_name}` | The full name of the user applying Suggestion(s). | **User 1** | +| `%{username}` | The username of the user applying Suggestion(s). | `user_1` | +| `%{user_full_name}` | The full name of the user applying Suggestion(s). | **User 1** | For example, to customize the commit message to output **Addresses user_1's review**, set the custom text to `Addresses %{username}'s review`. NOTE: -Custom commit messages for each applied Suggestion (and for batch Suggestions) will be +Custom commit messages for each applied Suggestion is introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). ### Batch Suggestions @@ -514,7 +495,7 @@ introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). You can apply multiple suggestions at once to reduce the number of commits added to your branch to address your reviewers' requests. -1. To start a batch of suggestions that will be applied with a single commit, click **Add suggestion to batch**: +1. To start a batch of suggestions to apply with a single commit, click **Add suggestion to batch**:  @@ -532,7 +513,7 @@ to your branch to address your reviewers' requests. ## Start a thread by replying to a standard comment -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30299) in GitLab 11.9 +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30299) in GitLab 11.9 To reply to a standard (non-thread) comment, you can use the **Reply to comment** button. @@ -540,20 +521,20 @@ To reply to a standard (non-thread) comment, you can use the **Reply to comment* The **Reply to comment** button is only displayed if you have permissions to reply to an existing thread, or start a thread from a standard comment. -Clicking on the **Reply to comment** button will bring the reply area into focus and you can type your reply. +Clicking on the **Reply to comment** button brings the reply area into focus and you can type your reply.  -Replying to a non-thread comment will convert the non-thread comment to a +Replying to a non-thread comment converts the non-thread comment to a thread after the reply is submitted. This conversion is considered an edit -to the original comment, so a note about when it was last edited will appear underneath it. +to the original comment, so a note about when it was last edited appears underneath it. -This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff threads are +This feature exists only for issues, merge requests, and epics. Commits, snippets, and merge request diff threads are not supported yet. ## Assign an issue to the commenting user -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191455) in GitLab 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191455) in GitLab 13.1. You can assign an issue to a user who made a comment. @@ -582,25 +563,6 @@ To disable it: Feature.disable(:confidential_notes) ``` -## Enable or disable Custom commit messages for suggestions **(FREE SELF)** - -Custom commit messages for suggestions is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it. - -To disable custom commit messages for suggestions: - -```ruby -Feature.disable(:suggestions_custom_commit) -``` - -To enable custom commit messages for suggestions: - -```ruby -Feature.enable(:suggestions_custom_commit) -``` - ## Enable or disable Batch Suggestions **(FREE SELF)** Batch Suggestions is diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index a59b1f2e9b2..813d2b8e265 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Custom project templates are useful for organizations that need to create many similar types of [projects](../project/index.md) and want to start from the same jumping-off point. -## Setting up Group-level Project Templates +## Setting up group-level project templates To use a custom project template for a new project you need to: @@ -30,7 +30,7 @@ To use a custom project template for a new project you need to: Here is a sample group/project structure for a hypothetical "Acme Co" for project templates: -```txt +```plaintext # GitLab instance and group gitlab.com/acmeco/ # Subgroups diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index c76b07481b2..1cb024ceb01 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -154,7 +154,7 @@ You can also consult the [group permissions table](../../permissions.md#group-me - Comments: collaborate on that epic by posting comments in its thread. These text fields also fully support - [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). + [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). ## Comment or start a thread diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index d4c1a5fc768..3c5e140965a 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -75,6 +75,9 @@ A modal appears to confirm your action. Deleting an epic releases all existing issues from their associated epic in the system. +WARNING: +If you delete an epic, all its child epics and their descendants are deleted as well. If needed, you can [remove child epics](#remove-a-child-epic-from-a-parent-epic) from the parent epic before you delete it. + ## Close an epic Whenever you decide that there is no longer need for that epic, @@ -243,7 +246,7 @@ To move an issue to another epic: If you have the necessary [permissions](../../permissions.md) to close an issue and create an epic in the immediate parent group, you can promote an issue to an epic with the `/promote` -[quick action](../../project/quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). +[quick action](../../project/quick_actions.md#issues-merge-requests-and-epics). Only issues from projects that are in groups can be promoted. When you attempt to promote a confidential issue, a warning is displayed. Promoting a confidential issue to an epic makes all information related to the issue public as epics are public to group members. diff --git a/doc/user/group/img/access_requests_management.png b/doc/user/group/img/access_requests_management.png Binary files differdeleted file mode 100644 index 7de6a1c0a5e..00000000000 --- a/doc/user/group/img/access_requests_management.png +++ /dev/null diff --git a/doc/user/group/img/add_new_members_v13_7.png b/doc/user/group/img/add_new_members_v13_7.png Binary files differdeleted file mode 100644 index 7e06bdf8fd1..00000000000 --- a/doc/user/group/img/add_new_members_v13_7.png +++ /dev/null diff --git a/doc/user/group/img/create_new_group_info.png b/doc/user/group/img/create_new_group_info.png Binary files differdeleted file mode 100644 index bd724240c37..00000000000 --- a/doc/user/group/img/create_new_group_info.png +++ /dev/null diff --git a/doc/user/group/img/create_new_project_from_group_v13_6.png b/doc/user/group/img/create_new_project_from_group_v13_6.png Binary files differdeleted file mode 100644 index 72d19817686..00000000000 --- a/doc/user/group/img/create_new_project_from_group_v13_6.png +++ /dev/null diff --git a/doc/user/group/img/group_activity_analytics_v12_10.png b/doc/user/group/img/group_activity_analytics_v12_10.png Binary files differdeleted file mode 100644 index e49594c155b..00000000000 --- a/doc/user/group/img/group_activity_analytics_v12_10.png +++ /dev/null diff --git a/doc/user/group/img/group_activity_analytics_v13_10.png b/doc/user/group/img/group_activity_analytics_v13_10.png Binary files differnew file mode 100644 index 00000000000..b6e9b04861d --- /dev/null +++ b/doc/user/group/img/group_activity_analytics_v13_10.png diff --git a/doc/user/group/img/group_file_template_dropdown.png b/doc/user/group/img/group_file_template_dropdown.png Binary files differdeleted file mode 100644 index f0586772218..00000000000 --- a/doc/user/group/img/group_file_template_dropdown.png +++ /dev/null diff --git a/doc/user/group/img/group_members_filter_2fa_disabled_13_7.png b/doc/user/group/img/group_members_filter_2fa_disabled_13_7.png Binary files differdeleted file mode 100644 index 8336103bad1..00000000000 --- a/doc/user/group/img/group_members_filter_2fa_disabled_13_7.png +++ /dev/null diff --git a/doc/user/group/img/group_members_filter_2fa_enabled_13_7.png b/doc/user/group/img/group_members_filter_2fa_enabled_13_7.png Binary files differdeleted file mode 100644 index eb27906b583..00000000000 --- a/doc/user/group/img/group_members_filter_2fa_enabled_13_7.png +++ /dev/null diff --git a/doc/user/group/img/group_members_filter_direct_13_7.png b/doc/user/group/img/group_members_filter_direct_13_7.png Binary files differdeleted file mode 100644 index c1b2d996e59..00000000000 --- a/doc/user/group/img/group_members_filter_direct_13_7.png +++ /dev/null diff --git a/doc/user/group/img/group_members_filter_inherited_13_7.png b/doc/user/group/img/group_members_filter_inherited_13_7.png Binary files differdeleted file mode 100644 index f75990f9da8..00000000000 --- a/doc/user/group/img/group_members_filter_inherited_13_7.png +++ /dev/null diff --git a/doc/user/group/img/group_members_search_13_7.png b/doc/user/group/img/group_members_search_13_7.png Binary files differdeleted file mode 100644 index 21f36fc75f8..00000000000 --- a/doc/user/group/img/group_members_search_13_7.png +++ /dev/null diff --git a/doc/user/group/img/group_members_sort_13_7.png b/doc/user/group/img/group_members_sort_13_7.png Binary files differdeleted file mode 100644 index 5d307da649a..00000000000 --- a/doc/user/group/img/group_members_sort_13_7.png +++ /dev/null diff --git a/doc/user/group/img/group_settings.png b/doc/user/group/img/group_settings.png Binary files differdeleted file mode 100644 index f3a75f1bde8..00000000000 --- a/doc/user/group/img/group_settings.png +++ /dev/null diff --git a/doc/user/group/img/groups.png b/doc/user/group/img/groups.png Binary files differdeleted file mode 100644 index 2e27d46b370..00000000000 --- a/doc/user/group/img/groups.png +++ /dev/null diff --git a/doc/user/group/img/ldap_sync_cn_v13_1.png b/doc/user/group/img/ldap_sync_cn_v13_1.png Binary files differdeleted file mode 100644 index 279b3192328..00000000000 --- a/doc/user/group/img/ldap_sync_cn_v13_1.png +++ /dev/null diff --git a/doc/user/group/img/ldap_sync_filter_v13_1.png b/doc/user/group/img/ldap_sync_filter_v13_1.png Binary files differdeleted file mode 100644 index 655bed58d46..00000000000 --- a/doc/user/group/img/ldap_sync_filter_v13_1.png +++ /dev/null diff --git a/doc/user/group/img/manual_permissions_v13_7.png b/doc/user/group/img/manual_permissions_v13_7.png Binary files differdeleted file mode 100644 index fcea0121915..00000000000 --- a/doc/user/group/img/manual_permissions_v13_7.png +++ /dev/null diff --git a/doc/user/group/img/member_lock.png b/doc/user/group/img/member_lock.png Binary files differdeleted file mode 100644 index 3f1382e76c6..00000000000 --- a/doc/user/group/img/member_lock.png +++ /dev/null diff --git a/doc/user/group/img/new_group_from_groups.png b/doc/user/group/img/new_group_from_groups.png Binary files differdeleted file mode 100644 index ffafac1b1cd..00000000000 --- a/doc/user/group/img/new_group_from_groups.png +++ /dev/null diff --git a/doc/user/group/img/new_group_from_other_pages.png b/doc/user/group/img/new_group_from_other_pages.png Binary files differdeleted file mode 100644 index f84501d1ff2..00000000000 --- a/doc/user/group/img/new_group_from_other_pages.png +++ /dev/null diff --git a/doc/user/group/img/request_access_button.png b/doc/user/group/img/request_access_button.png Binary files differdeleted file mode 100644 index 4d73990ec7e..00000000000 --- a/doc/user/group/img/request_access_button.png +++ /dev/null diff --git a/doc/user/group/img/select_group_dropdown.png b/doc/user/group/img/select_group_dropdown.png Binary files differdeleted file mode 100644 index 4948cefb65f..00000000000 --- a/doc/user/group/img/select_group_dropdown.png +++ /dev/null diff --git a/doc/user/group/img/select_group_dropdown_13_10.png b/doc/user/group/img/select_group_dropdown_13_10.png Binary files differnew file mode 100644 index 00000000000..bf0d927b653 --- /dev/null +++ b/doc/user/group/img/select_group_dropdown_13_10.png diff --git a/doc/user/group/img/share_with_group_lock.png b/doc/user/group/img/share_with_group_lock.png Binary files differdeleted file mode 100644 index 77b00d8a248..00000000000 --- a/doc/user/group/img/share_with_group_lock.png +++ /dev/null diff --git a/doc/user/group/img/withdraw_access_request_button.png b/doc/user/group/img/withdraw_access_request_button.png Binary files differdeleted file mode 100644 index a5fe78eb090..00000000000 --- a/doc/user/group/img/withdraw_access_request_button.png +++ /dev/null diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index f4d15dce1cd..302f12273cb 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -20,11 +20,23 @@ Using GitLab Group Migration, you can migrate existing top-level groups from Git The following resources are migrated to the target instance: -- Groups +- Groups ([Introduced in 13.7](https://gitlab.com/groups/gitlab-org/-/epics/4374)) - description - attributes - subgroups -- Epics +- Group Labels ([Introduced in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/292429)) + - title + - description + - color + - created_at ([Introduced in 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/300007)) + - updated_at ([Introduced in 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/300007)) +- Members ([Introduced in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/299415)) + Group members are associated with the imported group if: + - The user already exists in the target GitLab instance and + - The user has a public email in the source GitLab instance that matches a + confirmed email in the target GitLab instance + confirmed email in the target GitLab instance +- Epics ([Introduced in 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/250281)) - title - description - state (open / closed) @@ -32,6 +44,28 @@ The following resources are migrated to the target instance: - due date - epic order on boards - confidentiality + - labels ([Introduced in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/297460)) + - author ([Introduced in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/298745)) + - parent epic ([Introduced in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/297459)) + - emoji award ([Introduced in 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/297466)) + - events ([Introduced in 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/297465)) +- Milestones ([Introduced in 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/292427)) + - title + - description + - state (active / closed) + - start date + - due date + - created at + - updated at +- Iterations ([Introduced in 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/292428)) + - iid + - title + - description + - state (upcoming / started / closed) + - start date + - due date + - created at + - updated at Any other items are **not** migrated. diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 4c63bae7e44..655a0dcb00f 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -5,56 +5,36 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Groups +# Groups **(FREE)** -With GitLab Groups, you can: +In GitLab, you can put related projects together in a group. -- Assemble related projects together. -- Grant members access to several projects at once. +For example, you might create a group for your company members and a subgroup for each individual team. +You can name the group `company-team`, and the subgroups `backend-team`, `frontend-team`, and `production-team`. -For a video introduction to GitLab Groups, see [GitLab University: Repositories, Projects and Groups](https://www.youtube.com/watch?v=4TWfh1aKHHw). +Then you can: -Groups can also be nested in [subgroups](subgroups/index.md). +- Grant members access to multiple projects at once. +- Add to-do items for all of the group members at once. +- View the [issues](../project/issues/index.md#issues-list) and + [merge requests](../project/merge_requests/reviewing_and_managing_merge_requests.md#view-merge-requests-for-all-projects-in-a-group) + for all projects in the group, together in a single list view. +- [Bulk edit](../group/bulk_editing/index.md) issues, epics, and merge requests. -Find your groups by clicking **Groups > Your Groups** in the top navigation. +You can also create [subgroups](subgroups/index.md). - +## View groups -> The **Groups** dropdown in the top navigation was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36234) in [GitLab 11.1](https://about.gitlab.com/releases/2018/07/22/gitlab-11-1-released/#groups-dropdown-in-navigation). +To view groups: -The **Groups** page displays: +1. In the top menu, select **Groups > Your Groups**. All groups you are a member of are displayed. +1. To view a list of public groups, select **Explore public groups**. -- All groups you are a member of, when **Your groups** is selected. -- A list of public groups, when **Explore public groups** is selected. +You can also view groups by namespace. -Each group on the **Groups** page is listed with: +### Namespaces -- How many subgroups it has. -- How many projects it contains. -- How many members the group has, not including members inherited from parent group(s). -- The group's visibility. -- A link to the group's settings, if you have sufficient permissions. -- A link to leave the group, if you are a member. - -## Use cases - -You can create groups for numerous reasons. To name a couple: - -- Grant access to multiple projects and multiple team members in fewer steps by organizing related projects under the same [namespace](#namespaces) and adding members to the top-level group. -- Make it easier to `@mention` all of your team at once in issues and merge requests by creating a group and including the appropriate members. - -For example, you could create a group for your company members, and create a [subgroup](subgroups/index.md) for each individual team. Let's say you create a group called `company-team`, and you create subgroups in this group for the individual teams `backend-team`, `frontend-team`, and `production-team`. - -- When you start a new implementation from an issue, you add a comment: - _"`@company-team`, let's do it! `@company-team/backend-team` you're good to go!"_ -- When your backend team needs help from frontend, they add a comment: - _"`@company-team/frontend-team` could you help us here please?"_ -- When the frontend team completes their implementation, they comment: - _"`@company-team/backend-team`, it's done! Let's ship it `@company-team/production-team`!"_ - -## Namespaces - -In GitLab, a namespace is a unique name to be used as a user name, a group name, or a subgroup name. +In GitLab, a namespace is a unique name and URL for a user, a group, or subgroup. - `http://gitlab.example.com/username` - `http://gitlab.example.com/groupname` @@ -62,154 +42,106 @@ In GitLab, a namespace is a unique name to be used as a user name, a group name, For example, consider a user named Alex: -1. Alex creates an account on GitLab.com with the username `alex`; - their profile will be accessed under `https://gitlab.example.com/alex` -1. Alex creates a group for their team with the group name `alex-team`; - the group and its projects will be accessed under `https://gitlab.example.com/alex-team` -1. Alex creates a subgroup of `alex-team` with the subgroup name `marketing`; - this subgroup and its projects will be accessed under `https://gitlab.example.com/alex-team/marketing` - -By doing so: - -- Any team member mentions Alex with `@alex` -- Alex mentions everyone from their team with `@alex-team` -- Alex mentions only the marketing team with `@alex-team/marketing` - -## Issues and merge requests within a group - -Issues and merge requests are part of projects. For a given group, you can view all of the -[issues](../project/issues/index.md#issues-list) and [merge requests](../project/merge_requests/reviewing_and_managing_merge_requests.md#view-merge-requests-for-all-projects-in-a-group) across all projects in that group, -together in a single list view. - -### Bulk editing issues and merge requests - -For details, see [bulk editing issues and merge requests](../group/bulk_editing/index.md). - -## Create a new group - -> For a list of words that are not allowed to be used as group names see the -> [reserved names](../reserved_names.md). - -To create a new Group, either: - -- In the top menu, click **Groups** and then **Your Groups**, and click the green button **New group**. - -  +1. Alex creates an account with the username `alex`: `https://gitlab.example.com/alex` +1. Alex creates a group for their team with the group name `alex-team`. + The group and its projects are available at: `https://gitlab.example.com/alex-team` +1. Alex creates a subgroup of `alex-team` with the subgroup name `marketing`. + The subgroup and its projects are available at: `https://gitlab.example.com/alex-team/marketing` -- Or, in the top menu, expand the `plus` sign and choose **New group**. +## Create a group -  +To create a group: -Add the following information: - - - -1. The **Group name** will automatically populate the URL. Optionally, you can change it. - This is the name that displays in group views. - The name can contain only: +1. From the top menu, either: + - Select **Groups > Your Groups**, and on the right, select the **New group** button. + - To the left of the search box, select the plus sign and then **New group**. +1. For the **Group name**, use only: - Alphanumeric characters + - Emojis - Underscores - - Dashes and dots - - Spaces -1. The **Group URL** is the namespace under which your projects will be hosted. - The URL can contain only: + - Dashes, dots, spaces, and parentheses (however, it cannot start with any of these characters) + + For a list of words that cannot be used as group names, see [reserved names](../reserved_names.md). + +1. For the **Group URL**, which is used for the [namespace](#namespaces), + use only: - Alphanumeric characters - Underscores - Dashes and dots (it cannot start with dashes or end in a dot) -1. Optionally, you can add a brief description to tell others - what this group is about. -1. Optionally, choose an avatar for your group. 1. Choose the [visibility level](../../public_access/public_access.md). +1. Invite GitLab members or other users to join the group. -For more details on creating groups, watch the video [GitLab Namespaces (users, groups and subgroups)](https://youtu.be/r0sJgjR2f5A). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For details about groups, watch [GitLab Namespaces (users, groups and subgroups)](https://youtu.be/r0sJgjR2f5A). ## Add users to a group -A benefit of putting multiple projects in one group is that you can -give a user access to all projects in the group with one action. - -Add members to a group by navigating to the group's dashboard and clicking **Members**. - - - -Select the [permission level](../permissions.md#permissions), and add the new member. You can also set the expiring date for that user; this is the date on which they will no longer have access to your group. - -Consider a group with two projects: - -- On the **Group Members** page, you can now add a new user to the group. -- Now, because this user is a **Developer** member of the group, they automatically - get **Developer** access to **all projects** within that group. +You can give a user access to all projects in a group. -To increase the access level of an existing user for a specific project, -add them again as a new member to the project with the desired permission level. +1. From the top menu, select **Groups > Your Groups**. +1. Find your group and select it. +1. From the left sidebar, select **Members**. +1. Fill in the fields. + - The role applies to all projects in the group. [Learn more about permissions](../permissions.md#permissions). + - On the **Access expiration date**, the user can no longer access projects in the group. ## Request access to a group -As a group owner, you can enable or disable the ability for non-members to request access to -your group. Go to the group settings, and click **Allow users to request access**. +As a user, you can request to be a member of a group, if an administrator allows it. -As a user, you can request to be a member of a group, if that setting is enabled. Go to the group for which you'd like to be a member, and click the **Request Access** button on the right -side of your screen. +1. From the top menu, select **Groups > Your Groups**. +1. Find the group and select it. +1. Under the group name, select **Request Access**. - +As many as ten of the most-recently-active group owners receive an email with your request. +Any group owner can approve or decline the request. -Once access is requested: +If you change your mind before your request is approved, select +**Withdraw Access Request**. -- Up to ten group owners are notified of your request via email. - Email is sent to the most recently active group owners. -- Any group owner can approve or decline your request on the members page. +## Prevent users from requesting access to a group - +As a group owner, you can prevent non-members from requesting access to +your group. -If you change your mind before your request is approved, just click the -**Withdraw Access Request** button. - - - -## Changing the owner of a group +1. From the top menu, select **Groups > Your Groups**. +1. Find the group and select it. +1. From the left menu, select **Settings > General**. +1. Expand the **Permissions, LFS, 2FA** section. +1. Clear the **Allow users to request access** checkbox. +1. Select **Save changes**. -Ownership of a group means at least one of its members has -[Owner permission](../permissions.md#group-members-permissions). Groups must have at -least one owner. +## Change the owner of a group -Changing the owner of a group with only one owner is possible. To change the sole owner -of a group: +You can change the owner of a group. Each group must always have at least one +member with [Owner permission](../permissions.md#group-members-permissions). - As an administrator: - 1. Go to the group's **{users}** **Members** tab. + 1. Go to the group and from the left menu, select **Members**. 1. Give a different member **Owner** permissions. 1. Refresh the page. You can now remove **Owner** permissions from the original owner. - As the current group's owner: - 1. Go to the group's **{users}** **Members** tab. + 1. Go to the group and from the left menu, select **Members**. 1. Give a different member **Owner** permissions. 1. Have the new owner sign in and remove **Owner** permissions from you. ## Remove a member from the group -Only users with permissions of [Owner](../permissions.md#group-members-permissions) can manage -group members. - -You can remove a member from the group if the given member has a direct membership in the group. If -membership is inherited from a parent group, then the member can be removed only from the parent -group itself. - -When removing a member, you can decide whether to unassign the user from all issues and merge -requests they are currently assigned or leave the assignments as they are. +Prerequisites: -- **Unassigning the removed member** from all issues and merge requests might be helpful when a user - is leaving a private group and you wish to revoke their access to any issues and merge requests - they are assigned. -- **Keeping the issues and merge requests assigned** might be helpful for groups that accept public - contributions where a user doesn't have to be a member to be able to contribute to issues and - merge requests. +- You must have [Owner permissions](../permissions.md#group-members-permissions). +- The member must have direct membership in the group. If + membership is inherited from a parent group, then the member can be removed + from the parent group only. To remove a member from a group: -1. In a group, go to **{users}** **Members**. -1. Click the **Delete** **{remove}** button next to a group member you want to remove. - A **Remove member** modal appears. -1. (Optional) Select the **Also unassign this user from related issues and merge requests** checkbox. -1. Click **Remove member**. +1. Go to the group. +1. From the left menu, select **Members**. +1. Next to the member you want to remove, select **Delete**. +1. Optional. On the **Remove member** confirmation box, select the + **Also unassign this user from related issues and merge requests** checkbox. +1. Select **Remove member**. ## Filter and sort members in a group @@ -217,56 +149,49 @@ To remove a member from a group: > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/228675) in GitLab 13.7. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289911) in GitLab 13.8. -The following sections illustrate how you can filter and sort members in a group. To view these options, -navigate to your desired group, go to **Members**, and include the noted search terms. - -### Membership filter - -By default, inherited and direct members are displayed. The [membership](subgroups/index.md#membership) filter can be used to display only inherited or only direct members. - -#### Only display inherited members - -Include `Membership` `=` `Inherited` in the search text box. +To find members in a group, you can sort, filter, or search. - +### Filter a group -#### Only display direct members +Filter a group to find members. By default, all members in the group and subgroups are displayed. -Include `Membership` `=` `Direct` in the search text box. +1. Go to the group and select **Members**. +1. Above the list of members, in the **Filter members** box, enter filter criteria. + - To view members in the group only, select **Membership = Direct**. + - To view members of the group and its subgroups, select **Membership = Inherited**. + - To view members with two-factor authentication enabled or disabled, select **2FA = Enabled** or **Disabled**. - +### Search a group -### 2FA filter - -[Owner](../permissions.md#group-members-permissions) permissions required. - -By default, members with 2FA enabled and disabled are displayed. The 2FA filter can be used to display only members with 2FA enabled or only members with 2FA disabled. - -#### Only display members with 2FA enabled - -Include `2FA` `=` `Enabled` in the search text box. - - - -#### Only display members with 2FA disabled +You can search for members by name, username, or email. -Include `2FA` `=` `Disabled` in the search text box. +1. Go to the group and select **Members**. +1. Above the list of members, in the **Filter members** box, enter search criteria. +1. To the right of the **Filter members** box, select the magnifying glass (**{search}**). - +### Sort members in a group -### Search +You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in**. -You can search for members by name, username, or email. +1. Go to the group and select **Members**. +1. Above the list of members, on the top right, from the **Account** list, select + the criteria to filter by. +1. To switch the sort between ascending and descending, to the right of the **Account** list, select the + arrow (**{sort-lowest}** or **{sort-highest}**). - +## Mention a group in an issue or merge request -### Sort +When you mention a group in a comment, every member of the group gets a to-do item +added to their To-do list. -You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in** in ascending or descending order. +1. Open the MR or issue. +1. In a comment, type `@` followed by the user, group, or subgroup namespace. + For example, `@alex`, `@alex-team`, or `@alex-team/marketing`. +1. Select **Comment**. - +A to-do item is created for all the group and subgroup members. -## Changing the default branch protection of a group +## Change the default branch protection of a group > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. @@ -289,15 +214,11 @@ In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab adminis There are two different ways to add a new project to a group: - Select a group, and then click **New project**. You can then continue [creating your project](../../user/project/working_with_projects.md#create-a-project). +- While you are creating a project, select a group from the dropdown menu. -  - -- While you are creating a project, select a group namespace - you've already created from the dropdown menu. +  -  - -### Default project-creation level +### Specify who can add projects to a group > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. > - Brought to [GitLab Starter](https://about.gitlab.com/pricing/) in 10.7. @@ -314,154 +235,103 @@ To change this setting for a specific group: To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#default-project-creation-protection). -## View group details - -A group's **Details** page includes tabs for: - -- Subgroups and projects. -- Shared projects. -- Archived projects. - -### Group activity analytics overview +## Group activity analytics **(PREMIUM)** > - [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: **(PREMIUM)** - -- Merge requests. -- Issues. -- Members. - -These Group Activity Analytics can be enabled with the `group_activity_analytics` [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development). - - - -For details, see the section on how you can [View group activity](#view-group-activity). +a [beta feature](https://about.gitlab.com/handbook/product/#beta). -## View group activity +For a group, you can view how many merge requests, issues, and members were created in the last 90 days. -A group's **Activity** page displays the most recent actions taken in a group, including: +These Group Activity Analytics can be enabled with the `group_activity_analytics` [feature flag](../../development/feature_flags/index.md#enabling-a-feature-flag-locally-in-development). -- **Push events**: Recent pushes to branches. -- **Merge events**: Recent merges. -- **Issue events**: Issues opened or closed. -- **Epic events**: Epics opened or closed. -- **Comments**: Comments opened or closed. -- **Team**: Team members who have joined or left the group. -- **Wiki**: Wikis created, deleted, or updated. + -The entire activity feed is also available in Atom format by clicking the -**RSS** icon. +### View group activity -To view a group's **Activity** page: +You can view the most recent actions taken in a group. -1. Go to the group's page. -1. In the left navigation menu, go to **Group Overview** and select **Activity**. +1. From the top menu, select **Groups > Your Groups**. +1. Find the group and select it. +1. From the left menu, select **Group overview > Activity**. -## Transfer projects into groups +To view the activity feed in Atom format, select the +**RSS** (**{rss}**) icon. -Learn how to [transfer a project into a group](../project/settings/index.md#transferring-an-existing-project-into-another-namespace). - -## Sharing a project with a group - -You can [share your projects with a group](../project/members/share_project_with_groups.md) -and give all group members access to the project at once. - -Alternatively, you can [lock the sharing with group feature](#share-with-group-lock). - -## Sharing a group with another group +## Share a group with another group > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18328) in GitLab 12.7. -Similarly to [sharing a project with a group](#sharing-a-project-with-a-group), -you can share a group with another group to give direct group members access +Similar to how you [share a project with a group](../project/members/share_project_with_groups.md), +you can share a group with another group. Members get direct access to the shared group. This is not valid for inherited members. -To share a given group, for example, 'Frontend' with another group, for example, -'Engineering': +To share a given group, for example, `Frontend` with another group, for example, +`Engineering`: -1. Navigate to your 'Frontend' group page and use the left navigation menu to go - to your group **Members**. +1. Go to the `Frontend` group. +1. From the left menu, select **Members**. 1. Select the **Invite group** tab. -1. Add 'Engineering' with the maximum access level of your choice. -1. Click **Invite**. +1. In the **Select a group to invite** list, select `Engineering`. +1. For the **Max access level**, select an access level. +1. Select **Invite**. -All the members of the 'Engineering' group will have been added to 'Frontend'. +All the members of the `Engineering` group are added to the `Frontend` group. ## 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. +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. -Group links can be created using either a CN or a filter. These group links are created on the **Group Settings -> LDAP Synchronization** page. After configuring the link, it may take over an hour for the users to sync with the GitLab group. +Group links can be created by using either a CN or a filter. To create these group links, go to the group's **Settings > LDAP Synchronization** page. After configuring the link, it may take more than an hour for the users to sync with the GitLab group. For more information on the administration of LDAP and group sync, refer to the [main LDAP documentation](../../administration/auth/ldap/index.md#group-sync). 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. +When you add LDAP synchronization, if an LDAP user is a group member and they are not part of the LDAP group, they are removed from the group. -### Creating group links via CN **(PREMIUM SELF)** +### Create group links via CN **(PREMIUM SELF)** To create group links via CN: <!-- vale gitlab.Spelling = NO --> 1. Select the **LDAP Server** for the link. -1. Select `LDAP Group cn` as the **Sync method**. -1. In the **LDAP Group cn** text input box, begin typing the CN of the group. There will be a dropdown menu with matching CNs within the configured `group_base`. Select your CN from this list. +1. As the **Sync method**, select `LDAP Group cn`. +1. In the **LDAP Group cn** field, begin typing the CN of the group. There is a dropdown menu with matching CNs in the configured `group_base`. Select your CN from this list. 1. In the **LDAP Access** section, select the [permission level](../permissions.md) for users synced in this group. -1. Click the `Add Synchronization` button to save this group link. - - +1. Select the **Add Synchronization** button. <!-- vale gitlab.Spelling = YES --> -### Creating group links via filter **(PREMIUM SELF)** +### Create group links via filter **(PREMIUM SELF)** To create group links via filter: 1. Select the **LDAP Server** for the link. -1. Select `LDAP user filter` as the **Sync method**. +1. As the **Sync method**, select `LDAP user filter`. 1. Input your filter in the **LDAP User filter** box. Follow the [documentation on user filters](../../administration/auth/ldap/index.md#set-up-ldap-user-filter). 1. In the **LDAP Access** section, select the [permission level](../permissions.md) for users synced in this group. -1. Click the `Add Synchronization` button to save this group link. +1. Select the **Add Synchronization** button. - +### Override user permissions **(PREMIUM SELF)** -### 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: +LDAP user permissions can be manually overridden by an administrator. To override a user's permissions: 1. Go to your group's **Members** page. -1. Select the pencil icon in the row for the user you are editing. -1. Select the brown `Edit permissions` button in the modal. - - - -Now you will be able to edit the user's permissions from the **Members** page. - -## Epics **(ULTIMATE)** +1. In the row for the user you are editing, select the pencil (**{pencil}**) icon. +1. Select the brown **Edit permissions** button in the modal. -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2. - -Epics let you manage your portfolio of projects more efficiently and with less -effort by tracking groups of issues that share a theme, across projects and -milestones. - -[Learn more about Epics.](epics/index.md) +Now you can edit the user's permissions from the **Members** page. ## Group wikis **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. -Group wikis work the same way as [project wikis](../project/wiki/index.md), please refer to those docs for details on usage. +Group wikis work the same way as [project wikis](../project/wiki/index.md). Group wikis can be edited by members with [Developer permissions](../../user/permissions.md#group-members-permissions) and above. -Group wiki repositories can be moved through the [Group repository storage moves API](../../api/group_repository_storage_moves.md). - -### Group wikis limitations +You can move group wiki repositories by using the [Group repository storage moves API](../../api/group_repository_storage_moves.md). There are a few limitations compared to project wikis: @@ -469,33 +339,11 @@ There are a few limitations compared to project wikis: - Group wikis are not included in global search and Geo replication. - Changes to group wikis don't show up in the group's activity feed. -For updates, you can follow: - -- [The epic tracking feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). - -## Group Security Dashboard **(ULTIMATE)** - -Get an overview of the vulnerabilities of all the projects in a group and its subgroups. - -[Learn more about the Group Security Dashboard.](../application_security/security_dashboard/index.md) - -## Insights **(ULTIMATE)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). -Configure the Insights that matter for your groups or projects, allowing users -to explore data such as: +## Transfer a group -- Triage hygiene -- Issues created/closed per a given period -- Average time for merge requests to be merged -- Much more - -[Learn more about Insights](insights/index.md). - -## Transferring groups - -From GitLab 10.5, you can transfer groups in the following ways: +You can transfer groups in the following ways: - Transfer a subgroup to a new parent group. - Convert a top-level group into a subgroup by transferring it to the desired group. @@ -506,214 +354,173 @@ When transferring groups, note: - Changing a group's parent can have unintended side effects. See [Redirects when changing repository paths](../project/repository/index.md#redirects-when-changing-repository-paths). - You can only transfer groups to groups you manage. - You must update your local repositories to point to the new location. -- If the immediate parent group's visibility is lower than the group's current visibility, visibility levels for subgroups and projects will change to match the new parent group's visibility. +- If the immediate parent group's visibility is lower than the group's current visibility, visibility levels for subgroups and projects change to match the new parent group's visibility. - Only explicit group membership is transferred, not inherited membership. If the group's owners have only inherited membership, this leaves the group without an owner. In this case, the user transferring the group becomes the group's owner. -- Transfers will fail if [packages](../packages/index.md) exist in any of the projects within the group, or in any of its subgroups. - -## Group settings - -After creating a group, you can manage its settings by navigating to -the group's dashboard, and clicking **Settings**. +- Transfers fail if [packages](../packages/index.md) exist in any of the projects in the group, or in any of its subgroups. - - -### General settings - -In addition to editing any settings you previously -set when [creating the group](#create-a-new-group), you can also -access further configurations for your group. - -#### Changing a group's path +## Change a group's path Changing a group's path (group URL) can have unintended side effects. Read -[how redirects will behave](../project/repository/index.md#redirects-when-changing-repository-paths) -before proceeding. +[how redirects behave](../project/repository/index.md#redirects-when-changing-repository-paths) +before you proceed. -If you are vacating the path so it can be claimed by another group or user, -you may need to rename the group too, since both names and paths must +If you are changing the path so it can be claimed by another group or user, +you may need to rename the group too. Both names and paths must be unique. +To retain ownership of the original namespace and protect the URL redirects, +create a new group and transfer projects to it instead. + To change your group path (group URL): -1. Navigate to your group's **Settings > General** page. +1. Go to your group's **Settings > General** page. 1. Expand the **Path, transfer, remove** section. -1. Enter a new name under **Change group URL**. -1. Click **Change group URL**. +1. Under **Change group URL**, enter a new name. +1. Select **Change group URL**. WARNING: -It is currently not possible to rename a namespace if it contains a +It is not possible to rename a namespace if it contains a project with [Container Registry](../packages/container_registry/index.md) tags, because the project cannot be moved. -NOTE: -If you want to retain ownership over the original namespace and -protect the URL redirects, then instead of changing a group's path or renaming a -username, you can create a new group and transfer projects to it. - -### Group repository settings - -You can change settings that are specific to repositories in your group. - -#### Custom initial branch name **(FREE)** +## Use a custom name for the initial branch > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43290) in GitLab 13.6. By default, when you create a new project in GitLab, the initial branch is called `master`. For groups, a group owner can customize the initial branch name to something -else. This way, every new project created under that group from then on will start from the custom branch name rather than `master`. To do so: +else. This way, every new project created under that group from then on starts from the custom branch name rather than `master`. + +To use a custom name for the initial branch: -1. Go to the **Group page > Settings > Repository** and expand **Default initial - branch name**. +1. Go to the group's **Settings > Repository** page. +1. Expand the **Default initial branch name** section. 1. Change the default initial branch to a custom name of your choice. -1. **Save Changes**. +1. Select **Save changes**. -### Remove a group +## Remove a group To remove a group and its contents: -1. Navigate to your group's **Settings > General** page. +1. Go to your group's **Settings > General** page. 1. Expand the **Path, transfer, remove** section. -1. In the Remove group section, click the **Remove group** button. -1. Confirm the action when asked to. +1. In the Remove group section, select **Remove group**. +1. Confirm the action. -This action either: +This action removes the group. It also adds a background job to delete all projects in the group. -- Removes the group, and also queues a background job to delete all projects in that group. -- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium](https://about.gitlab.com/pricing/premium/) or higher tiers, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +Specifically: -Since [GitLab 13.6](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), if the user who sets up the deletion leaves or is otherwise removed from the group before the -actual deletion happens, the job is cancelled, and the group is no longer scheduled for deletion. +- In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium](https://about.gitlab.com/pricing/premium/) or higher tiers, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +- In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), if the user who sets up the deletion is removed from the group before the +deletion happens, the job is cancelled, and the group is no longer scheduled for deletion. -### Restore a group **(PREMIUM)** +## Restore a group **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33257) in GitLab 12.8. To restore a group that is marked for deletion: -1. Navigate to your group's **Settings > General** page. +1. Go to your group's **Settings > General** page. 1. Expand the **Path, transfer, remove** section. -1. In the Restore group section, click the **Restore group** button. +1. In the Restore group section, select **Restore group**. -#### Enforce 2FA to group members - -Add a security layer to your group by -[enforcing two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforcing-2fa-for-all-users-in-a-group) -for all group members. - -#### Share with group lock +## Prevent a project from being shared with groups Prevent projects in a group from [sharing a project with another group](../project/members/share_project_with_groups.md) to enable tighter control over project access. -For example, let's say you have two distinct teams (Group A and Group B) working together in a project, and to inherit the group membership, you share the project between the -two groups A and B. **Share with group lock** prevents any project within -the group from being shared with another group, -guaranteeing that only the right group members have access to those projects. +To prevent a project from being shared with other groups: -To enable this feature, navigate to the group settings page. Select -**Share with group lock** and **Save the group**. - - +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section. +1. Select **Prevent sharing a project within <group_name> with other groups**. +1. Select **Save changes**. -#### Member Lock **(PREMIUM)** +## Prevent members from being added to a group **(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. +As a group owner, you can prevent any new project membership for all +projects in a group, allowing tighter control over project membership. For example, if you want to lock the group for an [Audit Event](../../administration/audit_events.md), -enable Member lock to guarantee that project membership cannot be modified during that audit. - -To enable this feature: +you can guarantee that project membership cannot be modified during the audit. -1. Navigate to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section, and select **Member lock**. -1. Click **Save changes**. +To prevent members from being added to a group: - +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section. +1. Under **Member lock**, select **Prevent adding new members to project membership within this group**. +1. Select **Save changes**. -This will disable the option for all users who previously had permissions to -operate project memberships, so no new users can be added. Furthermore, any -request to add a new user to a project through API will not be possible. +All users who previously had permissions can no longer add members to a group. +API requests to add a new user to a project are not possible. -#### IP access restriction **(PREMIUM)** +## Restrict group access by IP address **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) to [GitLab Premium](https://about.gitlab.com/pricing/) in 13.1. NOTE: -IP Access Restrictions are currently not functioning as expected on GitLab.com. Some users -may experience blocked Git operations or have difficulties accessing projects. Please -review the [following bug report](https://gitlab.com/gitlab-org/gitlab/-/issues/271673) for -more information. +IP access restrictions are not functioning as expected on GitLab.com. If enabled, +users cannot perform Git operations through SSH, or access projects in the UI. +For more information, [see this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/271673). -To make sure only people from within your organization can access particular -resources, you have the option to restrict access to groups and their -underlying subgroups, projects, issues, and so on, by IP address. This can help ensure that -particular content doesn't leave the premises, while not blocking off access to -the entire instance. IP access restrictions can only be configured at the group level. +To ensure only people from your organization can access particular +resources, you can restrict access to groups by IP address. This setting applies to all subgroups, +projects, issues, and so on. -Add one or more allowed IP subnets using CIDR notation to the group settings and anyone -coming from a different IP address won't be able to access the restricted -content. +IP access restrictions can be configured at the group level only. -Restriction currently applies to: +This restriction applies to: -- UI. -- [From GitLab 12.3](https://gitlab.com/gitlab-org/gitlab/-/issues/12874), API access. -- [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/32113), Git actions via SSH. +- The GitLab UI. +- [In GitLab 12.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/12874), the API. +- [In GitLab 12.4 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/32113), Git actions via SSH. -To avoid accidental lock-out, admins and group owners are able to access -the group regardless of the IP restriction. +Administrators and group owners are able to access the group regardless of the IP restriction. -To enable this feature: +To restrict group access by IP address: -1. Navigate to the group’s **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section, and enter IP address ranges into **Allow access to the following IP addresses** field. -1. Click **Save changes**. +1. Go to the group’s **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section. +1. In the **Allow access to the following IP addresses** field, enter IP address ranges in CIDR notation. +1. Select **Save changes**.  -#### Allowed domain restriction **(PREMIUM)** +## Restrict group access by domain **(PREMIUM)** >- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. ->- Support for specifying multiple email domains [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) in GitLab 13.1 +>- Support for specifying multiple email domains [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) added in GitLab 13.1. -You can restrict access to groups by allowing only users with email addresses in particular domains to be added to the group. +You can prevent users with email addresses in specific domains from being added to a group. -Add email domains you want to allow and users with emails from different domains won't be allowed to be added to this group. - -Some domains cannot be restricted. These are the most popular public email domains, such as: +To restrict group access by domain: -- `gmail.com` -- `yahoo.com` -- `hotmail.com` -- `aol.com` -- `msn.com` -- `hotmail.co.uk` -- `hotmail.fr` -- `live.com` -- `outlook.com` -- `icloud.com` - -To enable this feature: - -1. Navigate to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section, and enter the domain names into **Restrict membership by email** field. -1. Click **Save changes**. +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section. +1. In the **Restrict membership by email** field, enter the domain names. +1. Select **Save changes**.  -This will enable the domain-checking for all new users added to the group from this moment on. +Any time you attempt to add a new user, they are compared against this list. + +Some domains cannot be restricted. These are the most popular public email domains, such as: + +- `gmail.com`, `yahoo.com`, `aol.com`, `icloud.com` +- `hotmail.com`, `hotmail.co.uk`, `hotmail.fr` +- `msn.com`, `live.com`, `outlook.com` NOTE: -Domain restrictions only apply to groups and do not prevent users from being added as members of projects owned by the restricted group. +Domain restrictions apply to groups only. They do not prevent users from being added as members of projects owned by the restricted group. -#### Group file templates **(PREMIUM)** +## Group file templates **(PREMIUM)** -Group file templates allow you to share a set of templates for common file +Use group file templates to share a set of templates for common file types with every project in a group. It is analogous to the -[instance template repository](../admin_area/settings/instance_template_repository.md) -feature, and the selected project should follow the same naming conventions as +[instance template repository](../admin_area/settings/instance_template_repository.md). +The selected project should follow the same naming conventions as are documented on that page. You can only choose projects in the group as the template source. @@ -721,38 +528,38 @@ This includes projects shared with the group, but it **excludes** projects in subgroups or parent groups of the group being configured. You can configure this feature for both subgroups and immediate parent groups. A project -in a subgroup will have access to the templates for that subgroup, as well as +in a subgroup has access to the templates for that subgroup, as well as any immediate parent groups. - +To learn how to create templates for issues and merge requests, see +[Description templates](../project/description_templates.md). -To enable this feature, navigate to the group settings page, expand the -**Templates** section, choose a project to act as the template repository, and -**Save group**. +Define project templates at a group level by setting a group as the template source. +[Learn more about group-level project templates](custom_project_templates.md). **(PREMIUM)** - +### Enable group file template **(PREMIUM)** -To learn how to create templates for issues and merge requests, visit -[Description templates](../project/description_templates.md). +To enable group file templates: -#### Group-level project templates **(PREMIUM)** - -Define project templates at a group level by setting a group as the template source. -[Learn more about group-level project templates](custom_project_templates.md). +1. Go to the group's **Settings > General** page. +1. Expand the **Templates** section. +1. Choose a project to act as the template repository. +1. Select **Save changes**. -#### Disabling email notifications +## Disable email notifications > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23585) in GitLab 12.2. You can disable all email notifications related to the group, which includes its subgroups and projects. -To enable this feature: +To disable email notifications: -1. Navigate to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section, and select **Disable email notifications**. -1. Click **Save changes**. +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section. +1. Select **Disable email notifications**. +1. Select **Save changes**. -#### Disabling group mentions +## Disable group mentions > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21301) in GitLab 12.6. @@ -763,120 +570,95 @@ Groups with disabled mentions are visualized accordingly in the autocompletion d This is particularly helpful for groups with a large number of users. -To enable this feature: +To disable group mentions: -1. Navigate to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section, and select **Disable group mentions**. -1. Click **Save changes**. +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section. +1. Select **Disable group mentions**. +1. Select **Save changes**. -#### Enabling delayed Project removal **(PREMIUM)** +## Enable delayed project removal **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. -By default, projects within a group are deleted immediately. +By default, projects in a group are deleted immediately. Optionally, on [Premium](https://about.gitlab.com/pricing/) or higher tiers, -you can configure the projects within a group to be deleted after a delayed interval. +you can configure the projects in a group to be deleted after a delayed interval. -During this interval period, the projects will be in a read-only state and can be restored, if required. -The interval period defaults to 7 days, and can be modified by an admin in the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +During this interval period, the projects are in a read-only state and can be restored, if required. +The interval period defaults to 7 days, and can be modified by an administrator in the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). To enable delayed deletion of projects: -1. Navigate to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section, and check **Enable delayed project removal**. -1. Click **Save changes**. +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section. +1. Check **Enable delayed project removal**. +1. Select **Save changes**. NOTE: The group setting for delayed deletion is not inherited by subgroups and has to be individually defined for each group. -#### Prevent project forking outside group **(PREMIUM)** +## Prevent project forking outside group **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216987) in GitLab 13.3. -By default, projects within a group can be forked. +By default, projects in a group can be forked. Optionally, on [Premium](https://about.gitlab.com/pricing/) or higher tiers, -you can prevent the projects within a group from being forked outside of the current top-level group. +you can prevent the projects in a group from being forked outside of the current top-level group. Previously this setting was available only for groups enforcing group managed account. This setting will be -removed from SAML setting page and migrated to group setting, but in the interim period of changes both of those settings will be taken into consideration, if even one is set to `true` then it will be assumed group does not allow forking projects outside. +removed from SAML setting page and migrated to group settings. In the interim period, both of these settings are taken into consideration. +If even one is set to `true` then it will be assumed the group does not allow forking projects outside. To enable prevent project forking: -1. Navigate to the top-level group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section, and check **Prevent project forking outside current group**. -1. Click **Save changes**. - -### Advanced settings - -- **Projects**: View all projects within that group, add members to each project, - access each project's settings, and remove any project, all from the same screen. -- **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. **(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. +1. Go to the top-level group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section. +1. Check **Prevent project forking outside current group**. +1. Select **Save changes**. -#### Group push rules **(PREMIUM)** +## 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. Group push rules allow group maintainers to set -[push rules](../../push_rules/push_rules.md) for newly created projects within the specific group. +[push rules](../../push_rules/push_rules.md) for newly created projects in the specific group. -To configure push rules for a group, navigate to **{push-rules}** on the group's -sidebar. +To configure push rules for a group: -When set, new subgroups have push rules set for them based on either: +1. Go to the groups's **Push Rules** page. +1. Select the settings you want. +1. Select **Save Push Rules**. + +The group's new subgroups have push rules set for them based on either: - The closest parent group with push rules defined. - Push rules set at the instance level, if no parent groups have push rules defined. -### Maximum artifacts size **(FREE SELF)** - -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 **(PREMIUM)** - -With [GitLab Contribution Analytics](contribution_analytics/index.md), -you have an overview of the contributions (pushes, merge requests, -and issues) performed by your group members. - -## Issue analytics **(PREMIUM)** - -With [GitLab Issue Analytics](issues_analytics/index.md), you can see a bar chart of the number of issues created each month in your groups. - -## Repositories analytics **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in GitLab 13.6. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/276003) in GitLab 13.7. - -With [GitLab Repositories Analytics](repositories_analytics/index.md), you can view overall activity of all projects with code coverage. - -## Dependency Proxy - -Use GitLab as a [dependency proxy](../packages/dependency_proxy/index.md) for upstream Docker images. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> - -## DORA4 analytics overview **(ULTIMATE ONLY)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291747) in GitLab [Ultimate](https://about.gitlab.com/pricing/) 13.9 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). - -Group details include the following analytics: - -- Deployment Frequency - -For more information, see [DORA4 Project Analytics API](../../api/dora4_group_analytics.md). +## Related topics + +- [Maximum artifacts size](../admin_area/settings/continuous_integration.md#maximum-artifacts-size). **(FREE SELF)** +- [Repositories analytics](repositories_analytics/index.md): View overall activity of all projects with code coverage. **(PREMIUM)** +- [Contribution analytics](contribution_analytics/index.md): View the contributions (pushes, merge requests, + and issues) of group members. **(PREMIUM)** +- [Issue analytics](issues_analytics/index.md): View a bar chart of your group's number of issues per month. **(PREMIUM)** +- Use GitLab as a [dependency proxy](../packages/dependency_proxy/index.md) for upstream Docker images. +- [DORA4 Project Analytics API](../../api/dora4_group_analytics.md): View deployment frequency analytics. + [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291747) in GitLab Ultimate 13.9 as a + [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). **(ULTIMATE SELF)** +- [Epics](epics/index.md): Track groups of issues that share a theme. **(ULTIMATE)** +- [Security Dashboard](../application_security/security_dashboard/index.md): View the vulnerabilities of all + the projects in a group and its subgroups. **(ULTIMATE)** +- [Insights](insights/index.md): Configure insights like triage hygiene, issues created/closed per a given period, and + average time for merge requests to be merged. **(ULTIMATE)** +- [Webhooks](../project/integrations/webhooks.md). +- [Kubernetes cluster integration](clusters/index.md). +- [Audit Events](../../administration/audit_events.md#group-events). **(PREMIUM)** +- [Pipelines quota](../admin_area/settings/continuous_integration.md): Keep track of the pipeline quota for the group. +- [Integrations](../admin_area/settings/project_integration_management.md). +- [Transfer a project into a group](../project/settings/index.md#transferring-an-existing-project-into-another-namespace). +- [Share a project with a group](../project/members/share_project_with_groups.md): Give all group members access to the project at once. +- [Lock the sharing with group feature](#prevent-a-project-from-being-shared-with-groups). +- [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforcing-2fa-for-all-users-in-a-group): Enforce 2FA + for all group members. diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 1cb7c05bb5f..42522723047 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -40,6 +40,9 @@ To see the latest code coverage for each project in your group: 1. Go to **Analytics > Repositories** in the group (not from a project). 1. In the **Latest test coverage results** section, use the **Select projects** dropdown to choose the projects you want to check. +You can download code coverage data for specific projects using +[code coverage history](../../../ci/pipelines/settings.md#code-coverage-history). + ## Download historic test coverage data > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index e2c01987e36..9b3ae75b39c 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -41,7 +41,7 @@ toggle the list of the milestone bars. > - Filtering roadmaps by milestone is enabled on GitLab.com. > - Filtering roadmaps by milestone is recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-filtering-roadmaps-by-milestone). **(PREMIUM SELF)** -> - Filtering by epic confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218624) in GitLab 13.8. +> - Filtering by epic confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218624) in GitLab 13.9. WARNING: Filtering roadmaps by milestone might not be available to you. Check the **version history** note above for details. diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index dd0888a610f..9f2cafd456b 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -37,17 +37,7 @@ Since use of the group-managed account requires the use of SSO, users of group-m - The user is unable to access the group (their credentials no longer work on the identity provider when prompted to use SSO). - Contributions in the group (for example, issues and merge requests) remains intact. -## Assertions - -When using group-managed accounts, the following user details need to be passed to GitLab as SAML -assertions to be able to create a user. - -| Field | Supported keys | -|-----------------|----------------| -| Email (required)| `email`, `mail` | -| Full Name | `name` | -| First Name | `first_name`, `firstname`, `firstName` | -| Last Name | `last_name`, `lastname`, `lastName` | +Please refer to our [SAML SSO for Groups page](../index.md) for information on how to configure SAML. ## Feature flag **(PREMIUM SELF)** diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index d1c490b0769..5079b927fbe 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -25,7 +25,8 @@ SAML SSO is only configurable at the top-level group. 1. Navigate to the group and select **Settings > SAML SSO**. 1. Configure your SAML server using the **Assertion consumer service URL**, **Identifier**, and **GitLab single sign-on URL**. Alternatively GitLab provides [metadata XML configuration](#metadata-configuration). See [specific identity provider documentation](#providers) for more details. 1. Configure the SAML response to include a NameID that uniquely identifies each user. -1. Configure [required assertions](group_managed_accounts.md#assertions) if using [Group Managed Accounts](group_managed_accounts.md). +1. Configure [required assertions](#assertions) at minimum containing + the user's email address. 1. While the default is enabled for most SAML providers, please ensure the app is set to have [Service Provider](#glossary) initiated calls in order to link existing GitLab accounts. 1. Once the identity provider is set up, move on to [configuring GitLab](#configuring-gitlab). @@ -53,6 +54,19 @@ Once users have signed into GitLab using the SSO SAML setup, changing the `NameI We recommend setting the NameID format to `Persistent` unless using a field (such as email) that requires a different format. +### Assertions + +For users to be created with the right information with the improved [user access and management](#user-access-and-management), +the following user details need to be passed to GitLab as SAML assertions. + +| Field | Supported keys | +|-----------------|----------------| +| Email (required)| `email`, `mail` | +| Username | `username`, `nickname` | +| Full Name | `name` | +| First Name | `first_name`, `firstname`, `firstName` | +| Last Name | `last_name`, `lastname`, `lastName` | + ### Metadata configuration GitLab provides metadata XML that can be used to configure your Identity Provider. @@ -87,9 +101,8 @@ Please note that the certificate [fingerprint algorithm](#additional-providers-a With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users can't be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. However, users are not prompted to sign in through SSO on each visit. GitLab checks whether a user -has authenticated through SSO. If it's been more than 7 days since the last sign-in, GitLab +has authenticated through SSO. If it's been more than 1 day since the last sign-in, GitLab prompts the user to sign in again through SSO. -You can see more information about how long a session is valid in our [user profile documentation](../../profile/#why-do-i-keep-getting-signed-out). We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/9152). @@ -148,8 +161,11 @@ For NameID, the following settings are recommended; for SCIM, the following sett ### OneLogin setup notes -The GitLab app listed in the OneLogin app catalog is for self-managed GitLab instances. -For GitLab.com, use a generic SAML Test Connector such as the SAML Test Connector (Advanced). +OneLogin supports their own [GitLab (SaaS)](https://onelogin.service-now.com/support?id=kb_article&sys_id=92e4160adbf16cd0ca1c400e0b961923&kb_category=50984e84db738300d5505eea4b961913) +application. + +If you decide to use the OneLogin generic [SAML Test Connector (Advanced)](https://onelogin.service-now.com/support?id=kb_article&sys_id=b2c19353dbde7b8024c780c74b9619fb&kb_category=93e869b0db185340d5505eea4b961934), +we recommend the following settings: | GitLab Setting | OneLogin Field | |--------------|----------------| @@ -170,7 +186,7 @@ For more information, see our [discussion on providers](#providers). Your identity provider may have relevant documentation. It may be generic SAML documentation, or specifically targeted for GitLab. Examples: - [ADFS (Active Directory Federation Services)](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) -- [Auth0](https://auth0.com/docs/protocols/saml-configuration-options/configure-auth0-as-saml-identity-provider) +- [Auth0](https://auth0.com/docs/protocols/saml-protocol/configure-auth0-as-saml-identity-provider) - [Google Workspace](https://support.google.com/a/answer/6087519?hl=en) - [JumpCloud](https://support.jumpcloud.com/support/s/article/single-sign-on-sso-with-gitlab-2019-08-21-10-36-47) - [PingOne by Ping Identity](https://docs.pingidentity.com/bundle/pingone/page/xsh1564020480660-1.html) @@ -348,6 +364,11 @@ the user gets the highest access level from the groups. For example, if one grou is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer` access. +Users who are not members of any mapped SAML groups are removed from the GitLab group. + +You can prevent accidental member removal. For example, if you have a SAML group link for `Owner` level access +in a top-level group, you should also set up a group link for all other members. + ## Glossary | Term | Description | diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 3a34a4b0599..d248729b615 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -161,6 +161,11 @@ The Okta GitLab application currently only supports SCIM. Continue using the separate Okta [SAML SSO](index.md) configuration along with the new SCIM application described above. +### OneLogin + +OneLogin provides a "GitLab (SaaS)" app in their catalog, which includes a SCIM integration. +As the app is developed by OneLogin, please reach out to OneLogin if you encounter issues. + ## User access and linking setup The following diagram is a general outline on what happens when you add users to your SCIM app: @@ -204,6 +209,10 @@ graph TD B -->|Yes| D[GitLab removes user from GitLab group] ``` +During the synchronization process, all of your users get GitLab accounts, welcoming them +to their respective groups, with an invitation email. When implementing SCIM provisioning, +you may want to warn your security-conscious employees about this email. + ## Troubleshooting This section contains possible solutions for problems you might encounter. diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 59812fc2b2f..16430b49549 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Manage +group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto, concepts --- @@ -147,7 +147,7 @@ From the image above, we can deduce the following things: - Administrator is the Owner and member of **all** subgroups and for that reason, as with User 3, the **Source** column indicates **Direct member**. -Members can be [filtered by inherited or direct membership](../index.md#membership-filter). +Members can be [filtered by inherited or direct membership](../index.md#filter-a-group). ### Overriding the ancestor group membership diff --git a/doc/user/img/gitlab_snippet_v13_0.png b/doc/user/img/gitlab_snippet_v13_0.png Binary files differdeleted file mode 100644 index 33194c512df..00000000000 --- a/doc/user/img/gitlab_snippet_v13_0.png +++ /dev/null diff --git a/doc/user/img/gitlab_snippet_v13_5.png b/doc/user/img/gitlab_snippet_v13_5.png Binary files differdeleted file mode 100644 index 3fce1d25c3d..00000000000 --- a/doc/user/img/gitlab_snippet_v13_5.png +++ /dev/null diff --git a/doc/user/img/new_personal_snippet_from_project_v12_10.png b/doc/user/img/new_personal_snippet_from_project_v12_10.png Binary files differdeleted file mode 100644 index af8cce01208..00000000000 --- a/doc/user/img/new_personal_snippet_from_project_v12_10.png +++ /dev/null diff --git a/doc/user/img/new_personal_snippet_v12_10.png b/doc/user/img/new_personal_snippet_v12_10.png Binary files differdeleted file mode 100644 index a995e4d4b40..00000000000 --- a/doc/user/img/new_personal_snippet_v12_10.png +++ /dev/null diff --git a/doc/user/index.md b/doc/user/index.md index a678038507f..dfbba7e9c19 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -31,10 +31,10 @@ For more information, see [All GitLab Features](https://about.gitlab.com/feature To get familiar with the concepts needed to develop code on GitLab, read the following articles: - [Demo: Mastering Code Review With GitLab](https://about.gitlab.com/blog/2017/03/17/demo-mastering-code-review-with-gitlab/). -- [GitLab Workflow: An Overview](https://about.gitlab.com/blog/2016/10/25/gitlab-workflow-an-overview/#gitlab-workflow-use-case-scenario). +- [GitLab Workflow: An Overview](https://about.gitlab.com/topics/version-control/what-is-gitlab-workflow/#gitlab-workflow-a-use-case-scenario). - [Tutorial: It's all connected in GitLab](https://about.gitlab.com/blog/2016/03/08/gitlab-tutorial-its-all-connected/): an overview on code collaboration with GitLab. - [Trends in Version Control Land: Microservices](https://about.gitlab.com/blog/2016/08/16/trends-in-version-control-land-microservices/). -- [Trends in Version Control Land: Innersourcing](https://about.gitlab.com/blog/2016/07/07/trends-version-control-innersourcing/). +- [Trends in Version Control Land: Innersourcing](https://about.gitlab.com/topics/version-control/what-is-innersource/). ## Use cases @@ -61,7 +61,7 @@ With GitLab Enterprise Edition, you can also: - [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards). - Create formal relationships between issues with [Related Issues](project/issues/related_issues.md). - Use [Burndown Charts](project/milestones/burndown_and_burnup_charts.md) to track progress during a sprint or while working on a new version of their software. -- Leverage [Elasticsearch](../integration/elasticsearch.md) with [Advanced Search](search/advanced_global_search.md) and [Advanced Search Syntax](search/advanced_search_syntax.md) for faster, more advanced code search across your entire GitLab instance. +- Leverage [Elasticsearch](../integration/elasticsearch.md) with [Advanced Search](search/advanced_search.md) for faster, more advanced code search across your entire GitLab instance. - [Authenticate users with Kerberos](../integration/kerberos.md). - [Mirror a repository](project/repository/repository_mirroring.md) from elsewhere on your local server. - View your entire CI/CD pipeline involving more than one project with [Multiple-Project Pipelines](../ci/multi_project_pipelines.md). diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 6ba5e49d553..b202359847c 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -52,9 +52,9 @@ This video from January 2021 walks you through all the GitLab Terraform integrat ## GitLab Managed Terraform state -[Terraform remote backends](https://www.terraform.io/docs/backends/index.html) +[Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html) enable you to store the state file in a remote, shared store. GitLab uses the -[Terraform HTTP backend](https://www.terraform.io/docs/backends/types/http.html) +[Terraform HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) to securely store the state files in local storage (the default) or [the remote store of your choice](../../administration/terraform_state.md). diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md index ae35ebce0dc..2cd5ed8ac78 100644 --- a/doc/user/infrastructure/terraform_state.md +++ b/doc/user/infrastructure/terraform_state.md @@ -8,9 +8,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. -[Terraform remote backends](https://www.terraform.io/docs/backends/index.html) +[Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html) enable you to store the state file in a remote, shared store. GitLab uses the -[Terraform HTTP backend](https://www.terraform.io/docs/backends/types/http.html) +[Terraform HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) to securely store the state files in local storage (the default) or [the remote store of your choice](../../administration/terraform_state.md). @@ -96,7 +96,7 @@ Next, [configure the backend](#configure-the-backend). After executing the `terraform init` command, you must configure the Terraform backend and the CI YAML file: -1. In your Terraform project, define the [HTTP backend](https://www.terraform.io/docs/backends/types/http.html) +1. In your Terraform project, define the [HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) by adding the following code block in a `.tf` file (such as `backend.tf`) to define the remote backend: @@ -116,7 +116,7 @@ and the CI YAML file: image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest ``` -1. In the `.gitlab-ci.yml` file, define some environment variables to ease +1. In the `.gitlab-ci.yml` file, define some CI/CD variables to ease development. In this example, `TF_ROOT` is the directory where the Terraform commands must be executed, `TF_ADDRESS` is the URL to the state on the GitLab instance where this pipeline runs, and the final path segment in `TF_ADDRESS` @@ -203,16 +203,16 @@ See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gi ## Using a GitLab managed Terraform state backend as a remote data source You can use a GitLab-managed Terraform state as a -[Terraform data source](https://www.terraform.io/docs/providers/terraform/d/remote_state.html). +[Terraform data source](https://www.terraform.io/docs/language/state/remote-state-data.html). To use your existing Terraform state backend as a data source, provide the following details -as [Terraform input variables](https://www.terraform.io/docs/configuration/variables.html): +as [Terraform input variables](https://www.terraform.io/docs/language/values/variables.html): - **address**: The URL of the remote state backend you want to use as a data source. For example, `https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>`. - **username**: The username to authenticate with the data source. If you are using a [Personal Access Token](../profile/personal_access_tokens.md) for authentication, this is your GitLab username. If you are using GitLab CI, this is `'gitlab-ci-token'`. - **password**: The password to authenticate with the data source. If you are using a Personal Access Token for - authentication, this is the token value. If you are using GitLab CI, it is the contents of the `${CI_JOB_TOKEN}` CI variable. + authentication, this is the token value. If you are using GitLab CI, it is the contents of the `${CI_JOB_TOKEN}` CI/CD variable. An example setup is shown below: diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 5f974d75522..0c257f2fb70 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -18,13 +18,13 @@ for a complete Kramdown reference. NOTE: We encourage you to view this document as [rendered by GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md). -## GitLab Flavored Markdown (GFM) +## GitLab Flavored Markdown -GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification](https://spec.commonmark.org/current/) +GitLab uses "GitLab Flavored Markdown". It extends the [CommonMark specification](https://spec.commonmark.org/current/) (which is based on standard Markdown) in several ways to add more features. -It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/free-pro-team@latest/github/writing-on-github/basic-writing-and-formatting-syntax). +It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). -You can use GFM in the following areas: +You can use GitLab Flavored Markdown in the following areas: - Comments - Issues @@ -92,12 +92,12 @@ if any changes are needed. `diff_redcarpet_cmark` is not an officially supported product. -### GFM extends standard Markdown +### GitLab Flavored Markdown extends standard Markdown GitLab makes full use of the standard (CommonMark) formatting, but also includes more helpful features for GitLab users. -It makes use of [new Markdown features](#new-gfm-markdown-extensions), +It makes use of [new Markdown features](#new-gitlab-flavored-markdown-extensions), not found in standard Markdown: - [Color chips written in HEX, RGB or HSL](#colors) @@ -124,7 +124,7 @@ changing how standard Markdown is used: | [line breaks](#line-breaks) | [more line break control](#newlines) | | [links](#links) | [automatically linking URLs](#url-auto-linking) | -## New GFM Markdown extensions +## New GitLab Flavored Markdown extensions ### Colors @@ -251,7 +251,7 @@ If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com ```markdown Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: -:zap: You can use emoji anywhere GFM is supported. :v: +:zap: You can use emoji anywhere GitLab Flavored Markdown is supported. :v: You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People :heart: you for that. @@ -262,7 +262,7 @@ Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all sup Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> to your <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. Well we have a gift for you: -<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">You can use emoji anywhere GFM is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> +<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">You can use emoji anywhere GitLab Flavored Markdown is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> You can use it to point out a<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/bug.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> patches. If someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/snail.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/birthday.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. People <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> you for that. @@ -424,14 +424,14 @@ the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activati ### Special GitLab references -GFM recognizes special GitLab related references. For example, you can reference -an issue, a commit, a team member, or even an entire project team. GFM turns +GitLab Flavored Markdown recognizes special GitLab related references. For example, you can reference +an issue, a commit, a team member, or even an entire project team. GitLab Flavored Markdown turns that reference into a link so you can navigate between them. -Additionally, GFM recognizes certain cross-project references and also has a shorthand +Additionally, GitLab Flavored Markdown recognizes certain cross-project references and also has a shorthand version to reference other projects from the same namespace. -GFM recognizes the following: +GitLab Flavored Markdown recognizes the following: | references | input | cross-project reference | shortcut inside same namespace | | :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- | @@ -462,7 +462,8 @@ GFM recognizes the following: For example, referencing an issue by using `#123` formats the output as a link to issue number 123 with text `#123`. Likewise, a link to issue number 123 is -recognized and formatted with text `#123`. +recognized and formatted with text `#123`. If you don't want `#123` to link to an issue, +add a leading backslash `\#123`. In addition to this, links to some objects are also recognized and formatted. Some examples of these are: @@ -630,7 +631,7 @@ Quote break. If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiline-blockquote). -GFM extends the standard Markdown by also supporting multi-line blockquotes +GitLab Flavored Markdown extends the standard Markdown by also supporting multi-line blockquotes fenced by `>>>`: ```markdown @@ -778,7 +779,7 @@ But let's throw in a <b>tag</b>. There are multiple ways to emphasize text in Markdown. You can italicize, bold, strikethrough, and combine these emphasis styles together. -Strikethrough is not part of the core Markdown standard, but is part of GFM. +Strikethrough is not part of the core Markdown standard, but is part of GitLab Flavored Markdown. Examples: @@ -807,7 +808,7 @@ If this section isn't rendered correctly, Avoid italicizing a portion of a word, especially when you're dealing with code and names that often appear with multiple underscores. -GFM extends the standard Markdown standard by ignoring multiple underlines in words, +GitLab Flavored Markdown extends the standard Markdown standard by ignoring multiple underlines in words, to allow better rendering of Markdown documents discussing code: ```markdown @@ -899,7 +900,7 @@ Alt-H2 #### Header IDs and links -GFM extends the standard Markdown standard so that all Markdown-rendered headers automatically +GitLab Flavored Markdown extends the standard Markdown standard so that all Markdown-rendered headers automatically get IDs, which can be linked to, except in comments. On hover, a link to those IDs becomes visible to make it easier to copy the link to @@ -1193,7 +1194,7 @@ in the *same paragraph*. #### Newlines -GFM adheres to the Markdown specification in how [paragraphs and line breaks are handled](https://spec.commonmark.org/current/). +GitLab Flavored Markdown adheres to the Markdown specification in how [paragraphs and line breaks are handled](https://spec.commonmark.org/current/). A paragraph is one or more consecutive lines of text, separated by one or more blank lines (two newlines at the end of the first paragraph), as [explained above](#line-breaks). @@ -1275,7 +1276,7 @@ points the link to `wikis/style` only when the link is inside of a wiki Markdown #### URL auto-linking -GFM auto-links almost any URL you put into your text: +GitLab Flavored Markdown auto-links almost any URL you put into your text: ```markdown - https://www.google.com @@ -1322,7 +1323,7 @@ Examples: <!-- The "2." and "4." in the example above are changed to "1." below, to match the style standards on docs.gitlab.com. -See https://docs.gitlab.com/ee/development/documentation/styleguide.html#lists +See https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#lists --> 1. First ordered list item @@ -1356,7 +1357,7 @@ They can even: <!-- The "*" and "+" in the example above are changed to "-" below, to match the style standards on docs.gitlab.com. -See https://docs.gitlab.com/ee/development/documentation/styleguide.html#lists +See https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#lists --> Unordered lists can: @@ -1418,7 +1419,7 @@ Example: ### Superscripts / Subscripts -CommonMark and GFM don't support the Redcarpet superscript syntax ( `x^2` ). +CommonMark and GitLab Flavored Markdown don't support the Redcarpet superscript syntax ( `x^2` ). Use the standard HTML syntax for superscripts and subscripts: ```html @@ -1435,7 +1436,7 @@ while the equation for the theory of relativity is E = mc<sup>2</sup>. ### Tables -Tables are not part of the core Markdown spec, but they are part of GFM. +Tables are not part of the core Markdown spec, but they are part of GitLab Flavored Markdown. 1. The first line contains the headers, separated by "pipes" (`|`). 1. The second line separates the headers from the cells, and must contain three or more dashes. diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index c115f94b964..3b8be68cff6 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -171,6 +171,10 @@ convention. ## Authenticate to the Package Registry +GitLab requires authentication to upload packages, and to install packages +from private and internal projects. (You can, however, install packages +from public projects without authentication.) + To authenticate to the Package Registry, you need one of the following: - A [personal access token](../../../user/profile/personal_access_tokens.md) @@ -302,8 +306,9 @@ file. Prerequisites: - The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote). -- [Authentication](#authenticate-to-the-package-registry) with the - Package Registry must be configured. +- For private and internal projects, you must configure + [Authentication](#authenticate-to-the-package-registry) + with the Package Registry. 1. In the project where you want to install the package as a dependency, open `conanfile.txt`. Or, in the root of your project, create a file called diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index e3a469c4b6c..eae114b49f2 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -577,7 +577,7 @@ Here are examples of regex patterns you may want to use: (?:v.+|master|release.*) ``` -### Set cleanup limits to conserve resources +### Set cleanup limits to conserve resources > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/288812) in GitLab 13.9. > - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. @@ -595,7 +595,7 @@ To prevent server resource starvation, the following application settings are av - `container_registry_delete_tags_service_timeout`. The maximum time, in seconds, that the cleanup process can take to delete a batch of tags. - `container_registry_cleanup_tags_service_max_list_size`. The maximum number of tags that can be deleted in a single execution. Additional tags must be deleted in another execution. We recommend starting with a low number, like `100`, and increasing it after monitoring that container images are properly deleted. - + For self-managed instances, those settings can be updated in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): ```ruby @@ -699,7 +699,7 @@ project or branch name. Special characters can include: - Leading underscore - Trailing hyphen/dash -To get around this, you can [change the group path](../../group/index.md#changing-a-groups-path), +To get around this, you can [change the group path](../../group/index.md#change-a-groups-path), [change the project path](../../project/settings/index.md#renaming-a-repository) or change the branch name. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index fdf0caba090..5b096f846e6 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -4,12 +4,13 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Dependency Proxy +# Dependency Proxy **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 13.6. -> - [Support for private groups](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. -> - Anonymous access to images in public groups is no longer available starting in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to GitLab Free in GitLab 13.6. +> - [Support for private groups](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in GitLab Free 13.7. +> - Anonymous access to images in public groups is no longer available starting in GitLab Free 13.7. +> - [Support for pull-by-digest and Docker version 20.x](https://gitlab.com/gitlab-org/gitlab/-/issues/290944) in GitLab Free 13.10. The GitLab Dependency Proxy is a local proxy you can use for your frequently-accessed upstream images. @@ -17,11 +18,6 @@ upstream images. In the case of CI/CD, the Dependency Proxy receives a request and returns the upstream image from a registry, acting as a pull-through cache. -NOTE: -The Dependency Proxy is not compatible with Docker version 20.x and later. -If you are using the Dependency Proxy, Docker version 19.x.x is recommended until -[issue #290944](https://gitlab.com/gitlab-org/gitlab/-/issues/290944) is resolved. - ## Prerequisites The Dependency Proxy must be [enabled by an administrator](../../../administration/packages/dependency_proxy.md). @@ -60,7 +56,7 @@ Prerequisites: ### Authenticate with the Dependency Proxy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in GitLab Free 13.7. > - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. > - It's enabled on GitLab.com. > - It's recommended for production use. @@ -162,7 +158,7 @@ the [Dependency Proxy API](../../../api/dependency_proxy.md). ## Docker Hub rate limits and the Dependency Proxy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) in GitLab Free 13.7. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch how to [use the Dependency Proxy to help avoid Docker Hub rate limits](https://youtu.be/Nc4nUo7Pq08). diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 73b84c04b6d..b9186e99357 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -40,7 +40,7 @@ Prerequisites: - You need to [authenticate with the API](../../../api/README.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. ```plaintext -PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name +PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name?status=:status ``` | Attribute | Type | Required | Description | @@ -53,12 +53,28 @@ PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name Provide the file context in the request body. -Example request: +Example request using a personal access token: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ --upload-file path/to/file.txt \ - "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt" + "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?status=hidden" +``` + +Example response: + +```json +{ + "message":"201 Created" +} +``` + +Example request using a deploy token: + +```shell +curl --header "DEPLOY-TOKEN: <deploy_token>" \ + --upload-file path/to/file.txt \ + "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?status=hidden" ``` Example response: diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index c9397f8d9f6..1fdc34e820e 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -96,7 +96,7 @@ following steps work only if GitLab is configured for HTTPS: Create a [personal access token](../../profile/personal_access_tokens.md) with the scope set to `api` or `read_api`. -Open your [`~/.netrc`](https://ec.haxx.se/usingcurl/usingcurl-netrc) file +Open your [`~/.netrc`](https://everything.curl.dev/usingcurl/netrc) file and add the following text. Replace the variables in `< >` with your values. ```plaintext diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index d2bd9ef5646..03738eb0b9e 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -43,14 +43,14 @@ guides you through the process. | CocoaPods | [#36890](https://gitlab.com/gitlab-org/gitlab/-/issues/36890) | | Conda | [#36891](https://gitlab.com/gitlab-org/gitlab/-/issues/36891) | | CRAN | [#36892](https://gitlab.com/gitlab-org/gitlab/-/issues/36892) | -| Debian | [WIP: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44746) | +| Debian | [Draft: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50438) | | Opkg | [#36894](https://gitlab.com/gitlab-org/gitlab/-/issues/36894) | | P2 | [#36895](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) | | Puppet | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | | RPM | [#5932](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) | | RubyGems | [#803](https://gitlab.com/gitlab-org/gitlab/-/issues/803) | | SBT | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | -| Terraform | [WIP: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) | +| Terraform | [Draft: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) | | Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | <!-- vale gitlab.Spelling = YES --> diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index b1075e19b7b..f048440e383 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -86,7 +86,9 @@ A `package.json` file is created. To use the GitLab endpoint for npm packages, choose an option: - **Project-level**: Use when you have few npm packages and they are not in - the same GitLab group. + the same GitLab group. The [package naming convention](#package-naming-convention) is not enforced at this level. + Instead, you should use a [scope](https://docs.npmjs.com/cli/v6/using-npm/scope) for your package. + When you use a scope, the registry URL is [updated](#authenticate-to-the-package-registry) only for that scope. - **Instance-level**: Use when you have many npm packages in different GitLab groups or in their own namespace. Be sure to comply with the [package naming convention](#package-naming-convention). @@ -151,7 +153,7 @@ npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_tok - `<your_token>` is your personal access token or deploy token. - Replace `gitlab.example.com` with your domain name. -You should now be able to publish and install npm packages in your project. +You should now be able to install npm packages in your project. If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view [troubleshooting steps](#troubleshooting). @@ -204,9 +206,14 @@ Then, you can run `npm publish` either locally or by using GitLab CI/CD. ## Package naming convention -Your npm package name must be in the format of `@scope/package-name`. +When you use the [instance-level endpoint](#use-the-gitlab-endpoint-for-npm-packages), only the packages with names in the format of `@scope/package-name` are available. -- The `@scope` is the root namespace of the GitLab project. It must match exactly, including the case. +- The `@scope` is the root namespace of the GitLab project. To follow npm's convention, it should be + lowercase. However, the GitLab package registry allows for uppercase. Before GitLab 13.10, the + `@scope` had to be a case-sensitive match of the GitLab project's root namespace. This was + problematic because the npm public registry does not allow uppercase letters. GitLab 13.10 relaxes + this requirement and translates uppercase in the GitLab `@scope` to lowercase for npm. For + example, a package `@MyScope/package-name` in GitLab becomes `@myscope/package-name` for npm. - The `package-name` can be whatever you want. For example, if your project is `https://gitlab.example.com/my-org/engineering-group/team-amazing/analytics`, @@ -216,7 +223,8 @@ the root namespace is `my-org`. When you publish a package, it must have `my-org | ---------------------- | ----------------------- | --------- | | `my-org/bar` | `@my-org/bar` | Yes | | `my-org/bar/baz` | `@my-org/baz` | Yes | -| `My-org/Bar/baz` | `@My-org/Baz` | Yes | +| `My-Org/Bar/baz` | `@my-org/Baz` | Yes | +| `My-Org/Bar/baz` | `@My-Org/Baz` | Yes | | `my-org/bar/buz` | `@my-org/anything` | Yes | | `gitlab-org/gitlab` | `@gitlab-org/gitlab` | Yes | | `gitlab-org/gitlab` | `@foo/bar` | No | @@ -229,8 +237,7 @@ In GitLab, this regex validates all package names from all package managers: This regex allows almost all of the characters that npm allows, with a few exceptions (for example, `~` is not allowed). -The regex also allows for capital letters, while npm does not. Capital letters are needed because the scope must be -identical to the root namespace of the project. +The regex also allows for capital letters, while npm does not. WARNING: When you update the path of a user or group, or transfer a subgroup or project, @@ -302,8 +309,9 @@ the same version more than once, even if it has been deleted. ## Install a package npm packages are commonly-installed by using the `npm` or `yarn` commands -in a JavaScript project. You can install a package from the scope of a project, group, -or instance. +in a JavaScript project. You can install a package from the scope of a project or instance. + +If multiple packages have the same name and version, when you install a package, the most recently-published package is retrieved. 1. Set the URL for scoped packages by running: diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 101bb810a0e..e1b61f28818 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -219,7 +219,7 @@ To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package <configuration> <packageSources> <clear /> - <add key="gitlab" value="https://gitlab.example.com/api/v4/project/<your_project_id>/packages/nuget/index.json" /> + <add key="gitlab" value="https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" /> </packageSources> <packageSourceCredentials> <gitlab> diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 19796de0f51..2fd05ac1748 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Package Registry +# Package Registry **(FREE)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 763dbee3a82..a6cc5cf1f07 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -174,11 +174,10 @@ index-servers = [gitlab] repository = https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi -username = __token__ -password = <your personal access token> +username = <your_personal_access_token_name> +password = <your_personal_access_token> ``` -- `username` must be `__token__` exactly. - Your project ID is on your project's home page. ### Authenticate with a deploy token @@ -317,24 +316,31 @@ more than once, a `404 Bad Request` error occurs. To install the latest version of a package, use the following command: ```shell -pip install --extra-index-url https://__token__:<personal_access_token>@gitlab.example.com/api/v4/projects/<project_id>/packages/pypi/simple --no-deps <package_name> +pip install --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/projects/<project_id>/packages/pypi/simple --no-deps <package_name> ``` - `<package_name>` is the package name. +- `<personal_access_token_name>` is a personal access token name with the `read_api` scope. - `<personal_access_token>` is a personal access token with the `read_api` scope. - `<project_id>` is the project ID. +In these commands, you can use `--extra-index-url` instead of `--index-url`. However, using +`--extra-index-url` makes you vulnerable to dependency confusion attacks because it checks the PyPi +repository for the package before it checks the custom repository. `--extra-index-url` adds the +provided URL as an additional registry which the client checks if the package is present. +`--index-url` tells the client to check for the package on the provided URL only. + If you were following the guide and want to install the `MyPyPiPackage` package, you can run: ```shell -pip install mypypipackage --no-deps --extra-index-url https://__token__:<personal_access_token>@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple +pip install mypypipackage --no-deps --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple ``` This message indicates that the package was installed successfully: ```plaintext -Looking in indexes: https://__token__:****@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple +Looking in indexes: https://<personal_access_token_name>:****@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple Collecting mypypipackage Downloading https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/files/d53334205552a355fee8ca35a164512ef7334f33d309e60240d57073ee4386e6/mypypipackage-0.0.1-py3-none-any.whl (1.6 kB) Installing collected packages: mypypipackage diff --git a/doc/user/packages/workflows/monorepo.md b/doc/user/packages/workflows/monorepo.md deleted file mode 100644 index abba9df6ec2..00000000000 --- a/doc/user/packages/workflows/monorepo.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../npm_registry/index.md' -disqus_identifier: 'https://docs.gitlab.com/ee/user/packages/workflows/monorepo.html' ---- - -This document was moved to [another location](../npm_registry/index.md). - -<!-- This redirect file can be deleted after <2021-02-14>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 9b99b126996..c63c2cc9989 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -77,6 +77,11 @@ depending on your final package recipe. For example: CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan upload MyPackage/1.0.0@foo+bar+my-proj/channel --all --remote=gitlab ``` +### Composer + +You can't publish a Composer package outside of its project. An [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/250633) +exists to implement functionality that allows you to publish such packages to other projects. + ### All other package types [All package types supported by GitLab](../index.md) can be published in diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 68a68ed65ad..bde589661f9 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -78,6 +78,7 @@ The following table depicts the various user permission levels in a project. | Assign reviewers | | ✓ | ✓ | ✓ | ✓ | | Label issues | | ✓ | ✓ | ✓ | ✓ | | Set issue weight | | ✓ | ✓ | ✓ | ✓ | +| [Set issue estimate and record time spent](project/time_tracking.md) | | ✓ | ✓ | ✓ | ✓ | | Lock issue threads | | ✓ | ✓ | ✓ | ✓ | | Manage issue tracker | | ✓ | ✓ | ✓ | ✓ | | Manage related issues | | ✓ | ✓ | ✓ | ✓ | @@ -104,7 +105,8 @@ The following table depicts the various user permission levels in a project. | Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | | Create/edit/delete a Cleanup policy | | | ✓ | ✓ | ✓ | | Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | -| Create/edit/delete [Releases](project/releases/index.md)| | | ✓ | ✓ | ✓ | +| Create/edit [releases](project/releases/index.md)| | | ✓ | ✓ | ✓ | +| Delete [releases](project/releases/index.md)| | | | ✓ | ✓ | | Create new branches | | | ✓ | ✓ | ✓ | | Push to non-protected branches | | | ✓ | ✓ | ✓ | | Force push to non-protected branches | | | ✓ | ✓ | ✓ | @@ -173,6 +175,7 @@ The following table depicts the various user permission levels in a project. | View project Audit Events | | | ✓ (*12*) | ✓ | ✓ | | Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | | Manage [project access tokens](project/settings/project_access_tokens.md) **(FREE SELF)** | | | | ✓ | ✓ | +| View 2FA status of members | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | | Transfer project to another namespace | | | | | ✓ | | Rename project | | | | | ✓ | @@ -194,7 +197,7 @@ The following table depicts the various user permission levels in a project. 1. If the [branch is protected](project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings), this depends on the access Developers and Maintainers are given. 1. Guest users can access GitLab [**Releases**](project/releases/index.md) for downloading assets but are not allowed to download the source code nor see repository information like tags and commits. 1. Actions are limited only to records owned (referenced) by user. -1. When [Share Group Lock](group/index.md#share-with-group-lock) is enabled the project can't be shared with other groups. It does not affect group with group sharing. +1. When [Share Group Lock](group/index.md#prevent-a-project-from-being-shared-with-groups) is enabled the project can't be shared with other groups. It does not affect group with group sharing. 1. For information on eligible approvers for merge requests, see [Eligible approvers](project/merge_requests/merge_request_approvals.md#eligible-approvers). 1. Owner permission is only available at the group or personal namespace level (and for instance admins) and is inherited by its projects. @@ -293,6 +296,7 @@ group. | View Value Stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | View Billing **(FREE SAAS)** | | | | | ✓ (4) | | View Usage Quotas **(FREE SAAS)** | | | | | ✓ (4) | +| View 2FA status of members | | | | | ✓ | | Filter members by 2FA status | | | | | ✓ | | Administer project compliance frameworks | | | | | ✓ | @@ -301,9 +305,9 @@ group. 1. Introduced in GitLab 12.2. 1. Default project creation role can be changed at: - The [instance level](admin_area/settings/visibility_and_access_controls.md#default-project-creation-protection). - - The [group level](group/index.md#default-project-creation-level). + - The [group level](group/index.md#specify-who-can-add-projects-to-a-group). 1. Does not apply to subgroups. -1. Developers can push commits to the default branch of a new project only if the [default branch protection](group/index.md#changing-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". +1. Developers can push commits to the default branch of a new project only if the [default branch protection](group/index.md#change-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". 1. In addition, if your group is public or internal, all users who can see the group can also see group wiki pages. 1. Users can only view events based on their individual actions. diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 44bf97bdd42..69efe455c53 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -49,11 +49,13 @@ To enable 2FA: 1. Select **Enable Two-factor Authentication**. 1. **On your device (usually your phone):** 1. Install a compatible application, like: - - [Authenticator](https://mattrubin.me/authenticator/): open source app for iOS devices. - - [andOTP](https://github.com/andOTP/andOTP): feature rich open source app for Android which supports PGP encrypted backups. - - [FreeOTP](https://freeotp.github.io/): open source app for Android. - - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en): proprietary app for iOS and Android. - - [SailOTP](https://openrepos.net/content/seiichiro0185/sailotp): open source app for SailFish OS. + - [Authy](https://authy.com/) + - [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app) + - [LastPass](https://lastpass.com/auth/) + - [Authenticator](https://mattrubin.me/authenticator/) + - [andOTP](https://github.com/andOTP/andOTP) + - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en) + - [SailOTP](https://openrepos.net/content/seiichiro0185/sailotp) 1. In the application, add a new entry in one of two ways: - Scan the code presented in GitLab with your device's camera to add the entry automatically. @@ -159,7 +161,7 @@ have FortiToken configured in FortiToken Cloud. You'll also need a `client_id` and `client_secret` to configure FortiToken Cloud. To get these, see the `REST API Guide` at -[`Fortinet Document Library`](https://docs.fortinet.com/document/fortitoken-cloud/20.4.d/rest-api). +[`Fortinet Document Library`](https://docs.fortinet.com/document/fortitoken-cloud/latest/rest-api). First configure FortiToken Cloud in GitLab. On your GitLab server: diff --git a/doc/user/profile/img/busy_indicator_note_header_v13_9.png b/doc/user/profile/img/busy_indicator_note_header_v13_9.png Binary files differnew file mode 100644 index 00000000000..63301ebdc14 --- /dev/null +++ b/doc/user/profile/img/busy_indicator_note_header_v13_9.png diff --git a/doc/user/profile/img/busy_indicator_notes_v13_9.png b/doc/user/profile/img/busy_indicator_notes_v13_9.png Binary files differnew file mode 100644 index 00000000000..2efe075c72b --- /dev/null +++ b/doc/user/profile/img/busy_indicator_notes_v13_9.png diff --git a/doc/user/profile/img/busy_indicator_profile_page_v13_6.png b/doc/user/profile/img/busy_indicator_profile_page_v13_6.png Binary files differnew file mode 100644 index 00000000000..c8e969f38db --- /dev/null +++ b/doc/user/profile/img/busy_indicator_profile_page_v13_6.png diff --git a/doc/user/profile/img/busy_indicator_settings_menu_v13_6.png b/doc/user/profile/img/busy_indicator_settings_menu_v13_6.png Binary files differnew file mode 100644 index 00000000000..711638541dd --- /dev/null +++ b/doc/user/profile/img/busy_indicator_settings_menu_v13_6.png diff --git a/doc/user/profile/img/busy_indicator_sidebar_collapsed_v13_9.png b/doc/user/profile/img/busy_indicator_sidebar_collapsed_v13_9.png Binary files differnew file mode 100644 index 00000000000..3dca88ec8cc --- /dev/null +++ b/doc/user/profile/img/busy_indicator_sidebar_collapsed_v13_9.png diff --git a/doc/user/profile/img/busy_indicator_sidebar_v13_9.png b/doc/user/profile/img/busy_indicator_sidebar_v13_9.png Binary files differnew file mode 100644 index 00000000000..83024b319bf --- /dev/null +++ b/doc/user/profile/img/busy_indicator_sidebar_v13_9.png diff --git a/doc/user/profile/img/busy_indicator_user_popovers_v13_6.png b/doc/user/profile/img/busy_indicator_user_popovers_v13_6.png Binary files differnew file mode 100644 index 00000000000..16fb0e6556b --- /dev/null +++ b/doc/user/profile/img/busy_indicator_user_popovers_v13_6.png diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index d2cbf9e4acd..65d83c2b413 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -40,9 +40,9 @@ On your profile page, you can see the following information: - Contributed projects: [projects](../project/index.md) you contributed to - Personal projects: your personal projects (respecting the project's visibility level) - Starred projects: projects you starred -- Snippets: your personal code [snippets](../snippets.md#personal-snippets) -- Followers: people following you -- Following: people you are following +- Snippets: your personal code [snippets](../snippets.md) +- Followers: people [following](../index.md#user-activity) you +- Following: people you are [following](../index.md#user-activity) Profile page with active Following view: @@ -233,6 +233,26 @@ To set the busy status indicator, either: 1. Select **Edit profile**. 1. Select the **Busy** checkbox. + Once selected, you can see the busy status in various locations in the user interface. + + Username: + + | Profile page | Settings menu | User popovers | + | --- | --- | --- | + |  |  |  | + + Issue and merge request sidebar: + + | Sidebar| Collapsed sidebar | + | --- | --- | + |  |  | + + Notes: + + | Notes | Note headers | + | --- | --- | + |  |  | + ### Disable busy status feature The busy status feature is deployed behind a feature flag and is **enabled by default**. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 703154945db..4f28558cca6 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -206,7 +206,8 @@ epics: | Failed pipeline | The author of the pipeline | | Fixed pipeline ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1.) | The author of the pipeline. Enabled by default. | | Merge merge request | | -| Merge when pipeline succeeds ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211961) in GitLab 13.4) | | +| Merge when pipeline succeeds ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211961) in GitLab 13.4) | Author, Participants, Watchers, Subscribers, and Custom notification level with this event selected. `Note:` Custom notification level is ignored for Author, Watchers and Subscribers | +| Merge request [marked as ready](../project/merge_requests/drafts.md) (introduced in [GitLab 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/15332)) | Watchers and participants | | New comment | Participants, Watchers, Subscribers, and Custom notification level with this event selected, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | | New epic | | | New issue | | diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 99db0c4b898..d32971a7618 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -21,7 +21,7 @@ Personal access tokens expire on the date you define, at midnight UTC. - GitLab runs a check at 01:00 AM UTC every day to identify personal access tokens that expire in under seven days. The owners of these tokens are notified by email. - GitLab runs a check at 02:00 AM UTC every day to identify personal access tokens that expired on the current date. The owners of these tokens are notified by email. - In GitLab Ultimate, administrators may [limit the lifetime of personal access tokens](../admin_area/settings/account_and_limit_settings.md#limiting-lifetime-of-personal-access-tokens). -- In GitLab Ultimate, administrators may [toggle enforcement of personal access token expiry](../admin_area/settings/account_and_limit_settings.md#optional-enforcement-of-personal-access-token-expiry). +- In GitLab Ultimate, administrators may [toggle enforcement of personal access token expiration](../admin_area/settings/account_and_limit_settings.md#optional-non-enforcement-of-personal-access-token-expiration). For examples of how you can use a personal access token to authenticate with the API, see the following section from our [API Docs](../../api/README.md#personalproject-access-tokens). diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 464edf13a7e..78900e145b7 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -58,12 +58,10 @@ Dark mode is available as a navigation theme, for MVC and compatibility reasons. the future, we plan to make it configurable in its own section along with support for [different navigation themes](https://gitlab.com/gitlab-org/gitlab/-/issues/219512). -NOTE: Dark theme only works with the **Dark** syntax highlighting theme. ## Syntax highlighting theme -NOTE: GitLab uses the [rouge Ruby library](http://rouge.jneen.net/ "Rouge website") for syntax highlighting outside of any Editor context. The WebIDE (like Snippets) uses [Monaco Editor](https://microsoft.github.io/monaco-editor/) and it's provided @@ -88,11 +86,7 @@ The default syntax theme is White, and you can choose among 5 different themes:  -[Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in 13.0, the theme -you choose also applies to the [Web IDE](../project/web_ide/index.md)'s code editor and [Snippets](../snippets.md). -The themes are available only in the Web IDE file editor, except for the [dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/209808) and -the [Solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228), -which apply to the entire Web IDE screen. +Introduced in GitLab 13.6, the themes [Solarized](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) and [Monokai](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) also apply to the [Web IDE](../project/web_ide/index.md) and [Snippets](../snippets.md). ## Behavior @@ -114,12 +108,13 @@ select few, the amount of activity on the default Dashboard page can be overwhelming. Changing this setting allows you to redefine your default dashboard. -You have 8 options here that you can use for your default dashboard view: +You can include the following options for your default dashboard view: - Your projects (default) - Starred projects - Your projects' activity - Starred projects' activity +- Followed Users' Activity - Your groups - Your [To-Do List](../todos.md) - Assigned Issues diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index 8d8ff942d05..aa8c21fc781 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -15,25 +15,24 @@ Markdown fields. When you start typing a word in a Markdown field with one of the following characters, GitLab progressively autocompletes against a set of matching values. The string matching is not case sensitive. -| Character | Autocompletes | -| :-------- | :------------ | -| `~` | Labels | -| `%` | Milestones | -| `@` | Users and groups | -| `#` | Issues | -| `!` | Merge requests | -| `&` | Epics | -| `$` | Snippets | -| `:` | Emoji | -| `/` | Quick Actions | - -Up to 5 of the most relevant matches are displayed in a popup list. When you -select an item from the list, the value is entered in the field. The more -characters you enter, the more precise the matches are. +| Character | Autocompletes | Relevant matches shown | +| :-------- | :------------ | :---- | +| `~` | Labels | 20 | +| `%` | Milestones | 5 | +| `@` | Users and groups | 10 | +| `#` | Issues | 5 | +| `!` | Merge requests | 5 | +| `&` | Epics | 5 | +| `$` | Snippets | 5 | +| `:` | Emoji | 5 | +| `/` | Quick Actions | 100 | + +When you select an item from the list, the value is entered in the field. +The more characters you enter, the more precise the matches are. Autocomplete characters are useful when combined with [Quick Actions](quick_actions.md). -## Example +## User autocomplete Assume your GitLab instance includes the following users: @@ -49,17 +48,9 @@ Assume your GitLab instance includes the following users: <!-- vale gitlab.Spelling = YES --> -In an Issue comment, entering `@l` results in the following popup list -appearing. Note that user `shelba` is not included, because the list includes -only the 5 users most relevant to the Issue. - - - -If you continue to type, `@le`, the popup list changes to the following. The -popup now only includes users where `le` appears in their username, or a word in -their name. - - +User autocompletion sorts by the users whose username or name start with your query first. +For example, typing `@lea` shows `leanna` first and typing `@ros` shows `Rosemarie Rogahn` and `Rosy Grant` first. +Any usernames or names that include your query are shown afterwards in the autocomplete menu. You can also search across the full name to find a user. -To find `Rosy Grant`, even if their username is for example `hunter2`, you can type their full name without spaces like `@rosygrant`. +To find `Rosy Grant`, even if their username is for example `alessandra`, you can type their full name without spaces like `@rosygrant`. diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 7e6bba30001..783232ca7f9 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -19,7 +19,7 @@ project maintainers. ## Project badges -Badges can be added to a project by Maintainers or Owners, and will then be visible on the project's overview page. +Badges can be added to a project by Maintainers or Owners, and are visible on the project's overview page. If you find that you have to add the same badges to several projects, you may want to add them at the [group level](#group-badges). To add a new badge to a project: @@ -52,7 +52,7 @@ To add this badge to a project: ## Group badges -Badges can be added to a group and will then be visible on every project's +Badges can be added to a group and are visible on every project's overview page that's under that group. In this case, they cannot be edited or deleted on the project level. If you need to have individual badges for each project, consider adding them on the [project level](#project-badges) or use @@ -75,7 +75,7 @@ Badges directly associated with a project can be configured on the ## Placeholders The URL a badge points to, as well as the image URL, can contain placeholders -which will be evaluated when displaying the badge. The following placeholders +which are evaluated when displaying the badge. The following placeholders are available: - `%{project_path}`: Path of a project including the parent groups diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index eb6b8302667..e329ec4f903 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -140,13 +140,11 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 1. Click **Review policy**. 1. Enter a suitable name for this policy, and click **Create Policy**. You can now close this window. -1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an EKS management IAM role. - To do so, follow the [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) instructions - to create a IAM role suitable for managing the AWS EKS cluster's resources on your behalf. +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an **EKS IAM role** following the [Amazon EKS cluster IAM role instructions](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html). This role should exist so that Kubernetes clusters managed by Amazon EKS can make calls to other AWS services on your behalf to manage the resources that you use with the service. In addition to the policies that guide suggests, you must also include the `AmazonEKSClusterPolicy` policy for this role in order for GitLab to manage the EKS cluster correctly. -1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role: - 1. From the left panel, select **Roles**. +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create another IAM role which will be used by GitLab to authenticate with AWS. Follow these steps to create it: + 1. On the AWS IAM console, select **Roles** from the left panel. 1. Click **Create role**. 1. Under `Select type of trusted entity`, select **Another AWS account**. 1. Enter the Account ID from GitLab into the `Account ID` field. @@ -326,7 +324,7 @@ If a default Storage Class doesn't already exist and is desired, follow Amazon's to create one. Alternatively, disable PostgreSQL by setting the project variable -[`POSTGRES_ENABLED`](../../../topics/autodevops/customize.md#environment-variables) to `false`. +[`POSTGRES_ENABLED`](../../../topics/autodevops/customize.md#cicd-variables) to `false`. ### Deploy the app to EKS diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index d3d434762ab..aabda474043 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -58,7 +58,6 @@ Kubernetes version to any supported version at any time: - 1.17 (support ends on September 22, 2021) - 1.16 (support ends on July 22, 2021) - 1.15 (support ends on May 22, 2021) -- 1.14 (deprecated, support ends on December 22, 2020) Some GitLab features may support versions outside the range provided here. @@ -87,7 +86,7 @@ differentiates the new cluster from the rest. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables) work. +[environment-specific CI/CD variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables) work. The default environment scope is `*`, which means all jobs, regardless of their environment, use that cluster. Each scope can be used only by a single cluster @@ -201,7 +200,7 @@ To clear the cache: You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case is specified as part of the Knative installation. See [Installing Applications](#installing-applications). -Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an environment variable. +Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an deployment variable. If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain is used for the different stages. For example, Auto Review Apps and Auto Deploy. @@ -289,7 +288,7 @@ A Kubernetes cluster can be the destination for a deployment job. If the cluster from your jobs using tools such as `kubectl` or `helm`. - You don't use the GitLab cluster integration, you can still deploy to your cluster. However, you must configure Kubernetes tools yourself - using [environment variables](../../../ci/variables/README.md#custom-cicd-variables) + using [CI/CD variables](../../../ci/variables/README.md#custom-cicd-variables) before you can interact with the cluster from your jobs. ### Deployment variables @@ -313,9 +312,9 @@ following command in your deployment job script, for Kubernetes to access the re The Kubernetes cluster integration exposes these [deployment variables](../../../ci/variables/README.md#deployment-variables) in the GitLab CI/CD build environment to deployment jobs. Deployment jobs have -[defined a target environment](../../../ci/environments/index.md#defining-environments). +[defined a target environment](../../../ci/environments/index.md). -| Variable | Description | +| Deployment Variable | Description | |----------------------------|-------------| | `KUBE_URL` | Equal to the API URL. | | `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | @@ -346,14 +345,14 @@ You can customize the deployment namespace in a few ways: - For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`, but the user is responsible for ensuring its existence. You can fully customize this value using - [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configuring-kubernetes-deployments) + [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments) in `.gitlab-ci.yml`. When you customize the namespace, existing environments remain linked to their current namespaces until you [clear the cluster cache](#clearing-the-cluster-cache). WARNING: -By default, anyone who can create a deployment job can access any CI variable in +By default, anyone who can create a deployment job can access any CI/CD variable in an environment's deployment job. This includes `KUBECONFIG`, which gives access to any secret available to the associated service account in your cluster. To keep your production credentials safe, consider using @@ -407,7 +406,7 @@ deployments, replica sets, and pods are annotated with: - `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` `$CI_ENVIRONMENT_SLUG` and `$CI_PROJECT_PATH_SLUG` are the values of -the CI variables. +the CI/CD variables. You must be the project owner or have `maintainer` permissions to use terminals. Support is limited to the first container in the first pod of your environment. @@ -432,8 +431,8 @@ Reasons for failure include: - The token you gave GitLab does not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) privileges required by GitLab. -- Missing `KUBECONFIG` or `KUBE_TOKEN` variables. To be passed to your job, they must have a matching - [`environment:name`](../../../ci/environments/index.md#defining-environments). If your job has no +- Missing `KUBECONFIG` or `KUBE_TOKEN` deployment variables. To be passed to your job, they must have a matching + [`environment:name`](../../../ci/environments/index.md). If your job has no `environment:name` set, the Kubernetes credentials are not passed to it. NOTE: diff --git a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md index 0c4ec72ed5b..d64ebfd9385 100644 --- a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md @@ -15,7 +15,7 @@ applications through GMAv2 exclusively when using Container Network Security. The following steps are recommended to install and use Container Host Security through GitLab: 1. [Install at least one runner and connect it to GitLab](https://docs.gitlab.com/runner/). -1. [Create a group](../../../../group/#create-a-new-group). +1. [Create a group](../../../../group/#create-a-group). 1. [Connect a Kubernetes cluster to the group](../../add_remove_clusters.md). 1. [Create a cluster management project and associate it with the Kubernetes cluster](../../../../clusters/management_project.md). @@ -57,7 +57,7 @@ initial troubleshooting steps that resolve the most common problems: 1. If things still aren't working, a more assertive set of actions may help get things back to a good state: - - Stop and [delete the problematic environment](../../../../../ci/environments/#delete-environments-through-the-ui) + - Stop and [delete the problematic environment](../../../../../ci/environments/#delete-a-stopped-environment) in GitLab. - Delete the relevant namespace in Kubernetes by running `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster. diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index e530f0dfcda..14db98c7ce7 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -15,7 +15,7 @@ applications through GMAv2 exclusively when using Container Network Security. The following steps are recommended to install and use Container Network Security through GitLab: 1. [Install at least one runner and connect it to GitLab](https://docs.gitlab.com/runner/). -1. [Create a group](../../../../group/#create-a-new-group). +1. [Create a group](../../../../group/#create-a-group). 1. [Connect a Kubernetes cluster to the group](../../add_remove_clusters.md). 1. [Create a cluster management project and associate it with the Kubernetes cluster](../../../../clusters/management_project.md). @@ -131,7 +131,7 @@ initial troubleshooting steps that resolve the most common problems: 1. If things still aren't working, a more assertive set of actions may help get things back into a good state: - - Stop and [delete the problematic environment](../../../../../ci/environments/index.md#delete-environments-through-the-ui) in GitLab. + - Stop and [delete the problematic environment](../../../../../ci/environments/index.md#delete-a-stopped-environment) in GitLab. - Delete the relevant namespace in Kubernetes by running `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster. - Rerun the application project pipeline to redeploy the application. diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 192a7c7cd39..f78fb2ed1ef 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -367,12 +367,11 @@ sam init -h ### Setting up your AWS credentials with your GitLab account In order to interact with your AWS account, the GitLab CI/CD pipelines require both -`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be set in the project's CI/CD -variables. +`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be set in the project's CI/CD variables. To set these: -1. Navigate to the project's **Settings > CI / CD**. +1. Navigate to the project's **Settings > CI/CD**. 1. Expand the **Variables** section and create entries for `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. 1. Mask the credentials so they do not show in logs using the **Masked** toggle. @@ -424,8 +423,8 @@ deploys your application. If your: - Incompatible versions of software. For example, Python runtime version might be different from the Python on the build machine. Address this by installing the required versions of the software. - - You may not be able to access your AWS account from GitLab. Check the environment - variables you set up with AWS credentials. + - You may not be able to access your AWS account from GitLab. Check the CI/CD variables + you set up with AWS credentials. - You may not have permission to deploy a serverless application. Make sure you provide all required permissions to deploy a serverless application. diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index c7ed8d6d2a5..0f7f5e23e59 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -90,7 +90,7 @@ memory. **RBAC must be enabled.** NOTE: Running `kubectl` commands on your cluster requires setting up access to the cluster first. For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl), - for other platforms [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + for other platforms [Install kubectl](https://kubernetes.io/docs/tasks/tools/). 1. The Ingress is now available at this address and routes incoming requests to the proper service based on the DNS name in the request. To support this, a wildcard DNS record should be created for the desired domain name. For example, @@ -396,7 +396,7 @@ kubectl create secret generic my-secrets -n "$KUBE_NAMESPACE" --from-literal MY_ #### Part of deployment job -You can extend your `.gitlab-ci.yml` to create the secrets during deployment using the [environment variables](../../../../ci/variables/README.md) +You can extend your `.gitlab-ci.yml` to create the secrets during deployment using the [CI/CD variables](../../../../ci/variables/README.md) stored securely under your GitLab project. ```yaml @@ -521,7 +521,7 @@ Running `kubectl` commands on your cluster requires setting up access to the cluster first. For clusters created on: - GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl) -- Other platforms, see [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). +- Other platforms, see [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/). ### Enable request log template @@ -769,7 +769,7 @@ or with other versions of Python. Running `kubectl` commands on your cluster requires setting up access to the cluster first. For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl). - For other platforms, [install `kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + For other platforms, [install `kubectl`](https://kubernetes.io/docs/tasks/tools/). ```shell kubectl create --namespace istio-system secret tls istio-ingressgateway-certs \ diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 0e8c1bf8f4d..f1071af7c1f 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -19,10 +19,13 @@ Code Intelligence is built into GitLab and powered by [LSIF](https://lsif.dev/) (Language Server Index Format), a file format for precomputed code intelligence data. +NOTE: +You can automate this feature in your applications by using [Auto DevOps](../../topics/autodevops/index.md). + ## Configuration Enable code intelligence for a project by adding a GitLab CI/CD job to the project's -`.gitlab-ci.yml` which will generate the LSIF artifact: +`.gitlab-ci.yml` which generates the LSIF artifact: ```yaml code_navigation: diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 72695580d9d..368417ac00b 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -16,6 +16,10 @@ of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use without any need to access Kubernetes. +NOTE: +If you have a Kubernetes cluster, you can Auto Deploy applications to production +environments by using [Auto DevOps](../../topics/autodevops/index.md). + ## Overview With Deploy Boards you can gain more insight into deploys with benefits such as: @@ -71,7 +75,7 @@ specific environment, there are a lot of use cases. To name a few: To display the Deploy Boards for a specific [environment](../../ci/environments/index.md) you should: -1. Have [defined an environment](../../ci/environments/index.md#defining-environments) with a deploy stage. +1. Have [defined an environment](../../ci/environments/index.md) with a deploy stage. 1. Have a Kubernetes cluster up and running. @@ -86,11 +90,11 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ [`kubernetes`](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. 1. Configure the [Kubernetes integration](clusters/index.md) in your project for the cluster. The Kubernetes namespace is of particular note as you need it - for your deployment scripts (exposed by the `KUBE_NAMESPACE` environment variable). + for your deployment scripts (exposed by the `KUBE_NAMESPACE` deployment variable). 1. Ensure Kubernetes annotations of `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` and `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` are applied to the deployments, replica sets, and pods, where `$CI_ENVIRONMENT_SLUG` and - `$CI_PROJECT_PATH_SLUG` are the values of the CI variables. This is so we can + `$CI_PROJECT_PATH_SLUG` are the values of the CI/CD variables. This is so we can lookup the proper environment in a cluster/namespace which may have more than one. These resources should be contained in the namespace defined in the Kubernetes service setting. You can use an [Auto deploy](../../topics/autodevops/stages.md#auto-deploy) `.gitlab-ci.yml` @@ -159,6 +163,6 @@ version of your application. ## Further reading - [GitLab Auto deploy](../../topics/autodevops/stages.md#auto-deploy) -- [GitLab CI/CD environment variables](../../ci/variables/README.md) +- [GitLab CI/CD variables](../../ci/variables/README.md) - [Environments and deployments](../../ci/environments/index.md) - [Kubernetes deploy example](https://gitlab.com/gitlab-examples/kubernetes-deploy) diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 6f05c40eefc..8606ce36a82 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -10,7 +10,7 @@ type: howto > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17894) in GitLab 10.7. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** in GitLab 12.9. > - [Added `write_registry` scope](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI / CD** in GitLab 12.10.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI/CD** in GitLab 12.10.1. > - [Added package registry scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. Deploy tokens allow you to download (`git clone`) or push and pull packages and @@ -20,7 +20,7 @@ Deploy tokens can be managed by [maintainers only](../../permissions.md). Deploy tokens cannot be used with the GitLab API. -If you have a key pair, you might want to use [deploy keys](../../../ssh/README.md#deploy-keys) +If you have a key pair, you might want to use [deploy keys](../../project/deploy_keys/index.md) instead. ## Creating a Deploy Token @@ -130,6 +130,22 @@ To pull packages in the GitLab package registry, you must: 1. For the [package type of your choice](../../packages/index.md), follow the authentication instructions for deploy tokens. +Example request publishing a generic package using a deploy token: + +```shell +curl --header "DEPLOY-TOKEN: <deploy_token>" \ + --upload-file path/to/file.txt \ + "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?status=hidden" +``` + +Example response: + +```json +{ + "message":"201 Created" +} +``` + ### Push or upload packages > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. @@ -169,7 +185,7 @@ apply consistently when cloning the repository of related projects. There's a special case when it comes to Deploy Tokens. If a user creates one named `gitlab-deploy-token`, the username and token of the Deploy Token is -automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` +automatically exposed to the CI/CD jobs as CI/CD variables: `CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD`, respectively. After you create the token, you can sign in to the Container Registry by using @@ -180,7 +196,6 @@ docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY ``` NOTE: -The special handling for the `gitlab-deploy-token` deploy token is not currently -implemented for group deploy tokens. For the deploy token to be available for -CI/CD jobs, it must be created at the project level. For details, see -[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214014). +The special handling for the `gitlab-deploy-token` deploy token is not +implemented for group deploy tokens. To make the group-level deploy token available for +CI/CD jobs, use the workaround in [issue 214014](https://gitlab.com/gitlab-org/gitlab/-/issues/214014). diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index c56470ee07a..e3fa7ca6dc0 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -37,10 +37,10 @@ To learn how to create templates for various file types in groups, visit images guidelines, link to the related issue, reviewer name, and so on. - You can also create issues and merge request templates for different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. -- You can use an [issue description template](#creating-issue-templates) as a +- You can use an [issue description template](#create-an-issue-template) as a [Service Desk email template](service_desk.md#new-service-desk-issues). -## Creating issue templates +## Create an issue template Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/` directory in your repository. Commit and push to your default branch. @@ -65,13 +65,13 @@ To create the `.gitlab/issue_templates` directory: To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue) and see if you can choose a description template. -## Creating merge request templates +## Create a merge request template Similarly to issue templates, create a new Markdown (`.md`) file inside the `.gitlab/merge_request_templates/` directory in your repository. Commit and push to your default branch. -## Using the templates +## Use the templates Let's take for example that you've created the file `.gitlab/issue_templates/Bug.md`. This enables the `Bug` dropdown option when creating or editing issues. When @@ -85,9 +85,45 @@ For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_templat  -## Setting a default template for merge requests and issues **(PREMIUM)** +### Set an issue and merge request description template at group level **(PREMIUM)** -> - Moved to GitLab Premium in 13.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled by default on GitLab.com. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to + [enable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). + +Templates can be useful because you can create a template once and use it multiple times. +To re-use templates [you've created](../project/description_templates.md#create-an-issue-template): + +1. Go to the group's **Settings > General > Templates**. +1. From the dropdown, select your template project as the template repository at group level. + + + +### Set an issue and merge request description template at instance level **(PREMIUM ONLY)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled by default on GitLab.com. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to + [enable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). + +Similar to group templates, issue and merge request templates can also be set up at the instance level. +This results in those templates being available in all projects within the instance. +Only instance administrators can set instance-level templates. + +To set the instance-level description template repository: + +1. Select the **Admin Area** icon (**{admin}**). +1. Go to **Settings > Templates**. +1. From the dropdown, select your template project as the template repository at instance level. + +Learn more about [instance template repository](../admin_area/settings/instance_template_repository.md). + + + +### Set a default template for merge requests and issues **(PREMIUM)** The visibility of issues or merge requests should be set to either "Everyone with access" or "Only Project Members" in your project's **Settings / Visibility, project features, permissions** section, otherwise the @@ -110,6 +146,10 @@ After you add the description, hit **Save changes** for the settings to take effect. Now, every time a new merge request or issue is created, it is pre-filled with the text you entered in the template(s). +[GitLab versions 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/885) +provide `issues_template` and `merge_requests_template` attributes in the +[Projects API](../../api/projects.md) to help you keep your templates up to date. + ## Description template example We make use of description templates for issues and merge requests in the GitLab project. @@ -159,3 +199,28 @@ it's very hard to read otherwise.) /cc @project-manager /assign @qa-tester ``` + +## Enable or disable issue and merge request description templates at group and instance level + +Setting issue and merge request description templates at group and instance levels +is under development and not ready for production use. It is deployed behind a +feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:inherited_issuable_templates) +``` + +To disable it: + +```ruby +Feature.disable(:inherited_issuable_templates) +``` + +The feature flag affects these features: + +- Setting a templates project as issue and merge request description templates source at group level. +- Setting a templates project as issue and merge request description templates source at instance level. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 5c24ec6caf6..4edb6fbdad9 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -36,9 +36,9 @@ GitLab supports two different modes of file locking: Locks can be created by any person who has at least [Developer permissions](../permissions.md) to the repository. -Only the user who locked the file or directory can edit locked files. Others -users will be prevented from modifying locked files by pushing, merging, -or any other means, and will be shown an error like: `The path '.gitignore' is +Only the user who locked the file or directory can edit locked files. Other +users are prevented from modifying locked files by pushing, merging, +or any other means, and are shown an error like: `The path '.gitignore' is locked by Administrator`. ## Exclusive file locks **(FREE)** @@ -60,7 +60,7 @@ Before getting started, make sure you have [Git LFS installed](../../topics/git/ git-lfs --version ``` -If it doesn't recognize this command, you'll have to install it. There are +If it doesn't recognize this command, you must install it. There are several [installation methods](https://git-lfs.github.com/) that you can choose according to your OS. To install it with Homebrew: @@ -70,7 +70,7 @@ brew install git-lfs Once installed, **open your local repository in a terminal window** and install Git LFS in your repository. If you're sure that LFS is already installed, -you can skip this step. If you're unsure, re-installing it won't do any harm: +you can skip this step. If you're unsure, re-installing it does no harm: ```shell git lfs install @@ -84,14 +84,14 @@ You need [Maintainer permissions](../permissions.md) to configure Exclusive File Locks for your project through the command line. The first thing to do before using File Locking is to tell Git LFS which -kind of files are lockable. The following command will store PNG files +kind of files are lockable. The following command stores PNG files in LFS and flag them as lockable: ```shell git lfs track "*.png" --lockable ``` -After executing the above command a file named `.gitattributes` will be +After executing the above command a file named `.gitattributes` is created or updated with the following content: ```shell @@ -110,9 +110,9 @@ implements the LFS File Locking API). To do that you can edit the The `.gitattributes` file is key to the process and **must** be pushed to the remote repository for the changes to take effect. -After a file type has been registered as lockable, Git LFS will make -them read-only on the file system automatically. This means you will -need to **lock the file** before [editing it](#edit-lockable-files). +After a file type has been registered as lockable, Git LFS makes +them read-only on the file system automatically. This means you +must **lock the file** before [editing it](#edit-lockable-files). ### Lock files @@ -168,7 +168,7 @@ git lfs locks The output lists the locked files followed by the user who locked each of them and the files' IDs. -On the repository file tree, GitLab will display an LFS badge for files +On the repository file tree, GitLab displays an LFS badge for files tracked by Git LFS plus a padlock icon on exclusively-locked files:  @@ -176,7 +176,7 @@ tracked by Git LFS plus a padlock icon on exclusively-locked files: You can also [view and remove existing locks](#view-and-remove-existing-locks) from the GitLab UI. NOTE: -When you rename an exclusively-locked file, the lock is lost. You'll have to +When you rename an exclusively-locked file, the lock is lost. You must lock it again to keep it locked. ### Edit lockable files @@ -204,7 +204,7 @@ or higher tiers. Default branch file and directory locks only apply to the default branch set in the project's settings (usually `master`). -Changes to locked files on the default branch will be blocked, including merge +Changes to locked files on the default branch are blocked, including merge requests that modify locked files. Unlock the file to allow changes. ### Lock a file or a directory @@ -216,10 +216,10 @@ To lock a file:  -An **Unlock** button will be displayed if the file is already locked, and -will be disabled if you do not have permission to unlock the file. +An **Unlock** button is displayed if the file is already locked, and +is disabled if you do not have permission to unlock the file. -If you did not lock the file, hovering your cursor over the button will show +If you did not lock the file, hovering your cursor over the button shows who locked the file. ### View and remove existing locks diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 2806f6e48d1..11d1db195e1 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -17,7 +17,7 @@ directory of your repository and push it to the default branch of your project. ## Encoding Requirements The `.gitattributes` file _must_ be encoded in UTF-8 and _must not_ contain a -Byte Order Mark. If a different encoding is used, the file's contents will be +Byte Order Mark. If a different encoding is used, the file's contents are ignored. ## Syntax Highlighting diff --git a/doc/user/project/img/autocomplete_characters_example1_v12_0.png b/doc/user/project/img/autocomplete_characters_example1_v12_0.png Binary files differdeleted file mode 100644 index 9c6fa923b80..00000000000 --- a/doc/user/project/img/autocomplete_characters_example1_v12_0.png +++ /dev/null diff --git a/doc/user/project/img/autocomplete_characters_example2_v12_0.png b/doc/user/project/img/autocomplete_characters_example2_v12_0.png Binary files differdeleted file mode 100644 index b2e8a782a0b..00000000000 --- a/doc/user/project/img/autocomplete_characters_example2_v12_0.png +++ /dev/null diff --git a/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png b/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png Binary files differdeleted file mode 100644 index fc2893aa4d5..00000000000 --- a/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png +++ /dev/null diff --git a/doc/user/project/img/code_owners_approval_new_protected_branch_v13_10.png b/doc/user/project/img/code_owners_approval_new_protected_branch_v13_10.png Binary files differnew file mode 100644 index 00000000000..ee4ee2c6d71 --- /dev/null +++ b/doc/user/project/img/code_owners_approval_new_protected_branch_v13_10.png diff --git a/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png b/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png Binary files differdeleted file mode 100644 index 59da6874d14..00000000000 --- a/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png +++ /dev/null diff --git a/doc/user/project/img/code_owners_approval_protected_branch_v13_10.png b/doc/user/project/img/code_owners_approval_protected_branch_v13_10.png Binary files differnew file mode 100644 index 00000000000..220eb207132 --- /dev/null +++ b/doc/user/project/img/code_owners_approval_protected_branch_v13_10.png diff --git a/doc/user/project/img/issue_boards_remove_issue_v13_6.png b/doc/user/project/img/issue_boards_remove_issue_v13_6.png Binary files differdeleted file mode 100644 index c980759ad0c..00000000000 --- a/doc/user/project/img/issue_boards_remove_issue_v13_6.png +++ /dev/null diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index c135b1be54a..eb426a9f126 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -49,8 +49,9 @@ The steps you take depend on whether you are importing from GitHub.com or GitHub [GitHub Rake task](../../../administration/raketasks/github_import.md) to import projects without the constraints of a [Sidekiq](../../../development/sidekiq_style_guide.md) worker. - If you're importing from GitHub Enterprise to your self-managed GitLab instance, you must first enable - [GitHub integration](../../../integration/github.md). However, you cannot import projects from GitHub Enterprise to GitLab.com. -- If you're importing from GitHub.com to your self-managed GitLab instance, you do not need to set up GitHub integration. + [GitHub integration](../../../integration/github.md). + - To import projects from GitHub Enterprise to GitLab.com, use the [Import API](../../../api/import.md). +- If you're importing from GitHub.com to your self-managed GitLab instance, you do not need to set up GitHub integration. You can use the [Import API](../../../api/import.md). ## How it works @@ -62,7 +63,7 @@ must meet one of the following conditions prior to the import: - Have previously logged in to a GitLab account using the GitHub icon. - Have a GitHub account with a publicly visible - [primary email address](https://docs.github.com/en/free-pro-team@latest/rest/reference/users#get-a-user) + [primary email address](https://docs.github.com/en/rest/reference/users#get-a-user) on their profile that matches their GitLab account's primary or secondary email address. If a user referenced in the project is not found in the GitLab database, the project creator (typically the user @@ -91,7 +92,7 @@ Before you begin, ensure that any GitHub users who you want to map to GitLab use - A GitLab account that has logged in using the GitHub icon \- or - -- A GitLab account with an email address that matches the [publicly visible email address](https://docs.github.com/en/free-pro-team@latest/rest/reference/users#get-a-user) in the profile of the GitHub user +- A GitLab account with an email address that matches the [publicly visible email address](https://docs.github.com/en/rest/reference/users#get-a-user) in the profile of the GitHub user User-matching attempts occur in that order, and if a user is not identified either way, the activity is associated with the user account that is performing the import. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index a8ab1cbbb63..7e5801a2382 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -154,9 +154,7 @@ There are numerous [APIs](../../api/README.md) to use with your projects: - [Aliases](../../api/project_aliases.md) - [DORA4 Analytics](../../api/dora4_project_analytics.md) -## DORA4 analytics overview **(ULTIMATE ONLY)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab [Ultimate](https://about.gitlab.com/pricing/) 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). +## DORA4 analytics overview Project details include the following analytics: diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index fb9314f7504..3b012ab4430 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Atlassian Bamboo CI Service +# Atlassian Bamboo CI Service **(FREE)** GitLab provides integration with Atlassian Bamboo for continuous integration. When configured, pushes to a project trigger a build in Bamboo automatically. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 4e2ee9b3662..7e14515d98e 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Bugzilla Service +# Bugzilla Service **(FREE)** Navigate to the [Integrations page](overview.md#accessing-integrations), select the **Bugzilla** service and fill in the required details as described diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 143f0e2a25d..9cc4e980212 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Custom Issue Tracker service +# Custom Issue Tracker service **(FREE)** To enable the Custom Issue Tracker integration in a project: diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 8e0a167a968..624c0252f23 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Discord Notifications service +# Discord Notifications service **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22684) in GitLab 11.6. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 2274913d349..4970e20974b 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Enabling emails on push +# Enabling emails on push **(FREE)** By enabling this service, you receive email notifications for every change that is pushed to your project. diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 5ef36ff4074..1c0309cab87 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -20,7 +20,7 @@ and is automatically configured on [GitHub import](../../../integration/github.m ### Complete these steps on GitHub -This integration requires a [GitHub API token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) +This integration requires a [GitHub API token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with `repo:status` access granted: 1. Go to your "Personal access tokens" page at <https://github.com/settings/tokens> diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 06dcca6eb44..d0efebd4da7 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Hangouts Chat service +# Hangouts Chat service **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43756) in GitLab 11.2. diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md index 7b90d8d7cfd..f66fc0a0f6a 100644 --- a/doc/user/project/integrations/hipchat.md +++ b/doc/user/project/integrations/hipchat.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Atlassian HipChat +# Atlassian HipChat **(FREE)** GitLab provides a way to send HipChat notifications upon a number of events, such as when a user pushes code, creates a branch or tag, adds a comment, and diff --git a/doc/user/project/integrations/img/mattermost_config_help.png b/doc/user/project/integrations/img/mattermost_config_help.png Binary files differdeleted file mode 100644 index dd3481bc1f6..00000000000 --- a/doc/user/project/integrations/img/mattermost_config_help.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_console_integrations.png b/doc/user/project/integrations/img/mattermost_console_integrations.png Binary files differdeleted file mode 100644 index 625b57d4dc9..00000000000 --- a/doc/user/project/integrations/img/mattermost_console_integrations.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_goto_console.png b/doc/user/project/integrations/img/mattermost_goto_console.png Binary files differdeleted file mode 100644 index 8bacbe485f4..00000000000 --- a/doc/user/project/integrations/img/mattermost_goto_console.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_slash_command_configuration.png b/doc/user/project/integrations/img/mattermost_slash_command_configuration.png Binary files differdeleted file mode 100644 index f9e9de439ca..00000000000 --- a/doc/user/project/integrations/img/mattermost_slash_command_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_slash_command_token.png b/doc/user/project/integrations/img/mattermost_slash_command_token.png Binary files differdeleted file mode 100644 index c38f37c203c..00000000000 --- a/doc/user/project/integrations/img/mattermost_slash_command_token.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_team_integrations.png b/doc/user/project/integrations/img/mattermost_team_integrations.png Binary files differdeleted file mode 100644 index c2b68256e11..00000000000 --- a/doc/user/project/integrations/img/mattermost_team_integrations.png +++ /dev/null diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 0e5163e992a..5628a9bc5e5 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project integrations +# Project integrations **(FREE)** You can find the available integrations under your project's **Settings > Integrations** page. You need to have at least diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 58f7ea3279f..e75561b3ddb 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Irker IRC Gateway +# Irker IRC Gateway **(FREE)** GitLab provides a way to push update messages to an Irker server. When configured, pushes to a project trigger the service to send data directly diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 5857c3da803..0878e1c9386 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Jira integration +# GitLab Jira integration **(FREE)** You can use Jira to track work implemented in GitLab. The Jira integration with GitLab makes the process of working across these systems more efficient. diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index e9f30f32308..8e25af3f884 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Create an API token in Jira on Atlassian cloud +# Create an API token in Jira on Atlassian cloud **(FREE)** For [integrations with Jira](jira.md), an API token is needed when integrating with Jira on Atlassian cloud. To create an API token: diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 6a1529f001a..6b938238320 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Jira integrations +# Jira integrations **(FREE)** GitLab can be integrated with [Jira](https://www.atlassian.com/software/jira). diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 5bb17388a1e..b1ab2076dc0 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Create Jira Server username and password +# Create Jira Server username and password **(FREE)** For [integrations with Jira](jira.md), you must create a user account in Jira to have access to all projects that need to integrate with GitLab. diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index db190f47b01..6a93fc0fb06 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Mattermost Notifications Service +# Mattermost Notifications Service **(FREE)** The Mattermost Notifications Service allows your GitLab project to send events (e.g., `issue created`) to your existing Mattermost team as notifications. This requires configurations in both Mattermost and GitLab. diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 6c8a0ded2ae..20f5b73b37c 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -4,118 +4,121 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Mattermost slash commands +# Mattermost slash commands **(FREE)** -> Introduced in GitLab 8.14 +If your team uses [Mattermost](https://mattermost.com/) as a chat service, you can +integrate GitLab commands into Mattermost chat. This integration enables users to +run common operations, such as creating a GitLab issue, from the Mattermost chat +environment. -Mattermost commands give users an extra interface to perform common operations -from the chat environment. This allows one to, for example, create an issue as -soon as the idea was discussed in Mattermost. - -GitLab can also send events (e.g., `issue created`) to Mattermost as notifications. -This is the separately configured [Mattermost Notifications Service](mattermost.md). +GitLab can also send events (such as `issue created`) to Mattermost as part of the +separately configured [Mattermost Notifications Service](mattermost.md). ## Prerequisites -Mattermost 3.4 and up is required. +Mattermost [3.4 or later](https://mattermost.com/blog/category/releases/) is required. +GitLab provides different methods of configuring Mattermost slash commands, depending +on your configuration: -If you have the Omnibus GitLab package installed, Mattermost is already bundled -in it. All you have to do is configure it. Read more in the -[Omnibus GitLab Mattermost documentation](https://docs.gitlab.com/omnibus/gitlab-mattermost/). +- **Omnibus GitLab installations**: Mattermost is bundled with + [Omnibus GitLab](https://docs.gitlab.com/omnibus/). To configure Mattermost for Omnibus GitLab, read the + [Omnibus GitLab Mattermost documentation](https://docs.gitlab.com/omnibus/gitlab-mattermost/). +- **If Mattermost is installed on the same server as GitLab**, use the + [automated configuration](#automated-configuration). +- **For all other installations**, use the [manual configuration](#manual-configuration). ## Automated configuration If Mattermost is installed on the same server as GitLab, the configuration process can be done for you by GitLab. -Go to the Mattermost Slash Command service on your project and click the 'Add to Mattermost' button. +Go to the Mattermost Slash Command service on your project and click **Add to Mattermost** button. ## Manual configuration -The configuration consists of two parts. First you need to enable the slash -commands in Mattermost and then enable the service in GitLab. - -### Step 1. Enable custom slash commands in Mattermost - -This step is only required when using a source install. Omnibus installs are -preconfigured with the right settings. - -The first thing to do in Mattermost is to enable custom slash commands from -the administrator console. - -1. Log in with an account that has administrator privileges and navigate to the system - console. - -  - -1. Click **Integration Management** and set **Enable Custom Slash Commands**, - **Enable integrations to override usernames**, and **Enable - integrations to override profile picture icons** to true +To manually configure slash commands in Mattermost, you must: -  +1. [Enable custom slash commands](#enable-custom-slash-commands) in Mattermost. +1. [Get configuration values](#get-configuration-values-from-gitlab) from GitLab. +1. [Create a new slash command](#create-a-slash-command) in Mattermost. +1. [Provide the Mattermost token](#provide-the-mattermost-token-to-gitlab) to GitLab. -1. Click **Save** at the bottom to save the changes. +### Enable custom slash commands -### Step 2. Open the Mattermost slash commands service in GitLab +NOTE: +Omnibus GitLab installations are preconfigured. This step is required only for +installations from source. -1. Open a new tab for GitLab, go to your project's - [Integrations page](overview.md#accessing-integrations) - and select the **Mattermost command** service to configure it. - A screen appears with all the values you need to copy in Mattermost as - described in the next step. Leave the window open. +To enable custom slash commands from the Mattermost administrator console: - NOTE: - GitLab offers some values for the Mattermost settings. Only **Request URL** is required - as offered, all the others are just suggestions. +1. Sign in to Mattermost as a user with administrator privileges. +1. Next to your username, click the **{ellipsis_v}** **Settings** icon, and + select **System Console**. +1. Select **Integration Management**, and set these values to `TRUE`: + - **Enable Custom Slash Commands** + - **Enable integrations to override usernames** + - **Enable integrations to override profile picture icons** +1. Click **Save**, but do not close this browser tab, because you need it in + a later step. -  +### Get configuration values from GitLab -1. Proceed to the next step and create a slash command in Mattermost with the - above values. +After you enable custom slash commands in Mattermost, you need configuration +information from GitLab. To get this information: -### Step 3. Create a new custom slash command in Mattermost +1. In a different browser tab than your current Mattermost session, sign in to + GitLab as a user with [administrator permissions](../../permissions.md). +1. In the top navigation bar, go to **{admin}** **Admin Area**. +1. In the left menu, go to **Settings > Integrations** and select + **Mattermost slash commands**. +1. GitLab displays potential values for Mattermost settings. Copy the **Request URL** + as you need it for the next step. All other values are suggestions. +1. Do not close this browser tab, because you need it in future steps. -Now that you have enabled custom slash commands in Mattermost and opened -the Mattermost slash commands service in GitLab, it's time to copy these values -in a new slash command. +Next, create a slash command in Mattermost with the values from GitLab. -1. Back to Mattermost, under your team page settings, you should see the - **Integrations** option. +### Create a slash command -  +To create a slash command, you need the values you obtained from GitLab in +the previous step: -1. Go to the **Slash Commands** integration and add a new one by clicking the - **Add Slash Command** button. +1. In the Mattermost tab you left open when you + [enabled custom slash commands](#enable-custom-slash-commands), go to your + team page. +1. Click the **{ellipsis_v}** **Settings** icon, and select **Integrations**. +1. In the left menu, select **Slash commands**. +1. Click **Add Slash Command**:  - -1. Fill in the options for the custom command as described in - [step 2](#step-2-open-the-mattermost-slash-commands-service-in-gitlab). - - NOTE: - If you plan on connecting multiple projects, pick a slash command trigger - word that relates to your projects such as `/gitlab-project-name` or even - just `/project-name`. Only use `/gitlab` if you plan to only connect a single - project to your Mattermost team. - -  - -1. After you set up all the values, copy the token (we use it below) and - click **Done**. - -  - -### Step 4. Copy the Mattermost token into the Mattermost slash command service - -1. In GitLab, paste the Mattermost token you copied in the previous step and +1. Provide a **Display Name** and **Description** for your new command. +1. Provide a **Command Trigger Word** according to your application's configuration: + + - **If you intend to only connect one project to your Mattermost team**: Use + `/gitlab` for your trigger word. + - **If you intend to connect multiple projects**: Use a trigger word that relates + to your project, such as `/project-name` or `/gitlab-project-name`. +1. For **Request URL**, provide the value you copied from GitLab when you + [viewed configuration values](#get-configuration-values-from-gitlab). +1. For all other values, you may use the suggestions from GitLab or use your + preferred values. +1. Copy the **Token** value, as you need it in a later step, and click **Done**. + +### Provide the Mattermost token to GitLab + +When you create a new slash command in Mattermost, it generates a token you must +provide to GitLab: + +1. In the GitLab browser tab from + [getting configuration values from GitLab](#get-configuration-values-from-gitlab), + select the **Active** check box to enable this configuration. +1. In the **Token** field, paste the token you obtained from Mattermost. ensure that the **Active** toggle is enabled.  1. Click **Save changes** for the changes to take effect. -You are now set to start using slash commands in Mattermost that talk to the -GitLab project you configured. +Your slash command can now communicate with your GitLab project. ## Authorizing Mattermost to interact with GitLab @@ -132,7 +135,7 @@ GitLab using the Mattermost commands. ## Available slash commands -The available slash commands are: +The available slash commands for Mattermost are: | Command | Description | Example | | ------- | ----------- | ------- | @@ -152,7 +155,7 @@ the [permissions you have on the project](../../permissions.md#project-members-p ## Troubleshooting -If an event is not being triggered, confirm that the channel you're using is a public one, as +If an event is not being triggered, confirm that the channel you're using is a public one. Mattermost webhooks do not have access to private channels. If a private channel is required, you can edit the webhook's channel in Mattermost and diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 136da05d0e8..41e0938fc3b 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Microsoft Teams service +# Microsoft Teams service **(FREE)** ## On Microsoft Teams diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 18f0ad6b275..934510fd155 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Mock CI Service +# Mock CI Service **(FREE)** **NB: This service is only listed if you are in a development environment!** diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index b22a7c0295e..f6590b6ba2f 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Integrations +# Integrations **(FREE)** Integrations allow you to integrate GitLab with other applications. They are a bit like plugins in that they allow a lot of freedom in adding diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 4a88010a343..04abb922175 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -6,31 +6,38 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Monitoring AWS resources **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 - -GitLab has support for automatically detecting and monitoring AWS resources, starting with the [Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/). This is provided by leveraging the official [Cloudwatch exporter](https://github.com/prometheus/cloudwatch_exporter), which translates [Cloudwatch metrics](https://aws.amazon.com/cloudwatch/) into a Prometheus readable form. +GitLab supports automatically detecting and monitoring AWS resources, starting +with the [Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/) (ELB). +This is provided by leveraging the official [Cloudwatch exporter](https://github.com/prometheus/cloudwatch_exporter), which translates [Cloudwatch metrics](https://aws.amazon.com/cloudwatch/) into +a Prometheus readable form. ## Requirements -The [Prometheus service](../prometheus.md) must be enabled. +You must enable the [Prometheus service](../prometheus.md). -## Metrics supported +## Supported metrics -| Name | Query | -| ---- | ----- | +| Name | Query | +|----------------------|-------| | Throughput (req/sec) | `sum(aws_elb_request_count_sum{%{environment_filter}}) / 60` | -| Latency (ms) | `avg(aws_elb_latency_average{%{environment_filter}}) * 1000` | -| HTTP Error Rate (%) | `sum(aws_elb_httpcode_backend_5_xx_sum{%{environment_filter}}) / sum(aws_elb_request_count_sum{%{environment_filter}})` | +| Latency (ms) | `avg(aws_elb_latency_average{%{environment_filter}}) * 1000` | +| HTTP Error Rate (%) | `sum(aws_elb_httpcode_backend_5_xx_sum{%{environment_filter}}) / sum(aws_elb_request_count_sum{%{environment_filter}})` | ## Configuring Prometheus to monitor for Cloudwatch metrics -To get started with Cloudwatch monitoring, you should install and configure the [Cloudwatch exporter](https://github.com/prometheus/cloudwatch_exporter) which retrieves and parses the specified Cloudwatch metrics and translates them into a Prometheus monitoring endpoint. +To get started with Cloudwatch monitoring, install and configure the +[Cloudwatch exporter](https://github.com/prometheus/cloudwatch_exporter). The +Cloudwatch exporter retrieves and parses the specified Cloudwatch metrics, and +translates them into a Prometheus monitoring endpoint. -Right now, the only AWS resource supported is the Elastic Load Balancer, whose Cloudwatch metrics are [documented here](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html). +The only supported AWS resource is the Elastic Load Balancer, whose Cloudwatch +metrics are [documented here](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html). -A sample Cloudwatch Exporter configuration file, configured for basic AWS ELB monitoring, is [available for download](../samples/cloudwatch.yml). +You can [download a sample Cloudwatch Exporter configuration file](../samples/cloudwatch.yml) +that's configured for basic AWS ELB monitoring. ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). +To isolate and display only the relevant metrics for a given environment, +GitLab needs a method to detect which labels are associated. To do this, GitLab +[looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 38d6194b390..256ffe84ee2 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Redmine Service +# Redmine Service **(FREE)** 1. To enable the Redmine integration in a project, navigate to the [Integrations page](overview.md#accessing-integrations), click diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index 1de69f60a34..bdc05552c31 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# ServiceNow integration +# ServiceNow integration **(FREE)** ServiceNow offers several integrations to help centralize and automate your management of GitLab workflows. diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index 7507792bb02..66810d8a01b 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Service templates +# Service templates **(FREE)** WARNING: Service templates are [deprecated and scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index ab798675278..17d1c3adcb5 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Slack Notifications Service +# Slack Notifications Service **(FREE)** The Slack Notifications Service allows your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index e8dcb577aba..3e5e368722e 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Unify Circuit service +# Unify Circuit service **(FREE)** The Unify Circuit service sends notifications from GitLab to the conversation for which the webhook was created. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 8a3383fd0e7..6820412808f 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Webex Teams service +# Webex Teams service **(FREE)** You can configure GitLab to send notifications to a Webex Teams space. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 0cf01adef13..bf289c9707c 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Webhooks +# Webhooks **(FREE)** Project webhooks allow you to trigger a percent-encoded URL if, for example, new code is pushed or a new issue is created. You can configure webhooks to listen for specific events @@ -1133,6 +1133,10 @@ X-Gitlab-Event: Pipeline Hook "artifacts_file":{ "filename": null, "size": null + }, + "environment": { + "name": "production", + "action": "start" } }, { @@ -1167,7 +1171,8 @@ X-Gitlab-Event: Pipeline Hook "artifacts_file":{ "filename": null, "size": null - } + }, + "environment": null }, { "id": 378, @@ -1200,7 +1205,8 @@ X-Gitlab-Event: Pipeline Hook "artifacts_file":{ "filename": null, "size": null - } + }, + "environment": null }, { "id": 376, @@ -1233,7 +1239,8 @@ X-Gitlab-Event: Pipeline Hook "artifacts_file":{ "filename": null, "size": null - } + }, + "environment": null }, { "id": 379, @@ -1257,6 +1264,10 @@ X-Gitlab-Event: Pipeline Hook "artifacts_file":{ "filename": null, "size": null + }, + "environment": { + "name": "staging", + "action": "start" } } ] @@ -1329,7 +1340,8 @@ X-Gitlab-Event: Job Hook "linux", "docker" ] - } + }, + "environment": null } ``` @@ -1554,7 +1566,7 @@ X-Gitlab-Event: Subgroup Hook ``` NOTE: -Webhooks for when a [subgroup is removed from a group](#subgroup-removed-from-a-group) are not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transferring-groups) +Webhooks for when a [subgroup is removed from a group](#subgroup-removed-from-a-group) are not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transfer-a-group) ### Feature Flag events diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index f9b3c083a54..f9f61de9d6b 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -4,7 +4,7 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# YouTrack Service +# YouTrack Service **(FREE)** JetBrains [YouTrack](https://www.jetbrains.com/help/youtrack/standalone/YouTrack-Documentation.html) is a web-based issue tracking and project management platform. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index e4f42b97b84..a537972dff7 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -87,9 +87,9 @@ To delete the currently active issue board: You can tailor GitLab issue boards to your own preferred workflow. Here are some common use cases for issue boards. -For examples of using issue boards along with [epics](../group/epics/index.md) **(PREMIUM)**, -[issue health status](issues/index.md#health-status) **(ULTIMATE)**, and -[scoped labels](labels.md#scoped-labels) **(PREMIUM)** for various Agile frameworks, check: +For examples of using issue boards along with [epics](../group/epics/index.md), +[issue health status](issues/index.md#health-status), and +[scoped labels](labels.md#scoped-labels) for various Agile frameworks, check: - The [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/) blog post (November 2020) - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -154,7 +154,7 @@ for them. NOTE: For a broader use case, please see the blog post -[GitLab Workflow, an Overview](https://about.gitlab.com/blog/2016/10/25/gitlab-workflow-an-overview/#gitlab-workflow-use-case-scenario). +[GitLab Workflow, an Overview](https://about.gitlab.com/topics/version-control/what-is-gitlab-workflow/#gitlab-workflow-a-use-case-scenario). For a real use case example, you can read why [Codepen decided to adopt issue boards](https://about.gitlab.com/blog/2017/01/27/codepen-welcome-to-gitlab/#project-management-everything-in-one-place) to improve their workflow with multiple boards. @@ -277,6 +277,32 @@ group and its descendant subgroups. Similarly, you can only filter by group labe boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only group-level objects are available. +#### GraphQL-based sidebar for group issue boards **(PREMIUM)** + +<!-- When the feature flag is removed, integrate this section into the above ("Group issue boards"). --> + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-graphql-based-sidebar-for-group-issue-boards). **(PREMIUM SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +The work-in-progress GraphQL-based sidebar for group issue boards brings better performance and the +ability to edit issue titles in the issue sidebar. + +To **edit an issue's title** in the issue sidebar: + +1. In a group issue board, select the issue card. The issue sidebar opens on the right. +1. Next to the issue's title, select **Edit**. + +This is work in progress as of GitLab 13.9. Learn more about the known issues in +[MR 51480](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51480). + +<!-- Add this at the end of the file --> + ### Assignee lists **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5784) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. @@ -317,6 +343,7 @@ As in other list types, click the trash icon to remove a list. > - Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. > - Editing issue titles in the issue sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232745) in GitLab 13.8. +> - Editing iteration in the issue sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290232) in GitLab 13.9. With swimlanes you can visualize issues grouped by epic. Your issue board keeps all the other features, but with a different visual organization of issues. @@ -456,31 +483,16 @@ the list by filtering by the following: - Release - Weight -#### Enable or disable adding issues to the list **(FREE SELF)** - -Adding issues to the list is deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:add_issues_button) -``` - -To disable it: - -```ruby -Feature.disable(:add_issues_button) -``` - ### Remove an issue from a list -Removing an issue from a list can be done by clicking the issue card and then -clicking the **Remove from board** button in the sidebar. The -respective label is removed. +> The **Remove from board** button was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229507) in GitLab 13.10. + +When an issue should no longer belong to a list, you can remove it. +The steps depend on the scope of the list: - +1. To open the right sidebar, select the issue card. +1. Remove what's keeping the issue in the list. + If it's a label list, remove the label. If it's an [assignee list](#assignee-lists), unassign the user. ### Filter issues @@ -593,3 +605,40 @@ A few things to remember: - For performance and visibility reasons, each list shows the first 20 issues by default. If you have more than 20 issues, start scrolling down and the next 20 appear. + +## Enable or disable GraphQL-based sidebar for group issue boards **(PREMIUM SELF)** + +GraphQL-based sidebar for group issue boards is under development and not ready for production use. +It is deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:graphql_board_lists) +``` + +To disable it: + +```ruby +Feature.disable(:graphql_board_lists) +``` + +## Enable or disable adding issues to the list **(FREE SELF)** + +Adding issues to the list is deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:add_issues_button) +``` + +To disable it: + +```ruby +Feature.disable(:add_issues_button) +``` diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index d81fe19c5b9..f98e94c66ae 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -17,7 +17,7 @@ team members can join swiftly without requesting a link. ## Adding a Zoom meeting to an issue To associate a Zoom meeting with an issue, you can use GitLab -[quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). +[quick actions](../quick_actions.md#issues-merge-requests-and-epics). In an issue, leave a comment using the `/zoom` quick action followed by a valid Zoom link: diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index e398c6f86d0..c97196ff861 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -137,7 +137,7 @@ You can mark two issues as related, so that when viewing one, the other is alway listed in its [Related Issues](related_issues.md) section. This can help display important context, such as past work, dependencies, or duplicates. -Users on [GitLab Starter, GitLab Bronze, and higher tiers](https://about.gitlab.com/pricing/), can +Users of [GitLab Premium](https://about.gitlab.com/pricing/) or higher can also mark issues as blocking or blocked by another issue. ### Crosslinking issues @@ -162,9 +162,9 @@ Up to five similar issues, sorted by most recently updated, are displayed below ### Health status **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. -> - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4 and later. -> - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in GitLab Ultimate 12.10. +> - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab Ultimate 13.4 and later. +> - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in GitLab Ultimate 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. To help you track issue statuses, you can assign a status to each issue. @@ -184,7 +184,7 @@ You can then see issue statuses in the [issue list](#issues-list) and the ## Other Issue actions -- [Create an issue from a template](../../project/description_templates.md#using-the-templates) +- [Create an issue from a template](../../project/description_templates.md#use-the-templates) - [Set a due date](due_dates.md) - [Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues in order to change their status, assignee, milestone, or labels in bulk. diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index c3adce33826..90c918792d7 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -186,7 +186,7 @@ This icon is only displayed if the user has permission to edit the issue. ### Description The plain text title and description of the issue fill the top center of the issue page. -The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), +The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown), allowing many formatting options. [In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an @@ -249,7 +249,7 @@ Also: ### Create Merge Request -Create a new branch and [**Draft** merge request](../merge_requests/work_in_progress_merge_requests.md) +Create a new branch and [**Draft** merge request](../merge_requests/drafts.md) in one action. The branch is named `issuenumber-title` by default, but you can choose any name, and GitLab verifies that it is not already in use. The merge request inherits the milestone and labels of the issue, and is set to automatically @@ -281,7 +281,7 @@ or newest items to be shown first. ### Comments Collaborate in the issue by posting comments in its thread. This text field also fully -supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). +supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). ### Submit comment, start a thread, or comment and close @@ -301,7 +301,7 @@ You can also close the issue from here, so you don't need to scroll to the top o > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31103) in GitLab 12.3. You can attach and remove Zoom meetings to issues using the `/zoom` and `/remove_zoom` [quick actions](../quick_actions.md) as part of -[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). +[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). Attaching a [Zoom](https://zoom.us) call an issue results in a **Join Zoom meeting** button at the top of the issue, just under the header. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index f1739726cf8..cfb22881431 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -298,7 +298,7 @@ To promote an issue to an epic: 1. In an issue, select the vertical ellipsis (**{ellipsis_v}**) button. 1. Select **Promote to epic**. -Alternatively, you can use the `/promote` [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). +Alternatively, you can use the `/promote` [quick action](../quick_actions.md#issues-merge-requests-and-epics). Read more about promoting an issue to an epic on the [Manage epics page](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). @@ -313,5 +313,5 @@ To add an issue to an [iteration](../../group/iterations/index.md): 1. Click an iteration you'd like to associate this issue with. You can also use the `/iteration` -[quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) +[quick action](../quick_actions.md#issues-merge-requests-and-epics) in a comment or description field. diff --git a/doc/user/project/members/img/project_members_filter_v12_6.png b/doc/user/project/members/img/project_members_filter_v12_6.png Binary files differdeleted file mode 100644 index 692fdfe00a1..00000000000 --- a/doc/user/project/members/img/project_members_filter_v12_6.png +++ /dev/null diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 00474098487..057c2930706 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -37,10 +37,7 @@ From the image above, we can deduce the following things: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. > - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/4901) in GitLab 13.9. -> - Improvements are [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - Improvements are enabled on GitLab.com. -> - Improvements are recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable improvements](#enable-or-disable-improvements-to-project-member-management). **(FREE SELF)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299954) in GitLab 13.10. The following sections illustrate how you can filter and sort members in a project. To view these options, navigate to your desired project, go to **Members**, and include the noted search terms. @@ -199,27 +196,3 @@ To remove a member from a project: A **Remove member** modal appears. 1. (Optional) Select the **Also unassign this user from related issues and merge requests** checkbox. 1. Click **Remove member**. - -## Enable or disable improvements to project member management **(FREE SELF)** - -Project member management improvements are deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable the improvements. - -To disable them: - -```ruby -# For the instance -Feature.disable(:vue_project_members_list) -# For a single project -Feature.disable(:vue_project_members_list, Project.find(<project id>)) -``` - -To enable them: - -```ruby -# For the instance -Feature.enable(:vue_project_members_list) -# For a single project -Feature.enable(:vue_project_members_list, Project.find(<project id>)) -``` diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 7000988d9bf..8ca403783cb 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -62,4 +62,4 @@ It is possible to prevent projects in a group from [sharing a project with another group](../members/share_project_with_groups.md). This allows for tighter control over project access. -Learn more about [Share with group lock](../../group/index.md#share-with-group-lock). +Learn more about [Share with group lock](../../group/index.md#prevent-a-project-from-being-shared-with-groups). diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 7aa7673366d..5917d67c398 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -18,15 +18,15 @@ This feature is available for merge requests across forked projects that are publicly accessible. When enabled for a merge request, members with merge access to the target -branch of the project will be granted write permissions to the source branch +branch of the project is granted write permissions to the source branch of the merge request. ## Enabling commit edits from upstream members In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308), this setting is enabled by default. It can be changed by users with Developer -permissions to the source project. Once enabled, upstream members will also be -able to retry the pipelines and jobs of the merge request: +permissions to the source project. Once enabled, upstream members can +retry the pipelines and jobs of the merge request: 1. While creating or editing a merge request, select the checkbox **Allow commits from members who can merge to the target branch**. @@ -64,7 +64,7 @@ Here's how the process would look like: git checkout -b thedude-awesome-project-update-docs FETCH_HEAD ``` - This will fetch the branch of the forked project and then create a local branch + This fetches the branch of the forked project and then create a local branch based off the fetched branch. 1. Make any changes you want and commit. @@ -74,7 +74,7 @@ Here's how the process would look like: git push git@gitlab.com:thedude/awesome-project.git thedude-awesome-project-update-docs:update-docs ``` - Note the colon (`:`) between the two branches. The above command will push the + Note the colon (`:`) between the two branches. The above command pushes the local branch `thedude-awesome-project-update-docs` to the `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository. diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 36481ac0133..aa43d34cdd9 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts --- diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 6fa2340c7a4..7a869ed071a 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -13,6 +13,9 @@ If your application offers a web interface and you're using [GitLab CI/CD](../../../ci/README.md), you can quickly determine the rendering performance impact of pending code changes in the browser. +NOTE: +You can automate this feature in your applications by using [Auto DevOps](../../../topics/autodevops/index.md). + ## Overview GitLab uses [Sitespeed.io](https://www.sitespeed.io), a free and open source @@ -90,7 +93,7 @@ that you can later download and analyze. This implementation always takes the la Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. -You can also customize the jobs with environment variables: +You can also customize the jobs with CI/CD variables: - `SITESPEED_IMAGE`: Configure the Docker image to use for the job (default `sitespeedio/sitespeed.io`), but not the image version. - `SITESPEED_VERSION`: Configure the version of the Docker image to use for the job (default `14.1.0`). @@ -115,7 +118,7 @@ performance: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27599) in GitLab 13.0. You can configure the sensitivity of degradation alerts to avoid getting alerts for minor drops in metrics. -This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert only shows up +This is done by setting the `DEGRADATION_THRESHOLD` CI/CD variable. In the example below, the alert only shows up if the `Total Score` metric degrades by 5 points or more: ```yaml @@ -186,7 +189,7 @@ GitLab version: - In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). - In 13.2 the feature was renamed from `Performance` to `Browser Performance` with -additional template variables. The job name in the template is still `performance` +additional template CI/CD variables. The job name in the template is still `performance` for compatibility reasons, but may be renamed to match in a future iteration. - For 11.5 to 12.3 no template is available and the job has to be defined manually as follows: diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 55dc0bcc41a..42c2547a618 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -22,8 +22,7 @@ Code Quality: [GitLab Code Quality](https://gitlab.com/gitlab-org/ci-cd/codequality) project using [default Code Climate configurations](https://gitlab.com/gitlab-org/ci-cd/codequality/-/tree/master/codeclimate_defaults). - Can make use of a [template](#example-configuration). -- Is available with [Auto - DevOps](../../../topics/autodevops/stages.md#auto-code-quality). +- Is available by using [Auto Code Quality](../../../topics/autodevops/stages.md#auto-code-quality), provided by [Auto DevOps](../../../topics/autodevops/index.md). - Can be extended through [Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines) or a [custom tool](#implementing-a-custom-tool). ## Code Quality Widget @@ -90,7 +89,7 @@ scans your source code for code quality issues. The report is saved as a that you can later download and analyze. It's also possible to override the URL to the Code Quality image by -setting the `CODE_QUALITY_IMAGE` variable. This is particularly useful if you want +setting the `CODE_QUALITY_IMAGE` CI/CD variable. This is particularly useful if you want to lock in a specific version of Code Quality, or use a fork of it: ```yaml @@ -236,12 +235,12 @@ was chosen as an operational decision by the runner team, instead of exposing `d ### Disabling the code quality job -The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` environment -variable is present. Please refer to the environment variables [documentation](../../../ci/variables/README.md) +The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` CI/CD variable +is present. Please refer to the CI/CD variables [documentation](../../../ci/variables/README.md) to learn more about how to define one. -To disable the `code_quality` job, add `CODE_QUALITY_DISABLED` as a custom environment -variable. This can be done: +To disable the `code_quality` job, add `CODE_QUALITY_DISABLED` as a custom CI/CD variable. +This can be done: - For the whole project, [in the project settings](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui) or [CI/CD configuration](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). @@ -268,7 +267,7 @@ code_quality: - if: '$CI_COMMIT_TAG || $CI_COMMIT_BRANCH' ``` -If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/README.md#workflowrules)) +If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/README.md#workflow)) might look like this example: ```yaml @@ -365,7 +364,7 @@ After the Code Quality job completes: In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/ci-cd/codequality/-/issues/10), it is possible to generate an HTML report file by setting the `REPORT_FORMAT` -variable to `html`. This is useful if you just want to view the report in a more +CI/CD variable to `html`. This is useful if you just want to view the report in a more human-readable format or to publish this artifact on GitLab Pages for even easier reviewing. @@ -509,6 +508,7 @@ This can be due to multiple reasons: nothing is displayed. - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifact(s) to expire faster than desired. +- The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the Merge Request widget to have no base report for comparison. - If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. - Large `gl-code-quality-report.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). As a work-around, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 5cfedc6c9f1..58e80504212 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto description: "How to create Merge Requests in GitLab." @@ -30,11 +30,16 @@ button and start a merge request from there. ## New Merge Request page -On the **New Merge Request** page, start by filling in the title -and description for the merge request. If there are already -commits on the branch, the title is prefilled with the first -line of the first commit message, and the description is -prefilled with any additional lines in the commit message. +On the **New Merge Request** page, start by filling in the title and description +for the merge request. If commits already exist on the branch, GitLab suggests a +merge request title for you: + +- **If a multi-line commit message exists**: GitLab adds the first line of the + first multi-line commit message as the title. Any additional lines in that + commit message become the description. +- **If no multi-line commit message exists**: GitLab adds the branch name as the + title, and leaves the description blank. + The title is the only field that is mandatory in all cases. From there, you can fill it with information (title, description, diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md new file mode 100644 index 00000000000..a030961e219 --- /dev/null +++ b/doc/user/project/merge_requests/drafts.md @@ -0,0 +1,99 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference, concepts +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/work_in_progress_merge_requests.html' +--- + +# Draft merge requests **(FREE)** + +If a merge request isn't ready to merge, potentially because of continued development +or open threads, you can prevent it from being accepted before you +[mark it as ready](#mark-merge-requests-as-ready). Flag it as a draft to disable +the **Merge** button until you remove the **Draft** flag: + + + +## Mark merge requests as drafts + +> - [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: + +- **Viewing a merge request**: In the top right corner of the merge request, click **Mark as draft**. +- **Creating or editing a merge request**: Add `[Draft]`, `Draft:` or `(Draft)` to + the beginning of the merge request's title, or click **Start the title with Draft:** + below the **Title** field. +- **Commenting in an existing merge request**: Add the `/draft` + [quick action](../quick_actions.md#issues-merge-requests-and-epics) + in a comment. This quick action is a toggle, and can be repeated to change the status + again. This quick action discards any other text in the comment. +- **Creating a commit**: 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 adding this text again in a later commit doesn't mark the + merge request as ready. + +WARNING: +Adding `WIP:` to the start of the merge request's title still marks a merge request +as a draft. This feature is scheduled for removal in GitLab 14.0. Use `Draft:` instead. + +## Mark merge requests as ready + +When a merge request is ready to be merged, you can remove the `Draft` flag in several ways: + +- **Viewing a merge request**: In the top right corner of the merge request, click **Mark as ready**. + Users with [Developer or greater permissions](../../permissions.md) + can also scroll to the bottom of the merge request description and click **Mark as ready**: + +  + +- **Editing an existing merge request**: Remove `[Draft]`, `Draft:` or `(Draft)` + from the beginning of the title, or click **Remove the Draft: prefix from the title** + below the **Title** field. +- **Commenting in an existing merge request**: Add the `/draft` + [quick action](../quick_actions.md#issues-merge-requests-and-epics) + in a comment in the merge request. This quick action is a toggle, and can be repeated + to change the status back. This quick action discards any other text in the comment. + +In [GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/15332), +when you mark a merge request as ready, notifications are triggered to +[merge request participants and watchers](../../profile/notifications.md#notifications-on-issues-merge-requests-and-epics). + +## Include or exclude drafts when searching + +When viewing or searching in your project's merge requests list, you can include or exclude +draft merge requests: + +1. In your project, select **Merge Requests** from the left sidebar. +1. In the navigation bar, click **Open**, **Merged**, **Closed**, or **All** to + filter by merge request status. +1. Click the search box to display a list of filters and select **Draft**, or + enter the word `draft`. +1. Select `=`. +1. Select **Yes** to include drafts, or **No** to exclude, and press **Return** + to update the list of merge requests: + +  + +## Pipelines for drafts + +When the [pipelines for merged results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md) +feature is enabled, draft merge requests run +[merge request pipelines](../../../ci/merge_request_pipelines/index.md) only. + +To run pipelines for merged results, you must +[mark the merge request as ready](#mark-merge-requests-as-ready). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index c4a34f9c65c..b1e8d761f5c 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -17,7 +17,7 @@ to accept merge requests without creating merge commits. When the fast-forward merge ([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting -is enabled, no merge commits will be created and all merges are fast-forwarded, +is enabled, no merge commits are created and all merges are fast-forwarded, which means that merging is only allowed if the branch can be fast-forwarded. When a fast-forward merge is not possible, the user is given the option to rebase. @@ -28,19 +28,19 @@ When a fast-forward merge is not possible, the user is given the option to rebas 1. Select the **Fast-forward merge** option 1. Hit **Save changes** for the changes to take effect -Now, when you visit the merge request page, you will be able to accept it +Now, when you visit the merge request page, you can accept it **only if a fast-forward merge is possible**.  If a fast-forward merge is not possible but a conflict free rebase is possible, -a rebase button will be offered. +a rebase button is offered.  If the target branch is ahead of the source branch and a conflict free rebase is not possible, you need to rebase the -source branch locally before you will be able to do a fast-forward merge. +source branch locally before you can do a fast-forward merge.  diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index b1a57d9c3e6..f25228729cf 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference description: "Getting started with Merge Requests." @@ -60,7 +60,7 @@ request's page at the top-right side: - [Close issues automatically](#merge-requests-to-close-issues) when they are merged. - Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option to keep your repository clean. - Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. -- Set the merge request as a [**Draft**](work_in_progress_merge_requests.md) to avoid accidental merges before it is ready. +- Set the merge request as a [**Draft**](drafts.md) to avoid accidental merges before it is ready. After you have created the merge request, you can also: @@ -84,7 +84,7 @@ See also other [features associated to merge requests](reviewing_and_managing_me Choose an assignee to designate someone as the person responsible for the first [review of the merge request](reviewing_and_managing_merge_requests.md). Open the drop down box to search for the user you wish to assign, -and the merge request will be added to their +and the merge request is added to their [assigned merge request list](../../search/index.md#issues-and-merge-requests). #### Multiple assignees **(PREMIUM)** @@ -110,7 +110,7 @@ dropdown menu. It is also possible to manage multiple assignees: - When creating a merge request. -- Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). +- Using [quick actions](../quick_actions.md#issues-merge-requests-and-epics). ### Reviewer @@ -122,17 +122,19 @@ Requesting a code review is an important part of contributing code. However, dec your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and reviewers makes it hard for others to determine who's doing what on a merge request. -GitLab Merge Request Reviewers easily allow authors to request a review as well as see the status of the -review. By selecting one or more users from the **Reviewers** field in the merge request's right-hand -sidebar, the assigned reviewers will receive a notification of the request to review the merge request. +The Merge Request Reviewers feature enables you to request a review of your work, and +see the status of the review. Reviewers help distinguish the roles of the users +involved in the merge request. In comparison to an **Assignee**, who is directly +responsible for creating or merging a merge request, a **Reviewer** is a team member +who may only be involved in one aspect of the merge request, such as a peer review. -This makes it easy to determine the relevant roles for the users involved in the merge request, as well as formally requesting a review from a peer. - -To request it, open the **Reviewers** drop-down box to search for the user you wish to get a review from. +To request a review of a merge request, expand the **Reviewers** select box in +the right-hand sidebar. Search for the users you want to request a review from. +When selected, GitLab creates a [to-do list item](../../todos.md) for each reviewer. #### Approval Rule information for Reviewers **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. For this version only, GitLab administrators can opt to [enable it](#enable-or-disable-approval-rule-information). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. When editing the **Reviewers** field in a new or existing merge request, GitLab @@ -162,6 +164,13 @@ the author of the merge request can request a new review from the reviewer: GitLab creates a new [to-do item](../../todos.md) for the reviewer, and sends them a notification email. +#### Approval status + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292936) in GitLab 13.10. + +If a user in the reviewer list has approved the merge request, a green tick symbol is +shown to the right of their name. + ### Merge requests to close issues If the merge request is being created to resolve an issue, you can @@ -198,9 +207,9 @@ is set for deletion, the merge request widget displays the > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. > - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-branch-retargeting-on-merge). +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) on GitLab 13.10. +> - It's recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [disable it](#enable-or-disable-branch-retargeting-on-merge). **(FREE SELF)** In specific circumstances, GitLab can retarget the destination branch of open merge request, if the destination branch merges while the merge request is @@ -221,6 +230,12 @@ GitLab retargets up to four merge requests when their target branch is merged in `master`, so you don't need to perform this operation manually. Merge requests from forks are not retargeted. +The feature today works only one a merge. Clicking the `Remove source branch` button +after the merge request was merged will not automatically retarget merge request. +The feature today works only on merge. Clicking the **Remove source branch** button +after the merge request was merged will not automatically retarget a merge request. +This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitlab/-/issues/321559). + ## Recommendations and best practices for Merge Requests - When working locally in your branch, add multiple commits and only push when @@ -231,33 +246,6 @@ forks are not retargeted. reviews are faster and your changes are less prone to errors. - Do not use capital letters nor special chars in branch names. -## Enable or disable Approval Rule information **(PREMIUM SELF)** - -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. - -Merge Request Reviewers is under development and ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -# For the instance -Feature.enable(:reviewer_approval_rules) -# For a single project -Feature.enable(:reviewer_approval_rules, Project.find(<project id>)) -``` - -To disable it: - -```ruby -# For the instance -Feature.disable(:reviewer_approval_rules) -# For a single project -Feature.disable(:reviewer_approval_rules, Project.find(<project id>)) -``` - ### Enable or disable branch retargeting on merge **(FREE SELF)** Automatically retargeting merge requests is under development but ready for production use. diff --git a/doc/user/project/merge_requests/img/comment-on-any-diff-line.png b/doc/user/project/merge_requests/img/comment-on-any-diff-line.png Binary files differdeleted file mode 100644 index cff5acb98ef..00000000000 --- a/doc/user/project/merge_requests/img/comment-on-any-diff-line.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/comment-on-any-diff-line_v13_10.png b/doc/user/project/merge_requests/img/comment-on-any-diff-line_v13_10.png Binary files differnew file mode 100644 index 00000000000..a31fea85be9 --- /dev/null +++ b/doc/user/project/merge_requests/img/comment-on-any-diff-line_v13_10.png diff --git a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png b/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png Binary files differnew file mode 100644 index 00000000000..3bac9f7fee8 --- /dev/null +++ b/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png diff --git a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_2.png b/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_2.png Binary files differdeleted file mode 100644 index f7968772500..00000000000 --- a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_2.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png b/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png Binary files differnew file mode 100644 index 00000000000..4458df987d6 --- /dev/null +++ b/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png diff --git a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png Binary files differdeleted file mode 100644 index 0989b41e2a4..00000000000 --- a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/multiline-comment-highlighted.png b/doc/user/project/merge_requests/img/multiline-comment-highlighted.png Binary files differdeleted file mode 100644 index 1bdcc37e274..00000000000 --- a/doc/user/project/merge_requests/img/multiline-comment-highlighted.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v12_8.png b/doc/user/project/merge_requests/img/scoped_to_protected_branch_v12_8.png Binary files differdeleted file mode 100644 index 9446ed66c38..00000000000 --- a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v12_8.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png b/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png Binary files differnew file mode 100644 index 00000000000..b1c2e147134 --- /dev/null +++ b/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png diff --git a/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png b/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png Binary files differnew file mode 100644 index 00000000000..c0cc0db600c --- /dev/null +++ b/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png diff --git a/doc/user/project/merge_requests/img/update_approval_rule_v13_4.png b/doc/user/project/merge_requests/img/update_approval_rule_v13_4.png Binary files differdeleted file mode 100644 index af713b48140..00000000000 --- a/doc/user/project/merge_requests/img/update_approval_rule_v13_4.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 8ccf50e48b8..99e0193d496 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -1,16 +1,29 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference --- # Merge requests **(FREE)** -A Merge Request (**MR**) is a _request_ to _merge_ one branch into another. +Whenever you need to merge one branch into another branch with GitLab, you +must create a merge request (MR). -Use merge requests to visualize and collaborate on proposed changes -to source code. +Using merge requests, you can visualize and collaborate on proposed changes to +source code. Merge requests display information about the proposed code changes, +including: + +- A description of the request. +- Code changes and inline code reviews. +- Information about CI/CD pipelines. +- A comment section for discussion threads. +- The list of commits. + +Based on your workflow, after review you can merge a merge request into its +target branch. + +To get started, read the [introduction to merge requests](getting_started.md). ## Use cases @@ -36,21 +49,9 @@ B. Consider you're a web developer writing a webpage for your company's website: 1. Your changes are previewed with [Review Apps](../../../ci/review_apps/index.md) 1. You request your web designers for their implementation 1. You request the [approval](merge_request_approvals.md) from your manager **(STARTER)** -1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/) +1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/) 1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production -## Overview - -Merge requests (aka "MRs") display a great deal of information about the changes proposed. -The body of an MR contains its description, along with its widget (displaying information -about CI/CD pipelines, when present), followed by the discussion threads of the people -collaborating with that MR. - -MRs also contain navigation tabs from which you can see the discussion happening on the thread, -the list of commits, the list of pipelines and jobs, the code changes, and inline code reviews. - -To get started, read the [introduction to merge requests](getting_started.md). - ## Merge request navigation tabs at the top > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33813) in GitLab 12.6. This positioning is experimental. diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 9154897d42d..e8062fadcfe 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -104,8 +104,8 @@ An example configuration workflow: 1. Set up GitLab Runner to run Docker containers, like the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). -1. Configure the default Load Performance Testing CI job in your `.gitlab-ci.yml` file. - You need to include the template and configure it with variables: +1. Configure the default Load Performance Testing CI/CD job in your `.gitlab-ci.yml` file. + You need to include the template and configure it with CI/CD variables: ```yaml include: @@ -153,7 +153,7 @@ but it can be extended to work with [review apps](../../../ci/review_apps) or [dynamic environments](../../../ci/environments) with a few extra steps. The best approach is to capture the dynamic URL in a [`.env` file](https://docs.docker.com/compose/env-file/) -as a job artifact to be shared, then use a custom environment variable we've provided named `K6_DOCKER_OPTIONS` +as a job artifact to be shared, then use a custom CI/CD variable we've provided named `K6_DOCKER_OPTIONS` to configure the k6 Docker container to use the file. With this, k6 can then use any environment variables from the `.env` file in scripts using standard JavaScript, such as: ``http.get(`${__ENV.ENVIRONMENT_URL}`)``. diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 1fcc09a9d8a..3d3e04842f8 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -79,7 +79,8 @@ An individual user can be added as an approver for a project if they are a membe - The project's immediate parent group. - A group that has access to the project via a [share](../members/share_project_with_groups.md). -A group of users can also be added as approvers. In the future, group approvers may be +A group of users can also be added as approvers, though they only count as approvers if +they have direct membership to the group. In the future, group approvers may be [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, @@ -138,17 +139,17 @@ to push or merge code to any branches. To enable this access: -1. [Create a new group](../../group/index.md#create-a-new-group), and then +1. [Create a new group](../../group/index.md#create-a-group), and then [add the user to the group](../../group/index.md#add-users-to-a-group), ensuring you select the Reporter role for the user. 1. [Share the project with your group](../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users), based on the Reporter role. 1. Navigate to your project's **Settings > General**, and in the **Merge request approvals** section, click **Expand**. -1. [Add the group](../../group/index.md#create-a-new-group) to the permission list - for the protected branch. +1. Select **Add approval rule** or **Update approval rule**. +1. [Add the group](../../group/index.md#create-a-group) to the permission list. - + #### Adding / editing a default approval rule @@ -239,7 +240,7 @@ the **Target branch** dropdown. Alternatively, you can select a very specific protected branch from the **Target branch** dropdown: - + To enable this configuration, see [Code Owner’s approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 646d77391a3..2d7ba853258 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -40,8 +40,7 @@ require changes to `awesome-lib`, and so necessitate two merge requests. Merging the `awesome-project` merge request before the `awesome-lib` one would break the `master`branch. -The `awesome-project` merge request could be [marked as -**Draft**](work_in_progress_merge_requests.md), +The `awesome-project` merge request could be [marked as **Draft**](drafts.md), and the reason for the draft stated included in the comments. However, this requires the state of the `awesome-lib` merge request to be manually tracked, and doesn't scale well if the `awesome-project` merge request @@ -85,7 +84,7 @@ merge request widget:  Until all dependencies have, themselves, been merged, the **Merge** -button will be disabled for the dependent merge request. In +button is disabled for the dependent merge request. In particular, note that **closed merge requests** still prevent their dependents from being merged - it is impossible to automatically determine whether the dependency expressed by a closed merge request diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index d33a8e40aac..58f2c310375 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -94,7 +94,7 @@ merge-request-pipeline-job: ``` You should avoid configuration like this, and only use branch (`push`) pipelines -or merge request pipelines, when possible. See [`rules` documentation](../../../ci/yaml/README.md#prevent-duplicate-pipelines) +or merge request pipelines, when possible. See [`rules` documentation](../../../ci/yaml/README.md#avoid-duplicate-pipelines) for details on avoiding two pipelines for a single merge request. ### Skipped pipelines diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index a53b5032e1d..4d5d89d6508 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index d5d0578c07c..a798f2c9b85 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -13,27 +13,26 @@ by clicking the **Revert** button in merge requests and commit details. ## Reverting a merge request NOTE: -The **Revert** button will only be available for merge requests +The **Revert** button is available only for merge requests created in GitLab 8.5 and later. However, you can still revert a merge request by reverting the merge commit from the list of Commits page. NOTE: -The **Revert** button will only be shown for projects that use the +The **Revert** button is shown only for projects that use the merge method "Merge Commit", which can be set under the project's **Settings > General > Merge request**. [Fast-forward commits](fast_forward_merge.md) -can not be reverted via the MR view. +can not be reverted by using the merge request view. -After the Merge Request has been merged, a **Revert** button will be available +After the merge request has been merged, use the **Revert** button to revert the changes introduced by that merge request. - + -After you click that button, a modal will appear where you can choose to +After you click that button, a modal appears where you can choose to revert the changes directly into the selected branch or you can opt to create a new merge request with the revert changes. -After the merge request has been reverted, the **Revert** button will not be -available anymore. +After the merge request has been reverted, the **Revert** button is no longer available. ## Reverting a commit @@ -45,14 +44,13 @@ Similar to reverting a merge request, you can opt to revert the changes directly into the target branch or create a new merge request to revert the changes. -After the commit has been reverted, the **Revert** button will not be available -anymore. +After a commit is reverted, the **Revert** button is no longer available. -Please note that when reverting 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 reverting 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 revert a merge commit using the second parent as the +Here's an example to revert a merge commit using the second parent as the mainline: ```shell 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 94f48fa544f..406a79217d0 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 @@ -1,6 +1,6 @@ --- stage: Create -group: Source Code +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference --- @@ -187,27 +187,31 @@ Feature.disable(:local_file_reviews) > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. 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. +In the Merge Request Diff UI, you can: - +- **Comment on a single line**: Click the **{comment}** **comment** icon in the + gutter to expand the diff lines and display a comment box. +- [**Comment on multiple lines**](#commenting-on-multiple-lines). ### Commenting on multiple lines > - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) click-and-drag features in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. -GitLab provides a way to select which lines of code a comment refers to. After starting a comment -a dropdown selector is shown to select the first line that this comment refers to. -The last line is the line that the comment icon was initially clicked on. +When commenting on a diff, you can select which lines of code your comment refers +to by either: -New comments default to single line comments by having the first and last lines -the same. Selecting a different starting line turns this into a multiline comment. + - +- Clicking and dragging the **{comment}** **comment** icon in the gutter to highlight + lines in the diff. GitLab expands the diff lines and displays a comment box. +- After starting a comment by clicking the **{comment}** **comment** icon in the + gutter, select the first line number your comment refers to in the **Commenting on lines** + select box. New comments default to single-line comments, unless you select + a different starting line. -Once a multiline comment is saved the lines of code pertaining to that comment are listed directly -above it. +Multiline comments display the comment's line numbers above the body of the comment:  diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 1b99b1b5c44..f500c18a32e 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -31,7 +31,7 @@ NOTE: The squashed commit in this example is followed by a merge commit, because the merge method for this repository uses a merge commit. You can disable merge commits in **Project Settings > General > Merge requests > Merge method > Fast-forward merge**. -The squashed commit's commit message will be either: +The squashed commit's commit message is either: - Taken from the first multi-line commit message in the merge. - The merge request's title if no multi-line commit message is found. @@ -60,7 +60,7 @@ This way, the history of your base branch remains clean with meaningful commit messages and: - It's simpler to [revert](revert_changes.md) if necessary. -- The merged branch will retain the full commit history. +- The merged branch retains the full commit history. ## Enabling squash for a merge request @@ -113,18 +113,18 @@ squashing can itself be considered equivalent to rebasing. With Squash Commits Options you can configure the behavior of Squash and Merge for your project. To set it up, navigate to your project's **Settings > General** and expand **Merge requests**. -You will find the following options to choose, which will affect existing and new merge requests +You can choose from these options, which affect existing and new merge requests submitted to your project: - **Do not allow**: users cannot use Squash and Merge to squash all the commits immediately before - merging. The checkbox to enable or disable it will be unchecked and hidden from the users. -- **Allow**: users will have the option to enable Squash and Merge on a merge request basis. - The checkbox will be unchecked (disabled) by default, but and the user is allowed to enable it. -- **Encourage**: users will have the option to enable Squash and Merge on a merge request basis. - The checkbox will be checked (enabled) by default to encourage its use, but the user is allowed to + merging. The checkbox to enable or disable it is unchecked and hidden from the users. +- **Allow**: users can enable Squash and Merge on a merge request basis. + The checkbox is unchecked (disabled) by default, but and the user is allowed to enable it. +- **Encourage**: users can enable Squash and Merge on a merge request basis. + The checkbox is checked (enabled) by default to encourage its use, but the user is allowed to disable it. -- **Require**: Squash and Merge is enabled for all merge requests, so it will always be performed. - The checkbox to enable or disable it will be checked and hidden from the users. +- **Require**: Squash and Merge is enabled for all merge requests, so it is always performed. + The checkbox to enable or disable it is checked and hidden from the users. The Squash and Merge checkbox is displayed when you create a merge request and when you edit the description of an existing one, except when Squash Commit Options is set to **Do not allow** or **Require**. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index e60f2f712d3..9f839dbd274 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -219,3 +219,32 @@ run tests: reports: cobertura: coverage.xml ``` + +### C/C++ example + +The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for C/C++ with +`gcc` or `g++` as the compiler uses [`gcovr`](https://gcovr.com/en/stable/) to generate the coverage +output file in Cobertura XML format. + +This example assumes: + +- That the `Makefile` is created by `cmake` in the `build` directory, + within another job in a previous stage. + (If you use `automake` to generate the `Makefile`, + then you need to call `make check` instead of `make test`.) +- `cmake` (or `automake`) has set the compiler option `--coverage`. + +```yaml +run tests: + stage: test + script: + - cd build + - make test + - gcovr --xml-pretty --exclude-unreachable-branches --print-summary -o coverage.xml --root ${CI_PROJECT_DIR} + coverage: /^\s*lines:\s*\d+.\d+\%/ + artifacts: + name: ${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}-${CI_COMMIT_SHA} + expire_in: 2 days + reports: + cobertura: build/coverage.xml +``` diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 8f3ce9186f1..2c77957c98d 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -64,7 +64,7 @@ In GitLab 12.10, we added a comparison mode, which shows a diff calculated by simulating how it would look like once merged - a more accurate representation of the changes rather than using the base of the two branches. The new mode is available from the comparison target drop down -by selecting **master (HEAD)**. In GitLab 13.9, it +by selecting **master (HEAD)**. In GitLab 13.9, it [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the old default comparison. For technical details, additional information is available in the [developer documentation](../../../development/diffs.md#merge-request-diffs-against-the-head-of-the-target-branch). 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 43ab03114fa..4b854da116e 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 @@ -1,78 +1,8 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, concepts +redirect_to: 'drafts.md' --- -# Draft merge requests **(FREE)** +This document was moved to [another location](drafts.md). -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 disables the **Merge** button, preventing it from -being merged. It stays disabled until the **Draft** flag has been removed. - - - -When [pipelines for merged results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md) -is enabled, draft merge requests run [merge request pipelines](../../../ci/merge_request_pipelines/index.md) -only. - -To run pipelines for merged results, you must [remove the draft status](#removing-the-draft-flag-from-a-merge-request). - -## 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** 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: - -- 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 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 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 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 has no effect. - -## Removing the "Draft" flag from a merge request - -Similar to above, when a Merge Request is ready to be merged, you can remove the -`Draft` flag in several ways: - -- 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, 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 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 - be visible. - -## Including/excluding WIP merge requests when searching - -When viewing/searching the merge requests list, you can choose to include or exclude -WIP merge requests. Add a **WIP** filter in the search box, and choose **Yes** -to include, or **No** to exclude. - - - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +<!-- This redirect file can be deleted after <2021-05-19>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md deleted file mode 100644 index 2985e5da2ab..00000000000 --- a/doc/user/project/milestones/burndown_charts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'burndown_and_burnup_charts.md' ---- - -This document was moved to [another location](burndown_and_burnup_charts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index e0d5e8be535..30dd337d9d8 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -41,7 +41,7 @@ configuration for the Pages site to generate properly. If everything is configured correctly, the site can take approximately 30 minutes to deploy. -You can watch the pipeline run by navigating to **CI / CD > Pipelines**. +You can watch the pipeline run by navigating to **CI/CD > Pipelines**. When the pipeline is finished, go to **Settings > Pages** to find the link to your Pages website. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 3f2df634e3a..8368b38bc80 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -152,7 +152,7 @@ pages: ``` Now save and commit the `.gitlab-ci.yml` file. You can watch the pipeline run -by going to **CI / CD > Pipelines**. +by going to **CI/CD > Pipelines**. When it succeeds, go to **Settings > Pages** to view the URL where your site is now available. @@ -396,7 +396,7 @@ but also pushes with **continuous tests** to feature-branches, For more information, see the following blog posts. - [Use GitLab CI/CD `environments` to deploy your - web app to staging and production](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/). + web app to staging and production](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). - Learn [how to run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/). - Learn [how to pull specific directories from different projects](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 6eb06972945..2a0e1207bf5 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -46,9 +46,9 @@ To create a GitLab Pages website: | Document | Description | | -------- | ----------- | -| [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | | [Use a new project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a new project template. | | [Use a `.gitlab-ci.yml` template](getting_started/pages_ci_cd_template.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | +| [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | | [Create a `gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | To update a GitLab Pages website: @@ -116,7 +116,7 @@ to use and adapt to your own needs: - [Posting to your GitLab Pages blog from iOS](https://about.gitlab.com/blog/2016/08/19/posting-to-your-gitlab-pages-blog-from-ios/). - [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/). -- [GitLab CI: Deployment & environments](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/). +- [GitLab CI: Deployment & environments](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). - [Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/). - [Publish code coverage reports with GitLab Pages](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 4629c87f41e..aef96ff12c9 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -35,7 +35,7 @@ See the [Changelog](#changelog) section for changes over time. ## Configuring protected branches To protect a branch, you need to have at least Maintainer permission level. -The `master` branch is protected by default. +The default branch for your repository is protected by default. 1. In your project, go to **Settings > Repository**. 1. Scroll to find the **Protected branches** section. @@ -177,6 +177,41 @@ Deleting a protected branch is allowed only by using the web interface; not from This means that you can't accidentally delete a protected branch from your command line or a Git client application. +## Allow force push on protected branches **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-allow-force-push-on-protected-branches). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can allow force pushes to protected branches by either setting **Allow force push** +when you protect a new branch, or by configuring an already-protected branch. + +To protect a new branch and enable Force push: + +1. Navigate to your project's **Settings > Repository**. +1. Expand **Protected branches**, and scroll to **Protect a branch**. +  +1. Select a **Branch** or wildcard you'd like to protect. +1. Select the user levels **Allowed to merge** and **Allowed to push**. +1. To allow all users with push access to force push, toggle the **Allow force push** slider. +1. To reject code pushes that change files listed in the `CODEOWNERS` file, toggle + **Require approval from code owners**. +1. Click **Protect**. + +To enable force pushes on branches already protected: + +1. Navigate to your project's **Settings > Repository**. +1. Expand **Protected branches** and scroll to **Protected branch**. +  +1. Toggle the **Allow force push** slider for the chosen branch. + +When enabled, members who are allowed to push to this branch can also force push. + ## Protected branches approval by Code Owners **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4. @@ -193,14 +228,14 @@ To protect a new branch and enable Code Owner's approval: 1. Scroll down to **Protect a branch**, select a **Branch** or wildcard you'd like to protect, select who's **Allowed to merge** and **Allowed to push**, and toggle the **Require approval from code owners** slider. 1. Click **Protect**. - + To enable Code Owner's approval to branches already protected: 1. Navigate to your project's **Settings > Repository** and expand **Protected branches**. 1. Scroll down to **Protected branch** and toggle the **Code owner approval** slider for the chosen branch. - + When enabled, all merge requests targeting these branches require approval by a Code Owner per matched rule before they can be merged. @@ -216,6 +251,25 @@ run CI/CD pipelines and execute actions on jobs that are related to those branch See [Security on protected branches](../../ci/pipelines/index.md#pipeline-security-on-protected-branches) for details about the pipelines security model. +## Enable or disable allow force push on protected branches **(FREE SELF)** + +Allow force push on protected branches is under development and not ready for +production use. It is deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:allow_force_push_to_protected_branches) +``` + +To disable it: + +```ruby +Feature.disable(:allow_force_push_to_protected_branches) +``` + ## Changelog - **13.5**: [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index f94a4075363..c557c7718c9 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -34,12 +34,12 @@ git push -o <push_option> ## Push options for GitLab CI/CD -You can use push options to skip a CI/CD pipeline, or pass environment variables. +You can use push options to skip a CI/CD pipeline, or pass CI/CD variables. | Push option | Description | Introduced in version | | ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | | `ci.skip` | Do not create a CI pipeline for the latest push. | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | -| `ci.variable="<name>=<value>"` | Provide [environment variables](../../ci/variables/README.md) to be used in a CI pipeline, if one is created due to the push. | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | +| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/README.md) to be used in a CI pipeline, if one is created due to the push. | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | An example of using `ci.skip`: @@ -47,7 +47,7 @@ An example of using `ci.skip`: git push -o ci.skip ``` -An example of passing some environment variables for a pipeline: +An example of passing some CI/CD variables for a pipeline: ```shell git push -o ci.variable="MAX_RETRIES=10" -o ci.variable="MAX_TIME=600" @@ -66,7 +66,7 @@ time as pushing changes: | `merge_request.remove_source_branch` | Set the merge request to remove the source branch when it's merged. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | | `merge_request.title="<title>"` | Set the title of the merge request. Ex: `git push -o merge_request.title="The title I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | | `merge_request.description="<description>"` | Set the description of the merge request. Ex: `git push -o merge_request.description="The description I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | -| `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it will be created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | +| `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | | `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | If you use a push option that requires text with spaces in it, you need to enclose it @@ -108,7 +108,7 @@ option](#push-options-for-merge-requests): git config --global alias.mwps "push -o merge_request.create -o merge_request.target=master -o merge_request.merge_when_pipeline_succeeds" ``` -Then to quickly push a local branch that will target master and merge when the +Then to quickly push a local branch that targets the default branch and merges when the pipeline succeeds: ```shell diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index ac65fabd6a7..284deabb33c 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Quick Actions +# GitLab quick actions **(FREE)** > - Introduced in [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672): > once an action is executed, an alert appears when a quick action is successfully applied. @@ -15,114 +15,113 @@ info: To determine the technical writer assigned to the Stage/Group associated w > `/` into a description or comment field, all available quick actions are displayed in a scrollable list. > - The rebase quick action was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49800) in GitLab 13.8. -Quick actions are textual shortcuts for common actions on issues, epics, merge requests, -and commits that are usually done by clicking buttons or dropdowns in the GitLab UI. -You can enter these commands in the description or in comments of issues, epics, merge requests, and commits. -Each command should be on a separate line in order to be properly detected and executed. - -## Quick Actions for issues, merge requests and epics - -The following quick actions are applicable to descriptions, discussions and threads in: - -- Issues -- Merge requests -- Epics **(PREMIUM)** - -| Command | Issue | Merge request | Epic | Action | -| :------------------------------------ | :---- | :------------ | :--- | :------------------------------------------------------------------------------------------------------------------------------ | -| `/approve` | | ✓ | | Approve the merge request. **(STARTER)** | -| `/assign @user` | ✓ | ✓ | | Assign one user. | -| `/assign @user1 @user2` | ✓ | ✓ | | Assign multiple users. **(STARTER)** | -| `/assign me` | ✓ | ✓ | | Assign yourself. | -| `/assign_reviewer @user` or `/reviewer @user` or `/request_review @user` | | ✓ | | Assign one user as a reviewer. | -| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | | ✓ | | Assign multiple users as reviewers. **(STARTER)** | -| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | | ✓ | | Assign yourself as a reviewer. | -| `/award :emoji:` | ✓ | ✓ | ✓ | Toggle emoji award. | -| `/child_epic <epic>` | | | ✓ | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | -| `/clear_weight` | ✓ | | | Clear weight. **(STARTER)** | -| `/clone <path/to/project> [--with_notes]`| ✓ | | | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | -| `/close` | ✓ | ✓ | ✓ | Close. | -| `/confidential` | ✓ | | | Make confidential. | -| `/copy_metadata <!merge_request>` | ✓ | ✓ | | Copy labels and milestone from another merge request in the project. | -| `/copy_metadata <#issue>` | ✓ | ✓ | | Copy labels and milestone from another issue in the project. | -| `/create_merge_request <branch name>` | ✓ | | | Create a new merge request starting from the current issue. | -| `/done` | ✓ | ✓ | ✓ | Mark to do as done. | -| `/draft` | | ✓ | | Toggle the draft status. | -| `/due <date>` | ✓ | | | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | -| `/duplicate <#issue>` | ✓ | | | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. **(STARTER)** | -| `/epic <epic>` | ✓ | | | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. **(PREMIUM)** | -| `/estimate <<W>w <DD>d <hh>h <mm>m>` | ✓ | ✓ | | Set time estimate. For example, `/estimate 1w 3d 2h 14m`. | -| `/iteration *iteration:"iteration name"` | ✓ | | | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). **(STARTER)** | -| `/label ~label1 ~label2` | ✓ | ✓ | ✓ | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | -| `/lock` | ✓ | ✓ | | Lock the discussions. | -| `/merge` | | ✓ | | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), adding to a [Merge Train](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md), etc. | -| `/milestone %milestone` | ✓ | ✓ | | Set milestone. | -| `/move <path/to/project>` | ✓ | | | Move this issue to another project. | -| `/parent_epic <epic>` | | | ✓ | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). **(ULTIMATE)** | -| `/promote` | ✓ | | | Promote issue to epic. **(PREMIUM)** | -| `/publish` | ✓ | | | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) **(ULTIMATE)** | -| `/reassign @user1 @user2` | ✓ | ✓ | | Replace current assignees with those specified. **(STARTER)** | -| `/rebase` | | ✓ | | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | -| `/reassign_reviewer @user1 @user2` | | ✓ | | Replace current reviewers with those specified. **(STARTER)** | -| `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace current labels with those specified. | -| `/relate #issue1 #issue2` | ✓ | | | Mark issues as related. **(STARTER)** | -| `/remove_child_epic <epic>` | | | ✓ | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | -| `/remove_due_date` | ✓ | | | Remove due date. | -| `/remove_epic` | ✓ | | | Remove from epic. **(PREMIUM)** | -| `/remove_estimate` | ✓ | ✓ | | Remove time estimate. | -| `/remove_iteration` | ✓ | | | Remove iteration ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)) **(STARTER)** | -| `/remove_milestone` | ✓ | ✓ | | Remove milestone. | -| `/remove_parent_epic` | | | ✓ | Remove parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). **(ULTIMATE)** | -| `/remove_time_spent` | ✓ | ✓ | | Remove time spent. | -| `/remove_zoom` | ✓ | | | Remove Zoom meeting from this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | -| `/reopen` | ✓ | ✓ | ✓ | Reopen. | -| `/shrug <comment>` | ✓ | ✓ | ✓ | Append the comment with `¯\＿(ツ)＿/¯`. | -| `/spend <time(-<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | ✓ | ✓ | | Subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend time(-1h 30m)` or `/spend time(-1h 30m) date(2018-08-26)`. | -| `/spend <time(<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | ✓ | ✓ | | Add spent time. Optionally, specify the date that time was spent on. For example, `/spend time(1h 30m)` or `/spend time(1h 30m) date(2018-08-26)`. | -| `/submit_review` | | ✓ | | Submit a pending review ([introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/8041)). **(PREMIUM)** | -| `/subscribe` | ✓ | ✓ | ✓ | Subscribe to notifications. | -| `/tableflip <comment>` | ✓ | ✓ | ✓ | Append the comment with `(╯°□°)╯︵ ┻━┻`. | -| `/target_branch <local branch name>` | | ✓ | | Set target branch. | -| `/title <new title>` | ✓ | ✓ | ✓ | Change title. | -| `/todo` | ✓ | ✓ | ✓ | Add a to-do item. | -| `/unassign @user1 @user2` | ✓ | ✓ | | Remove specific assignees. **(STARTER)** | -| `/unassign` | | ✓ | | Remove all assignees. | -| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | | ✓ | | Remove specific reviewers. **(STARTER)** | -| `/unassign_reviewer` or `/remove_reviewer` | | ✓ | | Remove all reviewers. | -| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove specified labels. | -| `/unlabel` or `/remove_label` | ✓ | ✓ | ✓ | Remove all labels. | -| `/unlock` | ✓ | ✓ | | Unlock the discussions. | -| `/unsubscribe` | ✓ | ✓ | ✓ | Unsubscribe from notifications. | -| `/weight <value>` | ✓ | | | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. **(STARTER)** | -| `/wip` | | ✓ | | Toggle the draft status. | -| `/zoom <Zoom URL>` | ✓ | | | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | - -## Autocomplete characters - -Many quick actions require a parameter, for example: username, milestone, and -label. [Autocomplete characters](autocomplete_characters.md) can make it easier -to enter a parameter, compared to selecting items from a list. - -## Quick actions parameters - -The easiest way to set parameters for quick actions is to use autocomplete. If -you manually enter a parameter, it must be enclosed in double quotation marks +Quick actions are text-based shortcuts for common actions that are usually done +by selecting buttons or dropdowns in the GitLab user interface. You can enter +these commands in the descriptions or comments of issues, epics, merge requests, +and commits. + +Be sure to enter each quick action on a separate line to allow GitLab to +properly detect and execute the commands. + +## Parameters + +Many quick actions require a parameter. For example, the `/assign` quick action +requires a username. GitLab uses [autocomplete characters](autocomplete_characters.md) +with quick actions to help users enter parameters, by providing a list of +available values. + +If you manually enter a parameter, it must be enclosed in double quotation marks (`"`), unless it contains only these characters: -1. ASCII letters. -1. Numerals (0-9). -1. Underscore (`_`), hyphen (`-`), question mark (`?`), dot (`.`), or ampersand (`&`). +- ASCII letters +- Numbers (0-9) +- Underscore (`_`), hyphen (`-`), question mark (`?`), dot (`.`), or ampersand (`&`) -Parameters are also case-sensitive. Autocomplete handles this, and the insertion +Parameters are case-sensitive. Autocomplete handles this, and the insertion of quotation marks, automatically. -## Quick actions for commit messages +## Issues, merge requests, and epics + +The following quick actions are applicable to descriptions, discussions, and +threads. Some quick actions might not be available to all subscription tiers. + +| Command | Issue | Merge request | Epic | Action | +|:--------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| +| `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. | +| `/assign @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one user. | +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign multiple users. | +| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | +| `/assign_reviewer @user` or `/reviewer @user` or `/request_review @user` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one user as a reviewer. | +| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign multiple users as reviewers. | +| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | +| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle emoji award. | +| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | +| `/clone <path/to/project> [--with_notes]`| **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | +| `/confidential` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Make confidential. | +| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. | +| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | +| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | +| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | +| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the draft status. | +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | +| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. | +| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | +| `/estimate <<W>w <DD>d <hh>h <mm>m>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1w 3d 2h 14m`. | +| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants`. | +| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | +| `/label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | +| `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | +| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). | +| `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. | +| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. | +| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | +| `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | +| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) | +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | +| `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | +| `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | +| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | +| `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. | +| `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | +| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. | +| `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. | +| `/remove_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. | +| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | +| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. | +| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | +| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | +| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/spend <time(-<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend time(-1h 30m)` or `/spend time(-1h 30m) date(2018-08-26)`. | +| `/spend <time(<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add spent time. Optionally, specify the date that time was spent on. For example, `/spend time(1h 30m)` or `/spend time(1h 30m) date(2018-08-26)`. | +| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/8041)). | +| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | +| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | +| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | +| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | +| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | +| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. | +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | +| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | +| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | +| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | +| `/wip` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the draft status. | +| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | + +## Commit messages The following quick actions are applicable for commit messages: | Command | Action | -| :---------------------- | :---------------------------------------- | -| `/tag v1.2.3 <message>` | Tags this commit with an optional message | +|:----------------------- |:------------------------------------------| +| `/tag v1.2.3 <message>` | Tags the commit with an optional message. | <!-- ## Troubleshooting diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index b5751797870..7348e17a017 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -66,14 +66,11 @@ To create a new release through the GitLab UI: 1. Navigate to **Project overview > Releases** and click the **New release** button. -1. In the [**Tag name**](#tag-name) box, enter a name. - - Creating a release based on an existing tag using the user - interface is not yet supported. However, this is possible using the - [Releases API](../../../api/releases/index.md#create-a-release). - -1. In the **Create from** list, select a branch, tag, or commit SHA to use when - creating the new tag. +1. Open the [**Tag name**](#tag-name) dropdown. Select an existing tag or type + in a new tag name. Selecting an existing tag that is already associated with + a release will result in a validation error. +1. If creating a new tag, open the **Create from** dropdown. Select a + branch, tag, or commit SHA to use when creating the new tag. 1. Optionally, fill out any additional information about the release, such as its [title](#title), [milestones](#associate-milestones-with-a-release), [release notes](#release-notes-description), or [assets links](#links). @@ -214,7 +211,7 @@ To set a deploy freeze window in the UI, complete these steps: 1. Sign in to GitLab as a user with project Maintainer [permissions](../../permissions.md). 1. Navigate to **Project overview**. -1. In the left navigation menu, navigate to **Settings > CI / CD**. +1. In the left navigation menu, navigate to **Settings > CI/CD**. 1. Scroll to **Deploy freezes**. 1. Click **Expand** to see the deploy freeze table. 1. Click **Add deploy freeze** to open the deploy freeze modal. @@ -475,7 +472,7 @@ terminal. Read the [Release CLI documentation](https://gitlab.com/gitlab-org/release-cli/-/blob/master/docs/index.md) for details. -## Release Metrics **(PREMIUM)** +## Release Metrics **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259703) in GitLab Premium 13.9. diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box.png b/doc/user/project/repository/branches/img/branch_filter_search_box.png Binary files differdeleted file mode 100644 index 5dc300cf24e..00000000000 --- a/doc/user/project/repository/branches/img/branch_filter_search_box.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png Binary files differnew file mode 100644 index 00000000000..da7d5268b3b --- /dev/null +++ b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png diff --git a/doc/user/project/repository/branches/img/compare_branches.png b/doc/user/project/repository/branches/img/compare_branches.png Binary files differdeleted file mode 100644 index e6f88da4989..00000000000 --- a/doc/user/project/repository/branches/img/compare_branches.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/compare_branches_v13_10.png b/doc/user/project/repository/branches/img/compare_branches_v13_10.png Binary files differnew file mode 100644 index 00000000000..2b9a5751938 --- /dev/null +++ b/doc/user/project/repository/branches/img/compare_branches_v13_10.png diff --git a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_10.png b/doc/user/project/repository/branches/img/repository_filter_search_box_v13_10.png Binary files differnew file mode 100644 index 00000000000..fdda3858c3b --- /dev/null +++ b/doc/user/project/repository/branches/img/repository_filter_search_box_v13_10.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 4d0cf28593d..d049b2108ee 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -64,7 +64,7 @@ against accidental deletion and forced pushes. By default, when you create a new project in GitLab, the initial branch is called `master`. For self-managed instances, a GitLab administrator can customize the initial branch name to something -else. This way, every new project created from then on will start from the custom branch name rather than `master`. To do so: +else. This way, every new project created from then on starts from the custom branch name rather than `master`. To do so: 1. Go to the **Admin Area > Settings > Repository** and expand **Default initial branch name**. @@ -96,10 +96,11 @@ To compare branches in a repository: 1. Navigate to your project's repository. 1. Select **Repository > Compare** in the sidebar. -1. Select branches to compare using the [branch filter search box](#branch-filter-search-box) +1. Select the target repository to compare with the [repository filter search box](#repository-filter-search-box). +1. Select branches to compare using the [branch filter search box](#branch-filter-search-box). 1. Click **Compare** to view the changes inline: - +  ## Delete merged branches @@ -108,17 +109,30 @@ To compare branches in a repository:  This feature allows merged branches to be deleted in bulk. Only branches that -have been merged and [are not protected](../../protected_branches.md) will be deleted as part of +have been merged and [are not protected](../../protected_branches.md) are deleted as part of this operation. It's particularly useful to clean up old branches that were not deleted automatically when a merge request was merged. +## Repository filter search box + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52967) in GitLab 13.10. + +This feature allows you to search and select a repository quickly when [comparing branches](#compare). + + + +Search results appear in the following order: + +- Repositories with names exactly matching the search terms. +- Other repositories with names that include search terms, sorted alphabetically. + ## Branch filter search box > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22166) in GitLab 11.5. - + This feature allows you to search and select branches quickly. Search results appear in the following order: @@ -127,8 +141,8 @@ This feature allows you to search and select branches quickly. Search results ap Sometimes when you have hundreds of branches you may want a more flexible matching pattern. In such cases you can use the following: -- `^feature` will only match branch names that begin with 'feature'. -- `feature$` will only match branch names that end with 'feature'. +- `^feature` matches only branch names that begin with 'feature'. +- `feature$` matches only branch names that end with 'feature'. <!-- ## Troubleshooting diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index df3e24fbf30..3af7a5045c4 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' --- -# File finder +# File finder **(FREE)** > [Introduced](https://github.com/gitlabhq/gitlabhq/pull/9889) in GitLab 8.4. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 1a5e169ec6b..c8922890deb 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -31,25 +31,25 @@ Forking a project is, in most cases, a two-step process.  -The fork is created. The permissions you have in the namespace are the permissions you will have in the fork. +The fork is created. The permissions you have in the namespace are your permissions in the fork. WARNING: -When a public project with the repository feature set to "Members -only" is forked, the repository will be public in the fork. The owner -of the fork will need to manually change the visibility. This is being +When a public project with the repository feature set to **Members Only** +is forked, the repository is public in the fork. The owner +of the fork must manually change the visibility. This is being fixed in [#36662](https://gitlab.com/gitlab-org/gitlab/-/issues/36662). ## Repository mirroring You can use [repository mirroring](repository_mirroring.md) to keep your fork synced with the original repository. You can also use `git remote add upstream` to achieve the same result. -The main difference is that with repository mirroring your remote fork will be automatically kept up-to-date. +The main difference is that with repository mirroring, your remote fork is automatically kept up-to-date. -Without mirroring, to work locally you'll have to use `git pull` to update your local repository +Without mirroring, to work locally you must use `git pull` to update your local repository with the upstream project, then push the changes back to your fork to update it. WARNING: -With mirroring, before approving a merge request, you'll likely be asked to sync; hence automating it is recommended. +With mirroring, before approving a merge request, you are asked to sync. Because of this, automating it is recommended. Read more about [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). @@ -60,7 +60,7 @@ When you are ready to send your code back to the upstream project, choose your forked project's branch. For **Target branch**, choose the original project's branch. NOTE: -When creating a merge request, if the forked project's visibility is more restrictive than the parent project (for example the fork is private, the parent is public), the target branch will default to the forked project's default branch. This prevents potentially exposing the private code of the forked project. +When creating a merge request, if the forked project's visibility is more restrictive than the parent project (for example the fork is private, the parent is public), the target branch defaults to the forked project's default branch. This prevents potentially exposing the private code of the forked project.  diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 81995291911..0f49932d0c6 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -18,13 +18,12 @@ You can find the **Blame** button with each file in a project.  -When you select the **Blame** button, you'll see a screen with the -noted information: +When you select the **Blame** button, this information is shown:  -If you hover over a commit in the UI, you'll see a precise date and time -for that commit. +If you hover over a commit in the UI, the commit's precise date and time +are shown. ## Blame previous commit @@ -45,7 +44,7 @@ about a `README.md` file in the local directory, run the following command: git blame README.md ``` -You'll see output similar to the following, which includes the commit time +The output looks similar to the following, which includes the commit time in UTC format: ```shell diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 2e27cab4177..1b30a0b0f5f 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -17,13 +17,12 @@ You can find the **History** button with each file in a project.  -When you select the **History** button, you'll see a screen with the -noted information: +When you select the **History** button, this information displays:  -If you hover over a commit in the UI, you'll see a precise date and time -that commit was last modified. +If you hover over a commit in the UI, the precise date and time of the commit modification +are shown. ## Associated `git` command @@ -36,7 +35,7 @@ following command: git log README.md ``` -You'll see output similar to the following, which includes the commit +Git displays output similar to the following, which includes the commit time in UTC format: ```shell diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 1a46c140507..c41b3ed8615 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -40,7 +40,7 @@ For a commit to be verified by GitLab: ## Generating a GPG key -If you don't already have a GPG key, the following steps will help you get +If you don't already have a GPG key, the following steps can help you get started: 1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system. @@ -225,8 +225,8 @@ git config --global commit.gpgsign true ## Verifying commits 1. Within a project or [merge request](../../merge_requests/index.md), navigate to - the **Commits** tab. Signed commits will show a badge containing either - "Verified" or "Unverified", depending on the verification status of the GPG + the **Commits** tab. Signed commits show a badge containing either + **Verified** or **Unverified**, depending on the verification status of the GPG signature.  @@ -240,8 +240,8 @@ git config --global commit.gpgsign true ## Revoking a GPG key Revoking a key **unverifies** already signed commits. Commits that were -verified by using this key will change to an unverified state. Future commits -will also stay unverified once you revoke this key. This action should be used +verified by using this key changes to an unverified state. Future commits +stay unverified after you revoke this key. This action should be used in case your key has been compromised. To revoke a GPG key: @@ -282,6 +282,7 @@ For more details about GPG, see: - [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) - [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) - [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) +- [Review existing GPG keys in your instance](../../../admin_area/credentials_inventory.md#review-existing-gpg-keys) <!-- ## Troubleshooting diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 5a915ebef89..4dfc922fbad 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -19,8 +19,8 @@ To create a new repository, all you need to do is Once you create a new project, you can add new files via UI (read the section below) or via command line. -To add files from the command line, follow the instructions that will -be presented on the screen when you create a new project, or read +To add files from the command line, follow the instructions +presented on the screen when you create a new project, or read through them in the [command line basics](../../../gitlab-basics/start-using-git.md) documentation. @@ -31,8 +31,7 @@ that you [connect with GitLab via SSH](../../../ssh/README.md). ## Files Use a repository to store your files in GitLab. In [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33806), -you'll see on the repository's file tree an icon next to the filename -according to its extension: +an icon identifying the extension is shown next to the filename:  @@ -76,7 +75,7 @@ markup languages](https://en.wikipedia.org/wiki/Lightweight_markup_language)) that you can use for the content of your files in a repository. They are mostly used for documentation purposes. -Just pick the right extension for your files and GitLab will render them +Just pick the right extension for your files and GitLab renders them according to the markup language. | Markup language | Extensions | @@ -93,7 +92,7 @@ according to the markup language. ### Repository README and index files -When a `README` or `index` file is present in a repository, its contents will be +When a `README` or `index` file is present in a repository, its contents are automatically pre-rendered by GitLab without opening it. They can either be plain text or have an extension of a @@ -101,12 +100,12 @@ They can either be plain text or have an extension of a Some things to note about precedence: -1. When both a `README` and an `index` file are present, the `README` will always - take precedence. +1. When both a `README` and an `index` file are present, the `README` always + takes precedence. 1. When more than one file is present with different extensions, they are - ordered alphabetically, with the exception of a file without an extension - which will always be last in precedence. For example, `README.adoc` will take - precedence over `README.md`, and `README.rst` will take precedence over + ordered alphabetically, with the exception of a file without an extension, + which is always last in precedence. For example, `README.adoc` takes + precedence over `README.md`, and `README.rst` takes precedence over `README`. ### Jupyter Notebook files @@ -159,18 +158,18 @@ Via command line, you can commit multiple times before pushing. - **Commit message:** A commit message is important to identity what is being changed and, more importantly, why. In GitLab, you can add keywords to the commit - message that will perform one of the actions below: + message that performs one of the actions below: - **Trigger a GitLab CI/CD pipeline:** If you have your project configured with [GitLab CI/CD](../../../ci/README.md), - you will trigger a pipeline per push, not per commit. + you trigger a pipeline per push, not per commit. - **Skip pipelines:** - You can add to you commit message the keyword - [`[ci skip]`](../../../ci/yaml/README.md#skip-pipeline) - and GitLab CI/CD will skip that pipeline. + You can add to your commit message the keyword + [`[ci skip]`](../../../ci/yaml/README.md#skip-pipeline), + and GitLab CI/CD skips that pipeline. - **Cross-link issues and merge requests:** [Cross-linking](../issues/crosslinking_issues.md#from-commit-messages) is great to keep track of what's is somehow related in your workflow. - If you mention an issue or a merge request in a commit message, they will be shown + If you mention an issue or a merge request in a commit message, they are shown on their respective thread. - **Cherry-pick a commit:** In GitLab, you can @@ -211,9 +210,9 @@ Find it under your project's **Repository > Graph**. ## Repository Languages -For the default branch of each repository, GitLab will determine what programming languages -were used and display this on the projects pages. If this information is missing, it will -be added after updating the default branch on the project. This process can take up to 5 +For the default branch of each repository, GitLab determines what programming languages +were used and displays this on the project's pages. If this information is missing, it's +added after updating the default branch for the project. This process can take up to five minutes.  @@ -253,8 +252,8 @@ into Xcode on macOS. To do that: 1. Click **Clone**. 1. Select **Xcode**. -The project will be cloned onto your computer in a folder of your choice and you'll -be prompted to open in XCode. +The project is cloned onto your computer in a folder of your choice and you are +prompted to open XCode. ### Clone and open in Visual Studio Code @@ -264,10 +263,10 @@ All projects can be cloned into Visual Studio Code. To do that: 1. From the GitLab UI, go to the project's overview page. 1. Click **Clone**. -1. Select **VS Code** +1. Select **VS Code**. +1. Select a folder to clone the project into. -You'll be prompted to select a folder to clone the project into. When VS Code has -successfully cloned your project, it will open the folder. +When VS Code has successfully cloned your project, it opens the folder. ## Download Source Code @@ -275,7 +274,7 @@ successfully cloned your project, it will open the folder. > - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. The source code stored in a repository can be downloaded from the UI. -By clicking the download icon, a dropdown will open with links to download the following: +By clicking the download icon, a dropdown opens with links to download the following:  @@ -298,7 +297,7 @@ and Git push/pull redirects. 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): +[changing a group path](../../group/index.md#change-a-groups-path) or [renaming a repository](../settings/index.md#renaming-a-repository): - Existing web URLs for the namespace and anything under it (such as projects) will redirect to the new URLs. diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 123df9097f9..e4a3e6d6ef1 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -12,12 +12,12 @@ type: reference interactive computing in many fields and contain a complete record of the user's sessions and include code, narrative text, equations, and rich output. -When added to a repository, Jupyter Notebooks with a `.ipynb` extension will be +When added to a repository, Jupyter Notebooks with a `.ipynb` extension are rendered to HTML when viewed.  -Interactive features, including JavaScript plots, will not work when viewed in +Interactive features, including JavaScript plots, don't work when viewed in GitLab. ## Jupyter Hub as a GitLab Managed App diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 4d5e4a5ef02..980c5417da6 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -7,19 +7,19 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.htm # Repository mirroring **(FREE)** -Repository mirroring allows for mirroring of repositories to and from external sources. It can be -used to mirror branches, tags, and commits between repositories. It is useful when you want to use +Repository mirroring allows for the mirroring of repositories to and from external sources. You +can use it to mirror branches, tags, and commits between repositories. It's useful when you want to use a repository outside of GitLab. -A repository mirror at GitLab will be updated automatically. You can also manually trigger an update -at most once every 5 minutes on GitLab.com with [the limit set by the administrator on self-managed instances](../../../administration/instance_limits.md#pull-mirroring-interval). +A repository mirror at GitLab updates automatically. You can also manually trigger an update +at most once every five minutes on GitLab.com with [the limit set by the administrator on self-managed instances](../../../administration/instance_limits.md#pull-mirroring-interval). There are two kinds of repository mirroring supported by GitLab: - [Push](#pushing-to-a-remote-repository): for mirroring a GitLab repository to another location. **(FREE)** - [Pull](#pulling-from-a-remote-repository): for mirroring a repository from another location to GitLab. **(PREMIUM)** -When the mirror repository is updated, all new branches, tags, and commits will be visible in the +When the mirror repository is updated, all new branches, tags, and commits are visible in the project's activity feed. Users with at least [Developer access](../../permissions.md) to the project can also force an @@ -37,7 +37,7 @@ The following are some possible use cases for repository mirroring: - You migrated to GitLab but still need to keep your project in another source. In that case, you can simply set it up to mirror to GitLab (pull) and all the essential history of commits, tags, - and branches will be available in your GitLab instance. **(PREMIUM)** + and branches are available in your GitLab instance. **(PREMIUM)** - You have old projects in another source that you don't use actively anymore, but don't want to remove for archiving purposes. In that case, you can create a push mirror so that your active GitLab repository can push its changes to the old location. @@ -49,25 +49,23 @@ The following are some possible use cases for repository mirroring: ## Pushing to a remote repository **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249) in GitLab Enterprise Edition 8.7. -> - [Moved to GitLab Free](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18715) in 10.8. -> - [LFS support over HTTPS added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in 13.5 +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in GitLab 13.5: LFS support over HTTPS. For an existing project, you can set up push mirroring as follows: -1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. +1. In your project, go to **Settings > Repository**, and then expand the **Mirroring repositories** section. 1. Enter a repository URL. -1. Select **Push** from the **Mirror direction** dropdown. +1. In the **Mirror direction** dropdown, select **Push**. 1. Select an authentication method from the **Authentication method** dropdown. You can authenticate with either a password or an [SSH key](#ssh-authentication). -1. Check the **Only mirror protected branches** box, if necessary. -1. Check the **Keep divergent refs** box, if desired. -1. Click the **Mirror repository** button to save the configuration. +1. Select the **Only mirror protected branches** check box, if necessary. +1. Select the **Keep divergent refs** check box, if desired. +1. Select **Mirror repository** to save the configuration.  When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the -mirror diverging. All changes will end up in the mirrored repository whenever: +mirror diverging. The mirrored repository receives all changes when: - Commits are pushed to GitLab. - A [forced update](#forcing-an-update) is initiated. @@ -77,7 +75,7 @@ Changes pushed to files in the repository are automatically pushed to the remote - Within five minutes of being received. - Within one minute if **Only mirror protected branches** is enabled. -In the case of a diverged branch, you will see an error indicated at the **Mirroring repositories** +In the case of a diverged branch, an error displays in the **Mirroring repositories** section. ### Configuring push mirrors through the API @@ -87,20 +85,20 @@ You can also create and modify project push mirrors through the ### Keep divergent refs -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0. By default, if any ref on the remote mirror has diverged from the local -repository, the *entire push* will fail, and nothing will be updated. +repository, the *entire push* fails, and no updates occur. For example, if a repository has `master`, `develop`, and `stable` branches that have been mirrored to a remote, and then a new commit is added to `develop` on -the mirror, the next push attempt will fail, leaving `master` and `stable` +the mirror, the next push attempt fails, leaving `master` and `stable` out-of-date despite not having diverged. No change on any branch can be mirrored until the divergence is resolved. With the **Keep divergent refs** option enabled, the `develop` branch is -skipped, allowing `master` and `stable` to be updated. The mirror status will -reflect that `develop` has diverged and was skipped, and be marked as a failed +skipped, allowing `master` and `stable` to be updated. The mirror status +reflects that `develop` has diverged and was skipped, and be marked as a failed update. NOTE: @@ -110,18 +108,18 @@ After the mirror is created, this option can currently only be modified via the To set up a mirror from GitLab to GitHub, you need to follow these steps: -1. Create a [GitHub personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) with the `public_repo` box checked. +1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the `public_repo` box checked. 1. Fill in the **Git repository URL** field using this format: `https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git`. 1. Fill in **Password** field with your GitHub personal access token. -1. Click the **Mirror repository** button. +1. Select **Mirror repository**. -The mirrored repository will be listed. For example, `https://*****:*****@github.com/<your_github_group>/<your_github_project>.git`. +The mirrored repository is listed. For example, `https://*****:*****@github.com/<your_github_group>/<your_github_project>.git`. -The repository will push soon. To force a push, click the **Update now** (**{retry}**) button. +The repository pushes shortly thereafter. To force a push, select the **Update now** (**{retry}**) button. ### Setting up a push mirror from GitLab to AWS CodeCommit -AWS CodeCommit push mirroring is currently the best way to connect GitLab repositories to AWS CodePipeline, as GitLab is not yet supported as one of their Source Code Management (SCM) providers. +AWS CodeCommit push mirroring is currently the best way to connect GitLab repositories to AWS CodePipeline, as GitLab isn't yet supported as one of their Source Code Management (SCM) providers. Each new AWS CodePipeline needs significant AWS infrastructure setup. It also requires an individual pipeline per branch. @@ -159,9 +157,9 @@ To set up a mirror from GitLab to AWS CodeCommit: } ``` -1. After the user was created, click the AWS IAM user name. -1. Click the **Security credentials** tab. -1. Under **HTTPS Git credentials for AWS CodeCommit** click **Generate credentials**. +1. After the user was created, select the AWS IAM user name. +1. Select the **Security credentials** tab. +1. Under **HTTPS Git credentials for AWS CodeCommit** select **Generate credentials**. NOTE: This Git user ID and password is specific to communicating with CodeCommit. Do @@ -169,9 +167,9 @@ To set up a mirror from GitLab to AWS CodeCommit: 1. Copy or download special Git HTTPS user ID and password. 1. In the AWS CodeCommit console, create a new repository to mirror from your GitLab repository. -1. Open your new repository and click **Clone URL > Clone HTTPS** (not **Clone HTTPS (GRC)**). +1. Open your new repository, and then select **Clone URL > Clone HTTPS** (not **Clone HTTPS (GRC)**). 1. In GitLab, open the repository to be push-mirrored. -1. Click **Settings > Repository** and expand **Mirroring repositories**. +1. Go to **Settings > Repository**, and then expand **Mirroring repositories**. 1. Fill in the **Git repository URL** field using this format: ```plaintext @@ -185,17 +183,17 @@ To set up a mirror from GitLab to AWS CodeCommit: 1. For **Authentication method**, select **Password** and fill in the **Password** field with the special IAM Git clone user ID **password** created earlier in AWS. 1. The option **Only mirror protected branches** should be good for CodeCommit as it pushes more frequently (from every five minutes to every minute). - CodePipeline requires individual pipeline setups for named branches you wish to have a AWS CI setup for. Since feature branches that have dynamic names will not be supported anyway, configuring **Only mirror protected branches** does not cause flexibility problems with CodePipeline integration as long as you are also willing to protect all the named branches you want to build CodePipelines for. + CodePipeline requires individual pipeline setups for named branches you wish to have a AWS CI setup for. Because feature branches that have dynamic names are unsupported, configuring **Only mirror protected branches** doesn't cause flexibility problems with CodePipeline integration as long as you are also willing to protect all the named branches you want to build CodePipelines for. -1. Click **Mirror repository**. You should see the mirrored repository appear: +1. Select **Mirror repository**. You should see the mirrored repository appear: ```plaintext https://*****:*****@git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> ``` -To test mirroring by forcing a push, click the half-circle arrows button (hover text is **Update now**). +To test mirroring by forcing a push, select the half-circle arrows button (hover text is **Update now**). If **Last successful update** shows a date, you have configured mirroring correctly. -If it is not working correctly a red `error` tag appears and shows the error message as hover text. +If it isn't working correctly, a red `error` tag appears and shows the error message as hover text. ### Setting up a push mirror to another GitLab instance with 2FA activated @@ -203,11 +201,10 @@ If it is not working correctly a red `error` tag appears and shows the error mes 1. On the source GitLab instance: 1. Fill in the **Git repository URL** field using this format: `https://oauth2@<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`. 1. Fill in the **Password** field with the GitLab personal access token created on the destination GitLab instance. - 1. Click the **Mirror repository** button. + 1. Select **Mirror repository**. ## Pulling from a remote repository **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51) in GitLab Enterprise Edition 8.2. > - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/-/issues/10871) in GitLab 11.11. > - Moved to GitLab Premium in 13.9. @@ -219,16 +216,20 @@ to be able to browse its content and its activity using the familiar GitLab inte To configure mirror pulling for an existing project: -1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** - section. -1. Enter a repository URL. -1. Select **Pull** from the **Mirror direction** dropdown. -1. Select an authentication method from the **Authentication method** dropdown, if necessary. -1. If necessary, check the following boxes: - - **Overwrite diverged branches**. - - **Trigger pipelines for mirror updates**. - - **Only mirror protected branches**. -1. Click the **Mirror repository** button to save the configuration. +1. If you [configured two-factor authentication (2FA)](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa) + for GitHub, create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) + with the `read_repository` scope. If 2FA is enabled, this personal access + token serves as your GitHub password. +1. In your project, go to **Settings > Repository**, and then expand the + **Mirroring repositories** section. +1. In the **Git repository URL** field, enter a repository URL. +1. In the **Mirror direction** dropdown, select **Pull**. +1. In the **Authentication method** dropdown, select your authentication method. +1. Select from the following checkboxes, if needed: + - **Overwrite diverged branches** + - **Trigger pipelines for mirror updates** + - **Only mirror protected branches** +1. Select **Mirror repository** to save the configuration.  @@ -238,15 +239,15 @@ To configure mirror pulling for an existing project: Because GitLab is now set to pull changes from the upstream repository, you should not push commits directly to the repository on GitLab. Instead, any commits should be pushed to the remote repository. -Changes pushed to the remote repository will be pulled into the GitLab repository, either: +Changes pushed to the remote repository are pulled into the GitLab repository, either: - Automatically within a certain period of time. - When a [forced update](#forcing-an-update) is initiated. WARNING: -If you do manually update a branch in the GitLab repository, the branch will become diverged from -upstream and GitLab will no longer automatically update this branch to prevent any changes from being lost. -Also note that deleted branches and tags in the upstream repository will not be reflected in the GitLab repository. +If you do manually update a branch in the GitLab repository, the branch becomes diverged from +upstream, and GitLab no longer automatically updates this branch to prevent any changes from being lost. +Deleted branches and tags in the upstream repository are not reflected in the GitLab repository. ### How it works @@ -259,13 +260,12 @@ Once per minute, a Sidekiq cron job schedules repository mirrors to update, base Repository mirrors are updated as Sidekiq becomes available to process them. If the process of updating the repository mirror: -- Succeeds, an update will be enqueued again with at least a 30 minute wait. -- Fails (for example, a branch diverged from upstream), it will be attempted again later. Mirrors can fail - up to 14 times before they will not be enqueued for update again. +- **Succeeds**: An update is enqueued again with at least a 30 minute wait. +- **Fails**: (For example, a branch diverged from upstream.), The update attempted again later. Mirrors can fail + up to 14 times before they are no longer enqueued for updates. ### Overwrite diverged branches **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4559) in GitLab 10.6. > - Moved to GitLab Premium in 13.9. You can choose to always update your local branches with remote versions, even if they have @@ -278,42 +278,39 @@ To use this option, check the **Overwrite diverged branches** box when creating ### Trigger pipelines for mirror updates **(PREMIUM)** -> Moved to GitLab Premium in 13.9. +> - Moved to GitLab Premium in 13.9. -If this option is enabled, pipelines will be triggered when branches or tags are +If this option is enabled, pipelines trigger when branches or tags are updated from the remote repository. Depending on the activity of the remote repository, this may greatly increase the load on your CI runners. Only enable -this if you know they can handle the load. CI will run using the credentials +this if you know they can handle the load. CI uses the credentials assigned when you set up pull mirroring. ### Hard failure **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3117) in GitLab 10.2. > - Moved to GitLab Premium in 13.9. -Once the mirroring process is unsuccessfully retried 14 times in a row, it will get marked as hard -failed. This will become visible in either the: +After 14 consecutive unsuccessful retries, the mirroring process is marked as a hard failure +and mirroring attempts stop. This failure is visible in either the: - Project's main dashboard. - Pull mirror settings page. -When a project is hard failed, it will no longer get picked up for mirroring. You can resume the project mirroring again by [forcing an update](#forcing-an-update). ### Trigger an update using the API **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in GitLab 10.3. > - Moved to GitLab Premium in 13.9. Pull mirroring uses polling to detect new branches and commits added upstream, often minutes afterwards. If you notify GitLab by [API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project), -updates will be pulled immediately. +updates are pulled immediately. For more information, see [Start the pull mirroring process for a Project](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project). ## Mirror only protected branches **(PREMIUM)** -> Moved to GitLab Premium in 13.9. +> - Moved to GitLab Premium in 13.9. Based on the mirror direction that you choose, you can opt to mirror only the [protected branches](../protected_branches.md) from/to your remote repository. @@ -324,7 +321,6 @@ creating a repository mirror. **(PREMIUM)** ## SSH authentication -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2551) in GitLab 9.5 for Pull mirroring. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in GitLab 11.6 for Push mirroring. SSH authentication is mutual: @@ -336,15 +332,15 @@ You provide your credentials as a password or public key. The server that the other repository resides on provides its credentials as a "host key", the fingerprint of which needs to be verified manually. -If you're mirroring over SSH (that is, using an `ssh://` URL), you can authenticate using: +If you're mirroring over SSH (using an `ssh://` URL), you can authenticate using: - Password-based authentication, just as over HTTPS. - Public key authentication. This is often more secure than password authentication, - especially when the other repository supports [deploy keys](../../../ssh/README.md#deploy-keys). + especially when the other repository supports [deploy keys](../deploy_keys/index.md). To get started: -1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. +1. In your project, go to **Settings > Repository**, and then expand the **Mirroring repositories** section. 1. Enter an `ssh://` URL for mirroring. NOTE: @@ -355,9 +351,9 @@ Entering the URL adds two buttons to the page: - **Detect host keys**. - **Input host keys manually**. -If you click the: +If you select the: -- **Detect host keys** button, GitLab will fetch the host keys from the server and display the fingerprints. +- **Detect host keys** button, GitLab fetches the host keys from the server and display the fingerprints. - **Input host keys manually** button, a field is displayed where you can paste in host keys. Assuming you used the former, you now need to verify that the fingerprints are @@ -366,13 +362,13 @@ fingerprints in the open for you to check: - [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) - [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/) -- [GitHub](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/githubs-ssh-key-fingerprints) +- [GitHub](https://docs.github.com/en/github/authenticating-to-github/githubs-ssh-key-fingerprints) - [GitLab.com](../../gitlab_com/index.md#ssh-host-keys-fingerprints) - [Launchpad](https://help.launchpad.net/SSHFingerprints) - [Savannah](http://savannah.gnu.org/maintenance/SshAccess/) - [SourceForge](https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/) -Other providers will vary. If you're running self-managed GitLab, or otherwise +Other providers vary. If you're running self-managed GitLab, or otherwise have access to the server for the other repository, you can securely gather the key fingerprints: @@ -386,28 +382,28 @@ $ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f - NOTE: You may need to exclude `-E md5` for some older versions of SSH. -When mirroring the repository, GitLab will now check that at least one of the +When mirroring the repository, GitLab checks that at least one of the stored host keys matches before connecting. This can prevent malicious code from being injected into your mirror, or your password being stolen. ### SSH public key authentication -To use SSH public key authentication, you'll also need to choose that option +To use SSH public key authentication, you must also choose that option from the **Authentication method** dropdown. When the mirror is created, -GitLab generates a 4096-bit RSA key that can be copied by clicking the **Copy SSH public key** button. +GitLab generates a 4096-bit RSA key that can be copied by selecting the **Copy SSH public key** button.  You then need to add the public SSH key to the other repository's configuration: - If the other repository is hosted on GitLab, you should add the public SSH key - as a [deploy key](../../../ssh/README.md#deploy-keys). + as a [deploy key](../../project/deploy_keys/index.md). - If the other repository is hosted elsewhere, you may need to add the key to your user's `authorized_keys` file. Paste the entire public SSH key into the file on its own line and save it. If you need to change the key at any time, you can remove and re-add the mirror -to generate a new key. You'll have to update the other repository with the new +to generate a new key. Update the other repository with the new key to keep the mirror running. NOTE: @@ -423,17 +419,17 @@ update button which is available on the **Mirroring repositories** section of th ## Bidirectional mirroring **(PREMIUM)** -> Moved to GitLab Premium in 13.9. +> - Moved to GitLab Premium in 13.9. WARNING: Bidirectional mirroring may cause conflicts. If you configure a GitLab repository to both pull from, and push to, the same remote source, there -is no guarantee that either repository will update correctly. If you set up a repository for -bidirectional mirroring, you should prepare for the likely conflicts by deciding who will resolve -them and how they will be resolved. +is no guarantee that either repository updates correctly. If you set up a repository for +bidirectional mirroring, you should prepare for the likely conflicts by deciding who resolves +them and how. -Rewriting any mirrored commit on either remote will cause conflicts and mirroring to fail. This can +Rewriting any mirrored commit on either remote causes conflicts and mirroring to fail. This can be prevented by [mirroring only protected branches](#mirror-only-protected-branches). You should [protect the branches](../protected_branches.md) you wish to mirror on both @@ -447,34 +443,35 @@ protected branches. ### Configure a webhook to trigger an immediate pull to GitLab -Assuming you have already configured the [push](#setting-up-a-push-mirror-to-another-gitlab-instance-with-2fa-activated) and [pull](#pulling-from-a-remote-repository) mirrors in the upstream GitLab instance, to trigger an immediate pull as suggested above, you will need to configure a [Push Event Web Hook](../integrations/webhooks.md#push-events) in the downstream instance. +Assuming you have already configured the [push](#setting-up-a-push-mirror-to-another-gitlab-instance-with-2fa-activated) and [pull](#pulling-from-a-remote-repository) mirrors in the upstream GitLab instance, to trigger an immediate pull as suggested above, you must configure a [Push Event Web Hook](../integrations/webhooks.md#push-events) in the downstream instance. To do this: -- Create a [personal access token](../../profile/personal_access_tokens.md) with `API` scope. -- Navigate to **Settings > Webhooks** -- Add the webhook URL which in this case will use the [Pull Mirror API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) request to trigger an immediate pull after updates to the repository. +1. Create a [personal access token](../../profile/personal_access_tokens.md) with `API` scope. +1. In your project, go to **Settings > Webhooks**. +1. Add the webhook URL which (in this case) uses the [Pull Mirror API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) request to trigger an immediate pull after updates to the repository. - ```plaintext - https://gitlab.example.com/api/v4/projects/:id/mirror/pull?private_token=<your_access_token> - ``` + ```plaintext + https://gitlab.example.com/api/v4/projects/:id/mirror/pull?private_token=<your_access_token> + ``` + +1. Ensure the **Push Events** checkbox is selected. +1. Select **Add Webhook** to save the webhook. -- Ensure that the **Push Events** checkbox is selected. -- Click on **Add Webhook** button to save the webhook. -- To test the integration click on the **Test** button and confirm GitLab does not return any error. +To test the integration, select the **Test** button and confirm GitLab doesn't return an error message. ### Preventing conflicts using a `pre-receive` hook WARNING: -The solution proposed will negatively impact the performance of -Git push operations because they will be proxied to the upstream Git +The solution proposed negatively affects the performance of +Git push operations because they are proxied to the upstream Git repository. A server-side `pre-receive` hook can be used to prevent the race condition described above by only accepting the push after first pushing the commit to the upstream Git repository. In this configuration one Git repository acts as the authoritative upstream, and the other as downstream. The `pre-receive` hook -will be installed on the downstream repository. +is installed on the downstream repository. Read about [configuring Server hooks](../../../administration/server_hooks.md) on the GitLab server. @@ -540,11 +537,11 @@ fi Note that this sample has a few limitations: - This example may not work verbatim for your use case and might need modification. - - It does not regard different types of authentication mechanisms for the mirror. - - It does not work with forced updates (rewriting history). - - Only branches that match the `allowlist` patterns will be proxy pushed. + - It doesn't regard different types of authentication mechanisms for the mirror. + - It doesn't work with forced updates (rewriting history). + - Only branches that match the `allowlist` patterns are proxy pushed. - The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` - is seen as a ref update and Git will complain about it. + is seen as a ref update, and Git displays warnings about it. ### Mirroring with Perforce Helix via Git Fusion **(PREMIUM)** @@ -560,22 +557,22 @@ mirror projects with GitLab. This may be useful in some situations when migratin to GitLab where overlapping Perforce Helix workspaces cannot be migrated simultaneously to GitLab. If using mirroring with Perforce Helix, you should only mirror protected branches. Perforce Helix -will reject any pushes that rewrite history. Only the fewest number of branches should be mirrored +rejects any pushes that rewrite history. Only the fewest number of branches should be mirrored due to the performance limitations of Git Fusion. When configuring mirroring with Perforce Helix via Git Fusion, the following Git Fusion settings are recommended: -- `change-pusher` should be disabled. Otherwise, every commit will be rewritten as being committed +- `change-pusher` should be disabled. Otherwise, every commit is rewritten as being committed by the mirroring account, rather than being mapped to existing Perforce Helix users or the `unknown_git` user. -- `unknown_git` user will be used as the commit author if the GitLab user does not exist in +- `unknown_git` user is used as the commit author if the GitLab user doesn't exist in Perforce Helix. Read about [Git Fusion settings on Perforce.com](https://www.perforce.com/manuals/git-fusion/Content/Git-Fusion/section_vss_bdw_w3.html#section_zdp_zz1_3l). ## Troubleshooting -Should an error occur during a push, GitLab will display an "Error" highlight for that repository. Details on the error can then be seen by hovering over the highlight text. +Should an error occur during a push, GitLab displays an **Error** highlight for that repository. Details on the error can then be seen by hovering over the highlight text. ### 13:Received RST_STREAM with error code 2 with GitHub @@ -584,3 +581,9 @@ If you receive an "13:Received RST_STREAM with error code 2" while mirroring to ### 4:Deadline Exceeded When upgrading to GitLab 11.11.8 or newer, a change in how usernames are represented means that you may need to update your mirroring username and password to ensure that `%40` characters are replaced with `@`. + +### Connection blocked because server only allows public key authentication + +As the error indicates, the connection is getting blocked between GitLab and the remote repository. Even if a [TCP Check](../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) is successful, you must check any networking components in the route from GitLab to the remote Server to ensure there's no blockage. + +For example, we've seen this error when a Firewall was performing a `Deep SSH Inspection` on outgoing packets. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index a9e249bb8c3..efa35c1ceac 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# GitLab Web Editor +# GitLab Web Editor **(FREE)** Sometimes it's easier to make quick changes directly from the GitLab interface than to clone the project and use the Git command-line tool. In this feature @@ -108,7 +108,7 @@ You can see a **Create merge request** dropdown below the issue description. The **Create merge request** button doesn't display if: - A branch with the same name already exists. -- The branch already has a referenced merge request. +- A merge request already exists for this branch. - Your project has an active fork relationship. To make this button appear, one possible workaround is to diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 29c1c32145d..c89f3a267ba 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -39,7 +39,7 @@ recommend using certificates from a PKI that are in line with ## Obtaining an X.509 key pair -If your organization has Public Key Infrastructure (PKI), that PKI will provide +If your organization has Public Key Infrastructure (PKI), that PKI provides an S/MIME key. If you do not have an S/MIME key pair from a PKI, you can either create your @@ -49,7 +49,7 @@ and some of them generate keys for free. ## Associating your X.509 certificate with Git -To take advantage of X.509 signing, you will need Git 2.19.0 or later. You can +To take advantage of X.509 signing, you need Git 2.19.0 or later. You can check your Git version with: ```shell diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index c7dda81685c..bd37acafd22 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -96,18 +96,20 @@ As soon as a requirement is reopened, it no longer appears in the **Archived** t ## Search for a requirement -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212543) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212543) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. +> - Searching by status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/224614) in GitLab 13.10. You can search for a requirement from the requirements list page based on the following criteria: -- Requirement title +- Title - Author's username +- Status (satisfied, failed, or missing) To search for a requirement: 1. In a project, go to **Requirements > List**. 1. Select the **Search or filter results** field. A dropdown menu appears. -1. Select the requirement author from the dropdown or enter plain text to search by requirement title. +1. Select the requirement author or status from the dropdown or enter plain text to search by requirement title. 1. Press <kbd>Enter</kbd> on your keyboard to filter the list. You can also sort the requirements list by: @@ -183,7 +185,7 @@ requirements_confirmation: ### Add the manual job to CI conditionally To configure your CI to include the manual job only when there are some open -requirements, add a rule which checks `CI_HAS_OPEN_REQUIREMENTS` CI variable. +requirements, add a rule which checks `CI_HAS_OPEN_REQUIREMENTS` CI/CD variable. ```yaml requirements_confirmation: diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index debe5c51d51..383b4df9612 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -73,7 +73,7 @@ To enable Service Desk in your project: 1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues to the project. -Service Desk is now enabled for this project! To access it in a project, in the left sidebar, select +Service Desk is now enabled for this project! To access it in a project, in the left sidebar, select **Issues > Service Desk**. WARNING: @@ -137,13 +137,13 @@ You can use these placeholders to be automatically replaced in each email: #### New Service Desk issues -You can select one [issue description template](description_templates.md#creating-issue-templates) +You can select one [issue description template](description_templates.md#create-an-issue-template) **per project** to be appended to every new Service Desk issue's description. Issue description templates should reside in your repository's `.gitlab/issue_templates/` directory. To use a custom issue template with Service Desk, in your project: -1. [Create a description template](description_templates.md#creating-issue-templates) +1. [Create a description template](description_templates.md#create-an-issue-template) 1. Go to **Settings > General > Service Desk**. 1. From the dropdown **Template to append to all Service Desk issues**, select your template. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 6f230f1798a..7b5a0cbb377 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -118,16 +118,16 @@ The following items will be exported: - Issue boards - Pipelines history - Push Rules +- Awards The following items will **not** be exported: - Build traces and artifacts - Container registry images -- CI variables +- CI/CD variables - Webhooks - Any encrypted tokens - Merge Request Approvers -- Awards NOTE: For more details on the specific data persisted in a project export, see the diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 8ab82fe7296..785618a862a 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -44,6 +44,7 @@ Compliance framework labels do not affect your project settings. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. > - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It can be enabled or disabled for a single group > - It's disabled on GitLab.com. > - It's not recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-custom-compliance-frameworks). **(PREMIUM)** @@ -103,8 +104,7 @@ Some features depend on others: When the **Issues** option is disabled, you can still access **Milestones** from merge requests. -- Additionally, if you disable both **Issues** and **Merge Requests**, you will no - longer have access to: +- Additionally, if you disable both **Issues** and **Merge Requests**, you cannot access: - **Labels** - **Milestones** @@ -220,7 +220,7 @@ To rename a repository: 1. Click **Change path**. Remember that this can have unintended side effects since everyone with the -old URL won't be able to push or pull. Read more about what happens with the +old URL can't push or pull. Read more about what happens with the [redirects when renaming repositories](../repository/index.md#redirects-when-changing-repository-paths). #### Transferring an existing project into another namespace @@ -243,7 +243,7 @@ To transfer a project: project to. 1. Confirm the transfer by typing the project's path as instructed. -Once done, you will be taken to the new project's namespace. At this point, +Once done, you are redirected to the new project's namespace. At this point, read what happens with the [redirects from the old project to the new one](../repository/index.md#redirects-when-changing-repository-paths). @@ -266,7 +266,7 @@ This action: - Deletes a project including all associated resources (issues, merge requests etc). - From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium](https://about.gitlab.com/pricing/) or higher tiers, -group owners can [configure](../../group/index.md#enabling-delayed-project-removal) projects within a group +group owners can [configure](../../group/index.md#enable-delayed-project-removal) projects within a group to be deleted after a delayed period. When enabled, actual deletion happens after number of days specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). @@ -293,7 +293,7 @@ If you want to use the fork for yourself and don't need to send you can safely remove the fork relationship. WARNING: -Once removed, the fork relationship cannot be restored. You will no longer be able to send merge requests to the source, and if anyone has forked your project, their fork will also lose the relationship. +Once removed, the fork relationship cannot be restored. You can't send merge requests to the source, and if anyone has forked your project, their fork also loses the relationship. To do so: @@ -330,11 +330,11 @@ can enable it. To enable it: ```ruby -Feature.enable(:ff_custom_compliance_frameworks) +Feature.enable(:ff_custom_compliance_frameworks, Group.find(<group id>)) ``` To disable it: ```ruby -Feature.disable(:ff_custom_compliance_frameworks) +Feature.disable(:ff_custom_compliance_frameworks, Group.find(<group id>)) ``` diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 590f549577e..cda39508835 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -78,33 +78,3 @@ the following table. | `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | | `read_repository` | Allows read-only access (pull) to the repository. | | `write_repository` | Allows read-write access (pull, push) to the repository. | - -### Enable or disable project access tokens - -Project access tokens are deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it for your instance, globally or by project. - -To disable it globally: - -```ruby -Feature.disable(:resource_access_token) -``` - -To disable it for a specific project: - -```ruby -Feature.disable(:resource_access_token, project) -``` - -To enable it globally: - -```ruby -Feature.enable(:resource_access_token) -``` - -To enable it for a specific project: - -```ruby -Feature.enable(:resource_access_token, project) -``` diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 002eb398406..431250a817d 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -102,7 +102,7 @@ To edit a file: in the bottom-right corner. 1. When you're done, click **Submit changes...**. 1. (Optional) Adjust the default title and description of the merge request, to submit - with your changes. Alternatively, select a [merge request template](../../../user/project/description_templates.md#creating-merge-request-templates) + with your changes. Alternatively, select a [merge request template](../../../user/project/description_templates.md#create-a-merge-request-template) from the dropdown menu and edit it accordingly. 1. Click **Submit changes**. 1. A new merge request is automatically created and you can assign a colleague for review. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 2b0ca38c57c..d1e9fe155b4 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -40,7 +40,8 @@ Below is an example of how you can use those new quick actions inside a comment.  -Adding time entries (time spent or estimates) is limited to project members. +Adding time entries (time spent or estimates) is limited to project members +with [Reporter and higher permission levels](../permissions.md). ### Estimates diff --git a/doc/user/project/web_ide/img/solarized_dark_theme_v13_1.png b/doc/user/project/web_ide/img/solarized_dark_theme_v13_1.png Binary files differindex ccb9cf6f126..8eca352a4d0 100644 --- a/doc/user/project/web_ide/img/solarized_dark_theme_v13_1.png +++ b/doc/user/project/web_ide/img/solarized_dark_theme_v13_1.png diff --git a/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png b/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png Binary files differdeleted file mode 100644 index 6257d78d29e..00000000000 --- a/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png +++ /dev/null diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 07f46cb94f7..57b79875909 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -71,19 +71,16 @@ Single file editing is based on the [Ace Editor](https://ace.c9.io). ### Themes -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab in 13.0. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab 13.0. > - Full Solarized Dark Theme [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219228) in GitLab 13.1. +> - Full [Solarized Light](https://gitlab.com/gitlab-org/gitlab/-/issues/221035) and [Monokai](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) Themes introduced in GitLab 13.6. -All the themes GitLab supports for syntax highlighting are added to the Web IDE's code editor. +All the themes GitLab supports for syntax highlighting are applied to the Web IDE's entire screen. You can pick a theme from your [profile preferences](../../profile/preferences.md). -The themes are available only in the Web IDE file editor, except for the [dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/209808) and -the [Solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228), -which apply to the entire Web IDE screen. - -| Solarized Light Theme | Solarized Dark Theme | Dark Theme | -|---------------------------------------------------------------|-------------------------------------------------------------|-----------------------------------------| -|  |  |  | +| Solarized Dark Theme | Dark Theme | +|-------------------------------------------------------------|-----------------------------------------| +|  |  | ## Schema based validation @@ -237,7 +234,7 @@ different branch. When you edit Markdown files in the Web IDE, you can preview your changes by clicking the **Preview Markdown** tab above the file editor. The Markdown preview -supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). +supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). You can also upload any local images by pasting them directly in the Markdown file. The image is uploaded to the same directory and is named `image.png` by default. @@ -424,7 +421,7 @@ terminal: See [this issue](https://gitlab.com/gitlab-org/webide-file-sync/-/issues/7) for more information. - `$CI_PROJECT_DIR` is a - [predefined environment variable](../../../ci/variables/predefined_variables.md) + [predefined CI/CD variable](../../../ci/variables/predefined_variables.md) for GitLab Runners. This is where your project's repository resides. After you have configured the web terminal for file syncing, then when the web diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 187fcb5b3f9..44860a0030e 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -24,9 +24,9 @@ a separate Git repository. ## First time creating the Home page -The first time you visit a Wiki, you will be directed to create the Home page. -The Home page is necessary to be created since it serves as the landing page -when viewing a Wiki. You only have to fill in the **Content** section and click +The first time you visit a Wiki, you are directed to create the Home page. +The Home page is necessary to be created because it serves as the landing page +when viewing a Wiki. Complete the **Content** section, and then select **Create page**. You can always edit it later, so go ahead and write a welcome message. @@ -37,38 +37,38 @@ message. NOTE: Requires Developer [permissions](../../permissions.md). -Create a new page by clicking the **New page** button that can be found +Create a new page by selecting the **New page** button that can be found in all wiki pages. -You will be asked to fill in a title for your new wiki page. +Enter a title for your new wiki page. You can specify a full path for the wiki page by using '/' in the -title to indicate subdirectories. Any missing directories will be created -automatically. For example, a title of `docs/my-page` will create a wiki +title to indicate subdirectories. Any missing directories are created +automatically. For example, a title of `docs/my-page` creates a wiki page with a path `/wikis/docs/my-page`. -Once you enter the page name, it's time to fill in its content. GitLab wikis +After you enter the page name, it's time to fill in its content. GitLab wikis support Markdown, RDoc, AsciiDoc, and Org. For Markdown based pages, all the [Markdown features](../../markdown.md) are supported and for links there is some [wiki specific](../../markdown.md#wiki-specific-markdown) behavior. In the web interface the commit message is optional, but the GitLab Wiki is -based on Git and needs a commit message, so one will be created for you if you -do not enter one. +based on Git and needs a commit message, so one is created for you if you +don't enter one. -When you're ready, click the **Create page** and the new page will be created. +When you're ready, select **Create page** and the new page is created.  ### Attachment storage -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475) in GitLab 11.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475) in GitLab 11.3. -Starting with GitLab 11.3, any file that is uploaded to the wiki via the GitLab -interface will be stored in the wiki Git repository, and it will be available +Any file uploaded to the wiki with the GitLab +interface is stored in the wiki Git repository, and is available if you clone the wiki repository locally. All uploaded files prior to GitLab 11.3 are stored in GitLab itself. If you want them to be part of the wiki's Git -repository, you will have to upload them again. +repository, you must upload them again. ### Special characters in page titles @@ -80,7 +80,7 @@ Wiki pages are stored as files in a Git repository, so certain characters have a ### Length restrictions for file and directory names -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. Many common file systems have a [limit of 255 bytes for file and directory names](https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits), and while Git and GitLab both support paths exceeding those limits, the presence of them makes it impossible for users on those file systems to checkout a wiki repository locally. @@ -99,9 +99,9 @@ Please note that: You need Developer [permissions](../../permissions.md) or higher to edit a wiki page. To do so: -1. Click the edit icon (**{pencil}**). +1. Select the edit icon (**{pencil}**). 1. Edit the content. -1. Click **Save changes**. +1. Select **Save changes**. ### Adding a table of contents @@ -114,7 +114,7 @@ You need Maintainer [permissions](../../permissions.md) or higher to delete a wi To do so: 1. Open the page you want to delete. -1. Click the **Delete page** button. +1. Select **Delete page**. 1. Confirm the deletion. ## Moving a wiki page @@ -122,22 +122,22 @@ To do so: You need Developer [permissions](../../permissions.md) or higher to move a wiki page. To do so: -1. Click the edit icon (**{pencil}**). +1. Select the edit icon (**{pencil}**). 1. Add the new path to the **Title** field. -1. Click **Save changes**. +1. Select **Save changes**. For example, if you have a wiki page called `about` under `company` and you want to move it to the wiki's root: -1. Click the edit icon (**{pencil}**). +1. Select the edit icon (**{pencil}**). 1. Change the **Title** from `about` to `/about`. -1. Click **Save changes**. +1. Select **Save changes**. If you want to do the opposite: -1. Click the edit icon (**{pencil}**). +1. Select the edit icon (**{pencil}**). 1. Change the **Title** from `about` to `company/about`. -1. Click **Save changes**. +1. Select **Save changes**. ## Viewing a list of all created wiki pages @@ -148,37 +148,37 @@ found. The list is ordered alphabetically.  -If you have many pages, not all will be listed in the sidebar. Click on +If you have many pages, not all are listed in the sidebar. Select **View All Pages** to see all of them. ## Viewing the history of a wiki page The changes of a wiki page over time are recorded in the wiki's Git repository, -and you can view them by clicking the **Page history** button. +and you can view them by selecting **Page history**. From the history page you can see the revision of the page (Git commit SHA), its author, the commit message, and when it was last updated. -To see how a previous version of the page looked like, click on a revision +To see how a previous version of the page looked like, select a revision number in the **Page version** column.  ### Viewing the changes between page versions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. Similar to versioned diff file views, you can see the changes made in a given Wiki page version: 1. Navigate to the Wiki page you're interested in. -1. Click on **Page history** to see all page versions. -1. Click on the commit message in the **Changes** column for the version you're interested in: +1. Select **Page history** to see all page versions. +1. Select the commit message in the **Changes** column for the version you're interested in.  ## Wiki activity records > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14902) in **GitLab 12.10.** -> - Git events were [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** +> - Git events were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** > - [Feature flag for Git events was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258665) in **GitLab 13.5** Wiki events (creation, deletion, and updates) are tracked by GitLab and @@ -191,12 +191,12 @@ and [project](../working_with_projects.md#project-activity) activity pages. Since wikis are based on Git repositories, you can clone them locally and edit them like you would do with every other Git repository. -On the right sidebar, click on **Clone repository** and follow the on-screen +In the right sidebar, select **Clone repository** and follow the on-screen instructions. Files that you add to your wiki locally must have one of the following supported extensions, depending on the markup language you wish to use, -otherwise they will not display when pushed to GitLab: +otherwise they don't display when pushed to GitLab: - Markdown extensions: `.mdown`, `.mkd`, `.mkdn`, `.md`, `.markdown`. - AsciiDoc extensions: `.adoc`, `.ad`, `.asciidoc`. @@ -204,11 +204,11 @@ otherwise they will not display when pushed to GitLab: ## Customizing sidebar -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by clicking the **Edit sidebar** button. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. To customize the Wiki's navigation sidebar, you need Developer permissions to the project. -On the top-right, click **Edit sidebar** and make your changes. This creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation. +In the top-right, select **Edit sidebar** and make your changes. This creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation. Example for `_sidebar` (using Markdown format): diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 3fe6193c414..43df1cce70f 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -212,7 +212,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 in 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 [Enable delayed project removal](../group/index.md#enable-delayed-project-removal). ## Project settings @@ -278,7 +278,7 @@ databases if the module name or a prefix of it appears in `GONOPRIVATE` or ### Authenticate Go requests To authenticate requests to private projects made by Go, use a [`.netrc` -file](https://ec.haxx.se/usingcurl-netrc.html) and a [personal access +file](https://everything.curl.dev/usingcurl/netrc) 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 does not transmit credentials over insecure connections. This authenticates diff --git a/doc/user/search/advanced_global_search.md b/doc/user/search/advanced_global_search.md deleted file mode 100644 index 2d1a05cd966..00000000000 --- a/doc/user/search/advanced_global_search.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -stage: Enablement -group: Global Search -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference ---- - -# Advanced Search **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109) in GitLab 8.4. -> - [Moved](../../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. - -NOTE: -Advanced Search (powered by Elasticsearch) is enabled for Bronze and above on GitLab.com since 2020-07-10. - -Leverage Elasticsearch for faster, more advanced code search across your entire -GitLab instance. - -This is the user documentation. To install and configure Elasticsearch, -visit the [administrator documentation](../../integration/elasticsearch.md). - -## Overview - -The Advanced Search in GitLab is a powerful search service that saves -you time. Instead of creating duplicate code and wasting time, you can -now search for code within other projects that can help your own project. - -GitLab leverages the search capabilities of [Elasticsearch](https://www.elastic.co/elasticsearch/) and enables it when -searching in: - -- Projects -- Issues -- Merge requests -- Milestones -- Comments -- Code -- Commits -- Wiki -- Users - -## Use cases - -The Advanced Search can be useful in various scenarios. - -### Faster searches - -Advanced Search is based on Elasticsearch, which is a purpose built full text search engine that can be horizontally scaled so that it can provide search results in 1-2 seconds in most cases. - -### Promote innersourcing - -Your company may consist of many different developer teams each of which has -their own group where the various projects are hosted. Some of your applications -may be connected to each other, so your developers need to instantly search -throughout the GitLab instance and find the code they search for. - -## Searching globally - -Just use the search as before and GitLab will show you matching code from each -project you have access to. - - - -You can also use the [Advanced Search Syntax](advanced_search_syntax.md) which -provides some useful queries. - -NOTE: -Elasticsearch has only data for the default branch. That means that if you go -to the repository tree and switch the branch from the default to something else, -then the "Code" tab in the search result page will be served by the basic -search even if Elasticsearch is enabled. diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search.md index 19f7305124e..d11f02addea 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search.md @@ -5,28 +5,53 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Advanced Search Syntax **(PREMIUM)** +# GitLab Advanced Search **(PREMIUM)** -> - Introduced in [GitLab](https://about.gitlab.com/pricing/) 9.2. -> - [Moved](../../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. +> - Moved to GitLab Premium in 13.9. -Use advanced queries for more targeted search results. - -This is the user documentation. To install and configure Elasticsearch, +NOTE: +This is the user documentation. To configure the Advanced Search, visit the [administrator documentation](../../integration/elasticsearch.md). -## Overview - -The Advanced Search Syntax is a subset of the -[Advanced Search](advanced_global_search.md), which you can use if you -want to have more specific search results. - -Advanced Search only supports searching the [default branch](../project/repository/branches/index.md#default-branch). - -## Using the Advanced Search Syntax - -The Advanced Search Syntax supports fuzzy or exact search queries with prefixes, -boolean operators, and much more. +GitLab Advanced Search expands on the Basic Search with an additional set of +features for faster, more advanced searches across the entire GitLab instance +when searching in: + +- Projects +- Issues +- Merge requests +- Milestones +- Epics +- Comments +- Code +- Commits +- Wiki +- Users + +The Advanced Search can be useful in various scenarios: + +- **Faster searches:** + Advanced Search is based on Elasticsearch, which is a purpose-built full + text search engine that can be horizontally scaled so that it can provide + search results in 1-2 seconds in most cases. +- **Promote innersourcing:** + Your company may consist of many different developer teams each of which has + their own group where the various projects are hosted. Some of your applications + may be connected to each other, so your developers need to instantly search + throughout the GitLab instance and find the code they search for. + +## Use the Advanced Search syntax + +Elasticsearch has only data for the default branch. That means that if you go +to the repository tree and switch the branch from the default to something else, +then the "Code" tab in the search result page will be served by the basic +search even if Elasticsearch is enabled. + +The Advanced Search syntax supports fuzzy or exact search queries with prefixes, +boolean operators, and much more. Use the search as before and GitLab will show +you matching code from each project you have access to. + + Full details can be found in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/5.3/query-dsl-simple-query-string-query.html#_simple_query_string_syntax), but here's a quick guide: @@ -40,14 +65,14 @@ here's a quick guide: - To match a partial word, use `*`. In this example, I want to find bugs with any 500 errors. : [`bug error 50*`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=bug+error+50*&group_id=9970&project_id=278964) - To use one of symbols above literally, escape the symbol with a preceding `\`: [`argument \-last`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=argument+%5C-last&group_id=9970&project_id=278964) -### Syntax search filters +## Syntax search filters -The Advanced Search Syntax also supports the use of filters. The available filters are: +Advanced Search also supports the use of filters. The available filters are: -- filename: Filters by filename. You can use the glob (`*`) operator for fuzzy matching. -- path: Filters by path. You can use the glob (`*`) operator for fuzzy matching. -- extension: Filters by extension in the filename. Please write the extension without a leading dot. Exact match only. -- blob: Filters by Git `object ID`. Exact match only. +- `filename`: Filters by filename. You can use the glob (`*`) operator for fuzzy matching. +- `path`: Filters by path. You can use the glob (`*`) operator for fuzzy matching. +- `extension`: Filters by extension in the filename. Please write the extension without a leading dot. Exact match only. +- `blob`: Filters by Git `object ID`. Exact match only. To use them, add them to your keyword in the format `<filter_name>:<value>` without any spaces between the colon (`:`) and the value. When no keyword is provided, an asterisk (`*`) will be used as the keyword. @@ -64,7 +89,7 @@ Examples: - Finding the files represented by the Git object ID `998707b421c89bd9a3063333f9f728ef3e43d101`: [`* blob:998707b421c89bd9a3063333f9f728ef3e43d101`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=false&scope=blobs&repository_ref=&search=*+blob%3A998707b421c89bd9a3063333f9f728ef3e43d101&group_id=9970) - Syntax filters can be combined for complex filtering. Finding any file starting with `search` containing `eventHub` and with the `.js` extension: [`eventHub filename:search* extension:js`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=eventHub+filename%3Asearch*+extension%3Ajs&group_id=9970&project_id=278964) -#### Excluding filters +### Excluding filters [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31684) in GitLab Starter 13.3. @@ -82,7 +107,7 @@ Examples: - Finding `import` excluding minified JavaScript (`.min.js`) files: [`import -extension:min.js`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=import+-extension%3Amin.js&group_id=9970&project_id=278964) - Finding `docs` for all files outside the `docs/` folder: [`docs -path:docs/`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=docs+-path%3Adocs%2F&group_id=9970&project_id=278964) -### Search by issue or merge request ID +## Search by issue or merge request ID You can search a specific issue or merge request by its ID with a special prefix. diff --git a/doc/user/search/img/advanced_global_search.png b/doc/user/search/img/advanced_global_search.png Binary files differdeleted file mode 100644 index 4903bbb07e1..00000000000 --- a/doc/user/search/img/advanced_global_search.png +++ /dev/null diff --git a/doc/user/search/img/advanced_search_v13.10.png b/doc/user/search/img/advanced_search_v13.10.png Binary files differnew file mode 100644 index 00000000000..39cd54fea75 --- /dev/null +++ b/doc/user/search/img/advanced_search_v13.10.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md index ffd331248be..f327288ea0a 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: index, reference, howto --- -# Search through GitLab +# Search through GitLab **(FREE)** ## Issues and merge requests @@ -298,34 +298,29 @@ redirected to the commit result and given the option to return to the search res Leverage Elasticsearch for faster, more advanced code search across your entire GitLab instance. -[Learn how to use the Advanced Search.](advanced_global_search.md) +[Learn how to use the Advanced Search.](advanced_search.md) -## Advanced Search Syntax **(PREMIUM)** - -Use advanced queries for more targeted search results. - -[Learn how to use the Advanced Search Syntax.](advanced_search_syntax.md) - -## Search project settings +## Search settings > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292941) in GitLab 13.8. +> - [Added to Group, Admin, and User settings](https://gitlab.com/groups/gitlab-org/-/epics/4842) in GitLab 13.9 > - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. > - It's disabled on GitLab.com. > - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-search-project-settings). **(FREE SELF)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-search-settings). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. -You can search inside the project’s settings sections by entering a search -term in the search box located at the top of the page. The search results +You can search inside a Project, Group, Admin, or User’s settings by entering +a search term in the search box located at the top of the page. The search results appear highlighted in the sections that match the search term.  -### Enable or disable Search project settings **(FREE SELF)** +### Enable or disable Search settings **(FREE SELF)** -Search project settings is under development and not ready for production use. It is +Search settings is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can enable it. diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 014555cffed..2a3ee09b40b 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -6,25 +6,32 @@ type: reference disqus_identifier: 'https://docs.gitlab.com/ee/workflow/shortcuts.html' --- -# GitLab keyboard shortcuts +# GitLab keyboard shortcuts **(FREE)** + +GitLab has several keyboard shortcuts you can use to access its different +features. + +To display a window in GitLab that lists its keyboard shortcuts, use one of the +following methods: + +- Press <kbd>?</kbd>. +- In the Help menu in the top right of the appication, select **Keyboard shortcuts**. -GitLab has many useful keyboard shortcuts to make it easier to access different features. -You can see a modal listing keyboard shortcuts within GitLab itself by pressing <kbd>?</kbd>, -or clicking **Keyboard shortcuts** in the Help menu at the top right. In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22113), -keyboard shortcuts can be disabled using the **Enable**/**Disable** toggle in this modal window. +you can disable keyboard shortcuts by using the **Keyboard shortcuts** toggle +at the top of the keyboard shortcut window. -The [Global Shortcuts](#global-shortcuts) work from any area of GitLab, but you must -be in specific pages for the other shortcuts to be available, as explained in each -section below. +Although [global shortcuts](#global-shortcuts) work from any area of GitLab, +you must be in specific pages for the other shortcuts to be available, as +explained in each section. -## Global Shortcuts +## Global shortcuts -These shortcuts are available in most areas of GitLab +These shortcuts are available in most areas of GitLab: -| Keyboard Shortcut | Description | -| ------------------------------- | ----------- | -| <kbd>?</kbd> | Show/hide shortcut reference sheet. | +| Keyboard shortcut | Description | +|---------------------------------|-------------| +| <kbd>?</kbd> | Show or hide the shortcut reference sheet. | | <kbd>Shift</kbd> + <kbd>p</kbd> | Go to your Projects page. | | <kbd>Shift</kbd> + <kbd>g</kbd> | Go to your Groups page. | | <kbd>Shift</kbd> + <kbd>a</kbd> | Go to your Activity page. | @@ -34,41 +41,41 @@ These shortcuts are available in most areas of GitLab | <kbd>Shift</kbd> + <kbd>i</kbd> | Go to your Issues page. | | <kbd>Shift</kbd> + <kbd>m</kbd> | Go to your Merge requests page.| | <kbd>Shift</kbd> + <kbd>t</kbd> | Go to your To-Do List page. | -| <kbd>p</kbd> + <kbd>b</kbd> | Show/hide the Performance Bar. | +| <kbd>p</kbd> + <kbd>b</kbd> | Show or hide the Performance Bar. | | <kbd>g</kbd> + <kbd>x</kbd> | Toggle between [GitLab](https://gitlab.com/) and [GitLab Next](https://next.gitlab.com/) (GitLab SaaS only). | -Additionally, the following shortcuts are available when editing text in text fields, -for example comments, replies, issue descriptions, and merge request descriptions: +Additionally, the following shortcuts are available when editing text in text +fields (for example, comments, replies, issue descriptions, and merge request +descriptions): -| Keyboard Shortcut | Description | -| ---------------------------------------------------------------------- | ----------- | -| <kbd>↑</kbd> | Edit your last comment. You must be in a blank text field below a thread, and you must already have at least one comment in the thread. | -| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> | Toggle Markdown preview, when editing text in a text field that has **Write** and **Preview** tabs at the top. | +| Keyboard shortcut | Description | +|---------------------------------------------------------------------------|-------------| +| <kbd>↑</kbd> | Edit your last comment. You must be in a blank text field below a thread, and you must already have at least one comment in the thread. | +| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> | Toggle Markdown preview when editing text in a text field that has **Write** and **Preview** tabs at the top. | | <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>b</kbd> | Bold the selected text (surround it with `**`). | | <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>i</kbd> | Italicize the selected text (surround it with `_`). | | <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>k</kbd> | Add a link (surround the selected text with `[]()`). | -NOTE: -The shortcuts for editing in text fields are always enabled, even when -other keyboard shortcuts are disabled as explained above. +The shortcuts for editing in text fields are always enabled, even if other +keyboard shortcuts are disabled. ## Project -These shortcuts are available from any page within a project. You must type them +These shortcuts are available from any page in a project. You must type them relatively quickly to work, and they take you to another page in the project. -| Keyboard Shortcut | Description | -| --------------------------- | ----------- | +| Keyboard shortcut | Description | +|-----------------------------|-------------| | <kbd>g</kbd> + <kbd>p</kbd> | Go to the project home page (**Project > Details**). | | <kbd>g</kbd> + <kbd>v</kbd> | Go to the project activity feed (**Project > Activity**). | | <kbd>g</kbd> + <kbd>r</kbd> | Go to the project releases list (**Project > Releases**). | | <kbd>g</kbd> + <kbd>f</kbd> | Go to the [project files](#project-files) list (**Repository > Files**). | -| <kbd>t</kbd> | Go to the project file search page. (**Repository > Files**, click **Find Files**). | +| <kbd>t</kbd> | Go to the project file search page. (**Repository > Files**, select **Find Files**). | | <kbd>g</kbd> + <kbd>c</kbd> | Go to the project commits list (**Repository > Commits**). | | <kbd>g</kbd> + <kbd>n</kbd> | Go to the [repository graph](#repository-graph) page (**Repository > Graph**). | | <kbd>g</kbd> + <kbd>d</kbd> | Go to repository charts (**Analytics > Repository Analytics**). | | <kbd>g</kbd> + <kbd>i</kbd> | Go to the project issues list (**Issues > List**). | -| <kbd>i</kbd> | Go to the New Issue page (**Issues**, click **New Issue** ). | +| <kbd>i</kbd> | Go to the New Issue page (**Issues**, select **New Issue** ). | | <kbd>g</kbd> + <kbd>b</kbd> | Go to the project issue boards list (**Issues > Boards**). | | <kbd>g</kbd> + <kbd>m</kbd> | Go to the project merge requests list (**Merge Requests**). | | <kbd>g</kbd> + <kbd>j</kbd> | Go to the CI/CD jobs list (**CI/CD > Jobs**). | @@ -78,52 +85,52 @@ relatively quickly to work, and they take you to another page in the project. | <kbd>g</kbd> + <kbd>s</kbd> | Go to the project snippets list (**Snippets**). | | <kbd>g</kbd> + <kbd>w</kbd> | Go to the project wiki (**Wiki**), if enabled. | -### Issues and Merge Requests +### Issues and merge requests -These shortcuts are available when viewing issues and merge requests. +These shortcuts are available when viewing issues and merge requests: -| Keyboard Shortcut | Description | -| ---------------------------- | ----------- | +| Keyboard shortcut | Description | +|------------------------------|-------------| | <kbd>e</kbd> | Edit description. | | <kbd>a</kbd> | Change assignee. | | <kbd>m</kbd> | Change milestone. | | <kbd>l</kbd> | Change label. | -| <kbd>r</kbd> | Start writing a comment. If any text is selected, it is quoted in the comment. Can't be used to reply within a thread. | +| <kbd>r</kbd> | Start writing a comment. Pre-selected text is quoted in the comment. Can't be used to reply in a thread. | | <kbd>n</kbd> | Move to next unresolved discussion (merge requests only). | | <kbd>p</kbd> | Move to previous unresolved discussion (merge requests only). | | <kbd>]</kbd> or <kbd>j</kbd> | Move to next file (merge requests only). | | <kbd>[</kbd> or <kbd>k</kbd> | Move to previous file (merge requests only). | | <kbd>b</kbd> | Copy source branch name (merge requests only). | -### Project Files +### Project files -These shortcuts are available when browsing the files in a project (navigate to -**Repository** > **Files**): +These shortcuts are available when browsing the files in a project (go to +**Repository > Files**): -| Keyboard Shortcut | Description | -| ----------------- | ----------- | +| Keyboard shortcut | Description | +|-------------------|-------------| | <kbd>↑</kbd> | Move selection up. | | <kbd>↓</kbd> | Move selection down. | | <kbd>enter</kbd> | Open selection. | -| <kbd>Escape</kbd> | Go back to file list screen (only while searching for files, **Repository > Files** then click on **Find File**). | +| <kbd>Escape</kbd> | Go back to file list screen (only while searching for files, **Repository > Files**, then select **Find File**). | | <kbd>y</kbd> | Go to file permalink (only while viewing a file). | ### Web IDE These shortcuts are available when editing a file with the [Web IDE](project/web_ide/index.md): -| Keyboard Shortcut | Description | -| ------------------------------------------------------- | ----------- | +| Keyboard shortcut | Description | +|------------------------------------------------------------|-------------| | <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>p</kbd> | Search for, and then open another file for editing. | | <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Enter</kbd> | Commit (when editing the commit message). | -### Repository Graph +### Repository graph These shortcuts are available when viewing the project [repository graph](project/repository/index.md#repository-graph) page (navigate to **Repository > Graph**): -| Keyboard Shortcut | Description | -| ------------------------------------------------------------------ | ----------- | +| Keyboard shortcut | Description | +|--------------------------------------------------------------------|-------------| | <kbd>←</kbd> or <kbd>h</kbd> | Scroll left. | | <kbd>→</kbd> or <kbd>l</kbd> | Scroll right. | | <kbd>↑</kbd> or <kbd>k</kbd> | Scroll up. | @@ -135,25 +142,25 @@ page (navigate to **Repository > Graph**): This shortcut is available when viewing a [wiki page](project/wiki/index.md): -| Keyboard Shortcut | Description | -| ----------------- | ----------- | +| Keyboard shortcut | Description | +|-------------------|-------------| | <kbd>e</kbd> | Edit wiki page. | -### Filtered Search +### Filtered search These shortcuts are available when using a [filtered search input](search/index.md): -| Keyboard Shortcut | Description | -| ----------------------------------------------------- | ----------- | -| <kbd>⌘</kbd> (Mac) + <kbd>⌫</kbd> | Clear entire search filter. | -| <kbd>⌥</kbd> (Mac) / <kbd>Control</kbd> + <kbd>⌫</kbd> | Clear one token at a time. | +| Keyboard shortcut | Description | +|--------------------------------------------------------|-------------| +| <kbd>⌘</kbd> (Mac) + <kbd>⌫</kbd> | Clear entire search filter. | +| <kbd>⌥</kbd> (Mac) / <kbd>Control</kbd> + <kbd>⌫</kbd> | Clear one token at a time. | ## Epics **(ULTIMATE)** -These shortcuts are available when viewing [Epics](group/epics/index.md): +These shortcuts are available when viewing [epics](group/epics/index.md): -| Keyboard Shortcut | Description | -| ----------------- | ----------- | -| <kbd>r</kbd> | Start writing a comment. If any text is selected, it is quoted in the comment. Can't be used to reply within a thread. | +| Keyboard shortcut | Description | +|-------------------|-------------| +| <kbd>r</kbd> | Start writing a comment. Pre-selected text is quoted in the comment. Can't be used to reply in a thread. | | <kbd>e</kbd> | Edit description. | | <kbd>l</kbd> | Change label. | diff --git a/doc/user/snippets.md b/doc/user/snippets.md index e919e73f404..a2a18c0e8de 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -5,85 +5,100 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Snippets +# Snippets **(FREE)** + +With GitLab snippets, you can store and share bits of code and text with other users. +You can [comment on](#comment-on-snippets), [clone](#clone-snippets), and +[use version control](#versioned-snippets) in snippets. They can +[contain multiple files](#add-or-remove-multiple-files). They also support +[syntax highlighting](#filenames), [embedding](#embed-snippets), [downloading](#download-snippets), +and you can maintain your snippets with the [snippets API](../api/snippets.md). + +GitLab provides two types of snippets: + +- **Personal snippets**: Created independent of any project. + You can set a [visibility level](../public_access/public_access.md) + for your snippet: public, internal, or private. +- **Project snippets**: Always related to a specific project. + Project snippets can be visible publicly or to only group members. + +## Create snippets + +You can create snippets in multiple ways, depending on whether you want to create a personal or project snippet: + +1. Select the kind of snippet you want to create: + - **To create a personal snippet**: + - *If you're on a project's page,* select the plus icon (**{plus-square-o}**) + in the top navigation bar, then select **New snippet** from the **GitLab** (for GitLab.com) + or **Your Instance** (self-managed) section of the same dropdown menu. + - *For all other pages,* select the plus icon (**{plus-square-o}**) + in the top navigation bar, then select **New snippet** from the dropdown menu. + - **To create a project snippet**: Go to your project's page. Select the plus icon + (**{plus-square-o}**), then select **New snippet** from the **This project** section + of the dropdown menu. +1. Add a **Title** and **Description**. +1. Name your **File** with an appropriate extension, such as `example.rb` or `index.html`. + Filenames with appropriate extensions display [syntax highlighting](#filenames). + Failure to add a filename can cause a known + [copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870). If you don't provide a filename, GitLab [creates a name for you](#filenames). +1. (Optional) Add [multiple files](#add-or-remove-multiple-files) to your snippet. +1. Select a visibility level, and select **Create snippet**. + +After you create a snippet, you can still [add more files to it](#add-or-remove-multiple-files). +In GitLab versions 13.0 and later, snippets are [versioned by default](#versioned-snippets). -With GitLab Snippets you can store and share bits of code and text with other users. - - - -Snippets can be maintained using [snippets API](../api/snippets.md). - -There are two types of snippets: - -- Personal snippets. -- Project snippets. - -## Personal snippets - -Personal snippets are not related to any project and can be created completely -independently. There are 3 visibility levels that can be set, public, internal -and private. See [Public access](../public_access/public_access.md) for more information. - -## Project snippets - -Project snippets are always related to a specific project. -See [Project features](project/index.md#project-features) for more information. - -## Create a snippet - -To create a personal snippet, click the plus icon (**{plus-square-o}**) -on the top navigation and select **New snippet** from the dropdown menu: - - - -If you're on a project's page but you want to create a new personal snippet, -click the plus icon (**{plus-square-o}**) and select **New snippet** from the -lower part of the dropdown (**GitLab** on GitLab.com; **Your Instance** on -self-managed instances): +## Discover snippets - +To discover all snippets visible to you in GitLab, you can: -To create a project snippet, navigate to your project's page and click the -plus icon (**{plus-square-o}**), then select **New snippet** from the upper -part of the dropdown (**This project**). +- **View all snippets visible to you**: In the top navigation bar of your GitLab + instance, go to **More > Snippets** to view your snippets dashboard. +- **Visit [GitLab snippets](http://snippets.gitlab.com/)** for your snippets on GitLab.com. +- **Explore all public snippets**: In the top navigation bar of your GitLab + instance, go to **More > Snippets** and select **Explore snippets** to view + [all public snippets](https://gitlab.com/explore/snippets). +- **View a project's snippets**: In your project, + go to **Snippets**. - +## Change default visibility of snippets -From there, add the **Title**, **Description**, and a **File** name with the -appropriate extension (for example, `example.rb`, `index.html`). +Project snippets are enabled and available by default. To change their +default visibility: -WARNING: -Make sure to add the filename to get code highlighting and to avoid this -[copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870). +1. In your project, + go to **Settings**. +1. Expand the **Visibility, project features, permissions** section, and scroll to **Snippets**. +1. Toggle the default visibility, and select whether snippets can be viewed by + everyone, or only project members. +1. Select **Save changes**. -## Versioned Snippets +## Versioned snippets > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/239) in GitLab 13.0. -Starting in 13.0, snippets (both personal and project snippets) +In GitLab versions 13.0 and later, snippets (both personal and project snippets) have version control enabled by default. This means that all snippets get their own underlying repository initialized with -a `master` branch at the moment the snippet is created. Whenever a change to the snippet is saved, a -new commit to the `master` branch is recorded. Commit messages are automatically -generated. The snippet's repository has only one branch (`master`) by default, deleting -it or creating other branches is not supported. +a default branch at the moment the snippet is created. Whenever a change to the snippet is saved, a +new commit to the default branch is recorded. Commit messages are automatically +generated. The snippet's repository has only one branch. You can't delete this branch, +or create other branches. -Existing snippets are automatically migrated in 13.0. Their current -content is saved as the initial commit to the snippets' repository. +Existing snippets were automatically migrated in 13.0. Their current +content was saved as the initial commit to the snippets' repository. -### Filenames +## Filenames Snippets support syntax highlighting based on the filename and extension provided for them. While you can submit a snippet -without specifying a filename and extension, it needs a valid name so the +without a filename and extension, it needs a valid name so the content can be created as a file in the snippet's repository. -If you don't attribute a filename and extension to a snippet, +If you don't give a snippet a filename and extension, GitLab adds a filename in the format `snippetfile<x>.txt` where `<x>` represents a number added to the file, starting with 1. This -number increments when more snippets without an attributed -filename are added. +number increments if you add more unnamed snippets. When upgrading from an earlier version of GitLab to 13.0, existing snippets without a supported filename are renamed to a compatible format. For @@ -92,139 +107,110 @@ changed to `http-a-weird-filename-me` to be included in the snippet's repository. As snippets are stored by ID, changing their filenames breaks direct or embedded links to the snippet. -### Multiple files by Snippet +## Add or remove multiple files > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2829) in GitLab 13.5. -GitLab Snippets support multiple files in one single snippet. This is helpful -when your code snippet is composed of multiple parts or when they relate -to a certain context. For example: +A single snippet can support up to 10 files, which helps keep related files together, such as: - A snippet that includes a script and its output. -- A snippet that includes HTML, CSS, and JS code. +- A snippet that includes HTML, CSS, and JavaScript code. - A snippet with a `docker-compose.yml` file and its associated `.env` file. -- A `gulpfile.js` file coupled with a `package.json` file, which together can be +- A `gulpfile.js` file and a `package.json` file, which together can be used to bootstrap a project and manage its dependencies. -Snippets support between 1 and 10 files. They can be managed via Git (because they're [versioned](#versioned-snippets) -by a Git repository), through the [Snippets API](../api/snippets.md), or in the GitLab UI. - - +You can manage these by using Git (because they're [versioned](#versioned-snippets) +by a Git repository), through the [Snippets API](../api/snippets.md), and in the GitLab UI. To add a new file to your snippet through the GitLab UI: 1. Go to your snippet in the GitLab UI. -1. Click **Edit** in the top right. +1. Select **Edit** in the top right corner. 1. Select **Add another file**. 1. Add your content to the file in the form fields provided. -1. Click **Save changes**. +1. Select **Save changes**. To delete a file from your snippet through the GitLab UI: 1. Go to your snippet in the GitLab UI. -1. Click **Edit** in the top right. +1. Select **Edit** in the top right corner. 1. Select **Delete file** alongside the filename of each file you wish to delete. -1. Click **Save changes**. - -### Cloning snippets +1. Select **Save changes**. -Snippets can be cloned as a regular Git repository using SSH or HTTPS. Click the **Clone** -button above the snippet content to copy the URL of your choice. +## Clone snippets - +Instead of copying a snippet to a local file, you may want to clone a snippet to +preserve its relationship with the repository, so you can receive or make updates +as needed. Select the **Clone** button on a snippet to display the URLs to clone with SSH or HTTPS: -This allows you to have a local copy of the snippet's repository and make -changes as needed. You can commit those changes and push them to the remote -`master` branch. + -### Reduce snippets repository size - -Because versioned Snippets are considered as part of the [namespace storage size](../user/admin_area/settings/account_and_limit_settings.md), -it's recommended to keep snippets' repositories as compact as possible. - -For more information about tools to compact repositories, -see the documentation on [reducing repository size](../user/project/repository/reducing_the_repo_size_using_git.md). +You can commit changes to a cloned snippet, and push the changes to GitLab. -### Limitations +## Embed snippets -- Binary files are not supported. -- Creating or deleting branches is not supported. Only a default `master` branch is used. -- Git tags are not supported in snippet repositories. -- Snippets' repositories are limited to 10 files. Attempting to push more - than 10 files results in an error. -- Revisions are not visible to the user on the GitLab UI, but this feature is planned - in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) - for updates. -- The [maximum size for a snippet](../administration/snippets/index.md#snippets-content-size-limit) - is 50 MB, by default. -- Git LFS is not supported. +Public snippets can be shared and embedded on any website. You can reuse a GitLab snippet in multiple places, and any change to the source +is reflected in the embedded snippets. When embedded, users can download it, or view the snippet in raw format. -## Discover snippets +To embed a snippet: -There are two main ways of how you can discover snippets in GitLab. +1. Confirm your snippet is publicly visible: + - *If it's a project snippet*, the project must be public. + - The snippet is publicly visible. + - In **Project > Settings > Permissions**, the snippets + permissions are set to **Everyone with access**. +1. In your snippet's **Embed** section, select **Copy** to copy a one-line script you can add to any website or blog post. For example: -For exploring all snippets that are visible to you, you can go to the Snippets -dashboard of your GitLab instance via the top navigation. For GitLab.com you can -navigate to an [overview]((https://gitlab.com/dashboard/snippets)) that shows snippets -you created and allows you to explore all snippets. + ```html + <script src="https://gitlab.com/namespace/project/snippets/SNIPPET_ID.js"></script> + ``` -To discover snippets that belong to a specific project, navigate -to the Snippets page via the left side navigation on the project page. -Project snippets are enabled and available by default. You can -disable them by navigating to your project's **Settings**, expanding -**Visibility, project features, permissions** and scrolling down to -**Snippets**. From there, you can toggle to disable them or select a -different visibility level from the dropdown menu. +1. Add your script to your file. -## Snippet comments +Embedded snippets display a header that shows: -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/12910) in GitLab 9.2. +- The filename, if defined. +- The snippet size. +- A link to GitLab. +- The actual snippet content. -With GitLab Snippets you engage in a conversation about that piece of code, -encouraging user collaboration. +For example: -## Downloading snippets +<script src="https://gitlab.com/gitlab-org/gitlab-foss/snippets/1717978.js"></script> -You can download the raw content of a snippet. +## Download snippets -By default snippets are downloaded with Linux-style line endings (`LF`). If +You can download the raw content of a snippet. By default, they download with Linux-style line endings (`LF`). If you want to preserve the original line endings you need to add a parameter `line_ending=raw` (For example: `https://gitlab.com/snippets/SNIPPET_ID/raw?line_ending=raw`). In case a snippet was created using the GitLab web interface the original line ending is Windows-like (`CRLF`). -## Embedded snippets - -> Introduced in GitLab 10.8. +## Comment on snippets -Public snippets can not only be shared, but also embedded on any website. With -this, you can reuse a GitLab snippet in multiple places and any change to the source -is automatically reflected in the embedded snippet. +With snippets, you engage in a conversation about that piece of code, +which can encourage user collaboration. -To embed a snippet, first make sure that: +## Troubleshooting -- The project is public (if it's a project snippet) -- The snippet is public -- In **Project > Settings > Permissions**, the snippets permissions are - set to **Everyone with access** +### Snippet limitations -After the above conditions are met, the **Embed** section appears in your -snippet. Click the **Copy** button to copy a one-line -script that you can add to any website or blog post. For example: - -```html -<script src="https://gitlab.com/namespace/project/snippets/SNIPPET_ID.js"></script> -``` - -Here's what an embedded snippet looks like: - -<script src="https://gitlab.com/gitlab-org/gitlab-foss/snippets/1717978.js"></script> +- Binary files are not supported. +- Creating or deleting branches is not supported. Only the default branch is used. +- Git tags are not supported in snippet repositories. +- Snippets' repositories are limited to 10 files. Attempting to push more + than 10 files results in an error. +- Revisions are not visible to the user on the GitLab UI, but this feature is planned + in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) + for updates. +- The [maximum size for a snippet](../administration/snippets/index.md#snippets-content-size-limit) + is 50 MB, by default. +- Git LFS is not supported. -Embedded snippets are displayed with a header that shows: +### Reduce snippets repository size -- The filename, if defined. -- The snippet size. -- A link to GitLab. -- The actual snippet content. +Because versioned snippets are considered as part of the [namespace storage size](../user/admin_area/settings/account_and_limit_settings.md), +it's recommended to keep snippets' repositories as compact as possible. -Actions in the header enable users to see the snippet in raw format, and download it. +For more information about tools to compact repositories, +see the documentation on [reducing repository size](../user/project/repository/reducing_the_repo_size_using_git.md). |
