diff options
Diffstat (limited to 'doc/user')
206 files changed, 3373 insertions, 2789 deletions
diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 959331c16de..a6e6a839912 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -7,7 +7,8 @@ type: reference, howto # Broadcast messages **(FREE SELF)** -> Target roles [introduced](https://gitlab.com/gitlab-org/growth/team-tasks/-/issues/461) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `role_targeted_broadcast_messages`. Disabled by default. +> - Target roles [introduced](https://gitlab.com/gitlab-org/growth/team-tasks/-/issues/461) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `role_targeted_broadcast_messages`. Disabled by default. +> - Theme [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83251) and background color removed in GitLab 14.10. GitLab can display broadcast messages to users of a GitLab instance. There are two types of broadcast messages: diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 5fd44cf8697..c689d61ad68 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -169,6 +169,20 @@ By default, impersonation is enabled. GitLab can be configured to [disable imper  +#### User identities + +> The ability to see a user's SCIM identity was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294608) in GitLab 15.3. + +When using authentication providers, administrators can see the identities for a user: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users**. +1. From the list of users, select a user. +1. Select **Identities**. + +This list shows the user's identities, including SCIM identities. Administrators can use this information to troubleshoot SCIM-related issues and confirm +the identities being used for an account. + #### User Permission Export **(PREMIUM SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1772) in GitLab 13.8. @@ -221,7 +235,7 @@ The [Cohorts](user_cohorts.md) tab displays the monthly cohorts of new users and ### Prevent a user from creating groups -By default, users can create groups. To prevent a user from creating groups: +By default, users can create groups. To prevent a user from creating a top level group: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users** (`/admin/users`). @@ -230,6 +244,8 @@ By default, users can create groups. To prevent a user from creating groups: 1. Clear the **Can create group** checkbox. 1. Select **Save changes**. +It is also possible to [limit which roles can create a subgroup within a group](../group/subgroups/index.md#change-who-can-create-subgroups). + ### Administering Groups You can administer all groups in the GitLab instance from the Admin Area's Groups page. @@ -250,7 +266,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-group) select **New group**. +To [Create a new group](../group/manage.md#create-a-group) select **New group**. ### Administering Topics @@ -421,7 +437,7 @@ For multi-node systems we recommend ingesting the logs into services like Elasti The contents of these log files can be useful when troubleshooting a problem. -For details of these log files and their contents, see [Log system](../../administration/logs.md). +For details of these log files and their contents, see [Log system](../../administration/logs/index.md). The content of each log file is listed in chronological order. To minimize performance issues, a maximum 2000 lines of each log file are shown. diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index 526e8cd17da..e090d4e7f88 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -38,4 +38,4 @@ Merge request approval settings that can be set at an instance level are: See also the following, which are affected by instance-level rules: - [Project merge request approval rules](../project/merge_requests/approvals/index.md). -- [Group merge request approval settings](../group/index.md#group-merge-request-approval-settings) available in GitLab 13.9 and later. +- [Group merge request approval settings](../group/manage.md#group-merge-request-approval-settings) available in GitLab 13.9 and later. diff --git a/doc/user/admin_area/monitoring/background_migrations.md b/doc/user/admin_area/monitoring/background_migrations.md index 02d32099c63..87374849674 100644 --- a/doc/user/admin_area/monitoring/background_migrations.md +++ b/doc/user/admin_area/monitoring/background_migrations.md @@ -48,6 +48,50 @@ To disable it: Feature.disable(:execute_batched_migrations_on_schedule) ``` +### Pause batched background migrations in GitLab 14.x + +To pause an ongoing batched background migration, use the `disable` command above. +This command causes the migration to complete the current batch, and then wait to start the next batch. + +Use the following database queries to see the state of the current batched background migration: + +1. Obtain the ID of the running migration: + + ```sql + SELECT + id job_class_name, + table_name, + column_name, + job_arguments + FROM batched_background_migrations + WHERE status <> 3; + ``` + +1. Run this query, replacing `XX` with the ID you obtained in the previous step, + to see the status of the migration: + + ```sql + SELECT + started_at, + finished_at, + finished_at - started_at AS duration, + min_value, + max_value, + batch_size, + sub_batch_size + FROM batched_background_migration_jobs + WHERE batched_background_migration_id = XX + ORDER BY id DESC + limit 10; + ``` + +1. Run the query multiple times within a few minutes to ensure no new row has been added. + If no new row has been added, the migration has been paused. + +1. After confirming the migration has paused, restart the migration (using the `enable` + command above) to proceed with the batch when ready. On larger instances, + background migrations can take as long as 48 hours to complete each batch. + ## Automatic batch size optimization > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60133) in GitLab 13.12. diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md index ec8e6f2dda4..a5e7fcb1b8e 100644 --- a/doc/user/admin_area/review_abuse_reports.md +++ b/doc/user/admin_area/review_abuse_reports.md @@ -26,8 +26,8 @@ The notification email address can also be set and retrieved ## Reporting abuse -To find out more about reporting abuse, see [abuse reports user -documentation](../report_abuse.md). +To find out more about reporting abuse, see +[abuse reports user documentation](../report_abuse.md). ## Resolving abuse reports 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 bedd648b3e7..e33cf4a9082 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -318,7 +318,7 @@ nginx['client_max_body_size'] = "200m" ### This repository has exceeded its size limit -If you receive intermittent push errors in your [Rails exceptions log](../../../administration/logs.md#exceptions_jsonlog), like this: +If you receive intermittent push errors in your [Rails exceptions log](../../../administration/logs/index.md#exceptions_jsonlog), like this: ```plaintext Your push has been rejected, because this repository has exceeded its size limit. diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 65712a9a85c..afb937494e0 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -48,7 +48,7 @@ tier. Users can continue to access the features in a paid tier without sharing u ### Features available in 14.4 and later - [Repository size limit](../settings/account_and_limit_settings.md#repository-size-limit). -- [Group access restriction by IP address](../../group/index.md#group-access-restriction-by-ip-address). +- [Group access restriction by IP address](../../group/access_and_permissions.md#restrict-group-access-by-ip-address). NOTE: Registration is not yet required for participation, but may be added in a future milestone. diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index bb3ee64abac..a35cbe5381a 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -144,7 +144,7 @@ Note that the bypass only works if the header is set to `1`. Requests that bypassed the rate limiter because of the bypass header are marked with `"throttle_safelist":"throttle_bypass_header"` in -[`production_json.log`](../../../administration/logs.md#production_jsonlog). +[`production_json.log`](../../../administration/logs/index.md#production_jsonlog). To disable the bypass mechanism, make sure the environment variable `GITLAB_THROTTLE_BYPASS_HEADER` is unset or empty. @@ -170,9 +170,9 @@ the allowlist configuration would be `1,53,217`. Requests that bypassed the rate limiter because of the user allowlist are marked with `"throttle_safelist":"throttle_user_allowlist"` in -[`production_json.log`](../../../administration/logs.md#production_jsonlog). +[`production_json.log`](../../../administration/logs/index.md#production_jsonlog). -At application startup, the allowlist is logged in [`auth.log`](../../../administration/logs.md#authlog). +At application startup, the allowlist is logged in [`auth.log`](../../../administration/logs/index.md#authlog). ## Try out throttling settings before enforcing them @@ -208,7 +208,7 @@ non-protected paths can be done by setting To enable dry run mode for all throttles, the variable can be set to `*`. Setting a throttle to dry run mode logs a message to the -[`auth.log`](../../../administration/logs.md#authlog) when it would hit the limit, while letting the +[`auth.log`](../../../administration/logs/index.md#authlog) when it would hit the limit, while letting the request continue as normal. The log message contains an `env` field set to `track`. The `matched` field contains the name of throttle that was hit. 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 8a9db68b34f..118d375da01 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -20,7 +20,7 @@ To access the visibility and access control options: ## Define which roles can create projects Instance-level protections for project creation define which roles can -[add projects to a group](../../group/index.md#specify-who-can-add-projects-to-a-group) +[add projects to a group](../../group/manage.md#specify-who-can-add-projects-to-a-group) on the instance. To alter which roles have permission to create projects: 1. Sign in to GitLab as a user with Administrator access level. @@ -53,6 +53,7 @@ By default both administrators and anyone with the **Owner** role can delete a p > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2 for groups created after August 12, 2021. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) from default delayed project deletion in GitLab 15.1. > - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. +> - [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3. Instance-level protection against accidental deletion of groups and projects. @@ -102,9 +103,9 @@ In GitLab 15.1 and later, delayed group deletion can be enabled by setting **Del Alternatively, projects that are marked for removal can be deleted immediately. To do so: -1. [Restore the project](../../project/settings/#restore-a-project). +1. [Restore the project](../../project/settings/index.md#restore-a-project). 1. Delete the project as described in the - [Administering Projects page](../../admin_area/#administering-projects). + [Administering Projects page](../../admin_area/index.md#administering-projects). ## Configure project visibility defaults diff --git a/doc/user/analytics/img/product_analytics_commits_per_mr_v14_4.png b/doc/user/analytics/img/product_analytics_commits_per_mr_v14_4.png Binary files differdeleted file mode 100644 index 2bfde7beead..00000000000 --- a/doc/user/analytics/img/product_analytics_commits_per_mr_v14_4.png +++ /dev/null diff --git a/doc/user/analytics/img/productivity_analytics_time_to_merge_v14_4.png b/doc/user/analytics/img/productivity_analytics_time_to_merge_v14_4.png Binary files differdeleted file mode 100644 index 0b30aff2c7a..00000000000 --- a/doc/user/analytics/img/productivity_analytics_time_to_merge_v14_4.png +++ /dev/null diff --git a/doc/user/analytics/img/productivity_analytics_trendline_v14_4.png b/doc/user/analytics/img/productivity_analytics_trendline_v14_4.png Binary files differdeleted file mode 100644 index e0b3c54dee2..00000000000 --- a/doc/user/analytics/img/productivity_analytics_trendline_v14_4.png +++ /dev/null diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index f699fa6d0fb..41547430e88 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -8,8 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Instance-level analytics -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in GitLab 12.2. - Instance-level analytics make it possible to aggregate analytics across GitLab, so that users can view information across multiple projects and groups in one place. @@ -18,8 +16,7 @@ in one place. ## Group-level analytics -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195979) in GitLab 12.8. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. GitLab provides several analytics features at the group level. Some of these features require you to use a higher tier than GitLab Free. @@ -50,7 +47,7 @@ You can use GitLab to review analytics at the project level. Some of these featu The following analytics features are available for users to create personalized views: -- [Application Security](../application_security/security_dashboard/#security-center) +- [Application Security](../application_security/security_dashboard/index.md#security-center) Be sure to review the documentation page for this feature for GitLab tier requirements. @@ -124,14 +121,14 @@ To retrieve metrics for change failure rate, use the [GraphQL](../../api/graphql ### Supported DORA metrics in GitLab -| Metric | Level | API | UI chart | Comments | -|---------------------------|-------------------------|-------------------------------------|---------------------------------------|-------------------------------| -| `deployment_frequency` | Project | [GitLab 13.7 and later](../../api/dora/metrics.md) | GitLab 14.8 and later | The previous API endpoint was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/323713) in 13.10. | -| `deployment_frequency` | Group | [GitLab 13.10 and later](../../api/dora/metrics.md) | GitLab 13.12 and later | | -| `lead_time_for_changes` | Project | [GitLab 13.10 and later](../../api/dora/metrics.md) | GitLab 13.11 and later | Unit in seconds. Aggregation method is median. | -| `lead_time_for_changes` | Group | [GitLab 13.10 and later](../../api/dora/metrics.md) | GitLab 14.0 and later | Unit in seconds. Aggregation method is median. | -| `time_to_restore_service` | Project and group | [GitLab 14.9 and later](../../api/dora/metrics.md) | GitLab 15.1 and later | Unit in days. Aggregation method is median. | -| `change_failure_rate` | Project and group | [GitLab 14.10 and later](../../api/dora/metrics.md) | GitLab 15.2 and later | Percentage of deployments. | | +| Metric | Level | API | UI chart | Comments | +|---------------------------|-------------------|-----------------------------------------------------|------------------------|----------| +| `deployment_frequency` | Project | [GitLab 13.7 and later](../../api/dora/metrics.md) | GitLab 14.8 and later | The previous API endpoint was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/323713) in 13.10. | +| `deployment_frequency` | Group | [GitLab 13.10 and later](../../api/dora/metrics.md) | GitLab 13.12 and later | | +| `lead_time_for_changes` | Project | [GitLab 13.10 and later](../../api/dora/metrics.md) | GitLab 13.11 and later | Unit in seconds. Aggregation method is median. | +| `lead_time_for_changes` | Group | [GitLab 13.10 and later](../../api/dora/metrics.md) | GitLab 14.0 and later | Unit in seconds. Aggregation method is median. | +| `time_to_restore_service` | Project and group | [GitLab 14.9 and later](../../api/dora/metrics.md) | GitLab 15.1 and later | Unit in days. Aggregation method is median. | +| `change_failure_rate` | Project and group | [GitLab 14.10 and later](../../api/dora/metrics.md) | GitLab 15.2 and later | Percentage of deployments. | ## Definitions diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 29f2ec79800..038b2f0c97e 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -31,12 +31,12 @@ To view merge request analytics: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Merge request**. -## View merge requests merged per month +## View the number of merge requests in a date range > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232651) in GitLab 13.3. > - Filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229266) in GitLab 13.4 -To view the number of merge requests merged per month: +To view the number of merge requests merged during a specific date range: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Merge request**. diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index be710f8cbd7..f8b28ead155 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -4,103 +4,65 @@ group: Optimize 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 --- -# Productivity Analytics **(PREMIUM)** +# Productivity analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12079) in GitLab 12.3. +You can use productivity analytics to identify: -Track development velocity with Productivity Analytics. +- Your development velocity based on how long it takes for a merge request to merge. +- The most time consuming merge requests and potential causes. +- Authors, labels, or milestones with the longest time to merge, or most changes. -For many companies, the development cycle is a black box and getting an estimate of how -long, on average, it takes to deliver features is an enormous endeavor. +Use productivity analytics to view the following merge request statistics for your groups: -While [Value Stream Analytics](../analytics/value_stream_analytics.md) focuses on the entire -Software Development Life Cycle (SDLC) process, Productivity Analytics provides a way for Engineering Management to drill down in a systematic way to uncover patterns and causes for success or failure at an individual, project, or group level. +- Amount of time between merge request creation and merge. +- Amount of time between commits, comments, and merge. +- Complexity of changes, like number of lines of code per commit and number of files. -Productivity can slow down for many reasons ranging from degrading codebase to quickly growing teams. To investigate, department or team leaders can start by visualizing the time it takes for merge requests to be merged. +To view merge request data for projects, use [Merge request analytics](../analytics/merge_request_analytics.md). -## Visualizations and metrics +## View productivity analytics -With Productivity Analytics, GitLab users can: +Prerequisite: -- Visualize typical merge request (MR) lifetime and statistics. A histogram shows the distribution of the time elapsed between creating and merging merge requests. -- Drill down into the most time consuming merge requests, select outliers, and filter subsequent charts to investigate potential causes. -- Filter by group, project, author, label, milestone, or a specific date range. For example, filter down to the merge requests of a specific author in a group or project during a milestone or specific date range. -- Measure velocity over time. To observe progress, visualize the trends of each metric from the charts over time. Zoom in on a particular date range if you notice outliers. +- You must have at least the Reporter role for the group. -## Metrics charts +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Productivity**. +1. Optional. Filter results: + 1. Select a project from the dropdown list. + 1. To filter results by author, milestone, or label, + select **Filter results...** and enter a value. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. -To access the charts, navigate to a group's sidebar and select **Analytics > Productivity Analytics**. -Metrics and visualizations of **merged** merge requests are available on a project or group level. +## View time metrics for merge requests -### Time to merge +Use the following charts in productivity analytics to view the velocity of your merge requests: -The **Time to merge** histogram shows the number of merge requests and the number -of days it took to merge after creation. Select a column to filter subsequent charts. +- **Time to merge**: number of days it took for a +merge requests to merge after they were created. +- **Trendline**: number of merge requests that were merged in a specific time period. - +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Productivity**. -### Trendline +To filter time metrics: -The **Trendline** scatterplot shows all merge requests on a certain date, -and the days it took to complete the action and a 30 day rolling median. Select the dropdown to view: +1. To filter the **Trendline** chart, in the **Time to merge** chart, select a column. +1. To view a specific merge request, below the charts, select a merge request from the **List**. -- Time from first commit to first comment. -- Time from first comment until last commit. -- Time from last commit to merge. -- Number of commits per merge request. -- Number of lines of code (LOC) per commit. -- Number of files touched. +## View commit statistics - +To view commit statistics for your group: -### Commits and merge request size +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Productivity**. +1. Under the **Trendline** scatterplot, view the commit statistics: + - The left histogram shows the number of hours between commits, comments, and merges. + - The right histogram shows the number of commits and changes per merge request. -Under the **Trendline** scatterplot, the left-side histogram shows -the time taken (in hours) between commits and comments until the merge -request is merged. Select the dropdown to view: +To filter commit statistics: -- Time from first commit to first comment. -- Time from first comment until last commit. -- Time from last commit to merge. - -The right-side histogram shows the size or complexity of a merge request. -Select the dropdown to view: - -- Number of commits per merge request. -- Number of lines of code (LOC) per commit. -- Number of files touched. - - - -### Merge request list - -The **List** table shows a list of merge requests with their respective time duration metrics. - -Sort metrics by: - -- Time from first commit to first comment. -- Time from first comment until last commit. -- Time from last commit to merge. - -Filter metrics by: - -- Number of commits per merge request. -- Number of lines of code per commit. -- Number of files touched. - -## Filter by date range - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13188) in GitLab 12.4. - -You can filter analytics based on a date range. To filter results: - -1. Select a group. -1. Optional. Select a project. -1. Select a date range by using the available date pickers. - -## Permissions - -The **Productivity Analytics** dashboard can be accessed only: - -- On [GitLab Premium](https://about.gitlab.com/pricing/) and above. -- By users with at least the Reporter role. +1. To view different types of commit data, select the dropdown list next to each histogram. +1. To view a specific merge request, below the charts, select a merge request from the **List**. diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 96236f60417..80e4700c34c 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -1677,7 +1677,7 @@ For more information, see [Offline environments](../offline_deployments/index.md ## Troubleshooting -### Error waiting for API Security 'http://127.0.0.1:5000' to become available +### `Error waiting for API Security 'http://127.0.0.1:5000' to become available` A bug exists in versions of the API Fuzzing analyzer prior to v1.6.196 that can cause a background process to fail under certain conditions. The solution is to update to a newer version of the DAST API analyzer. @@ -1690,7 +1690,7 @@ If the issue is occurring with versions v1.6.196 or greater, please contact Supp 1. The `gl-api-security-scanner.log` file available as a job artifact. In the right-hand panel of the job details page, select the **Browse** button. 1. The `apifuzzer_fuzz` job definition from your `.gitlab-ci.yml` file. -### Error, the OpenAPI document is not valid. Errors were found during validation of the document using the published OpenAPI schema +### `Error, the OpenAPI document is not valid. Errors were found during validation of the document using the published OpenAPI schema` At the start of an API Fuzzing job the OpenAPI Specification is validated against the [published schema](https://github.com/OAI/OpenAPI-Specification/tree/master/schemas). This error is shown when the provided OpenAPI Specification has validation errors. Errors can be introduced when creating an OpenAPI Specification manually, and also when the schema is generated. @@ -1719,7 +1719,7 @@ For OpenAPI Specifications that are generated automatically validation errors ar 1. Alternatively, you can check the log output and look for schema validation warnings. They are prefixed with messages such as `OpenAPI 2.0 schema validation error` or `OpenAPI 3.0.x schema validation error`. Each failed validation provides extra information about `location` and `description`. Correct each of the validation failures and then resubmit the OpenAPI doc. Note that JSON Schema validation message might not be easy to understand. This is why we recommend the use of editors to validate document. 1. Once the validation issues are resolved, re-run your pipeline. -### Failed to start scanner session (version header not found) +### `Failed to start scanner session (version header not found)` The API Fuzzing engine outputs an error message when it cannot establish a connection with the scanner application component. The error message is shown in the job output window of the `apifuzzer_fuzz` job. A common cause of this issue is changing the `FUZZAPI_API` variable from its default. @@ -1733,7 +1733,7 @@ The API Fuzzing engine outputs an error message when it cannot establish a conne - Remove the `FUZZAPI_API` variable from the `.gitlab-ci.yml` file. The value will be inherited from the API Fuzzing CI/CD template. We recommend this method instead of manually setting a value. - If removing the variable is not possible, check to see if this value has changed in the latest version of the [API Fuzzing CI/CD template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. -### Application cannot determine the base URL for the target API +### `Application cannot determine the base URL for the target API` The API Fuzzing analyzer outputs an error message when it cannot determine the target API after inspecting the OpenAPI document. This error message is shown when the target API has not been set in the `.gitlab-ci.yml`file, it is not available in the `environment_url.txt` file, and it could not be computed using the OpenAPI document. @@ -1802,7 +1802,7 @@ To detect and correct elements that don't comply with the OpenAPI specifications | Editor | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x | | -- | -- | -- | -- | | [Swagger Editor](https://editor.swagger.io/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{dotted-circle}** YAML, JSON | -| [Stoplight Studio](https://stoplight.io/studio/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | +| [Stoplight Studio](https://stoplight.io/studio) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | If your OpenAPI document is generated manually, load your document in the editor and fix anything that is non-compliant. If your document is generated automatically, load it in your editor to identify the issues in the schema, then go to the application and perform the corrections based on the framework you are using. @@ -1826,7 +1826,7 @@ API Security can still try to consume an OpenAPI document that does not fully co FUZZAPI_OPENAPI_RELAXED_VALIDATION: On ``` -### No operation in the OpenAPI document is consuming any supported media type +### `No operation in the OpenAPI document is consuming any supported media type` API Security uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. @@ -1844,7 +1844,7 @@ API Security uses the specified media types in the OpenAPI document to generate To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). The [GitLab issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues) is the right place for bugs and feature proposals about API Security and API Fuzzing. -Please use `~"Category:API Security"` [label](../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding API fuzzing to ensure it is quickly reviewed by the right people. Please refer to our [review response SLO](../../../development/code_review.md#review-response-slo) to understand when you should receive a response. +Please use `~"Category:API Security"` [label](../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding API fuzzing to ensure it is quickly reviewed by the right people. Please refer to our [review response SLO](https://about.gitlab.com/handbook/engineering/workflow/code-review/#review-response-slo) to understand when you should receive a response. [Search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) for similar entries before submitting your own, there's a good chance somebody else had the same issue or feature proposal. Show your support with an award emoji and or join the discussion. diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index cf864068e44..7bb3cb4f64c 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -7,7 +7,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Container Scanning **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in GitLab 10.4. +> - Improved support for FIPS [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) in GitLab 13.6 by upgrading `CS_MAJOR_VERSION` from `2` to `3`. +> - Integration with Trivy [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322656) in GitLab 13.9 by upgrading `CS_MAJOR_VERSION` from `3` to `4`. +> - Integration with Clair [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/321451) in GitLab 13.9. +> - Default container scanning with Trivy [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61850) in GitLab 14.0. +> - Integration with Grype as an alternative scanner [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326279) in GitLab 14.0. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86092) the major analyzer version from `4` to `5` in GitLab 15.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86783) from GitLab Ultimate to GitLab Free in 15.0. Your application's Docker image may itself be based on Docker images that contain known vulnerabilities. By including an extra Container Scanning job in your pipeline that scans for those @@ -19,7 +25,7 @@ aspects of inspecting the items your code uses. These items typically include ap dependencies that are almost always imported from external sources, rather than sourced from items you wrote yourself. -GitLab offers both Container Scanning and [Dependency Scanning](../dependency_scanning/) +GitLab offers both Container Scanning and [Dependency Scanning](../dependency_scanning/index.md) to ensure coverage for all of these dependency types. To cover as much of your risk area as possible, we encourage you to use all of our security scanners. @@ -68,7 +74,7 @@ information directly in the merge request. To enable container scanning in your pipeline, you need the following: -- Container Scanning runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. +- GitLab CI/CD pipeline must include the `test` stage, which is available unless overridden with the [`stages`](../../../ci/yaml/index.md#stages) keyword. - [GitLab Runner](https://docs.gitlab.com/runner/) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor on Linux/amd64. - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the @@ -79,7 +85,6 @@ To enable container scanning in your pipeline, you need the following: - If you're using a third-party container registry, you might need to provide authentication credentials through the `DOCKER_USER` and `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). For more details on how to use these variables, see [authenticate to a remote registry](#authenticate-to-a-remote-registry). -- GitLab CI/CD pipeline must include the `test` stage, which is available unless overridden with the [`stages`](../../../ci/yaml/index.md#stages) keyword. ## Configuration @@ -224,7 +229,7 @@ container_scanning: CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN: "false" ``` -When you enable this feature, you may see [duplicate findings](../terminology/#duplicate-finding) +When you enable this feature, you may see [duplicate findings](../terminology/index.md#duplicate-finding) in the [Vulnerability Report](../vulnerability_report/) if [Dependency Scanning](../dependency_scanning/) is enabled for your project. This happens because GitLab can't automatically deduplicate findings @@ -680,7 +685,7 @@ It's possible to run the [GitLab container scanning tool](https://gitlab.com/git against a Docker container without needing to run it within the context of a CI job. To scan an image directly, follow these steps: -1. Run [Docker Desktop](https://www.docker.com/products/docker-desktop) +1. Run [Docker Desktop](https://www.docker.com/products/docker-desktop/) or [Docker Machine](https://github.com/docker/machine). 1. Run the analyzer's Docker image, passing the image and tag you want to analyze in the @@ -700,101 +705,21 @@ The results are stored in `gl-container-scanning-report.json`. ## Reports JSON format -The container scanning tool emits a JSON report file. For more information, see the -[schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/container-scanning-report-format.json). - -Here's an example container scanning report: - -```json-doc -{ - "version": "14.0.0", - "vulnerabilities": [ - { - "id": "df52bc8ce9a2ae56bbcb0c4ecda62123fbd6f69b", - "category": "container_scanning", - "message": "CVE-2019-3462 in apt-1.4.8", - "description": "Incorrect sanitation of the 302 redirect field in HTTP transport method of apt versions 1.4.8 and earlier can lead to content injection by a MITM attacker, potentially leading to remote code execution on the target machine.", - "severity": "High", - "confidence": "Unknown", - "solution": "Upgrade apt from 1.4.8 to 1.4.9", - "scanner": { - "id": "trivy", - "name": "trivy" - }, - "location": { - "dependency": { - "package": { - "name": "apt" - }, - "version": "1.4.8" - }, - "operating_system": "debian:9.4", - "image": "registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256:bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e", - "default_branch_image": "registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0:latest" - }, - "identifiers": [ - { - "type": "cve", - "name": "CVE-2019-3462", - "value": "CVE-2019-3462", - "url": "http://www.securityfocus.com/bid/106690" - } - ], - "links": [ - { - "url": "http://www.securityfocus.com/bid/106690" - }, - { - "url": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-3462" - }, - { - "url": "https://lists.apache.org/thread.html/8338a0f605bdbb3a6098bb76f666a95fc2b2f53f37fa1ecc89f1146f@%3Cdevnull.infra.apache.org%3E" - }, - { - "url": "https://lists.debian.org/debian-lts-announce/2019/01/msg00013.html" - }, - { - "url": "https://lists.debian.org/debian-lts-announce/2019/01/msg00014.html" - }, - { - "url": "https://security.netapp.com/advisory/ntap-20190125-0002/" - }, - { - "url": "https://usn.ubuntu.com/3863-1/" - }, - { - "url": "https://usn.ubuntu.com/3863-2/" - }, - { - "url": "https://usn.ubuntu.com/usn/usn-3863-1" - }, - { - "url": "https://usn.ubuntu.com/usn/usn-3863-2" - }, - { - "url": "https://www.debian.org/security/2019/dsa-4371" - } - ] - } - ], - "remediations": [] - "scan": { - "scanner": { - "id": "trivy", - "name": "Trivy", - "url": "https://github.com/aquasecurity/trivy/", - "vendor": { - "name": "GitLab" - }, - "version": "0.16.0" - }, - "type": "container_scanning", - "start_time": "2021-04-14T19:45:58", - "end_time": "2021-04-14T19:46:18", - "status": "success" - } -} -``` +The container scanning tool emits JSON reports which the [GitLab Runner](https://docs.gitlab.com/runner/) +recognizes through the [`artifacts:reports`](../../../ci/yaml/#artifactsreports) +keyword in the CI configuration file. + +Once the CI job finishes, the Runner uploads these reports to GitLab, which are then available in +the CI Job artifacts. In GitLab Ultimate, these reports can be viewed in the corresponding [pipeline](../vulnerability_report/pipeline.md) +and become part of the [Vulnerability Report](../vulnerability_report/). + +These reports must follow a format defined in the +[security report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/). See: + +- [Latest schema for the container scanning report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/container-scanning-report-format.json). +- [Example container scanning report](https://gitlab.com/gitlab-examples/security/security-reports/-/blob/master/samples/container-scanning.json) + +For more information, see [Security scanner integration](../../../development/integrations/secure.md). ## Security Dashboard @@ -878,27 +803,5 @@ For information on this, see the [general Application Security troubleshooting s ## Changes -- GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for - [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the - `CS_MAJOR_VERSION` from `2` to `3`. Version `3` of the `container_scanning` Docker image uses - [`centos:centos8`](https://hub.docker.com/_/centos) - as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77) - script and instead executes the analyzer by default. Any customizations made to the - `container_scanning` job's [`before_script`](../../../ci/yaml/index.md#before_script) - and [`after_script`](../../../ci/yaml/index.md#after_script) - blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based - Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-cicd-variables) - variable. -- GitLab 13.9 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322656) integration with - [Trivy](https://github.com/aquasecurity/trivy) by upgrading `CS_MAJOR_VERSION` from `3` to `4`. -- GitLab 13.9 [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/321451) the integration with - [Clair](https://github.com/quay/clair/). -- GitLab 14.0 [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61850) - an integration with [Trivy](https://github.com/aquasecurity/trivy) - as the default for container scanning, and also [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326279) - an integration with [Grype](https://github.com/anchore/grype) - as an alternative scanner. -- GitLab 15.0 changed the major analyzer version from `4` to `5`. - -Other changes to the container scanning analyzer can be found in the project's +Changes to the container scanning analyzer can be found in the project's [changelog](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/blob/master/CHANGELOG.md). diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index ac3b266ad48..154884c16e7 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -367,12 +367,12 @@ vulnerability: ## Troubleshooting -### Error "Unable to extract corpus folder from artifacts zip file" +### Error `Unable to extract corpus folder from artifacts zip file` If you see this error message, and `COVFUZZ_USE_REGISTRY` is set to `true`, ensure that the uploaded corpus file extracts into a folder named `corpus`. -### Error "400 Bad request - Duplicate package is not allowed" +### Error `400 Bad request - Duplicate package is not allowed` If you see this error message when running the fuzzing job with `COVFUZZ_USE_REGISTRY` set to `true`, ensure that duplicates are allowed. For more details, see diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index ffcd496e2c3..e8373b0c0b7 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -5,34 +5,42 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# DAST browser-based crawler **(ULTIMATE)** +# DAST browser-based analyzer **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323423) in GitLab 13.12. WARNING: This product is in an early-access stage and is considered a [beta](../../../policy/alpha-beta-support.md#beta-features) feature. -GitLab DAST's new browser-based crawler is a crawl engine built by GitLab to test Single Page Applications (SPAs) and traditional web applications. -Due to the reliance of modern web applications on JavaScript, handling SPAs or applications that are dependent on JavaScript is paramount to ensuring proper coverage of an application for Dynamic Application Security Testing (DAST). +GitLab DAST's browser-based analyzer was built by GitLab to test Single Page Applications (SPAs) and +traditional web applications. It both crawls the web application and analyzes the resulting output +for vulnerabilities. Analysis of modern applications, heavily reliant on JavaScript, is vital to +ensuring DAST coverage. -The browser-based crawler works by loading the target application into a specially-instrumented Chromium browser. A snapshot of the page is taken before a search to find any actions that a user might perform, -such as clicking on a link or filling in a form. For each action found, the crawler executes it, takes a new snapshot, and determines what in the page changed from the previous snapshot. -Crawling continues by taking more snapshots and finding subsequent actions. +The browser-based scanner works by loading the target application into a specially-instrumented +Chromium browser. A snapshot of the page is taken before a search to find any actions that a user +might perform, such as clicking on a link or filling in a form. For each action found, the +browser-based scanner executes it, takes a new snapshot, and determines what in the page changed +from the previous snapshot. Crawling continues by taking more snapshots and finding subsequent +actions. The benefit of scanning by following user actions in a browser is that the crawler can +interact with the target application much like a real user would, identifying complex flows that +traditional web crawlers don't understand. This results in better coverage of the website. -The benefit of crawling by following user actions in a browser is that the crawler can interact with the target application much like a real user would, identifying complex flows that traditional web crawlers don't understand. This results in better coverage of the website. +The browser-based scanner should provide greater coverage for most web applications, compared +with the current DAST AJAX crawler. While both crawlers are +used together with the current DAST scanner, the combination of the browser-based crawler with the +current DAST scanner is much more effective at finding and testing every page in an application. -Using the browser-based crawler should provide greater coverage for most web applications, compared with the current DAST AJAX crawler. The new crawler replaces the AJAX crawler and is specifically designed to maximize crawl coverage in modern web applications. While both crawlers are currently used in conjunction with the existing DAST scanner, the combination of the browser-based crawler with the current DAST scanner is much more effective at finding and testing every page in an application. +## Enable browser-based analyzer -## Enable browser-based crawler - -The browser-based crawler is an extension to the GitLab DAST product. DAST should be included in the CI/CD configuration and the browser-based crawler enabled using CI/CD variables: +To enable the browser-based analyzer: 1. Ensure the DAST [prerequisites](index.md#prerequisites) are met. -1. Include the [DAST CI template](index.md#include-the-dast-template). -1. Set the target website using the `DAST_WEBSITE` CI/CD variable. +1. Include the [DAST CI/CD template](index.md#include-the-dast-template). +1. Set the target website using the [`DAST_WEBSITE` CI/CD variable](index.md#available-cicd-variables). 1. Set the CI/CD variable `DAST_BROWSER_SCAN` to `true`. -An example configuration might look like the following: +Example extract of `.gitlab-ci.yml` file: ```yaml include: @@ -77,13 +85,20 @@ The [DAST variables](index.md#available-cicd-variables) `SECURE_ANALYZERS_PREFIX ## Vulnerability detection -While the browser-based crawler crawls modern web applications efficiently, vulnerability detection is still managed by the standard DAST/Zed Attack Proxy (ZAP) solution. +Vulnerability detection is gradually being migrated from the default Zed Attack Proxy (ZAP) solution +to the browser-based analyzer. For details of the vulnerability detection already migrated, see +[browser-based vulnerability checks](checks/index.md). -The crawler runs the target website in a browser with DAST/ZAP configured as the proxy server. This ensures that all requests and responses made by the browser are passively scanned by DAST/ZAP. -When running a full scan, active vulnerability checks executed by DAST/ZAP do not use a browser. This difference in how vulnerabilities are checked can cause issues that require certain features of the target website to be disabled to ensure the scan works as intended. +The crawler runs the target website in a browser with DAST/ZAP configured as the proxy server. This +ensures that all requests and responses made by the browser are passively scanned by DAST/ZAP. When +running a full scan, active vulnerability checks executed by DAST/ZAP do not use a browser. This +difference in how vulnerabilities are checked can cause issues that require certain features of the +target website to be disabled to ensure the scan works as intended. -For example, for a target website that contains forms with Anti-CSRF tokens, a passive scan works as intended because the browser displays pages and forms as if a user is viewing the page. -However, active vulnerability checks that run in a full scan cannot submit forms containing Anti-CSRF tokens. In such cases, we recommend you disable Anti-CSRF tokens when running a full scan. +For example, for a target website that contains forms with Anti-CSRF tokens, a passive scan works as +intended because the browser displays pages and forms as if a user is viewing the page. However, +active vulnerability checks that run in a full scan cannot submit forms containing Anti-CSRF tokens. +In such cases, we recommend you disable Anti-CSRF tokens when running a full scan. ## Managing scan time diff --git a/doc/user/application_security/dast/checks/16.7.md b/doc/user/application_security/dast/checks/16.7.md index a02fb3a451f..2e6607575db 100644 --- a/doc/user/application_security/dast/checks/16.7.md +++ b/doc/user/application_security/dast/checks/16.7.md @@ -25,8 +25,8 @@ Only three directives are applicable for the `Strict-Transport-Security` header. Note that invalid directives, or the `Strict-Transport-Security` header appearing more than once (if the values are different) is considered invalid. -Prior to adding to this security configuration to your website, it is recommended you review the hstspreload.org [Deployment -Recommendations](https://hstspreload.org/#deployment-recommendations). +Prior to adding to this security configuration to your website, it is recommended you review the hstspreload.org +[Deployment Recommendations](https://hstspreload.org/#deployment-recommendations). ## Details diff --git a/doc/user/application_security/dast/checks/601.1.md b/doc/user/application_security/dast/checks/601.1.md index 60249c2562d..c51b00cdd36 100644 --- a/doc/user/application_security/dast/checks/601.1.md +++ b/doc/user/application_security/dast/checks/601.1.md @@ -30,5 +30,5 @@ then be used to redirect the user, using the 301 response code and `Location` he ## Links -- [OWASP](https://owasp.org/www-project-cheat-sheets/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html) +- [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html) - [CWE](https://cwe.mitre.org/data/definitions/601.html) diff --git a/doc/user/application_security/dast/checks/798.45.md b/doc/user/application_security/dast/checks/798.45.md deleted file mode 100644 index a800063f15d..00000000000 --- a/doc/user/application_security/dast/checks/798.45.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -stage: Secure -group: Dynamic 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 ---- - -# Exposure of confidential secret or token Finicity Public Key - -## Description - -The response body contains content that matches the pattern of a Finicity Public Key. -Exposing this value could allow attackers to gain access to all resources granted by this token. - -## Remediation - -Review the response body content and remove any exposed values. - -## Details - -| ID | Aggregated | CWE | Type | Risk | -|:---|:--------|:--------|:--------|:--------| -| 798.45 | false | 798 | Passive | High | - -## Links - -- [CWE](https://cwe.mitre.org/data/definitions/798.html) diff --git a/doc/user/application_security/dast/checks/798.51.md b/doc/user/application_security/dast/checks/798.51.md deleted file mode 100644 index f131d31ae65..00000000000 --- a/doc/user/application_security/dast/checks/798.51.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -stage: Secure -group: Dynamic 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 ---- - -# Exposure of confidential secret or token GCP API key - -## Description - -The response body contains content that matches the pattern of a GCP API key. -Exposing this value could allow attackers to gain access to all resources granted by this token. - -## Remediation - -Review the response body content and remove any exposed values. - -## Details - -| ID | Aggregated | CWE | Type | Risk | -|:---|:--------|:--------|:--------|:--------| -| 798.51 | false | 798 | Passive | High | - -## Links - -- [CWE](https://cwe.mitre.org/data/definitions/798.html) diff --git a/doc/user/application_security/dast/checks/798.71.md b/doc/user/application_security/dast/checks/798.71.md deleted file mode 100644 index f0bcc43940d..00000000000 --- a/doc/user/application_security/dast/checks/798.71.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -stage: Secure -group: Dynamic 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 ---- - -# Exposure of confidential secret or token Lob Publishable API Key - -## Description - -The response body contains content that matches the pattern of a Lob Publishable API Key. -Exposing this value could allow attackers to gain access to all resources granted by this token. - -## Remediation - -Review the response body content and remove any exposed values. - -## Details - -| ID | Aggregated | CWE | Type | Risk | -|:---|:--------|:--------|:--------|:--------| -| 798.71 | false | 798 | Passive | High | - -## Links - -- [CWE](https://cwe.mitre.org/data/definitions/798.html) diff --git a/doc/user/application_security/dast/checks/798.73.md b/doc/user/application_security/dast/checks/798.73.md deleted file mode 100644 index eae41a49782..00000000000 --- a/doc/user/application_security/dast/checks/798.73.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -stage: Secure -group: Dynamic 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 ---- - -# Exposure of confidential secret or token Mailgun public validation key - -## Description - -The response body contains content that matches the pattern of a Mailgun public validation key. -Exposing this value could allow attackers to gain access to all resources granted by this token. - -## Remediation - -Review the response body content and remove any exposed values. - -## Details - -| ID | Aggregated | CWE | Type | Risk | -|:---|:--------|:--------|:--------|:--------| -| 798.73 | false | 798 | Passive | High | - -## Links - -- [CWE](https://cwe.mitre.org/data/definitions/798.html) diff --git a/doc/user/application_security/dast/checks/798.76.md b/doc/user/application_security/dast/checks/798.76.md deleted file mode 100644 index 87e6364184f..00000000000 --- a/doc/user/application_security/dast/checks/798.76.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -stage: Secure -group: Dynamic 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 ---- - -# Exposure of confidential secret or token MapBox API token - -## Description - -The response body contains content that matches the pattern of a MapBox API token. -Exposing this value could allow attackers to gain access to all resources granted by this token. - -## Remediation - -Review the response body content and remove any exposed values. - -## Details - -| ID | Aggregated | CWE | Type | Risk | -|:---|:--------|:--------|:--------|:--------| -| 798.76 | false | 798 | Passive | High | - -## Links - -- [CWE](https://cwe.mitre.org/data/definitions/798.html) diff --git a/doc/user/application_security/dast/checks/798.79.md b/doc/user/application_security/dast/checks/798.79.md deleted file mode 100644 index 9a580658a72..00000000000 --- a/doc/user/application_security/dast/checks/798.79.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -stage: Secure -group: Dynamic 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 ---- - -# Exposure of confidential secret or token MessageBird client ID - -## Description - -The response body contains content that matches the pattern of a MessageBird client ID. -Exposing this value could allow attackers to gain access to all resources granted by this token. - -## Remediation - -Review the response body content and remove any exposed values. - -## Details - -| ID | Aggregated | CWE | Type | Risk | -|:---|:--------|:--------|:--------|:--------| -| 798.79 | false | 798 | Passive | High | - -## Links - -- [CWE](https://cwe.mitre.org/data/definitions/798.html) diff --git a/doc/user/application_security/dast/checks/798.85.md b/doc/user/application_security/dast/checks/798.85.md deleted file mode 100644 index 0726bdc7fd8..00000000000 --- a/doc/user/application_security/dast/checks/798.85.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -stage: Secure -group: Dynamic 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 ---- - -# Exposure of confidential secret or token Nytimes Access Token - -## Description - -The response body contains content that matches the pattern of a Nytimes Access Token. -Exposing this value could allow attackers to gain access to all resources granted by this token. - -## Remediation - -Review the response body content and remove any exposed values. - -## Details - -| ID | Aggregated | CWE | Type | Risk | -|:---|:--------|:--------|:--------|:--------| -| 798.85 | false | 798 | Passive | High | - -## Links - -- [CWE](https://cwe.mitre.org/data/definitions/798.html) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index cdfebc07ef2..387682318e6 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -81,13 +81,11 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [798.42](798.42.md) | Exposure of confidential secret or token Finicity API token | High | Passive | | [798.43](798.43.md) | Exposure of confidential secret or token Flickr Access Token | High | Passive | | [798.44](798.44.md) | Exposure of confidential secret or token Finnhub Access Token | High | Passive | -| [798.45](798.45.md) | Exposure of confidential secret or token Finicity Public Key | High | Passive | | [798.46](798.46.md) | Exposure of confidential secret or token Flutterwave Secret Key | High | Passive | | [798.47](798.47.md) | Exposure of confidential secret or token Flutterwave Encryption Key | High | Passive | | [798.48](798.48.md) | Exposure of confidential secret or token Frame.io API token | High | Passive | | [798.49](798.49.md) | Exposure of confidential secret or token Freshbooks Access Token | High | Passive | | [798.50](798.50.md) | Exposure of confidential secret or token GoCardless API token | High | Passive | -| [798.51](798.51.md) | Exposure of confidential secret or token GCP API key | High | Passive | | [798.52](798.52.md) | Exposure of confidential secret or token GitHub Personal Access Token | High | Passive | | [798.53](798.53.md) | Exposure of confidential secret or token GitHub OAuth Access Token | High | Passive | | [798.54](798.54.md) | Exposure of confidential secret or token GitHub App Token | High | Passive | @@ -107,21 +105,16 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [798.68](798.68.md) | Exposure of confidential secret or token LinkedIn Client ID | High | Passive | | [798.69](798.69.md) | Exposure of confidential secret or token LinkedIn Client secret | High | Passive | | [798.70](798.70.md) | Exposure of confidential secret or token Lob API Key | High | Passive | -| [798.71](798.71.md) | Exposure of confidential secret or token Lob Publishable API Key | High | Passive | | [798.72](798.72.md) | Exposure of confidential secret or token Mailchimp API key | High | Passive | -| [798.73](798.73.md) | Exposure of confidential secret or token Mailgun public validation key | High | Passive | | [798.74](798.74.md) | Exposure of confidential secret or token Mailgun private API token | High | Passive | | [798.75](798.75.md) | Exposure of confidential secret or token Mailgun webhook signing key | High | Passive | -| [798.76](798.76.md) | Exposure of confidential secret or token MapBox API token | High | Passive | | [798.77](798.77.md) | Exposure of confidential secret or token Mattermost Access Token | High | Passive | | [798.78](798.78.md) | Exposure of confidential secret or token MessageBird API token | High | Passive | -| [798.79](798.79.md) | Exposure of confidential secret or token MessageBird client ID | High | Passive | | [798.80](798.80.md) | Exposure of confidential secret or token Netlify Access Token | High | Passive | | [798.81](798.81.md) | Exposure of confidential secret or token New Relic user API Key | High | Passive | | [798.82](798.82.md) | Exposure of confidential secret or token New Relic user API ID | High | Passive | | [798.83](798.83.md) | Exposure of confidential secret or token New Relic ingest browser API token | High | Passive | | [798.84](798.84.md) | Exposure of confidential secret or token npm access token | High | Passive | -| [798.85](798.85.md) | Exposure of confidential secret or token Nytimes Access Token | High | Passive | | [798.86](798.86.md) | Exposure of confidential secret or token Okta Access Token | High | Passive | | [798.87](798.87.md) | Exposure of confidential secret or token Plaid Client ID | High | Passive | | [798.88](798.88.md) | Exposure of confidential secret or token Plaid Secret key | High | Passive | diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index f8aa2e3d1c6..a49dd8fd646 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -351,7 +351,7 @@ include: - template: DAST-API.gitlab-ci.yml variables: - DAST_API_OPENAPI: http://my.api/api-specification.yml + DAST_API_SPECIFICATION: http://my.api/api-specification.yml ``` #### Import API specification from a file @@ -366,7 +366,7 @@ dast: - cp api-specification.yml /zap/wrk/api-specification.yml variables: GIT_STRATEGY: fetch - DAST_API_OPENAPI: api-specification.yml + DAST_API_SPECIFICATION: api-specification.yml ``` #### Full API scan @@ -402,7 +402,7 @@ include: - template: DAST-API.gitlab-ci.yml variables: - DAST_API_OPENAPI: http://api-test.host.com/api-specification.yml + DAST_API_SPECIFICATION: http://api-test.host.com/api-specification.yml DAST_API_HOST_OVERRIDE: api-test.host.com ``` @@ -417,7 +417,7 @@ include: - template: DAST-API.gitlab-ci.yml variables: - DAST_API_OPENAPI: http://api-test.api.com/api-specification.yml + DAST_API_SPECIFICATION: http://api-test.api.com/api-specification.yml DAST_REQUEST_HEADERS: "Authorization: Bearer my.token" ``` @@ -633,8 +633,7 @@ including a large number of false positives. | `DAST_ADVERTISE_SCAN` | boolean | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334947) in GitLab 14.1. | | `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. | | `DAST_API_HOST_OVERRIDE` <sup>1</sup> | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080`. | -| `DAST_API_OPENAPI` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. The variable `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_API_SPECIFICATION` <sup>1</sup> | URL or string | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290241)** in GitLab 15.0. Replaced by `DAST_API_OPENAPI`. The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. The variable `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_API_SPECIFICATION` <sup>1</sup> | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. The variable `DAST_WEBSITE` must be specified if this is omitted. | | `DAST_AUTH_REPORT` <sup>2</sup> | boolean | Used in combination with exporting the `gl-dast-debug-auth-report.html` artifact to aid in debugging authentication issues. | | `DAST_AUTH_EXCLUDE_URLS` <sup>2</sup> | URLs | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289959)** in GitLab 14.0. Replaced by `DAST_EXCLUDE_URLS`. The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | | `DAST_AUTH_URL` <sup>1,2</sup> | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. Example: `https://login.example.com`. | @@ -671,7 +670,7 @@ including a large number of false positives. | `DAST_USERNAME` <sup>1,2</sup> | string | The username to authenticate to in the website. Example: `admin` | | `DAST_USERNAME_FIELD` <sup>1,2</sup> | string | The selector of username field at the sign-in HTML form. Example: `name:username` | | `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_WEBSITE` <sup>1</sup> | URL | The URL of the website to scan. The variable `DAST_API_OPENAPI` must be specified if this is omitted. | +| `DAST_WEBSITE` <sup>1</sup> | URL | The URL of the website to scan. The variable `DAST_API_SPECIFICATION` must be specified if this is omitted. | | `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. Example: `logger.httpsender.name=org.parosproxy.paros.network.HttpSender;logger.httpsender.level=debug;logger.sitemap.name=org.parosproxy.paros.model.SiteMap;logger.sitemap.level=debug;` | | `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | @@ -995,8 +994,7 @@ An on-demand scan can be run in active or passive mode: - _Passive mode_ is the default and runs a ZAP Baseline Scan. - _Active mode_ runs a ZAP Full Scan which is potentially harmful to the site being scanned. To - minimize the risk of accidental damage, running an active scan requires a [validated site - profile](#site-profile-validation). + minimize the risk of accidental damage, running an active scan requires a [validated site profile](#site-profile-validation). ### View on-demand DAST scans diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index fdca02267e4..1f86f2ffa49 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -1524,7 +1524,7 @@ For more information, see [Offline environments](../offline_deployments/index.md ## Troubleshooting -### Error waiting for API Security 'http://127.0.0.1:5000' to become available +### `Error waiting for API Security 'http://127.0.0.1:5000' to become available` A bug exists in versions of the DAST API analyzer prior to v1.6.196 that can cause a background process to fail under certain conditions. The solution is to update to a newer version of the DAST API analyzer. @@ -1537,7 +1537,7 @@ If the issue is occurring with versions v1.6.196 or greater, please contact Supp 1. The `gl-api-security-scanner.log` file available as a job artifact. In the right-hand panel of the job details page, select the **Browse** button. 1. The `dast_api` job definition from your `.gitlab-ci.yml` file. -### Failed to start scanner session (version header not found) +### `Failed to start scanner session (version header not found)` The DAST API engine outputs an error message when it cannot establish a connection with the scanner application component. The error message is shown in the job output window of the `dast_api` job. A common cause of this issue is changing the `DAST_API_API` variable from its default. @@ -1551,7 +1551,7 @@ The DAST API engine outputs an error message when it cannot establish a connecti - Remove the `DAST_API_API` variable from the `.gitlab-ci.yml` file. The value will be inherited from the DAST API CI/CD template. We recommend this method instead of manually setting a value. - If removing the variable is not possible, check to see if this value has changed in the latest version of the [DAST API CI/CD template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. -### Application cannot determine the base URL for the target API +### `Application cannot determine the base URL for the target API` The DAST API engine outputs an error message when it cannot determine the target API after inspecting the OpenAPI document. This error message is shown when the target API has not been set in the `.gitlab-ci.yml` file, it is not available in the `environment_url.txt` file, and it could not be computed using the OpenAPI document. @@ -1612,7 +1612,7 @@ To detect and correct elements that don't comply with the OpenAPI specifications | Editor | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x | | -- | -- | -- | -- | | [Swagger Editor](https://editor.swagger.io/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{dotted-circle}** YAML, JSON | -| [Stoplight Studio](https://stoplight.io/studio/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | +| [Stoplight Studio](https://stoplight.io/studio) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | If your OpenAPI document is generated manually, load your document in the editor and fix anything that is non-compliant. If your document is generated automatically, load it in your editor to identify the issues in the schema, then go to the application and perform the corrections based on the framework you are using. @@ -1636,7 +1636,7 @@ API Security can still try to consume an OpenAPI document that does not fully co DAST_API_OPENAPI_RELAXED_VALIDATION: On ``` -### No operation in the OpenAPI document is consuming any supported media type +### `No operation in the OpenAPI document is consuming any supported media type` API Security uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. @@ -1654,7 +1654,7 @@ API Security uses the specified media types in the OpenAPI document to generate To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). The [GitLab issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues) is the right place for bugs and feature proposals about API Security and DAST API. -Please use `~"Category:API Security"` [label](../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding DAST API to ensure it is quickly reviewed by the right people. Please refer to our [review response SLO](../../../development/code_review.md#review-response-slo) to understand when you should receive a response. +Please use `~"Category:API Security"` [label](../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding DAST API to ensure it is quickly reviewed by the right people. Please refer to our [review response SLO](https://about.gitlab.com/handbook/engineering/workflow/code-review/#review-response-slo) to understand when you should receive a response. [Search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) for similar entries before submitting your own, there's a good chance somebody else had the same issue or feature proposal. Show your support with an award emoji and or join the discussion. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index d0a91ab664e..521bb6adbf0 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -109,6 +109,8 @@ maximum of two directory levels from the repository's root. For example, the `gemnasium-dependency_scanning` job is enabled if a repository contains either `Gemfile`, `api/Gemfile`, or `api/client/Gemfile`, but not if the only supported dependency file is `api/v1/client/Gemfile`. +For Java and Python, when a supported depedency file is detected, Dependency Scanning attempts to build the project and execute some Java or Python commands to get the list of dependencies. For all other projects, the lock file is parsed to obtain the list of dependencies without needing to build the project first. + When a supported dependency file is detected, all dependencies, including transitive dependencies are analyzed. There is no limit to the depth of nested or transitive dependencies that are analyzed. The following languages and dependency managers are supported: @@ -148,14 +150,13 @@ table.supported-languages ul { <th>Language Versions</th> <th>Package Manager</th> <th>Supported files</th> - <th>Analyzer</th> <th><a href="#how-multiple-files-are-processed">Processes multiple files?</a></th> </tr> </thead> <tbody> <tr> <td>Ruby</td> - <td>Not applicable</td> + <td>All versions</td> <td><a href="https://bundler.io/">Bundler</a></td> <td> <ul> @@ -163,23 +164,20 @@ table.supported-languages ul { <li><code>gems.locked</code></li> </ul> </td> - <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>Y</td> </tr> <tr> <td>PHP</td> - <td>Not applicable</td> + <td>All versions</td> <td><a href="https://getcomposer.org/">Composer</a></td> <td><code>composer.lock</code></td> - <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>Y</td> </tr> <tr> <td>C</td> - <td rowspan="2">Not applicable</td> + <td rowspan="2">All versions</td> <td rowspan="2"><a href="https://conan.io/">Conan</a></td> <td rowspan="2"><a href="https://docs.conan.io/en/latest/versioning/lockfiles.html"><code>conan.lock</code></a></td> - <td rowspan="2"><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td rowspan="2">Y</td> </tr> <tr> @@ -187,10 +185,9 @@ table.supported-languages ul { </tr> <tr> <td>Go</td> - <td>Not applicable</td> + <td>All versions</td> <td><a href="https://go.dev/">Go</a></td> <td><code>go.sum</code></td> - <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>Y</td> </tr> <tr> @@ -211,41 +208,36 @@ table.supported-languages ul { <li><code>build.gradle.kts</code></li> </ul> </td> - <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>N</td> </tr> <tr> <td><a href="https://maven.apache.org/">Maven</a></td> <td><code>pom.xml</code></td> - <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>N</td> </tr> <tr> <td rowspan="2">JavaScript</td> - <td>Not applicable</td> + <td>All versions</td> <td><a href="https://www.npmjs.com/">npm</a></td> <td> <ul> - <li><code>package-lock.json</code></li> + <li><code>package-lock.json</code><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-3">3</a></b></sup></li> <li><code>npm-shrinkwrap.json</code></li> </ul> </td> - <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>Y</td> </tr> <tr> - <td>Not applicable</td> + <td>All versions</td> <td><a href="https://classic.yarnpkg.com/en/">yarn</a></td> <td><code>yarn.lock</code></td> - <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>Y</td> </tr> <tr> <td>.NET</td> - <td rowspan="2">Not applicable</td> + <td rowspan="2">All versions</td> <td rowspan="2"><a href="https://www.nuget.org/">NuGet</a></td> <td rowspan="2"><a href="https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file"><code>packages.lock.json</code></a></td> - <td rowspan="2"><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td rowspan="2">Y</td> </tr> <tr> @@ -256,7 +248,6 @@ table.supported-languages ul { <td rowspan="4">3.9</td> <td><a href="https://setuptools.readthedocs.io/en/latest/">setuptools</a></td> <td><code>setup.py</code></td> - <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>N</td> </tr> <tr> @@ -268,7 +259,6 @@ table.supported-languages ul { <li><code>requires.txt</code></li> </ul> </td> - <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>N</td> </tr> <tr> @@ -276,24 +266,21 @@ table.supported-languages ul { <td> <ul> <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile</code></a></li> - <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-3">3</a></b></sup></li> + <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-4">4</a></b></sup></li> </ul> </td> - <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>N</td> </tr> <tr> <td><a href="https://python-poetry.org/">Poetry</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-5">5</a></b></sup></td> <td><code>poetry.lock</code></td> - <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>N</td> </tr> <tr> <td>Scala</td> - <td>Not applicable</td> - <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-4">4</a></b></sup></td> + <td>All versions</td> + <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-6">6</a></b></sup></td> <td><code>build.sbt</code></td> - <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>N</td> </tr> </tbody> @@ -311,12 +298,18 @@ table.supported-languages ul { <p> Although Gradle with Java 8 is supported, there are other issues such that Android project builds are not supported at this time. Please see the backlog issue <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/336866">Android support for Dependency - Scanning (gemnasium-maven)</a> for more details. Also, Gradle is not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. + Scanning (gemnasium-maven)</a> for more details. Also, Gradle is not supported when <a href="https://docs.gitlab.com/ee/development/fips_compliance.html#enable-fips-mode">FIPS mode</a> is enabled. </p> </li> <li> <a id="notes-regarding-supported-languages-and-package-managers-3"></a> <p> + npm is only supported when `lockfileVersion = 1` or `lockfileVersion = 2`. Work to add support for `lockfileVersion = 3` is being tracked in issue <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">GitLab#365176</a>. + </p> + </li> + <li> + <a id="notes-regarding-supported-languages-and-package-managers-4"></a> + <p> The presence of a <code>Pipfile.lock</code> file alone will <i>not</i> trigger the analyzer; the presence of a <code>Pipfile</code> is still required in order for the analyzer to be executed. However, if a <code>Pipfile.lock</code> file is found, it will be used by <code>Gemnasium</code> to scan the exact package versions listed in this file. @@ -328,12 +321,6 @@ table.supported-languages ul { </p> </li> <li> - <a id="notes-regarding-supported-languages-and-package-managers-4"></a> - <p> - Support for <a href="https://www.scala-sbt.org/">sbt</a> 1.3 and above was added in GitLab 13.9. - </p> - </li> - <li> <a id="notes-regarding-supported-languages-and-package-managers-5"></a> <p> Support for <a href="https://python-poetry.org/">Poetry</a> projects with a <code>poetry.lock</code> file was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/7006">added in GitLab 15.0</a>. @@ -341,6 +328,12 @@ table.supported-languages ul { <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/32774">Poetry's pyproject.toml support for dependency scanning.</a> </p> </li> + <li> + <a id="notes-regarding-supported-languages-and-package-managers-6"></a> + <p> + Support for <a href="https://www.scala-sbt.org/">sbt</a> 1.3 and above was added in GitLab 13.9. + </p> + </li> </ol> <!-- markdownlint-enable MD044 --> @@ -601,7 +594,7 @@ The following variables allow configuration of global dependency scanning settin | `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | | `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Dependency Scanning Analyzers](analyzers.md). | | `DS_DEFAULT_ANALYZERS` | This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/287691) in GitLab 14.0 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/333299) in 15.0. Use `DS_EXCLUDED_ANALYZERS` instead. | -| `DS_EXCLUDED_PATHS` | Exclude files and directories from the scan based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | +| `DS_EXCLUDED_PATHS` | Exclude files and directories from the scan based on the paths. A comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | | `DS_IMAGE_SUFFIX` | Suffix added to the image name. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354796) in GitLab 14.10.) Automatically set to `"-fips"` when FIPS mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357922) in GitLab 15.0.) | | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `SECURE_LOG_LEVEL` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info`. | @@ -924,8 +917,7 @@ Please check the [Release Process documentation](https://gitlab.com/gitlab-org/s ## Contributing to the vulnerability database -You can search the [`gemnasium-db`](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project -to find a vulnerability in the GitLab Advisory Database. +To find a vulnerability, you can search the [`GitLab Advisory Database`](https://advisories.gitlab.com/). You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md). ## Running dependency scanning in an offline environment diff --git a/doc/user/application_security/get-started-security.md b/doc/user/application_security/get-started-security.md new file mode 100644 index 00000000000..4c2b971b5fa --- /dev/null +++ b/doc/user/application_security/get-started-security.md @@ -0,0 +1,34 @@ +--- +stage: DevSecOps +group: Technical writing +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 +--- + +# Get started with GitLab application security **(ULTIMATE)** + +Complete the following steps to get the most from GitLab application security tools. + +1. Enable [Secret Detection](secret_detection/index.md) scanning for your default branch. +1. Enable [Dependency Scanning](dependency_scanning/index.md) for your default branch so you can start identifying existing + vulnerable packages in your codebase. +1. Add security scans to feature branch pipelines. The same scans should be enabled as are running + on your default branch. Subsequent scans will show only new vulnerabilities by comparing the feature branch to the default branch results. +1. Let your team get comfortable with [vulnerability reports](vulnerability_report/index.md) and + establish a vulnerability triage workflow. +1. Consider creating [labels](../project/labels.md) and [issue boards](../project/issue_board.md) to + help manage issues created from vulnerabilities. Issue boards allow all stakeholders to have a + common view of all issues. +1. Create a [scan result policy](policies/index.md) to limit new vulnerabilities from being merged + into your default branch. +1. Monitor the [Security Dashboard](security_dashboard/index.md) trends to gauge success in + remediating existing vulnerabilities and preventing the introduction of new ones. +1. Enable other scan types such as [SAST](sast/index.md), [DAST](dast/index.md), + [Fuzz testing](coverage_fuzzing/index.md), or [Container Scanning](container_scanning/index.md). + Be sure to add the same scan types to both feature pipelines and default branch pipelines. +1. Use [Compliance Pipelines](../../user/project/settings/index.md#compliance-pipeline-configuration) + or [Scan Execution Policies](policies/scan-execution-policies.md) to enforce required scan types + and ensure separation of duties between security and engineering. +1. Consider enabling [Review Apps](../../development/testing_guide/review_apps.md) to allow for DAST + and [Web API fuzzing](api_fuzzing/index.md) on ephemeral test environments. +1. Enable [operational container scanning](../../user/clusters/agent/vulnerabilities.md) to scan + container images in your production cluster for security vulnerabilities. diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 35968a6361f..16f08de738b 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -64,7 +64,7 @@ variables: SAST_IMAGE_SUFFIX: '-fips' include: - - template: Security/SAST-IaC.latest.gitlab-ci.yml + - template: Jobs/SAST-IaC.gitlab-ci.yml ``` ### Making IaC analyzers available to all GitLab tiers @@ -98,11 +98,11 @@ To configure IaC Scanning for a project you can: ### Configure IaC Scanning manually To enable IaC Scanning you must [include](../../../ci/yaml/index.md#includetemplate) the -[`SAST-IaC.latest.gitlab-ci.yml template`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST-IaC.latest.gitlab-ci.yml) provided as part of your GitLab installation. Here is an example of how to include it: +[`SAST-IaC.gitlab-ci.yml template`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST-IaC.gitlab-ci.yml) provided as part of your GitLab installation. Here is an example of how to include it: ```yaml include: - - template: Security/SAST-IaC.latest.gitlab-ci.yml + - template: Jobs/SAST-IaC.gitlab-ci.yml ``` The included template creates IaC scanning jobs in your CI/CD pipeline and scans @@ -130,3 +130,24 @@ The IaC tool emits a JSON report file in the existing SAST report format. For mo The JSON report file can be downloaded from the CI pipelines page, or the pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/yaml/index.md#artifactspaths) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md). + +## Troubleshooting + +### IaC debug logging + +To help troubleshoot IaC jobs, you can increase the [Secure scanner log verbosity](../sast/index.md#logging-level) +by using a global CI/CD variable set to `debug`: + +```yaml +variables: + SECURE_LOG_LEVEL: "debug" +``` + +### IaC Scanning findings show as `No longer detected` unexpectedly + +If a previously detected finding unexpectedly shows as `No longer detected`, it might +be due to an update to the scanner. An update can disable rules that are found to +be ineffective or false positives, and the findings are marked as `No longer detected`: + +- In GitLab 15.3, [secret detection in the KICS SAST IaC scanner was disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/346181), + so IaC findings in the "Passwords and Secrets" family show as `No longer detected`. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index e3a419ea771..7c7d5380a24 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -149,19 +149,8 @@ base address for Docker images. You can override this for most scanners by setti The [Container Scanning](container_scanning/index.md) analyzer is an exception, and it does not use the `SECURE_ANALYZERS_PREFIX` variable. To override its Docker image, see -the instructions for [Running container scanning in an offline -environment](container_scanning/index.md#running-container-scanning-in-an-offline-environment). - -### Use security scanning tools with merge request pipelines - -By default, the application security jobs are configured to run for branch pipelines only. -To use them with [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md), -you may need to override the default `rules:` configuration to add: - -```yaml -rules: - - if: $CI_PIPELINE_SOURCE == "merge_request_event" -``` +the instructions for +[Running container scanning in an offline environment](container_scanning/index.md#running-container-scanning-in-an-offline-environment). ## Default behavior of GitLab security scanning tools @@ -401,8 +390,10 @@ Validation depends on the schema version declared in the security report artifac - If your security report specifies a supported schema version, GitLab uses this version to validate. - If your security report uses a deprecated version, GitLab attempts validation against that version and adds a deprecation warning to the validation result. -- If your security report uses a version that is not supported, GitLab attempts to validate it against the latest schema version available in GitLab. -- If your security report does not specify a schema version, GitLab attempts to validate it against the lastest schema version available in GitLab. Since the `version` property is required, validation always fails in this case, but other validation errors may also be present. +- If your security report uses a supported MAJOR-MINOR version of the report schema but the PATCH version doesn't match any vendored versions, GitLab attempts to validate it against latest vendored PATCH version of the schema. + - Example: security report uses version 14.1.1 but the latest vendored version is 14.1.0. GitLab would validate against schema version 14.1.0. +- If your security report uses a version that is not supported, GitLab attempts to validate it against the latest schema version available in your installation but doesn't ingest the report. +- If your security report does not specify a schema version, GitLab attempts to validate it against the latest schema version available in GitLab. Because the `version` property is required, validation always fails in this case, but other validation errors may also be present. You can always find supported and deprecated schema versions in the [source code](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/parsers/security/validators/schema_validator.rb). diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 81a9cef885d..53f9c400259 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -137,3 +137,13 @@ See [Scan result policies](scan-result-policies.md). See the [Category Direction page](https://about.gitlab.com/direction/protect/security_orchestration/) for more information on the product direction of security policies within GitLab. + +## Troubleshooting + +### `Branch name does not follow the pattern 'update-policy-<timestamp>'` + +When you create a new security policy or change an existing policy, a new branch is automatically created with the branch name following the pattern `update-policy-<timestamp>`. For example: `update-policy-1659094451`. + +If you have group or instance push rules that do not allow branch name patterns that contain the text `update-policy-<timestamp>`, you will get an error that states `Branch name does not follow the pattern 'update-policy-<timestamp>'`. + +The workaround is to amend your group or instance push rules to allow branches following the pattern `update-policy-` followed by an integer timestamp. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 0f9e3343072..cbd64e278c8 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -47,7 +47,7 @@ For an analyzer to be considered Generally Available, it is expected to minimall support the following features: - [Customizable configuration](index.md#available-cicd-variables) -- [Customizable rulesets](index.md#customize-rulesets) +- [Customizable rulesets](customize_rulesets.md#customize-rulesets) - [Scan projects](index.md#supported-languages-and-frameworks) - [Multi-project support](index.md#multi-project-support) - [Offline support](index.md#running-sast-in-an-offline-environment) diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md new file mode 100644 index 00000000000..919a3565d88 --- /dev/null +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -0,0 +1,381 @@ +--- +stage: Secure +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 +--- + +# Customize rulesets **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for +> passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. + +You can customize the default scanning rules provided by our SAST analyzers. +Ruleset customization supports the following that can be used +simultaneously: + +- [Disabling predefined rules](#disable-predefined-analyzer-rules). Available for all analyzers. +- [Overriding predefined rules](#override-predefined-analyzer-rules). Available for all analyzers. +- Modifying the default behavior of a given analyzer by [synthesizing and passing a custom configuration](#synthesize-a-custom-configuration). Available for only `nodejs-scan`, `gosec`, and `semgrep`. + +To customize the default scanning rules, create a file containing custom rules. These rules +are passed through to the analyzer's underlying scanner tools. + +To create a custom ruleset: + +1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist. +1. Create a custom ruleset file named `sast-ruleset.toml` in the `.gitlab` directory. + +## Disable predefined analyzer rules + +To disable analyzer rules: + +1. Set the `disabled` flag to `true` in the context of a `ruleset` section + +1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has: + +- a `type` field, to name the predefined rule identifier that the targeted analyzer uses. +- a `value` field, to name the rule to be disabled. + +### Example: Disable predefined rules of SAST analyzers + +In the following example, the disabled rules are assigned to `eslint` +and `sobelow` by matching the `type` and `value` of identifiers: + +```toml +[eslint] + [[eslint.ruleset]] + disable = true + [eslint.ruleset.identifier] + type = "eslint_rule_id" + value = "security/detect-object-injection" + + [[eslint.ruleset]] + disable = true + [eslint.ruleset.identifier] + type = "cwe" + value = "185" + +[sobelow] + [[sobelow.ruleset]] + disable = true + [sobelow.ruleset.identifier] + type = "sobelow_rule_id" + value = "sql_injection" +``` + +Those vulnerabilities containing the provided type and value are now disabled, meaning +they won't be displayed in Merge Request nor the Vulnerability Report. + +## Override predefined analyzer rules + +To override analyzer rules: + +1. In one or more `ruleset.identifier` subsections, list the rules that you want to override. Every `ruleset.identifier` section has: + + - a `type` field, to name the predefined rule identifier that the targeted analyzer uses. + - a `value` field, to name the rule to be overridden. + +1. In the `ruleset.override` context of a `ruleset` section, + provide the keys to override. Any combination of keys can be + overridden. Valid keys are: + + - description + - message + - name + - severity (valid options are: Critical, High, Medium, Low, Unknown, Info) + +### Example: Override predefined rules of SAST analyzers + +Before adding a ruleset, we verify which vulnerability will be overwritten by viewing the [`gl-sast-report.json`](index.md#reports-json-format): + +```json +"identifiers": [ + { + "type": "gosec_rule_id", + "name": "Gosec Rule ID G307", + "value": "G307" + }, + { + "type": "CWE", + "name": "CWE-703", + "value": "703", + "url": "https://cwe.mitre.org/data/definitions/703.html" + } + ] +``` + +In the following example, rules from `gosec` are matched by the `type` +and `value` of identifiers and then overridden: + +```toml +[gosec] + [[gosec.ruleset]] + [gosec.ruleset.identifier] + type = "CWE" + value = "703" + [gosec.ruleset.override] + severity = "Critical" +``` + +If a vulnerability is found with a type `CWE` with a value of `703` then +the vulnerability severity is overwritten to `Critical`. + +## Synthesize a custom configuration + +To create a custom configuration, you can use passthrough chains. + +A passthrough is a single step in a passthrough chain. The passthrough is evaluated +in a sequence to incrementally build a configuration. The configuration is then +passed to the target analyzer. + +A configuration section for an analyzer has the following +parameters: + +| Parameter | Explanation | +| ------------- | ------ | +| `description` | Description about the analyzer configuration section. | +| `targetdir` | The `targetdir` parameter defines the directory where the final configuration is located. If `targetdir` is empty, the analyzer uses a random directory. The maximum size of `targetdir` is 100MB. | +| `validate` | If set to `true`, the target files for passthroughs (`raw`, `file` and `url`) are validated. The validation works for `yaml`, `xml`, `json` and `toml` files. The proper validator is identified based on the extension of the target file. By default, `validate` is set to `false`. | +| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. | +| `timeout` | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. | + +A configuration section can include one or more passthrough sections. The maximum number of passthrough sections is 20. +There are several types of passthroughs: + +| Type | Description | +| ------ | ------ | +| `file` | Use a file that is already available in the Git repository. | +| `raw` | Provide the configuration inline. | +| `git` | Pull the configuration from a remote Git repository. | +| `url` | Fetch the analyzer configuration through HTTP. | + +If multiple passthrough sections are defined in a passthrough chain, their +position in the chain defines the order in which they are evaluated. + +- Passthroughs listed later in the chain sequence have a higher precedence. +- Passthroughs with a higher precedence overwrite (default) and append data + yielded by previous passthroughs. This is useful for cases where you need to + use or modify an existing configuration. + +Configure a passthrough these parameters: + +| Parameter | Explanation | +| ------------ | ----------- | +| `type` | One of `file`, `raw`, `git` or `url`. | +| `target` | The target file that contains the data written by the passthrough evaluation. If no value is provided, a random target file is generated. | +| `mode` | `overwrite`: if `target` exists, overwrites the file; `append`: append to file instead. The default is `overwrite`. | +| `ref` | This option only applies to the `git` passthrough type and contains the name of the branch or the SHA to be used. | +| `subdir` | This option only applies to the `git` passthrough type and can be used to only consider a certain subdirectory of the source Git repository. | +| `value` | For the `file` `url` and `git` types, `value` defines the source location of the file/Git repository; for the `raw` type, `value` carries the raw content to be passed through. | +| `validator` | Can be used to explicitly invoke validators (`xml`, `yaml`, `json`, `toml`) on the target files after the application of a passthrough. Per default, no validator is set. | + +The amount of data generated by a single passthrough is limited to 1MB. + +## Passthrough configuration examples + +### Raw passthrough for nodejs-scan + +Define a custom analyzer configuration. In this example, customized rules are +defined for the `nodejs-scan` scanner: + +```toml +[nodejs-scan] + description = 'custom ruleset for nodejs-scan' + + [[nodejs-scan.passthrough]] + type = "raw" + value = ''' +- nodejs-extensions: + - .js + + template-extensions: + - .new + - .hbs + - '' + + ignore-filenames: +- skip.js + + ignore-paths: + - __MACOSX + - skip_dir + - node_modules + + ignore-extensions: + - .hbs + + ignore-rules: + - regex_injection_dos + - pug_jade_template + - express_xss + +''' +``` + +### File passthrough for Gosec + +Provide the name of the file containing a custom analyzer configuration. In +this example, customized rules for the `gosec` scanner are contained in the +file `gosec-config.json`: + +```toml +[gosec] + description = 'custom ruleset for gosec' + + [[gosec.passthrough]] + type = "file" + value = "gosec-config.json" +``` + +### Passthrough chain for Semgrep + +In the below example, we generate a custom configuration under the `/sgrules` +target directory with a total `timeout` of 60 seconds. + +Several passthrouh types generate a configuration for the target analyzer: + +- Two `git` passthrough sections pull the head of branch + `refs/remotes/origin/test` from the `myrules` Git repository, and revision + `97f7686` from the `sast-rules` Git repository. From the `sast-rules` Git + repository, only data from the `go` subdirectory is considered. + - The `sast-rules` entry has a higher precedence because it appears later in + the configuration. + - If there is a filename collision between files in both repositories, files + from the `sast` repository overwrite files from the `myrules` repository, + as `sast-rules` has higher precedence. +- The `raw` entry creates a file named `insecure.yml` under `/sgrules`. The + full path is `/sgrules/insecure.yml`. +- The `url` entry fetches a configuration made available through a URL and + stores it in the `/sgrules/gosec.yml` file. + +Afterwards, Semgrep is invoked with the final configuration located under +`/sgrules`. + +```toml +[semgrep] + description = 'semgrep custom rules configuration' + targetdir = "/sgrules" + timeout = 60 + + [[semgrep.passthrough]] + type = "git" + value = "https://gitlab.com/user/myrules.git" + ref = "refs/remotes/origin/test" + + [[semgrep.passthrough]] + type = "git" + value = "https://gitlab.com/gitlab-org/secure/gsoc-sast-vulnerability-rules/playground/sast-rules.git" + ref = "97f7686db058e2141c0806a477c1e04835c4f395" + subdir = "go" + + [[semgrep.passthrough]] + type = "raw" + target = "insecure.yml" + value = """ +rules: +- id: "insecure" + patterns: + - pattern: "func insecure() {...}" + message: | + Insecure function insecure detected + metadata: + cwe: "CWE-200: Exposure of Sensitive Information to an Unauthorized Actor" + severity: "ERROR" + languages: + - "go" + """ + + [[semgrep.passthrough]] + type = "url" + value = "https://semgrep.dev/c/p/gosec" + target = "gosec.yml" +``` + +### Interpolation + +The code snippet below shows an example configuration that uses an environment +variable `$GITURL` to access a private repositories with a Git URL. The variable contains +a username and token in the `value` field (for example `https://user:token@url`). +It does not explicitly store credentials in the configuration file. To reduce the risk of leaking secrets through created paths and files, use this feature with caution. + +```toml +[semgrep] + description = 'semgrep custom rules configuration' + targetdir = "/sgrules" + interpolate = true + + [[semgrep.passthrough]] + type = "git" + value = "$GITURL" + ref = "refs/remotes/origin/main" +``` + +### Configure the append mode for passthroughs + +To append data to previous passthroughs, use the `append` mode for the +passthrough types `file`, `url`, and `raw`. + +Passthroughs in `override` mode overwrite files +created when preceding passthroughs in the chain find a naming +collision. If `mode` is set to `append`, a passthrough appends data to the +files created by its predecessors instead of overwriting. + +In the below Semgrep configuration,`/sgrules/insecure.yml` assembles two passthroughs. The rules are: + +- `insecure` +- `secret` + +These rules add a search pattern to the analyzer and extends Semgrep capabilities. + +For passthrough chains we recommend that you enable validation. To enable validation, +you can either: + +- set `validate` to `true` + +- set a passthrough `validator` to `xml`, `json`, `yaml`, or `toml`. + +```toml +[semgrep] + description = 'semgrep custom rules configuration' + targetdir = "/sgrules" + validate = true + + [[semgrep.passthrough]] + type = "raw" + target = "insecure.yml" + value = """ +rules: +- id: "insecure" + patterns: + - pattern: "func insecure() {...}" + message: | + Insecure function insecure detected + metadata: + cwe: "... + severity: "ERROR" + languages: + - "go" +""" + + [[semgrep.passthrough]] + type = "raw" + mode = "append" + target = "insecure.yml" + value = """ +- id: "secret" + patterns: + - pattern-either: + - pattern: "$MASK = \"...\"" + - metavariable-regex: + metavariable: "$MASK" + regex: "(password|pass|passwd|pwd|secret|token)" + message: | + Use of Hard-coded Password + cwe: "..." + severity: "ERROR" + languages: + - "go" +""" +``` diff --git a/doc/user/application_security/sast/img/sast_vulnerability_page_fp_detection_v15_2.png b/doc/user/application_security/sast/img/sast_vulnerability_page_fp_detection_v15_2.png Binary files differnew file mode 100644 index 00000000000..2a3e6e7e45f --- /dev/null +++ b/doc/user/application_security/sast/img/sast_vulnerability_page_fp_detection_v15_2.png diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 92dc795afe5..d4b0d5b972c 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -176,18 +176,18 @@ 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 & Premium | In Ultimate | -|:----------------------------------------------------------------|:--------------------|:-------------------| -| [Configure SAST scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize SAST settings](#available-cicd-variables) | **{check-circle}** | **{check-circle}** | -| Download [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| See new findings in merge request widget | **{dotted-circle}** | **{check-circle}** | -| [Manage vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Access the Security Dashboard](../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}** | -| [Detect False Positives](#false-positive-detection) | **{dotted-circle}** | **{check-circle}** | -| [Track moved vulnerabilities](#advanced-vulnerability-tracking) | **{dotted-circle}** | **{check-circle}** | +| Capability | In Free & Premium | In Ultimate | +|:---------------------------------------------------------------- -|:--------------------|:-------------------| +| [Configure SAST scanners](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize SAST settings](#available-cicd-variables) | **{check-circle}** | **{check-circle}** | +| Download [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | +| See new findings in merge request widget | **{dotted-circle}** | **{check-circle}** | +| [Manage vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Access the Security Dashboard](../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.md) | **{dotted-circle}** | **{check-circle}** | +| [Detect False Positives](#false-positive-detection) | **{dotted-circle}** | **{check-circle}** | +| [Track moved vulnerabilities](#advanced-vulnerability-tracking) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -320,382 +320,6 @@ brakeman-sast: SAST_ANALYZER_IMAGE_TAG: "2.21.1" ``` -### Customize rulesets **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for -> passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. - -You can customize the default scanning rules provided by our SAST analyzers. -Ruleset customization supports the following that can be used -simultaneously: - -- [Disabling predefined rules](index.md#disable-predefined-analyzer-rules). Available for all analyzers. -- [Overriding predefined rules](index.md#override-predefined-analyzer-rules). Available for all analyzers. -- Modifying the default behavior of a given analyzer by [synthesizing and passing a custom configuration](index.md#synthesize-a-custom-configuration). Available for only `nodejs-scan`, `gosec`, and `semgrep`. - -To customize the default scanning rules, create a file containing custom rules. These rules -are passed through to the analyzer's underlying scanner tools. - -To create a custom ruleset: - -1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist. -1. Create a custom ruleset file named `sast-ruleset.toml` in the `.gitlab` directory. - -#### Disable predefined analyzer rules - -To disable analyzer rules: - -1. Set the `disabled` flag to `true` in the context of a `ruleset` section - -1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has: - -- a `type` field, to name the predefined rule identifier that the targeted analyzer uses. -- a `value` field, to name the rule to be disabled. - -##### Example: Disable predefined rules of SAST analyzers - -In the following example, the disabled rules are assigned to `eslint` -and `sobelow` by matching the `type` and `value` of identifiers: - -```toml -[eslint] - [[eslint.ruleset]] - disable = true - [eslint.ruleset.identifier] - type = "eslint_rule_id" - value = "security/detect-object-injection" - - [[eslint.ruleset]] - disable = true - [eslint.ruleset.identifier] - type = "cwe" - value = "185" - -[sobelow] - [[sobelow.ruleset]] - disable = true - [sobelow.ruleset.identifier] - type = "sobelow_rule_id" - value = "sql_injection" -``` - -Those vulnerabilities containing the provided type and value are now disabled, meaning -they won't be displayed in Merge Request nor the Vulnerability Report. - -#### Override predefined analyzer rules - -To override analyzer rules: - -1. In one or more `ruleset.identifier` subsections, list the rules that you want to override. Every `ruleset.identifier` section has: - - - a `type` field, to name the predefined rule identifier that the targeted analyzer uses. - - a `value` field, to name the rule to be overridden. - -1. In the `ruleset.override` context of a `ruleset` section, - provide the keys to override. Any combination of keys can be - overridden. Valid keys are: - - - description - - message - - name - - severity (valid options are: Critical, High, Medium, Low, Unknown, Info) - -##### Example: Override predefined rules of SAST analyzers - -Before adding a ruleset, we verify which vulnerability will be overwritten by viewing the [`gl-sast-report.json`](#reports-json-format): - -```json -"identifiers": [ - { - "type": "gosec_rule_id", - "name": "Gosec Rule ID G307", - "value": "G307" - }, - { - "type": "CWE", - "name": "CWE-703", - "value": "703", - "url": "https://cwe.mitre.org/data/definitions/703.html" - } - ] -``` - -In the following example, rules from `gosec` are matched by the `type` -and `value` of identifiers and then overridden: - -```toml -[gosec] - [[gosec.ruleset]] - [gosec.ruleset.identifier] - type = "CWE" - value = "703" - [gosec.ruleset.override] - severity = "Critical" -``` - -If a vulnerability is found with a type `CWE` with a value of `703` then -the vulnerability severity is overwritten to `Critical`. - -#### Synthesize a custom configuration - -To create a custom configuration, you can use passthrough chains. - -A passthrough is a single step in a passthrough chain. The passthrough is evaluated -in a sequence to incrementally build a configuration. The configuration is then -passed to the target analyzer. - -A configuration section for an analyzer has the following -parameters: - -| Parameter | Explanation | -| ------------- | ------ | -| `description` | Description about the analyzer configuration section. | -| `targetdir` | The `targetdir` parameter defines the directory where the final configuration is located. If `targetdir` is empty, the analyzer uses a random directory. The maximum size of `targetdir` is 100MB. | -| `validate` | If set to `true`, the target files for passthroughs (`raw`, `file` and `url`) are validated. The validation works for `yaml`, `xml`, `json` and `toml` files. The proper validator is identified based on the extension of the target file. By default, `validate` is set to `false`. | -| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. | -| `timeout` | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. | - -A configuration section can include one or more passthrough sections. The maximum number of passthrough sections is 20. -There are several types of passthroughs: - -| Type | Description | -| ------ | ------ | -| `file` | Use a file that is already available in the Git repository. | -| `raw` | Provide the configuration inline. | -| `git` | Pull the configuration from a remote Git repository. | -| `url` | Fetch the analyzer configuration through HTTP. | - -If multiple passthrough sections are defined in a passthrough chain, their -position in the chain defines the order in which they are evaluated. - -- Passthroughs listed later in the chain sequence have a higher precedence. -- Passthroughs with a higher precedence overwrite (default) and append data - yielded by previous passthroughs. This is useful for cases where you need to - use or modify an existing configuration. - -Configure a passthrough these parameters: - -| Parameter | Explanation | -| ------------ | ----------- | -| `type` | One of `file`, `raw`, `git` or `url`. | -| `target` | The target file that contains the data written by the passthrough evaluation. If no value is provided, a random target file is generated. | -| `mode` | `overwrite`: if `target` exists, overwrites the file; `append`: append to file instead. The default is `overwrite`. | -| `ref` | This option only applies to the `git` passthrough type and contains the name of the branch or the SHA to be used. | -| `subdir` | This option only applies to the `git` passthrough type and can be used to only consider a certain subdirectory of the source Git repository. | -| `value` | For the `file` `url` and `git` types, `value` defines the source location of the file/Git repository; for the `raw` type, `value` carries the raw content to be passed through. | -| `validator` | Can be used to explicitly invoke validators (`xml`, `yaml`, `json`, `toml`) on the target files after the application of a passthrough. Per default, no validator is set. | - -The amount of data generated by a single passthrough is limited to 1MB. - -#### Passthrough configuration examples - -##### Raw passthrough for nodejs-scan - -Define a custom analyzer configuration. In this example, customized rules are -defined for the `nodejs-scan` scanner: - -```toml -[nodejs-scan] - description = 'custom ruleset for nodejs-scan' - - [[nodejs-scan.passthrough]] - type = "raw" - value = ''' -- nodejs-extensions: - - .js - - template-extensions: - - .new - - .hbs - - '' - - ignore-filenames: -- skip.js - - ignore-paths: - - __MACOSX - - skip_dir - - node_modules - - ignore-extensions: - - .hbs - - ignore-rules: - - regex_injection_dos - - pug_jade_template - - express_xss - -''' -``` - -##### File passthrough for Gosec - -Provide the name of the file containing a custom analyzer configuration. In -this example, customized rules for the `gosec` scanner are contained in the -file `gosec-config.json`: - -```toml -[gosec] - description = 'custom ruleset for gosec' - - [[gosec.passthrough]] - type = "file" - value = "gosec-config.json" -``` - -##### Passthrough chain for Semgrep - -In the below example, we generate a custom configuration under the `/sgrules` -target directory with a total `timeout` of 60 seconds. - -Several passthrouh types generate a configuration for the target analyzer: - -- Two `git` passthrough sections pull the head of branch - `refs/remotes/origin/test` from the `myrules` Git repository, and revision - `97f7686` from the `sast-rules` Git repository. From the `sast-rules` Git - repository, only data from the `go` subdirectory is considered. - - The `sast-rules` entry has a higher precedence because it appears later in - the configuration. - - If there is a filename collision between files in both repositories, files - from the `sast` repository overwrite files from the `myrules` repository, - as `sast-rules` has higher precedence. -- The `raw` entry creates a file named `insecure.yml` under `/sgrules`. The - full path is `/sgrules/insecure.yml`. -- The `url` entry fetches a configuration made available through a URL and - stores it in the `/sgrules/gosec.yml` file. - -Afterwards, Semgrep is invoked with the final configuration located under -`/sgrules`. - -```toml -[semgrep] - description = 'semgrep custom rules configuration' - targetdir = "/sgrules" - timeout = 60 - - [[semgrep.passthrough]] - type = "git" - value = "https://gitlab.com/user/myrules.git" - ref = "refs/remotes/origin/test" - - [[semgrep.passthrough]] - type = "git" - value = "https://gitlab.com/gitlab-org/secure/gsoc-sast-vulnerability-rules/playground/sast-rules.git" - ref = "97f7686db058e2141c0806a477c1e04835c4f395" - subdir = "go" - - [[semgrep.passthrough]] - type = "raw" - target = "insecure.yml" - value = """ -rules: -- id: "insecure" - patterns: - - pattern: "func insecure() {...}" - message: | - Insecure function insecure detected - metadata: - cwe: "CWE-200: Exposure of Sensitive Information to an Unauthorized Actor" - severity: "ERROR" - languages: - - "go" - """ - - [[semgrep.passthrough]] - type = "url" - value = "https://semgrep.dev/c/p/gosec" - target = "gosec.yml" -``` - -##### Interpolation - -The code snippet below shows an example configuration that uses an environment -variable `$GITURL` to access a private repositories with a Git URL. The variable contains -a username and token in the `value` field (for example `https://user:token@url`). -It does not explicitly store credentials in the configuration file. To reduce the risk of leaking secrets through created paths and files, use this feature with caution. - -```toml -[semgrep] - description = 'semgrep custom rules configuration' - targetdir = "/sgrules" - interpolate = true - - [[semgrep.passthrough]] - type = "git" - value = "$GITURL" - ref = "refs/remotes/origin/main" -``` - -##### Configure the append mode for passthroughs - -To append data to previous passthroughs, use the `append` mode for the -passthrough types `file`, `url`, and `raw`. - -Passthroughs in `override` mode overwrite files -created when preceding passthroughs in the chain find a naming -collision. If `mode` is set to `append`, a passthrough appends data to the -files created by its predecessors instead of overwriting. - -In the below Semgrep configuration,`/sgrules/insecure.yml` assembles two passthroughs. The rules are: - -- `insecure` -- `secret` - -These rules add a search pattern to the analyzer and extends Semgrep capabilities. - -For passthrough chains we recommend that you enable validation. To enable validation, -you can either: - -- set `validate` to `true` - -- set a passthrough `validator` to `xml`, `json`, `yaml`, or `toml`. - -```toml -[semgrep] - description = 'semgrep custom rules configuration' - targetdir = "/sgrules" - validate = true - - [[semgrep.passthrough]] - type = "raw" - target = "insecure.yml" - value = """ -rules: -- id: "insecure" - patterns: - - pattern: "func insecure() {...}" - message: | - Insecure function insecure detected - metadata: - cwe: "... - severity: "ERROR" - languages: - - "go" -""" - - [[semgrep.passthrough]] - type = "raw" - mode = "append" - target = "insecure.yml" - value = """ -- id: "secret" - patterns: - - pattern-either: - - pattern: "$MASK = \"...\"" - - metavariable-regex: - metavariable: "$MASK" - regex: "(password|pass|passwd|pwd|secret|token)" - message: | - Use of Hard-coded Password - cwe: "..." - severity: "ERROR" - languages: - - "go" -""" -``` - ### False Positive Detection **(ULTIMATE)** > Introduced in GitLab 14.2. @@ -706,6 +330,8 @@ False positive detection is available in a subset of the [supported languages](# - Ruby, in the Brakeman-based analyzer + + ### Advanced vulnerability tracking **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5144) in GitLab 14.2. @@ -829,7 +455,7 @@ spotbugs-sast: dependencies: - build variables: - MAVEN_REPO_PATH: ./.m2/repository + MAVEN_REPO_PATH: $CI_PROJECT_DIR/.m2/repository COMPILE: "false" artifacts: reports: @@ -907,7 +533,7 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | CI/CD variable | Default value | Description | |------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. To exclude paths, copy and paste the default excluded paths, then **add** your own paths to be excluded. If you don't specify the default excluded paths, you will override the defaults and _only_ paths you specify will be excluded from the SAST scans. | +| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. To exclude paths, copy and paste the default excluded paths, then **add** your own paths to be excluded. If you don't specify the default excluded paths, you will override the defaults and _only_ paths you specify will be excluded from the SAST scans. | | `SEARCH_MAX_DEPTH` | 4 | SAST searches the repository to detect the programming languages used, and selects the matching analyzers. Set the value of `SEARCH_MAX_DEPTH` to specify how many directory levels the search phase should span. After the analyzers have been selected, the _entire_ repository is analyzed. | | `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | | `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | @@ -963,6 +589,8 @@ removed, or promoted to regular features at any time. Experimental features available are: - Enable scanning of iOS and Android apps using the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). +- Disable the following rules in the [Semgrep analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) that are known to cause a high rate of false positives: + - [`eslint.detect-object-injection`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/6c4764567d9854f5e4a4a35dacf5a68def7fb4c1/rules/eslint.yml#L751-773) #### Enable experimental features diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 02d50b0a857..93c32f998fa 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -200,7 +200,7 @@ Secret Detection can be customized by defining available CI/CD variables: | CI/CD variable | Default value | Description | |-----------------------------------|---------------|-------------| -| `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | +| `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | | `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | | `SECRET_DETECTION_IMAGE_SUFFIX` | "" | Suffix added to the image name. If set to `-fips`, `FIPS-enabled` images are used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355519) in GitLab 14.10. | | `SECRET_DETECTION_LOG_OPTIONS` | "" | [`git log`](https://git-scm.com/docs/git-log) options used to define commit ranges. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350660) in GitLab 15.1.| @@ -224,9 +224,9 @@ You can customize the default secret detection rules provided with GitLab. Ruleset customization supports the following capabilities that can be used simultaneously: -- [Disabling predefined rules](index.md#disable-predefined-analyzer-rules). -- [Overriding predefined rules](index.md#override-predefined-analyzer-rules). -- Modifying the default behavior of the Secret Detection analyzer by [synthesizing and passing a custom configuration](index.md#synthesize-a-custom-configuration). +- [Disabling predefined rules](#disable-predefined-analyzer-rules). +- [Overriding predefined rules](#override-predefined-analyzer-rules). +- Modifying the default behavior of the Secret Detection analyzer by [synthesizing and passing a custom configuration](#synthesize-a-custom-configuration). Customization allows replacing the default secret detection rules with rules that you define. @@ -334,7 +334,7 @@ To create a custom configuration, you can use passthrough chains. ``` Passthroughs can also be chained to build more complex configurations. -For more details, see [SAST Customize ruleset section](../sast/index.md#customize-rulesets). +For more details, see [SAST Customize ruleset section](../sast/customize_rulesets.md). ### Logging level diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index f0ac01000ef..ad397c3fe04 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -152,8 +152,8 @@ includes a **Resolve with merge request** option. The following scanners are supported by this feature: - [Dependency Scanning](../dependency_scanning/index.md). - Automatic Patch creation is only available for Node.js projects managed with - `yarn` when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is disabled. + Automatic patch creation is only available for Node.js projects managed with + `yarn`. Also, Automatic patch creation is only supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is disabled. - [Container Scanning](../container_scanning/index.md). To resolve a vulnerability, you can either: diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index 14c13f74a5e..32916f4c9c7 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -60,14 +60,14 @@ To download a security scan output: ## Scan results This shows a list of the combined results for all security report artifacts. The filters work like the -[Vulnerability Report filters](index.md#vulnerability-report-filters), but they are limited to **Severity** and **Tool**, with +[Vulnerability Report filters](index.md#vulnerability-report-filters), but they are limited to **Severity** and **Tool**, with the addition of a **Hide dismissed** toggle. -When you review the vulnerability findings reported in the pipeline, you can select one or more entries for dismissal, +When you review the vulnerability findings reported in the pipeline, you can select one or more entries for dismissal, similar to [Dismissing a vulnerability](index.md#dismissing-a-vulnerability) in the Vulnerability Report. When you merge the branch corresponding to the pipeline into the default branch, all reported findings are combined into -the [Vulnerability Report](index.md). Scan results in pipelines executed on the default branch are +the [Vulnerability Report](index.md). Scan results in pipelines executed on the default branch are incorporated once the pipeline finishes. | Existing vulnerability status | Dismissed in pipeline? | New vulnerability status | diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index b55a55eebe5..8de777672ff 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -477,8 +477,8 @@ digraph G { #### PlantUML -To make PlantUML available in GitLab, a GitLab administrator needs to enable it first. -Read more in [PlantUML & GitLab](../administration/integration/plantuml.md). +PlantUML integration is enabled on GitLab.com. To make PlantUML available in self-managed +installation of GitLab, a GitLab administrator [must enable it](../administration/integration/plantuml.md). After PlantUML is enabled, enter your text in a `plantuml` block: diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index dce02a72300..16b92eb92a3 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -25,7 +25,7 @@ To ensure access to your cluster is safe: - Each agent has a separate context (`kubecontext`). - Only the project where the agent is configured, and any additional projects you authorize, can access the agent in your cluster. -You do not need to have a runner in the cluster with the agent. +The CI/CD workflow requires runners to be registered with GitLab, but these runners do not have to be in the cluster where the agent is. ## GitLab CI/CD workflow steps @@ -127,8 +127,8 @@ Run `kubectl config get-contexts`. ### Environments with both certificate-based and agent-based connections -When you deploy to an environment that has both a [certificate-based -cluster](../../infrastructure/clusters/index.md) (deprecated) and an agent connection: +When you deploy to an environment that has both a +[certificate-based cluster](../../infrastructure/clusters/index.md) (deprecated) and an agent connection: - The certificate-based cluster's context is called `gitlab-deploy`. This context is always selected by default. diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index 73a35ffbc64..4978b56917b 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -4,10 +4,11 @@ group: Configure 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 --- -# Using GitOps with a Kubernetes cluster **(PREMIUM)** +# Using GitOps with a Kubernetes cluster **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/346567) from GitLab Premium to GitLab Free in 15.3. With GitOps, you can manage containerized clusters and applications from a Git repository that: diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 9282ac7fb40..4b0d8b77493 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -17,7 +17,7 @@ To connect a Kubernetes cluster to GitLab, you must install an agent in your clu Before you can install the agent in your cluster, you need: - An existing Kubernetes cluster. If you don't have a cluster, you can create one on a cloud provider, like: - - [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine/docs/quickstart) + - [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine/docs/deploy-app-cluster) - [Amazon Elastic Kubernetes Service (EKS)](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html) - [Digital Ocean](https://docs.digitalocean.com/products/kubernetes/quickstart/) - On self-managed GitLab instances, a GitLab administrator must set up the diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index 3b80a7a0f81..5afe3ccec2b 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -16,6 +16,9 @@ You can also configure your agent so the vulnerabilities are displayed with othe You can use operational container scanning to scan container images in your cluster for security vulnerabilities. +NOTE: +In GitLab 15.0 and later, you do not need to install Starboard operator in the Kubernetes cluster. + To begin scanning all resources in your cluster, add a `starboard` configuration block to your agent configuration with a `cadence` field containing a CRON expression for when the scans will be run. diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index 47dc9c42797..3dcec32b90c 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -61,7 +61,7 @@ this dashboard. You can customize the cost dashboard by editing the `.gitlab/dashboards/default_costs.yml` file or creating similar dashboard configuration files. To learn more, read about -[customizing dashboards in our documentation](/ee/operations/metrics/dashboards/). +[customizing dashboards in our documentation](../../operations/metrics/dashboards/index.md). #### Available metrics diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index b7732a7abf8..cf71729b517 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -33,8 +33,8 @@ With cluster environments, you can gain insight into:  -Access to cluster environments is restricted to [group maintainers and -owners](../permissions.md#group-members-permissions) +Access to cluster environments is restricted to +[group maintainers and owners](../permissions.md#group-members-permissions) ## Usage diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index d59edb1e2c2..361276194b0 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -81,8 +81,7 @@ configure cluster: ### Setting the environment scope -[Environment -scopes](../project/clusters/multiple_kubernetes_clusters.md#setting-the-environment-scope) +[Environment scopes](../project/clusters/multiple_kubernetes_clusters.md#setting-the-environment-scope) are usable when associating multiple clusters to the same management project. diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 7ab77c67bcc..4b00784a7ae 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -15,6 +15,9 @@ to create a project. The project includes cluster applications that integrate wi and extend GitLab functionality. You can use the pattern shown in the project to extend your custom cluster applications. +NOTE: +The project template works on GitLab.com without modifications. If you're on a self-managed instance, you must modify the `.gitlab-ci.yml` file. + ## Use one project for the agent and your manifests If you **have not yet** used the agent to connect your cluster with GitLab: @@ -47,10 +50,7 @@ To create a project from the cluster management project template: 1. From the list of templates, next to **GitLab Cluster Management**, select **Use template**. 1. Enter the project details. 1. Select **Create project**. - -If you use self-managed GitLab, your instance might not include the latest version of the template. -In that case, select **Import project**, **Repository by URL** and for the **Git repository URL**, enter -`https://gitlab.com/gitlab-org/project-templates/cluster-management.git`. +1. In the new project, [configure the files](#configure-the-project) as needed. ## Configure the project @@ -73,6 +73,11 @@ The base image used in the pipeline is built by the [cluster-applications](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications) project. This image contains a set of Bash utility scripts to support [Helm v3 releases](https://helm.sh/docs/intro/using_helm/#three-big-concepts). +If you are on a self-managed instance of GitLab, you must modify the `.gitlab-ci.yml` file. +Specifically, the section that starts with the comment `Automatic package upgrades` will not +work on a self-managed instance, because the `include` refers to a GitLab.com project. +If you remove everything below this comment, the pipeline will succeed. + ### The main `helmfile.yml` file The template contains a [Helmfile](https://github.com/roboll/helmfile) you can use to manage diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index f547e5f146f..4cd2705e917 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -92,30 +92,49 @@ Our criteria for the separation of duties is as follows: ## Chain of Custody report -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in GitLab 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in GitLab 13.3. +> - Chain of Custody reports sent using email [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342594) in GitLab 15.3 with a flag named `async_chain_of_custody_report`. Disabled by default. + +FLAG: +On self-managed GitLab, by default sending Chain of Custody reports through email is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `async_chain_of_custody_report`. On GitLab.com, this feature is not available. The Chain of Custody report allows customers to export a list of merge commits within the group. The data provides a comprehensive view with respect to merge commits. It includes the merge commit SHA, merge request author, merge request ID, merge user, date merged, pipeline ID, group name, project name, and merge request approvers. Depending on the merge strategy, the merge commit SHA can be a merge commit, squash commit, or a diff head commit. -To download the Chain of Custody report: +To generate the Chain of Custody report: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Security & Compliance > Compliance report**. 1. Select **List of all merge commits**. -### Commit-specific Chain of Custody Report +The Chain of Custody report is either: + +- Available for download. +- Sent through email. Requires GitLab 15.3 and later with `async_chain_of_custody_report` feature flag enabled. + +### Commit-specific Chain of Custody report > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in GitLab 13.6. -You can generate a commit-specific Chain of Custody report for a given commit SHA. +Authenticated group owners can generate a commit-specific Chain of Custody report for a given commit SHA, either: -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Security & Compliance > Compliance report**. -1. At the top of the compliance report, to the right of **List of all merge commits**, select the down arrow (**{chevron-lg-down}**). -1. Enter the merge commit SHA, and then select **Export commit custody report**. - SHA and then select **Export commit custody report**. +- Using the GitLab UI: + + 1. On the top bar, select **Menu > Groups** and find your group. + 1. On the left sidebar, select **Security & Compliance > Compliance report**. + 1. At the top of the compliance report, to the right of **List of all merge commits**, select the down arrow (**{chevron-lg-down}**). + 1. Enter the merge commit SHA, and then select **Export commit custody report**. + SHA and then select **Export commit custody report**. + +The Chain of Custody report is either: + +- Available for download. +- Sent through email. Requires GitLab 15.3 and later with `async_chain_of_custody_report` feature flag enabled. + +- Using a direct link: `https://gitlab.com/groups/<group-name>/-/security/merge_commit_reports.csv?commit_sha={optional_commit_sha}`, passing in an optional value to the + `commit_sha` query parameter. NOTE: The Chain of Custody report download is a CSV file, with a maximum size of 15 MB. diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 8c57220068b..1c9f9e85ab7 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -71,13 +71,11 @@ Gradle 1.x projects are not supported. The minimum supported version of Maven is |------------|----------------------------------------------------------------------------------------------|-------| | JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) (7 and earlier) | | | Go | [Godep](https://github.com/tools/godep) ([deprecated](../../../update/deprecations.md#godep-support-in-license-compliance)), [go mod](https://github.com/golang/go/wiki/Modules) | | -| Java | [Gradle](https://gradle.org/) <sup>1</sup>, [Maven](https://maven.apache.org/) | | +| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | | | .NET | [NuGet](https://www.nuget.org/) | The .NET Framework is supported via the [mono project](https://www.mono-project.com/). There are, however, some limitations. The scanner doesn't support Windows-specific dependencies and doesn't report dependencies of your project's listed dependencies. Also, the scanner always marks detected licenses for all dependencies as `unknown`. | | Python | [pip](https://pip.pypa.io/en/stable/) | Python is supported through [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files) and [Pipfile.lock](https://github.com/pypa/pipfile#pipfilelock). | | Ruby | [gem](https://rubygems.org/) | | -1. Gradle 7 and later is not supported as dependencies are not discovered when included with the `implementation` directive. Please see [GitLab#341222](https://gitlab.com/gitlab-org/gitlab/-/issues/341222) for more details. - ### Experimental support The following languages and package managers are [supported experimentally](https://github.com/pivotal/LicenseFinder#experimental-project-types). @@ -468,7 +466,7 @@ package manager. For a comprehensive list, consult [the Conan documentation](htt The default [Conan](https://conan.io/) configuration sets [`CONAN_LOGIN_USERNAME`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) to `ci_user`, and binds [`CONAN_PASSWORD`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-password-conan-password-remote-name) to the [`CI_JOB_TOKEN`](../../../ci/variables/predefined_variables.md) -for the running job. This allows Conan projects to fetch packages from a [GitLab Conan Repository](../../packages/conan_repository/#fetch-conan-package-information-from-the-package-registry) +for the running job. This allows Conan projects to fetch packages from a [GitLab Conan Repository](../../packages/conan_repository/index.md#fetch-conan-package-information-from-the-package-registry) if a GitLab remote is specified in the `.conan/remotes.json` file. To override the default credentials specify a [`CONAN_LOGIN_USERNAME_{REMOTE_NAME}`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index a2cfdf61a8d..e71a983ccfd 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -169,7 +169,7 @@ You can also add, remove, or replace issue contacts using the [GraphQL](../../api/graphql/reference/index.md#mutationissuesetcrmcontacts) API. -## Autocomplete contacts **(FREE SELF)** +## Autocomplete contacts > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `contacts_autocomplete`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/352123) in GitLab 15.0. diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 1f34d182718..3fb0be6480c 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -47,7 +47,19 @@ in a different color. Avoid mentioning `@all` in issues and merge requests, because it sends an email notification to all the members of that project's group. This might be interpreted as spam. Notifications and mentions can be disabled in -[a group's settings](../group/index.md#disable-email-notifications). +[a group's settings](../group/manage.md#disable-email-notifications). + +### Mention a group in an issue or merge request + +When you mention a group in a comment, every member of the group gets a to-do item +added to their To-do list. + +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. ## Add a comment to a merge request diff @@ -347,3 +359,19 @@ with a new push. Threads are now resolved if a push makes a diff section outdated. Threads on lines that don't change and top-level resolvable threads are not resolved. + +## Display paginated merge request discussions + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340172) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `paginated_mr_discussions`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.2. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.3. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature +per project or for your entire instance, ask an administrator to +[disable the feature flag](../../administration/feature_flags.md) named `paginated_mr_discussions`. +On GitLab.com, this feature is available. + +A merge request can have many discussions. Loading them all in a single request +can be slow. To improve the performance of loading discussions, they are split into multiple +pages, loading sequentially. diff --git a/doc/user/feature_highlight.md b/doc/user/feature_highlight.md index e5f0369a0f6..ef96d2524a6 100644 --- a/doc/user/feature_highlight.md +++ b/doc/user/feature_highlight.md @@ -1,15 +1,11 @@ --- -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: 'index.md' +remove_date: '2022-10-29' --- -# Feature highlight +This document was moved to [another location](index.md). -Feature highlights are represented by a pulsing blue dot. Hovering over the dot -displays more information. They're used to emphasize certain features and -highlight helpful information to the user. - -You can dismiss any feature highlight permanently by clicking the **Got it** link -at the bottom of the information window. You cannot restore a feature highlight -after you dismiss it. +<!-- This redirect file can be deleted after <2022-10-29>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/free_user_limit.md b/doc/user/free_user_limit.md index b848128b160..a62b9c9e363 100644 --- a/doc/user/free_user_limit.md +++ b/doc/user/free_user_limit.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Free user limit **(FREE SAAS)** -From September 15, 2022, namespaces in GitLab.com on the Free tier -will be limited to five (5) members per [namespace](group/index.md#namespaces). +From October 19, 2022, namespaces in GitLab.com on the Free tier +will be limited to five (5) members per [namespace](namespace/index.md). This limit applies to top-level groups and personal namespaces. In a personal namespace, the limit applies across all projects in your personal diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 529b81e2645..53e459f7a09 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -96,7 +96,7 @@ Projects are permanently deleted after a seven-day delay. If you are on: -- Premium tier and above, you can disable this by changing the [group setting](../group/index.md#enable-delayed-project-deletion). +- Premium tier and above, you can disable this by changing the [group setting](../group/manage.md#enable-delayed-project-deletion). - Free tier, you cannot disable this setting or restore projects. ## Inactive project deletion @@ -322,7 +322,7 @@ The list of GitLab.com specific settings (and their defaults) is as follows: Some of these settings are in the process being adjusted. For example, the value for `shared_buffers` is quite high, and we are -[considering adjusting it](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/4985). +[considering adjusting it](https://gitlab.com/gitlab-com/gl-infra/reliability/-/issues/4985). ## Puma @@ -336,8 +336,8 @@ documentation. When a request is rate limited, GitLab responds with a `429` status code. The client should wait before attempting the request again. There -are also informational headers with this response detailed in [rate -limiting responses](#rate-limiting-responses). +are also informational headers with this response detailed in +[rate limiting responses](#rate-limiting-responses). The following table describes the rate limits for GitLab.com, both before and after the limits change in January, 2021: @@ -358,9 +358,9 @@ after the limits change in January, 2021: | **Pipeline creation** requests (for a given **project, user, and commit**) | | **25** requests per minute | | **Alert integration endpoint** requests (for a given **project**) | | **3600** requests per hour | -More details are available on the rate limits for [protected -paths](#protected-paths-throttle) and [raw -endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md). +More details are available on the rate limits for +[protected paths](#protected-paths-throttle) and +[raw endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md). GitLab can rate-limit requests at several layers. The rate limits listed here are configured in the application. These limits are the most @@ -398,7 +398,7 @@ following section. If you receive a `403 Forbidden` error for all requests to GitLab.com, check for any automated processes that may be triggering a block. For -assistance, contact [GitLab Support](https://support.gitlab.com/hc/en-us) +assistance, contact [GitLab Support](https://support.gitlab.com) with details, such as the affected IP address. #### Git and container registry failed authentication ban @@ -424,13 +424,9 @@ For performance reasons, if a query returns more than 10,000 records, [GitLab ex ### Visibility settings -If created before GitLab 12.2 (July 2019), these items have the +Projects, groups, and snippets have the [Internal visibility](../public_access.md#internal-projects-and-groups) -setting [disabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/12388): - -- Projects -- Groups -- Snippets +setting [disabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/12388). ### SSH maximum number of connections diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md new file mode 100644 index 00000000000..c469d6c2f6d --- /dev/null +++ b/doc/user/group/access_and_permissions.md @@ -0,0 +1,260 @@ +--- +stage: Manage +group: Workspace +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 +--- + +# Group access and permissions + +Configure your groups to control group permissions and access. + +## Group push rules **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in GitLab 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](../project/repository/push_rules.md) for newly created projects in the specific group. + +To configure push rules for a group: + +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. + +## Restrict group access by IP address **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in GitLab 12.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) from GitLab Ultimate to GitLab Premium in 13.1. + +To ensure only people from your organization can access particular +resources, you can restrict access to groups by IP address. This group-level setting +applies to: + +- The GitLab UI, including subgroups, projects, and issues. +- [In GitLab 12.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/12874), the API. + +### Security implications + +You should consider some security implications before configuring IP address restrictions. + +- Restricting HTTP traffic on GitLab.com with IP address restrictions causes SSH requests (including Git operations over + SSH) to fail. For more information, see [the relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/271673). +- Administrators and group owners can access group settings from any IP address, regardless of IP restriction. However: + - Groups owners cannot access projects belonging to the group when accessing from a disallowed IP address. + - Administrators can access projects belonging to the group when accessing from a disallowed IP address. + Access to projects includes cloning code from them. + - Users can still see group and project names and hierarchies. Only the following are restricted: + - [Groups](../../api/groups.md), including all [group resources](../../api/api_resources.md#group-resources). + - [Project](../../api/projects.md), including all [project resources](../../api/api_resources.md#project-resources). +- When you register a runner, it is not bound by the IP restrictions. When the runner requests a new job or an update to + a job's state, it is also not bound by the IP restrictions. But when the running CI/CD job sends Git requests from a + restricted IP address, the IP restriction prevents code from being cloned. +- Users may still see some events from the IP restricted groups and projects on their dashboard. Activity may include + push, merge, issue, or comment events. + +### Restrict group access by IP address + +To restrict group access by IP address: + +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions and group features** section. +1. In the **Allow access to the following IP addresses** field, enter IPv4 or IPv6 address ranges in CIDR notation. +1. Select **Save changes**. + +In self-managed installations of GitLab 15.1 and later, you can also configure +[globally-allowed IP address ranges](../admin_area/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges) +at the group level. + +## Restrict group access by domain **(PREMIUM)** + +> - Support for specifying multiple email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) in GitLab 13.1. +> - Support for restricting access to projects in the group [added](https://gitlab.com/gitlab-org/gitlab/-/issues/14004) in GitLab 14.1.2. +> - Support for restricting group memberships to groups with a subset of the allowed email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/354791) in GitLab 15.1.1 + +You can prevent users with email addresses in specific domains from being added to a group and its projects. + +To restrict group access by domain: + +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions and group features** section. +1. In the **Restrict membership by email** field, enter the domain names. +1. Select **Save changes**. + +Any time you attempt to add a new user, the user's [primary email](../profile/index.md#change-your-primary-email) is compared against this list. +Only users with a [primary email](../profile/index.md#change-your-primary-email) that matches any of the configured email domain restrictions +can be added to the group. + +The most popular public email domains cannot be restricted, such as: + +- `gmail.com`, `yahoo.com`, `aol.com`, `icloud.com` +- `hotmail.com`, `hotmail.co.uk`, `hotmail.fr` +- `msn.com`, `live.com`, `outlook.com` + +When you share a group, both the source and target namespaces must allow the domains of the members' email addresses. + +NOTE: +Removing a domain from the **Restrict membership by email** list does not remove the users with this email domain from the groups and projects under this group. +Also, if you share a group or project with another group, the target group can add more email domains to its list that are not in the list of the source group. +Hence, this feature does not ensure that the current members always conform to the **Restrict membership by email** list. + +## Prevent group sharing outside the group hierarchy + +You can configure a top-level group so its subgroups and projects +cannot invite other groups outside of the top-level group's hierarchy. +This option is only available for top-level groups. + +For example, in the following group and project hierarchy: + +- **Animals > Dogs > Dog Project** +- **Animals > Cats** +- **Plants > Trees** + +If you prevent group sharing outside the hierarchy for the **Animals** group: + +- **Dogs** can invite the group **Cats**. +- **Dogs** cannot invite the group **Trees**. +- **Dog Project** can invite the group **Cats**. +- **Dog Project** cannot invite the group **Trees**. + +To prevent sharing outside of the group's hierarchy: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions and group features**. +1. Select **Prevent members from sending invitations to groups outside of `<group_name>` and its subgroups**. +1. Select **Save changes**. + +## 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. + +To prevent a project from being shared with other groups: + +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions and group features** section. +1. Select **Prevent sharing a project in `<group_name>` with other groups**. +1. Select **Save changes**. + +This setting applies to all subgroups unless overridden by a group owner. Groups already +added to a project lose access when the setting is enabled. + +## Prevent users from requesting access to a group + +As a group owner, you can prevent non-members from requesting access to +your group. + +1. On the top bar, select **Menu > Groups**. +1. Select **Your Groups**. +1. Find the group and select it. +1. From the left menu, select **Settings > General**. +1. Expand the **Permissions and group features** section. +1. Clear the **Allow users to request access** checkbox. +1. Select **Save changes**. + +## Prevent project forking outside group **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216987) in GitLab 13.3. + +By default, projects in a group can be forked. +Optionally, on [GitLab Premium](https://about.gitlab.com/pricing/) or higher tiers, +you can prevent the projects in a group from being forked outside of the current top-level group. + +This setting will be removed from the SAML setting page, and migrated to the +group settings page. In the interim period, both of these settings are taken into consideration. +If even one is set to `true`, then the group does not allow outside forks. + +To prevent projects from being forked outside the group: + +1. Go to the top-level group's **Settings > General** page. +1. Expand the **Permissions and group features** section. +1. Check **Prevent project forking outside current group**. +1. Select **Save changes**. + +Existing forks are not removed. + +## Prevent members from being added to projects in a group **(PREMIUM)** + +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), +you can guarantee that project membership cannot be modified during the audit. + +You can still invite groups or to add members to groups, implicitly giving members access to projects in the **locked** group. + +The setting does not cascade. Projects in subgroups observe the subgroup configuration, ignoring the parent group. + +To prevent members from being added to projects in a group: + +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions and group features** section. +1. Under **Membership**, select **Prevent adding new members to projects within this group**. +1. Select **Save changes**. + +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. + +## 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 are associated with GitLab groups. + +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/ldap_synchronization.md#group-sync). + +NOTE: +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. + +### 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. 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 list 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. Select **Add Synchronization**. + +<!-- vale gitlab.Spelling = YES --> + +### Create group links via filter **(PREMIUM SELF)** + +To create group links via filter: + +1. Select the **LDAP Server** for the link. +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. Select **Add Synchronization**. + +### Override user permissions **(PREMIUM SELF)** + +LDAP user permissions can be manually overridden by an administrator. To override a user's permissions: + +1. Go to your group's **Group information > Members** page. +1. In the row for the user you are editing, select the pencil (**{pencil}**) icon. +1. Select **Edit permissions** in the modal. + +Now you can edit the user's permissions from the **Members** page. + +## Troubleshooting + +### Verify if access is blocked by IP restriction + +If a user sees a 404 when they would normally expect access, and the problem is limited to a specific group, search the `auth.log` rails log for one or more of the following: + +- `json.message`: `'Attempting to access IP restricted group'` +- `json.allowed`: `false` + +In viewing the log entries, compare the `remote.ip` with the list of +[allowed IPs](#restrict-group-access-by-ip-address) for the group. diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 6755bf9ffb9..43587dd54ef 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -30,7 +30,7 @@ To set up custom project templates in a group, add the subgroup that contains th project templates to the group settings: 1. In the group, create a [subgroup](subgroups/index.md). -1. [Add projects to the new subgroup](index.md#add-projects-to-a-group) as your templates. +1. [Add projects to the new subgroup](manage.md#add-projects-to-a-group) as your templates. 1. In the left menu for the group, select **Settings > General**. 1. Expand **Custom project templates** and select the subgroup. diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 56d1569c908..c7d92af8ee8 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -18,17 +18,9 @@ You can use groups to communicate with all of the members of the group at once. For larger organizations, you can also create [subgroups](subgroups/index.md). -## View groups +For more information about creating and managing your groups, see [Manage groups](manage.md). -To view groups: - -1. On the top bar, select **Menu > Groups**. -1. Select **Your Groups**. All groups you are a member of are displayed. -1. To view a list of public groups, select **Explore public groups**. - -You can also view groups by namespace. - -### Group visibility +## Group visibility Like projects, a group can be configured to limit the visibility of it to: @@ -43,816 +35,6 @@ empty for anonymous users. The group page has a visibility level icon. Administrator users cannot create a subgroup or project with a higher visibility level than that of the immediate parent group. -### Namespaces - -In GitLab, a *namespace* organizes related projects together. -GitLab has two types of namespaces: - -- A *personal* namespace, which is based on your username. Projects under a personal namespace must be configured one at a time. -- A *group* or *subgroup* namespace. In these namespaces, you can manage multiple projects at once. - -To determine whether you're viewing a group or personal namespace, you can view the URL. For example: - -| Namespace for | URL | Namespace | -| ------------- | --- | --------- | -| A user named `alex`. | `https://gitlab.example.com/alex` | `alex` | -| A group named `alex-team`. | `https://gitlab.example.com/alex-team` | `alex-team` | -| A group named `alex-team` with a subgroup named `marketing`. | `https://gitlab.example.com/alex-team/marketing` | `alex-team/marketing` | - -## Create a group - -To create a group: - -1. On the top bar, either: - - Select **Menu > Groups**, and on the right, select **Create group**. - - To the left of the search box, select the plus sign and then **New group**. -1. Select **Create group**. -1. Enter a name for the group in **Group name**. For a list of words that cannot be used as group names, see - [reserved names](../reserved_names.md). -1. Enter a path for the group in **Group URL**, which is used for the [namespace](#namespaces). -1. Choose the [visibility level](../public_access.md). -1. Personalize your GitLab experience by answering the following questions: - - What is your role? - - Who will be using this group? - - What will you use this group for? -1. Invite GitLab members or other users to join the group. - -<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 - -You can give a user access to all projects in a group. - -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Members**. -1. Select **Invite members**. -1. Fill in the fields. - - The role applies to all projects in the group. [Learn more about permissions](../permissions.md). - - On the **Access expiration date**, the user can no longer access projects in the group. -1. Select **Invite**. - -Members that are not automatically added are displayed on the **Invited** tab. -Users can be on this tab because they: - -- Have not yet accepted the invitation. -- Are waiting for [approval from an administrator](../admin_area/moderate_users.md). -- [Exceed the group user cap](#user-cap-for-groups). - -## Request access to a group - -As a user, you can request to be a member of a group, if an administrator allows it. - -1. On the top bar, select **Menu > Groups** and find your group. -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. - -If you change your mind before your request is approved, select -**Withdraw Access Request**. - -## Prevent users from requesting access to a group - -As a group owner, you can prevent non-members from requesting access to -your group. - -1. On the top bar, select **Menu > Groups**. -1. Select **Your Groups**. -1. Find the group and select it. -1. From the left menu, select **Settings > General**. -1. Expand the **Permissions and group features** section. -1. Clear the **Allow users to request access** checkbox. -1. Select **Save changes**. - -## Change the owner of a group - -You can change the owner of a group. Each group must always have at least one -member with the Owner role. - -- As an administrator: - 1. Go to the group and from the left menu, select **Group information > Members**. - 1. Give a different member the **Owner** role. - 1. Refresh the page. You can now remove the **Owner** role from the original owner. -- As the current group's owner: - 1. Go to the group and from the left menu, select **Group information > Members**. - 1. Give a different member the **Owner** role. - 1. Have the new owner sign in and remove the **Owner** role from you. - -## Remove a member from the group - -Prerequisites: - -- You must have the Owner role. -- 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. Go to the group. -1. From the left menu, select **Group information > 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 linked issues and merge requests** checkbox. -1. Select **Remove member**. - -## Filter and sort members in a group - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. -> - [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. - -To find members in a group, you can sort, filter, or search. - -### Filter a group - -Filter a group to find members. By default, all members in the group and subgroups are displayed. - -1. Go to the group and select **Group information > 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**. - - [In GitLab 14.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/349887), to view GitLab users created by [SAML SSO](saml_sso/index.md) or [SCIM provisioning](saml_sso/scim_setup.md) select **Enterprise = true**. - -### Search a group - -You can search for members by name, username, or email. - -1. Go to the group and select **Group information > 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 - -You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in**. - -1. Go to the group and select **Group information > 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 - -When you mention a group in a comment, every member of the group gets a to-do item -added to their To-do list. - -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. - -## Change the default branch protection of a group - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. -> - [Settings moved and renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/340403) in GitLab 14.9. - -By default, every group inherits the branch protection set at the global level. - -To change this setting for a specific group, see [group level default branch protection](../project/repository/branches/default.md#group-level-default-branch-protection). - -To change this setting globally, see [initial default branch protection](../project/repository/branches/default.md#instance-level-default-branch-protection). - -NOTE: -In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can choose to [disable group owners from updating the default branch protection](../project/repository/branches/default.md#prevent-overrides-of-default-branch-protection). - -## Add projects to a group - -There are two different ways to add a new project to a group: - -- Select a group, and then select **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 list. - -  - -### Specify who can add projects to a group - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in GitLab 10.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) from GitLab Premium to GitLab Free in 11.10. - -By default, users with at least the Developer role can create projects under a group. - -To change this setting for a specific group: - -1. On the top bar, select **Menu > Groups**. -1. Select **Your Groups**. -1. Find the group and select it. -1. From the left menu, select **Settings > General**. -1. Expand the **Permissions and group features** section. -1. Select the desired option in the **Roles allowed to create projects** dropdown list. -1. Select **Save changes**. - -To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). - -## Group activity analytics **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab 12.10 as a [Beta feature](../../policy/alpha-beta-support.md#beta-features). - -For a group, you can view how many merge requests, issues, and members were created in the last 90 days. - -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). - - - -Changes to [group wikis](../project/wiki/group.md) do not appear in group activity analytics. - -### View group activity - -You can view the most recent actions taken in a group, either in your browser or in an RSS feed: - -1. On the top bar, select **Menu > Groups**. -1. Select **Your Groups**. -1. Find the group and select it. -1. On the left sidebar, select **Group information > Activity**. - -To view the activity feed in Atom format, select the -**RSS** (**{rss}**) icon. - -## Share a group with another group - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18328) in GitLab 12.7. -> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../feature_flags.md). Disabled by default. -> - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. - [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. - -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. To invite a group, you must be a member of it. Members get direct access -to the shared group. This includes members who inherited group membership from a parent group. - -To share a given group, for example, `Frontend` with another group, for example, -`Engineering`: - -1. Go to the `Frontend` group. -1. On the left sidebar, select **Group information > Members**. -1. Select **Invite a group**. -1. In the **Select a group to invite** list, select `Engineering`. -1. Select a [role](../permissions.md) as maximum access level. -1. Select **Invite**. - -After sharing the `Frontend` group with the `Engineering` group: - -- The **Groups** tab lists the `Engineering` group. -- The **Groups** tab lists a group regardless of whether it is a public or private group. -- All members of the `Engineering` group have access to the `Frontend` group. The same access levels of the members apply up to the maximum access level selected when sharing the 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 are associated with GitLab groups. - -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/ldap_synchronization.md#group-sync). - -NOTE: -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. - -### 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. 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 list 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. Select **Add Synchronization**. - -<!-- vale gitlab.Spelling = YES --> - -### Create group links via filter **(PREMIUM SELF)** - -To create group links via filter: - -1. Select the **LDAP Server** for the link. -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. Select **Add Synchronization**. - -### Override user permissions **(PREMIUM SELF)** - -LDAP user permissions can be manually overridden by an administrator. To override a user's permissions: - -1. Go to your group's **Group information > Members** page. -1. In the row for the user you are editing, select the pencil (**{pencil}**) icon. -1. Select **Edit permissions** in the modal. - -Now you can edit the user's permissions from the **Members** page. - -## Transfer a group - -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. -- Convert a subgroup into a top-level group by transferring it out of its current group. - -When transferring groups, note: - -- Changing a group's parent can have unintended side effects. See [what happens when a repository path changes](../project/repository/index.md#what-happens-when-a-repository-path-changes). -- 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 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 fail if [packages](../packages/index.md) exist in any of the projects in the group, or in any of its subgroups. - -## Change a group's path - -Changing a group's path (group URL) can have unintended side effects. Read -[how redirects behave](../project/repository/index.md#what-happens-when-a-repository-path-changes) -before you proceed. - -If you are changing the path so it can be claimed by another group or user, -you must 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. Go to your group's **Settings > General** page. -1. Expand the **Advanced** section. -1. Under **Change group URL**, enter a new name. -1. Select **Change group URL**. - -WARNING: -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. - -## Use a custom name for the initial branch - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43290) in GitLab 13.6. - -When you create a new project in GitLab, a default branch is created with the -first push. The group owner can -[customize the initial branch](../project/repository/branches/default.md#group-level-custom-initial-branch-name) -for the group's projects to meet your group's needs. - -## Remove a group - -To remove a group and its contents: - -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Advanced** section. -1. In the **Remove group** section, select **Remove group**. -1. Type the group name. -1. Select **Confirm**. - -A group can also be removed from the groups dashboard: - -1. On the top bar, select **Menu > Groups**. -1. Select **Your Groups**. -1. Select (**{ellipsis_v}**) for the group you want to delete. -1. Select **Delete**. -1. In the Remove group section, select **Remove group**. -1. Type the group name. -1. Select **Confirm**. - -This action removes the group. It also adds a background job to delete all projects in the group. - -Specifically: - -- In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [GitLab 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#deletion-protection). -- 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. - -## Remove a group immediately **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336985) in GitLab 14.2. - -If you don't want to wait, you can remove a group immediately. - -Prerequisites: - -- You must have at least the Owner role for a group. -- You have [marked the group for deletion](#remove-a-group). - -To immediately remove a group marked for deletion: - -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Expand **Advanced**. -1. In the "Permanently remove group" section, select **Remove group**. -1. Confirm the action when asked to. - -Your group, its subgroups, projects, and all related resources, including issues and merge requests, -are deleted. - -## 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. Go to your group's **Settings > General** page. -1. Expand the **Path, transfer, remove** section. -1. In the Restore group section, select **Restore group**. - -## Prevent group sharing outside the group hierarchy - -You can configure a top-level group so its subgroups and projects -cannot invite other groups outside of the top-level group's hierarchy. -This option is only available for top-level groups. - -For example, in the following group and project hierarchy: - -- **Animals > Dogs > Dog Project** -- **Animals > Cats** -- **Plants > Trees** - -If you prevent group sharing outside the hierarchy for the **Animals** group: - -- **Dogs** can invite the group **Cats**. -- **Dogs** cannot invite the group **Trees**. -- **Dog Project** can invite the group **Cats**. -- **Dog Project** cannot invite the group **Trees**. - -To prevent sharing outside of the group's hierarchy: - -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Expand **Permissions and group features**. -1. Select **Members cannot invite groups outside of `<group_name>` and its subgroups**. -1. Select **Save changes**. - -## 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. - -To prevent a project from being shared with other groups: - -1. Go to the group's **Settings > General** page. -1. Expand the **Permissions and group features** section. -1. Select **Projects in `<group_name>` cannot be shared with other groups**. -1. Select **Save changes**. - -This setting applies to all subgroups unless overridden by a group owner. Groups already -added to a project lose access when the setting is enabled. - -## User cap for groups - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330027) in GitLab 14.7. - -FLAG: -On self-managed GitLab, this feature is not available. On GitLab.com, this feature is available for some groups. -This feature is not ready for production use. - -When the number of billable members reaches the user cap, new users can't be added to the group -without being approved by the group owner. - -Groups with the user cap feature enabled have [group sharing](#share-a-group-with-another-group) -disabled for the group and its subgroups. - -### Specify a user cap for a group - -Prerequisite: - -- You must be assigned the Owner role) for the group. - -To specify a user cap: - -1. On the top bar, select **Menu > Groups** and find your group. - You can set a cap on the top-level group only. -1. On the left sidebar, select **Settings > General**. -1. Expand **Permissions and group features**. -1. In the **User cap** box, enter the desired number of users. -1. Select **Save changes**. - -If you already have more users in the group than the user cap value, users -are not removed. However, you can't add more without approval. - -Increasing the user cap does not approve pending members. - -### Remove the user cap for a group - -You can remove the user cap, so there is no limit on the number of members you can add to a group. - -Prerequisite: - -- You must be assigned the Owner role) for the group. - -To remove the user cap: - -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Expand **Permissions and group features**. -1. In the **User cap** box, delete the value. -1. Select **Save changes**. - -Decreasing the user cap does not approve pending members. - -### Approve pending members for a group - -When the number of billable users reaches the user cap, any new member is put in a pending state -and must be approved. - -Pending members do not count as billable. Members count as billable only after they have been approved and are no longer in a pending state. - -Prerequisite: - -- You must be assigned the Owner role) for the group. - -To approve members that are pending because they've exceeded the user cap: - -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Settings > Usage Quotas**. -1. On the **Seats** tab, under the alert, select **View pending approvals**. -1. For each member you want to approve, select **Approve**. - -## Prevent members from being added to projects in a group **(PREMIUM)** - -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), -you can guarantee that project membership cannot be modified during the audit. - -You can still invite groups or to add members to groups, implicitly giving members access to projects in the **locked** group. - -The setting does not cascade. Projects in subgroups observe the subgroup configuration, ignoring the parent group. - -To prevent members from being added to projects in a group: - -1. Go to the group's **Settings > General** page. -1. Expand the **Permissions and group features** section. -1. Under **Membership**, select **Users cannot be added to projects in this group**. -1. Select **Save changes**. - -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. - -## Export members as CSV **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287940) in GitLab 14.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/336520) in GitLab 14.5. - -You can export a list of members in a group or subgroup as a CSV. - -1. Go to your group or subgroup and select either **Group information > Members** or **Subgroup information > Members**. -1. Select **Export as CSV**. -1. After the CSV file has been generated, it is emailed as an attachment to the user that requested it. - -## Group access restriction by IP address **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in GitLab 12.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) from GitLab Ultimate to GitLab Premium in 13.1. - -To ensure only people from your organization can access particular -resources, you can restrict access to groups by IP address. This group-level setting -applies to: - -- The GitLab UI, including subgroups, projects, issues, and pages. -- [In GitLab 12.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/12874), the API. -- Using Git over SSH on GitLab.com. - -### Security implications - -You should consider some security implications before configuring IP address restrictions. - -- Administrators and group owners can access group settings from any IP address, regardless of IP restriction. However: - - Groups owners cannot access projects belonging to the group when accessing from a disallowed IP address. - - Administrators can access projects belonging to the group when accessing from a disallowed IP address. - Access to projects includes cloning code from them. - - Users can still see group and project names and hierarchies. Only the following are restricted: - - [Groups](../../api/groups.md), including all [group resources](../../api/api_resources.md#group-resources). - - [Project](../../api/projects.md), including all [project resources](../../api/api_resources.md#project-resources). -- When you register a runner, it is not bound by the IP restrictions. When the runner requests a new job or an update to - a job's state, it is also not bound by the IP restrictions. But when the running CI/CD job sends Git requests from a - restricted IP address, the IP restriction prevents code from being cloned. -- Users may still see some events from the IP restricted groups and projects on their dashboard. Activity may include - push, merge, issue, or comment events. -- IP access restrictions for Git operations via SSH are supported only on GitLab SaaS. - IP access restrictions applied to self-managed instances block SSH completely. - -### Restrict group access by IP address - -To restrict group access by IP address: - -1. Go to the group's **Settings > General** page. -1. Expand the **Permissions and group features** section. -1. In the **Restrict access by IP address** field, enter IPv4 or IPv6 address ranges in CIDR notation. -1. Select **Save changes**. - -In self-managed installations of GitLab 15.1 and later, you can also configure -[globally-allowed IP address ranges](../admin_area/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges) -at the group level. - -## Restrict group access by domain **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in GitLab 12.2. -> - Support for specifying multiple email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) in GitLab 13.1. -> - Support for restricting access to projects in the group [added](https://gitlab.com/gitlab-org/gitlab/-/issues/14004) in GitLab 14.1.2. -> - Support for restricting group memberships to groups with a subset of the allowed email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/354791) in GitLab 15.0.1 - -You can prevent users with email addresses in specific domains from being added to a group and its projects. - -To restrict group access by domain: - -1. Go to the group's **Settings > General** page. -1. Expand the **Permissions and group features** section. -1. In the **Restrict membership by email** field, enter the domain names. -1. Select **Save changes**. - -Any time you attempt to add a new user, the user's [primary email](../profile/index.md#change-your-primary-email) is compared against this list. -Only users with a [primary email](../profile/index.md#change-your-primary-email) that matches any of the configured email domain restrictions -can be added to the group. - -The most popular public email domains cannot be restricted, such as: - -- `gmail.com`, `yahoo.com`, `aol.com`, `icloud.com` -- `hotmail.com`, `hotmail.co.uk`, `hotmail.fr` -- `msn.com`, `live.com`, `outlook.com` - -When you share a group, both the source and target namespaces must allow the domains of the members' email addresses. - -## Restrict Git access protocols - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365601) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `group_level_git_protocol_control`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to -[enable the feature flag](../../administration/feature_flags.md) named `group_level_git_protocol_control`. On GitLab.com, -this feature is available. - -You can set the permitted protocols used to access a group's repositories to either SSH, HTTPS, or both. This setting -is disabled when the [instance setting](../admin_area/settings/visibility_and_access_controls.md#configure-enabled-git-access-protocols) is -configured by an administrator. - -To change the permitted Git access protocols for a group: - -1. Go to the group's **Settings > General** page. -1. Expand the **Permissions and group features** section. -1. Choose the permitted protocols from **Enabled Git access protocols**. -1. Select **Save changes**. - -## Group file templates **(PREMIUM)** - -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). -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. -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 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). - -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). - -### Enable group file template **(PREMIUM)** - -To enable group file templates: - -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**. - -## 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 disable email notifications: - -1. Go to the group's **Settings > General** page. -1. Expand the **Permissions and group features** section. -1. Select **Email notifications are disabled**. -1. Select **Save changes**. - -## Disable group mentions - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21301) in GitLab 12.6. - -You can prevent users from being added to a conversation and getting notified when -anyone [mentions a group](../discussions/index.md#mentions) -in which those users are members. - -Groups with disabled mentions are visualized accordingly in the autocompletion dropdown list. - -This is particularly helpful for groups with a large number of users. - -To disable group mentions: - -1. Go to the group's **Settings > General** page. -1. Expand the **Permissions and group features** section. -1. Select **Group mentions are disabled**. -1. Select **Save changes**. - -## Enable delayed project deletion **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. -> - [Inheritance and enforcement added](https://gitlab.com/gitlab-org/gitlab/-/issues/321724) in GitLab 13.11. -> - [Instance setting to enable by default added](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2. -> - [Instance setting is inherited and enforced when disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. -> - [User interface changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352961) in GitLab 15.1. - -[Delayed project deletion](../project/settings/index.md#delayed-project-deletion) is locked and disabled unless the instance-level settings for -[deletion protection](../admin_area/settings/visibility_and_access_controls.md#deletion-protection) are enabled for either groups only or groups and projects. -When enabled on groups, projects in the group are deleted after a period of delay. During this period, projects are in a read-only state and can be restored. -The default period is seven days but [is configurable at the instance level](../admin_area/settings/visibility_and_access_controls.md#retention-period). - -On self-managed GitLab, projects are deleted immediately by default. -In GitLab 14.2 and later, an administrator can -[change the default setting](../admin_area/settings/visibility_and_access_controls.md#deletion-protection) -for projects in newly-created groups. - -On GitLab.com, see the [GitLab.com settings page](../gitlab_com/index.md#delayed-project-deletion) for -the default setting. - -To enable delayed deletion of projects in a group: - -1. Go to the group's **Settings > General** page. -1. Expand the **Permissions and group features** section. -1. Scroll to: - - (GitLab 15.1 and later) **Deletion protection** and select **Keep deleted projects**. - - (GitLab 15.0 and earlier) **Enable delayed project deletion** and tick the checkbox. -1. Optional. To prevent subgroups from changing this setting, select: - - (GitLab 15.1 and later), **Enforce deletion protection for all subgroups** - - (GitLab 15.0 and earlier), **Enforce for all subgroups**. -1. Select **Save changes**. - -NOTE: -In GitLab 13.11 and above the group setting for delayed project deletion is inherited by subgroups. As discussed in [Cascading settings](../../development/cascading_settings.md) inheritance can be overridden, unless enforced by an ancestor. - -## Prevent project forking outside group **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216987) in GitLab 13.3. - -By default, projects in a group can be forked. -Optionally, on [GitLab Premium](https://about.gitlab.com/pricing/) or higher tiers, -you can prevent the projects in a group from being forked outside of the current top-level group. - -This setting will be removed from the SAML setting page, and migrated to the -group settings page. In the interim period, both of these settings are taken into consideration. -If even one is set to `true`, then the group does not allow outside forks. - -To prevent projects from being forked outside the group: - -1. Go to the top-level group's **Settings > General** page. -1. Expand the **Permissions and group features** section. -1. Check **Prevent project forking outside current group**. -1. Select **Save changes**. - -Existing forks are not removed. - -## Group push rules **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in GitLab 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](../project/repository/push_rules.md) for newly created projects in the specific group. - -To configure push rules for a group: - -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. - -## Group merge request approval settings **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285458) in GitLab 13.9. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.5. -> - [Feature flag `group_merge_request_approval_settings_feature_flag`](https://gitlab.com/gitlab-org/gitlab/-/issues/343872) removed in GitLab 14.9. - -Group approval settings manage [project merge request approval settings](../project/merge_requests/approvals/settings.md) -at the top-level group level. These settings [cascade to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) -that belong to the group. - -To view the merge request approval settings for a group: - -1. Go to the top-level group's **Settings > General** page. -1. Expand the **Merge request approvals** section. -1. Select the settings you want. -1. Select **Save changes**. - -Support for group-level settings for merge request approval rules is tracked in this [epic](https://gitlab.com/groups/gitlab-org/-/epics/4367). - ## Related topics - [Group wikis](../project/wiki/index.md) @@ -874,31 +56,8 @@ Support for group-level settings for merge request approval rules is tracked in - [Integrations](../admin_area/settings/project_integration_management.md). - [Transfer a project into a group](../project/settings/index.md#transfer-a-project-to-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). +- [Lock the sharing with group feature](access_and_permissions.md#prevent-a-project-from-being-shared-with-groups). - [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforce-2fa-for-all-users-in-a-group): Enforce 2FA for all group members. - Namespaces [API](../../api/namespaces.md) and [Rake tasks](../../raketasks/index.md). - [Control access and visibility](../admin_area/settings/visibility_and_access_controls.md). - -## Troubleshooting - -### Verify if access is blocked by IP restriction - -If a user sees a 404 when they would normally expect access, and the problem is limited to a specific group, search the `auth.log` rails log for one or more of the following: - -- `json.message`: `'Attempting to access IP restricted group'` -- `json.allowed`: `false` - -In viewing the log entries, compare the `remote.ip` with the list of -[allowed IPs](#group-access-restriction-by-ip-address) for the group. - -### Validation errors on namespaces and groups - -[GitLab 14.4 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70365) performs -the following checks when creating or updating namespaces or groups: - -- Namespaces must not have parents. -- Group parents must be groups and not namespaces. - -In the unlikely event that you see these errors in your GitLab installation, -[contact Support](https://about.gitlab.com/support/) so that we can improve this validation. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 858b13b87b8..530635802a6 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -35,10 +35,22 @@ In GitLab, iterations are similar to milestones, with a few differences: ## View the iterations list -To view the iterations list, go to **{issues}** **Issues > Iterations**. +To view the iterations list: + +1. On the top bar, select **Menu > Projects** and find your project. +1. Select **Issues > Iterations**. + To view all the iterations in a cadence, ordered by descending date, select that iteration cadence. From there you can create a new iteration or select an iteration to get a more detailed view. +NOTE: +If a project has issue tracking +[turned off](../../project/settings/index.md#configure-project-visibility-features-and-permissions), +you can view the iterations list +by going to its URL. To do so, add: `/-/cadences` to your project or group URL. +For example `https://gitlab.com/gitlab-org/sample-data-templates/sample-gitlab-project/-/cadences`. +This is tracked in [issue 339009](https://gitlab.com/gitlab-org/gitlab/-/issues/339009). + ## Create an iteration > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) in GitLab 14.10. @@ -175,6 +187,7 @@ To group issues by label: > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5077) in GitLab 14.1 [with a flag](../../../administration/feature_flags.md), named `iteration_cadences`. Disabled by default. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/354977) in GitLab 15.0: All scheduled iterations must start on the same day of the week as the cadence start day. Start date of cadence cannot be edited after the first iteration starts. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/354878) in GitLab 15.0. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/367493) in GitLab 15.3: A new automation start date can be selected for cadence. Upcoming iterations will be scheduled to start on the same day of the week as the changed start date. Iteration cadences automate iteration scheduling. You can use them to automate creating iterations every 1, 2, 3, or 4 weeks. You can also @@ -195,7 +208,7 @@ To create an iteration cadence: 1. Select **New iteration cadence**. 1. Complete the fields. - Enter the title and description of the iteration cadence. - - Enter the first iteration start date of the iteration cadence. Iterations will be scheduled to + - Select the automation start date of the iteration cadence. Iterations will be scheduled to begin on the same day of the week as the day of the week of the start date. - From the **Duration** dropdown list, select how many weeks each iteration should last. - From the **Upcoming iterations** dropdown list, select how many upcoming iterations should be @@ -215,10 +228,9 @@ To edit an iteration cadence: 1. On the left sidebar, select **Issues > Iterations**. 1. Select **Edit iteration cadence**. -When you edit the **Duration**, **Upcoming iterations**, or **First iteration start date** fields, -only upcoming iterations are affected. - -You can edit the first iteration start date of a cadence if the cadence has not started yet. +When you edit the **Automation start date** field, +you must set a new start date that doesn't overlap with the existing +current or past iterations. Editing **Upcoming iterations** is a non-destructive action. If ten upcoming iterations already exist, changing the number under **Upcoming iterations** to `2` @@ -261,25 +273,12 @@ To upgrade the iteration cadence to use the automation features: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Issues > Iterations**. 1. Select the three-dot menu (**{ellipsis_v}**) > **Edit cadence** for the cadence you want to upgrade. -1. Complete the required fields **Duration** and **Upcoming iterations**. +1. Complete the required fields **Duration**, **Upcoming iterations**, and **Automation start date**. +For **Automation start date**, you can select any date that doesn't overlap with the existing open iterations. +If you have upcoming iterations, the automatic scheduling adjusts them appropriately to fit +your chosen duration. 1. Select **Save changes**. -#### Start dates of converted cadences - -The first iteration start date of your converted cadence is set to the start date of its -**first** existing iteration. - -If you attempt to set a new start date, the conversion fails with an error message. -If your manual cadence is empty, converting it to use automatic scheduling is effectively -the same as creating a new automated cadence. - -GitLab will start scheduling new iterations on the same day of the week as the start date, -starting from the nearest such day from the current date. - -During the conversion process GitLab does not delete or modify existing **ongoing** or -**closed** iterations. If you have iterations with start dates in the future, -they are updated to fit your cadence settings. - #### Converted cadences example For example, suppose it's Friday, April 15, and you have three iterations in a manual cadence: @@ -288,20 +287,21 @@ For example, suppose it's Friday, April 15, and you have three iterations in a m - Tuesday, April 12 - Friday, April 15 (ongoing) - Tuesday, May 3 - Friday, May 6 (upcoming) -On Friday, April 15, you convert the manual cadence -to automate scheduling iterations every week, up to two upcoming iterations. - -The first iteration is closed, and the second iteration is ongoing, -so they aren't deleted or modified in the conversion process. - -To observe the weekly duration, the third iteration is updated so that it: +The earliest possible **Automation start date** you can choose +is Saturday, April 16 in this scenario, because April 15 overlaps with +the ongoing iteration. -- Starts on Monday, April 18 - which is the nearest date that is Monday. -- Ends on Sunday, April 24. - -Finally, to always have two upcoming iterations, an additional iteration is scheduled: +If you select Monday, April 18 as the automation start date to +automate scheduling iterations every week up to two upcoming iterations, +after the conversion you have the following iterations: - Monday, April 4 - Friday, April 8 (closed) - Tuesday, April 12 - Friday, April 15 (ongoing) - Monday, April 18 - Sunday, April 24 (upcoming) - Monday, April 25 - Sunday, May 1 (upcoming) + +Your existing upcoming iteration "Tuesday, April 12 - Friday, April 15" +is changed to "April 18 - Sunday, April 24". + +An additional upcoming iteration "April 25 - Sunday, May 1" is scheduled +to satisfy the requirement that there are at least two upcoming iterations scheduled. diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md new file mode 100644 index 00000000000..a9cc6cc8432 --- /dev/null +++ b/doc/user/group/manage.md @@ -0,0 +1,570 @@ +--- +stage: Manage +group: Workspace +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 +--- + +# Manage groups + +Use groups to manage one or more related projects at the same time. + +## View groups + +1. On the top bar, select **Menu > Groups**. +1. Select **Explore groups**. + +The **Groups** page shows a list of groups, sorted by last updated date. + +- To explore all public groups, select **Explore groups**. +- To view groups where you have a direct or indirect membership, select **Your groups**. This tab shows groups that you are a member of: + - Through membership of a subgroup's parent group. + - Through direct or inherited membership of a project in the group or subgroup. + +## Create a group + +To create a group: + +1. On the top bar, either: + - Select **Menu > Groups**, and on the right, select **Create group**. + - To the left of the search box, select the plus sign and then **New group**. +1. Select **Create group**. +1. Enter a name for the group in **Group name**. For a list of words that cannot be used as group names, see + [reserved names](../reserved_names.md). +1. Enter a path for the group in **Group URL**, which is used for the [namespace](../namespace/index.md). +1. Choose the [visibility level](../public_access.md). +1. Personalize your GitLab experience by answering the following questions: + - What is your role? + - Who will be using this group? + - What will you use this group for? +1. Invite GitLab members or other users to join the group. + +<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). + +## Remove a group + +To remove a group and its contents: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Advanced** section. +1. In the **Remove group** section, select **Remove group**. +1. Type the group name. +1. Select **Confirm**. + +A group can also be removed from the groups dashboard: + +1. On the top bar, select **Menu > Groups**. +1. Select **Your Groups**. +1. Select (**{ellipsis_v}**) for the group you want to delete. +1. Select **Delete**. +1. In the Remove group section, select **Remove group**. +1. Type the group name. +1. Select **Confirm**. + +This action removes the group. It also adds a background job to delete all projects in the group. + +Specifically: + +- In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [GitLab 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#deletion-protection). +- 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. + +## Remove a group immediately **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336985) in GitLab 14.2. + +If you don't want to wait, you can remove a group immediately. + +Prerequisites: + +- You must have at least the Owner role for a group. +- You have [marked the group for deletion](#remove-a-group). + +To immediately remove a group marked for deletion: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. In the "Permanently remove group" section, select **Remove group**. +1. Confirm the action when asked to. + +Your group, its subgroups, projects, and all related resources, including issues and merge requests, +are deleted. + +## 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. Go to your group's **Settings > General** page. +1. Expand the **Path, transfer, remove** section. +1. In the Restore group section, select **Restore group**. + +## Request access to a group + +As a user, you can request to be a member of a group, if an administrator allows it. + +1. On the top bar, select **Menu > Groups** and find your group. +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. + +If you change your mind before your request is approved, select +**Withdraw Access Request**. + +## Filter and sort members in a group + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. +> - [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. + +To find members in a group, you can sort, filter, or search. + +### Filter a group + +Filter a group to find members. By default, all members in the group and subgroups are displayed. + +1. Go to the group and select **Group information > 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**. + - [In GitLab 14.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/349887), to view GitLab users created by [SAML SSO](saml_sso/index.md) or [SCIM provisioning](saml_sso/scim_setup.md) select **Enterprise = true**. + +### Search a group + +You can search for members by name, username, or email. + +1. Go to the group and select **Group information > 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 + +You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in**. + +1. Go to the group and select **Group information > 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}**). + +## Add users to a group + +You can give a user access to all projects in a group. + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Members**. +1. Select **Invite members**. +1. Fill in the fields. + - The role applies to all projects in the group. [Learn more about permissions](../permissions.md). + - On the **Access expiration date**, the user can no longer access projects in the group. +1. Select **Invite**. + +Members that are not automatically added are displayed on the **Invited** tab. +Users can be on this tab because they: + +- Have not yet accepted the invitation. +- Are waiting for [approval from an administrator](../admin_area/moderate_users.md). +- [Exceed the group user cap](#user-cap-for-groups). + +## Remove a member from the group + +Prerequisites: + +- You must have the Owner role. +- 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. Go to the group. +1. From the left menu, select **Group information > 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 linked issues and merge requests** checkbox. +1. Select **Remove member**. + +## Add projects to a group + +There are two different ways to add a new project to a group: + +- Select a group, and then select **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 list. + +  + +### Specify who can add projects to a group + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in GitLab 10.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) from GitLab Premium to GitLab Free in 11.10. + +By default, users with at least the Developer role can create projects under a group. + +To change this setting for a specific group: + +1. On the top bar, select **Menu > Groups**. +1. Select **Your Groups**. +1. Find the group and select it. +1. From the left menu, select **Settings > General**. +1. Expand the **Permissions and group features** section. +1. Select the desired option in the **Allowed to create projects** dropdown list. +1. Select **Save changes**. + +To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). + +## Change the owner of a group + +You can change the owner of a group. Each group must always have at least one +member with the Owner role. + +- As an administrator: + 1. Go to the group and from the left menu, select **Group information > Members**. + 1. Give a different member the **Owner** role. + 1. Refresh the page. You can now remove the **Owner** role from the original owner. +- As the current group's owner: + 1. Go to the group and from the left menu, select **Group information > Members**. + 1. Give a different member the **Owner** role. + 1. Have the new owner sign in and remove the **Owner** role from you. + +## Change a group's path + +Changing a group's path (group URL) can have unintended side effects. Read +[how redirects behave](../project/repository/index.md#what-happens-when-a-repository-path-changes) +before you proceed. + +If you are changing the path so it can be claimed by another group or user, +you must 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. Go to your group's **Settings > General** page. +1. Expand the **Advanced** section. +1. Under **Change group URL**, enter a new name. +1. Select **Change group URL**. + +WARNING: +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. + +## Change the default branch protection of a group + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. +> - [Settings moved and renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/340403) in GitLab 14.9. + +By default, every group inherits the branch protection set at the global level. + +To change this setting for a specific group, see [group level default branch protection](../project/repository/branches/default.md#group-level-default-branch-protection). + +To change this setting globally, see [initial default branch protection](../project/repository/branches/default.md#instance-level-default-branch-protection). + +NOTE: +In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can choose to [disable group owners from updating the default branch protection](../project/repository/branches/default.md#prevent-overrides-of-default-branch-protection). + +## Use a custom name for the initial branch + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43290) in GitLab 13.6. + +When you create a new project in GitLab, a default branch is created with the +first push. The group owner can +[customize the initial branch](../project/repository/branches/default.md#group-level-custom-initial-branch-name) +for the group's projects to meet your group's needs. + +## Share a group with another group + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18328) in GitLab 12.7. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../feature_flags.md). Disabled by default. +> - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. + [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. + +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. To invite a group, you must be a member of it. Members get direct access +to the shared group. This includes members who inherited group membership from a parent group. + +To share a given group, for example, `Frontend` with another group, for example, +`Engineering`: + +1. Go to the `Frontend` group. +1. On the left sidebar, select **Group information > Members**. +1. Select **Invite a group**. +1. In the **Select a group to invite** list, select `Engineering`. +1. Select a [role](../permissions.md) as maximum access level. +1. Select **Invite**. + +After sharing the `Frontend` group with the `Engineering` group: + +- The **Groups** tab lists the `Engineering` group. +- The **Groups** tab lists a group regardless of whether it is a public or private group. +- All members of the `Engineering` group have access to the `Frontend` group. The same access levels of the members apply up to the maximum access level selected when sharing the group. + +## Transfer a group + +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. +- Convert a subgroup into a top-level group by transferring it out of its current group. + +When transferring groups, note: + +- Changing a group's parent can have unintended side effects. See [what happens when a repository path changes](../project/repository/index.md#what-happens-when-a-repository-path-changes). +- 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 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 fail if [packages](../packages/index.md) exist in any of the projects in the group, or in any of its subgroups. + +To transfer a group: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Advanced** section. +1. In the **Remove group** section, select **Transfer group**. +1. Select the group name in the drop down menu. +1. Select **Transfer group**. + +## Enable delayed project deletion **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. +> - [Inheritance and enforcement added](https://gitlab.com/gitlab-org/gitlab/-/issues/321724) in GitLab 13.11. +> - [Instance setting to enable by default added](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2. +> - [Instance setting is inherited and enforced when disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. +> - [User interface changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352961) in GitLab 15.1. + +[Delayed project deletion](../project/settings/index.md#delayed-project-deletion) is locked and disabled unless the instance-level settings for +[deletion protection](../admin_area/settings/visibility_and_access_controls.md#deletion-protection) is enabled for either groups only or groups and projects. +When enabled on groups, projects in the group are deleted after a period of delay. During this period, projects are in a read-only state and can be restored. +The default period is seven days but [is configurable at the instance level](../admin_area/settings/visibility_and_access_controls.md#retention-period). + +On self-managed GitLab, projects are deleted immediately by default. +In GitLab 14.2 and later, an administrator can +[change the default setting](../admin_area/settings/visibility_and_access_controls.md#deletion-protection) +for projects in newly-created groups. + +On GitLab.com, see the [GitLab.com settings page](../gitlab_com/index.md#delayed-project-deletion) for +the default setting. + +To enable delayed deletion of projects in a group: + +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions and group features** section. +1. Scroll to: + - (GitLab 15.1 and later) **Deletion protection** and select **Keep deleted projects**. + - (GitLab 15.0 and earlier) **Enable delayed project deletion** and tick the checkbox. +1. Optional. To prevent subgroups from changing this setting, select: + - (GitLab 15.1 and later), **Enforce deletion protection for all subgroups** + - (GitLab 15.0 and earlier), **Enforce for all subgroups**. +1. Select **Save changes**. + +NOTE: +In GitLab 13.11 and above the group setting for delayed project deletion is inherited by subgroups. As discussed in [Cascading settings](../../development/cascading_settings.md) inheritance can be overridden, unless enforced by an ancestor. + +## 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 disable email notifications: + +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions and group features** section. +1. Select **Disable email notifications**. +1. Select **Save changes**. + +## Disable group mentions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21301) in GitLab 12.6. + +You can prevent users from being added to a conversation and getting notified when +anyone [mentions a group](../discussions/index.md#mentions) +in which those users are members. + +Groups with disabled mentions are visualized accordingly in the autocompletion dropdown list. + +This is particularly helpful for groups with a large number of users. + +To disable group mentions: + +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions and group features** section. +1. Select **Disable group mentions**. +1. Select **Save changes**. + +## Export members as CSV **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287940) in GitLab 14.2. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/336520) in GitLab 14.5. + +You can export a list of members in a group or subgroup as a CSV. + +1. Go to your group or subgroup and select either **Group information > Members** or **Subgroup information > Members**. +1. Select **Export as CSV**. +1. After the CSV file has been generated, it is emailed as an attachment to the user that requested it. + +## User cap for groups + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330027) in GitLab 14.7. + +FLAG: +On self-managed GitLab, this feature is not available. On GitLab.com, this feature is available for some groups. +This feature is not ready for production use. + +When the number of billable members reaches the user cap, new users can't be added to the group +without being approved by the group owner. + +Groups with the user cap feature enabled have [group sharing](#share-a-group-with-another-group) +disabled for the group and its subgroups. + +### Specify a user cap for a group + +Prerequisite: + +- You must be assigned the Owner role) for the group. + +To specify a user cap: + +1. On the top bar, select **Menu > Groups** and find your group. + You can set a cap on the top-level group only. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions and group features**. +1. In the **User cap** box, enter the desired number of users. +1. Select **Save changes**. + +If you already have more users in the group than the user cap value, users +are not removed. However, you can't add more without approval. + +Increasing the user cap does not approve pending members. + +### Remove the user cap for a group + +You can remove the user cap, so there is no limit on the number of members you can add to a group. + +Prerequisite: + +- You must be assigned the Owner role) for the group. + +To remove the user cap: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions and group features**. +1. In the **User cap** box, delete the value. +1. Select **Save changes**. + +Decreasing the user cap does not approve pending members. + +### Approve pending members for a group + +When the number of billable users reaches the user cap, any new member is put in a pending state +and must be approved. + +Pending members do not count as billable. Members count as billable only after they have been approved and are no longer in a pending state. + +Prerequisite: + +- You must be assigned the Owner role) for the group. + +To approve members that are pending because they've exceeded the user cap: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Usage Quotas**. +1. On the **Seats** tab, under the alert, select **View pending approvals**. +1. For each member you want to approve, select **Approve**. + +## Group file templates **(PREMIUM)** + +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). +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. +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 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). + +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). + +### Enable group file template **(PREMIUM)** + +To enable group file templates: + +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**. + +## Group merge request approval settings **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285458) in GitLab 13.9. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.5. +> - [Feature flag `group_merge_request_approval_settings_feature_flag`](https://gitlab.com/gitlab-org/gitlab/-/issues/343872) removed in GitLab 14.9. + +Group approval settings manage [project merge request approval settings](../project/merge_requests/approvals/settings.md) +at the top-level group level. These settings [cascade to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) +that belong to the group. + +To view the merge request approval settings for a group: + +1. Go to the top-level group's **Settings > General** page. +1. Expand the **Merge request approvals** section. +1. Select the settings you want. +1. Select **Save changes**. + +Support for group-level settings for merge request approval rules is tracked in this [epic](https://gitlab.com/groups/gitlab-org/-/epics/4367). + +## Group activity analytics **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab 12.10 as a [Beta feature](../../policy/alpha-beta-support.md#beta-features). + +For a group, you can view how many merge requests, issues, and members were created in the last 90 days. + +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). + + + +Changes to [group wikis](../project/wiki/group.md) do not appear in group activity analytics. + +### View group activity + +You can view the most recent actions taken in a group, either in your browser or in an RSS feed: + +1. On the top bar, select **Menu > Groups**. +1. Select **Your Groups**. +1. Find the group and select it. +1. On the left sidebar, select **Group information > Activity**. + +To view the activity feed in Atom format, select the +**RSS** (**{rss}**) icon. + +## Troubleshooting + +### Validation errors on namespaces and groups + +[GitLab 14.4 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70365) performs +the following checks when creating or updating namespaces or groups: + +- Namespaces must not have parents. +- Group parents must be groups and not namespaces. + +In the unlikely event that you see these errors in your GitLab installation, +[contact Support](https://about.gitlab.com/support/) so that we can improve this validation. diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md new file mode 100644 index 00000000000..97e8f9c54a3 --- /dev/null +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -0,0 +1,211 @@ +--- +stage: Manage +group: Authentication and Authorization +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 +--- + +# Example group SAML and SCIM configurations **(PREMIUM SAAS)** + +These are notes and screenshots regarding Group SAML and SCIM that the GitLab Support Team sometimes uses while troubleshooting, but which do not fit into the official documentation. GitLab is making this public, so that anyone can make use of the Support team's collected knowledge. + +Please refer to the GitLab [Group SAML](index.md) docs for information on the feature and how to set it up. + +When troubleshooting a SAML configuration, GitLab team members will frequently start with the [SAML troubleshooting section](index.md#troubleshooting). + +They may then set up a test configuration of the desired identity provider. We include example screenshots in this section. + +## SAML and SCIM screenshots + +This section includes relevant screenshots of the following example configurations of [Group SAML](index.md) and [Group SCIM](scim_setup.md): + +- [Azure Active Directory](#azure-active-directory) +- [Google Workspace](#google-workspace) +- [Okta](#okta) +- [OneLogin](#onelogin) + +WARNING: +These screenshots are updated only as needed by GitLab Support. They are **not** official documentation. + +If you are currently having an issue with GitLab, you may want to check your [support options](https://about.gitlab.com/support/). + +## Azure Active Directory + +Basic SAML app configuration: + + + +User claims and attributes: + + + +SCIM mapping: + + + + +Group Sync: + + + +## Google Workspace + +Basic SAML app configuration: + + + +User claims and attributes: + + + +IdP links and certificate: + +NOTE: +Google Workspace displays a SHA256 fingerprint. To retrieve the SHA1 fingerprint required by GitLab for configuring SAML, download the certificate and calculate the SHA1 certificate +fingerprint. + + + +## Okta + +Basic SAML app configuration for GitLab.com groups: + + + +Basic SAML app configuration for GitLab self-managed: + + + +User claims and attributes: + + + +Groups attribute: + + + +Advanced SAML app settings (defaults): + + + +IdP Links and Certificate: + + + +Sign on settings: + + + +Setting the username for the newly provisioned users when assigning them the SCIM app: + + + +## OneLogin + +Application details: + + + +Parameters: + + + +Adding a user: + + + +SSO settings: + + + +## SAML response example + +When a user signs in using SAML, GitLab receives a SAML response. The SAML response can be found in `production.log` logs as a base64-encoded message. Locate the response by +searching for `SAMLResponse`. The decoded SAML response is in XML format. For example: + +```xml +<?xml version="1.0" encoding="UTF-8"?> +<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:xs="http://www.w3.org/2001/XMLSchema" Destination="https://gitlabexample/-/saml/callback" ID="id4898983630840142426821432" InResponseTo="_c65e4c88-9425-4472-b42c-37f4186ac0ee" IssueInstant="2022-05-30T21:30:35.696Z" Version="2.0"> + <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.okta.com/exk2y6j57o1Pdr2lI8qh7</saml2:Issuer> + <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> + <ds:SignedInfo> + <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> + <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/> + <ds:Reference URI="#id4898983630840142426821432"> + <ds:Transforms> + <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> + <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"> + <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="xs"/> + </ds:Transform> + </ds:Transforms> + <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/> + <ds:DigestValue>neiQvv9d3OgS4GZW8Nptp4JhjpKs3GCefibn+vmRgk4=</ds:DigestValue> + </ds:Reference> + </ds:SignedInfo> + <ds:SignatureValue>dMsQX8ivi...HMuKGhyLRvabGU6CuPrf7==</ds:SignatureValue> + <ds:KeyInfo> + <ds:X509Data> + <ds:X509Certificate>MIIDq...cptGr3vN9TQ==</ds:X509Certificate> + </ds:X509Data> + </ds:KeyInfo> + </ds:Signature> + <saml2p:Status xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"> + <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/> + </saml2p:Status> + <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="id489" IssueInstant="2022-05-30T21:30:35.696Z" Version="2.0"> + <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.okta.com/exk2y6j57o1Pdr2lI8qh7</saml2:Issuer> + <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> + <ds:SignedInfo> + <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> + <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/> + <ds:Reference URI="#id48989836309833801859473359"> + <ds:Transforms> + <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> + <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"> + <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="xs"/> + </ds:Transform> + </ds:Transforms> + <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/> + <ds:DigestValue>MaIsoi8hbT9gsi/mNZsz449mUuAcuEWY0q3bc4asOQs=</ds:DigestValue> + </ds:Reference> + </ds:SignedInfo> + <ds:SignatureValue>dMsQX8ivi...HMuKGhyLRvabGU6CuPrf7==<</ds:SignatureValue> + <ds:KeyInfo> + <ds:X509Data> + <ds:X509Certificate>MIIDq...cptGr3vN9TQ==</ds:X509Certificate> + </ds:X509Data> + </ds:KeyInfo> + </ds:Signature> + <saml2:Subject xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"> + <saml2:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">useremail@domain.com</saml2:NameID> + <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> + <saml2:SubjectConfirmationData InResponseTo="_c65e4c88-9425-4472-b42c-37f4186ac0ee" NotOnOrAfter="2022-05-30T21:35:35.696Z" Recipient="https://gitlab.example.com/-/saml/callback"/> + </saml2:SubjectConfirmation> + </saml2:Subject> + <saml2:Conditions xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" NotBefore="2022-05-30T21:25:35.696Z" NotOnOrAfter="2022-05-30T21:35:35.696Z"> + <saml2:AudienceRestriction> + <saml2:Audience>https://gitlab.example.com/</saml2:Audience> + </saml2:AudienceRestriction> + </saml2:Conditions> + <saml2:AuthnStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" AuthnInstant="2022-05-30T21:30:35.696Z" SessionIndex="_c65e4c88-9425-4472-b42c-37f4186ac0ee"> + <saml2:AuthnContext> + <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef> + </saml2:AuthnContext> + </saml2:AuthnStatement> + <saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"> + <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">useremail@domain.com</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="firtname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">John</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="lastname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Doe</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="Groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Super-awesome-group</saml2:AttributeValue> + </saml2:Attribute> + </saml2:AttributeStatement> + </saml2:Assertion> +</saml2p:Response> +``` diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index b8b7a16b31b..8bc316f9396 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -28,7 +28,7 @@ To configure SAML Group Sync: 1. Ensure your SAML identity provider sends an attribute statement with the same name as the value of the `groups_attribute` setting. - For GitLab.com: 1. See [SAML SSO for GitLab.com groups](index.md). - 1. Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups`. + 1. Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups`. NOTE: The value for `Groups` or `groups` in the SAML response can be either the group name or the group ID. @@ -44,8 +44,8 @@ The value for `Groups` or `groups` in the SAML response can be either the group Other attribute names such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` are not accepted as a source of groups. -See the [SAML troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md) -for examples on configuring the required attribute name in the SAML identity provider's settings. +See [examples](../../../user/group/saml_sso/example_saml_config.md) +for configuring the required attribute name in the SAML identity provider's settings. ## Configure SAML Group Links @@ -161,3 +161,9 @@ graph TB GitLabGroupD --> |Member|GitLabUserC GitLabGroupD --> |Member|GitLabUserD ``` + +### Use the API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3. + +You can use the GitLab API to [list, add, and delete](../../../api/groups.md#saml-group-links) SAML group links. diff --git a/doc/user/group/saml_sso/img/AzureAD-basic_SAML.png b/doc/user/group/saml_sso/img/AzureAD-basic_SAML.png Binary files differnew file mode 100644 index 00000000000..7a0d83ab2dd --- /dev/null +++ b/doc/user/group/saml_sso/img/AzureAD-basic_SAML.png diff --git a/doc/user/group/saml_sso/img/AzureAD-claims.png b/doc/user/group/saml_sso/img/AzureAD-claims.png Binary files differnew file mode 100644 index 00000000000..576040be337 --- /dev/null +++ b/doc/user/group/saml_sso/img/AzureAD-claims.png diff --git a/doc/user/group/saml_sso/img/AzureAD-scim_attribute_mapping.png b/doc/user/group/saml_sso/img/AzureAD-scim_attribute_mapping.png Binary files differnew file mode 100644 index 00000000000..5ad82003eed --- /dev/null +++ b/doc/user/group/saml_sso/img/AzureAD-scim_attribute_mapping.png diff --git a/doc/user/group/saml_sso/img/AzureAD-scim_provisioning.png b/doc/user/group/saml_sso/img/AzureAD-scim_provisioning.png Binary files differnew file mode 100644 index 00000000000..b2c385151a6 --- /dev/null +++ b/doc/user/group/saml_sso/img/AzureAD-scim_provisioning.png diff --git a/doc/user/group/saml_sso/img/GoogleWorkspace-basic-SAML_v14_10.png b/doc/user/group/saml_sso/img/GoogleWorkspace-basic-SAML_v14_10.png Binary files differnew file mode 100644 index 00000000000..e002503ddc0 --- /dev/null +++ b/doc/user/group/saml_sso/img/GoogleWorkspace-basic-SAML_v14_10.png diff --git a/doc/user/group/saml_sso/img/GoogleWorkspace-claims_v14_10.png b/doc/user/group/saml_sso/img/GoogleWorkspace-claims_v14_10.png Binary files differnew file mode 100644 index 00000000000..2b827e122a8 --- /dev/null +++ b/doc/user/group/saml_sso/img/GoogleWorkspace-claims_v14_10.png diff --git a/doc/user/group/saml_sso/img/GoogleWorkspace-linkscert_v14_10.png b/doc/user/group/saml_sso/img/GoogleWorkspace-linkscert_v14_10.png Binary files differnew file mode 100644 index 00000000000..8d6c5010670 --- /dev/null +++ b/doc/user/group/saml_sso/img/GoogleWorkspace-linkscert_v14_10.png diff --git a/doc/user/group/saml_sso/img/Okta-GroupAttribute.png b/doc/user/group/saml_sso/img/Okta-GroupAttribute.png Binary files differnew file mode 100644 index 00000000000..54c69053754 --- /dev/null +++ b/doc/user/group/saml_sso/img/Okta-GroupAttribute.png diff --git a/doc/user/group/saml_sso/img/Okta-GroupSAML.png b/doc/user/group/saml_sso/img/Okta-GroupSAML.png Binary files differnew file mode 100644 index 00000000000..7871e4ff82b --- /dev/null +++ b/doc/user/group/saml_sso/img/Okta-GroupSAML.png diff --git a/doc/user/group/saml_sso/img/Okta-SM.png b/doc/user/group/saml_sso/img/Okta-SM.png Binary files differnew file mode 100644 index 00000000000..b335009fed9 --- /dev/null +++ b/doc/user/group/saml_sso/img/Okta-SM.png diff --git a/doc/user/group/saml_sso/img/Okta-advancedsettings.png b/doc/user/group/saml_sso/img/Okta-advancedsettings.png Binary files differnew file mode 100644 index 00000000000..1478dc58ccd --- /dev/null +++ b/doc/user/group/saml_sso/img/Okta-advancedsettings.png diff --git a/doc/user/group/saml_sso/img/Okta-attributes.png b/doc/user/group/saml_sso/img/Okta-attributes.png Binary files differnew file mode 100644 index 00000000000..38af72474d8 --- /dev/null +++ b/doc/user/group/saml_sso/img/Okta-attributes.png diff --git a/doc/user/group/saml_sso/img/Okta-linkscert.png b/doc/user/group/saml_sso/img/Okta-linkscert.png Binary files differnew file mode 100644 index 00000000000..62db5d2b7e3 --- /dev/null +++ b/doc/user/group/saml_sso/img/Okta-linkscert.png diff --git a/doc/user/group/saml_sso/img/OneLogin-SSOsettings.png b/doc/user/group/saml_sso/img/OneLogin-SSOsettings.png Binary files differnew file mode 100644 index 00000000000..58f936d8567 --- /dev/null +++ b/doc/user/group/saml_sso/img/OneLogin-SSOsettings.png diff --git a/doc/user/group/saml_sso/img/OneLogin-app_details.png b/doc/user/group/saml_sso/img/OneLogin-app_details.png Binary files differnew file mode 100644 index 00000000000..77618960897 --- /dev/null +++ b/doc/user/group/saml_sso/img/OneLogin-app_details.png diff --git a/doc/user/group/saml_sso/img/OneLogin-parameters.png b/doc/user/group/saml_sso/img/OneLogin-parameters.png Binary files differnew file mode 100644 index 00000000000..a2fa734152c --- /dev/null +++ b/doc/user/group/saml_sso/img/OneLogin-parameters.png diff --git a/doc/user/group/saml_sso/img/OneLogin-userAdd.png b/doc/user/group/saml_sso/img/OneLogin-userAdd.png Binary files differnew file mode 100644 index 00000000000..54c1ecd2e68 --- /dev/null +++ b/doc/user/group/saml_sso/img/OneLogin-userAdd.png diff --git a/doc/user/group/saml_sso/img/azure_configure_group_claim.png b/doc/user/group/saml_sso/img/azure_configure_group_claim.png Binary files differnew file mode 100644 index 00000000000..9d8c5348273 --- /dev/null +++ b/doc/user/group/saml_sso/img/azure_configure_group_claim.png diff --git a/doc/user/group/saml_sso/img/okta_saml_settings.png b/doc/user/group/saml_sso/img/okta_saml_settings.png Binary files differnew file mode 100644 index 00000000000..9c774b72d66 --- /dev/null +++ b/doc/user/group/saml_sso/img/okta_saml_settings.png diff --git a/doc/user/group/saml_sso/img/okta_setting_username.png b/doc/user/group/saml_sso/img/okta_setting_username.png Binary files differnew file mode 100644 index 00000000000..5f87d14bb8b --- /dev/null +++ b/doc/user/group/saml_sso/img/okta_setting_username.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 80e7a5903fa..25060f8e749 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -99,7 +99,7 @@ After you set up your identity provider to work with GitLab, you must configure  NOTE: -The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-configuring-your-identity-provider) must be in SHA1. When configuring the identity provider, use a secure signature algorithm. +The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-configuring-your-identity-provider) must be in SHA1. When configuring the identity provider (such as [Google Workspace](#google-workspace-setup-notes)), use a secure signature algorithm. ### SSO enforcement @@ -131,6 +131,8 @@ SSO has the following effects when enabled: - Git activity originating from CI/CD jobs do not have the SSO check enforced. - Credentials that are not tied to regular users (for example, project and group access tokens, and deploy keys) do not have the SSO check enforced. - Users must be signed-in through SSO before they can pull images using the [Dependency Proxy](../../packages/dependency_proxy/index.md). +- When the **Enforce SSO-only authentication for Git and Dependency Proxy activity for this group** option is enabled, any API endpoint that involves Git activity is under SSO + enforcement. For example, creating or deleting a branch, commit, or tag. When SSO is enforced, users are not immediately revoked. If the user: @@ -174,7 +176,7 @@ The recommended attributes and claims settings are: If using [Group Sync](#group-sync), customize the name of the group claim to match the required attribute. -See the [troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory) for an example configuration. +See our [example configuration page](example_saml_config.md#azure-active-directory). ### Google Workspace setup notes @@ -191,7 +193,7 @@ with the notes below for consideration. NOTE: Google Workspace displays a SHA256 fingerprint. To retrieve the SHA1 fingerprint required by GitLab for [configuring SAML](#configure-gitlab), download the certificate and calculate -the SHA1 certificate fingerprint. +the SHA1 certificate fingerprint using this sample command: `openssl x509 -noout -fingerprint -sha1 -inform pem -in "GoogleIDPCertificate-domain.com.pem"`. The recommended attributes and claims settings are: @@ -206,7 +208,7 @@ For NameID, the following settings are recommended: When selecting **Verify SAML Configuration** on the GitLab SAML SSO page, disregard the warning recommending setting the NameID format to "persistent". -See the [troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md#google-workspace) for an example configuration. +See our [example configuration page](example_saml_config.md#google-workspace). ### Okta setup notes @@ -445,7 +447,7 @@ To generate a SAML Response: ### Verifying configuration -For convenience, we've included some [example resources](../../../administration/troubleshooting/group_saml_scim.md) used by our Support Team. While they may help you verify the SAML app configuration, they are not guaranteed to reflect the current state of third-party products. +For convenience, we've included some [example resources](../../../user/group/saml_sso/example_saml_config.md) used by our Support Team. While they may help you verify the SAML app configuration, they are not guaranteed to reflect the current state of third-party products. ### Verifying NameID diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 04aa99e08af..7962f171166 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -82,7 +82,7 @@ For a list of required attributes, refer to the [SCIM API documentation](../../. | `userPrincipalName` | `emails[type eq "work"].value` | | | `mailNickname` | `userName` | | -For guidance, you can view [an example configuration in the troubleshooting reference](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory). +For guidance, you can view [an example configuration](example_saml_config.md#azure-active-directory). 1. Below the mapping list select **Show advanced options > Edit attribute list for AppName**. 1. Ensure the `id` is the primary and required field, and `externalId` is also required. @@ -106,7 +106,7 @@ Before you start this section: - Check that you are using Okta [Lifecycle Management](https://www.okta.com/products/lifecycle-management/) product. This product tier is required to use SCIM on Okta. To check which Okta product you are using, check your signed Okta contract, contact your Okta AE, CSM, or Okta support. - Complete the [GitLab configuration](#gitlab-configuration) process. -- Complete the setup for SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/), as described in the [Okta setup notes](index.md#okta-setup-notes). +- Complete the setup for SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/), as described in the [Okta setup notes](index.md#okta-setup-notes). - Check that your Okta SAML setup matches our documentation exactly, especially the NameID configuration. Otherwise, the Okta SCIM app may not work properly. After the above steps are complete: @@ -220,6 +220,8 @@ It is important that this SCIM `id` and SCIM `externalId` are configured to the ### How do I verify user's SAML NameId matches the SCIM externalId +Admins can use the Admin Area to [list SCIM identities for a user](../../admin_area/#user-identities). + Group owners can see the list of users and the `externalId` stored for each user in the group SAML SSO Settings page. A possible alternative is to use the [SCIM API](../../../api/scim.md#get-a-list-of-scim-provisioned-users) to manually retrieve the `externalId` we have stored for users, also called the `external_uid` or `NameId`. diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index 9e8fc120731..c3098bb56c2 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -154,5 +154,8 @@ to groups instead of projects. Bot users for groups: - Do not count as licensed seats. - Can have a maximum role of Owner for a group. For more information, see [Create a group access token](../../../api/group_access_tokens.md#create-a-group-access-token). +- The username is set to `group_{project_id}_bot` for the first access token. For example, `project_123_bot`. +- The email is set to `group{group_id}_bot@noreply.{Gitlab.config.gitlab.host}`. For example, `group123_bot@noreply.example.com`. +- All other properties are similar to [bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects) For more information, see [Bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects). diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index bf4e13779fd..12434de5efc 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -47,6 +47,28 @@ graph TD end ``` +## View subgroups of a group + +Prerequisite: + +- To view private nested subgroups, you must be a direct or inherited member of +the private subgroup. + +To view the subgroups of a group: + +1. On the top bar, select **Menu > Groups** and find your group. +1. Select the **Subgroups and projects** tab. +1. To view a nested subgroup, expand a subgroup in the hierarchy list. + +### Private subgroups in public parent groups + +In the hierarchy list, public groups with a private subgroup have an expand option (**{chevron-down}**) +for all users that indicate there is a subgroup. When users who are not direct or inherited members of +the private subgroup select expand (**{chevron-down}**), the nested subgroup does not display. + +If you prefer to keep information about the presence of nested subgroups private, we advise that you only +add private subgroups to private parent groups. + ## Create a subgroup Prerequisites: @@ -102,7 +124,7 @@ Subgroup members can: 1. Be [direct members](../../project/members/index.md#add-users-to-a-project) of the subgroup. 1. [Inherit membership](../../project/members/index.md#inherited-membership) of the subgroup from the subgroup's parent group. -1. Be a member of a group that was [shared with the subgroup's top-level group](../index.md#share-a-group-with-another-group). +1. Be a member of a group that was [shared with the subgroup's top-level group](../manage.md#share-a-group-with-another-group). ```mermaid flowchart RL @@ -161,7 +183,7 @@ In the screenshot above: - Administrator has the Owner role on group _Four_ and is a member of all subgroups. For that reason, as with User 3, the **Source** column indicates they are a direct member. -Members can be [filtered by inherited or direct membership](../index.md#filter-a-group). +Members can be [filtered by inherited or direct membership](../manage.md#filter-a-group). ### Override ancestor group membership diff --git a/doc/user/img/completed_tasks_v13_3.png b/doc/user/img/completed_tasks_v13_3.png Binary files differdeleted file mode 100644 index b12d95f0a23..00000000000 --- a/doc/user/img/completed_tasks_v13_3.png +++ /dev/null diff --git a/doc/user/img/completed_tasks_v15_3.png b/doc/user/img/completed_tasks_v15_3.png Binary files differnew file mode 100644 index 00000000000..c1619e70839 --- /dev/null +++ b/doc/user/img/completed_tasks_v15_3.png diff --git a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md index fad75ca6cab..ecf93958b1e 100644 --- a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md @@ -90,7 +90,7 @@ Refer to the [Civo Terraform provider](https://registry.terraform.io/providers/c After configuring your project, manually trigger the provisioning of your cluster. In GitLab: 1. On the left sidebar, go to **CI/CD > Pipelines**. -1. Next to **Play** (**{play}**), select the dropdown icon (**{angle-down}**). +1. Next to **Play** (**{play}**), select the dropdown icon (**{chevron-lg-down}**). 1. Select **Deploy** to manually trigger the deployment job. When the pipeline finishes successfully, you can see your new cluster: diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md index 798e02ab9b4..2f5967bd7ee 100644 --- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -122,12 +122,13 @@ To remove all resources: stages: - init - validate + - test - build - deploy - cleanup destroy: - extends: .destroy + extends: .terraform:destroy needs: [] ``` diff --git a/doc/user/infrastructure/clusters/deploy/inventory_object.md b/doc/user/infrastructure/clusters/deploy/inventory_object.md index d184d969ace..fc3b86776f0 100644 --- a/doc/user/infrastructure/clusters/deploy/inventory_object.md +++ b/doc/user/infrastructure/clusters/deploy/inventory_object.md @@ -4,9 +4,10 @@ group: Configure 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 --- -# Tracking cluster resources managed by GitLab **(PREMIUM)** +# Tracking cluster resources managed by GitLab **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/346567) from GitLab Premium to GitLab Free in 15.3. GitLab uses an inventory object to track the resources you deploy to your cluster. The inventory object is a `ConfigMap` that contains a list of controlled objects. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md index 5ad1fb81a39..51fd626ce0f 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md @@ -18,19 +18,28 @@ uncomment this line from your `helmfile.yaml`: - path: applications/cert-manager/helmfile.yaml ``` +And update the `applications/cert-manager/helmfile.yaml` with a valid email address. + +```yaml + values: + - letsEncryptClusterIssuer: + # + # IMPORTANT: This value MUST be set to a valid email. + # + email: example@example.com +``` + NOTE: -If your Kubernetes version is earlier than 1.20 and you are [migrating from GitLab -Managed Apps to a cluster management -project](../../../../clusters/migrating_from_gma_to_project_template.md), then -you can instead use `- path: applications/cert-manager-legacy/helmfile.yaml` to +If your Kubernetes version is earlier than 1.20 and you are +[migrating from GitLab Managed Apps to a cluster management project](../../../../clusters/migrating_from_gma_to_project_template.md), +then you can instead use `- path: applications/cert-manager-legacy/helmfile.yaml` to take over an existing release of cert-manager v0.10. cert-manager: - Is installed by default into the `gitlab-managed-apps` namespace of your cluster. - Includes a - [Let's Encrypt - `ClusterIssuer`](https://cert-manager.io/docs/configuration/acme/) enabled by + [Let's Encrypt `ClusterIssuer`](https://cert-manager.io/docs/configuration/acme/) enabled by default. In the `certmanager-issuer` release, the issuer requires a valid email address for `letsEncryptClusterIssuer.email`. Let's Encrypt uses this email address to contact you about expiring certificates and issues related to your account. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md b/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md index 383e857bb20..64d325dedc6 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md @@ -1,27 +1,11 @@ --- -stage: Monitor -group: Respond -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: '../../../../../operations/metrics/index.md' +remove_date: '2022-11-03' --- -# Install Prometheus with a cluster management project **(FREE)** +This document was moved to [another location](../../../../../operations/metrics/index.md). -> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. - -[Prometheus](https://prometheus.io/docs/introduction/overview/) is an -open-source monitoring and alerting system for supervising your -deployed applications. - -Assuming you already have a project created from a -[management project template](../../../../../user/clusters/management_project_template.md), to install Prometheus you should -uncomment this line from your `helmfile.yaml`: - -```yaml - - path: applications/prometheus/helmfile.yaml -``` - -You can customize the installation of Prometheus by updating the -`applications/prometheus/values.yaml` file in your cluster -management project. Refer to the -[Configuration section](https://github.com/helm/charts/tree/master/stable/prometheus#configuration) -of the Prometheus chart's README for the available configuration options. +<!-- This redirect file can be deleted after <2022-11-03>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md b/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md index d2d314b649e..f42e9c83120 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md @@ -1,70 +1,11 @@ --- -stage: Monitor -group: Respond -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: '../../../../../operations/error_tracking.md' +remove_date: '2022-11-03' --- -# Install Sentry with a cluster management project **(FREE)** +This document was moved to [another location](../../../../../operations/error_tracking.md). -> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. - -The Sentry Helm chart [recommends](https://github.com/helm/charts/blob/f6e5784f265dd459c5a77430185d0302ed372665/stable/sentry/values.yaml#L284-L285) -at least 3 GB of available RAM for database migrations. - -Assuming you already have a project created from a -[management project template](../../../../../user/clusters/management_project_template.md), to install Sentry you should -uncomment this line from your `helmfile.yaml`: - -```yaml - - path: applications/sentry/helmfile.yaml -``` - -Sentry is installed by default into the `gitlab-managed-apps` namespace -of your cluster. - -You can customize the installation of Sentry by defining -`applications/sentry/values.yaml` file in your cluster -management project. Refer to the -[chart](https://github.com/helm/charts/tree/master/stable/sentry) -for the available configuration options. - -We recommend you pay close attention to the following configuration options: - -- `email`. Needed to invite users to your Sentry instance and to send error emails. -- `user`. Where you can set the login credentials for the default administrator user. -- `postgresql`. For a PostgreSQL password that can be used when running future updates. - -When upgrading, it's important to provide the existing PostgreSQL password (given -using the `postgresql.postgresqlPassword` key) to avoid authentication errors. -Read the [PostgreSQL chart documentation](https://github.com/helm/charts/tree/master/stable/postgresql#upgrade) -for more information. - -Here is an example configuration for Sentry: - -```yaml -# Admin user to create -user: - # Indicated to create the admin user or not, - # Default is true as the initial installation. - create: true - email: "<your email>" - password: "<your password>" - -email: - from_address: "<your from email>" - host: smtp - port: 25 - use_tls: false - user: "<your email username>" - password: "<your email password>" - enable_replies: false - -ingress: - enabled: true - hostname: "<sentry.example.com>" - -# Needs to be here between runs. -# See https://github.com/helm/charts/tree/master/stable/postgresql#upgrade for more info -postgresql: - postgresqlPassword: example-postgresql-password -``` +<!-- This redirect file can be deleted after <2022-11-03>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md index 06e67b78c91..31a22a240d9 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md @@ -35,7 +35,7 @@ Vault application causes downtime. To optimally use Vault in a production environment, it's ideal to have a good understanding of the internals of Vault and how to configure it. This can be done by reading -the [Vault Configuration guide](../../../../../ci/secrets/#configure-your-vault-server), +the [Vault Configuration guide](../../../../../ci/secrets/index.md#configure-your-vault-server), the [Vault documentation](https://www.vaultproject.io/docs/internals) and the Vault Helm chart [`values.yaml` file](https://github.com/hashicorp/vault-helm/blob/v0.3.3/values.yaml). diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 24203e8d922..4e78e0bbed5 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -68,17 +68,34 @@ To configure GitLab CI/CD as a backend: } ``` -1. In the root directory of your project repository, create a `.gitlab-ci.yml` file. Use - [this file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) - to populate it. - +1. In the root directory of your project repository, create a `.gitlab-ci.yml` file. Use the + [`Terraform.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) + template to populate it. 1. Push your project to GitLab. This action triggers a pipeline, which runs the `gitlab-terraform init`, `gitlab-terraform validate`, and `gitlab-terraform plan` commands. -1. Trigger the manual `terraform apply` job from the previous pipeline to provision the defined infrastructure. +1. Trigger the manual `deploy` job from the previous pipeline, which runs `gitlab-terraform apply` command, to provision the defined infrastructure. The output from the above `terraform` commands should be viewable in the job logs. +The `gitlab-terraform` CLI is a wrapper around the `terraform` CLI. You can [view the source code of `gitlab-terraform`](https://gitlab.com/gitlab-org/terraform-images/-/blob/master/src/bin/gitlab-terraform.sh) if you're interested. + +If you prefer to call the `terraform` commands explicitly, you can override +the template, and instead, use it as reference for what you can achieve. + +### Customizing your Terraform environment variables + +When you use the `Terraform.gitlab-ci.yml` template, you can use [Terraform HTTP configuration variables](https://www.terraform.io/language/settings/backends/http#configuration-variables) when you define your CI/CD jobs. + +To customize your `terraform init` and override the Terraform configuration, +use environment variables instead of the `terraform init -backend-config=...` approach. +When you use `-backend-config`, the configuration is: + +- Cached in the output of the `terraform plan` command. +- Usually passed forward to the `terraform apply` command. + +This configuration can lead to problems like [being unable to lock Terraform state files in CI jobs](troubleshooting.md#unable-to-lock-terraform-state-files-in-ci-jobs-for-terraform-apply-using-a-plan-created-in-a-previous-job). + ## Access the state from your local machine You can access the GitLab-managed Terraform state from your local machine. @@ -109,66 +126,6 @@ You should use a local terminal to run the commands needed for migrating to GitL The following example demonstrates how to change the state name. The same workflow is needed to migrate to GitLab-managed Terraform state from a different state storage backend. -## Use your GitLab backend as a remote data source - -You can use a GitLab-managed Terraform state backend as a -[Terraform data source](https://www.terraform.io/language/state/remote-state-data). - -1. In your `main.tf` or other relevant file, declare these variables. Leave the values empty. - - ```hcl - variable "example_remote_state_address" { - type = string - description = "Gitlab remote state file address" - } - - variable "example_username" { - type = string - description = "Gitlab username to query remote state" - } - - variable "example_access_token" { - type = string - description = "GitLab access token to query remote state" - } - ``` - -1. To override the values from the previous step, create a file named `example.auto.tfvars`. This file should **not** be versioned in your project repository. - - ```plaintext - example_remote_state_address = "https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>" - example_username = "<GitLab username>" - example_access_token = "<GitLab Personal Access Token>" - ``` - -1. In a `.tf` file, define the data source by using [Terraform input variables](https://www.terraform.io/language/values/variables): - - ```hcl - data "terraform_remote_state" "example" { - backend = "http" - - config = { - address = var.example_remote_state_address - username = var.example_username - password = var.example_access_token - } - } - ``` - - - **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 value is your GitLab username. If you are using GitLab CI/CD, this value is `'gitlab-ci-token'`. - - **password**: The password to authenticate with the data source. If you are using a Personal Access Token for - authentication, this value is the token value (the token must have the **API** scope). - If you are using GitLab CI/CD, this value is the contents of the `${CI_JOB_TOKEN}` CI/CD variable. - -Outputs from the data source can now be referenced in your Terraform resources -using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. - -To read the Terraform state in the target project, you need at least the Developer role. - ### Set up the initial backend ```shell @@ -264,6 +221,66 @@ commands will detect it and remind you to do so if necessary. If you type `yes`, it copies your state from the old location to the new location. You can then go back to running it in GitLab CI/CD. +## Use your GitLab backend as a remote data source + +You can use a GitLab-managed Terraform state backend as a +[Terraform data source](https://www.terraform.io/language/state/remote-state-data). + +1. In your `main.tf` or other relevant file, declare these variables. Leave the values empty. + + ```hcl + variable "example_remote_state_address" { + type = string + description = "Gitlab remote state file address" + } + + variable "example_username" { + type = string + description = "Gitlab username to query remote state" + } + + variable "example_access_token" { + type = string + description = "GitLab access token to query remote state" + } + ``` + +1. To override the values from the previous step, create a file named `example.auto.tfvars`. This file should **not** be versioned in your project repository. + + ```plaintext + example_remote_state_address = "https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>" + example_username = "<GitLab username>" + example_access_token = "<GitLab Personal Access Token>" + ``` + +1. In a `.tf` file, define the data source by using [Terraform input variables](https://www.terraform.io/language/values/variables): + + ```hcl + data "terraform_remote_state" "example" { + backend = "http" + + config = { + address = var.example_remote_state_address + username = var.example_username + password = var.example_access_token + } + } + ``` + + - **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 value is your GitLab username. If you are using GitLab CI/CD, this value is `'gitlab-ci-token'`. + - **password**: The password to authenticate with the data source. If you are using a Personal Access Token for + authentication, this value is the token value (the token must have the **API** scope). + If you are using GitLab CI/CD, this value is the contents of the `${CI_JOB_TOKEN}` CI/CD variable. + +Outputs from the data source can now be referenced in your Terraform resources +using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. + +To read the Terraform state in the target project, you need at least the Developer role. + ## Manage Terraform state files > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8. diff --git a/doc/user/infrastructure/iac/troubleshooting.md b/doc/user/infrastructure/iac/troubleshooting.md index 5817337223f..e187fe54136 100644 --- a/doc/user/infrastructure/iac/troubleshooting.md +++ b/doc/user/infrastructure/iac/troubleshooting.md @@ -97,6 +97,8 @@ As a result, to create a plan and later use the same plan in another CI job, you `Error: Error acquiring the state lock` errors when using `-backend-config=password=$CI_JOB_TOKEN`. This happens because the value of `$CI_JOB_TOKEN` is only valid for the duration of the current job. +Another possible error message for the same problem could be: `Error: Error loading state: HTTP remote state endpoint requires auth`. + As a workaround, use [http backend configuration variables](https://www.terraform.io/docs/language/settings/backends/http.html#configuration-variables) in your CI job, which is what happens behind the scenes when following the [Get started using GitLab CI](terraform_state.md#initialize-a-terraform-state-as-a-backend-by-using-gitlab-cicd) instructions. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index b1e6fcb2f4e..6a524fe206a 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -190,8 +190,8 @@ end #### PlantUML -To make PlantUML available in GitLab, a GitLab administrator must enable it. For more information, see the -[PlantUML & GitLab](../administration/integration/plantuml.md) page. +PlantUML integration is enabled on GitLab.com. To make PlantUML available in self-managed +installation of GitLab, a GitLab administrator [must enable it](../administration/integration/plantuml.md). #### Kroki @@ -376,6 +376,8 @@ the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activati ### Task lists +> Inapplicable checkboxes [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85982) in GitLab 15.3. + [View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#task-lists). You can add task lists anywhere Markdown is supported. @@ -384,22 +386,28 @@ You can add task lists anywhere Markdown is supported. - In all other places, you cannot select the boxes. You must edit the Markdown manually by adding or removing an `x` in the brackets. +Besides complete and incomplete, tasks can also be **inapplicable**. Selecting an inapplicable checkbox +in an issue, merge request, or comment has no effect. + To create a task list, follow the format of an ordered or unordered list: ```markdown - [x] Completed task +- [~] Inapplicable task - [ ] Incomplete task - - [ ] Sub-task 1 - - [x] Sub-task 2 + - [x] Sub-task 1 + - [~] Sub-task 2 - [ ] Sub-task 3 1. [x] Completed task +1. [~] Inapplicable task 1. [ ] Incomplete task - 1. [ ] Sub-task 1 - 1. [x] Sub-task 2 + 1. [x] Sub-task 1 + 1. [~] Sub-task 2 + 1. [ ] Sub-task 3 ``` - + ### Table of contents @@ -1398,6 +1406,42 @@ For example: 1. Another item +--- + +Ordered lists that are the first sub-item of an unordered list item must have a preceding blank line if they don't start with `1.`. + +**Good** + +```markdown +- Unordered list item + + 5. First ordered list item +``` + +**Bad** + +```markdown +- Unordered list item + 5. First ordered list item +``` + +--- + +CommonMark ignores blank lines between ordered and unordered list items, and considers them part of a single list. These are rendered as a +_[loose](https://spec.commonmark.org/0.30/#loose)_ list. Each list item is enclosed in a paragraph tag and, therefore, has paragraph spacing and margins. +This makes the list look like there is extra spacing between each item. + +For example: + +```markdown +- First list item +- Second list item + +- A different list +``` + +CommonMark ignores the blank line and renders this as one list with paragraph spacing. + ### Superscripts / Subscripts CommonMark and GitLab Flavored Markdown don't support the Redcarpet superscript syntax ( `x^2` ). diff --git a/doc/user/namespace/index.md b/doc/user/namespace/index.md new file mode 100644 index 00000000000..9ffc65a4e8e --- /dev/null +++ b/doc/user/namespace/index.md @@ -0,0 +1,21 @@ +--- +stage: Manage +group: Workspace +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 +--- + +# Namespaces + +In GitLab, a *namespace* organizes related projects together. +GitLab has two types of namespaces: + +- A *personal* namespace, which is based on your username. Projects under a personal namespace must be configured one at a time. +- A *group* or *subgroup* namespace. In these namespaces, you can manage multiple projects at once. + +To determine whether you're viewing a group or personal namespace, you can view the URL. For example: + +| Namespace for | URL | Namespace | +| ------------- | --- | --------- | +| A user named `alex`. | `https://gitlab.example.com/alex` | `alex` | +| A group named `alex-team`. | `https://gitlab.example.com/alex-team` | `alex-team` | +| A group named `alex-team` with a subgroup named `marketing`. | `https://gitlab.example.com/alex-team/marketing` | `alex-team/marketing` | diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 901fb740717..4fc55d18253 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -44,7 +44,7 @@ a group's namespace, rather than a user's namespace. Composer packages 1. Run [`composer init`](https://getcomposer.org/doc/03-cli.md#init) and answer the prompts. - For namespace, enter your unique [namespace](../../../user/group/index.md#namespaces), like your GitLab username or group name. + For namespace, enter your unique [namespace](../../../user/namespace/index.md), like your GitLab username or group name. A file called `composer.json` is created: diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index d0c771ecc41..a203de2ed2c 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -555,6 +555,12 @@ this setting. However, disabling the Container Registry disables all Container R ## Troubleshooting the GitLab Container Registry +## Migrating OCI container images to GitLab Container Registry + +Migrating built container images to the GitLab registry is not a current feature. However, an [epic](https://gitlab.com/groups/gitlab-org/-/epics/5210) is open to track the work on this feature. + +Some third-party tools can help migrate container images, for example, [skopeo](https://github.com/containers/skopeo), which can [copy container images](https://github.com/containers/skopeo#copying-images) between various storage mechanisms. You can use skopeo to copy from container registries, container storage backends, local directories, and local OCI-layout directories to the GitLab Container Registry. + ### Docker connection error A Docker connection error can occur when there are special characters in either the group, @@ -563,7 +569,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#change-a-groups-path), +To get around this, you can [change the group path](../../group/manage.md#change-a-groups-path), [change the project path](../../project/settings/index.md#rename-a-repository) or change the branch name. diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md index 3e41a260854..788e57b6410 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -16,9 +16,26 @@ to automatically manage your container registry usage. ## Check Container Registry Storage Use -The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages, -which doesn't include the Container Registry. To track work on this, see the epic -[Storage management for the Container Registry](https://gitlab.com/groups/gitlab-org/-/epics/7226). +The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages. +This page includes the Container Registry usage but is currently only available on GitLab.com. +Measuring usage is only possible on the new version of the GitLab Container Registry backed by a +metadata database. We are completing the [upgrade and migration of the GitLab.com Container Registry](https://gitlab.com/groups/gitlab-org/-/epics/5523) +first and only then will work on [making this available to self-managed installs](https://gitlab.com/groups/gitlab-org/-/epics/5521). + +Image layers stored in the Container Registry are deduplicated at the root namespace level. +Therefore, if you tag the same 500MB image twice (either in the same repository or across distinct +repositories under the same root namespace), it will only count towards the root namespace usage +once. Similarly, if a given image layer is shared across multiple images, be those under the same +container repository, project, group, or across different ones, that layer will count only once +towards the root namespace usage. + +Only layers that are referenced by tagged images are accounted for. Untagged images and any layers +referenced exclusively by them are subject to [online garbage collection](index.md#delete-images) +and automatically deleted after 24 hours if they remain unreferenced during that period. + +Image layers are stored on the storage backend in the original (usually compressed) format. This +means that the measured size for any given image layer should match the size displayed on the +corresponding [image manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md#example-image-manifest). ## Cleanup policy diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 4770057e4ea..ea9435de12a 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -316,6 +316,28 @@ services: alias: docker ``` +### Issues when authenticating to the Dependency Proxy from CI/CD jobs + +GitLab Runner will automatically authenticate to the Dependency Proxy. However, the underlying Docker engine is still subject to its [authorization resolving process](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/advanced-configuration.md#precedence-of-docker-authorization-resolving). + +Misconfigurations in the authentication mechanism may cause `HTTP Basic: Access denied` and `403: Access forbidden` errors. + +You can use the job logs to view the authentication mechanism used to authenticate against the Dependency Proxy: + +```plaintext +Authenticating with credentials from $DOCKER_AUTH_CONFIG +``` + +```plaintext +Authenticating with credentials from /root/.docker/config.json +``` + +```plaintext +Authenticating with credentials from job payload (GitLab Registry) +``` + +Make sure you are using the expected authentication mechanism. + ### "Not Found" error when pulling image Docker errors similar to the following may indicate that the user running the build job doesn't have diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 8d5fc73ad4e..d4acb14b9ca 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -73,6 +73,7 @@ Example request with attribute `select = package_file`: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --user "<username>:<Project 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?select=package_file" ``` diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index 07e853fa18c..f64a269938f 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -71,7 +71,7 @@ Once built, a chart can be uploaded to the desired channel with `curl` or `helm ### Release channels -You can publish Helm charts to channels in GitLab. Channels are a method you can use to differentiate Helm chart repositories. +You can publish Helm charts to channels in GitLab. Channels are a method you can use to differentiate Helm chart repositories. For example, you can use `stable` and `devel` as channels to allow users to add the `stable` repo while `devel` charts are isolated. ## Use CI/CD to publish a Helm package @@ -129,7 +129,7 @@ See [Using Helm](https://helm.sh/docs/intro/using_helm/) for more information. ### The chart is not visible in the Package Registry after uploading -Check the [Sidekiq log](../../../administration/logs.md#sidekiqlog) +Check the [Sidekiq log](../../../administration/logs/index.md#sidekiqlog) for any related errors. If you see `Validation failed: Version is invalid`, it means that the version in your `Chart.yaml` file does not follow [Helm Chart versioning specifications](https://helm.sh/docs/topics/charts/#charts-and-versioning). To fix the error, use the correct version syntax and upload the chart again. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 7ea3c1aa0c8..28de06b2d8a 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -585,7 +585,7 @@ NPM_TOKEN=<your_token> npm install If you get this error, ensure that: - The Package Registry is enabled in your project settings. Although the Package Registry is enabled - by default, it's possible to [disable it](../package_registry/#disable-the-package-registry). + by default, it's possible to [disable it](../package_registry/index.md#disable-the-package-registry). - Your token is not expired and has appropriate permissions. - A package with the same name or version doesn't already exist within the given scope. - The scoped packages URL includes a trailing slash: @@ -634,7 +634,7 @@ This might be accompanied by another error: This is usually a permissions issue with either: - `'packages_storage_path'` default `/var/opt/gitlab/gitlab-rails/shared/packages/`. -- The remote bucket if [object storage](../../../administration/packages/#using-object-storage) +- The remote bucket if [object storage](../../../administration/packages/index.md#using-object-storage) is used. In the latter case, ensure the bucket exists and GitLab has write access to it. diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index d68c7218ca5..7748780d0e4 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -60,11 +60,8 @@ For most package types, the following credential types are valid: allows access to packages in the project running the job for the users running the pipeline. Access to other external projects can be configured. - NOTE: - There's an open issue, - [GitLab-#333444](https://gitlab.com/gitlab-org/gitlab/-/issues/333444), - which prevents you from using a job token with internal projects. This bug only impacts self-managed - GitLab instances. +NOTE: +If you have not activated the "Packages" feature for your project at **Settings > General > Project features**, you will receive a 403 Forbidden response. ## Use GitLab CI/CD to build packages diff --git a/doc/user/packages/package_registry/reduce_package_registry_storage.md b/doc/user/packages/package_registry/reduce_package_registry_storage.md index 4a03bd9e8a0..cd7dd062f60 100644 --- a/doc/user/packages/package_registry/reduce_package_registry_storage.md +++ b/doc/user/packages/package_registry/reduce_package_registry_storage.md @@ -53,7 +53,7 @@ The package files are permanently deleted. ## Cleanup policy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346153) in GitLab 15.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346153) in GitLab 15.2. Depending on the number of packages to remove, the process of manually deleting the packages can take a long time to finish. A cleanup policy defines a set of rules that, applied to a project, defines which package files you can automatically delete. diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 2668b8b35ac..436c55f9ee0 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -101,7 +101,7 @@ module "<module>" { } ``` -Where `<namespace>` is the [namespace](../../../user/group/index.md#namespaces) of the Terraform module registry. +Where `<namespace>` is the [namespace](../../../user/namespace/index.md) of the Terraform module registry. ## Publish a Terraform module by using CI/CD @@ -125,7 +125,7 @@ upload: script: - TERRAFORM_MODULE_NAME=$(echo "${TERRAFORM_MODULE_NAME}" | tr " _" -) # module-name must not have spaces or underscores, so translate them to hyphens - tar -vczf ${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz -C ${TERRAFORM_MODULE_DIR} --exclude=./.git . - - 'curl --location --header "JOB-TOKEN: ${CI_JOB_TOKEN}" + - 'curl --location --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file ${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/terraform/modules/${TERRAFORM_MODULE_NAME}/${TERRAFORM_MODULE_SYSTEM}/${TERRAFORM_MODULE_VERSION}/file' rules: diff --git a/doc/user/permissions.md b/doc/user/permissions.md index b01bfbef3aa..c89dd3f65f7 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -39,10 +39,10 @@ usernames. A GitLab administrator can configure the GitLab instance to A user's role determines what permissions they have on a project. The Owner role provides all permissions but is available only: -- For group owners. The role is inherited for a group's projects. +- For group and project Owners. In GitLab 14.8 and earlier, the role is inherited for a group's projects. - For Administrators. -Personal [namespace](group/index.md#namespaces) owners: +Personal [namespace](namespace/index.md) owners: - Are displayed as having the Maintainer role on projects in the namespace, but have the same permissions as a user with the Owner role. - In GitLab 14.9 and later, for new projects in the namespace, are displayed as having the Owner role. @@ -95,6 +95,7 @@ The following table lists project permissions available for each role: | [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [related issues](project/issues/related_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Set [weight](project/issues/issue_weight.md) | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | +| [Issues]](project/issues/index.md):<br>Set [parent epic](group/epics/manage_epics.md#add-an-existing-issue-to-an-epic) | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Close / reopen (*19*) | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | @@ -214,18 +215,18 @@ The following table lists project permissions available for each role: [GitLab.com visibility settings](gitlab_com/index.md#visibility-settings). 2. Guest users can only view the [confidential issues](project/issues/confidential_issues.md) they created themselves or are assigned to. 3. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md). -4. If the [branch is protected](project/protected_branches.md), this depends on the access Developers and Maintainers are given. +4. If the [branch is protected](project/protected_branches.md), this depends on the access given to Developers and Maintainers. 5. 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 commits and release evidence](project/releases/index.md#view-a-release-and-download-assets). 6. Actions are limited only to records owned (referenced) by user. -7. 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. +7. When [Share Group Lock](group/access_and_permissions.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. 8. For information on eligible approvers for merge requests, see [Eligible approvers](project/merge_requests/approvals/rules.md#eligible-approvers). 9. Applies only to comments on [Design Management](project/issues/design_management.md) designs. 10. Users can only view events based on their individual actions. 11. Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). -12. If the [tag is protected](#release-permissions-with-protected-tags), this depends on the access Developers and Maintainers are given. -13. A Maintainer can't change project features visibility level if +12. If the [tag is protected](#release-permissions-with-protected-tags), this depends on the access given to Developers and Maintainers. +13. A Maintainer or Owner can't change project features visibility level if [project visibility](public_access.md) is set to private. 14. Attached design files are moved together with the issue even if the user doesn't have the Developer role. @@ -333,10 +334,9 @@ which visibility level you select on project settings. ### Protected branches Additional restrictions can be applied on a per-branch basis with [protected branches](project/protected_branches.md). -Additionally, you can customize permissions to allow or prevent project -Maintainers and Developers from pushing to a protected branch. Read through the documentation on -[protected branches](project/protected_branches.md) -to learn more. +Additionally, you can customize permissions to allow or prevent project Developers or Maintainers +from pushing to a protected branch. Read through the documentation on +[protected branches](project/protected_branches.md) to learn more. ### Value stream analytics permissions @@ -412,7 +412,7 @@ The following table lists group permissions available for each role: | Delete [group wiki](project/wiki/group.md) pages | | | ✓ | ✓ | ✓ | | Edit [epic](group/epics/index.md) comments (posted by any user) | | | | ✓ (2) | ✓ (2) | | List group deploy tokens | | | | ✓ | ✓ | -| Manage [group push rules](group/index.md#group-push-rules) | | | | ✓ | ✓ | +| Manage [group push rules](group/access_and_permissions.md#group-push-rules) | | | | ✓ | ✓ | | View/manage group-level Kubernetes cluster | | | | ✓ | ✓ | | Create and manage compliance frameworks | | | | | ✓ | | Create/Delete group deploy tokens | | | | | ✓ | @@ -439,9 +439,9 @@ The following table lists group permissions available for each role: 2. Introduced in GitLab 12.2. 3. Default project creation role can be changed at: - The [instance level](admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). - - The [group level](group/index.md#specify-who-can-add-projects-to-a-group). + - The [group level](group/manage.md#specify-who-can-add-projects-to-a-group). 4. Does not apply to subgroups. -5. 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". +5. Developers can push commits to the default branch of a new project only if the [default branch protection](group/manage.md#change-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". 6. In addition, if your group is public or internal, all users who can see the group can also see group wiki pages. 7. Users can only view events based on their individual actions. @@ -600,7 +600,7 @@ for more information. ## LDAP users permissions LDAP user permissions can be manually overridden by an administrator. -Read through the documentation on [LDAP users permissions](group/index.md#manage-group-memberships-via-ldap) to learn more. +Read through the documentation on [LDAP users permissions](group/access_and_permissions.md#manage-group-memberships-via-ldap) to learn more. ## Project aliases diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 3f5554b80ac..5ec29814e06 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -78,7 +78,7 @@ in users not being deleted, and the following error generated: ERROR: null value in column "user_id" violates not-null constraint ``` -The error can be found in the [PostgreSQL log](../../../administration/logs.md#postgresql-logs) and +The error can be found in the [PostgreSQL log](../../../administration/logs/index.md#postgresql-logs) and in the **Retries** section of the [background jobs view](../../admin_area/index.md#background-jobs) in the Admin Area. If the user being deleted used the [iterations](../../group/iterations/index.md) feature, such diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 4563cfe5648..3af033c7130 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -59,15 +59,12 @@ To enable 2FA with a one-time password: 1. Select **Enable Two-factor Authentication**. 1. **On your device (usually your phone):** 1. Install a compatible application. For example: - - [Aegis](https://getaegis.app/) - - [Raivo OTP](https://apps.apple.com/us/app/raivo-otp/id1459042137#platform=iphone) - - [Authy](https://authy.com/) - - [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app) - - [LastPass Authenticator](https://lastpass.com/auth/) - - [Authenticator](https://mattrubin.me/authenticator/) - - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en) - - [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app) - - [SailOTP](https://openrepos.net/content/seiichiro0185/sailotp) + - Cloud-based (recommended because you can restore access if you lose the hardware device): + - [Authy](https://authy.com/) + - [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app) + - Other: + - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en) + - [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app) 1. In the application, add a new entry in one of two ways: - Scan the code displayed by GitLab with your device's camera to add the entry automatically. - Enter the details provided to add the entry manually. @@ -358,8 +355,7 @@ After you use a recovery code, you cannot re-use it. You can still use the other ### Generate new recovery codes using SSH -Users often forget to save their recovery codes when enabling 2FA. If you added an SSH key to your -GitLab account, you can generate a new set of recovery codes with SSH: +If you forget to save your recovery codes when enabling 2FA, and you added an SSH key to your GitLab account, you can generate a new set of recovery codes with SSH: 1. In a terminal, run: @@ -403,10 +399,9 @@ After signing in, immediately set up 2FA with a new device. ### Have two-factor authentication disabled on your account **(PREMIUM SAAS)** -If other methods are unavailable, submit a [support ticket](https://support.gitlab.com/hc/en-us/requests/new) to request +If other methods are unavailable, have a GitLab support contact submit a [support ticket](https://support.gitlab.com) to request a GitLab global administrator disable 2FA for your account: -- Only the owner of the account can make this request. - This service is only available for accounts that have a GitLab.com subscription. For more information, see our [blog post](https://about.gitlab.com/blog/2020/08/04/gitlab-support-no-longer-processing-mfa-resets-for-free-users/). - Disabling this setting temporarily leaves your account in a less secure state. You should sign in and re-enable two-factor diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index bf696310158..4c859d98004 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -36,11 +36,11 @@ To change your password: 1. In the **New password** and **Password confirmation** text box, enter your new password. 1. Select **Save password**. -If you don't know your current password, select the **I forgot my password** link. +If you don't know your current password, select the **I forgot my password** link. A password reset email is sent to the account's **primary** email address. ## Change your username -Your username has a unique [namespace](../group/index.md#namespaces), +Your username has a unique [namespace](../namespace/index.md), which is updated when you change your username. Before you change your username, read about [how redirects behave](../project/repository/index.md#what-happens-when-a-repository-path-changes). If you do not want to update the namespace, you can create a new user or group and transfer projects to it instead. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 3eda363d108..0245f0615e0 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -7,9 +7,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Notification emails **(FREE)** -> Enhanced email styling [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78604) in GitLab 14.9 [with a feature flag](../../administration/feature_flags.md) named `enhanced_notify_css`. Disabled by default. -> Enhanced email styling [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/355907) in GitLab 14.9. -> Enhanced email styling [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/355907) in GitLab 15.0. +> - Enhanced email styling [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78604) in GitLab 14.9 [with a feature flag](../../administration/feature_flags.md) named `enhanced_notify_css`. Disabled by default. +> - Enhanced email styling [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/355907) in GitLab 14.9. +> - Enhanced email styling [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/355907) in GitLab 15.0. Stay informed about what's happening in GitLab with email notifications. You can receive updates about activity in issues, merge requests, epics, and designs. diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index a76517a7341..f8494116655 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -38,9 +38,9 @@ want to make sure the performance stays the same, or improves. Developers need to be careful when using canaries with user-facing changes, because by default, requests from the same user are randomly distributed between canary and non-canary pods, which could result in confusion or even errors. If needed, you -may want to consider [setting `service.spec.sessionAffinity` to `ClientIP` in -your Kubernetes service definitions](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies), but that is beyond the scope of -this document. +may want to consider +[setting `service.spec.sessionAffinity` to `ClientIP` in your Kubernetes service definitions](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies), +but that is beyond the scope of this document. ## Advanced traffic control with Canary Ingress diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 2e1c8766ae3..bfaf9aab7b7 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -37,7 +37,7 @@ Prerequisites: set up with access. - Kubernetes Engine API and related services enabled. It should work immediately but may take up to 10 minutes after you create a project. For more information see the - ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). + ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/deploy-app-cluster#before-you-begin). Note the following: @@ -51,8 +51,8 @@ Note the following: cluster's pod address IP range is set to `/16` instead of the regular `/14`. `/16` is a CIDR notation. - GitLab requires basic authentication enabled and a client certificate issued for the cluster to - set up an [initial service account](cluster_access.md). In [GitLab versions - 11.10 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58208), the cluster creation process + set up an [initial service account](cluster_access.md). In + [GitLab versions 11.10 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58208), the cluster creation process explicitly requests GKE to create clusters with basic authentication enabled and a client certificate. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 95d8064b380..f1004a40a13 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -46,3 +46,27 @@ To remove the Kubernetes cluster integration: 1. Go to your cluster details page. 1. Select the **Advanced Settings** tab. 1. Select either **Remove integration** or **Remove integration and resources**. + +### Remove clusters by using the Rails console **(FREE SELF)** + +[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). + +To find a cluster: + +``` ruby +cluster = Clusters::Cluster.find(1) +cluster = Clusters::Cluster.find_by(name: 'cluster_name') +``` + +To delete a cluster but not the associated resources: + +```ruby +# Find users who have administrator access +user = User.find_by(username: 'admin_user') + +# Find the cluster with the ID +cluster = Clusters::Cluster.find(1) + +# Delete the cluster +Clusters::DestroyService.new(user).execute(cluster) +``` diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index fc41533b17c..0a574b9afe2 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -131,7 +131,7 @@ However, sometimes GitLab cannot create them. In such instances, your job can fa This job failed because the necessary resources were not successfully created. ``` -To find the cause of this error when creating a namespace and service account, check the [logs](../../../administration/logs.md#kuberneteslog). +To find the cause of this error when creating a namespace and service account, check the [logs](../../../administration/logs/index.md#kuberneteslog). Reasons for failure include: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index adea5dad7b8..fd2df96308c 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -8,21 +8,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Moved to GitLab Premium in 13.9. -Code Owners define who owns specific files or directories in a repository. +Code Owners define who develops and maintains a feature, and own the resulting +files or directories in a repository. - The users you define as Code Owners are displayed in the UI when you browse directories. - You can set your merge requests so they must be approved by Code Owners before merge. - You can protect a branch and allow only Code Owners to approve changes to the branch. -If you don't want to use Code Owners for approvals, you can -[configure rules](merge_requests/approvals/rules.md) instead. +Use Code Owners and approvers together with +[approval rules](merge_requests/approvals/rules.md) to build a flexible approval +workflow: -## Set up Code Owners +- Use **Code Owners** to define the users who have domain expertise for specific paths in your repository. +- Use **Approvers** and **Approval rules** to define domains of expertise (such as a security team) + that are not scoped to specific file paths in your repository. + - **Approvers** define the users. + - **Approval rules** define when these users can approve work, and whether or not their approval is required. + +For example: + +| Type | Name | Scope | Comment | +|------|------|--------|------------| +| Approval rule | UX | All files | A user experience (UX) team member reviews the user experience of all changes made in your project. | +| Approval rule | Security | All files | A security team member reviews all changes for vulnerabilities. | +| Code Owner approval rule | Frontend: Code Style | `*.css` files | A frontend engineer reviews CSS file changes for adherence to project style standards. | +| Code Owner approval rule | Backend: Code Review | `*.rb` files | A backend engineer reviews the logic and code style of Ruby files. | -You can use Code Owners to specify users or [shared groups](members/share_project_with_groups.md) -that are responsible for specific files and directories in a repository. +## Set up Code Owners -To set up Code Owners: +Create a `CODEOWNERS` file to specify users or [shared groups](members/share_project_with_groups.md) +that are responsible for specific files and directories in a repository. Each repository +can have a single `CODEOWNERS` file. To create it: 1. Choose the location where you want to specify Code Owners: - In the root directory of the repository @@ -59,24 +75,38 @@ Next steps: > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1. > - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. -You can use members of groups and subgroups as Code Owners for a project. +You can use members of groups and subgroups as Code Owners for projects: -For example, if you have these groups: +```mermaid +graph TD + A[Parent group X] -->|owns| B[Project A] + A -->|contains| C[Subgroup Y] + C -->|owns| D[Project B] + A-. inherits ownership .-> D +``` -- **Group X** (`group-x`) with **Project A** in it. -- **Subgroup Y** (`group-x/subgroup-y`), which belongs to **Group X**, with **Project B** in it. +In this example: -The eligible Code Owners: +- **Parent group X** (`group-x`) owns **Project A**. +- **Parent group X** also contains a subgroup, **Subgroup Y**. (`group-x/subgroup-y`) +- **Subgroup Y** owns **Project B**. -- For **Project A** are the members of **Group X** only, because **Project A** doesn't belong to **Subgroup Y**. -- For **Project B** are the members of both **Group X** and **Subgroup Y**. +The eligible Code Owners are: - +- **Project A**: the members of **Group X** only, because **Project A** doesn't belong to **Subgroup Y**. +- **Project B**: the members of both **Group X** and **Subgroup Y**. You can [invite](members/share_project_with_groups.md) **Subgroup Y** to **Project A** so that their members also become eligible Code Owners. - +```mermaid +graph LR + A[Parent group X] -->|owns| B[Project A] + A -->|also contains| C[Subgroup Y] + C -.->D{Invite Subgroup Y<br/>to Project A?} -.->|yes| F[Approvals can be<br/> required] -.-> B + D{Invite Subgroup Y<br/>to Project A?} -.->|no| I[Subgroup Y cannot be<br /> an approver] -.-> B + C -.->E{Add Subgroup Y<br/>as Code Owners<br/>to Project A?} -.->|yes| H[Approvals can only<br/>be optional] -.-> B +``` If you do not invite **Subgroup Y** to **Project A**, but make them Code Owners, their approval of the merge request becomes optional. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index a90ffbe5796..41afbdada6b 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -116,8 +116,8 @@ To display the deploy boards for a specific [environment](../../ci/environments/ Kubernetes. NOTE: - Matching based on the Kubernetes `app` label was removed in [GitLab - 12.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/14020). + Matching based on the Kubernetes `app` label was removed in + [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/14020). To migrate, please apply the required annotations (see above) and re-deploy your application. If you are using Auto DevOps, this will be done automatically and no action is necessary. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index c64afd95d8d..a9f19d27416 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use deploy keys to access repositories that are hosted in GitLab. In most cases, you use deploy keys to access a repository from an external host, like a build server or Continuous Integration (CI) server. -Depending on your needs, you might want to use a [deploy token](../deploy_tokens/) to access a repository instead. +Depending on your needs, you might want to use a [deploy token](../deploy_tokens/index.md) to access a repository instead. | Attribute | Deploy key | Deploy token | |------------------|-------------|--------------| @@ -146,8 +146,8 @@ What happens to the deploy key when it is disabled depends on the following: ### Deploy key cannot push to a protected branch -There are a few scenarios where a deploy key will fail to push to a [protected -branch](../protected_branches.md). +There are a few scenarios where a deploy key will fail to push to a +[protected branch](../protected_branches.md). - The owner associated to a deploy key does not have access to the protected branch. - The owner associated to a deploy key does not have [membership](../members/index.md) to the project of the protected branch. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 42287ff84ce..5df3a973cca 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -112,7 +112,7 @@ To re-use templates [you've created](../project/description_templates.md#create-  You might also be interested in templates for various -[file types in groups](../group/index.md#group-file-templates). +[file types in groups](../group/manage.md#group-file-templates). ### Set a default template for merge requests and issues diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 11d1db195e1..90f64b7262c 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -23,5 +23,5 @@ ignored. ## Syntax Highlighting The `.gitattributes` file can be used to define which language to use when -syntax highlighting files and diffs. See ["Syntax -Highlighting"](highlighting.md) for more information. +syntax highlighting files and diffs. See +["Syntax Highlighting"](highlighting.md) for more information. diff --git a/doc/user/project/img/code_owners_invite_members_v13_4.png b/doc/user/project/img/code_owners_invite_members_v13_4.png Binary files differdeleted file mode 100644 index 852a5f68b36..00000000000 --- a/doc/user/project/img/code_owners_invite_members_v13_4.png +++ /dev/null diff --git a/doc/user/project/img/code_owners_members_v13_4.png b/doc/user/project/img/code_owners_members_v13_4.png Binary files differdeleted file mode 100644 index e37fe72cd6e..00000000000 --- a/doc/user/project/img/code_owners_members_v13_4.png +++ /dev/null diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 867477c83b2..d9ad0c57d79 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -11,8 +11,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w tools developed by IBM which also include a centralized version control system similar to Git. -A good read of ClearCase's basic concepts is can be found in this [StackOverflow -post](https://stackoverflow.com/a/645771/974710). +A good read of ClearCase's basic concepts is can be found in this +[StackOverflow post](https://stackoverflow.com/a/645771/974710). The following table illustrates the main differences between ClearCase and Git: diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index a190edb179d..a3dfa3edff0 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -241,3 +241,35 @@ Feature.disable(:github_importer_lower_per_page_limit, group) For information on automating user, group, and project import API calls, see [Automate group and project import](index.md#automate-group-and-project-import). + +## Troubleshooting + +### Manually continue a previously failed import process + +In some cases, the GitHub import process can fail to import the repository. This causes GitLab to abort the project import process and requires the +repository to be imported manually. Administrators can manually import the repository for a failed import process: + +1. Open a Rails console. +1. Run the following series of commands in the console: + + ```ruby + project_id = <PROJECT_ID> + github_access_token = <GITHUB_ACCESS_TOKEN> + github_repository_path = '<GROUP>/<REPOSITORY>' + + github_repository_url = "https://#{github_access_token}@github.com/#{github_repository_path}.git" + + # Find project by ID + project = Project.find(project_id) + # Set import URL and credentials + project.import_url = github_repository_url + project.import_type = 'github' + project.import_source = github_repository_path + project.save! + # Create an import state if the project was created manually and not from a failed import + project.create_import_state if project.import_state.blank? + # Set state to start + project.import_state.force_start + # Trigger import from second step + Gitlab::GithubImport::Stage::ImportRepositoryWorker.perform_async(project.id) + ``` diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 0609b843e86..53547e69e00 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -68,12 +68,14 @@ bugsCharts: description: "Open bugs created per month" type: bar query: - issuable_type: issue - issuable_state: opened - filter_labels: - - bug - group_by: month - period_limit: 24 + data_source: issuables + params: + issuable_type: issue + issuable_state: opened + filter_labels: + - bug + group_by: month + period_limit: 24 ``` Each chart definition is made up of a hash composed of key-value pairs. @@ -85,12 +87,14 @@ For example, here's single chart definition: description: "Open bugs created per month" type: bar query: - issuable_type: issue - issuable_state: opened - filter_labels: - - bug - group_by: month - period_limit: 24 + data_source: issuables + params: + issuable_type: issue + issuable_state: opened + filter_labels: + - bug + group_by: month + period_limit: 24 ``` ## Configuration parameters @@ -104,7 +108,7 @@ The following table lists available parameters for charts: | [`title`](#title) | The title of the chart. This displays on the Insights page. | | [`description`](#description) | A description for the individual chart. This displays above the relevant chart. | | [`type`](#type) | The type of chart: `bar`, `line` or `stacked-bar`. | -| [`query`](#query) | A hash that defines the conditions for issues / merge requests to be part of the chart. | +| [`query`](#query) | A hash that defines the data source and filtering conditions for the chart. | ## Parameter details @@ -153,10 +157,12 @@ Supported values are: | `line` |  | | `stacked-bar` |  | +NOTE: +The `dora` data source only supports the `bar` chart type. + ### `query` -`query` allows to define the conditions for issues / merge requests to be part -of the chart. +`query` allows to define the data source and various filtering conditions for the chart. Example: @@ -166,6 +172,29 @@ monthlyBugsCreated: description: "Open bugs created per month" type: bar query: + data_source: issuables + params: + issuable_type: issue + issuable_state: opened + filter_labels: + - bug + collection_labels: + - S1 + - S2 + - S3 + - S4 + group_by: week + period_limit: 104 +``` + +The legacy format without the `data_source` parameter is still supported: + +```yaml +monthlyBugsCreated: + title: "Monthly bugs created" + description: "Open bugs created per month" + type: bar + query: issuable_type: issue issuable_state: opened filter_labels: @@ -179,7 +208,20 @@ monthlyBugsCreated: period_limit: 104 ``` -#### `query.issuable_type` +#### `query.data_source` + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 15.3. + +The `data_source` parameter was introduced to allow visualizing data from different data sources. + +Supported values are: + +- `issuables`: Exposes merge request or issue data. +- `dora`: Exposes DORA metrics data. + +#### `Issuable` query parameters + +##### `query.params.issuable_type` Defines the type of "issuable" you want to create a chart for. @@ -188,7 +230,7 @@ Supported values are: - `issue`: The chart displays issues' data. - `merge_request`: The chart displays merge requests' data. -#### `query.issuable_state` +##### `query.params.issuable_state` Filter by the current state of the queried "issuable". @@ -202,7 +244,7 @@ Supported values are: - `merged`: Merged merge requests. - `all`: Issues / merge requests in all states -#### `query.filter_labels` +##### `query.params.filter_labels` Filter by labels currently applied to the queried "issuable". @@ -216,14 +258,16 @@ monthlyBugsCreated: title: "Monthly regressions created" type: bar query: - issuable_type: issue - issuable_state: opened - filter_labels: - - bug - - regression + data_source: issuables + params: + issuable_type: issue + issuable_state: opened + filter_labels: + - bug + - regression ``` -#### `query.collection_labels` +##### `query.params.collection_labels` Group "issuable" by the configured labels. @@ -237,18 +281,20 @@ weeklyBugsBySeverity: title: "Weekly bugs by severity" type: stacked-bar query: - issuable_type: issue - issuable_state: opened - filter_labels: - - bug - collection_labels: - - S1 - - S2 - - S3 - - S4 + data_source: issuables + params: + issuable_type: issue + issuable_state: opened + filter_labels: + - bug + collection_labels: + - S1 + - S2 + - S3 + - S4 ``` -#### `query.group_by` +##### `query.group_by` Define the X-axis of your chart. @@ -258,7 +304,7 @@ Supported values are: - `week`: Group data per week. - `month`: Group data per month. -#### `query.period_limit` +##### `query.period_limit` Define how far "issuables" are queried in the past (using the `query.period_field`). @@ -295,6 +341,68 @@ NOTE: Until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/26911), is resolved, you may see `created_at` in place of `merged_at`. `created_at` is used instead. +#### `DORA` query parameters + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367248) in GitLab 15.3. + +An example DORA chart definition: + +```yaml +dora: + title: "DORA charts" + charts: + - title: "DORA deployment frequency" + type: bar # only bar chart is supported at the moment + query: + data_source: dora + params: + metric: deployment_frequency + group_by: day + period_limit: 10 + projects: + only: + - 38 + - title: "DORA lead time for changes" + description: "DORA lead time for changes" + type: bar + query: + data_source: dora + params: + metric: lead_time_for_changes + group_by: day + environment_tiers: + - staging + period_limit: 30 +``` + +##### `query.metric` + +Defines which DORA metric to query. The available values are: + +- `deployment_frequency` (default) +- `lead_time_for_changes` +- `time_to_restore_service` +- `change_failure_rate` + +The metrics are described on the [DORA API](../../../api/dora/metrics.md#the-value-field) page. + +##### `query.group_by` + +Define the X-axis of your chart. + +Supported values are: + +- `day` (default): Group data per day. +- `month`: Group data per month. + +##### `query.period_limit` + +Define how far the metrics are queried in the past (default: 15). Maximum lookback period is 180 days or 6 months. + +##### `query.environment_tiers` + +An array of environments to include into the calculation (default: production). Available options: `production`, `staging`, `testing`, `development`, `other`. + ### `projects` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10904) in GitLab 12.4. @@ -325,10 +433,12 @@ monthlyBugsCreated: description: "Open bugs created per month" type: bar query: - issuable_type: issue - issuable_state: opened - filter_labels: - - bug + data_source: issuables + params: + issuable_type: issue + issuable_state: opened + filter_labels: + - bug projects: only: - 3 # You can use the project ID @@ -355,41 +465,47 @@ bugsCharts: type: bar <<: *projectsOnly query: - issuable_type: issue - issuable_state: opened - filter_labels: - - bug - group_by: month - period_limit: 24 + data_source: issuables + params: + issuable_type: issue + issuable_state: opened + filter_labels: + - bug + group_by: month + period_limit: 24 - title: "Weekly bugs by severity" type: stacked-bar <<: *projectsOnly query: - issuable_type: issue - issuable_state: opened - filter_labels: - - bug - collection_labels: - - S1 - - S2 - - S3 - - S4 - group_by: week - period_limit: 104 + data_source: issuables + params: + issuable_type: issue + issuable_state: opened + filter_labels: + - bug + collection_labels: + - S1 + - S2 + - S3 + - S4 + group_by: week + period_limit: 104 - title: "Monthly bugs by team" type: line <<: *projectsOnly query: - issuable_type: merge_request - issuable_state: opened - filter_labels: - - bug - collection_labels: - - Manage - - Plan - - Create - group_by: month - period_limit: 24 + data_source: issuables + params: + issuable_type: merge_request + issuable_state: opened + filter_labels: + - bug + collection_labels: + - Manage + - Plan + - Create + group_by: month + period_limit: 24 ``` diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 1319c9e74cd..da35f0dc226 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -39,7 +39,7 @@ GitLab supports integrating Harbor projects at the group or project level. Compl After the Harbor integration is activated: -- The global variables `$HARBOR_USERNAME`, `$HARBOR_PASSWORD`, `$HARBOR_URL`, and `$HARBOR_PROJECT` are created for CI/CD use. +- The global variables `$HARBOR_USERNAME`, `$HARBOR_HOST`, `$HARBOR_OCI`, `$HARBOR_PASSWORD`, `$HARBOR_URL`, and `$HARBOR_PROJECT` are created for CI/CD use. - The project-level integration settings override the group-level integration settings. ## Secure your requests to the Harbor APIs @@ -50,3 +50,51 @@ the `username:password` combination. The following are suggestions for safe use: - Use TLS on the Harbor APIs you connect to. - Follow the principle of least privilege (for access on Harbor) with your credentials. - Have a rotation policy on your credentials. + +## Examples of Harbor variables in CI/CD + +### Push a Docker image with kaniko + +For more information, see [Use kaniko to build Docker images](../../../ci/docker/using_kaniko.md). + +```yaml +docker: + stage: docker + image: + name: gcr.io/kaniko-project/executor:debug + entrypoint: [''] + script: + - mkdir -p /kaniko/.docker + - echo "{\"auths\":{\"${HARBOR_HOST}\":{\"auth\":\"$(echo -n ${HARBOR_USERNAME}:${HARBOR_PASSWORD} | base64)\"}}}" > /kaniko/.docker/config.json + - >- + /kaniko/executor + --context "${CI_PROJECT_DIR}" + --dockerfile "${CI_PROJECT_DIR}/Dockerfile" + --destination "${HARBOR_HOST}/${HARBOR_PROJECT}/${CI_PROJECT_NAME}:${CI_COMMIT_TAG}" + rules: + - if: $CI_COMMIT_TAG +``` + +### Push a Helm chart with an OCI registry + +Helm supports OCI registries by default. OCI is supported in [Harbor 2.0](https://github.com/goharbor/harbor/releases/tag/v2.0.0) and later. +Read more about OCI in Helm's [blog](https://helm.sh/blog/storing-charts-in-oci/) and [documentation](https://helm.sh/docs/topics/registries/#enabling-oci-support). + +```yaml +helm: + stage: helm + image: + name: dtzar/helm-kubectl:latest + entrypoint: [''] + variables: + # Enable OCI support (not required since Helm v3.8.0) + HELM_EXPERIMENTAL_OCI: 1 + script: + # Log in to the Helm registry + - helm registry login "${HARBOR_URL}" -u "${HARBOR_USERNAME}" -p "${HARBOR_PASSWORD}" + # Package your Helm chart, which is in the `test` directory + - helm package test + # Your helm chart is created with <chart name>-<chart release>.tgz + # You can push all building charts to your Harbor repository + - helm push test-*.tgz ${HARBOR_OCI}/${HARBOR_PROJECT} +``` diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 7af2e431157..3ef40fdfe44 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -73,6 +73,7 @@ You can configure the following integrations. | [Pipelines emails](pipeline_status_emails.md) | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | | [Pivotal Tracker](pivotal_tracker.md) | Add commit messages as comments to Pivotal Tracker stories. | **{dotted-circle}** No | | [Prometheus](prometheus.md) | Monitor application metrics. | **{dotted-circle}** No | +| [Pumble](pumble.md) | Send event notifications to a Pumble channel. | **{dotted-circle}** No | | Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | | [Redmine](redmine.md) | Use Redmine as the issue tracker. | **{dotted-circle}** No | | [Slack application](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | diff --git a/doc/user/project/integrations/pumble.md b/doc/user/project/integrations/pumble.md new file mode 100644 index 00000000000..cd28a7c0048 --- /dev/null +++ b/doc/user/project/integrations/pumble.md @@ -0,0 +1,39 @@ +--- +stage: Ecosystem +group: Integrations +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 +--- + +# Pumble **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93623) in GitLab 15.3. + +You can configure GitLab to send notifications to a Pumble channel: + +1. Create a webhook for the channel. +1. Add the webhook to GitLab. + +## Create a webhook for your Pumble channel + +1. Follow the steps in [Incoming Webhooks for Pumble](https://pumble.com/help/integrations/custom-apps/incoming-webhooks-for-pumble/) in the Pumble documentation. +1. Copy the webhook URL. + +## Configure settings in GitLab + +After you have a webhook URL for your Pumble channel, configure GitLab to send +notifications: + +1. To enable the integration for your group or project: + 1. In your group or project, on the left sidebar, select **Settings > Integrations**. +1. To enable the integration for your instance: + 1. On the top bar, select **Menu > Admin**. + 1. On the left sidebar, select **Settings > Integrations**. +1. Select the **Pumble** integration. +1. Ensure that the **Active** toggle is enabled. +1. Select the checkboxes corresponding to the GitLab events you want to receive in Pumble. +1. Paste the **Webhook** URL for the Pumble channel. +1. Configure the remaining options. +1. Optional. To test the integration, select **Test settings**. +1. Select **Save changes**. + +The Pumble channel begins to receive all applicable GitLab events. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index bd93fbcbcbc..dd0f57570aa 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -77,13 +77,13 @@ The following triggers are available for Slack notifications: ## Troubleshooting If your Slack integration is not working, start troubleshooting by -searching through the [Sidekiq logs](../../../administration/logs.md#sidekiqlog) +searching through the [Sidekiq logs](../../../administration/logs/index.md#sidekiqlog) for errors relating to your Slack service. ### Something went wrong on our end You might get this generic error message in the GitLab UI. -Review [the logs](../../../administration/logs.md#productionlog) to find +Review [the logs](../../../administration/logs/index.md#productionlog) to find the error message and keep troubleshooting from there. ### `certificate verify failed` diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 32e5f949c15..51049f156b8 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -878,7 +878,9 @@ Payload example: "source_branch": "ms-viewport", "source_project_id": 14, "author_id": 51, + "assignee_ids": [6], "assignee_id": 6, + "reviewer_ids": [6], "title": "MS-Viewport", "created_at": "2013-12-03T17:23:34Z", "updated_at": "2013-12-03T17:23:34Z", @@ -945,12 +947,7 @@ Payload example: "type": "ProjectLabel", "group_id": 41 }], - "action": "open", - "assignee": { - "name": "User1", - "username": "user1", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" - } + "action": "open" }, "labels": [{ "id": 206, @@ -999,7 +996,23 @@ Payload example: "group_id": 41 }] } - } + }, + "assignees": [ + { + "id": 6, + "name": "User1", + "username": "user1", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + } + ], + "reviewers": [ + { + "id": 6, + "name": "User1", + "username": "user1", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + } + ] } ``` @@ -1614,7 +1627,7 @@ Payload example: ### Remove a subgroup from a group -This webhook is not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transfer-a-group). +This webhook is not triggered when a [subgroup is transferred to a new parent group](../../group/manage.md#transfer-a-group). Request header: diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index e4ce736684b..1de7440a15d 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -137,7 +137,7 @@ For example, to test `push events`, your project should have at least one commit To test a webhook: -1. In your project, on the left sidebar, select **Settings > Webhooks**. +1. In your project or group, on the left sidebar, select **Settings > Webhooks**. 1. Scroll down to the list of configured webhooks. 1. From the **Test** dropdown list, select the type of event to test. @@ -236,12 +236,14 @@ For more information about supported events for Webhooks, go to [Webhook events] ## Troubleshoot webhooks +> **Recent events** for group webhooks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325642) in GitLab 15.3. + GitLab records the history of each webhook request. You can view requests made in the last 2 days in the **Recent events** table. To view the table: -1. In your project, on the left sidebar, select **Settings > Webhooks**. +1. In your project or group, on the left sidebar, select **Settings > Webhooks**. 1. Scroll down to the webhooks. 1. Each [failing webhook](#failing-webhooks) has a badge listing it as: @@ -261,10 +263,6 @@ The table includes the following details about each request:  -NOTE: -The **Recent events** table is unavailable for group-level webhooks. For more information, read -[issue #325642](https://gitlab.com/gitlab-org/gitlab/-/issues/325642). - Each webhook event has a corresponding **Details** page. This page details the data that GitLab sent (request headers and body) and received (response headers and body). To view the **Details** page, select **View details** for the webhook event. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index c8ecb2fd2e6..787e990526d 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -642,3 +642,20 @@ 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. + +## Troubleshooting issue boards + +### Use Rails console to fix issue boards not loading and timing out + +If you see issue board not loading and timing out in UI, use Rails console to call the Issue Rebalancing service to fix it: + +1. [Start a Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session). +1. Run these commands: + + ```ruby + p = Project.find_by_full_path('<username-or-group>/<project-name>') + + Issues::RelativePositionRebalancingService.new(p.root_namespace.all_projects).execute + ``` + +1. To exit the Rails console, type `quit`. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index d1b27f6eab0..bf3cd13f3f0 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -276,7 +276,7 @@ It's rendered as: User activity events on designs (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#access-your-user-profile), -[group](../../group/index.md#view-group-activity), +[group](../../group/manage.md#view-group-activity), and [project](../working_with_projects.md#view-project-activity) activity pages. ## GitLab-Figma plugin diff --git a/doc/user/project/issues/img/related_issue_block_v12_8.png b/doc/user/project/issues/img/related_issue_block_v12_8.png Binary files differdeleted file mode 100644 index ce261f26ce6..00000000000 --- a/doc/user/project/issues/img/related_issue_block_v12_8.png +++ /dev/null diff --git a/doc/user/project/issues/img/related_issue_block_v15_3.png b/doc/user/project/issues/img/related_issue_block_v15_3.png Binary files differnew file mode 100644 index 00000000000..827ddeabf10 --- /dev/null +++ b/doc/user/project/issues/img/related_issue_block_v15_3.png diff --git a/doc/user/project/issues/img/related_issues_add_v12_8.png b/doc/user/project/issues/img/related_issues_add_v12_8.png Binary files differdeleted file mode 100644 index 8a06d005a5f..00000000000 --- a/doc/user/project/issues/img/related_issues_add_v12_8.png +++ /dev/null diff --git a/doc/user/project/issues/img/related_issues_add_v15_3.png b/doc/user/project/issues/img/related_issues_add_v15_3.png Binary files differnew file mode 100644 index 00000000000..7c6edf61427 --- /dev/null +++ b/doc/user/project/issues/img/related_issues_add_v15_3.png diff --git a/doc/user/project/issues/img/related_issues_remove_v12_8.png b/doc/user/project/issues/img/related_issues_remove_v12_8.png Binary files differdeleted file mode 100644 index a8dff4c7052..00000000000 --- a/doc/user/project/issues/img/related_issues_remove_v12_8.png +++ /dev/null diff --git a/doc/user/project/issues/img/related_issues_remove_v15_3.png b/doc/user/project/issues/img/related_issues_remove_v15_3.png Binary files differnew file mode 100644 index 00000000000..577bbed9df3 --- /dev/null +++ b/doc/user/project/issues/img/related_issues_remove_v15_3.png diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index 756fe9699f1..fcc53a239dc 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -17,6 +17,7 @@ You can set the weight of an issue during its creation, by changing the value in the dropdown menu. You can set it to a non-negative integer value from 0, 1, 2, and so on. You can remove weight from an issue as well. +A user with a Reporter role (or above) can set the weight. This value appears on the right sidebar of an individual issue, as well as in the issues page next to a weight icon (**{weight}**). diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 15d8da7f544..40e5a6d6a92 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -123,8 +123,8 @@ example, if the list is scoped to a label `Frontend`, the new issue also has thi ### By sending an email -> Generated email address format changed in GitLab 11.7. -> The older format is still supported, so existing aliases and contacts still work. +> - Generated email address format changed in GitLab 11.7. +> - The older format is still supported, so existing aliases and contacts still work. You can send an email to create an issue in a project on the project's **Issues List** page. @@ -731,4 +731,4 @@ You can do the following **only by using quick actions**: - [Publish an issue](#publish-an-issue) (`/publish`). - Clone an issue to the same or another project (`/clone`). - Close an issue and mark as a duplicate of another issue (`/duplicate`). -- Copy labels and milestone from another merge request in the project (`/copy_metadata`). +- Copy labels and milestone from another merge request or issue in the project (`/copy_metadata`). diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 028dd2ea473..9dc361b403f 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -37,7 +37,7 @@ To link one issue to another: - **[is blocked by](#blocking-issues)** 1. Input the issue number or paste in the full URL of the issue. -  +  Issues of the same project can be specified just by the reference number. Issues from a different project require additional information like the @@ -54,7 +54,7 @@ To link one issue to another: When you have finished adding all linked issues, you can see them categorized so their relationships can be better understood visually. - + You can also add a linked issue from a commit message or the description in another issue or MR. [Learn more about crosslinking issues](crosslinking_issues.md). @@ -66,7 +66,7 @@ right-side of each issue token to remove. Due to the bi-directional relationship, the relationship no longer appears in either issue. - + Access our [permissions](../../permissions.md) page for more information. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 333b073ee40..62c5489d9c3 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -446,12 +446,13 @@ To learn what happens when you sort by priority or label priority, see ## Real-time changes to labels -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241538) in GitLab 14.10 with a [feature flag](../../administration/feature_flags.md) named `realtime_labels`, disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241538) in GitLab 14.10 with a [feature flag](../../administration/feature_flags.md) named `realtime_labels`, disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/357370#note_991987201) in GitLab 15.1. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `realtime_labels`. -On GitLab.com, this feature is unavailable. +On GitLab.com, this feature is available. Changed labels are immediately visible to other users, without refreshing the page, on the following: diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index ff5f2ac8cb6..4a6272a0ca3 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -15,7 +15,7 @@ Project members can: 1. Be [direct members](#add-users-to-a-project) of the project. 1. [Inherit membership](#inherited-membership) of the project from the project's group. 1. Be a member of a group that was [shared](share_project_with_groups.md) with the project. -1. Be a member of a group that was [shared with the project's group](../../group/index.md#share-a-group-with-another-group). +1. Be a member of a group that was [shared with the project's group](../../group/manage.md#share-a-group-with-another-group). ```mermaid flowchart RL @@ -49,11 +49,22 @@ flowchart RL [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. Add users to a project so they become members and have permission -to perform actions. The Owner [role](../../permissions.md#project-members-permissions) can only be added at the group level. +to perform actions. + +The maximum role (access level) you set depends on if you have the Owner or Maintainer role for the group. For example, the maximum +role that can be set is: + +- Owner (`50`), if you have the Owner role for the project. +- Maintainer (`40`), if you have the Maintainer role on the project. + +In GitLab 14.8 and earlier, direct members of a project have a maximum role of Maintainer. +The Owner [role](../../permissions.md#project-members-permissions) can only be added at the group level. Prerequisite: -- You must have the Maintainer or Owner role. +- You must have the Maintainer or Owner role: + - To remove direct members with the Maintainer role and below, you must have the Maintainer role. + - To remove members with the Owner role, you must have the Owner role. To add a user to a project: @@ -91,7 +102,7 @@ Each user's access is based on: Prerequisite: - You must have the Maintainer or Owner role. -- Sharing the project with other groups must not be [prevented](../../group/index.md#prevent-a-project-from-being-shared-with-groups). +- Sharing the project with other groups must not be [prevented](../../group/access_and_permissions.md#prevent-a-project-from-being-shared-with-groups). To add groups to a project: @@ -107,7 +118,7 @@ The members of the group are not displayed on the **Members** tab. The **Members** tab shows: - Members who are directly assigned to the project. -- If the project was created in a group [namespace](../../group/index.md#namespaces), members of that group. +- If the project was created in a group [namespace](../../namespace/index.md), members of that group. ## Import users from another project @@ -173,7 +184,7 @@ To remove a member from a project: user has not forked the private repository or created webhooks. Existing forks continue to receive changes from the upstream project, and webhooks continue to receive updates. You may also want to configure your project to prevent projects in a group - [from being forked outside their group](../../group/index.md#prevent-project-forking-outside-group). + [from being forked outside their group](../../group/access_and_permissions.md#prevent-project-forking-outside-group). 1. Select **Remove member**. ## Filter and sort members diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index c4ae00f3c6c..3d5b855a9d3 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -29,7 +29,7 @@ You can share a project only with: - Groups for which you have an explicitly defined [membership](index.md). - Groups that contain a nested subgroup or project for which you have an explicitly defined role. -Administrators can share projects with any group in the namespace. +Administrators can share projects with any group in the instance. The primary mechanism to give a group of users, say 'Engineering', access to a project, say 'Project Acme', in GitLab is to make the 'Engineering' group the owner of 'Project @@ -52,7 +52,7 @@ After sharing 'Project Acme' with 'Engineering': When you share a project, be aware of the following restrictions and outcomes: - [Maximum access level](#maximum-access-level) -- [Sharing a public project with a private group](#share-a-public-project-with-private-group) +- [Sharing projects with groups of a higher restrictive visibility level](#sharing-projects-with-groups-of-a-higher-restrictive-visibility-level) - [Sharing project with group lock](#share-project-with-group-lock) ## Maximum access level @@ -67,18 +67,24 @@ in. That means you can only share down the hierarchy. For example, `group/subgro - Can not be shared with `group`. - Can be shared with `group/subgroup02` or `group/subgroup01/subgroup03`. -## Share a public project with private group +## Sharing projects with groups of a higher restrictive visibility level -When you share a public project with a private group, be aware of the following outcomes: +There are several outcomes you must be aware of when you share a project with a group that has a more restrictive [visibility level](../../public_access.md#project-and-group-visibility) than the project. For example, when you: -- The name of the group is no longer private and is visible to all users in the project members page. -- Owners of the project have access to members of the private group when they mention them in issues or merge requests. -- Project members who are direct or indirect members of the private group can see private group members listed in addition to members of the project. +- Share a public project with a private group. +- Share a public project with an internal group. +- Share an internal project with a private group. + +The following outcomes occur: + +- The group name is visible to all users that can view the project members page. +- Owners of the project have access to members of the group when they mention them in issues or merge requests. +- Project members who are direct or indirect members of the group can see group members listed in addition to members of the project. ## Share project with group lock -It is possible to prevent projects in a group from [sharing -a project with another group](../members/share_project_with_groups.md). +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#prevent-a-project-from-being-shared-with-groups). +Learn more about [Share with group lock](../../group/access_and_permissions.md#prevent-a-project-from-being-shared-with-groups). diff --git a/doc/user/project/merge_requests/approvals/img/scoped_to_protected_branch_v13_10.png b/doc/user/project/merge_requests/approvals/img/scoped_to_protected_branch_v13_10.png Binary files differdeleted file mode 100644 index a6636f0bc7f..00000000000 --- a/doc/user/project/merge_requests/approvals/img/scoped_to_protected_branch_v13_10.png +++ /dev/null diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 014936208c6..9f33ed6807b 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -23,7 +23,7 @@ flexibility: and require their approval before work can merge. You can configure merge request approvals on a per-project basis, and -[on the group level](../../../group/index.md#group-merge-request-approval-settings). Administrators of +[on the group level](../../../group/manage.md#group-merge-request-approval-settings). Administrators of [GitLab Premium](https://about.gitlab.com/pricing/) and [GitLab Ultimate](https://about.gitlab.com/pricing/) self-managed GitLab instances can also configure approvals diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index b79c8ee867f..c9278c19322 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -7,7 +7,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Merge request approval rules **(PREMIUM)** Approval rules define how many [approvals](index.md) a merge request must receive before it can -be merged, and which users should do the approving. You can define approval rules: +be merged, and which users should do the approving. They can be used in conjunction +with [Code owners](#code-owners-as-eligible-approvers) to ensure that changes are +reviewed both by the group maintaining the feature, and any groups responsible +for specific areas of oversight. + +You can define approval rules: - [As project defaults](#add-an-approval-rule). - [Per merge request](#edit-or-override-merge-request-approval-rules). @@ -127,7 +132,7 @@ users were not explicitly listed in the approval rules. ### Group approvers You can add a group of users as approvers, but those users count as approvers only if -they have direct membership to the group. Group approvers are +they have **direct membership** to the group. Inherited members do not count. Group approvers are restricted to only groups [with share access to the project](../../members/share_project_with_groups.md). A user's membership in an approvers group affects their individual ability to @@ -172,15 +177,15 @@ oversight on proposed work. To enable approval permissions for these users witho granting them push access: 1. [Create a protected branch](../../protected_branches.md) -1. [Create a new group](../../../group/index.md#create-a-group). -1. [Add the user to the group](../../../group/index.md#add-users-to-a-group), +1. [Create a new group](../../../group/manage.md#create-a-group). +1. [Add the user to the group](../../../group/manage.md#add-users-to-a-group), and select the Reporter role for the user. 1. [Share the project with your group](../../members/share_project_with_groups.md#share-a-project-with-a-group-of-users), based on the Reporter role. 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. 1. Select **Add approval rule** or **Update approval rule** and target the protected branch. -1. [Add the group](../../../group/index.md#create-a-group) to the permission list. +1. [Add the group](../../../group/manage.md#create-a-group) to the permission list.  @@ -213,7 +218,8 @@ appreciated, but not required. To make an approval rule optional: ## Approvals for protected branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab 12.8. +> - **All protected branches** target branch option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360930) in GitLab 15.3. Approval rules are often relevant only to specific branches, like your [default branch](../../repository/branches/default.md). To configure an @@ -223,10 +229,10 @@ approval rule for certain branches: 1. Go to your project and select **Settings**. 1. Expand **Merge request (MR) approvals**. 1. Select a **Target branch**: - - To protect all branches, select **All branches**. - - To select a specific branch, select it from the list: + - To apply the rule to all branches, select **All branches**. + - To apply the rule to all protected branches, select **All protected branches** (GitLab 15.3 and later). + - To apply the rule to a specific branch, select it from the list: -  1. To enable this configuration, read [Code Owner's approvals for protected branches](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 7b865a91106..3ca8ddb508a 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -19,7 +19,9 @@ To view or edit merge request approval settings: 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -In this section of general settings, you can configure the following settings: +### Approval settings + +These settings limit who can approve merge requests. | Setting | Description | | ------ | ------ | @@ -27,7 +29,14 @@ In this section of general settings, you can configure the following settings: | [Prevent approvals by users who add commits](#prevent-approvals-by-users-who-add-commits) | When enabled, users who have committed to a merge request cannot approve it. | | [Prevent editing approval rules in merge requests](#prevent-editing-approval-rules-in-merge-requests) | When enabled, users can't override the project's approval rules on merge requests. | | [Require user password to approve](#require-user-password-to-approve) | Force potential approvers to first authenticate with a password. | -| [Remove all approvals when commits are added to the source branch](#remove-all-approvals-when-commits-are-added-to-the-source-branch) | When enabled, remove all existing approvals on a merge request when more changes are added to it. | + +You can further define what happens to existing approvals when commits are added to the merge request. + +| Setting | Description | +| ------ | ------ | +| Keep approvals | Do not remove approvals. | +| [Remove all approvals](#remove-all-approvals-when-commits-are-added-to-the-source-branch) | Remove all existing approvals. | +| [Remove approvals by Code Owners if their files changed](#remove-approvals-by-code-owners-if-their-files-changed) | If a Code Owner has approved the merge request, and the commit changes files they are the Code Owner for, their approval is removed. | ## Prevent approval by author @@ -119,9 +128,27 @@ when more changes are added to it: 1. Select the **Remove all approvals when commits are added to the source branch** checkbox. 1. Select **Save changes**. -Approvals aren't reset when a merge request is [rebased from the UI](../methods/index.md#rebasing-in-semi-linear-merge-methods). +Approvals aren't removed when a merge request is [rebased from the UI](../methods/index.md#rebasing-in-semi-linear-merge-methods) However, approvals are reset if the target branch is changed. +## Remove approvals by Code Owners if their files changed + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90578) in GitLab 15.3. + +If you only want to remove approvals by Code Owners whose files have been changed: + +Prerequisite: + +- You must have at least the Maintainer role for a project. + +To do this: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge request approvals**. +1. Select **Remove approvals by Code Owners if their files changed**. +1. Select **Save changes**. + ## Code coverage check approvals You can require specific approvals if a merge request would result in a decline in code test @@ -139,7 +166,7 @@ You can also enforce merge request approval settings: - At the [instance level](../../../admin_area/merge_requests_approvals.md), which apply to all groups on an instance and, therefore, all projects. -- On a [top-level group](../../../group/index.md#group-merge-request-approval-settings), which apply to all subgroups +- On a [top-level group](../../../group/manage.md#group-merge-request-approval-settings), which apply to all subgroups and projects. If the settings are inherited by a group or project, they cannot be changed in the group or project diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 2adcc4d4575..893b2bc6811 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -8,13 +8,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3619) in GitLab 13.6. -Exporting merge requests CSV enables you and your team to export all the data collected from merge requests into a comma-separated values (CSV) file, which stores tabular data in plain text. +Export all the data collected from a project's merge requests into a comma-separated values (CSV) file. -To export merge requests to CSV, navigate to your **Merge requests** from the sidebar of a project and select **Export as CSV**. +To export merge requests to a CSV file: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** . +1. Add any searches or filters. This can help you keep the size of the CSV file under the 15MB limit. The limit ensures + the file can be emailed to a variety of email providers. +1. Select **Export as CSV** (**{export}**). +1. Confirm the correct number of merge requests are to be exported. +1. Select **Export merge requests**. ## CSV Output -The following table shows what attributes will be present in the CSV. +The following table shows the attributes in the CSV file. | Column | Description | |--------------------|--------------------------------------------------------------| @@ -42,8 +50,3 @@ The following table shows what attributes will be present in the CSV. In GitLab 14.7 and earlier, the first two columns were `MR ID` and `URL`, which [caused an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/34769) when importing back into GitLab. - -## Limitations - -- Export merge requests to CSV is not available at the Group's merge request list. -- As the merge request CSV file is sent as an email attachment, the size is limited to 15MB to ensure successful delivery across a range of email providers. If you need to minimize the size of the file, you can narrow the search before export. For example, you can set up exports of open and closed merge requests in separate files. diff --git a/doc/user/project/merge_requests/img/license_compliance_widget_v15_3.png b/doc/user/project/merge_requests/img/license_compliance_widget_v15_3.png Binary files differnew file mode 100644 index 00000000000..a9f73d40f82 --- /dev/null +++ b/doc/user/project/merge_requests/img/license_compliance_widget_v15_3.png diff --git a/doc/user/project/merge_requests/img/status_checks_widget_passed_v14_0.png b/doc/user/project/merge_requests/img/status_checks_widget_passed_v14_0.png Binary files differdeleted file mode 100644 index de61ca8b553..00000000000 --- a/doc/user/project/merge_requests/img/status_checks_widget_passed_v14_0.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/status_checks_widget_pending_v14_0.png b/doc/user/project/merge_requests/img/status_checks_widget_pending_v14_0.png Binary files differdeleted file mode 100644 index c4e606bd2f4..00000000000 --- a/doc/user/project/merge_requests/img/status_checks_widget_pending_v14_0.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index a7a669d3b75..35ec075c674 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -41,7 +41,7 @@ To view merge requests for all projects in a group: If your group contains subgroups, this view also displays merge requests from the subgroup projects. -## View all merge requests assigned to you +### View all merge requests assigned to you To view all merge requests assigned to you: @@ -52,13 +52,14 @@ To view all merge requests assigned to you: <!-- vale gitlab.FirstPerson = YES --> -Or: +or: - To use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>m</kbd>. -- On the top bar, on the top right, select **{merge-request-open}** **Merge requests**. - Then select one of the following: - - [Review requests](reviews/index.md). - - Merge requests assigned. + +or: + +1. On the top bar, on the top right, select **{merge-request-open}** **Merge requests**. +1. From the dropdown list, select **Assigned to you**. ## Filter the list of merge requests diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 63b464e5ff4..c4e4b40dc48 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -150,12 +150,8 @@ considered equivalent to rebasing. ### Rebase without CI/CD pipeline -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118825) in GitLab 14.7 [with a flag](../../../../administration/feature_flags.md) named `rebase_without_ci_ui`. Disabled by default. - -FLAG: -On GitLab.com and self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) named `rebase_without_ci_ui`. -The feature is not ready for production use. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118825) in GitLab 14.7 [with a flag](../../../../administration/feature_flags.md) named `rebase_without_ci_ui`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350262) in GitLab 15.3. Feature flag `rebase_without_ci_ui` removed. To rebase a merge request's branch without triggering a CI/CD pipeline, select **Rebase without pipeline** from the merge request reports section. diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png b/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png Binary files differdeleted file mode 100644 index 6b4899bf67f..00000000000 --- a/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v15_3.png b/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v15_3.png Binary files differnew file mode 100644 index 00000000000..b73dbb50cd2 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v15_3.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png b/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png Binary files differdeleted file mode 100644 index ced33682459..00000000000 --- a/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png b/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png Binary files differdeleted file mode 100644 index 2f0be3b6d06..00000000000 --- a/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_start.png b/doc/user/project/merge_requests/reviews/img/mr_review_start.png Binary files differdeleted file mode 100644 index 08b4c6bb82b..00000000000 --- a/doc/user/project/merge_requests/reviews/img/mr_review_start.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png b/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png Binary files differdeleted file mode 100644 index 4bef38f7808..00000000000 --- a/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_3.png b/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_3.png Binary files differnew file mode 100644 index 00000000000..38e18115803 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_3.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index a8f43dd9c02..27b223c48ec 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -36,13 +36,9 @@ To start your review: 1. Select the **{comment}** **comment** icon in the gutter to expand the diff lines and display a comment box. In GitLab version 13.2 and later, you can [select multiple lines](#comment-on-multiple-lines). -1. Write your first comment, and select **Start a review** below your comment: -  -1. Continue adding comments to lines of code, and select the appropriate button after - you write a comment: - - **Add to review**: Keep this comment private and add to the current review. - These review comments are marked **Pending** and are visible only to you. - - **Add comment now**: Submits the specific comment as a regular comment instead of as part of the review. +1. In the text area, write your first comment, then select **Start a review** below your comment. +1. Continue adding comments to lines of code. After each comment, select **Add to review**. + Comments made as part of a review are visible only to you until you submit your review. 1. Optional. You can use [quick actions](../../quick_actions.md) inside review comments. The comment shows the actions to perform after publication, but does not perform them until you submit your review. @@ -60,8 +56,12 @@ displays next to your name. You can submit your completed review in multiple ways: - Use the `/submit_review` [quick action](../../quick_actions.md) in the text of a non-review comment. -- When creating a review comment, select **Submit review**. -- Scroll to the bottom of the screen and select **Submit review**. +- Select **Finish review** and then **Submit review** in the footer at the bottom of the screen. + +Selecting **Finish review** opens a modal window to add an optional comment to summarize your review. +You can also include quick actions: + + When you submit your review, GitLab: @@ -73,25 +73,25 @@ When you submit your review, GitLab: ### Resolve or unresolve thread with a comment Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread). -When replying to a comment, a checkbox is displayed to resolve or unresolve -the thread after publication. - - +To resolve or unresolve a thread when replying to a comment: -If a particular pending comment resolves or unresolves the thread, this is shown on the pending -comment itself. +1. In the comment text area, write your comment. +1. Select or clear **Resolve thread**. +1. Select **Add comment now** or **Add to review**. - +Pending comments display information about the action to be taken when the comment is published: - +- **{check-circle-filled}** Thread will be resolved. +- **{check-circle}** Thread stays unresolved. ### Add a new comment > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8225) in GitLab 13.10. -If you have a review in progress, you are presented with the option to **Add to review**: +If you have a review in progress, you can also add a comment from the **Overview** tab by selecting + **Add to review**: - + ### Approval Rule information for Reviewers **(PREMIUM)** diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 423179325d3..0d7794a3ebd 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -10,6 +10,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/statu > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0, disabled behind the `:ff_external_status_checks` feature flag. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320783) in GitLab 14.1. +> - `failed` status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329636) in GitLab 14.9. You can create a status check that sends merge request data to third-party tools. When users create, change, or close merge requests, GitLab sends a notification. The users or automated workflows @@ -50,9 +51,8 @@ Merge requests return a `409 Conflict` error to any responses that do not refer External status checks have the following states: - `pending` - The default state. No response can been received by the merge request from the external service. -- `response received` - A response from the external service has been received and approved by it. - -Support for adding a `failed` state is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/338827). +- `passed` - A response from the external service has been received and approved by it. +- `failed` - A response from the external service has been received and denied by it. If something changes outside of GitLab, you can [set the status of an external status check](../../../api/status_checks.md#set-status-of-an-external-status-check) using the API. You don't need to wait for a merge request webhook payload to be sent first. @@ -138,24 +138,18 @@ the status check and it **will not** be recoverable. ## Status checks widget -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327634) in GitLab 14.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327634) in GitLab 14.1. +> - UI [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91504) in GitLab 15.2. -The status checks widget displays in merge requests and shows the status of external -status checks: +The status checks widget displays in merge requests and displays the following statuses: - +- **pending** (**{status-neutral}**), while GitLab waits for a response from an external status check. +- **success** (**{status-success}**) or **failed** (**{status-failed}**), when GitLab receives a response from an external status check. An organization might have a policy that does not allow merging merge requests if external status checks do not pass. However, the details in the widget are for informational purposes only. GitLab does not prevent merging of merge requests that fail status checks. - -While GitLab waits for a response from the external status check, the widget shows -the status checks as `pending`: - - - -After GitLab [receives a response](../../../api/status_checks.md#set-status-of-an-external-status-check) -from the external status check, the widget updates accordingly. +Support to allow merges to be blocked when external status checks fail is proposed in epic [&8516](https://gitlab.com/groups/gitlab-org/-/epics/8516). NOTE: GitLab cannot guarantee that the external status checks are properly processed by diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md index b0464f3f972..0e179415192 100644 --- a/doc/user/project/merge_requests/widgets.md +++ b/doc/user/project/merge_requests/widgets.md @@ -63,6 +63,12 @@ faster to preview proposed modifications. [Read more about Review Apps](../../../ci/review_apps/index.md). +## License compliance **(ULTIMATE)** + +If you have configured [License Compliance](../../compliance/license_compliance/index.md) for your project, then you can view a list of licenses that are detected for your project's dependencies. + + + ## External status checks **(ULTIMATE)** If you have configured [external status checks](status_checks.md) you can diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index ba48876d4fd..ef734225fb4 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -44,6 +44,14 @@ To view the milestone list: In a project, GitLab displays milestones that belong to the project. In a group, GitLab displays milestones that belong to the group and all projects in the group. +NOTE: +If a project has issue tracking +[turned off](../settings/index.md#configure-project-visibility-features-and-permissions), +you can get to the milestones page +by going to its URL. To do so, add: `/-/milestones` to your project or group URL. +For example `https://gitlab.com/gitlab-org/sample-data-templates/sample-gitlab-project/-/milestones`. +This is tracked in [issue 339009](https://gitlab.com/gitlab-org/gitlab/-/issues/339009). + ### View all milestones You can view all the milestones you have access to in the entire GitLab namespace. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 6daf671a751..c4c30dbdab4 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -32,6 +32,7 @@ for the most popular hosting services: <!-- vale gitlab.Spelling = NO --> +- [123-reg](https://www.123-reg.co.uk/support/domains/domain-name-server-dns-management-guide/) - [Amazon](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html) - [Bluehost](https://www.bluehost.com/help/article/dns-management-add-edit-or-delete-dns-entries) - [Cloudflare](https://support.cloudflare.com/hc/en-us/articles/201720164-Creating-a-Cloudflare-account-and-adding-a-website) diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 184e4f345c1..0cc6cb808d1 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -79,8 +79,6 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain-to-pages). 1. Go to step 1. -Another possible cause of this error is the `_redirects` file because the current implementation relies on an HTTP ACME challenge. If you redirect the `.acme-challenge/` endpoint Let's Encrypt cannot validate the domain. Make sure you don't have a wildcard (`*`) redirect either as that too breaks validation. The problem with wildcard redirects is tracked in the [Wildcard redirects break Let's Encrypt integration](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/649) issue. - ### Message "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later." hangs for more than an hour If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: 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 5fd17b5c07e..68a2a6a80ad 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -420,10 +420,10 @@ Now GitLab CI/CD not only builds the website, but also: 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/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/). +- Use GitLab CI/CD `environments` to + [deploy your 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/) to deploy this website, <https://docs.gitlab.com>. - Learn [how to use GitLab Pages to produce a code coverage report](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 54b843945cd..29712a82be1 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -18,7 +18,7 @@ replace the Pages wildcard domain on GitLab.com (`*.gitlab.io`) with your own. If you set up a GitLab Pages project on GitLab, it's automatically accessible under a subdomain of `namespace.example.io`. -The [`namespace`](../../group/index.md#namespaces) +The [`namespace`](../../namespace/index.md) is defined by your username on GitLab.com, or the group name you created this project under. For GitLab self-managed instances, replace `example.io` diff --git a/doc/user/project/pages/img/remove_pages.png b/doc/user/project/pages/img/remove_pages.png Binary files differdeleted file mode 100644 index d6c37ef30cd..00000000000 --- a/doc/user/project/pages/img/remove_pages.png +++ /dev/null diff --git a/doc/user/project/pages/img/remove_pages_v15_3.png b/doc/user/project/pages/img/remove_pages_v15_3.png Binary files differnew file mode 100644 index 00000000000..f740daf5c0b --- /dev/null +++ b/doc/user/project/pages/img/remove_pages_v15_3.png diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 1ea7500273e..3bd16a17f23 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -74,7 +74,7 @@ to your project's settings through the gear icon in the top right, and then navigating to **Pages**. Select the **Remove pages** button to delete your Pages website. - + ## Subdomains of subdomains @@ -297,9 +297,6 @@ A 404 can also be related to incorrect permissions. If [Pages Access Control](pa navigates to the Pages URL and receives a 404 response, it is possible that the user does not have permission to view the site. To fix this, verify that the user is a member of the project. -For Geo instances, 404 errors on Pages occur after promoting a secondary to a primary. -Find more details in the [Pages administration documentation](../../../administration/pages/index.md#404-error-after-promoting-a-geo-secondary-to-a-primary-node) - ### Cannot play media content on Safari Safari requires the web server to support the [Range request header](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/CreatingVideoforSafarioniPhone/CreatingVideoforSafarioniPhone.html#//apple_ref/doc/uid/TP40006514-SW6) diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index eb897c176fa..e6446c34bf0 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Pages access control **(FREE)** -> Available on GitLab.com in GitLab 12.4. - You can enable Pages access control on your project if your administrator has [enabled the access control feature](../../../administration/pages/index.md#access-control) on your GitLab instance. When enabled, only authenticated diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 6ef8477b6b6..d02609cbdc7 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -95,15 +95,15 @@ git push -o merge_request.create -o merge_request.target=my-target-branch -o mer ## Useful Git aliases As shown above, Git push options can cause Git commands to grow very long. If -you use the same push options frequently, it's useful to create [Git -aliases](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases). Git aliases +you use the same push options frequently, it's useful to create +[Git aliases](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases). Git aliases are command line shortcuts for Git which can significantly simplify the use of long Git commands. ### Merge when pipeline succeeds alias -To set up a Git alias for the [merge when pipeline succeeds Git push -option](#push-options-for-merge-requests): +To set up a Git alias for the +[merge when pipeline succeeds Git push option](#push-options-for-merge-requests): ```shell git config --global alias.mwps "push -o merge_request.create -o merge_request.target=master -o merge_request.merge_when_pipeline_succeeds" diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 96e51b061ee..216d040734d 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -56,6 +56,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more 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. | +| `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line created a specific type of to-do item notification. | | `/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](https://gitlab.com/gitlab-org/gitlab/-/issues/7330) in GitLab 12.0). | | `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | | `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 1d448ca5c94..d3456e086ce 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -32,12 +32,10 @@ When you create a release, or after, you can: - Add release notes. - Add a message for the Git tag associated with the release. - [Associate milestones with it](#associate-milestones-with-a-release). -- Attach [release assets](#release-assets), like runbooks or packages. +- Attach [release assets](release_fields.md#release-assets), like runbooks or packages. ## View releases -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36667) in GitLab 12.8. - To view a list of releases: - On the left sidebar, select **Deployments > Releases**, or @@ -81,18 +79,18 @@ To create a release in the Releases page: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Releases** and select **New release**. -1. From the [**Tag name**](#tag-name) dropdown, either: +1. From the [**Tag name**](release_fields.md#tag-name) dropdown, either: - Select an existing Git tag. Selecting an existing tag that is already associated with a release results in a validation error. - Enter a new Git tag name. 1. From the **Create from** dropdown, select a branch or commit SHA to use when creating the new tag. 1. Optional. Enter additional information about the release, including: - - [Title](#title). + - [Title](release_fields.md#title). - [Milestones](#associate-milestones-with-a-release). - - [Release notes](#release-notes-description). + - [Release notes](release_fields.md#release-notes-description). - Whether or not to include the [Tag message](../../../topics/git/tags.md). - - [Asset links](#links). + - [Asset links](release_fields.md#links). 1. Select **Create release**. ### Create a release in the Tags page @@ -126,99 +124,8 @@ You can create a release directly as part of the GitLab CI/CD pipeline by using The release is created only if the job processes without error. If the API returns an error during release creation, the release job fails. -Methods for creating a release using a CI/CD job include: - -- Create a release when a Git tag is created. -- Create a release when a commit is merged to the default branch. - -#### Create a release when a Git tag is created - -In this CI/CD example, pushing a Git tag to the repository, or creating a Git tag in the UI triggers -the release. You can use this method if you prefer to create the Git tag manually, and create a -release as a result. - -NOTE: -Do not provide Release notes when you create the Git tag in the UI. Providing release notes -creates a release, resulting in the pipeline failing. - -Key points in the following _extract_ of an example `.gitlab-ci.yml` file: - -- The `rules` stanza defines when the job is added to the pipeline. -- The Git tag is used in the release's name and description. - -```yaml -release_job: - stage: release - image: registry.gitlab.com/gitlab-org/release-cli:latest - rules: - - if: $CI_COMMIT_TAG # Run this job when a tag is created - script: - - echo "running release_job" - release: # See https://docs.gitlab.com/ee/ci/yaml/#release for available properties - tag_name: '$CI_COMMIT_TAG' - description: '$CI_COMMIT_TAG' -``` - -#### Create a release when a commit is merged to the default branch - -In this CI/CD example, merging a commit to the default branch triggers the pipeline. You can use -this method if your release workflow does not create a tag manually. - -Key points in the following _extract_ of an example `.gitlab-ci.yml` file: - -- The Git tag, description, and reference are created automatically in the pipeline. -- If you manually create a tag, the `release_job` job does not run. - -```yaml -release_job: - stage: release - image: registry.gitlab.com/gitlab-org/release-cli:latest - rules: - - if: $CI_COMMIT_TAG - when: never # Do not run this job when a tag is created manually - - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch - script: - - echo "running release_job for $TAG" - release: # See https://docs.gitlab.com/ee/ci/yaml/#release for available properties - tag_name: 'v0.$CI_PIPELINE_IID' # The version is incremented per pipeline. - description: 'v0.$CI_PIPELINE_IID' - ref: '$CI_COMMIT_SHA' # The tag is created from the pipeline SHA. -``` - -NOTE: -Environment variables set in `before_script` or `script` are not available for expanding -in the same job. Read more about -[potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400). - -#### Skip multiple pipelines when creating a release - -Creating a release using a CI/CD job could potentially trigger multiple pipelines if the associated tag does not exist already. To understand how this might happen, consider the following workflows: - -- Tag first, release second: - 1. A tag is created via UI or pushed. - 1. A tag pipeline is triggered, and runs `release` job. - 1. A release is created. - -- Release first, tag second: - 1. A pipeline is triggered when commits are pushed or merged to default branch. The pipeline runs `release` job. - 1. A release is created. - 1. A tag is created. - 1. A tag pipeline is triggered. The pipeline also runs `release` job. - -In the second workflow, the `release` job runs in multiple pipelines. To prevent this, you can use the [`workflow:rules` keyword](../../../ci/yaml/index.md#workflowrules) to determine if a release job should run in a tag pipeline: - -```yaml -release_job: - rules: - - if: $CI_COMMIT_TAG - when: never # Do not run this job in a tag pipeline - - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch - script: - - echo "Create release" - release: - name: 'My awesome release' - tag_name: '$CI_COMMIT_TAG' -``` +For examples of how you can create a release of your application in the CI/CD pipeline, +see [Release CI/CD examples](release_cicd_examples.md). ### Use a custom SSL CA certificate authority @@ -250,18 +157,6 @@ The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. -### `release-cli` command line - -The entries under the `release` node are transformed into Bash commands and sent -to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli). -You can also call the `release-cli` directly from a `script` entry. - -For example, if you use the YAML described previously: - -```shell -release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"} -``` - ### Create multiple releases in a single pipeline A pipeline can have multiple `release` jobs, for example: @@ -298,10 +193,17 @@ release tag. When the `released_at` date and time has passed, the badge is autom  -## Edit a release +## Historical releases + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199429) in GitLab 15.2. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26016) in GitLab 12.6. -> - Asset link editing [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9427) in GitLab 12.10. +You can create a release in the past using either the +[Releases API](../../../api/releases/index.md#historical-releases) or the UI. When you set +a past `released_at` date, an **Historical release** badge is displayed next to +the release tag. Due to being released in the past, [release evidence](#release-evidence) +is not available. + +## Edit a release Only users with at least the Developer role can edit releases. Read more about [Release permissions](#release-permissions). @@ -430,277 +332,6 @@ complete overlapping period. For more information, see [Deployment safety](../../../ci/environments/deployment_safety.md). -## Release fields - -The following fields are available when you create or edit a release. - -### Title - -The release title can be customized using the **Release title** field when -creating or editing a release. If no title is provided, the release's tag name -is used instead. - -### Tag name - -The release tag name should include the release version. GitLab uses [Semantic Versioning](https://semver.org/) -for our releases, and we recommend you do too. Use `(Major).(Minor).(Patch)`, as detailed in the -[GitLab Policy for Versioning](../../../policy/maintenance.md#versioning). - -For example, for GitLab version `10.5.7`: - -- `10` represents the major version. The major release was `10.0.0`, but often referred to as `10.0`. -- `5` represents the minor version. The minor release was `10.5.0`, but often referred to as `10.5`. -- `7` represents the patch number. - -Any part of the version number can be multiple digits, for example, `13.10.11`. - -### Release notes description - -Every release has a description. You can add any text you like, but we recommend -including a changelog to describe the content of your release. This helps users -quickly scan the differences between each release you publish. - -[Git's tagging messages](https://git-scm.com/book/en/v2/Git-Basics-Tagging) can -be included in Release note descriptions by selecting **Include tag message in -the release notes**. - -Description supports [Markdown](../../markdown.md). - -### Release assets - -A release contains the following types of assets: - -- [Source code](#source-code) -- [Link](#links) - -#### Source code - -GitLab automatically generates `zip`, `tar.gz`, `tar.bz2`, and `tar` -archived source code from the given Git tag. These are read-only assets. - -#### Links - -A link is any URL which can point to whatever you like: documentation, built -binaries, or other related materials. These can be both internal or external -links from your GitLab instance. -Each link as an asset has the following attributes: - -| Attribute | Description | Required | -| ---- | ----------- | --- | -| `name` | The name of the link. | Yes | -| `url` | The URL to download a file. | Yes | -| `filepath` | The redirect link to the `url`. See [this section](#permanent-links-to-release-assets) for more information. | No | -| `link_type` | The content kind of what users can download via `url`. See [this section](#link-types) for more information. | No | - -##### Permanent link to latest release - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16821) in GitLab 14.9. - -Latest release page is accessible through a permanent URL. -GitLab will redirect to the latest release page URL when it is visited. - -The format of the URL is: - -```plaintext -https://host/namespace/project/-/releases/permalink/latest -``` - -We also support, suffix path carry forward on the redirect to the latest release. -Example if release `v14.8.0-ee` is the latest release and has a readable link `https://host/namespace/project/-/releases/v14.8.0-ee#release` then it can be addressed as `https://host/namespace/project/-/releases/permalink/latest#release`. - -Refer [permanent links to latest release assets](#permanent-links-to-latest-release-assets) section to understand more about the suffix path carry forward usage. - -###### Sorting preferences - -By default, GitLab fetches the release using `released_at` time. The use of the query parameter `?order_by=released_at` is optional, and support for `?order_by=semver` is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352945). - -##### Permanent links to release assets - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27300) in GitLab 12.9. - -The assets associated with a release are accessible through a permanent URL. -GitLab always redirects this URL to the actual asset -location, so even if the assets move to a different location, you can continue -to use the same URL. This is defined during [link creation](../../../api/releases/links.md#create-a-link) or [updating](../../../api/releases/links.md#update-a-link) using the `filepath` API attribute. - -The format of the URL is: - -```plaintext -https://host/namespace/project/-/releases/:release/downloads/:filepath -``` - -If you have an asset for the `v11.9.0-rc2` release in the `gitlab-org` -namespace and `gitlab-runner` project on `gitlab.com`, for example: - -```json -{ - "name": "linux amd64", - "filepath": "/binaries/gitlab-runner-linux-amd64", - "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64", - "link_type": "other" -} -``` - -This asset has a direct link of: - -```plaintext -https://gitlab.com/gitlab-org/gitlab-runner/-/releases/v11.9.0-rc2/downloads/binaries/gitlab-runner-linux-amd64 -``` - -The physical location of the asset can change at any time and the direct link remains unchanged. - -##### Permanent links to latest release assets - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16821) in GitLab 14.9. - -The `filepath` from [permanent links to release assets](#permanent-links-to-release-assets) can be used in combination with [permanent link to the latest release](#permanent-link-to-latest-release). It is useful when we want to link a permanent URL to download an asset from the *latest release*. - -The format of the URL is: - -```plaintext -https://host/namespace/project/-/releases/permalink/latest/downloads/:filepath -``` - -If you have an asset with [`filepath`](../../../api/releases/links.md#create-a-link) for the `v11.9.0-rc2` latest release in the `gitlab-org` -namespace and `gitlab-runner` project on `gitlab.com`, for example: - -```json -{ - "name": "linux amd64", - "filepath": "/binaries/gitlab-runner-linux-amd64", - "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64", - "link_type": "other" -} -``` - -This asset has a direct link of: - -```plaintext -https://gitlab.com/gitlab-org/gitlab-runner/-/releases/permalink/latest/downloads/binaries/gitlab-runner-linux-amd64 -``` - -##### Link Types - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207257) in GitLab 13.1. - -The four types of links are "Runbook," "Package," "Image," and "Other." -The `link_type` parameter accepts one of the following four values: - -- `runbook` -- `package` -- `image` -- `other` (default) - -This field has no effect on the URL and it's only used for visual purposes in the Releases page of your project. - -##### Use a generic package for attaching binaries - -You can use [generic packages](../../packages/generic_packages/index.md) -to store any artifacts from a release or tag pipeline, -that can also be used for attaching binary files to an individual release entry. -You basically need to: - -1. [Push the artifacts to the Generic Package Registry](../../packages/generic_packages/index.md#publish-a-package-file). -1. [Attach the package link to the release](#links). - -The following example generates release assets, publishes them -as a generic package, and then creates a release: - -```yaml -stages: - - build - - upload - - release - -variables: - # Package version can only contain numbers (0-9), and dots (.). - # Must be in the format of X.Y.Z, i.e. should match /\A\d+\.\d+\.\d+\z/ regular expresion. - # See https://docs.gitlab.com/ee/user/packages/generic_packages/#publish-a-package-file - PACKAGE_VERSION: "1.2.3" - DARWIN_AMD64_BINARY: "myawesomerelease-darwin-amd64-${PACKAGE_VERSION}" - LINUX_AMD64_BINARY: "myawesomerelease-linux-amd64-${PACKAGE_VERSION}" - PACKAGE_REGISTRY_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/myawesomerelease/${PACKAGE_VERSION}" - -build: - stage: build - image: alpine:latest - rules: - - if: $CI_COMMIT_TAG - script: - - mkdir bin - - echo "Mock binary for ${DARWIN_AMD64_BINARY}" > bin/${DARWIN_AMD64_BINARY} - - echo "Mock binary for ${LINUX_AMD64_BINARY}" > bin/${LINUX_AMD64_BINARY} - artifacts: - paths: - - bin/ - -upload: - stage: upload - image: curlimages/curl:latest - rules: - - if: $CI_COMMIT_TAG - script: - - | - curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${DARWIN_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}" - - | - curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${LINUX_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}" - -release: - # Caution, as of 2021-02-02 these assets links require a login, see: - # https://gitlab.com/gitlab-org/gitlab/-/issues/299384 - stage: release - image: registry.gitlab.com/gitlab-org/release-cli:latest - rules: - - if: $CI_COMMIT_TAG - script: - - | - release-cli create --name "Release $CI_COMMIT_TAG" --tag-name $CI_COMMIT_TAG \ - --assets-link "{\"name\":\"${DARWIN_AMD64_BINARY}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}\"}" \ - --assets-link "{\"name\":\"${LINUX_AMD64_BINARY}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}\"}" -``` - -PowerShell users may need to escape the double quote `"` inside a JSON -string with a `` ` `` (back tick) for `--assets-link` and `ConvertTo-Json` -before passing on to the `release-cli`. -For example: - -```yaml -release: - script: - - $env:asset = "{`"name`":`"MyFooAsset`",`"url`":`"https://gitlab.com/upack/artifacts/download/$env:UPACK_GROUP/$env:UPACK_NAME/$($env:GitVersion_SemVer)?contentOnly=zip`"}" - - $env:assetjson = $env:asset | ConvertTo-Json - - release-cli create --name $CI_COMMIT_TAG --description "Release $CI_COMMIT_TAG" --ref $CI_COMMIT_TAG --tag-name $CI_COMMIT_TAG --assets-link=$env:assetjson -``` - -NOTE: -Directly attaching [job artifacts](../../../ci/pipelines/job_artifacts.md) -links to a release is not recommended, because artifacts are ephemeral and -are used to pass data in the same pipeline. This means there's a risk that -they could either expire or someone might manually delete them. - -#### Number of new and total features **(FREE SAAS)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235618) in GitLab 13.5. - -On [GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/releases), you can view the number of new and total features in the project. - - - -The totals are displayed on [shields](https://shields.io/) and are generated per release by -[a Rake task in the `www-gitlab-com` repository](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/lib/tasks/update_gitlab_project_releases_page.rake). - -| Item | Formula | -| ------ | ------ | -| `New features` | Total count of release posts across all tiers for a single release in the project. | -| `Total features` | Total count of release posts in reverse order for all releases in the project. | - -The counts are also shown by license tier. - -| Item | Formula | -| ------ | ------ | -| `New features` | Total count of release posts across a single tier for a single release in the project. | -| `Total features` | Total count of release posts across a single tier in reverse order for all releases in the project. | - ## Release evidence > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. @@ -828,10 +459,11 @@ keyword. Learn more in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issue In the API: -- If you specify a future `released_at` date, the release becomes an **Upcoming Release** +- If you specify a future `released_at` date, the release becomes an **Upcoming release** and the evidence is collected on the date of the release. You cannot collect release evidence before then. -- If you use a past `released_at` date, no evidence is collected. +- If you specify a past `released_at` date, the release becomes an **Historical + release** and no evidence is collected. - If you do not specify a `released_at` date, release evidence is collected on the date the release is created. @@ -848,7 +480,7 @@ In the API: - Users with the Guest role have read and download access to the project releases. This includes associated Git-tag-names, release description, author information of the releases. - However, other repository-related information, such as [source code](#source-code), [release evidence](#release-evidence) are redacted. + However, other repository-related information, such as [source code](release_fields.md#source-code), [release evidence](#release-evidence) are redacted. ### Create, update, and delete a release and its assets @@ -862,19 +494,6 @@ users with at least the Maintainer role to create, update, and delete releases by protecting the tag with a wildcard (`*`), and set **Maintainer** in the **Allowed to create** column. -## Release Command Line - -> [Introduced](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/6) in GitLab 12.10. - -The Release CLI is a command-line tool for managing GitLab Releases from the command line or from -the GitLab CI/CD configuration file, `.gitlab-ci.yml`. - -With it, you can create, update, modify, and delete releases right through the -terminal. - -Read the [Release CLI documentation](https://gitlab.com/gitlab-org/release-cli/-/blob/master/docs/index.md) -for details. - ## Release Metrics **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259703) in GitLab Premium 13.9. diff --git a/doc/user/project/releases/release_cicd_examples.md b/doc/user/project/releases/release_cicd_examples.md new file mode 100644 index 00000000000..f1d3e55a707 --- /dev/null +++ b/doc/user/project/releases/release_cicd_examples.md @@ -0,0 +1,100 @@ +--- +stage: Release +group: Release +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 +--- + +# Release CI/CD examples + +GitLab release functionality is flexible, able to be configured to match your workflow. This page +features example CI/CD release jobs. Each example demonstrates a method of creating a release in a +CI/CD pipeline. + +## Create a release when a Git tag is created + +In this CI/CD example, pushing a Git tag to the repository, or creating a Git tag in the UI triggers +the release. You can use this method if you prefer to create the Git tag manually, and create a +release as a result. + +NOTE: +Do not provide Release notes when you create the Git tag in the UI. Providing release notes +creates a release, resulting in the pipeline failing. + +Key points in the following _extract_ of an example `.gitlab-ci.yml` file: + +- The `rules` stanza defines when the job is added to the pipeline. +- The Git tag is used in the release's name and description. + +```yaml +release_job: + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + rules: + - if: $CI_COMMIT_TAG # Run this job when a tag is created + script: + - echo "running release_job" + release: # See https://docs.gitlab.com/ee/ci/yaml/#release for available properties + tag_name: '$CI_COMMIT_TAG' + description: '$CI_COMMIT_TAG' +``` + +## Create a release when a commit is merged to the default branch + +In this CI/CD example, merging a commit to the default branch triggers the pipeline. You can use +this method if your release workflow does not create a tag manually. + +Key points in the following _extract_ of an example `.gitlab-ci.yml` file: + +- The Git tag, description, and reference are created automatically in the pipeline. +- If you manually create a tag, the `release_job` job does not run. + +```yaml +release_job: + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + rules: + - if: $CI_COMMIT_TAG + when: never # Do not run this job when a tag is created manually + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch + script: + - echo "running release_job for $TAG" + release: # See https://docs.gitlab.com/ee/ci/yaml/#release for available properties + tag_name: 'v0.$CI_PIPELINE_IID' # The version is incremented per pipeline. + description: 'v0.$CI_PIPELINE_IID' + ref: '$CI_COMMIT_SHA' # The tag is created from the pipeline SHA. +``` + +NOTE: +Environment variables set in `before_script` or `script` are not available for expanding +in the same job. Read more about +[potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400). + +## Skip multiple pipelines when creating a release + +Creating a release using a CI/CD job could potentially trigger multiple pipelines if the associated tag does not exist already. To understand how this might happen, consider the following workflows: + +- Tag first, release second: + 1. A tag is created via UI or pushed. + 1. A tag pipeline is triggered, and runs `release` job. + 1. A release is created. + +- Release first, tag second: + 1. A pipeline is triggered when commits are pushed or merged to default branch. The pipeline runs `release` job. + 1. A release is created. + 1. A tag is created. + 1. A tag pipeline is triggered. The pipeline also runs `release` job. + +In the second workflow, the `release` job runs in multiple pipelines. To prevent this, you can use the [`workflow:rules` keyword](../../../ci/yaml/index.md#workflowrules) to determine if a release job should run in a tag pipeline: + +```yaml +release_job: + rules: + - if: $CI_COMMIT_TAG + when: never # Do not run this job in a tag pipeline + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch + script: + - echo "Create release" + release: + name: 'My awesome release' + tag_name: '$CI_COMMIT_TAG' +``` diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index b55f0b0a734..9e65ab4bc01 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -4,16 +4,38 @@ group: Release 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 --- -# Install the `release-cli` for the Shell executor **(FREE)** + +# GitLab Release CLI tool + +The [GitLab Release CLI (`release-cli`)](https://gitlab.com/gitlab-org/release-cli) tool +is a command-line tool for managing releases from the command line or from a CI/CD pipeline. +You can use the release CLI to create, update, modify, and delete releases. + +When you [use a CI/CD job to create a release](index.md#creating-a-release-by-using-a-cicd-job), +the `release` keyword entries are transformed into Bash commands and sent to the Docker +container containing the `release-cli` tool. The tool then creates the release. + +You can also call the `release-cli` tool directly from a [`script`](../../../ci/yaml/index.md#script). +For example: + +```shell +release-cli create --name "Release $CI_COMMIT_SHA" --description \ + "Created using the release-cli $EXTRA_DESCRIPTION" \ + --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" \ + --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" \ + --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"} +``` + +## Install the `release-cli` for the Shell executor **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/release-cli/-/issues/21) in GitLab 13.8. -> - [Changed](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/108) in GitLab 14.2, the `release-cli` binaries are also [available in the Package Registry](https://gitlab.com/jaime/release-cli/-/packages). +> - [Changed](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/108) in GitLab 14.2, the `release-cli` binaries are also [available in the Package Registry](https://gitlab.com/gitlab-org/release-cli/-/packages). When you use a runner with the Shell executor, you can download and install the `release-cli` manually for your [supported OS and architecture](https://release-cli-downloads.s3.amazonaws.com/latest/index.html). Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is available to use in your CI/CD jobs. -## Install on Unix/Linux +### Install on Unix/Linux 1. Download the binary for your system from S3, in the following example for amd64 systems: @@ -41,7 +63,7 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av release-cli version 0.6.0 ``` -## Install on Windows PowerShell +### Install on Windows PowerShell 1. Create a folder somewhere in your system, for example `C:\GitLab\Release-CLI\bin` diff --git a/doc/user/project/releases/release_fields.md b/doc/user/project/releases/release_fields.md new file mode 100644 index 00000000000..647cac9c38e --- /dev/null +++ b/doc/user/project/releases/release_fields.md @@ -0,0 +1,274 @@ +--- +stage: Release +group: Release +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 +--- + +# Release fields + +The following fields are available when you create or edit a release. + +## Title + +The release title can be customized using the **Release title** field when +creating or editing a release. If no title is provided, the release's tag name +is used instead. + +## Tag name + +The release tag name should include the release version. GitLab uses [Semantic Versioning](https://semver.org/) +for our releases, and we recommend you do too. Use `(Major).(Minor).(Patch)`, as detailed in the +[GitLab Policy for Versioning](../../../policy/maintenance.md#versioning). + +For example, for GitLab version `10.5.7`: + +- `10` represents the major version. The major release was `10.0.0`, but often referred to as `10.0`. +- `5` represents the minor version. The minor release was `10.5.0`, but often referred to as `10.5`. +- `7` represents the patch number. + +Any part of the version number can be multiple digits, for example, `13.10.11`. + +## Release notes description + +Every release has a description. You can add any text you like, but we recommend +including a changelog to describe the content of your release. This helps users +quickly scan the differences between each release you publish. + +[Git's tagging messages](https://git-scm.com/book/en/v2/Git-Basics-Tagging) can +be included in Release note descriptions by selecting **Include tag message in +the release notes**. + +Description supports [Markdown](../../markdown.md). + +## Release assets + +A release contains the following types of assets: + +- [Source code](#source-code) +- [Link](#links) + +### Source code + +GitLab automatically generates `zip`, `tar.gz`, `tar.bz2`, and `tar` +archived source code from the given Git tag. These are read-only assets. + +### Links + +A link is any URL which can point to whatever you like: documentation, built +binaries, or other related materials. These can be both internal or external +links from your GitLab instance. +Each link as an asset has the following attributes: + +| Attribute | Description | Required | +|-------------|--------------------------------------------------------------------------------------------------------------|----------| +| `name` | The name of the link. | Yes | +| `url` | The URL to download a file. | Yes | +| `filepath` | The redirect link to the `url`. See [this section](#permanent-links-to-release-assets) for more information. | No | +| `link_type` | The content kind of what users can download via `url`. See [this section](#link-types) for more information. | No | + +#### Permanent link to latest release + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16821) in GitLab 14.9. + +Latest release page is accessible through a permanent URL. +GitLab redirects to the latest release page URL when it is visited. + +The format of the URL is: + +```plaintext +https://host/namespace/project/-/releases/permalink/latest +``` + +We also support, suffix path carry forward on the redirect to the latest release. +Example if release `v14.8.0-ee` is the latest release and has a readable link `https://host/namespace/project/-/releases/v14.8.0-ee#release` then it can be addressed as `https://host/namespace/project/-/releases/permalink/latest#release`. + +Refer [permanent links to latest release assets](#permanent-links-to-latest-release-assets) section to understand more about the suffix path carry forward usage. + +##### Sorting preferences + +By default, GitLab fetches the release using `released_at` time. The use of the query parameter `?order_by=released_at` is optional, and support for `?order_by=semver` is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352945). + +#### Permanent links to release assets + +The assets associated with a release are accessible through a permanent URL. +GitLab always redirects this URL to the actual asset +location, so even if the assets move to a different location, you can continue +to use the same URL. This is defined during [link creation](../../../api/releases/links.md#create-a-link) or [updating](../../../api/releases/links.md#update-a-link) using the `filepath` API attribute. + +The format of the URL is: + +```plaintext +https://host/namespace/project/-/releases/:release/downloads/:filepath +``` + +If you have an asset for the `v11.9.0-rc2` release in the `gitlab-org` +namespace and `gitlab-runner` project on `gitlab.com`, for example: + +```json +{ + "name": "linux amd64", + "filepath": "/binaries/gitlab-runner-linux-amd64", + "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64", + "link_type": "other" +} +``` + +This asset has a direct link of: + +```plaintext +https://gitlab.com/gitlab-org/gitlab-runner/-/releases/v11.9.0-rc2/downloads/binaries/gitlab-runner-linux-amd64 +``` + +The physical location of the asset can change at any time and the direct link remains unchanged. + +#### Permanent links to latest release assets + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16821) in GitLab 14.9. + +The `filepath` from [permanent links to release assets](#permanent-links-to-release-assets) can be used in combination with [permanent link to the latest release](#permanent-link-to-latest-release). It is useful when we want to link a permanent URL to download an asset from the *latest release*. + +The format of the URL is: + +```plaintext +https://host/namespace/project/-/releases/permalink/latest/downloads/:filepath +``` + +If you have an asset with [`filepath`](../../../api/releases/links.md#create-a-link) for the `v11.9.0-rc2` latest release in the `gitlab-org` +namespace and `gitlab-runner` project on `gitlab.com`, for example: + +```json +{ + "name": "linux amd64", + "filepath": "/binaries/gitlab-runner-linux-amd64", + "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64", + "link_type": "other" +} +``` + +This asset has a direct link of: + +```plaintext +https://gitlab.com/gitlab-org/gitlab-runner/-/releases/permalink/latest/downloads/binaries/gitlab-runner-linux-amd64 +``` + +#### Link Types + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207257) in GitLab 13.1. + +The four types of links are "Runbook," "Package," "Image," and "Other." +The `link_type` parameter accepts one of the following four values: + +- `runbook` +- `package` +- `image` +- `other` (default) + +This field has no effect on the URL and it's only used for visual purposes in the Releases page of your project. + +#### Use a generic package for attaching binaries + +You can use [generic packages](../../packages/generic_packages/index.md) +to store any artifacts from a release or tag pipeline, +that can also be used for attaching binary files to an individual release entry. +You basically need to: + +1. [Push the artifacts to the Generic Package Registry](../../packages/generic_packages/index.md#publish-a-package-file). +1. [Attach the package link to the release](#links). + +The following example generates release assets, publishes them +as a generic package, and then creates a release: + +```yaml +stages: + - build + - upload + - release + +variables: + # Package version can only contain numbers (0-9), and dots (.). + # Must be in the format of X.Y.Z, i.e. should match /\A\d+\.\d+\.\d+\z/ regular expresion. + # See https://docs.gitlab.com/ee/user/packages/generic_packages/#publish-a-package-file + PACKAGE_VERSION: "1.2.3" + DARWIN_AMD64_BINARY: "myawesomerelease-darwin-amd64-${PACKAGE_VERSION}" + LINUX_AMD64_BINARY: "myawesomerelease-linux-amd64-${PACKAGE_VERSION}" + PACKAGE_REGISTRY_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/myawesomerelease/${PACKAGE_VERSION}" + +build: + stage: build + image: alpine:latest + rules: + - if: $CI_COMMIT_TAG + script: + - mkdir bin + - echo "Mock binary for ${DARWIN_AMD64_BINARY}" > bin/${DARWIN_AMD64_BINARY} + - echo "Mock binary for ${LINUX_AMD64_BINARY}" > bin/${LINUX_AMD64_BINARY} + artifacts: + paths: + - bin/ + +upload: + stage: upload + image: curlimages/curl:latest + rules: + - if: $CI_COMMIT_TAG + script: + - | + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${DARWIN_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}" + - | + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${LINUX_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}" + +release: + # Caution, as of 2021-02-02 these assets links require a login, see: + # https://gitlab.com/gitlab-org/gitlab/-/issues/299384 + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + rules: + - if: $CI_COMMIT_TAG + script: + - | + release-cli create --name "Release $CI_COMMIT_TAG" --tag-name $CI_COMMIT_TAG \ + --assets-link "{\"name\":\"${DARWIN_AMD64_BINARY}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}\"}" \ + --assets-link "{\"name\":\"${LINUX_AMD64_BINARY}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}\"}" +``` + +PowerShell users may need to escape the double quote `"` inside a JSON +string with a `` ` `` (back tick) for `--assets-link` and `ConvertTo-Json` +before passing on to the `release-cli`. +For example: + +```yaml +release: + script: + - $env:asset = "{`"name`":`"MyFooAsset`",`"url`":`"https://gitlab.com/upack/artifacts/download/$env:UPACK_GROUP/$env:UPACK_NAME/$($env:GitVersion_SemVer)?contentOnly=zip`"}" + - $env:assetjson = $env:asset | ConvertTo-Json + - release-cli create --name $CI_COMMIT_TAG --description "Release $CI_COMMIT_TAG" --ref $CI_COMMIT_TAG --tag-name $CI_COMMIT_TAG --assets-link=$env:assetjson +``` + +NOTE: +Directly attaching [job artifacts](../../../ci/pipelines/job_artifacts.md) +links to a release is not recommended, because artifacts are ephemeral and +are used to pass data in the same pipeline. This means there's a risk that +they could either expire or someone might manually delete them. + +### Number of new and total features **(FREE SAAS)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235618) in GitLab 13.5. + +On [GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/releases), you can view the number of new and total features in the project. + + + +The totals are displayed on [shields](https://shields.io/) and are generated per release by +[a Rake task in the `www-gitlab-com` repository](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/lib/tasks/update_gitlab_project_releases_page.rake). + +| Item | Formula | +|------------------|------------------------------------------------------------------------------------| +| `New features` | Total count of release posts across all tiers for a single release in the project. | +| `Total features` | Total count of release posts in reverse order for all releases in the project. | + +The counts are also shown by license tier. + +| Item | Formula | +|------------------|-----------------------------------------------------------------------------------------------------| +| `New features` | Total count of release posts across a single tier for a single release in the project. | +| `Total features` | Total count of release posts across a single tier in reverse order for all releases in the project. | diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 747da817195..3083ca5da3c 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -110,7 +110,7 @@ This setting applies only to each repository's default branch. To protect other you must either: - Configure [branch protection in the repository](../../../project/protected_branches.md). -- Configure [branch protection for groups](../../../group/index.md#change-the-default-branch-protection-of-a-group). +- Configure [branch protection for groups](../../../group/manage.md#change-the-default-branch-protection-of-a-group). Administrators of self-managed instances can customize the initial default branch protection for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 85bea80f777..df75f19ea6c 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -26,7 +26,7 @@ To fork an existing project in GitLab: 1. On the project's home page, in the top right, select **{fork}** **Fork**:  1. Optional. Edit the **Project name**. -1. For **Project URL**, select the [namespace](../../group/index.md#namespaces) +1. For **Project URL**, select the [namespace](../../namespace/index.md) your fork should belong to. 1. Add a **Project slug**. This value becomes part of the URL to your fork. It must be unique in the namespace. diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index a8937d4f705..8e1286548b9 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -232,7 +232,7 @@ When a repository path changes, GitLab handles the transition from the old location to the new one with a redirect. When you [rename a user](../../profile/index.md#change-your-username), -[change a group path](../../group/index.md#change-a-groups-path), or [rename a repository](../settings/index.md#rename-a-repository): +[change a group path](../../group/manage.md#change-a-groups-path), or [rename a repository](../settings/index.md#rename-a-repository): - URLs for the namespace and everything under it, like projects, are redirected to the new URLs. diff --git a/doc/user/project/repository/managing_large_repositories.md b/doc/user/project/repository/managing_large_repositories.md index 93b94ac0641..ba425ae3dc7 100644 --- a/doc/user/project/repository/managing_large_repositories.md +++ b/doc/user/project/repository/managing_large_repositories.md @@ -16,6 +16,8 @@ On this page we detail several best practices to improve performance with these It's *strongly* recommended in any Git system that binary or blob files (for example, packages, audio, video, graphics, etc.) are stored as Large File Storage (LFS) objects. In such setup, the Objects are stored elsewhere, such as in Object Storage, and this can reduce the repository size significantly, thus improving performance. +To analyze if the repository has these sorts of objects, it's recommended to run [`git-sizer`](https://github.com/github/git-sizer) to get a detailed analysis. This tool shows in detail what makes up the repository as well as highlights any areas of concern. + Refer to the [Git LFS documentation for more information](../../../topics/git/lfs/index.md). ## Gitaly Pack Objects Cache @@ -32,7 +34,7 @@ In these types of setups it's recommended that the GitLab environment used match ## Gitaly Cluster -Gitaly Cluster can notably improve large repository performance as it holds multiple replicas of the repository across several nodes. As a result, Gitaly Cluster can load balance read requests against those repositories and is also fault tolerant. +Gitaly Cluster can notably improve large repository performance as it holds multiple replicas of the repository across several nodes. As a result, Gitaly Cluster can load balance read requests against those repositories and is also fault-tolerant. It's recommended for large repositories, however, Gitaly Cluster is a large solution with additional complexity of setup, and management. Refer to the [Gitaly Cluster documentation for more information](../../../administration/gitaly/index.md), specifically the [Before deploying Gitaly Cluster](../../../administration/gitaly/index.md#before-deploying-gitaly-cluster) section. diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 4537f8520cd..b08530c34b3 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -17,8 +17,8 @@ Subscribe to the issue to follow its progress. Several mirroring methods exist: -- [Push](push.md): for mirroring a GitLab repository to another location. -- [Pull](pull.md): for mirroring a repository from another location to GitLab. +- [Push](push.md): Mirror a repository from GitLab to another location. +- [Pull](pull.md): Mirror a repository from another location to a GitLab Premium instance. - [Bidirectional](bidirectional.md) mirroring is also available, but can cause conflicts. Mirror a repository when: @@ -113,6 +113,11 @@ GitLab supports these authentication methods: - [SSH authentication](#ssh-authentication). - Password. +When using password authentication, ensure you specify the username. +For a [project access token](../../settings/project_access_tokens.md) or +[group access token](../../../group/settings/group_access_tokens.md), +use the username (not token name) and the token as the password. + ### SSH authentication SSH authentication is mutual: @@ -226,7 +231,7 @@ This error can occur when a firewall performs a `Deep SSH Inspection` on outgoin ### Could not read username: terminal prompts disabled If you receive this error after creating a new project using -[GitLab CI/CD for external repositories](../../../../ci/ci_cd_for_external_repos/): +[GitLab CI/CD for external repositories](../../../../ci/ci_cd_for_external_repos/index.md): - In Bitbucket Cloud: diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 88104e34eb4..d0f2b9a8088 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -28,6 +28,11 @@ local repository, GitLab stops updating the branch. This prevents data loss. Deleted branches and tags in the upstream repository are not reflected in the downstream repository. +NOTE: +Items deleted from the downstream pull mirror repository, but still in the upstream repository, +are restored upon the next pull. For example: a branch deleted _only_ in the mirrored repository +reappears after the next pull. + ## How pull mirroring works After you configure a GitLab repository as a pull mirror: diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index 592aff85434..46a9585604e 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -25,7 +25,7 @@ For custom push rules use [server hooks](../../../administration/server_hooks.md ## Enable global push rules You can create push rules for all new projects to inherit, but they can be overridden -at the project level or the [group level](../../group/index.md#group-push-rules). +at the project level or the [group level](../../group/access_and_permissions.md#group-push-rules). All projects created after you configure global push rules inherit this configuration. However, each existing project must be updated manually, using the process described in [Override global push rules per project](#override-global-push-rules-per-project). diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index b0ae1b7d1e0..344c288b607 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -46,8 +46,8 @@ To purge files from a GitLab repository: [`git-sizer`](https://github.com/github/git-sizer#getting-started) using a supported package manager or from source. -1. Generate a fresh [export from the - project](../settings/import_export.html#export-a-project-and-its-data) and download it. +1. Generate a fresh + [export from the project](../settings/import_export.md#export-a-project-and-its-data) and download it. This project export contains a backup copy of your repository *and* refs we can use to purge files from your repository. @@ -195,8 +195,8 @@ When using repository cleanup, note: - Project statistics are cached. You may need to wait 5-10 minutes to see a reduction in storage utilization. - The cleanup prunes loose objects older than 30 minutes. This means objects added or referenced in the last 30 minutes - are not be removed immediately. If you have access to the - [Gitaly](../../../administration/gitaly/index.md) server, you may slip that delay and run `git gc --prune=now` to + are not removed immediately. If you have access to the + [Gitaly](../../../administration/gitaly/index.md) server, you may skip that delay and run `git gc --prune=now` to prune all loose objects immediately. - This process removes some copies of the rewritten commits from the GitLab cache and database, but there are still numerous gaps in coverage and some of the copies may persist indefinitely. @@ -207,7 +207,7 @@ When using repository cleanup, note: Repository size limits: -- Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#account-and-limit-settings) +- Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#account-and-limit-settings). - Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md) on self-managed instances. - Are [set for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 17e55b7aac2..f32035102bb 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -307,8 +307,7 @@ In these issues, you can also see our friendly neighborhood [Support Bot](#suppo ### As an end user (issue creator) -> Support for additional email headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346600) in GitLab 14.6. -> In earlier versions, the Service Desk email address had to be in the "To" field. +> Support for additional email headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346600) in GitLab 14.6. In earlier versions, the Service Desk email address had to be in the "To" field. To create a Service Desk issue, an end user does not need to know anything about the GitLab instance. They just send an email to the address they are given, and diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 7d1bfcaab59..b973a0f56d1 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -253,7 +253,7 @@ Use the toggles to enable or disable features in the project. | **Security & Compliance** | ✓ | Control access to [security features](../../application_security/index.md). | | **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/). | | **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | -| **Pages** | ✓ | Allows you to [publish static websites](../pages/). | +| **Pages** | ✓ | Allows you to [publish static websites](../pages/index.md). | | **Operations** | ✓ | Control access to Operations-related features, including [Operations Dashboard](../../../operations/index.md), [Environments and Deployments](../../../ci/environments/index.md), [Feature Flags](../../../operations/feature_flags.md). | | **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | @@ -392,7 +392,7 @@ When you transfer a project to another namespace, you move the project to a diff Prerequisites: -- You must have at least the Maintainer role for the [group](../../group/index.md#create-a-group) to which you are transferring. +- You must have at least the Maintainer role for the [group](../../group/manage.md#create-a-group) to which you are transferring. - You must be the Owner of the project you transfer. - The group must allow creation of new projects. - The project must not contain any [container images](../../packages/container_registry/index.md#limitations). @@ -447,15 +447,16 @@ in GitLab 12.6, and then to [immediate deletion](https://gitlab.com/gitlab-org/g ### Delayed project deletion **(PREMIUM)** -> [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. +> - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. +> - [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3. -Projects can be deleted after a delay period. Multiple settings can affect whether +Projects in a group (not a personal namespace) can be deleted after a delay period. Multiple settings can affect whether delayed project deletion is enabled for a particular project: - Self-managed instance [settings](../../admin_area/settings/visibility_and_access_controls.md#delayed-project-deletion). You can enable delayed project deletion as the default setting for new groups, and configure the number of days for the delay. For GitLab.com, see the [GitLab.com settings](../../gitlab_com/index.md#delayed-project-deletion). -- Group [settings](../../group/index.md#enable-delayed-project-deletion) to enabled delayed project deletion for all +- Group [settings](../../group/manage.md#enable-delayed-project-deletion) to enabled delayed project deletion for all projects in the group. ### Delete a project immediately diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index facaba45aec..5a4e300a210 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -16,15 +16,18 @@ Use the <kbd>.</kbd> [keyboard shortcut](../../shortcuts.md) to open the Web IDE You can also open the Web IDE when viewing a file, from the repository file list, and from merge requests: -- *When viewing a file, or the repository file list* - +### When viewing a file or the repository file list + 1. In the upper right corner of the page, select **Open in Web IDE** if it is visible. 1. If **Open in Web IDE** is not visible: 1. Select the (**{chevron-lg-down}**) next to **Edit** or **Gitpod**, depending on your configuration. 1. Select **Open in Web IDE** from the list to display it as the editing option. 1. Select **Open in Web IDE** to open the editor. -- *When viewing a merge request* - + +### When viewing a merge request + 1. Go to your merge request. - 1. In the upper right corner, select **Code**, then select **Open in Gitpod**. + 1. In the upper right corner, select **Code > Open in Web IDE**. ## File finder @@ -86,7 +89,7 @@ You can pick a theme from your [profile preferences](../../profile/preferences.m ## Highlight lines -WebIDE is built with the [Web Editor](../repository/web_editor.md). This enables WebIDE to share the +The Web IDE is built with the [Web Editor](../repository/web_editor.md). This enables the Web IDE to share the same core features for highlighting and linking to particular lines in the edited files [described for the Web Editor](../repository/web_editor.md#highlight-lines). diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index dc448fed970..a3ba5789d39 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -15,7 +15,7 @@ Group wikis are similar to [project wikis](index.md), with a few limitations: - [Git LFS](../../../topics/git/lfs/index.md) is not supported. - Group wikis are not included in [global search](../../search/advanced_search.md). -- Changes to group wikis don't show up in the [group's activity feed](../../group/index.md#group-activity-analytics). +- Changes to group wikis don't show up in the [group's activity feed](../../group/manage.md#group-activity-analytics). - Group wikis are enabled by default for GitLab Premium and higher tiers. You [can't turn them off from the GitLab user interface](https://gitlab.com/gitlab-org/gitlab/-/issues/208413). diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 6e320923496..c7f675417bb 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -6,6 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Wiki **(FREE)** +> - Page loading [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/336792) to asynchronous in GitLab 14.9. +> - Page slug encoding method [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71753) to `ERB::Util.url_encode` in GitLab 14.9. + If you don't want to keep your documentation in your repository, but you want to keep it in the same project as your code, you can use the wiki GitLab provides in each GitLab project. Every wiki is a separate Git repository, so you can create @@ -230,7 +233,7 @@ GitLab tracks wiki creation, deletion, and update events. These events are displ - [User profile](../../profile/index.md#access-your-user-profile). - Activity pages, depending on the type of wiki: - - [Group activity](../../group/index.md#view-group-activity). + - [Group activity](../../group/manage.md#view-group-activity). - [Project activity](../working_with_projects.md#view-project-activity). Commits to wikis are not counted in [repository analytics](../../analytics/repository_analytics.md). @@ -337,7 +340,7 @@ Support includes: - List formatting for unordered, numbered, and checklists. - Creating and editing the structure of tables. - Inserting and formatting code blocks with syntax highlighting. -- Live preview of Mermaid, PlantUML, and Kroki diagrams ([Introduced]<https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86701> in GitLab 15.2). +- Live preview of Mermaid, PlantUML, and Kroki diagrams ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86701) in GitLab 15.2). ### Use the Content Editor @@ -370,3 +373,35 @@ For the status of the ongoing development for CommonMark and GitLab Flavored Mar - [Group repository storage moves API](../../../api/group_repository_storage_moves.md) - [Group wikis API](../../../api/group_wikis.md) - [Wiki keyboard shortcuts](../../shortcuts.md#wiki-pages) + +## Troubleshooting + +### Page slug rendering with Apache reverse proxy + +In GitLab 14.9 and later, page slugs are now encoded using the +[`ERB::Util.url_encode`](https://www.rubydoc.info/stdlib/erb/ERB%2FUtil.url_encode) method. +If you use an Apache reverse proxy, you can add a `nocanon` argument to the `ProxyPass` +line of your Apache configuration to ensure your page slugs render correctly. + +### Recreate a project wiki with the Rails console **(FREE SELF)** + +WARNING: +This operation deletes all data in the wiki. + +To clear all data from a project wiki and recreate it in a blank state: + +1. [Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). +1. Run these commands: + + ```ruby + # Enter your project's path + p = Project.find_by_full_path('<username-or-group>/<project-name>') + + # This command deletes the wiki project from the filesystem. + GitlabShellWorker.perform_in(0, :remove_repository, p.repository_storage, p.wiki.disk_path) + + # Refresh the wiki repository state. + p.wiki.repository.expire_exists_cache + ``` + +All data from the wiki has been cleared, and the wiki is ready for use. diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 9572bc241fc..2501fa8b45c 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -233,7 +233,7 @@ To push your repository and create a project: ``` - For `gitlab.example.com`, use the domain name of the machine that hosts your Git repository. - - For `namespace`, use the name of your [namespace](../group/index.md#namespaces). + - For `namespace`, use the name of your [namespace](../namespace/index.md). - For `myproject`, use the name of your project. - Optional. To export existing repository tags, append the `--tags` flag to your `git push` command. 1. Optional. To configure the remote: @@ -290,7 +290,7 @@ To view your personal projects: ## Delete a project After you delete a project, projects in personal namespaces are deleted immediately. To delay deletion of projects in a group -you can [enable delayed project removal](../group/index.md#enable-delayed-project-deletion). +you can [enable delayed project removal](../group/manage.md#enable-delayed-project-deletion). To delete a project: @@ -310,7 +310,7 @@ To delete a project: > - [Available to all users](https://gitlab.com/gitlab-org/gitlab/-/issues/346976) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `project_owners_list_project_pending_deletion`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/351556) in GitLab 14.9. [Feature flag `project_owners_list_project_pending_deletion`](https://gitlab.com/gitlab-org/gitlab/-/issues/351556) removed. -When delayed project deletion is [enabled for a group](../group/index.md#enable-delayed-project-deletion), +When delayed project deletion is [enabled for a group](../group/manage.md#enable-delayed-project-deletion), projects within that group are not deleted immediately, but only after a delay. To view a list of all projects that are pending deletion: @@ -371,7 +371,7 @@ To leave a project: 1. Select a project. 1. Select **Leave project**. The **Leave project** option only displays on the project dashboard when a project is part of a group under a -[group namespace](../group/index.md#namespaces). +[group namespace](../namespace/index.md). ## Use a project as a Go package diff --git a/doc/user/ssh.md b/doc/user/ssh.md index e884d762379..5667890757a 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -304,8 +304,10 @@ Verify that your SSH key was added correctly. The following commands use the example hostname `gitlab.example.com`. Replace this example hostname with your GitLab instance's hostname, for example, `git@gitlab.com`. -1. For GitLab.com, to ensure you're connecting to the correct server, confirm the - [SSH host keys fingerprints](gitlab_com/index.md#ssh-host-keys-fingerprints). +1. To ensure you're connecting to the correct server, check the server's SSH host keys fingerprint. For: + - GitLab.com, see the [SSH host keys fingerprints](gitlab_com/index.md#ssh-host-keys-fingerprints) documentation. + - GitLab.com or another GitLab instance, see `gitlab.example.com/help/instance_configuration#ssh-host-keys-fingerprints` where `gitlab.example.com` is `gitlab.com` (for + GitLab.com) or the address of the GitLab instance. 1. Open a terminal and run this command, replacing `gitlab.example.com` with your GitLab instance URL: diff --git a/doc/user/tasks.md b/doc/user/tasks.md index 36236f2969e..b5c2c4eb3a5 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -8,12 +8,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `work_items`. Disabled by default. > - [Creating, editing, and deleting tasks](https://gitlab.com/groups/gitlab-org/-/epics/7169) introduced in GitLab 15.0. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 15.3. + +WARNING: +Tasks are in [**Alpha**](../policy/alpha-beta-support.md#alpha-features). + +The following list are the known limitations: + +- [Tasks currently cannot be accessed via REST API.](https://gitlab.com/gitlab-org/gitlab/-/issues/368055) +- An issue's tasks can only currently be accessed via a reference within a description, comment, or direct URL (`.../-/work_items/[global_id]`). + +For the latest updates, check the [Tasks Roadmap](https://gitlab.com/groups/gitlab-org/-/epics/7103). FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `work_items`. -On GitLab.com, this feature is not available. -The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to [disable the feature flags](../administration/feature_flags.md) named `work_items` and `work_items_hierarchy`. +On GitLab.com, this feature is available. Use tasks to track steps needed for the [issue](project/issues/index.md) to be closed. diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index 6401828270d..1b267a0569b 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -83,7 +83,7 @@ You have the following options to help your users: - They can confirm their address through the email that they received. - They can confirm the subject email address themselves by navigating to `https://gitlab.example.com/users/confirmation/new`. -As an administrator, you may also confirm a user in the [Admin Area](admin_area/#administering-users). +As an administrator, you may also confirm a user in the [Admin Area](admin_area/index.md#administering-users). ## What do I do if I am an administrator and I am locked out? diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index c863a9d8270..5d78b4bb795 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -12,8 +12,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Namespace storage limit -Namespaces on a GitLab SaaS Free tier have a 5 GB storage limit. For more information, see our [pricing page](https://about.gitlab.com/pricing/). -This limit is not visible on the storage quota page, but we plan to make it visible and enforced starting October 19, 2022. +Namespaces on GitLab SaaS have a storage limit. For more information, see our [pricing page](https://about.gitlab.com/pricing/). +This limit is not visible on the Usage quotas page, but will be prior to [enforcement](#namespace-storage-limit-enforcement-schedule). Self-managed deployments are not affected. Storage types that add to the total namespace storage are: @@ -22,7 +22,7 @@ Storage types that add to the total namespace storage are: - Artifacts - Container registry - Package registry -- Dependecy proxy +- Dependency proxy - Wiki - Snippets @@ -30,27 +30,18 @@ If your total namespace storage exceeds the available namespace storage quota, a To prevent exceeding the namespace storage quota, you can: -1. [Purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer). -1. [Upgrade to a paid tier](../subscriptions/gitlab_com/#upgrade-your-gitlab-saas-subscription-tier). -1. [Reduce storage usage](#manage-your-storage-usage). +1. Reduce storage consumption by following the suggestions in the [Manage Your Storage Usage](#manage-your-storage-usage) section of this page. +1. Apply for [GitLab for Education](https://about.gitlab.com/solutions/education/join/), [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/join/), or [GitLab for Startups](https://about.gitlab.com/solutions/startups/) if you meet the eligibility requirements. +1. Consider using a [self-managed instance](../subscriptions/self_managed/) of GitLab which does not have these limits on the free tier. +1. [Purchase additional storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) units at $60/year for 10GB of storage. +1. [Start a trial](https://about.gitlab.com/free-trial/) or [upgrade to GitLab Premium or Ultimate](https://about.gitlab.com/pricing) which include higher limits and features that enable growing teams to ship faster without sacrificing on quality. +1. [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) to learn more about your options and ask questions. ### Namespace storage limit enforcement schedule -Starting October 19, 2022, a storage limit will be enforced on all GitLab Free namespaces. -We will start with a large limit enforcement and eventually reduce it to 5 GB. +Storage limits for GitLab SaaS Free tier namespaces will not be enforced prior to 2022-10-19. Storage limits for GitLab SaaS Paid tier namespaces will not be enforced for prior to 2023-02-15. -The following table describes the enforcement schedule, which is subject to change. - -| Target enforcement date | Limit | Expected Impact | Status | -| ------ | ------ | ------ | ------ | -| October 19, 2022 | 45,000 GB | LOW | Pending (**{hourglass}**)| -| October 20, 2022 | 7,500 GB | LOW | Pending (**{hourglass}**)| -| October 24, 2022 | 500 GB | MEDIUM | Pending (**{hourglass}**)| -| October 27, 2022 | 75 GB | MEDIUM HIGH | Pending (**{hourglass}**)| -| November 2, 2022 | 10 GB | HIGH | Pending (**{hourglass}**)| -| November 9, 2022 | 5 GB | VERY HIGH | Pending (**{hourglass}**)| - -Namespaces that reach the enforced limit will have their projects locked. To unlock your project, you will have to [manage its storage](#manage-your-storage-usage). +Impacted users are notified via email and in-app notifications at least 60 days prior to enforcement. ### Project storage limit @@ -67,7 +58,7 @@ you must purchase additional storage. For more details, see [Excess storage usag ## View storage usage -You can view storage usage for your project or [namespace](../user/group/#namespaces). +You can view storage usage for your project or [namespace](../user/namespace/index.md). 1. Go to your project or namespace: - For a project, on the top bar, select **Menu > Projects** and find your project. diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index 0ef3eb8b6fe..1c5a77c1f0c 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -17,14 +17,14 @@ sole discretion of GitLab Inc. NOTE: Workspace is currently in development. -Workspace will be above the [top-level namespaces](../group/index.md#namespaces) for you to manage +Workspace will be above the [top-level namespaces](../namespace/index.md) for you to manage everything you do as a GitLab administrator, including: - Defining and applying settings to all of your groups, subgroups, and projects. - Aggregating data from all your groups, subgroups, and projects. Our goal is to reach feature parity between SaaS and self-managed installations, with all -[Admin Area settings](/ee/user/admin_area/settings/) moving to either: +[Admin Area settings](/ee/user/admin_area/settings/index.md) moving to either: - Groups. Available in the Workspace, top-level group namespaces, and sub-groups. - Hardware Controls. For functionality that does not apply to groups, Hardware Controls are only |
