diff options
Diffstat (limited to 'doc/user')
186 files changed, 3251 insertions, 1089 deletions
diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index 8f629fd4250..80108fba060 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -38,7 +38,7 @@ collected before this feature is available. ## DevOps Adoption **(ULTIMATE)** -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). The DevOps Adoption tab shows you which segments of your organization are using the most essential features of GitLab: @@ -50,7 +50,9 @@ The DevOps Adoption tab shows you which segments of your organization are using - Deploys - Scanning -Segments are arbitrary collections of GitLab groups that you define. You might define a segment to represent a small team, a large department, or a whole organization. You are limited to creating a maximum of 20 segments, and each segment is limited to a maximum of 20 groups. Buttons to manage your segments appear in the DevOps Adoption section of the page. +Segments are arbitrary collections of GitLab groups that you define. You might define a segment to represent a small team, a large department, or a whole organization. +You are limited to creating a maximum of 20 segments, and each segment is limited to a maximum of 20 groups. +Buttons to manage your segments appear in the DevOps Adoption section of the page. DevOps Adoption allows you to: @@ -62,18 +64,18 @@ DevOps Adoption allows you to: ### Disable or enable DevOps Adoption -DevOps Adoption is deployed behind a feature flag that is **enabled by default**. +DevOps Adoption is deployed behind a feature flag that is **disabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. +can opt to enable it. -To disable it: +To enable it: ```ruby -Feature.disable(:devops_adoption_feature) +Feature.enable(:devops_adoption_feature) ``` -To enable it: +To disable it: ```ruby -Feature.enable(:devops_adoption_feature) +Feature.disable(:devops_adoption_feature) ``` diff --git a/doc/user/admin_area/analytics/user_cohorts.md b/doc/user/admin_area/analytics/user_cohorts.md index 1d2d0029860..7adc9ad59a5 100644 --- a/doc/user/admin_area/analytics/user_cohorts.md +++ b/doc/user/admin_area/analytics/user_cohorts.md @@ -6,32 +6,31 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Cohorts **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/23361) in GitLab 9.1. - As a benefit of having the [usage ping active](../settings/usage_statistics.md), -GitLab lets you analyze the users' activities over time of your GitLab installation. +you can analyze your users' GitLab activities over time. -To see User Cohorts, go to **Admin Area > Analytics > Cohorts**. +To see user cohorts, go to **Admin Area > Analytics > Cohorts**. ## Overview -How do we read the user cohorts table? Let's take an example with the following -user cohorts. +How do you interpret the user cohorts table? Let's review an example with the +following user cohorts:  -For the cohort of March 2020, three users have been added on this server and have -been active since this month. One month later, in April 2020, two users are -still active. Five months later (August), we can see that one user from this cohort -is active, or 33% of the original cohort of three that joined in March. +For the cohort of March 2020, three users were added to this server and have +been active since this month. One month later (April 2020), two users are still +active. Five months later (August 2020), one user from this cohort is still +active, or 33% of the original cohort of three that joined in March. -The Inactive users column shows the number of users who have been added during -the month, but who have never actually had any activity in the instance. +The **Inactive users** column shows the number of users who were added during +the month, but who never had any activity in the instance. How do we measure the activity of users? GitLab considers a user active if: - The user signs in. - The user has Git activity (whether push or pull). -- The user visits pages related to Dashboards, Projects, Issues, and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54947) in GitLab 11.8). -- The user uses the API -- The user uses the GraphQL API +- The user visits pages related to dashboards, projects, issues, or merge + requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54947) in GitLab 11.8). +- The user uses the API. +- The user uses the GraphQL API. diff --git a/doc/user/admin_area/img/license_admin_area.png b/doc/user/admin_area/img/license_admin_area.png Binary files differdeleted file mode 100644 index b5662b81c5e..00000000000 --- a/doc/user/admin_area/img/license_admin_area.png +++ /dev/null diff --git a/doc/user/admin_area/img/license_upload.png b/doc/user/admin_area/img/license_upload.png Binary files differdeleted file mode 100644 index 29d55175a2d..00000000000 --- a/doc/user/admin_area/img/license_upload.png +++ /dev/null diff --git a/doc/user/admin_area/img/license_upload_v13_8.png b/doc/user/admin_area/img/license_upload_v13_8.png Binary files differnew file mode 100644 index 00000000000..c15bc2bfa02 --- /dev/null +++ b/doc/user/admin_area/img/license_upload_v13_8.png diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index d7710c362e5..d06b0c844ec 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -32,7 +32,7 @@ is locked. ## Uploading your license -The very first time you visit your GitLab EE installation signed in as an administrator, +The first time you visit your GitLab EE installation signed in as an administrator, you should see a note urging you to upload a license with a link that takes you to **Admin Area > License**. @@ -42,18 +42,21 @@ Otherwise, you can: 1. Navigate to the **License** tab, and click **Upload New License**. -  + - *If you've received a `.gitlab-license` file:* + 1. Download the license file to your local machine. + 1. Select **Upload `.gitlab-license` file**. + 1. Select **Choose File** and select the license file. + In this example the license file is named `GitLab.gitlab-license`. + 1. Check the **Subscription Agreement** checkbox. + 1. Select **Upload License**. - - *If you've received a `.gitlab-license` file,* you should have already downloaded - it in your local machine. You can then upload it directly by choosing the - license file and clicking the **Upload license** button. In the image below, - the selected license file is named `GitLab.gitlab-license`. +  -  - - - *If you've received your license as plain text,* select the - **Enter license key** option, copy the license, paste it into the **License key** - field, and click **Upload license**. + - *If you've received your license as plain text:* + 1. Select **Enter license key**. + 1. Copy the license and paste it into the **License key** field. + 1. Check the **Subscription Agreement** checkbox. + 1. Select **Upload License**. ## Add your license at install time @@ -120,6 +123,11 @@ You can upload and view more than one license, but only the latest license in th range is used as the active license. When you upload a future-dated license, it doesn't take effect until its applicable date. +NOTE: +In GitLab 13.6 and earlier, a notification banner about an expiring license may continue to be displayed even after a new license has been uploaded. +This happens when the newly uploaded license's start date is in the future and the expiring one is still active. +The banner disappears after the new license becomes active. + ## Troubleshooting ### There is no License tab in the Admin Area 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 bc266216714..028858c96f6 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -7,10 +7,18 @@ type: reference # Account and limit settings **(CORE ONLY)** +## Default projects limit + +You can change the default maximum number of projects that users can create in their personal namespace. +Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. +You can increase or decrease that `Default projects limit` value. + +- If you set `Default projects limit` to 0, users are not allowed to create projects in their users personal namespace. However, projects can still be created within a group. + ## Max attachment size You can change the maximum file size for attachments in comments and replies in GitLab. -Navigate to **Admin Area (wrench icon) > Settings > General**, then expand **Account and Limit**. +Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. From here, you can increase or decrease by changing the value in `Maximum attachment size (MB)`. NOTE: @@ -21,13 +29,13 @@ details. ## Max push size You can change the maximum push size for your repository. -Navigate to **Admin Area (wrench icon) > Settings > General**, then expand **Account and Limit**. +Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. From here, you can increase or decrease by changing the value in `Maximum push size (MB)`. ## Max import size You can change the maximum file size for imports in GitLab. -Navigate to **Admin Area (wrench icon) > Settings > General**, then expand **Account and Limit**. +Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. From here, you can increase or decrease by changing the value in `Maximum import size (MB)`. NOTE: diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index ef2eb046c21..6418be13ee9 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -174,7 +174,7 @@ but commented out to help encourage others to add to it in the future. --> WARNING: This feature is being re-evaluated in favor of a different -[compliance solution](https://gitlab.com/gitlab-org/gitlab/-/issues/34830). +[compliance solution](https://gitlab.com/groups/gitlab-org/-/epics/3156). We recommend that users who haven't yet implemented this feature wait for the new solution. @@ -187,6 +187,12 @@ sourced from: - The [instance template repository](instance_template_repository.md). - GitLab-supplied configuration. +NOTE: +When you use a configuration defined in an instance template repository, +nested [`include:`](../../../ci/yaml/README.md#include) keywords +(including `include:file`, `include:local`, `include:remote`, and `include:template`) +[do not work](https://gitlab.com/gitlab-org/gitlab/-/issues/35345). + To set required pipeline configuration: 1. Go to **Admin Area > Settings > CI/CD**. diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index a7641ec22ca..9a661fa9716 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -38,7 +38,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | [PlantUML](../../../administration/integration/plantuml.md#gitlab) | Allow rendering of PlantUML diagrams in AsciiDoc and Markdown documents. | | [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) **(FREE ONLY)** | Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). | | [Third party offers](third_party_offers.md) | Control the display of third party offers. | -| [Snowplow](../../../development/product_analytics/snowplow.md) | Configure the Snowplow integration. | +| [Snowplow](../../../development/snowplow.md) | Configure the Snowplow integration. | | [Google GKE](../../project/clusters/add_gke_clusters.md) | Google GKE integration allows you to provision GKE clusters from GitLab. | | [Amazon EKS](../../project/clusters/add_eks_clusters.md) | Amazon EKS integration allows you to provision EKS clusters from GitLab. | diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index fe4e84b98ac..adb192f5b4a 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -51,6 +51,14 @@ is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). This would allo administrators to update settings inherited by groups and projects without enabling the integration on all non-configured groups and projects by default. +### Remove an instance-level default setting + +1. Navigate to **Admin Area > Settings > Integrations**. +1. Select an integration. +1. Click **Reset** and confirm. + +Resetting an instance-level default setting removes the integration from all projects that have the integration set to use default settings. + ## Manage group-level default settings for a project integration > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6. @@ -86,6 +94,14 @@ is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). This would allo administrators to update settings inherited by subgroups and projects without enabling the integration on all non-configured groups and projects by default. +### Remove a group-level default setting + +1. Navigate to the group's **Settings > Integrations**. +1. Select an integration. +1. Click **Reset** and confirm. + +Resetting a group-level default setting removes integrations that use default settings and belong to a project or subgroup of the group. + ## Use instance-level or group-level default settings for a project integration > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6 for group-level settings. diff --git a/doc/user/admin_area/settings/protected_paths.md b/doc/user/admin_area/settings/protected_paths.md index 870735f5be7..a03156511e2 100644 --- a/doc/user/admin_area/settings/protected_paths.md +++ b/doc/user/admin_area/settings/protected_paths.md @@ -28,11 +28,7 @@ GitLab rate limits the following paths with Rack Attack by default: GitLab responds with HTTP status code `429` to POST requests at protected paths that exceed 10 requests per minute per IP address. -This header is included in responses to blocked requests: - -```plaintext -Retry-After: 60 -``` +See [User and IP rate limits](../../admin_area/settings/user_and_ip_rate_limits.md#response-headers) for the headers responded to blocked requests. For example, the following are limited to a maximum 10 requests per minute: diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 02b1428177f..06b39d67228 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -61,13 +61,12 @@ sequenceDiagram ## Usage Ping **(CORE ONLY)** -See [Usage Ping guide](../../../development/product_analytics/usage_ping.md). +See [Usage Ping guide](../../../development/usage_ping.md). -## Instance-level statistics **(CORE ONLY)** +## Instance-level analytics availability After usage ping is enabled, GitLab gathers data from other instances and -can show [usage statistics](../analytics/index.md) -of your instance to your admins in **Admin Area > Analytics**. +enables certain [instance-level analytics features](../analytics/index.md) that are dependent on usage ping. <!-- ## Troubleshooting 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 3f0d75dc682..e2040ef19d6 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 @@ -20,8 +20,42 @@ IP rate limits**: These limits are disabled by default. +NOTE: +By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations +may trigger the rate limits configured for unauthenticated requests. +  +## Response text + +A request that exceeds a rate limit returns a 429 response code and a +plain-text body, which by default is: + +```plaintext +Retry later +``` + +It is possible to customize this response text in the Admin Area. + +## Response headers + +> [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/731) in GitLab 13.8, the `Rate-Limit` headers. `Retry-After` was introduced in an earlier version. + +When a client exceeds the associated rate limit, the following requests are +blocked. The server may respond with rate-limiting information allowing the +requester to retry after a specific period of time. These information are +attached into the response headers. + +| Header | Example | Description | +|:----------------------|:--------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `RateLimit-Limit` | `60` | The request quota for the client **each minute**. If the rate limit period set in the admin area is different from 1 minute, the value of this header is adjusted to approximately the nearest 60-minute period. | +| `RateLimit-Name` | `throttle_authenticated_web` | Name of the throttle blocking the requests. | +| `RateLimit-Observed` | `67` | Number of requests associated to the client in the time window. | +| `RateLimit-Remaining` | `0` | Remaining quota in the time window. The result of `RateLimit-Limit` - `RateLimit-Remaining`. | +| `RateLimit-Reset` | `1609844400` | [Unix time](https://en.wikipedia.org/wiki/Unix_time)-formatted time when the request quota is reset. | +| `RateLimit-ResetTime` | `Tue, 05 Jan 2021 11:00:00 GMT` | [RFC2616](https://tools.ietf.org/html/rfc2616#section-3.3.1)-formatted date and time when the request quota is reset. | +| `Retry-After` | `30` | Remaining duration **in seconds** until the quota is reset. This is a [standard HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). | + ## Use an HTTP header to bypass rate limiting > [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/622) in GitLab 13.6. @@ -47,7 +81,7 @@ GitLab. For example: in `/etc/default/gitlab`. It is important that your load balancer erases or overwrites the bypass -header on all incoming traffic, because otherwise you must trust your +header on all incoming traffic. Otherwise, you must trust your users to not set that header and bypass the GitLab rate limiter. Note that the bypass only works if the header is set to `1`. @@ -59,7 +93,9 @@ are marked with `"throttle_safelist":"throttle_bypass_header"` in To disable the bypass mechanism, make sure the environment variable `GITLAB_THROTTLE_BYPASS_HEADER` is unset or empty. -## Allowing specific users to bypass authenticated request rate limiting +## Allow specific users to bypass authenticated request rate limiting + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49127) in GitLab 13.7. Similarly to the bypass header described above, it is possible to allow a certain set of users to bypass the rate limiter. This only applies @@ -82,13 +118,12 @@ are marked with `"throttle_safelist":"throttle_user_allowlist"` in At application startup, the allowlist is logged in [`auth.log`](../../../administration/logs.md#authlog). -## Trying out throttling settings before enforcing them +## Try out throttling settings before enforcing them > [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/629) in GitLab 13.6. -Trying out throttling settings can be done by setting the -`GITLAB_THROTTLE_DRY_RUN` environment variable to a comma-separated -list of throttle names. +You can try out throttling settings by setting the `GITLAB_THROTTLE_DRY_RUN` environment variable to +a comma-separated list of throttle names. The possible names are: @@ -99,21 +134,19 @@ The possible names are: - `throttle_authenticated_protected_paths_api` - `throttle_authenticated_protected_paths_web` -For example: trying out throttles for all authenticated requests to -non-protected paths could be done by setting +For example, to try out throttles for all authenticated requests to +non-protected paths can be done by setting `GITLAB_THROTTLE_DRY_RUN='throttle_authenticated_web,throttle_authenticated_api'`. -To enable the dry-run mode for all throttles, the variable can be set -to `*`. +To enable dry run mode for all throttles, the variable can be set to `*`. -Setting a throttle to dry-run mode will log a message to the -[`auth.log`](../../../administration/logs.md#authlog) when it would -hit the limit, while letting the request continue as normal. The log -message will contain an `env` field set to `track`. The `matched` -field will contain the name of throttle that was hit. +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 +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. It is important to set the environment variable **before** enabling -the rate limiting in the settings. The settings in the admin panel +the rate limiting in the settings. The settings in the Admin Area take effect immediately, while setting the environment variable requires a restart of all the Puma processes. diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md new file mode 100644 index 00000000000..beb2cbfdc58 --- /dev/null +++ b/doc/user/analytics/ci_cd_analytics.md @@ -0,0 +1,33 @@ +--- +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 +--- + +# CI/CD Analytics + +## Pipeline success and duration charts **(CORE)** + +> - Introduced in GitLab 3.1.1 as Commit Stats, and later renamed to Pipeline Charts. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/38318) to CI/CD Analytics in GitLab 12.8. + +GitLab tracks the history of your pipeline successes and failures, as well as how long each pipeline +ran. To view this information, go to **Analytics > CI/CD Analytics**. + +View successful pipelines: + + + +View pipeline duration history: + + + +## Deployment frequency charts **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.8. + +The **Analytics > CI/CD Analytics** page shows information about the deployment frequency to the +`production` environment. The environment **must** be named `production` for its deployment +information to appear on the graphs. + + diff --git a/doc/user/analytics/img/deployment_frequency_chart_v13_8.png b/doc/user/analytics/img/deployment_frequency_chart_v13_8.png Binary files differnew file mode 100644 index 00000000000..40dd2fa0321 --- /dev/null +++ b/doc/user/analytics/img/deployment_frequency_chart_v13_8.png diff --git a/doc/user/analytics/img/pipelines_duration_chart.png b/doc/user/analytics/img/pipelines_duration_chart.png Binary files differnew file mode 100644 index 00000000000..12ec262dadb --- /dev/null +++ b/doc/user/analytics/img/pipelines_duration_chart.png diff --git a/doc/user/analytics/img/pipelines_success_chart.png b/doc/user/analytics/img/pipelines_success_chart.png Binary files differnew file mode 100644 index 00000000000..f44dc25ff1c --- /dev/null +++ b/doc/user/analytics/img/pipelines_success_chart.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index adfd09d8526..caa8972b220 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -33,7 +33,7 @@ The following analytics features are available at the group level: The following analytics features are available at the project level: -- [CI/CD](../../ci/pipelines/index.md#pipeline-success-and-duration-charts). **(STARTER)** +- [CI/CD](ci_cd_analytics.md). **(CORE)** - [Code Review](code_review_analytics.md). **(STARTER)** - [Insights](../project/insights/index.md). **(ULTIMATE)** - [Issue](../group/issues_analytics/index.md). **(PREMIUM)** diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 09e38d5048f..674afcb29ee 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -157,6 +157,7 @@ You can use various tools to generate HAR files: - [Insomnia Core](https://insomnia.rest/): API client - [Chrome](https://www.google.com/chrome/): Browser - [Firefox](https://www.mozilla.org/en-US/firefox/): Browser +- [GitLab HAR Recorder](https://gitlab.com/gitlab-org/security-products/har-recorder): Command line WARNING: HAR files may contain sensitive information such as authentication tokens, API keys, and session diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 0a5a0c3a565..469945246c1 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -29,8 +29,10 @@ Docker image with the fuzz engine to run your app. | GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example) | | Swift | [libfuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | | Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | [rust-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/rust-fuzzing-example) | -| Java | [JQF](https://github.com/rohanpadhye/JQF) | [java-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | | Java | [javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | +| Java | [JQF](https://github.com/rohanpadhye/JQF) (not preferred) | [jqf-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | +| JavaScript | [jsfuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/jsfuzz)| [jsfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/jsfuzz-fuzzing-example) | +| Python | [pythonfuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/pythonfuzz)| [pythonfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/pythonfuzz-fuzzing-example) | ## Configuration diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index f4401fa6445..395a8702d1b 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -86,6 +86,20 @@ variables: DAST_WEBSITE: https://example.com ``` +### Latest template + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254325) in GitLab 13.8 + +To use the latest version of the DAST template, include +`DAST.latest.gitlab-ci.yml` instead of `DAST.gitlab-ci.yml`. +See the CI [docs](../../../development/cicd/templates.md#latest-version) +on template versioning for more information. + +Please note that the latest version may include breaking changes. Check the +[DAST troubleshooting guide](#troubleshooting) if you experience problems. + +### Template options + There are two ways to define the URL to be scanned by DAST: 1. Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables). @@ -183,6 +197,10 @@ To create masked variables for the username and password, see [Create a custom v Note that the key of the username variable must be `DAST_USERNAME` and the key of the password variable must be `DAST_PASSWORD`. +After DAST has authenticated with the application, all cookies are collected from the web browser. +For each cookie a matching session token is created for use by ZAP. This ensures ZAP is recognized +by the application as correctly authenticated. + Other variables that are related to authenticated scans are: ```yaml @@ -196,7 +214,8 @@ variables: DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form DAST_SUBMIT_FIELD: login # the `id` or `name` of the element that when clicked will submit the login form or the password form of a multi-page login process DAST_FIRST_SUBMIT_FIELD: next # the `id` or `name` of the element that when clicked will submit the username form of a multi-page login process - DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between + DAST_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between + DAST_AUTH_VALIDATION_URL: http://example.com/loggedin_page # optional, a URL only accessible to logged in users that DAST can use to confirm successful authentication ``` The results are saved as a @@ -544,12 +563,14 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `DAST_API_SPECIFICATION` | 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. `DAST_WEBSITE` must be specified if this is omitted. | | `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | | `DAST_AUTH_URL` | 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. | +| `DAST_AUTH_VALIDATION_URL` | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST will exit if it cannot access the URL. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. | `DAST_USERNAME` | string | The username to authenticate to in the website. | | `DAST_PASSWORD` | string | The password to authenticate to in the website. | | `DAST_USERNAME_FIELD` | string | The name of username field at the sign-in HTML form. | | `DAST_PASSWORD_FIELD` | string | The name of password field at the sign-in HTML form. | +| `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | | `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | -| `DAST_AUTH_EXCLUDE_URLS` | 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_EXCLUDE_URLS` | 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. In [GitLab 13.7 and earlier](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/367), was `DAST_AUTH_EXCLUDE_URLS` (which we plan to support until GitLab 14.0). | | `DAST_FULL_SCAN_ENABLED` | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | Set to `true` to require [domain validation](#domain-validation) when running DAST full scans. Not supported for API scans. Default: `false` | | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | @@ -701,6 +722,49 @@ security reports without requiring internet access. Alternatively, you can use the variable `SECURE_ANALYZERS_PREFIX` to override the base registry address of the `dast` image. +## On-demand scans + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. + +An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger +the scan. You must start it manually. + +An on-demand DAST scan: + +- Uses settings in the site profile and scanner profile you select when you run the scan, + instead of those in the `.gitlab-ci.yml` file. +- Is associated with your project's default branch. + +### On-demand scan modes + +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). + +### Run an on-demand DAST scan + +NOTE: +You must have permission to run an on-demand DAST scan against a protected branch. +The default branch is automatically protected. For more information, see +[Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). + +To run an on-demand DAST scan, you need: + +- A [scanner profile](#create-a-scanner-profile). +- A [site profile](#create-a-site-profile). +- If you are running an active scan the site profile must be [validated](#validate-a-site-profile). + +1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. +1. In **Scanner profile**, select a scanner profile from the dropdown. +1. In **Site profile**, select a site profile from the dropdown. +1. Click **Run scan**. + +The on-demand DAST scan runs and the project's dashboard shows the results. + ## Site profile A site profile describes the attributes of a web site to scan on demand with DAST. A site profile is @@ -711,31 +775,115 @@ A site profile contains the following: - **Profile name**: A name you assign to the site to be scanned. - **Target URL**: The URL that DAST runs against. +## Site profile validation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. + +Site profile validation reduces the risk of running an active scan against the wrong website. A site +must be validated before an active scan can run against it. The site validation methods are as +follows: + +- _Text file validation_ requires a text file be uploaded to the target site. The text file is + allocated a name and content that is unique to the project. The validation process checks the + file's content. +- _Header validation_ requires the header `Gitlab-On-Demand-DAST` be added to the target site, + with a value unique to the project. The validation process checks that the header is present, and + checks its value. + +Both methods are equivalent in functionality. Use whichever is feasible. + ### Create a site profile To create a site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Click **Manage** in the **DAST Profiles** row. -1. Click **New Profile > Site Profile**. -1. Type in a unique **Profile name** and **Target URL** then click **Save profile**. +1. Select **Manage** in the **DAST Profiles** row. +1. Select **New Profile > Site Profile**. +1. Type in a unique **Profile name** and **Target URL** then select **Save profile**. ### Edit a site profile To edit an existing site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Click **Manage** in the **DAST Profiles** row. -1. Click **Edit** in the row of the profile to edit. -1. Edit the **Profile name** and **Target URL**, then click **Save profile**. +1. Select **Manage** in the **DAST Profiles** row. +1. Select **Edit** in the row of the profile to edit. +1. Edit the **Profile name** and **Target URL**, then select **Save profile**. ### Delete a site profile To delete an existing site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Click **Manage** in the **DAST Profiles** row. -1. Click **{remove}** (Delete profile) in the row of the profile to delete. +1. Select **Manage** in the **DAST Profiles** row. +1. Select **{remove}** (Delete profile) in the row of the profile to delete. + +### Validate a site profile + +To validate a site profile: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Select **Manage** in the **DAST Profiles** row. +1. Select **Validate target site** beside the profile to validate. +1. Select the validation method. + 1. For **Text file validation**: + 1. Download the validation file listed in **Step 2**. + 1. Upload the validation file to the host. You can upload the file to the location in + **Step 3** or any location you prefer. + 1. Select **Validate**. + 1. For **Header validation**: + 1. Select the clipboard icon in **Step 2**. + 1. Edit the header of the site to validate, and paste the clipboard content. + 1. Select the input field in **Step 3** and enter the location of the header. + 1. Select **Validate**. + +The site is validated and an active scan can run against it. + +If a validated site profile's target URL is edited, the site is no longer validated. + +#### Validated site profile headers + +The following are code samples of how you could provide the required site profile header in your +application. + +##### Ruby on Rails example for on-demand scan + +Here's how you can add a custom header in a Ruby on Rails application: + +```ruby +class DastWebsiteTargetController < ActionController::Base + def dast_website_target + response.headers['Gitlab-On-Demand-DAST'] = '0dd79c9a-7b29-4e26-a815-eaaf53fcab1c' + head :ok + end +end +``` + +##### Django example for on-demand scan + +Here's how you can add a +[custom header in Django](https://docs.djangoproject.com/en/2.2/ref/request-response/#setting-header-fields): + +```python +class DastWebsiteTargetView(View): + def head(self, *args, **kwargs): + response = HttpResponse() + response['Gitlab-On-Demand-DAST'] = '0dd79c9a-7b29-4e26-a815-eaaf53fcab1c' + + return response +``` + +##### Node (with Express) example for on-demand scan + +Here's how you can add a +[custom header in Node (with Express)](http://expressjs.com/en/5x/api.html#res.append): + +```javascript +app.get('/dast-website-target', function(req, res) { + res.append('Gitlab-On-Demand-DAST', '0dd79c9a-7b29-4e26-a815-eaaf53fcab1c') + res.send('Respond to DAST ping') +}) +``` ## Scanner profile @@ -779,40 +927,6 @@ To delete a scanner profile: 1. Click **Manage** in the **DAST Profiles** row. 1. Click **{remove}** (Delete profile) in the scanner profile's row. -## On-demand scans - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. - -An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger -the scan. You must start it manually. - -An on-demand DAST scan: - -- Uses settings in the site profile and scanner profile you select when you run the scan, - instead of those in the `.gitlab-ci.yml` file. -- Is associated with your project's default branch. - -### Run an on-demand DAST scan - -NOTE: -You must have permission to run an on-demand DAST scan against a protected branch. -The default branch is automatically protected. For more information, see -[Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). - -To run an on-demand DAST scan, you need: - -- A [scanner profile](#create-a-scanner-profile). -- A [site profile](#create-a-site-profile). - -1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. -1. Click **Create new DAST scan**. -1. In **Scanner profile**, select a scanner profile from the dropdown. -1. In **Site profile**, select a site profile from the dropdown. -1. Click **Run scan**. - -The on-demand DAST scan runs and the project's dashboard shows the results. - ## Reports The DAST tool outputs a report file in JSON format by default. However, this tool can also generate reports in @@ -940,6 +1054,25 @@ If your DAST job exceeds the job timeout and you need to reduce the scan duratio For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). +### Getting error `dast job: chosen stage does not exist` when including DAST CI template + +Newer versions of the DAST CI template do not define stages in order to avoid +overwriting stages from other CI files. If you've recently started using +`DAST.latest.gitlab-ci.yml` or upgraded to a new major release of GitLab and +began receiving this error, you will need to define a `dast` stage with your +other stages. Please note that you must have a running application for DAST to +scan. If your application is set up in your pipeline, it must be deployed + in a stage _before_ the `dast` stage: + +```yaml +stages: + - deploy # DAST needs a running application to scan + - dast + +include: + - template: DAST.latest.gitlab-ci.yml +``` + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 07774f51958..cecf818edfc 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -64,16 +64,19 @@ The following languages and dependency managers are supported: | [Conan](https://conan.io/) | C, C++ | [`conan.lock`](https://docs.conan.io/en/latest/versioning/lockfiles.html) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [Golang](https://golang.org/) | Go | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | Java | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) | +| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package.json` | [Retire.js](https://retirejs.github.io/retire.js/) | | [NuGet](https://www.nuget.org/) 4.9+ | .NET, C# | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [setuptools](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [setuptools](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) (*1*) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile`, `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [sbt](https://www.scala-sbt.org/) 1.2 and below ([Ivy](http://ant.apache.org/ivy/)) | Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +1. [Pipenv](https://pipenv.pypa.io/en/latest/) projects are scanned when a `Pipfile` is present. + Gemnasium scans the exact package versions listed in `Pipfile.lock` when this file is also present. + Plans are underway for supporting the following languages, dependency managers, and dependency files. For details, see the issue link for each. | Package Managers | Languages | Supported files | Scan tools | Issue | | ------------------- | --------- | --------------- | ---------- | ----- | -| [Pipenv](https://pipenv.pypa.io/en/latest/) | Python | `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#11756](https://gitlab.com/gitlab-org/gitlab/-/issues/11756) | | [Poetry](https://python-poetry.org/) | Python | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/-/issues/7006) | | [sbt](https://www.scala-sbt.org/) 1.3+ ([Coursier](https://get-coursier.io/))| Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#271345](https://gitlab.com/gitlab-org/gitlab/-/issues/271345) | @@ -115,7 +118,7 @@ include: - template: Dependency-Scanning.gitlab-ci.yml variables: - DS_PYTHON_VERSION: 2 + SECURE_LOG_LEVEL: error ``` Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline @@ -489,7 +492,7 @@ ensure that it can reach your private repository. Here is an example configurati ### Referencing local dependencies using a path in JavaScript projects The [Retire.js](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js) analyzer -doesn't support dependency references made with [local paths](https://docs.npmjs.com/files/package.json#local-paths) +doesn't support dependency references made with [local paths](https://docs.npmjs.com/cli/v6/configuring-npm/package-json#local-paths) in the `package.json` of JavaScript projects. The dependency scan outputs the following error for such references: @@ -504,7 +507,7 @@ As a workaround, remove the [`retire.js`](analyzers.md#selecting-specific-analyz ### `Error response from daemon: error processing tar file: docker-tar: relocation error` -This error occurs when the Docker version that runs the dependency scanning job is `19.03.00`. +This error occurs when the Docker version that runs the dependency scanning job is `19.03.0`. Consider updating to Docker `19.03.1` or greater. Older versions are not affected. Read more in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 15412473ab1..1f0b461c91b 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -68,6 +68,10 @@ the official analyzers. ### Selecting specific analyzers +WARNING: +`SAST_DEFAULT_ANALYZERS` is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50872) in GitLab 13.8, +and is scheduled for [removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/290777). + You can select the official analyzers you want to run. Here's how to enable `bandit` and `flawfinder` while disabling all the other default ones. In `.gitlab-ci.yml` define: @@ -83,9 +87,9 @@ variables: `bandit` runs first. When merging the reports, SAST removes the duplicates and keeps the `bandit` entries. -### Disabling default analyzers +### Disabling all default analyzers -Setting `SAST_DEFAULT_ANALYZERS` to an empty string disables all the official +Setting `SAST_DISABLED` to `true` disables all the official default analyzers. In `.gitlab-ci.yml` define: ```yaml @@ -93,11 +97,25 @@ include: - template: Security/SAST.gitlab-ci.yml variables: - SAST_DEFAULT_ANALYZERS: "" + SAST_DISABLED: true ``` That's needed when one totally relies on [custom analyzers](#custom-analyzers). +### Disabling specific default analyzers + +Set `SAST_EXCLUDED_ANALYZERS` to a comma-delimited string that includes the official +default analyzers that you want to avoid running. In `.gitlab-ci.yml` define the +following to prevent the `eslint` analyzer from running: + +```yaml +include: + - template: Security/SAST.gitlab-ci.yml + +variables: + SAST_EXCLUDED_ANALYZERS: "eslint" +``` + ## Custom Analyzers You can provide your own analyzers by diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index fb3bc256e11..59887c95c67 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -431,7 +431,8 @@ The following are Docker image-related variables. |---------------------------|---------------------------------------------------------------------------------------------------------------------------------------| | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `SAST_ANALYZER_IMAGE_TAG` | **DEPRECATED:** Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md). | -| `SAST_DEFAULT_ANALYZERS` | Override the names of default images. Read more about [customizing analyzers](analyzers.md). | +| `SAST_DEFAULT_ANALYZERS` | **DEPRECATED:** Override the names of default images. Scheduled for [removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/290777). | +| `SAST_EXCLUDED_ANALYZERS` | Names of default images that should never run. Read more about [customizing analyzers](analyzers.md). | #### Vulnerability filters @@ -511,7 +512,7 @@ The SAST 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/sast-report-format.json). The JSON report file can be downloaded from the CI pipelines page, or the -pipelines tab on merge requests. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md). +pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/pipelines/job_artifacts.md#defining-artifacts-in-gitlab-ciyml) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md). Here's an example SAST report: @@ -727,3 +728,25 @@ against the given glob pattern. If the number of matches exceeds the maximum, th parameter returns `true`. Depending on the number of files in your repository, a SAST job might be triggered even if the scanner doesn't support your project. For more details about this issue, see the [`rules:exists` documentation](../../../ci/yaml/README.md#rulesexists). + +### SpotBugs UTF-8 unmappable character errors + +These errors occur when UTF-8 encoding isn't enabled on a SpotBugs build and there are UTF-8 +characters in the source code. To fix this error, enable UTF-8 for your project's build tool. + +For Gradle builds, add the following to your `build.gradle` file: + +```gradle +compileJava.options.encoding = 'UTF-8' +tasks.withType(JavaCompile) { + options.encoding = 'UTF-8' +} +``` + +For Maven builds, add the following to your `pom.xml` file: + +```xml +<properties> + <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> +</properties> +``` diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 8f57e2c5535..0ae038924ec 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -53,6 +53,7 @@ The [default ruleset provided by Gitleaks](https://gitlab.com/gitlab-org/securit - Twitter API - Cloud SaaS vendors: - GitHub API + - Shopify API - Slack Token - Slack Webhook - Stripe API diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png b/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png Binary files differindex b9b228c9430..5184ad85fa9 100644 --- a/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png +++ b/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 2750aa81872..10bf6202a92 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -92,7 +92,8 @@ the **Failed jobs** tab of the pipeline page. The Vulnerability Report next displays the total number of vulnerabilities by severity (for example, Critical, High, Medium, Low, Info, Unknown). Below this, a table shows each vulnerability's status, severity, -and description. Clicking a vulnerability takes you to its [Vulnerability Details](../vulnerabilities) +description and if there is a Merge Request related to it. Clicking a vulnerability takes you to its +[Vulnerability Details](../vulnerabilities) page to view more information about that vulnerability.  diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md new file mode 100644 index 00000000000..ce2297f7a1a --- /dev/null +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -0,0 +1,70 @@ +--- +type: reference +stage: Secure +group: Threat Insights +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Vulnerability severity levels + +GitLab vulnerability analyzers attempt to return vulnerability severity level values whenever +possible. The following is a list of available GitLab vulnerability severity levels, ranked from +most to least severe: + +- `Critical` +- `High` +- `Medium` +- `Low` +- `Info` +- `Unknown` + +Most GitLab vulnerability analyzers are wrappers around popular open source scanning tools. Each +open source scanning tool provides their own native vulnerability severity level value. These values +can be one of the following: + +| Native vulnerability severity level type | Examples | +|-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------| +| String | `WARNING`, `ERROR`, `Critical`, `Negligible` | +| Integer | `1`, `2`, `5` | +| [CVSS v2.0 Rating](https://nvd.nist.gov/vuln-metrics/cvss) | `(AV:N/AC:L/Au:S/C:P/I:P/A:N)` | +| [CVSS v3.1 Qualitative Severity Rating](https://www.first.org/cvss/v3.1/specification-document#Qualitative-Severity-Rating-Scale) | `CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H` | + +To provide consistent vulnerability severity level values, the GitLab vulnerability analyzers +convert from the above values to a standardized GitLab vulnerability severity level, as outlined in +the following tables: + +## SAST + +| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | +|--------------------------------------------------------------------------------------------------------|--------------------------|----------------------------|------------------------------------| +| [security-code-scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | **{dotted-circle}** No | N/A | N/A | +| [brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | **{dotted-circle}** No | N/A | N/A | +| [sobelow](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Unknown` | +| [nodejs-scan](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) | **{check-circle}** Yes | String | `INFO`, `WARNING`, `ERROR` | +| [flawfinder](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) | **{check-circle}** Yes | Integer | `0`, `1`, `2`, `3`, `4`, `5` | +| [eslint](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Unknown` | +| [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `11`, `12`, `18` | +| [gosec](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | +| [bandit](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | +| [phpcs-security-audit](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) | **{check-circle}** Yes | String | `ERROR`, `WARNING` | +| [pmd-apex](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `4`, `5` | +| [kubesec](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | **{check-circle}** Yes | String | `CriticalSeverity`, `InfoSeverity` | +| [secrets](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Critical` | + +## Dependency Scanning + +| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | +|------------------------------------------------------------------------------------------|------------------------------|----------------------------|-------------------------------------| +| [bundler-audit](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit) | **{check-circle}** Yes | String | `low`, `medium`, `high`, `critical` | +| [retire.js](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js) | **{check-circle}** Yes | String | `low`, `medium`, `high`, `critical` | +| [gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | **{check-circle}** Yes | CVSS v2.0 Rating and CVSS v3.1 Qualitative Severity Rating | `(AV:N/AC:L/Au:S/C:P/I:P/A:N)`, `CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H` | + +## Container Scanning + +| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | +|------------------------------------------------------------------------|--------------------------|----------------------------|--------------------------------------------------------------| +| [klar](https://gitlab.com/gitlab-org/security-products/analyzers/klar) | **{check-circle}** Yes | String | `Negligible`, `Low`, `Medium`, `High`, `Critical`, `Defcon1` | + +## Fuzz Testing + +All fuzz testing results are reported as Unknown. They should be reviewed and triaged manually to find exploitable faults to prioritize for fixing. diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 5963485aebc..2c0d9b6c9ce 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -20,9 +20,10 @@ tasks in a secure and cloud-native way. It enables: (network address translation). - Pull-based GitOps deployments by leveraging the [GitOps Engine](https://github.com/argoproj/gitops-engine). -- Real-time access to API endpoints within a cluster. +- Real-time access to API endpoints in a cluster. -Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329). +Many more features are planned. Please review [our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) +and [our development documentation](../../../development/agent/index.md). ## GitLab Agent GitOps workflow @@ -169,7 +170,7 @@ gitops: GitLab [versions 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) also supports manifest projects containing multiple directories (or subdirectories) of YAML files. For more information see our -documentation on the [Kubernetes Agent configuration respository](repository.md). +documentation on the [Kubernetes Agent configuration repository](repository.md). ### Create an Agent record in GitLab @@ -266,7 +267,7 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways [Support TLS for gRPC communication issue](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) for progress updates. - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the `kas-address` for `wss` and `ws` schemes to whatever you need. - Check the [chart's KAS Ingress docs](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) + Check the [chart's KAS Ingress documentation](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) to learn more about it. - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. - If you defined your own secret name, replace `gitlab-agent-token` with your @@ -436,12 +437,9 @@ spec: The following example projects can help you get started with the Kubernetes Agent. -### Simple NGINX deployment - -This basic GitOps example deploys NGINX: - - [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) -- [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) +- This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) +- [Install GitLab Runner](runner.md) ### Deploying GitLab Runner with the Agent diff --git a/doc/user/clusters/agent/runner.md b/doc/user/clusters/agent/runner.md new file mode 100644 index 00000000000..715b27f951a --- /dev/null +++ b/doc/user/clusters/agent/runner.md @@ -0,0 +1,452 @@ +--- +stage: Configure +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 +--- + +# Install GitLab Runner with Kubernetes Agent **(PREMIUM ONLY)** + +These instructions to install the GitLab Runner assume the +[GitLab Kubernetes Agent](index.md) is already configured. + +1. Review the possible [Runner chart YAML values](https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/master/values.yaml) in the Runner chart documentation, + and create a `runner-chart-values.yaml` file with the configuration that fits + your needs, such as: + + ```yaml + # The GitLab Server URL (with protocol) that want to register the runner against + # ref: https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-register + # + gitlabUrl: https://gitlab.my.domain.example.com/ + + # The Registration Token for adding new Runners to the GitLab Server. This must + # be retrieved from your GitLab Instance. + # ref: https://docs.gitlab.com/ce/ci/runners/README.html + # + runnerRegistrationToken: "yrnZW46BrtBFqM7xDzE7dddd" + + # For RBAC support: + rbac: + create: true + + # Run all containers with the privileged flag enabled + # This will allow the docker:dind image to run if you need to run Docker + # commands. Please read the docs before turning this on: + # ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-dockerdind + runners: + privileged: true + ``` + +1. Create a single manifest file to install the Runner chart with your cluster agent, + replacing `GITLAB GITLAB-RUNNER` with your namespace: + + ```shell + helm template --namespace GITLAB GITLAB-RUNNER -f runner-chart-values.yaml gitlab/gitlab-runner > runner-manifest.yaml + ``` + + An [example file is available](#example-runner-manifest). + +1. Push your `runner-manifest.yaml` to your manifest repository. + +## Example Runner manifest + +```yaml +# This code is an example of a runner manifest looks like. +# Create your own manifest.yaml file to meet your project's needs. + +--- +# Source: gitlab-runner/templates/service-account.yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + annotations: + name: gitlab-runner-gitlab-runner + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" +--- +# Source: gitlab-runner/templates/secrets.yaml +apiVersion: v1 +kind: Secret +metadata: + name: "gitlab-runner-gitlab-runner" + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" +type: Opaque +data: + runner-registration-token: "FAKE-TOKEN" + runner-token: "" +--- +# Source: gitlab-runner/templates/configmap.yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: gitlab-runner-gitlab-runner + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" +data: + entrypoint: | + #!/bin/bash + set -e + mkdir -p /home/gitlab-runner/.gitlab-runner/ + cp /scripts/config.toml /home/gitlab-runner/.gitlab-runner/ + + # Register the runner + if [[ -f /secrets/accesskey && -f /secrets/secretkey ]]; then + export CACHE_S3_ACCESS_KEY=$(cat /secrets/accesskey) + export CACHE_S3_SECRET_KEY=$(cat /secrets/secretkey) + fi + + if [[ -f /secrets/gcs-applicaton-credentials-file ]]; then + export GOOGLE_APPLICATION_CREDENTIALS="/secrets/gcs-applicaton-credentials-file" + elif [[ -f /secrets/gcs-application-credentials-file ]]; then + export GOOGLE_APPLICATION_CREDENTIALS="/secrets/gcs-application-credentials-file" + else + if [[ -f /secrets/gcs-access-id && -f /secrets/gcs-private-key ]]; then + export CACHE_GCS_ACCESS_ID=$(cat /secrets/gcs-access-id) + # echo -e used to make private key multiline (in google json auth key private key is oneline with \n) + export CACHE_GCS_PRIVATE_KEY=$(echo -e $(cat /secrets/gcs-private-key)) + fi + fi + + if [[ -f /secrets/runner-registration-token ]]; then + export REGISTRATION_TOKEN=$(cat /secrets/runner-registration-token) + fi + + if [[ -f /secrets/runner-token ]]; then + export CI_SERVER_TOKEN=$(cat /secrets/runner-token) + fi + + if ! sh /scripts/register-the-runner; then + exit 1 + fi + + # Run pre-entrypoint-script + if ! bash /scripts/pre-entrypoint-script; then + exit 1 + fi + + # Start the runner + exec /entrypoint run --user=gitlab-runner \ + --working-directory=/home/gitlab-runner + + config.toml: | + concurrent = 10 + check_interval = 30 + log_level = "info" + listen_address = ':9252' + configure: | + set -e + cp /init-secrets/* /secrets + register-the-runner: | + #!/bin/bash + MAX_REGISTER_ATTEMPTS=30 + + for i in $(seq 1 "${MAX_REGISTER_ATTEMPTS}"); do + echo "Registration attempt ${i} of ${MAX_REGISTER_ATTEMPTS}" + /entrypoint register \ + --non-interactive + + retval=$? + + if [ ${retval} = 0 ]; then + break + elif [ ${i} = ${MAX_REGISTER_ATTEMPTS} ]; then + exit 1 + fi + + sleep 5 + done + + exit 0 + + check-live: | + #!/bin/bash + if /usr/bin/pgrep -f .*register-the-runner; then + exit 0 + elif /usr/bin/pgrep gitlab.*runner; then + exit 0 + else + exit 1 + fi + + pre-entrypoint-script: | +--- +# Source: gitlab-runner/templates/role.yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: "Role" +metadata: + name: gitlab-runner-gitlab-runner + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" +rules: +- apiGroups: [""] + resources: ["*"] + verbs: ["*"] +--- +# Source: gitlab-runner/templates/role-binding.yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: "RoleBinding" +metadata: + name: gitlab-runner-gitlab-runner + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: "Role" + name: gitlab-runner-gitlab-runner +subjects: +- kind: ServiceAccount + name: gitlab-runner-gitlab-runner + namespace: "gitlab" +--- +# Source: gitlab-runner/templates/deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: gitlab-runner-gitlab-runner + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" +spec: + replicas: 1 + selector: + matchLabels: + app: gitlab-runner-gitlab-runner + template: + metadata: + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" + annotations: + checksum/configmap: a6623303f6fcc3a043e87ea937bb8399d2d0068a901aa9c3419ed5c7a5afa9db + checksum/secrets: 32c7d2c16918961b7b84a005680f748e774f61c6f4e4da30650d400d781bbb30 + prometheus.io/scrape: 'true' + prometheus.io/port: '9252' + spec: + securityContext: + runAsUser: 100 + fsGroup: 65533 + terminationGracePeriodSeconds: 3600 + initContainers: + - name: configure + command: ['sh', '/config/configure'] + image: gitlab/gitlab-runner:alpine-v13.4.1 + imagePullPolicy: "IfNotPresent" + env: + + - name: CI_SERVER_URL + value: "https://gitlab.qa.joaocunha.eu/" + - name: CLONE_URL + value: "" + - name: RUNNER_REQUEST_CONCURRENCY + value: "1" + - name: RUNNER_EXECUTOR + value: "kubernetes" + - name: REGISTER_LOCKED + value: "true" + - name: RUNNER_TAG_LIST + value: "" + - name: RUNNER_OUTPUT_LIMIT + value: "4096" + - name: KUBERNETES_IMAGE + value: "ubuntu:16.04" + + - name: KUBERNETES_PRIVILEGED + value: "true" + + - name: KUBERNETES_NAMESPACE + value: "gitlab" + - name: KUBERNETES_POLL_TIMEOUT + value: "180" + - name: KUBERNETES_CPU_LIMIT + value: "" + - name: KUBERNETES_CPU_LIMIT_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_MEMORY_LIMIT + value: "" + - name: KUBERNETES_MEMORY_LIMIT_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_CPU_REQUEST + value: "" + - name: KUBERNETES_CPU_REQUEST_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_MEMORY_REQUEST + value: "" + - name: KUBERNETES_MEMORY_REQUEST_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_SERVICE_ACCOUNT + value: "" + - name: KUBERNETES_SERVICE_CPU_LIMIT + value: "" + - name: KUBERNETES_SERVICE_MEMORY_LIMIT + value: "" + - name: KUBERNETES_SERVICE_CPU_REQUEST + value: "" + - name: KUBERNETES_SERVICE_MEMORY_REQUEST + value: "" + - name: KUBERNETES_HELPER_CPU_LIMIT + value: "" + - name: KUBERNETES_HELPER_MEMORY_LIMIT + value: "" + - name: KUBERNETES_HELPER_CPU_REQUEST + value: "" + - name: KUBERNETES_HELPER_MEMORY_REQUEST + value: "" + - name: KUBERNETES_HELPER_IMAGE + value: "" + - name: KUBERNETES_PULL_POLICY + value: "" + volumeMounts: + - name: runner-secrets + mountPath: /secrets + readOnly: false + - name: scripts + mountPath: /config + readOnly: true + - name: init-runner-secrets + mountPath: /init-secrets + readOnly: true + resources: + {} + serviceAccountName: gitlab-runner-gitlab-runner + containers: + - name: gitlab-runner-gitlab-runner + image: gitlab/gitlab-runner:alpine-v13.4.1 + imagePullPolicy: "IfNotPresent" + lifecycle: + preStop: + exec: + command: ["/entrypoint", "unregister", "--all-runners"] + command: ["/bin/bash", "/scripts/entrypoint"] + env: + + - name: CI_SERVER_URL + value: "https://gitlab.qa.joaocunha.eu/" + - name: CLONE_URL + value: "" + - name: RUNNER_REQUEST_CONCURRENCY + value: "1" + - name: RUNNER_EXECUTOR + value: "kubernetes" + - name: REGISTER_LOCKED + value: "true" + - name: RUNNER_TAG_LIST + value: "" + - name: RUNNER_OUTPUT_LIMIT + value: "4096" + - name: KUBERNETES_IMAGE + value: "ubuntu:16.04" + + - name: KUBERNETES_PRIVILEGED + value: "true" + + - name: KUBERNETES_NAMESPACE + value: "gitlab" + - name: KUBERNETES_POLL_TIMEOUT + value: "180" + - name: KUBERNETES_CPU_LIMIT + value: "" + - name: KUBERNETES_CPU_LIMIT_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_MEMORY_LIMIT + value: "" + - name: KUBERNETES_MEMORY_LIMIT_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_CPU_REQUEST + value: "" + - name: KUBERNETES_CPU_REQUEST_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_MEMORY_REQUEST + value: "" + - name: KUBERNETES_MEMORY_REQUEST_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_SERVICE_ACCOUNT + value: "" + - name: KUBERNETES_SERVICE_CPU_LIMIT + value: "" + - name: KUBERNETES_SERVICE_MEMORY_LIMIT + value: "" + - name: KUBERNETES_SERVICE_CPU_REQUEST + value: "" + - name: KUBERNETES_SERVICE_MEMORY_REQUEST + value: "" + - name: KUBERNETES_HELPER_CPU_LIMIT + value: "" + - name: KUBERNETES_HELPER_MEMORY_LIMIT + value: "" + - name: KUBERNETES_HELPER_CPU_REQUEST + value: "" + - name: KUBERNETES_HELPER_MEMORY_REQUEST + value: "" + - name: KUBERNETES_HELPER_IMAGE + value: "" + - name: KUBERNETES_PULL_POLICY + value: "" + livenessProbe: + exec: + command: ["/bin/bash", "/scripts/check-live"] + initialDelaySeconds: 60 + timeoutSeconds: 1 + periodSeconds: 10 + successThreshold: 1 + failureThreshold: 3 + readinessProbe: + exec: + command: ["/usr/bin/pgrep","gitlab.*runner"] + initialDelaySeconds: 10 + timeoutSeconds: 1 + periodSeconds: 10 + successThreshold: 1 + failureThreshold: 3 + ports: + - name: metrics + containerPort: 9252 + volumeMounts: + - name: runner-secrets + mountPath: /secrets + - name: etc-gitlab-runner + mountPath: /home/gitlab-runner/.gitlab-runner + - name: scripts + mountPath: /scripts + resources: + {} + volumes: + - name: runner-secrets + emptyDir: + medium: "Memory" + - name: etc-gitlab-runner + emptyDir: + medium: "Memory" + - name: init-runner-secrets + projected: + sources: + - secret: + name: "gitlab-runner-gitlab-runner" + items: + - key: runner-registration-token + path: runner-registration-token + - key: runner-token + path: runner-token + - name: scripts + configMap: + name: gitlab-runner-gitlab-runner +``` diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 53be7e995d5..b03dfb79ae0 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -100,7 +100,7 @@ include: - template: Managed-Cluster-Applications.gitlab-ci.yml apply: - image: "registry.gitlab.com/gitlab-org/cluster-integration/cluster-applications:v0.34.1" + image: "registry.gitlab.com/gitlab-org/cluster-integration/cluster-applications:v0.37.0" ``` ### Use the template with a custom environment @@ -1268,6 +1268,11 @@ record. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21966) in GitLab 12.7. +WARNING: +The Web Application Firewall is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/271276) +in GitLab 13.6, and planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/271349) +in GitLab 14.0. + A Web Application Firewall (WAF) examines traffic being sent or received, and can block malicious traffic before it reaches your application. The benefits of a WAF are: @@ -1296,7 +1301,7 @@ To enable WAF, switch its respective toggle to the enabled position when install or updating [Ingress application](#ingress). If this is your first time using the GitLab WAF, we recommend you follow the -[quick start guide](../../topics/web_application_firewall/quick_start_guide.md). +[quick start guide](../project/clusters/protect/web_application_firewall/quick_start_guide.md). There is a small performance overhead by enabling ModSecurity. If this is considered significant for your application, you can disable ModSecurity's @@ -1308,7 +1313,7 @@ rule engine for your deployed application in any of the following ways: 1. Switch its respective toggle to the disabled position, and then apply changes by selecting **Save changes** to reinstall Ingress with the recent changes. - + ##### Logging and blocking modes @@ -1321,7 +1326,7 @@ To help you tune your WAF rules, you can globally set your WAF to either To change your WAF's mode: 1. If you haven't already done so, - [install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). + [install ModSecurity](../project/clusters/protect/web_application_firewall/quick_start_guide.md). 1. Navigate to **Operations > Kubernetes**. 1. In **Applications**, scroll to **Ingress**. 1. Under **Global default**, select your desired mode. @@ -1337,12 +1342,12 @@ The **ModSecurity** user interface controls are disabled if the version deployed differs from the one available in GitLab. However, actions at the [Ingress](#ingress) level, such as uninstalling, can still be performed: - + Update [Ingress](#ingress) to the most recent version to take advantage of bug fixes, security fixes, and performance improvements. To update the [Ingress application](#ingress), you must first uninstall it, and then re-install -it as described in [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). +it as described in [Install ModSecurity](../project/clusters/protect/web_application_firewall/quick_start_guide.md). ##### Viewing Web Application Firewall traffic diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index f78b6115623..1428a0d4e80 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -76,7 +76,7 @@ The reported licenses might be incomplete or inaccurate. | Elixir | [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) | | C++/C | [Conan](https://conan.io/) | | Scala | [sbt](https://www.scala-sbt.org/) | -| Rust | [Cargo](https://crates.io) | +| Rust | [Cargo](https://crates.io/) | | PHP | [Composer](https://getcomposer.org/) | ## Requirements diff --git a/doc/user/discussions/img/threads_resolved.png b/doc/user/discussions/img/threads_resolved.png Binary files differdeleted file mode 100644 index ffb1233f2ee..00000000000 --- a/doc/user/discussions/img/threads_resolved.png +++ /dev/null diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 945c082bba9..bf3e907bd24 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -90,27 +90,6 @@ When a link of a commit reference is found in a thread inside a merge request, it will be automatically converted to a link in the context of the current merge request. -### Jumping between unresolved threads (deprecated) - -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/199718) in GitLab 13.3. -> - This button's removal is behind a feature flag enabled by default. -> - For GitLab self-managed instances, GitLab administrators with access to the - [GitLab Rails console](../../administration/feature_flags.md) can opt to disable it by running - `Feature.disable(:hide_jump_to_next_unresolved_in_threads)` (for the instance) or - `Feature.disable(:hide_jump_to_next_unresolved_in_threads, Project.find(<project id>))` - (per project.) **(CORE ONLY)** - -When a merge request has a large number of comments it can be difficult to track -what remains unresolved. You can jump between unresolved threads with the -Jump button next to the Reply field on a thread. - -You can also use keyboard shortcuts to navigate among threads: - -- Use <kbd>n</kbd> to jump to the next unresolved thread. -- Use <kbd>p</kbd> to jump to the previous unresolved thread. - - - ### Marking a comment or thread as resolved You can mark a thread as resolved by clicking the **Resolve thread** diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 7aafa52799d..611c1105961 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -114,7 +114,7 @@ or over the repository size limit, you can [reduce your repository size with Git | Setting | GitLab.com | Default | | ----------- | ----------- | ------------- | | [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md) | 10 GB | Unlimited | -| Maximum import size | 5 GB | 50 MB | +| Maximum import size | 5 GB | Unlimited | NOTE: `git push` and GitLab project imports are limited to 5 GB per request through Cloudflare. Git LFS and imports other than a file upload are not affected by this limit. @@ -132,6 +132,23 @@ All our runners are deployed into Google Cloud Platform (GCP) - any IP based firewall can be configured by looking up all [IP address ranges or CIDR blocks for GCP](https://cloud.google.com/compute/docs/faq#where_can_i_find_product_name_short_ip_ranges). +## Hostname list + +To configure allow-lists in local HTTP(S) proxies, or other +web-blocking software that govern end-user machines, +pages on GitLab.com will attempt to load content from +the following hostnames: + +- `gitlab.com` +- `*.gitlab.com` +- `*.gitlab-static.net` +- `*.gitlab.io` +- `*.gitlab.net` + +Documentation and Company pages served over `docs.gitlab.com` +and `about.gitlab.com` will attempt to also load certain page +content directly from common public CDN hostnames. + ## Webhooks A limit of: @@ -532,13 +549,10 @@ endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md). ### Rate limiting responses -The [`Retry-After` -header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) -indicates when the client should retry. +For information on rate limiting responses, see: -Rate limits applied by HAProxy (instead of Cloudflare or the -GitLab application) have `RateLimit-Reset` and `RateLimit-ResetTime` -headers. +- [List of headers on responses to blocked requests](../admin_area/settings/user_and_ip_rate_limits.md#response-headers). +- [Customizable response text](../admin_area/settings/user_and_ip_rate_limits.md#response-text). ### Protected paths throttle @@ -548,11 +562,7 @@ paths that exceed 10 requests per **minute** per IP address. See the source below for which paths are protected. This includes user creation, user confirmation, user sign in, and password reset. -This header is included in responses to blocked requests: - -```plaintext -Retry-After: 60 -``` +[User and IP rate limits](../admin_area/settings/user_and_ip_rate_limits.md#response-headers) includes a list of the headers responded to blocked requests. See [Protected Paths](../admin_area/settings/protected_paths.md) for more details. diff --git a/doc/user/group/import/img/bulk_imports_v13_8.png b/doc/user/group/import/img/bulk_imports_v13_8.png Binary files differnew file mode 100644 index 00000000000..31234f9fcea --- /dev/null +++ b/doc/user/group/import/img/bulk_imports_v13_8.png diff --git a/doc/user/group/import/img/import_panel_v13_8.png b/doc/user/group/import/img/import_panel_v13_8.png Binary files differnew file mode 100644 index 00000000000..1fb7fbad291 --- /dev/null +++ b/doc/user/group/import/img/import_panel_v13_8.png diff --git a/doc/user/group/import/img/new_group_navigation_v13_8.png b/doc/user/group/import/img/new_group_navigation_v13_8.png Binary files differnew file mode 100644 index 00000000000..307175727c7 --- /dev/null +++ b/doc/user/group/import/img/new_group_navigation_v13_8.png diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md new file mode 100644 index 00000000000..d051a134af1 --- /dev/null +++ b/doc/user/group/import/index.md @@ -0,0 +1,91 @@ +--- +type: reference, howto +stage: Manage +group: Import +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 +--- + +# Import groups from another instance of GitLab **(CORE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7. +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's enabled on GitLab.com. + +## Overview + +WARNING: +This feature is [under construction](https://gitlab.com/groups/gitlab-org/-/epics/2771) and currently migrates only some of the Group data. Please see below for the full list of what is included in the migration at this time. + +Using GitLab Group Migration, you can migrate existing top-level groups from GitLab.com or a self-managed instance. Groups can be migrated to a target instance, as a top-level group, or as a sub-group of any existing top-level group. + +The following resources are migrated to the target instance: + +- Groups + - description + - attributes + - subgroups +- Epics + - title + - description + - state (open / closed) + - start date + - due date + - epic order on boards + - confidentiality + +Any other items are **not** migrated. + +## Enable or disable GitLab Group Migration + +Support for GitLab Group Migration is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it. + +To enable it: + +```ruby +Feature.enable(:bulk_import) +``` + +To disable it: + +```ruby +Feature.disable(:bulk_import) +``` + +## Import your groups into GitLab + +Before you begin, ensure that the target instance of GitLab can communicate with the source +over HTTPS (HTTP is not supported). + +NOTE: +This might involve reconfiguring your firewall to prevent blocking connection on the side of self-managed instance. + +### Connect to the remote GitLab instance + +1. Navigate to the New Group page, either via the `+` button in the top navigation bar, or the **New subgroup** button +on an existing group's page. + +  + +1. On the New Group page, select the **Import group** tab. + +  + +1. Fill in source URL of your GitLab. +1. Fill in [personal access token](../../../user/profile/personal_access_tokens.md) for remote GitLab instance. +1. Click "Connect instance". + +### Selecting which groups to import + +After you have authorized access to GitLab instance, you are redirected to the GitLab Group Migration importer page and your remote GitLab groups are listed. + +1. By default, the proposed group namespaces match the names as they exist in remote instance, but based on your permissions, you can choose to edit these names before you proceed to import any of them. + +1. Select the **Import** button next to any number of groups. + +1. The **Status** column shows the import status of each group. You can choose to leave the page open and it will update in real-time. + +1. Once a group has been imported, click its GitLab path to open its GitLab URL. + + diff --git a/doc/user/group/index.md b/doc/user/group/index.md index a0884461da1..069dea40ba5 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -215,10 +215,7 @@ To remove a member from 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. -> - Improvements are [deployed behind a feature flag](../feature_flags.md), enabled by default. -> - Improvements are enabled on GitLab.com. -> - Improvements are recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable improvements](#enable-or-disable-improvements-to-the-ability-to-filter-and-sort-group-members). **(CORE ONLY)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289911) in GitLab 13.8. The following sections illustrate how you can filter and sort members in a group. To view these options, navigate to your desired group, go to **Members**, and include the noted search terms. @@ -269,30 +266,6 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last  -### Enable or disable improvements to the ability to filter and sort group members **(CORE ONLY)** - -Group member filtering and sorting improvements are deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable the improvements. - -To disable them: - -```ruby -# For the instance -Feature.disable(:group_members_filtered_search) -# For a single group -Feature.disable(:group_members_filtered_search, Group.find(<group id>)) -``` - -To enable them: - -```ruby -# For the instance -Feature.enable(:group_members_filtered_search) -# For a single group -Feature.enable(:group_members_filtered_search, Group.find(<group id>)) -``` - ## Changing the default branch protection of a group > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. @@ -487,7 +460,7 @@ and above. There are a few limitations compared to project wikis: - Git LFS is not supported. -- Group wikis are not included in global search, group exports, backups, and Geo replication. +- Group wikis are not included in global search, group exports, and Geo replication. - Changes to group wikis don't show up in the group's activity feed. - Group wikis [can't be moved](../../api/project_repository_storage_moves.md#limitations) using the project repository moves API. @@ -664,6 +637,12 @@ request to add a new user to a project through API will not be possible. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in [GitLab Ultimate and Gold](https://about.gitlab.com/pricing/) 12.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) to [GitLab Premium and Silver](https://about.gitlab.com/pricing/) in 13.1. +NOTE: +IP Access Restrictions are currently not functioning as expected on GitLab.com. Some users +may experience blocked Git operations or have difficulties accessing projects. Please +review the [following bug report](https://gitlab.com/gitlab-org/gitlab/-/issues/271673) for +more information. + To make sure only people from within your organization can access particular resources, you have the option to restrict access to groups and their underlying projects, issues, etc, by IP address. This can help ensure that diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index a06c7a8f325..65d3129a825 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -88,6 +88,22 @@ similar to how they appear when viewing a [milestone](../../project/milestones/i Burndown charts help track completion progress of total scope, and burnup charts track the daily total count and weight of issues added to and completed in a given timebox. +### Group issues by label + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225500) in GitLab 13.8. + +You can group the list of issues by label. +This can help you view issues that have your team's label, +and get a more accurate understanding of scope attributable to each label. + +To group issues by label: + +1. In the **Group by** dropdown, select **Label**. +1. Select the **Filter by label** dropdown. +1. Select the labels you want to group by in the labels dropdown. + You can also search for labels by typing in the search input. +1. Click or tap outside of the label dropdown. The page is now grouped by the selected labels. + ## Disable iterations **(STARTER ONLY)** GitLab Iterations feature is deployed with a feature flag that is **enabled by default**. diff --git a/doc/user/group/roadmap/img/roadmap_filters_v13_7.png b/doc/user/group/roadmap/img/roadmap_filters_v13_7.png Binary files differdeleted file mode 100644 index 00505a7f34f..00000000000 --- a/doc/user/group/roadmap/img/roadmap_filters_v13_7.png +++ /dev/null diff --git a/doc/user/group/roadmap/img/roadmap_filters_v13_8.png b/doc/user/group/roadmap/img/roadmap_filters_v13_8.png Binary files differnew file mode 100644 index 00000000000..d826909b022 --- /dev/null +++ b/doc/user/group/roadmap/img/roadmap_filters_v13_8.png diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 6dfa7641dbb..f3b7be536ae 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -67,8 +67,9 @@ You can also filter epics in the Roadmap view by: - Author - Label - Milestone +- Confidentiality of epics - + Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics). diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index 15dd91bece2..7158b7bc86b 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -52,11 +52,13 @@ assertions to be able to create a user. ## Feature flag **(PREMIUM ONLY)** -The group-managed accounts feature is behind a feature flag: `group_managed_accounts`. The flag is disabled by default. +The group-managed accounts feature is behind these feature flags: `group_managed_accounts`, `sign_up_on_sso` and `convert_user_to_group_managed_accounts`. The flags are disabled by default. To activate the feature, ask a GitLab administrator with Rails console access to run: ```ruby Feature.enable(:group_managed_accounts) +Feature.enable(:sign_up_on_sso) +Feature.enable(:convert_user_to_group_managed_accounts) ``` ## Project restrictions for Group-managed accounts diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 62431747911..0ce92eac1a3 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -80,10 +80,14 @@ Please note that the certificate [fingerprint algorithm](#additional-providers-a - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5291) in GitLab 11.8. - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI. +- [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/292811) in GitLab 13.8, with an updated timeout experience. +- [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/211962) in GitLab 13.8 with allowing group owners to not go through SSO. With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users can't be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. -However, users are not prompted to sign in through SSO on each visit. GitLab checks whether a user has authenticated through SSO, and only prompts the user to sign in via SSO if the session has expired. +However, users are not prompted to sign in through SSO on each visit. GitLab checks whether a user +has authenticated through SSO. If it's been more than 7 days since the last sign-in, GitLab +prompts the user to sign in again through SSO. You can see more information about how long a session is valid in our [user profile documentation](../../profile/#why-do-i-keep-getting-signed-out). We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/9152). @@ -93,11 +97,10 @@ When SSO enforcement is enabled for a group, users can't share a project in the ## Providers NOTE: -GitLab is unable to provide support for IdPs that are not listed here. +GitLab is unable to provide full support for integrating identify providers that are not listed here. | Provider | Documentation | |----------|---------------| -| ADFS (Active Directory Federation Services) | [Create a Relying Party Trust](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) | | Azure | [Configuring single sign-on to applications](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) | | Okta | [Setting up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/) | | OneLogin | [Use the OneLogin SAML Test Connector](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f) | @@ -164,8 +167,9 @@ For more information, see our [discussion on providers](#providers). Your identity provider may have relevant documentation. It may be generic SAML documentation, or specifically targeted for GitLab. Examples: +- [ADFS (Active Directory Federation Services)](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) - [Auth0](https://auth0.com/docs/protocols/saml-configuration-options/configure-auth0-as-saml-identity-provider) -- [G Suite](https://support.google.com/a/answer/6087519?hl=en) +- [Google Workspace](https://support.google.com/a/answer/6087519?hl=en) - [JumpCloud](https://support.jumpcloud.com/support/s/article/single-sign-on-sso-with-gitlab-2019-08-21-10-36-47) - [PingOne by Ping Identity](https://docs.pingidentity.com/bundle/pingone/page/xsh1564020480660-1.html) @@ -209,7 +213,7 @@ When a user tries to sign in with Group SSO, GitLab attempts to find or create a To link SAML to your existing GitLab.com account: 1. Sign in to your GitLab.com account. -1. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group Admin can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the Identity Provider. +1. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group owner can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the Identity Provider. 1. Click **Authorize**. 1. Enter your credentials on the Identity Provider if prompted. 1. You are then redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 40c036e1fc0..cd3e99ae541 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -232,7 +232,7 @@ It is important that this SCIM `id` and SCIM `externalId` are configured to the 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-saml-users) to manually retrieve the `externalId` we have stored for users, also called the `external_uid` or `NameId`. +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`. To see how the `external_uid` compares to the value returned as the SAML NameId, you can have the user use a [SAML Tracer](index.md#saml-debugging-tools). @@ -251,7 +251,7 @@ you can address the problem in the following ways: - You can have users unlink and relink themselves, based on the ["SAML authentication failed: User has already been taken"](index.md#message-saml-authentication-failed-user-has-already-been-taken) section. - You can unlink all users simultaneously, by removing all users from the SAML app while provisioning is turned on. -- It may be possible to use the [SCIM API](../../../api/scim.md#update-a-single-saml-user) to manually correct the `externalId` stored for users to match the SAML `NameId`. +- It may be possible to use the [SCIM API](../../../api/scim.md#update-a-single-scim-provisioned-user) to manually correct the `externalId` stored for users to match the SAML `NameId`. To look up a user, you'll need to know the desired value that matches the `NameId` as well as the current `externalId`. It is important not to update these to incorrect values, since this will cause users to be unable to sign in. It is also important not to assign a value to the wrong user, as this would cause users to get signed into the wrong account. @@ -269,7 +269,7 @@ Changing the SAML or SCIM configuration or provider can cause the following prob | Problem | Solution | |------------------------------------------------------------------------------|--------------------| | SAML and SCIM identity mismatch. | First [verify that the user's SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) and then [update or fix the mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid). | -| SCIM identity mismatch between GitLab and the Identify Provider SCIM app. | You can confirm whether you're hitting the error because of your SCIM identity mismatch between your SCIM app and GitLab.com by using [SCIM API](../../../api/scim.md#update-a-single-saml-user) which shows up in the `id` key and compares it with the user `externalId` in the SCIM app. You can use the same [SCIM API](../../../api/scim.md#update-a-single-saml-user) to update the SCIM `id` for the user on GitLab.com. | +| SCIM identity mismatch between GitLab and the Identify Provider SCIM app. | You can confirm whether you're hitting the error because of your SCIM identity mismatch between your SCIM app and GitLab.com by using [SCIM API](../../../api/scim.md#update-a-single-scim-provisioned-user) which shows up in the `id` key and compares it with the user `externalId` in the SCIM app. You can use the same [SCIM API](../../../api/scim.md#update-a-single-scim-provisioned-user) to update the SCIM `id` for the user on GitLab.com. | ### Azure diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 2aee8706194..6b95388bf2e 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -76,7 +76,7 @@ For more details on the specific data persisted in a group export, see the file from there by clicking **Download export**, or generate a new file by clicking **Regenerate export**. NOTE: -The maximum import file size can be set by the Administrator, default is 50MB. +The maximum import file size can be set by the Administrator, default is `0` (unlimited). As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin UI](../../admin_area/settings/account_and_limit_settings.md). ### Between CE and EE diff --git a/doc/user/group/subgroups/img/group_members_filter_v12_6.png b/doc/user/group/subgroups/img/group_members_filter_v12_6.png Binary files differdeleted file mode 100644 index 692fdfe00a1..00000000000 --- a/doc/user/group/subgroups/img/group_members_filter_v12_6.png +++ /dev/null diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 8af075fc0c0..59812fc2b2f 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -117,7 +117,7 @@ Follow the same process to create any subsequent groups. ## Membership When you add a member to a group, that member is also added to all subgroups. -Permission level is inherited from the group’s parent. This model allows access to +Permission level is inherited from the group’s parent. This model allows access to subgroups if you have membership in one of its parents. Jobs for pipelines in subgroups can use [runners](../../../ci/runners/README.md) registered to the parent group(s). diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 0f9afdef995..438769872c0 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -316,15 +316,6 @@ To delete a custom value stream:  -### Disabling custom value streams - -Custom value streams are enabled by default. If you have a self-managed instance, an -administrator can open a Rails console and disable them with the following command: - -```ruby -Feature.disable(:value_stream_analytics_create_multiple_value_streams) -``` - ## Days to completion chart > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21631) in GitLab 12.6. diff --git a/doc/user/infrastructure/img/terraform_list_view_actions_v13_8.png b/doc/user/infrastructure/img/terraform_list_view_actions_v13_8.png Binary files differnew file mode 100644 index 00000000000..7d619b6ad7e --- /dev/null +++ b/doc/user/infrastructure/img/terraform_list_view_actions_v13_8.png diff --git a/doc/user/infrastructure/img/terraform_list_view_v13_5.png b/doc/user/infrastructure/img/terraform_list_view_v13_5.png Binary files differdeleted file mode 100644 index b23dfa6289e..00000000000 --- a/doc/user/infrastructure/img/terraform_list_view_v13_5.png +++ /dev/null diff --git a/doc/user/infrastructure/img/terraform_list_view_v13_8.png b/doc/user/infrastructure/img/terraform_list_view_v13_8.png Binary files differnew file mode 100644 index 00000000000..6eb85285e81 --- /dev/null +++ b/doc/user/infrastructure/img/terraform_list_view_v13_8.png diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 4c012fbf1d9..60453b007ba 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -8,11 +8,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Motivation -The Terraform integration features within GitLab enable your GitOps / Infrastructure-as-Code (IaC) +The Terraform integration features in GitLab enable your GitOps / Infrastructure-as-Code (IaC) workflows to tie into GitLab authentication and authorization. These features focus on -lowering the barrier to entry for teams to adopt Terraform, collaborate effectively within +lowering the barrier to entry for teams to adopt Terraform, collaborate effectively in GitLab, and support Terraform best practices. +## Quick Start + +Use the following `.gitlab-ci.yml` to set up a basic Terraform project integration +for GitLab versions 13.5 and later: + +```yaml +include: + - template: Terraform.latest.gitlab-ci.yml + +variables: + # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables + TF_STATE_NAME: default + TF_CACHE_KEY: default +``` + +This template uses `.latest.`, instead of stable, and may include breaking changes. +This template also includes some opinionated decisions, which you can override: + +- Including the latest [GitLab Terraform Image](https://gitlab.com/gitlab-org/terraform-images). +- Using the [GitLab managed Terraform State](#gitlab-managed-terraform-state) as + the Terraform state storage backend. +- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml): + `init`, `validate`, `build`, and `deploy`. These stages + [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml) + `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on `master`. + ## GitLab Managed Terraform state [Terraform remote backends](https://www.terraform.io/docs/backends/index.html) @@ -22,7 +48,7 @@ to securely store the state files in local storage (the default) or [the remote store of your choice](../../administration/terraform_state.md). The GitLab managed Terraform state backend can store your Terraform state easily and -securely, and spares you from setting up additional remote resources like +securely. It spares you from setting up additional remote resources like Amazon S3 or Google Cloud Storage. Its features include: - Supporting encryption of the state file both in transit and at rest. @@ -39,32 +65,23 @@ recommends encrypting plan output or modifying the project visibility settings. ## Terraform integration in Merge Requests -Collaborating around Infrastructure as Code (IaC) changes requires both code changes and expected infrastructure changes to be checked and approved. GitLab provides a solution to help collaboration around Terraform code changes and their expected effects using the Merge Request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows. +Collaborating around Infrastructure as Code (IaC) changes requires both code changes +and expected infrastructure changes to be checked and approved. GitLab provides a +solution to help collaboration around Terraform code changes and their expected +effects using the Merge Request pages. This way users don't have to build custom +tools or rely on 3rd party solutions to streamline their IaC workflows. Read more on setting up and [using the merge request integrations](mr_integration.md). -## Quick Start - -Use the following `.gitlab-ci.yml` to set up a simple Terraform project integration -for GitLab versions 13.5 and greater: +## The GitLab terraform provider -```yaml -include: - - template: Terraform.latest.gitlab-ci.yml - -variables: - # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables - TF_STATE_NAME: default - TF_CACHE_KEY: default -``` +WARNING: +The GitLab Terraform provider is released separately from GitLab. +We are working on migrating the GitLab Terraform provider for GitLab.com. -This template uses `.latest.`, instead of stable, and may include breaking changes. -This template also includes some opinionated decisions, which you can override: +You can use the [GitLab Terraform provider](https://github.com/gitlabhq/terraform-provider-gitlab) +to manage various aspects of GitLab using Terraform. The provider is an open source project, +owned by GitLab, where everyone can contribute. -- Including the latest [GitLab Terraform Image](https://gitlab.com/gitlab-org/terraform-images). -- Using the [GitLab managed Terraform State](#gitlab-managed-terraform-state) as - the Terraform state storage backend. -- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml): - `init`, `validate`, `build`, and `deploy`. These stages - [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml) - `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on `master`. +The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) +is available as part of the official Terraform provider documentations. diff --git a/doc/user/infrastructure/mr_integration.md b/doc/user/infrastructure/mr_integration.md index c86e5ddf1db..2704e7b7c8d 100644 --- a/doc/user/infrastructure/mr_integration.md +++ b/doc/user/infrastructure/mr_integration.md @@ -72,10 +72,10 @@ To manually configure a GitLab Terraform Report artifact requires the following terraform: $PLAN_JSON ``` - For a full example using the pre-built image, see [Example `.gitlab-ci.yaml` - file](#example-gitlab-ciyaml-file). + For a full example using the pre-built image, see [Example `.gitlab-ci.yml` + file](#example-gitlab-ciyml-file). - For an example displaying multiple reports, see [`.gitlab-ci.yaml` multiple reports file](#multiple-terraform-plan-reports). + For an example displaying multiple reports, see [`.gitlab-ci.yml` multiple reports file](#multiple-terraform-plan-reports). 1. Running the pipeline displays the widget in the merge request, like this: @@ -86,7 +86,7 @@ To manually configure a GitLab Terraform Report artifact requires the following  -### Example `.gitlab-ci.yaml` file +### Example `.gitlab-ci.yml` file ```yaml default: diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md index cbd2a63524d..30838b1cabd 100644 --- a/doc/user/infrastructure/terraform_state.md +++ b/doc/user/infrastructure/terraform_state.md @@ -62,7 +62,7 @@ local machine, this is a simple way to get started: 1. On your local machine, run `terraform init`, passing in the following options, replacing `<YOUR-STATE-NAME>`, `<YOUR-PROJECT-ID>`, `<YOUR-USERNAME>` and `<YOUR-ACCESS-TOKEN>` with the relevant values. This command initializes your - Terraform state, and stores that state within your GitLab project. The name of + Terraform state, and stores that state in your GitLab project. The name of your state can contain only uppercase and lowercase letters, decimal digits, hyphens, and underscores. This example uses `gitlab.com`: @@ -104,7 +104,7 @@ and the CI YAML file: ``` 1. In the root directory of your project repository, configure a - `.gitlab-ci.yaml` file. This example uses a pre-built image which includes a + `.gitlab-ci.yml` file. This example uses a pre-built image which includes a `gitlab-terraform` helper. For supported Terraform versions, see the [GitLab Terraform Images project](https://gitlab.com/gitlab-org/terraform-images). @@ -112,7 +112,7 @@ and the CI YAML file: image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest ``` -1. In the `.gitlab-ci.yaml` file, define some environment variables to ease +1. In the `.gitlab-ci.yml` file, define some environment variables to ease development. In this example, `TF_ROOT` is the directory where the Terraform commands must be executed, `TF_ADDRESS` is the URL to the state on the GitLab instance where this pipeline runs, and the final path segment in `TF_ADDRESS` @@ -194,7 +194,7 @@ recommends encrypting plan output or modifying the project visibility settings. ### Example project -See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 within a custom VPC. +See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 in a custom VPC. ## Using a GitLab managed Terraform state backend as a remote data source @@ -234,7 +234,7 @@ An example setup is shown below: } ``` -Outputs from the data source can now be referenced within your Terraform resources +Outputs from the data source can now be referenced in your Terraform resources using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. You need at least [developer access](../permissions.md) to the target project @@ -340,21 +340,76 @@ 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 from within GitLab CI. +location. You can then go back to running it in GitLab CI/CD. ## Managing state files +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8. + +Users with Developer and greater [permissions](../permissions.md) can view the +state files attached to a project at **Operations > Terraform**. Users with +Maintainer permissions can perform commands on the state files. The user interface +contains these fields: + + + +- **Name**: The name of the environment, with a locked (**{lock}**) icon if the + state file is locked. +- **Pipeline**: A link to the most recent pipeline and its status. +- **Details**: Information about when the state file was created or changed. +- **Actions**: Actions you can take on the state file, including downloading, + locking, unlocking, or [removing](#remove-a-state-file) the state file and versions: + +  + NOTE: -We are currently working on [providing a graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563). +Additional improvements to the +[graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563) +are planned. + +## Remove a state file + +Users with Maintainer and greater [permissions](../permissions.md) can use the +following options to remove a state file: - +- **GitLab UI**: Go to **Operations > Terraform**. In the **Actions** column, + click the vertical ellipsis (**{ellipsis_v}**) button and select + **Remove state file and versions**. +- **GitLab REST API**: You can remove a state file by making a request to the + REST API. For example: -The state files attached to a project can be found under Operations / Terraform. + ```shell + curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>" + ``` -## Removing a State file +- [GitLab GraphQL API](#remove-a-state-file-with-the-gitlab-graphql-api). -You can only remove a state file by making a request to the API, like the following example: +### Remove a state file with the GitLab GraphQL API + +You can remove a state file by making a GraphQL API request. For example: + +```shell +mutation deleteState { + terraformStateDelete(input: { id: "<global_id_for_the_state>" }) { + errors + } +} +``` + +You can obtain the `<global_id_for_the_state>` by querying the list of states: ```shell -curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>" +query ProjectTerraformStates { + project(fullPath: "<your_project_path>") { + terraformStates { + nodes { + id + name + } + } + } +} ``` + +For those new to the GitLab GraphQL API, read +[Getting started with GitLab GraphQL API](../../api/graphql/getting_started.md). diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 751915f84a0..6159ea395fa 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -21,6 +21,11 @@ If you do not have a Composer package, create one and check it in to a repository. This example shows a GitLab repository, but the repository can be any public or private repository. +WARNING: +If you are using a GitLab repository, the project must have been created from +a group's namespace, rather than a user's namespace. Composer packages +[can't be published to projects created from a user's namespace](https://gitlab.com/gitlab-org/gitlab/-/issues/235467). + 1. Create a directory called `my-composer-package` and change to that directory: ```shell @@ -72,8 +77,8 @@ Prerequisites: - A package in a GitLab repository. Composer packages should be versioned based on the [Composer specification](https://getcomposer.org/doc/04-schema.md#version). - If the version is not valid, for example, it has three dots (`1.0.0.0`), an - error (`Validation failed: Version is invalid`) occurs when you publish. + If the version is not valid, for example, it has three dots (`1.0.0.0`), an + error (`Validation failed: Version is invalid`) occurs when you publish. - A valid `composer.json` file. - The Packages feature is enabled in a GitLab repository. - The project ID, which is on the project's home page. @@ -132,6 +137,13 @@ A more detailed Composer CI/CD file is also available as a `.gitlab-ci.yml` temp WARNING: Do not save unless you want to overwrite the existing CI/CD file. +## Publishing packages with the same name or version + +When you publish: + +- The same package with different data, it overwrites the existing package. +- The same package with the same data, a `404 Bad request` error occurs. + ## Install a Composer package Install a package from the Package Registry so you can use it as a dependency. @@ -260,6 +272,6 @@ Output indicates that the package has been successfully installed. WARNING: Never commit the `auth.json` file to your repository. To install packages from a CI/CD job, -consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages-with-satis.md#authentication) tool with your personal access token +consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages.md#satis) tool with your personal access token stored in a [GitLab CI/CD environment variable](../../../ci/variables/README.md) or in [HashiCorp Vault](../../../ci/secrets/index.md). diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 73798d363af..f90c220a622 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -47,7 +47,7 @@ Conan version 1.20.5 ### Install CMake When you develop with C++ and Conan, you can select from many available -compilers. This example uses the CMake compiler. +compilers. This example uses the CMake build system generator. To install CMake: @@ -283,6 +283,9 @@ Additional Conan images to use as the basis of your CI file are available in the Install a Conan package from the Package Registry so you can use it as a dependency. +WARNING: +Project-level packages [cannot be downloaded currently](https://gitlab.com/gitlab-org/gitlab/-/issues/270129). + Conan packages are often installed as dependencies by using the `conanfile.txt` file. @@ -384,3 +387,16 @@ The GitLab Conan repository supports the following Conan CLI commands: packages you have permission to view. - `conan info`: View the information on a given package from the Package Registry. - `conan remove`: Delete the package from the Package Registry. + +## Troubleshooting Conan packages + +### `ERROR: <package> was not found in remote <remote>` + +When you attempt to install a Conan package, you might receive a `404` error +like `ERROR: <package> was not found in remote <remote>`. + +This issue occurs when you request a download from the project-level Conan API. +The resulting URL is missing is project's `/<id>` and Conan commands, like +`conan install`, fail. + +For more information, see [issue 270129](https://gitlab.com/gitlab-org/gitlab/-/issues/270129). diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 4e8d105adfa..8c284ccb9a3 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -305,7 +305,7 @@ is set to `always`. To use your own Docker images for Docker-in-Docker, follow these steps in addition to the steps in the -[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor) section: +[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) section: 1. Update the `image` and `service` to point to your registry. 1. Add a service [alias](../../../ci/yaml/README.md#servicesalias). @@ -666,6 +666,23 @@ For example, you may have two individual images, one for `amd64` and another for As a workaround, you should include the architecture in the tag name of individual images. For example, use `mygroup/myapp:1.0.0-amd64` instead of using sub repositories, like `mygroup/myapp/amd64:1.0.0`. You can then tag the manifest list with `mygroup/myapp:1.0.0`. +### The cleanup policy doesn't delete any tags + +In GitLab 13.6 and earlier, when you run the cleanup policy, +you may expect it to delete tags and it does not. + +This issue occurs when the cleanup policy was saved without +editing the value in the **Remove tags matching** field. + +This field had a grayed out `.*` value as a placeholder. +Unless `.*` (or other regex pattern) was entered explicitly into the +field, a `nil` value was submitted. This value prevents the +saved cleanup policy from matching any tags. + +As a workaround, edit the cleanup policy. In the **Remove tags matching** +field, enter `.*` and save. This value indicates that all tags should +be removed. + ### Troubleshoot as a GitLab server admin Troubleshooting the GitLab Container Registry, most of the times, requires diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index fbede6d13b7..5e5aadfae2b 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -141,11 +141,10 @@ You can use the Dependency Proxy to pull your base image. bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= ``` - This can also be other credentials such as: + This can also be a [personal access token](../../../user/profile/personal_access_tokens.md) such as: ```shell echo -n "my_username:personal_access_token" | base64 - echo -n "deploy_token_username:deploy_token" | base64 ``` 1. Create a [custom environment variables](../../../ci/variables/README.md#custom-environment-variables) diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index c9859840c9c..82c72481984 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -20,16 +20,24 @@ Publish generic files, like release binaries, in your project’s Package Regist ## Authenticate to the Package Registry -To authenticate to the Package Registry, you need either a [personal access token](../../../api/README.md#personalproject-access-tokens) -or [CI job token](../../../api/README.md#gitlab-ci-job-token). +To authenticate to the Package Registry, you need either a [personal access token](../../../api/README.md#personalproject-access-tokens), +[CI job token](../../../api/README.md#gitlab-ci-job-token), or [deploy token](../../project/deploy_tokens/index.md). + +In addition to the standard API authentication mechanisms, the generic package +API allows authentication with HTTP Basic authentication for use with tools that +do not support the other available mechanisms. The `user-id` is not checked and +may be any value, and the `password` must be either a [personal access token](../../../api/README.md#personalproject-access-tokens), +a [CI job token](../../../api/README.md#gitlab-ci-job-token), or a [deploy token](../../project/deploy_tokens/index.md). ## Publish a package file When you publish a package file, if the package does not exist, it is created. +If a package with the same name, version, and filename already exists, it is also created. It does not overwrite the existing package. + Prerequisites: -- You need to [authenticate with the API](../../../api/README.md#authentication). +- You need to [authenticate with the API](../../../api/README.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. ```plaintext PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name @@ -62,11 +70,13 @@ Example response: ## Download package file -Install a package file. +Download a package file. + +If multiple packages have the same name, version, and filename, then the most recent one is retrieved. Prerequisites: -- You need to [authenticate with the API](../../../api/README.md#authentication). +- You need to [authenticate with the API](../../../api/README.md#authentication). If authenticating with a deploy token, it must be configured with the `read_package_registry` and/or `write_package_registry` scope. ```plaintext GET /projects/:id/packages/generic/:package_name/:package_version/:file_name @@ -88,6 +98,13 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt" ``` +Example request that uses HTTP Basic authentication: + +```shell +curl --user "user:<your_access_token>" \ + https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt +``` + ## Publish a generic package by using CI/CD To work with generic packages in [GitLab CI/CD](../../../ci/README.md), you can use diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 51b41b842fa..c16fea1d00a 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -94,7 +94,10 @@ Some features such as [publishing](#publish-an-npm-package) a package is only av ## Authenticate to the Package Registry -To authenticate to the Package Registry, you must use one of the following: +You must authenticate with the Package Registry when the project +is private. Public projects do not require authentication. + +To authenticate, use one of the following: - A [personal access token](../../../user/profile/personal_access_tokens.md) (required for two-factor authentication (2FA)), with the scope set to `api`. @@ -102,7 +105,7 @@ To authenticate to the Package Registry, you must use one of the following: - It's not recommended, but you can use [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. You must use a personal access token with OAuth headers. - A [CI job token](#authenticate-with-a-ci-job-token). -- Your NPM package name must be in the format of [@scope:package-name](#package-naming-convention). It must match exactly, including the case. +- Your NPM package name must be in the format of [@scope/package-name](#package-naming-convention). It must match exactly, including the case. ### Authenticate with a personal access token or deploy token @@ -201,7 +204,7 @@ Then, you can run `npm publish` either locally or by using GitLab CI/CD. ## Package naming convention -Your NPM package name must be in the format of `@scope:package-name`. +Your NPM package name must be in the format of `@scope/package-name`. - The `@scope` is the root namespace of the GitLab project. It must match exactly, including the case. - The `package-name` can be whatever you want. @@ -241,7 +244,7 @@ Prerequisites: - [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. - Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages). -- Your NPM package name must be in the format of [@scope:package-name](#package-naming-convention). It must match exactly, including the case. +- Your NPM package name must be in the format of [@scope/package-name](#package-naming-convention). It must match exactly, including the case. To upload an NPM package to your project, run this command: @@ -461,7 +464,30 @@ If you get this error, ensure that: ### `npm publish` returns `npm ERR! 400 Bad Request` If you get this error, your package name may not meet the -[@scope:package-name package naming convention](#package-naming-convention). +[@scope/package-name package naming convention](#package-naming-convention). Ensure the name meets the convention exactly, including the case. Then try to publish again. + +### `npm publish` returns `npm ERR! 500 Internal Server Error - PUT` + +This is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/238950) in GitLab +13.3.x and later. The error in the logs will appear as: + +```plaintext +>NoMethodError - undefined method `preferred_language' for #<Rack::Response +``` + +This might be accompanied by another error: + +```plaintext +>Errno::EACCES","exception.message":"Permission denied +``` + +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) + is used. + +In the latter case, ensure the bucket exists and the GitLab has write access to it. diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index bdf50ecef0b..35172663cc1 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -60,6 +60,21 @@ NuGet CLI. mono nuget.exe ``` +## Use the GitLab endpoint for NuGet Packages + +To use the GitLab endpoint for NuGet Packages, choose an option: + +- **Project-level**: Use when you have few NuGet packages and they are not in + the same GitLab group. +- **Group-level**: Use when you have many NuGet packages in different within the + same GitLab group. + +Some features such as [publishing](#publish-a-nuget-package) a package are only available on the project-level endpoint. + +WARNING: +Because of how NuGet handles credentials, the Package Registry rejects anonymous requests on the group-level endpoint. +To work around this limitation, set up [authentication](#add-the-package-registry-as-a-source-for-nuget-packages). + ## Add the Package Registry as a source for NuGet packages To publish and install packages to the Package Registry, you must add the @@ -75,7 +90,9 @@ Prerequisites: with the scope set to `read_package_registry`, `write_package_registry`, or both. - A name for your source. -- Your project ID, which is found on your project's home page. +- Depending on the [endpoint level](#use-the-gitlab-endpoint-for-nuget-packages) you use, either: + - Your project ID, which is found on your project's home page. + - Your group ID, which is found on your group's home page. You can now add a new source to NuGet with: @@ -85,7 +102,9 @@ You can now add a new source to NuGet with: ### Add a source with the NuGet CLI -To add the Package Registry as a source with `nuget`: +#### Project-level endpoint + +To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with `nuget`: ```shell nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token> @@ -99,9 +118,27 @@ For example: nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password 12345678asdf ``` +#### Group-level endpoint + +To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with `nuget`: + +```shell +nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token> +``` + +- `<source_name>` is the desired source name. + +For example: + +```shell +nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/groups/23/-/packages/nuget/index.json" -UserName carol -Password 12345678asdf +``` + ### Add a source with Visual Studio -To add the Package Registry as a source with Visual Studio: +#### Project-level endpoint + +To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with Visual Studio: 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). 1. In Windows, select **File > Options**. On macOS, select **Visual Studio > Preferences**. @@ -126,9 +163,38 @@ The source is displayed in your list. If you get a warning, ensure that the **Location**, **Username**, and **Password** are correct. +#### Group-level endpoint + +To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with Visual Studio: + +1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). +1. In Windows, select **File > Options**. On macOS, select **Visual Studio > Preferences**. +1. In the **NuGet** section, select **Sources** to view a list of all your NuGet sources. +1. Select **Add**. +1. Complete the following fields: + - **Name**: Name for the source. + - **Location**: `https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json`, + where `<your_group_id>` is your group ID, and `gitlab.example.com` is + your domain name. + - **Username**: Your GitLab username or deploy token username. + - **Password**: Your personal access token or deploy token. + +  + +1. Click **Save**. + +The source is displayed in your list. + + + +If you get a warning, ensure that the **Location**, **Username**, and +**Password** are correct. + ### Add a source with the .NET CLI -To add the Package Registry as a source for .NET: +#### Project-level endpoint + +To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for .NET: 1. In the root of your project, create a file named `nuget.config`. 1. Add this content: @@ -138,7 +204,30 @@ To add the Package Registry as a source for .NET: <configuration> <packageSources> <clear /> - <add key="gitlab" value="https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" /> + <add key="gitlab" value="https://gitlab.example.com/api/v4/project/<your_project_id>/packages/nuget/index.json" /> + </packageSources> + <packageSourceCredentials> + <gitlab> + <add key="Username" value="<gitlab_username or deploy_token_username>" /> + <add key="ClearTextPassword" value="<gitlab_personal_access_token or deploy_token>" /> + </gitlab> + </packageSourceCredentials> + </configuration> + ``` + +#### Group-level endpoint + +To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for .NET: + +1. In the root of your project, create a file named `nuget.config`. +1. Add this content: + + ```xml + <?xml version="1.0" encoding="utf-8"?> + <configuration> + <packageSources> + <clear /> + <add key="gitlab" value="https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" /> </packageSources> <packageSourceCredentials> <gitlab> @@ -151,6 +240,10 @@ To add the Package Registry as a source for .NET: ## Publish a NuGet package +Prerequisite: + +- Set up the [source](#https://docs.gitlab.com/ee/user/packages/nuget_repository/#add-the-package-registry-as-a-source-for-nuget-packages) with a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages). + When publishing packages: - The Package Registry on GitLab.com can store up to 500 MB of content. @@ -164,9 +257,10 @@ When publishing packages: ### Publish a package with the NuGet CLI -Prerequisite: +Prerequisites: - [A NuGet package created with NuGet CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package). +- Set a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages). Publish a package by running this command: @@ -179,9 +273,10 @@ nuget push <package_file> -Source <source_name> ### Publish a package with the .NET CLI -Prerequisite: +Prerequisites: - [A NuGet package created with .NET CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli). +- Set a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages). Publish a package by running this command: diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index e78224f89d1..376c0439f32 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -233,11 +233,16 @@ password = ${env.CI_JOB_TOKEN} ## Publish a PyPI package -When publishing packages, note that: +Prerequisites: -- The maximum allowed size is 50 MB. +- You must [authenticate with the Package Registry](#authenticate-with-the-package-registry). +- Your [version string must be valid](#ensure-your-version-string-is-valid). +- The maximum allowed package size is 5 GB. - You can't upload the same version of a package multiple times. If you try, - you receive the error `Validation failed: File name has already been taken`. + you receive the error `400 Bad Request`. +- You cannot publish PyPI packages to a group, only to a project. + +You can then [publish a package by using twine](#publish-a-pypi-package-by-using-twine). ### Ensure your version string is valid @@ -301,6 +306,12 @@ python -m twine upload --repository <source_name> dist/<package_file> - `<package_file>` is your package filename, ending in `.tar.gz` or `.whl`. - `<source_name>` is the [source name used during setup](#authenticate-with-the-package-registry). +### Publishing packages with the same name or version + +You cannot publish a package if a package of the same name and version already exists. +You must delete the existing package first. If you attempt to publish the same package +more than once, a `404 Bad Request` error occurs. + ## Install a PyPI package To install the latest version of a package, use the following command: diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index aea1238b9da..d20c75e2d7a 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -68,7 +68,7 @@ For Conan, you need to add GitLab as a Conan registry remote. Follow the instruc Then, create your package using the plus-separated (`+`) project path as your Conan user. For example, if your project is located at `https://gitlab.com/foo/bar/my-proj`, [create your Conan package](../conan_repository/index.md) using `conan create . foo+bar+my-proj/channel`. -`channel` is your package channel (such as `stable` or `beta`). +`channel` is your package channel (such as `stable` or `beta`). After you create your package, you're ready to [publish your package](../conan_repository/index.md#publish-a-conan-package), depending on your final package recipe. For example: diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 0dd7d6f7696..3dbae78ccc4 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -75,6 +75,7 @@ The following table depicts the various user permission levels in a project. | Manage user-starred metrics dashboards (*7*) | ✓ | ✓ | ✓ | ✓ | ✓ | | View confidential issues | (*2*) | ✓ | ✓ | ✓ | ✓ | | Assign issues | | ✓ | ✓ | ✓ | ✓ | +| Assign reviewers | | ✓ | ✓ | ✓ | ✓ | | Label issues | | ✓ | ✓ | ✓ | ✓ | | Set issue weight | | ✓ | ✓ | ✓ | ✓ | | Lock issue threads | | ✓ | ✓ | ✓ | ✓ | @@ -94,7 +95,7 @@ The following table depicts the various user permission levels in a project. | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | | Archive/reopen requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | | Create/edit requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| Import requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| Import/export requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | | Create new [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | | Archive [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | | Move [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | @@ -322,7 +323,7 @@ project and should only have access to that project. External users: -- Cannot create groups, projects, or personal snippets. +- Cannot create projects (including forks), groups, or personal snippets. - Can only access public projects and projects to which they are explicitly granted access, thus hiding all other internal or private ones from them (like being logged out). diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index c25535cbf65..6cdd2d6f161 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -245,7 +245,7 @@ Search for `security.webauth.u2f` and double click on it to toggle to `true`. To set up 2FA with a U2F device: -1. Log in to your GitLab account. +1. Sign in to your GitLab account. 1. Go to your [**Profile settings**](../index.md#profile-settings). 1. Go to **Account**. 1. Click **Enable Two-Factor Authentication**. @@ -298,11 +298,11 @@ NOTE: Recovery codes are not generated for U2F / WebAuthn devices. WARNING: -Each code can be used only once to log in to your account. +Each code can be used only once to sign in to your account. Immediately after successfully enabling two-factor authentication, you're prompted to download a set of generated recovery codes. Should you ever lose access -to your one-time password authenticator, you can use one of these recovery codes to log in to +to your one-time password authenticator, you can use one of these recovery codes to sign in to your account. We suggest copying and printing them, or downloading them using the **Download codes** button for storage in a safe place. If you choose to download them, the file is called `gitlab-recovery-codes.txt`. @@ -314,41 +314,41 @@ If you lose the recovery codes or just want to generate new ones, you can do so from the [two-factor authentication account settings page](#regenerate-2fa-recovery-codes) or [using SSH](#generate-new-recovery-codes-using-ssh). -## Logging in with 2FA Enabled +## Signing in with 2FA Enabled -Logging in with 2FA enabled is only slightly different than a normal login. +Signing in with 2FA enabled is only slightly different than the normal sign-in process. Enter your username and password credentials as you normally would, and you're presented with a second prompt, depending on which type of 2FA you've enabled. -### Log in via a one-time password +### Sign in by using a one-time password When asked, enter the pin from your one time password authenticator's application or a -recovery code to log in. +recovery code to sign in. -### Log in via U2F device +### Sign in by using a U2F device -To log in via a U2F device: +To sign in by using a U2F device: 1. Click **Login via U2F Device**. 1. A light begins blinking on your device. Activate it by touching/pressing its button. A message displays, indicating that your device responded to the authentication -request, and you're automatically logged in. +request, and you're automatically signed in. -### Log in via WebAuthn device +### Sign in by using a WebAuthn device In supported browsers you should be automatically prompted to activate your WebAuthn device (e.g. by touching/pressing its button) after entering your credentials. A message displays, indicating that your device responded to the authentication -request and you're automatically logged in. +request and you're automatically signed in. ## Disabling 2FA If you ever need to disable 2FA: -1. Log in to your GitLab account. +1. Sign in to your GitLab account. 1. Go to your [**Profile settings**](../index.md#profile-settings). 1. Go to **Account**. 1. Click **Disable**, under **Two-Factor Authentication**. @@ -356,6 +356,9 @@ If you ever need to disable 2FA: This clears all your two-factor authentication registrations, including mobile applications and U2F / WebAuthn devices. +Support for disabling 2FA is limited, depending on your subscription level. For more information, see the +[Account Recovery](https://about.gitlab.com/support/#account-recovery) section of our website. + ## Personal access tokens When 2FA is enabled, you can no longer use your normal account password to @@ -393,9 +396,13 @@ a new set of recovery codes with SSH: 1. Run: ```shell - ssh git@gitlab.example.com 2fa_recovery_codes + ssh git@gitlab.com 2fa_recovery_codes ``` + NOTE: + On self-managed instances, replace **`gitlab.com`** in the command above + with the GitLab server hostname (`gitlab.example.com`). + 1. You are prompted to confirm that you want to generate new codes. Continuing this process invalidates previously saved codes: @@ -465,9 +472,9 @@ Sign in and re-enable two-factor authentication as soon as possible. For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`: - - The user logs in via `first.host.xyz` and registers their U2F key. - - The user logs out and attempts to log in via `first.host.xyz` - U2F authentication succeeds. - - The user logs out and attempts to log in via `second.host.xyz` - U2F authentication fails, because + - The user signs in by using `first.host.xyz` and registers their U2F key. + - The user signs out and attempts to sign in by using `first.host.xyz` - U2F authentication succeeds. + - The user signs out and attempts to sign in by using `second.host.xyz` - U2F authentication fails, because the U2F key has only been registered on `first.host.xyz`. - To enforce 2FA at the system or group levels see [Enforce Two-factor Authentication](../../../security/two_factor_authentication.md). diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index d60fb528499..a96975fea92 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -203,11 +203,12 @@ If you previously selected the "Busy" checkbox, remember to deselect it when you ## Busy status indicator -> - Introduced in GitLab 13.6. -> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259649) in GitLab 13.6. +> - It was [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/281073) in GitLab 13.8. +> - It's enabled on GitLab.com. > - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-busy-status-feature). +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-busy-status-feature). To indicate to others that you are busy, you can set an indicator @@ -228,10 +229,16 @@ To set the busy status indicator, either: 1. Click **Edit profile** (**{pencil}**). 1. Select the **Busy** checkbox -### Enable busy status feature +### Disable busy status feature -The busy status feature is deployed behind a feature flag and is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can enable it for your instance from the [rails console](../../administration/feature_flags.md#start-the-gitlab-rails-console). +The busy status feature is deployed behind a feature flag and is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can disable it for your instance from the [rails console](../../administration/feature_flags.md#start-the-gitlab-rails-console). + +To disable it: + +```ruby +Feature.disable(:set_user_availability_status) +``` To enable it: @@ -288,7 +295,7 @@ git config --global user.email <your email address> When signing in to the main GitLab application, a `_gitlab_session` cookie is set. `_gitlab_session` is cleared client-side when you close your browser and expires after "Application settings -> Session duration (minutes)"/`session_expire_delay` -(defaults to `10080` minutes = 7 days). +(defaults to `10080` minutes = 7 days) of no activity. When signing in to the main GitLab application, you can also check the "Remember me" option which sets the `remember_user_token` @@ -316,7 +323,9 @@ The `remember_user_token` lifetime of a cookie can now extend beyond the deadlin GitLab uses both session and persistent cookies: -- Session cookie: Session cookies are normally removed at the end of the browser session when the browser is closed. The `_gitlab_session` cookie has no expiration date. +- Session cookie: Session cookies are normally removed at the end of the browser session when + the browser is closed. The `_gitlab_session` cookie has no fixed expiration date. However, + it expires based on its [`session_expire_delay`](#why-do-i-keep-getting-signed-out). - Persistent cookie: The `remember_user_token` is a cookie with an expiration date of two weeks. GitLab activates this cookie if you click Remember Me when you sign in. By default, the server sets a time-to-live (TTL) of 1-week on any session that is used. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 8974505cf02..38ef01b7537 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -146,13 +146,15 @@ Users are notified of the following events: | New email added | User | Security email, always sent. | | Email changed | User | Security email, always sent. | | Password changed | User | Security email, always sent when user changes their own password | -| Password changed by administrator | User | Security email, always sent when an administrator changes the password of another user | +| Password changed by administrator | User | Security email, always sent when an administrator changes the password of another user | | Two-factor authentication disabled | User | Security email, always sent. | | New user created | User | Sent on user creation, except for OmniAuth (LDAP)| | User added to project | User | Sent when user is added to project | | Project access level changed | User | Sent when user project access level is changed | | User added to group | User | Sent when user is added to group | | Group access level changed | User | Sent when user group access level is changed | +| Personal Access Tokens expiring soon <!-- Do not delete or lint this instance of future tense --> | User | Security email, always sent. | +| Personal Access Tokens have expired | User | Security email, always sent. | | Project moved | Project members (1) | (1) not disabled | | New release | Project members | Custom notification | diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index cfc70c5a6f0..49889cd3017 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -112,7 +112,7 @@ token = PersonalAccessToken.find_by_token('token-string-here123') token.revoke! ``` -This can be shorted into a single-line shell command using the +This can be shortened into a single-line shell command using the [Rails runner](../../administration/troubleshooting/debug.md#using-the-rails-runner): ```shell diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 52c825932fa..85ac641f6e4 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -4,9 +4,10 @@ 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 --- -# Canary Deployments **(PREMIUM)** +# Canary Deployments **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Core in 13.8. A popular [Continuous Deployment](https://en.wikipedia.org/wiki/Continuous_deployment) strategy, where a small portion of the fleet is updated to the new version of @@ -71,7 +72,7 @@ can easily notice them. ### Advanced traffic control with Canary Ingress > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Core in GitLab 13.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Core in GitLab 13.8. Canary deployments can be more strategic with [Canary Ingress](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#canary), which is an advanced traffic routing service that controls incoming HTTP diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 4fae10c58eb..9047e564598 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -122,6 +122,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: "iam:CreateInstanceProfile", "iam:CreateServiceLinkedRole", "iam:GetRole", + "iam:listAttachedRolePolicies", "iam:ListRoles", "iam:PassRole", "ssm:GetParameters" diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 8ee9b1f37dd..beb8b71b917 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -189,7 +189,7 @@ To add a Kubernetes cluster to your project, group, or instance: Get the API URL by running this command: ```shell - kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' + kubectl cluster-info | grep -E 'Kubernetes master|Kubernetes control plane' | awk '/http/ {print $NF}' ``` 1. **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We use the certificate created by default. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 55467c8a468..a06846e33a6 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -20,7 +20,7 @@ Using the GitLab project Kubernetes integration, you can: - Detect and [monitor Kubernetes](#monitoring-your-kubernetes-cluster). - Use it with [Auto DevOps](#auto-devops). - Use [Web terminals](#web-terminals). -- Use [Deploy Boards](#deploy-boards). **(PREMIUM)** +- Use [Deploy Boards](#deploy-boards). - Use [Canary Deployments](#canary-deployments). **(PREMIUM)** - Use [deployment variables](#deployment-variables). - Use [role-based or attribute-based access controls](add_remove_clusters.md#access-controls). @@ -248,9 +248,17 @@ Deployment variables require a valid [Deploy Token](../deploy_tokens/index.md) n [`gitlab-deploy-token`](../deploy_tokens/index.md#gitlab-deploy-token), and the following command in your deployment job script, for Kubernetes to access the registry: -```plaintext -kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run | kubectl apply -f - -``` +- Using Kubernetes 1.18+: + + ```shell + kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run=client | kubectl apply -f - + ``` + +- Using Kubernetes <1.18: + + ```shell + kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run | kubectl apply -f - + ``` The Kubernetes cluster integration exposes the following [deployment variables](../../../ci/variables/README.md#deployment-environment-variables) in the @@ -308,7 +316,7 @@ combined with either ### Integrations -#### Canary Deployments **(PREMIUM)** +#### Canary Deployments Leverage [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) and visualize your canary deployments right inside the Deploy Board, without @@ -316,7 +324,7 @@ the need to leave GitLab. [Read more about Canary Deployments](../canary_deployments.md) -#### Deploy Boards **(PREMIUM)** +#### Deploy Boards GitLab Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../../ci/environments/index.md) running on Kubernetes, diff --git a/doc/user/project/clusters/protect/container_host_security/index.md b/doc/user/project/clusters/protect/container_host_security/index.md new file mode 100644 index 00000000000..102001d4f87 --- /dev/null +++ b/doc/user/project/clusters/protect/container_host_security/index.md @@ -0,0 +1,59 @@ +--- +stage: Protect +group: Container Security +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/#designated-technical-writers +--- + +# Container Host Security + +Container Host Security in GitLab provides Intrusion Detection and Prevention capabilities that can +monitor and (optionally) block activity inside the containers themselves. This is done by leveraging +an integration with Falco to provide the monitoring capabilities and an integration with Pod +Security Policies and AppArmor to provide blocking capabilities. + +## Overview + +Container Host Security can be used to monitor and block activity inside a container as well as to +enforce security policies across the entire Kubernetes cluster. Falco profiles allow for users to +define the activity they want to monitor for and detect. Among other things, this can include system +log entries, process starts, file activity, and network ports opened. AppArmor is used to block any +undesired activity via AppArmor profiles. These profiles are loaded into the cluster when +referenced by Pod Security Policies. + +By default, Container Host Security is deployed into the cluster in monitor mode only, with no +default profiles or rules running out-of-the-box. Activity monitoring and blocking begins only when +users define profiles for these technologies. + +## Installation + +See the [installation guide](quick_start_guide.md) for the recommended steps to install the +Container Host Security capabilities. This guide shows the recommended way of installing Container +Host Security through GMAv2. However, it's also possible to do a manual installation through our +Helm chart. + +## Features + +- Prevent containers from starting as root. +- Limit the privileges and system calls available to containers. +- Monitor system logs, process starts, files read/written/deleted, and network ports opened. +- Optionally block processes from starting or files from being read/written/deleted. + +## Supported container orchestrators + +Kubernetes v1.14+ is the only supported container orchestrator. OpenShift and other container +orchestrators aren't supported. + +## Supported Kubernetes providers + +The following cloud providers are supported: + +- Amazon EKS +- Google GKE + +Although Container Host Security may function on Azure or self-managed Kubernetes instances, it isn't +officially tested and supported on those providers. + +## Roadmap + +See the [Category Direction page](https://about.gitlab.com/direction/protect/container_host_security/) +for more information on the product direction of Container Host Security. diff --git a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md new file mode 100644 index 00000000000..0c4ec72ed5b --- /dev/null +++ b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md @@ -0,0 +1,81 @@ +--- +stage: Protect +group: Container Security +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/#designated-technical-writers +--- + +# Getting started with Container Host Security + +The following steps are recommended for installing Container Host Security. Although you can install +some capabilities through GMAv1, we [recommend](#using-gmav1-with-gmav2) that you install +applications through GMAv2 exclusively when using Container Network Security. + +## Installation steps + +The following steps are recommended to install and use Container Host Security through GitLab: + +1. [Install at least one runner and connect it to GitLab](https://docs.gitlab.com/runner/). +1. [Create a group](../../../../group/#create-a-new-group). +1. [Connect a Kubernetes cluster to the group](../../add_remove_clusters.md). +1. [Create a cluster management project and associate it with the Kubernetes cluster](../../../../clusters/management_project.md). + +1. Install and configure an Ingress node: + + - [Install the Ingress node via CI/CD (GMAv2)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). + - [Determine the external endpoint via the manual method](../../../../clusters/applications.md#determining-the-external-endpoint-manually). + - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain) + into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes + cluster. + +1. [Install and configure Falco](../../../../clusters/applications.md#install-falco-using-gitlab-cicd) + for activity monitoring. +1. [Install and configure AppArmor](../../../../clusters/applications.md#install-apparmor-using-gitlab-cicd) + for activity blocking. +1. [Configure Pod Security Policies](../../../../clusters/applications.md#using-podsecuritypolicy-in-your-deployments) + (required to be able to load AppArmor profiles). + +It's possible to install and manage Falco and AppArmor in other ways, such as installing them +manually in a Kubernetes cluster and then connecting it back to GitLab. These methods aren't +supported or documented. + +## Viewing the logs + +Falco logs can be viewed by running the following command in your Kubernetes cluster: + +```shell +kubectl -n gitlab-managed-apps logs -l app=falco +``` + +## Troubleshooting + +### Trouble connecting to the cluster + +Your CI/CD pipeline may occasionally fail or have trouble connecting to the cluster. Here are some +initial troubleshooting steps that resolve the most common problems: + +1. [Clear the cluster cache](../../index.md#clearing-the-cluster-cache) +1. If things still aren't working, a more assertive set of actions may help get things back to a + good state: + + - Stop and [delete the problematic environment](../../../../../ci/environments/#delete-environments-through-the-ui) + in GitLab. + - Delete the relevant namespace in Kubernetes by running + `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster. + - Rerun the application project pipeline to redeploy the application. + +### Using GMAv1 with GMAv2 + +When GMAv1 and GMAv2 are used together on the same cluster, users may experience problems with +applications being uninstalled or removed from the cluster. This is because GMAv2 actively +uninstalls applications that are installed with GMAv1 and not configured to be installed with GMAv2. +It's possible to use a mixture of applications installed with GMAv1 and GMAv2 by ensuring that the +GMAv1 applications are installed **after** the GMAv2 cluster management project pipeline runs. GMAv1 +applications must be reinstalled after each run of that pipeline. This approach isn't recommended as +it's error-prone and can lead to downtime as applications are uninstalled and later reinstalled. +When using Container Network Security, the preferred and recommended path is to install all +necessary components with GMAv2 and the cluster management project. + +**Related documentation links:** + +- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click) +- [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md) diff --git a/doc/user/project/clusters/protect/container_network_security/index.md b/doc/user/project/clusters/protect/container_network_security/index.md new file mode 100644 index 00000000000..8299844e511 --- /dev/null +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -0,0 +1,70 @@ +--- +stage: Protect +group: Container Security +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/#designated-technical-writers +--- + +# Container Network Security + +Container Network Security in GitLab provides basic firewall functionality by leveraging Cilium +NetworkPolicies to filter traffic going in and out of the cluster as well as traffic between pods +inside the cluster. Container Network Security can be used to enforce L3, L4, and L7 policies and +can prevent an attacker with control over one pod from spreading laterally to access other pods in +the same cluster. Both Ingress and Egress rules are supported. + +By default, Cilium is deployed in Detection-only mode and only logs attack attempts. GitLab provides +a set of out-of-the-box policies as examples and to help users get started. These policies are +disabled by default, as they must usually be customized to match application-specific needs. + +## Installation + +See the [installation guide](quick_start_guide.md) for the recommended steps to install GitLab +Container Network Security. This guide shows the recommended way of installing Container Network +Security through GMAv2. However, it's also possible to install Cilium manually through our Helm +chart. + +## Features + +- GitLab managed installation of Cilium. +- Support for L3, L4, and L7 policies. +- Ability to export logs to a SIEM. +- Statistics page showing volume of packets processed and dropped over time (Gold/Ultimate users + only). +- Management of NetworkPolicies through code in a project (Available for auto DevOps users only). +- Management of CiliumNetworkPolicies through a UI policy manager (Gold/Ultimate users only). + +## Supported container orchestrators + +Kubernetes v1.14+ is the only supported container orchestrator. OpenShift and other container +orchestrators aren't supported. + +## Supported Kubernetes providers + +The following cloud providers are supported: + +- Amazon EKS +- Google GKE + +Although Container Network Security may function on Azure or self-managed Kubernetes instances, it +isn't officially tested and supported on those providers. + +## Supported NetworkPolicies + +GitLab only supports the use of CiliumNetworkPolicies. Although generic Kubernetes NetworkPolicies +or other kinds of NetworkPolicies may work, GitLab doesn't test or support them. + +## Managing NetworkPolicies through GitLab vs your cloud provider + +Some cloud providers offer integrations with Cilium or offer other ways to manage NetworkPolicies in +Kubernetes. GitLab Container Network Security doesn't support deployments that have NetworkPolicies +managed by an external provider. By choosing to manage NetworkPolicies through GitLab, you can take +advantage of the following benefits: + +- Support for handling NetworkPolicy infrastructure as code. +- Full revision history and audit log of all changes made. +- Ability to revert back to a previous version at any time. + +## Roadmap + +See the [Category Direction page](https://about.gitlab.com/direction/protect/container_network_security/) +for more information on the product direction of Container Network Security. diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md new file mode 100644 index 00000000000..10f9380a1f2 --- /dev/null +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -0,0 +1,153 @@ +--- +stage: Protect +group: Container Security +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/#designated-technical-writers +--- + +# Getting started with Container Network Security + +The following steps are recommended for installing Container Network Security. Although you can +install some capabilities through GMAv1, we [recommend](#using-gmav1-with-gmav2) that you install +applications through GMAv2 exclusively when using Container Network Security. + +## Installation steps + +The following steps are recommended to install and use Container Network Security through GitLab: + +1. [Install at least one runner and connect it to GitLab](https://docs.gitlab.com/runner/). +1. [Create a group](../../../../group/#create-a-new-group). +1. [Connect a Kubernetes cluster to the group](../../add_remove_clusters.md). +1. [Create a cluster management project and associate it with the Kubernetes cluster](../../../../clusters/management_project.md). + +1. Install and configure an Ingress node: + + - [Install the Ingress node via CI/CD (GMAv2)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). + - [Determine the external endpoint via the manual method](../../../../clusters/applications.md#determining-the-external-endpoint-manually). + - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain) + into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes + cluster. + +1. [Install and configure Cilium](../../../../clusters/applications.md#install-cilium-using-gitlab-cicd). +1. Be sure to restart all pods that were running before Cilium was installed by running this command + in your cluster: + + `kubectl get pods --all-namespaces -o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,HOSTNETWORK:.spec.hostNetwork --no-headers=true | grep '<none>' | awk '{print "-n "$1" "$2}' | xargs -L 1 -r kubectl delete pod` + +It's possible to install and manage Cilium in other ways. For example, you could use the GitLab Helm +chart to install Cilium manually in a Kubernetes cluster, and then connect it back to GitLab. +However, such methods aren't documented or officially supported by GitLab. + +## Managing Network Policies + +Managing NetworkPolicies through GitLab is advantageous over managing the policies in Kubernetes +directly. Kubernetes doesn't provide a GUI editor, a change control process, or a revision history. +Network Policies can be managed through GitLab in one of two ways: + +- Management through a YAML file in each application's project (for projects using Auto DevOps). For + more information, see the [Network Policy documentation](../../../../../topics/autodevops/stages.md#network-policy). +- Management through the GitLab Policy management UI (for projects not using Auto DevOps). For more + information, see the [Container Network Policy documentation](../../../../application_security/threat_monitoring/index.md#container-network-policy-management) (Ultimate/Gold only). + +Each method has benefits and drawbacks: + +| | YAML method | UI method (Ultimate/Gold only) | +|--|:------------|:-------------------------------| +| **Benefits** | A change control process is possible by requiring [MR Approvals](../../../merge_requests/merge_request_approvals.md). All changes are fully tracked and audited in the same way that Git tracks the history of any file in its repository. | The UI provides a simple rules editor for users who are less familiar with the YAML syntax of NetworkPolicies. This view is a live representation of the policies currently deployed in the Kubernetes cluster. The UI also allows for multiple network policies to be created per environment. | +| **Drawbacks** | Only one network policy can be deployed per environment (although that policy can be as detailed as needed). Also, if changes were made in Kubernetes directly rather than through the `auto-deploy-values.yaml` file, the YAML file's contents don't represent the actual state of policies deployed in Kubernetes. | Policy changes aren't audited and a change control process isn't available. | + +Users are encouraged to choose one of the two methods to manage their policies. If users attempt to +use both methods simultaneously, when the application project pipeline runs the contents of the +NetworkPolicy in the `auto-deploy-values.yaml` file may override policies configured in the UI +editor. + +## Monitoring throughput `**(ULTIMATE)**` + +To view statistics for Container Network Security, you must follow the installation steps above and +configure GitLab integration with Prometheus. Also, if you use custom Helm values for Cilium, you +must enable Hubble with flow metrics for each namespace by adding the following lines to +your [Cilium values](../../../../clusters/applications.md#install-cilium-using-gitlab-cicd): +your [Cilium values](../../../../clusters/applications.md#install-cilium-using-gitlab-cicd): + +```yaml +global: + hubble: + enabled: true + metrics: + enabled: + - 'flow:sourceContext=namespace;destinationContext=namespace' +``` + +Additional information about the statistics page is available in the +[documentation that describes the Threat Management UI](../../../../application_security/threat_monitoring/index.md#container-network-policy). + +## Forwarding logs to a SIEM + +Cilium logs can be forwarded to a SIEM or an external logging system through syslog protocol by +installing and configuring Fluentd. Fluentd can be installed through GitLab in two ways: + +- The [GMAv1 method](../../../../clusters/applications.md#fluentd) +- The [GMAv2 method](../../../../clusters/applications.md#install-fluentd-using-gitlab-cicd) + +GitLab strongly encourages using only the GMAv2 method to install Fluentd. + +## Viewing the logs + +Cilium logs can be viewed by running the following command in your Kubernetes cluster: + +```shell +kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor +``` + +## Troubleshooting + +### Traffic is not being blocked as expected + +By default, Cilium is installed in Audit mode only, meaning that NetworkPolicies log policy +violations but don't block any traffic. To set Cilium to Blocking mode, you must add the following +lines to the `.gitlab/managed-apps/cilium/values.yaml` file in your cluster management project: + +```yaml +config: + policyAuditMode: false + +agent: + monitor: + eventTypes: ["drop"] +``` + +### Traffic is not being allowed as expected + +Keep in mind that when Cilium is set to blocking mode (rather than Audit mode), NetworkPolicies +operate on an allow-list basis. If one or more NetworkPolicies apply to a node, then all traffic +that doesn't match at least one Policy is blocked. To resolve, add NetworkPolicies defining the +traffic that you want to allow in the node. + +### Trouble connecting to the cluster + +Occasionally, your CI/CD pipeline may fail or have trouble connecting to the cluster. Here are some +initial troubleshooting steps that resolve the most common problems: + +1. [Clear the cluster cache](../../index.md#clearing-the-cluster-cache). +1. If things still aren't working, a more assertive set of actions may help get things back into a + good state: + + - Stop and [delete the problematic environment](../../../../../ci/environments/index.md#delete-environments-through-the-ui) in GitLab. + - Delete the relevant namespace in Kubernetes by running `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster. + - Rerun the application project pipeline to redeploy the application. + +### Using GMAv1 with GMAv2 + +When GMAv1 and GMAv2 are used together on the same cluster, users may experience problems with +applications being uninstalled or removed from the cluster. This is because GMAv2 actively +uninstalls applications that are installed with GMAv1 and not configured to be installed with GMAv2. +It's possible to use a mixture of applications installed with GMAv1 and GMAv2 by ensuring that the +GMAv1 applications are installed **after** the GMAv2 cluster management project pipeline runs. GMAv1 +applications must be reinstalled after each run of that pipeline. This approach isn't recommended as +it's error-prone and can lead to downtime as applications are uninstalled and later reinstalled. +When using Container Network Security, the preferred and recommended path is to install all +necessary components with GMAv2 and the cluster management project. + +**Related documentation links:** + +- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click) +- [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md) diff --git a/doc/user/project/clusters/protect/index.md b/doc/user/project/clusters/protect/index.md new file mode 100644 index 00000000000..c489a0ddd30 --- /dev/null +++ b/doc/user/project/clusters/protect/index.md @@ -0,0 +1,29 @@ +--- +stage: Protect +group: Container Security +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/#designated-technical-writers +--- + +# Protecting your deployed applications + +GitLab makes it straightforward to protect applications deployed in [connected Kubernetes clusters](index.md). +These protections are available in the Kubernetes network layer and in the container itself. At +the network layer, the Container Network Security capabilities in GitLab provide basic firewall +functionality by leveraging Cilium NetworkPolicies to filter traffic going in and out of the cluster +and traffic between pods inside the cluster. Inside the container, Container Host Security provides +Intrusion Detection and Prevention capabilities that can monitor and block activity inside the +containers themselves. + +## Capabilities + +The following capabilities are available to protect deployed applications in Kubernetes: + +- Web Application Firewall + - [Overview](web_application_firewall/index.md) + - [Installation guide](web_application_firewall/quick_start_guide.md) +- Container Network Security + - [Overview](container_network_security/index.md) + - [Installation guide](container_network_security/quick_start_guide.md) +- Container Host Security + - [Overview](container_host_security/index.md) + - [Installation guide](container_host_security/quick_start_guide.md) diff --git a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png Binary files differnew file mode 100644 index 00000000000..2dd6df3d37b --- /dev/null +++ b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png diff --git a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_installation_v12_10.png b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_installation_v12_10.png Binary files differnew file mode 100644 index 00000000000..e88f62a2eba --- /dev/null +++ b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_installation_v12_10.png diff --git a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png Binary files differnew file mode 100644 index 00000000000..1c99d4f7f96 --- /dev/null +++ b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png diff --git a/doc/user/project/clusters/protect/web_application_firewall/index.md b/doc/user/project/clusters/protect/web_application_firewall/index.md new file mode 100644 index 00000000000..6e2e71c6ced --- /dev/null +++ b/doc/user/project/clusters/protect/web_application_firewall/index.md @@ -0,0 +1,103 @@ +--- +stage: Protect +group: Container Security +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 +--- + +# Web Application Firewall + +WARNING: +The Web Application Firewall is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/271276) +in GitLab 13.6, and planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/271349) +in GitLab 14.0. + +A web application firewall (or WAF) filters, monitors, and blocks HTTP traffic to +and from a web application. By inspecting HTTP traffic, it can prevent attacks +stemming from web application security flaws. It can be used to detect SQL injection, +Cross-Site Scripting (XSS), Remote File Inclusion, Security Misconfigurations, and +much more. + +## Overview + +GitLab provides a WAF out of the box after Ingress is deployed. All you need to do is deploy your +application along with a service and Ingress resource. In the GitLab [Ingress](../../../../clusters/applications.md#ingress) +deployment, the [ModSecurity](https://modsecurity.org/) +module is loaded into Ingress-NGINX by default and monitors the traffic to the applications +which have an Ingress. The ModSecurity module runs with the [OWASP Core Rule Set (CRS)](https://coreruleset.org/) +by default. The OWASP CRS detects and logs a wide range of common attacks. + +By default, the WAF is deployed in Detection-only mode and only logs attack attempts. + +## Requirements + +The Web Application Firewall requires: + +- **Kubernetes** + + To enable the WAF, you need: + + - Kubernetes 1.12+. + - A load balancer. You can use NGINX-Ingress by deploying it to your + Kubernetes cluster by either: + - Using the [`nginx-ingress` Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). + - Installing the [Ingress GitLab Managed App](../../../../clusters/applications.md#ingress) with WAF enabled. + +- **Configured Kubernetes objects** + + To use the WAF on an application, you need to deploy the following Kubernetes resources: + + - [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) + - [Service](https://kubernetes.io/docs/concepts/services-networking/service/) + - [Ingress Resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) + +## Quick start + +If you are using GitLab.com, see the [quick start guide](quick_start_guide.md) for +how to use the WAF with GitLab.com and a Kubernetes cluster on Google Kubernetes Engine (GKE). + +If you are using a self-managed instance of GitLab, you must configure the +[Google OAuth2 OmniAuth Provider](../../../../../integration/google.md) before +you can configure a cluster on GKE. Once this is set up, you can follow the steps on the +[quick start guide](quick_start_guide.md) +to get started. + +NOTE: +This guide shows how the WAF can be deployed using Auto DevOps. The WAF +is available by default to all applications no matter how they are deployed, +as long as they are using Ingress. + +## Network firewall vs. Web Application Firewall + +A network firewall or packet filter looks at traffic at the Network (L3) and Transport (L4) layers +of the [OSI Model](https://en.wikipedia.org/wiki/OSI_model), and denies packets from entry based on +a set of rules regarding the network in general. + +A Web Application Firewall operates at the Application (L7) layer of the OSI Model and can +examine all the packets traveling to and from a specific application. A WAF can set +more advanced rules around threat detection. + +## Features + +ModSecurity is enabled with the [OWASP Core Rule Set (CRS)](https://github.com/coreruleset/coreruleset/) by +default. The OWASP CRS logs attempts to the following attacks: + +- [SQL Injection](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_SQL_Injection) +- [Cross-Site Scripting](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Cross-Site_Scripting_(XSS)) +- [Local File Inclusion](https://wiki.owasp.org/index.php/Testing_for_Local_File_Inclusion) +- [Remote File Inclusion](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Remote_File_Inclusion) +- [Code Injection](https://wiki.owasp.org/index.php/Code_Injection) +- [Session Fixation](https://wiki.owasp.org/index.php/Session_fixation) +- [Scanner Detection](https://wiki.owasp.org/index.php/Category:Vulnerability_Scanning_Tools) +- [Metadata/Error Leakages](https://wiki.owasp.org/index.php/Improper_Error_Handling) + +It is good to have a basic knowledge of the following: + +- [Kubernetes](https://kubernetes.io/docs/home/) +- [Ingress](https://kubernetes.github.io/ingress-nginx/) +- [ModSecurity](https://www.modsecurity.org/) +- [OWASP Core Rule Set](https://github.com/coreruleset/coreruleset/) + +## Roadmap + +You can find more information on the product direction of the WAF in +[Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/). diff --git a/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md b/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md new file mode 100644 index 00000000000..e9a05b58fec --- /dev/null +++ b/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md @@ -0,0 +1,265 @@ +--- +stage: Protect +group: Container Security +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 +--- + +# Getting started with the Web Application Firewall + +WARNING: +The Web Application Firewall is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/271276) +in GitLab 13.6, and planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/271349) +in GitLab 14.0. + +This is a step-by-step guide to help you use the GitLab [Web Application Firewall](index.md) after +deploying a project hosted on GitLab.com to Google Kubernetes Engine using [Auto DevOps](../../../../../topics/autodevops/index.md). + +The GitLab native Kubernetes integration is used, so you do not need +to create a Kubernetes cluster manually using the Google Cloud Platform console. +A simple application is created and deployed based on a GitLab template. + +These instructions also work for a self-managed GitLab instance. However, you +need to ensure your own [runners are configured](../../../../../ci/runners/README.md) and +[Google OAuth is enabled](../../../../../integration/google.md). + +The GitLab Web Application Firewall is deployed with [Ingress](../../../../clusters/applications.md#ingress), +so it is available to your applications no matter how you deploy them to Kubernetes. + +## Configuring your Google account + +Before creating and connecting your Kubernetes cluster to your GitLab project, +you need a Google Cloud Platform account. If you do not already have one, +sign up at <https://console.cloud.google.com>. You need to either sign in with an existing +Google account (for example, one that you use to access Gmail, Drive, etc.) or create a new one. + +1. To enable the required APIs and related services, follow the steps in the ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). +1. Make sure you have created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account). + +NOTE: +Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial), +and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with the GitLab +Google Kubernetes Engine integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?PCN=a0n60000006Vpz4AAC) and apply for credit. + +## Creating a new project from a template + +We use a GitLab project templates to get started. As the name suggests, +those projects provide a barebones application built on some well-known frameworks. + +1. In GitLab, click the plus icon (**+**) at the top of the navigation bar and select + **New project**. +1. Go to the **Create from template** tab where you can choose for example a Ruby on + Rails, Spring, or NodeJS Express project. + Use the Ruby on Rails template. + +  + +1. Give your project a name, optionally a description, and make it public so that + you can take advantage of the features available in the + [GitLab Gold plan](https://about.gitlab.com/pricing/#gitlab-com). + +  + +1. Click **Create project**. + +Now that the project is created, the next step is to create the Kubernetes cluster +to deploy this application under. + +## Creating a Kubernetes cluster from within GitLab + +1. On the project's landing page, click **Add Kubernetes cluster** + (note that this option is also available when you navigate to **Operations > Kubernetes**). + +  + +1. On the **Create new cluster on GKE** tab, click **Sign in with Google**. + +  + +1. Connect with your Google account and click **Allow** when asked (this + appears only the first time you connect GitLab with your Google account). + +  + +1. The last step is to provide the cluster details. + 1. Give it a name, leave the environment scope as is, and choose the GCP project under which to create the cluster. + (Per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you.) + 1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) to create the cluster in. + 1. Enter the number of nodes you want it to have. + 1. Choose the [machine type](https://cloud.google.com/compute/docs/machine-types). + +  + +1. Click **Create Kubernetes cluster**. + +After a couple of minutes, the cluster is created. You can also see its +status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). + +The next step is to install some applications on your cluster that are needed +to take full advantage of Auto DevOps. + +## Install Ingress + +The GitLab Kubernetes integration comes with some +[pre-defined applications](../../index.md#installing-applications) +for you to install. + + + +For this guide, we need to install Ingress. Ingress provides load balancing, +SSL termination, and name-based virtual hosting, using NGINX behind +the scenes. Make sure to switch the toggle to the enabled position before installing. + +Both logging and blocking modes are available for WAF. While logging mode is useful for +auditing anomalous traffic, blocking mode ensures the traffic doesn't reach past Ingress. + + + +After Ingress is installed, wait a few seconds and copy the IP address that +is displayed in order to add in your base **Domain** at the top of the page. For +the purpose of this guide, we use the one suggested by GitLab. Once you have +filled in the domain, click **Save changes**. + + + +Prometheus should also be installed. It is an open-source monitoring and +alerting system that is used to supervise the deployed application. +Installing GitLab Runner is not required as we use the shared runners that +GitLab.com provides. + +## Enabling Auto DevOps (optional) + +Starting with GitLab 11.3, Auto DevOps is enabled by default. However, it is possible to disable +Auto DevOps at both the instance-level (for self-managed instances) and the group-level. +Follow these steps if Auto DevOps has been manually disabled: + +1. Navigate to **Settings > CI/CD > Auto DevOps**. +1. Select **Default to Auto DevOps pipeline**. +1. Select the [continuous deployment strategy](../../../../../topics/autodevops/index.md#deployment-strategy) + which automatically deploys the application to production once the pipeline + successfully runs on the `master` branch. +1. Click **Save changes**. + +  + +Once you complete all the above and save your changes, a new pipeline is +automatically created. To view the pipeline, go to **CI/CD > Pipelines**. + + + +The next section explains what each pipeline job does. + +## Deploying the application + +By now you should see the pipeline running, but what is it running exactly? + +To navigate inside the pipeline, click its status badge (its status should be "Running"). +The pipeline is split into a few stages, each running a couple of jobs. + + + +In the **build** stage, the application is built into a Docker image and then +uploaded to your project's [Container Registry](../../../../packages/container_registry/index.md) +([Auto Build](../../../../../topics/autodevops/stages.md#auto-build)). + +In the **test** stage, GitLab runs various checks on the application. + +The **production** stage is run after the tests and checks finish, and it automatically +deploys the application in Kubernetes ([Auto Deploy](../../../../../topics/autodevops/stages.md#auto-deploy)). + +The **production** stage creates Kubernetes objects +like a Deployment, Service, and Ingress resource. The +application is monitored by the WAF automatically. + +## Validating Ingress is running ModSecurity + +Now we can make sure that Ingress is running properly with ModSecurity and send +a request to ensure our application is responding correctly. You must connect to +your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install). + +1. After connecting to your cluster, check if the Ingress-NGINX controller is running and ModSecurity is enabled. + + This is done by running the following commands: + + ```shell + $ kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' + ingress-nginx-ingress-controller-55f9cf6584-dxljn 2/2 Running + + $ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /etc/nginx/nginx.conf | grep 'modsecurity on;' + modsecurity on; + ``` + +1. Verify the Rails application has been installed properly. + + ```shell + $ kubectl get ns + auto-devv-2-16730183-production Active + + $ kubectl get pods -n auto-devv-2-16730183-production + NAME READY STATUS RESTARTS + production-5778cfcfcd-nqjcm 1/1 Running 0 + production-postgres-6449f8cc98-r7xgg 1/1 Running 0 + ``` + +1. To make sure the Rails application is responding, send a request to it by running: + + ```shell + $ kubectl get ing -n auto-devv-2-16730183-production + NAME HOSTS PORTS + production-auto-deploy fjdiaz-auto-devv-2.34.68.60.207.nip.io,le-16730183.34.68.60.207.nip.io 80, 443 + + $ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" | grep 'Rails!' --after 2 --before 2 + <body> + <p>You're on Rails!</p> + </body> + ``` + +Now that we have confirmed our system is properly setup, we can go ahead and test +the WAF with OWASP CRS! + +## Testing out the OWASP Core Rule Set + +Now let's send a potentially malicious request, as if we were a scanner, +checking for vulnerabilities within our application and examine the ModSecurity logs: + +```shell +$ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" --header "User-Agent: absinthe" | grep 'Rails!' --after 2 --before 2 +<body> + <p>You're on Rails!</p> +</body> + +$ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /var/log/modsec/audit.log | grep 'absinthe' +{ + "message": "Found User-Agent associated with security scanner", + "details": { + "match": "Matched \"Operator `PmFromFile' with parameter `scanners-user-agents.data' against variable `REQUEST_HEADERS:user-agent' (Value: `absinthe' )", + "reference": "o0,8v84,8t:lowercase", + "ruleId": "913100", + "file": "/etc/nginx/owasp-modsecurity-crs/rules/REQUEST-913-SCANNER-DETECTION.conf", + "lineNumber": "33", + "data": "Matched Data: absinthe found within REQUEST_HEADERS:user-agent: absinthe", + "severity": "2", + "ver": "OWASP_CRS/3.2.0", + "rev": "", + "tags": ["application-multi", "language-multi", "platform-multi", "attack-reputation-scanner", "OWASP_CRS", "OWASP_CRS/AUTOMATION/SECURITY_SCANNER", "WASCTC/WASC-21", "OWASP_TOP_10/A7", "PCI/6.5.10"], + "maturity": "0", + "accuracy": "0" + } +} +``` + +You can see that ModSecurity logs the suspicious behavior. By sending a request +with the `User Agent: absinthe` header, which [absinthe](https://github.com/cameronhotchkies/Absinthe), +a tool for testing for SQL injections uses, we can detect that someone was +searching for vulnerabilities on our system. Detecting scanners is useful, because we +can learn if someone is trying to exploit our system. + +## Conclusion + +You can now see the benefits of a using a Web Application Firewall. +ModSecurity and the OWASP Core Rule Set, offer many more benefits. +You can explore them in more detail: + +- [Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/) +- [ModSecurity](https://www.modsecurity.org/) +- [OWASP Core Rule Set](https://github.com/coreruleset/coreruleset/) +- [AutoDevOps](../../../../../topics/autodevops/index.md) diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 332c1f35d89..8572ab850e4 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -103,7 +103,7 @@ the components outlined above and the pre-loaded demo runbook. Enter these values, maintaining the single quotes as follows: ```sql - PRIVATE_TOKEN = 'n671WNGecHugsdEDPsyo' + PRIVATE_TOKEN = '<your_access_token>' PROJECT_ID = '1234567' ``` diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md index fa80bd6423b..d734db6bac9 100644 --- a/doc/user/project/clusters/securing.md +++ b/doc/user/project/clusters/securing.md @@ -1,155 +1,8 @@ --- -stage: Protect -group: Container Security -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: 'protect/index.md' --- -# Securing your deployed applications +This document was moved to [another location](protect/index.md). -GitLab makes it easy to secure applications deployed in [connected Kubernetes clusters](index.md). -You can benefit from the protection of a [Web Application Firewall](../../../topics/web_application_firewall/quick_start_guide.md), -[Network Policies](../../../topics/autodevops/stages.md#network-policy), -and [Container Host Security](../../clusters/applications.md#install-falco-using-gitlab-cicd). - -This page contains full end-to-end steps and instructions to connect your cluster to GitLab and -install these features, whether or not your applications are deployed through GitLab CI/CD. If you -use [Auto DevOps](../../../topics/autodevops/index.md) -to build and deploy your application with GitLab, see the documentation for the respective -[GitLab Managed Applications](../../clusters/applications.md) -above. - -## Overview - -At a high level, the required steps include the following: - -- Connect the cluster to GitLab. -- Set up one or more runners. -- Set up a cluster management project. -- Install a Web Application Firewall, and/or Network Policies, and/or Container Host - Security. -- Install Prometheus to get statistics and metrics in the - [threat monitoring](../../application_security/threat_monitoring/) - dashboard. - -### Requirements - -Minimum requirements (depending on the GitLab Manage Application you want to install): - -- Your cluster is connected to GitLab (ModSecurity, Cilium, and Falco). -- At least one runner is installed (Cilium and Falco only). - -### Understanding how GitLab Managed Apps are installed - -NOTE: -These diagrams use the term _Kubernetes_ for simplicity. In practice, Sidekiq connects to a Helm -command runner pod in the cluster. - -You install GitLab Managed Apps from the GitLab web interface with a one-click setup process. GitLab -uses Sidekiq (a background processing service) to facilitate this. - -```mermaid - sequenceDiagram - autonumber - GitLab->>+Sidekiq: Install a GitLab Managed App - Sidekiq->>+Kubernetes: Helm install - Kubernetes-->>-Sidekiq: Installation complete - Sidekiq-->>-GitLab: Refresh UI -``` - -Although this installation method is easier because it's a point-and-click action in the user -interface, it's inflexible and harder to debug. If something goes wrong, you can't see the -deployment logs. The Web Application Firewall feature uses this installation method. - -However, the next generation of GitLab Managed Apps V2 ([CI/CD-based GitLab Managed Apps](https://gitlab.com/groups/gitlab-org/-/epics/2103)) -don't use Sidekiq to deploy. All the applications are deployed using a GitLab CI/CD pipeline and -therefore, by runners. - -```mermaid -sequenceDiagram - autonumber - GitLab->>+GitLab: Trigger pipeline - GitLab->>+Runner: Run deployment job - Runner->>+Kubernetes: Helm install - Kubernetes-->>-Runner: Installation is complete - Runner-->>-GitLab: Report job status and update pipeline -``` - -Debugging is easier because you have access to the raw logs of these jobs (the Helm Tiller output is -available as an artifact in case of failure), and the flexibility is much better. Since these -deployments are only triggered when a pipeline is running (most likely when there's a new commit in -the cluster management repository), every action has a paper trail and follows the classic merge -request workflow (approvals, merge, deploy). The Network Policy (Cilium) Managed App, and Container -Host Security (Falco) are deployed with this model. - -## Connect the cluster to GitLab - -To deploy GitLab Managed Apps to your cluster, you must first -[add your cluster](add_remove_clusters.md) -to GitLab. Then [install](../../clusters/applications.md#install-with-one-click) -the Web Application Firewall from the project or group Kubernetes page. - -Note that your project doesn't have to be hosted or deployed through GitLab. You can manage a -cluster independent of the applications that use the cluster. - -## Set up a runner - -To install CI/CD-based GitLab Managed Apps, a pipeline using a runner must be running in -GitLab. You can [install a runner](../../clusters/applications.md#gitlab-runner) -in the Kubernetes cluster added in the previous step, or use one of the shared runners provided by -GitLab if you're using GitLab.com. - -With your cluster connected to GitLab and a runner in place, you can proceed to the next -steps and start installing the Cilium and Falco GitLab Managed Apps to secure your applications -hosted on this cluster. - -## Create a Cluster Management Project - -A [Cluster Management Project](../../clusters/management_project.md) -is a GitLab project that contains a `.gitlab-ci.yml` file to deploy GitLab Managed Apps to your -cluster. This project runs the required charts with the Kubernetes -[`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) -privileges. - -The creation of this project starts like any other GitLab project. Use an empty -project and add a `gitlab-ci.yml` file at the root, containing this template: - -```yaml -include: - - template: Managed-Cluster-Applications.gitlab-ci.yml -``` - -To make this project a Cluster Management Project, follow these -[instructions](../../clusters/management_project.md#selecting-a-cluster-management-project). -This project can be designated as such even if your application isn't hosted on GitLab. In this -case, create a new empty project where you can select your newly created Cluster Management Project. - -## Install GitLab Container Network Policy - -GitLab Container Network Policy is based on [Cilium](https://cilium.io/). To -install the Cilium GitLab Managed App, add a -`.gitlab/managed-apps/config.yaml` file to your Cluster Management project: - -```yaml -# possible values are gke, eks or you can leave it blank -clusterType: gke - -cilium: - installed: true -``` - -Your application doesn't have to be managed or deployed by GitLab to leverage this feature. -[Read more](../../clusters/applications.md#install-cilium-using-gitlab-cicd) -about configuring Container Network Policy. - -## Install GitLab Container Host Security - -Similarly, you can install Container Host Security, based on -[Falco](https://falco.org/), in your `.gitlab/managed-apps/config.yaml`: - -```yaml -falco: - installed: true -``` - -[Read more](../../clusters/applications.md#install-falco-using-gitlab-cicd) -about configuring Container Host Security. +<!-- This redirect file can be deleted after <2021-04-01>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index fcbf85121b2..043c5e4ca79 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -560,7 +560,6 @@ Or: By default, a GitLab serverless deployment is served over `http`. To serve over `https`, you must manually obtain and install TLS certificates. -12345678901234567890123456789012345678901234567890123456789012345678901234567890 The simplest way to accomplish this is to use Certbot to [manually obtain Let's Encrypt certificates](https://knative.dev/docs/serving/using-a-tls-cert/#using-certbot-to-manually-obtain-let-s-encrypt-certificates). Certbot is a free, open source software tool for automatically using Let’s Encrypt diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index d0e89400d88..63ea84e42c9 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -225,6 +225,52 @@ the rules for "Groups" and "Documentation" sections:  +#### Optional Code Owners Sections **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.8 behind a feature flag, enabled by default. + +When you want to make a certain section optional, you can do so by adding a code owners section prepended with the caret `^` character. Approvals from owners listed in the section will **not** be required. For example: + +```plaintext +[Documentation] +*.md @root + +[Ruby] +*.rb @root + +^[Go] +*.go @root +``` + +The optional code owners section will be displayed in merge requests under the **Approval Rules** area: + + + +If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails. + +For example, the code owners of the "Documentation" section below will still be required to approve merge requests: + +```plaintext +[Documentation] +*.md @root + +[Ruby] +*.rb @root + +^[Go] +*.go @root + +^[Documentation] +*.txt @root +``` + +Optional sections in the code owners file are currently treated as optional only +when changes are submitted via merge requests. If a change is submitted directly +to the protected branch, approval from code owners will still be required, even if the +section is marked as optional. We plan to change this in a +[future release](https://gitlab.com/gitlab-org/gitlab/-/issues/297638), +where direct pushes to the protected branch will be allowed for sections marked as optional. + ## Example `CODEOWNERS` file ```plaintext diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 33bec99767a..831a8803622 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -5,9 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy Boards **(PREMIUM)** +# Deploy Boards **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. +> - [Moved](<https://gitlab.com/gitlab-org/gitlab/-/issues/212320>) to GitLab Core in 13.8. GitLab Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status @@ -53,8 +54,8 @@ specific environment, there are a lot of use cases. To name a few: - You want to promote what's running in staging, to production. You go to the environments list, verify that what's running in staging is what you think is running, then click on the [manual action](../../ci/yaml/README.md#whenmanual) to deploy to production. -- You trigger a deploy, and you've got lots of containers to upgrade so you know - it'll take a while (you've also throttled your deploy to only take down X +- You trigger a deploy, and you have many containers to upgrade so you know + this takes a while (you've also throttled your deploy to only take down X containers at a time). But you need to tell someone when it's deployed, so you go to the environments list, look at the production environment to see what the progress is in real-time as each pod is rolled. @@ -75,8 +76,8 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ 1. Have a Kubernetes cluster up and running. NOTE: - If you are using OpenShift, ensure that you're using the `Deployment` resource - instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards won't render + If you're using OpenShift, ensure that you're using the `Deployment` resource + instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards don't render correctly. For more information, read the [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/-/issues/4584). @@ -84,7 +85,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ 1. [Configure GitLab Runner](../../ci/runners/README.md) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. 1. Configure the [Kubernetes integration](clusters/index.md) in your project for the - cluster. The Kubernetes namespace is of particular note as you will need it + cluster. The Kubernetes namespace is of particular note as you need it for your deployment scripts (exposed by the `KUBE_NAMESPACE` environment variable). 1. Ensure Kubernetes annotations of `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` and `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` are applied to the @@ -94,7 +95,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ than one. These resources should be contained in the namespace defined in the Kubernetes service setting. You can use an [Autodeploy](../../topics/autodevops/stages.md#auto-deploy) `.gitlab-ci.yml` template which has predefined stages and commands to use, and automatically - applies the annotations. Each project will need to have a unique namespace in + applies the annotations. Each project must have a unique namespace in Kubernetes as well. The image below demonstrates how this is shown inside Kubernetes. @@ -105,7 +106,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ re-deploy your application. If you are using Auto DevOps, this will be done automatically and no action is necessary. - If you are using GCP to manage clusters, you can see the deployment details in GCP itself by going to **Workloads > deployment name > Details**: + If you use GCP to manage clusters, you can see the deployment details in GCP itself by navigating to **Workloads > deployment name > Details**:  @@ -141,7 +142,7 @@ spec: app.gitlab.com/env: ${CI_ENVIRONMENT_SLUG} ``` -The annotations will be applied to the deployments, replica sets, and pods. By changing the number of replicas, like `kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}`, you can follow the instances' pods from the board. +The annotations are applied to the deployments, replica sets, and pods. By changing the number of replicas, like `kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}`, you can follow the instances' pods from the board. NOTE: The YAML file is static. If you apply it using `kubectl apply`, you must diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 39b790544c1..93ed1030e1f 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -92,7 +92,7 @@ There are three lists of Project Deploy Keys:  -After you add a key, it will be enabled for this project by default, and it'll appear +After you add a key, it's enabled for this project by default and it appears in the **Enabled deploy keys** tab. In the **Privately accessible deploy keys** tab, you can enable a private key which @@ -111,7 +111,7 @@ and `read-write` access. NOTE: If you have enabled a privately or publicly accessible or deploy key for your project, and if you then update the access level for this key from `read-only` to -`read-write`, the change will be only for the **current project**. +`read-write`, the change is only for the **current project**. ### Public deploy keys @@ -131,7 +131,7 @@ Instance administrators can add public deploy keys:  -After adding a key, it will be available to any shared systems. Project maintainers +After adding a key, it's available to any shared systems. Project maintainers or higher can [authorize a public deploy key](#project-deploy-keys) to start using it with the project. NOTE: @@ -155,8 +155,8 @@ until a project maintainer chooses to make use of it. ### Deploy Key cannot push to a protected branch -If the owner of this deploy key does not have access to a [protected -branch](../protected_branches.md), then this deploy key won't have access to +If the owner of this deploy key doesn't have access to a [protected +branch](../protected_branches.md), then this deploy key doesn't have access to the branch either. In addition to this, choosing the **No one** value in [the "Allowed to push" section](../protected_branches.md#configuring-protected-branches) means that no users **and** no services using deploy keys can push to that selected branch. diff --git a/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png b/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png Binary files differindex 83f59b8f6f0..4ab6a45aee1 100644 --- a/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png +++ b/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index ac19c44c58a..5a62730d989 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -36,7 +36,7 @@ project. Alternatively, you can also create [group-scoped deploy tokens](#group- 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). 1. Select **Create deploy token**. 1. Save the deploy token somewhere safe. After you leave or refresh - the page, **you won't be able to access it again**. + the page, **you can't access it again**.  @@ -89,7 +89,7 @@ Replace `<username>` and `<deploy_token>` with the proper values. ### Read Container Registry images -To read the container registry images, you'll need to: +To read the container registry images, you must: 1. Create a Deploy Token with `read_registry` as a scope. 1. Take note of your `username` and `token`. @@ -106,7 +106,7 @@ pull images from your Container Registry. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10. -To push the container registry images, you'll need to: +To push the container registry images, you must: 1. Create a Deploy Token with `write_registry` as a scope. 1. Take note of your `username` and `token`. @@ -123,7 +123,7 @@ push images to your Container Registry. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. -To pull packages in the GitLab package registry, you'll need to: +To pull packages in the GitLab package registry, you must: 1. Create a Deploy Token with `read_package_registry` as a scope. 1. Take note of your `username` and `token`. @@ -134,7 +134,7 @@ To pull packages in the GitLab package registry, you'll need to: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. -To upload packages in the GitLab package registry, you'll need to: +To upload packages in the GitLab package registry, you must: 1. Create a Deploy Token with `write_package_registry` as a scope. 1. Take note of your `username` and `token`. @@ -160,7 +160,7 @@ To use a group deploy token: 1. Use it the same way you use a project deploy token when [cloning a repository](#git-clone-a-repository). -The scopes applied to a group deploy token (such as `read_repository`) will +The scopes applied to a group deploy token (such as `read_repository`) apply consistently when cloning the repository of related projects. ### GitLab Deploy Token @@ -168,7 +168,7 @@ apply consistently when cloning the repository of related projects. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18414) in GitLab 10.8. There's a special case when it comes to Deploy Tokens. If a user creates one -named `gitlab-deploy-token`, the username and token of the Deploy Token will be +named `gitlab-deploy-token`, the username and token of the Deploy Token is automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD`, respectively. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index db2631f9596..3108bdda7a0 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -108,7 +108,7 @@ you should be fine.  After you add the description, hit **Save changes** for the settings to take -effect. Now, every time a new merge request or issue is created, it is +effect. Now, every time a new merge request or issue is created, it is pre-filled with the text you entered in the template(s). ## Description template example diff --git a/doc/user/project/img/canary_weight.png b/doc/user/project/img/canary_weight.png Binary files differindex e6544358c15..fe17c62bdea 100644 --- a/doc/user/project/img/canary_weight.png +++ b/doc/user/project/img/canary_weight.png diff --git a/doc/user/project/img/description_templates_issue_settings.png b/doc/user/project/img/description_templates_issue_settings.png Binary files differindex 657b6ae1269..7f354f7c288 100644 --- a/doc/user/project/img/description_templates_issue_settings.png +++ b/doc/user/project/img/description_templates_issue_settings.png diff --git a/doc/user/project/img/optional_code_owners_sections_v13_8.png b/doc/user/project/img/optional_code_owners_sections_v13_8.png Binary files differnew file mode 100644 index 00000000000..7a5a2fab6e3 --- /dev/null +++ b/doc/user/project/img/optional_code_owners_sections_v13_8.png diff --git a/doc/user/project/img/protected_branches_deploy_keys_v13_5.png b/doc/user/project/img/protected_branches_deploy_keys_v13_5.png Binary files differindex 6eda7a671b2..ccd23dbe160 100644 --- a/doc/user/project/img/protected_branches_deploy_keys_v13_5.png +++ b/doc/user/project/img/protected_branches_deploy_keys_v13_5.png diff --git a/doc/user/project/img/service_desk_custom_email_address_v13_0.png b/doc/user/project/img/service_desk_custom_email_address_v13_0.png Binary files differdeleted file mode 100644 index 3789e039904..00000000000 --- a/doc/user/project/img/service_desk_custom_email_address_v13_0.png +++ /dev/null diff --git a/doc/user/project/img/service_desk_enabled.png b/doc/user/project/img/service_desk_enabled.png Binary files differdeleted file mode 100644 index 33d51227e5f..00000000000 --- a/doc/user/project/img/service_desk_enabled.png +++ /dev/null diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 8b6d86b14c9..c135b1be54a 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -63,7 +63,7 @@ must meet one of the following conditions prior to the import: - Have previously logged in to a GitLab account using the GitHub icon. - Have a GitHub account with a publicly visible [primary email address](https://docs.github.com/en/free-pro-team@latest/rest/reference/users#get-a-user) - on their profile that matches their GitLab account's email address. + on their profile that matches their GitLab account's primary or secondary email address. If a user referenced in the project is not found in the GitLab database, the project creator (typically the user that initiated the import process) is set as the author/assignee, but a note on the issue mentioning the original diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 8344baebd82..ccf4b6cb303 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -37,7 +37,7 @@ integration settings. Keep in mind that you need to have the appropriate permissions for your Slack team in order to be able to install a new application, read more in Slack's -docs on [Adding an app to your workspace](https://slack.com/help/articles/202035138-Add-an-app-to-your-workspace). +docs on [Adding an app to your workspace](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace). To enable the GitLab service for your Slack team: diff --git a/doc/user/project/integrations/img/webhooks_ssl.png b/doc/user/project/integrations/img/webhooks_ssl.png Binary files differdeleted file mode 100644 index e5777a2e99b..00000000000 --- a/doc/user/project/integrations/img/webhooks_ssl.png +++ /dev/null diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index f15a5ee4429..3c91fd3549f 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -30,6 +30,6 @@ The following Jira integrations allow different types of cross-referencing betwe | Mention of Jira issue ID in GitLab issue/MR is reflected in the Jira issue | Yes, as a Jira comment with the GitLab issue/MR title and a link back to it. Its first mention also adds the GitLab page to the Jira issue under “Web links”. | Yes, in the issue’s Development panel | | Mention of Jira issue ID in GitLab commit message is reflected in the issue | Yes. The entire commit message is added to the Jira issue as a comment and under “Web links”, each with a link back to the commit in GitLab. | Yes, in the issue’s Development panel and optionally with a custom comment on the Jira issue using Jira Smart Commits. | | Mention of Jira issue ID in GitLab branch names is reflected in Jira issue | No | Yes, in the issue’s Development panel | -| Record Jira time tracking info against an issue | No | Yes. Time can be specified via Jira Smart Commits. | +| Record Jira time tracking information against an issue | No | Yes. Time can be specified via Jira Smart Commits. | | Transition or close a Jira issue with a Git commit or merge request | Yes. Only a single transition type, typically configured to close the issue by setting it to Done. | Yes. Transition to any state using Jira Smart Commits. | | Display a list of Jira issues | Yes **(PREMIUM)** | No | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 9d7960790ff..959c4cc623b 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -199,7 +199,6 @@ to integrate with. ### Precedence with multiple Prometheus configurations -12345678901234567890123456789012345678901234567890123456789012345678901234567890 Although you can enable both a [manual configuration](#manual-configuration-of-prometheus) and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, you can use only one: diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index d8b51e8b777..47a44e53b47 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Webhooks -Project webhooks allow you to trigger a URL if for example new code is pushed or +Project webhooks allow you to trigger a percent-encoded URL if, for example, new code is pushed or a new issue is created. You can configure webhooks to listen for specific events like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. @@ -28,32 +28,15 @@ notify bug tracking systems. Webhooks can be used to update an external issue tracker, trigger CI jobs, update a backup mirror, or even deploy to your production server. -They are available **per project** for GitLab Community Edition, -and **per project and per group** for **GitLab Enterprise Edition**. -Navigate to the webhooks page at your project's **Settings > Webhooks**. +Webhooks are available: + +- Per project, at a project's **Settings > Webhooks** menu. **(CORE)** +- Additionally per group, at a group's **Settings > Webhooks** menu. **(PREMIUM)** NOTE: On GitLab.com, the [maximum number of webhooks and their size](../../../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. -## Version history - -Starting from GitLab 8.5: - -- the `repository` key is deprecated in favor of the `project` key -- the `project.ssh_url` key is deprecated in favor of the `project.git_ssh_url` key -- the `project.http_url` key is deprecated in favor of the `project.git_http_url` key - -Starting from GitLab 11.1, the logs of webhooks are automatically removed after -one month. - -Starting from GitLab 11.2: - -- The `description` field for issues, merge requests, comments, and wiki pages - is rewritten so that simple Markdown image references (like - ``) have their target URL changed to an absolute URL. See - [image URL rewriting](#image-url-rewriting) for more details. - ## Possible uses for webhooks - You can set up a webhook in GitLab to send a notification to @@ -91,8 +74,6 @@ be self-signed. You can turn this off in the webhook settings in your GitLab projects. - - ## Branch filtering > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/20338) in GitLab 11.3. @@ -115,6 +96,10 @@ attribute only contains the first 20 for performance reasons. Loading detailed commit data is expensive. Note that despite only 20 commits being present in the `commits` attribute, the `total_commits_count` attribute contains the actual total. +NOTE: +If a branch creation push event is generated without new commits being introduced, the +`commits` attribute in the payload is empty. + Also, if a single push includes changes for more than three (by default, depending on [`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) branches, this hook isn't executed. @@ -276,6 +261,7 @@ X-Gitlab-Event: Issue Hook "object_kind": "issue", "event_type": "issue", "user": { + "id": 1, "name": "Administrator", "username": "root", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", @@ -439,9 +425,11 @@ X-Gitlab-Event: Note Hook { "object_kind": "note", "user": { + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" }, "project_id": 5, "project":{ @@ -519,9 +507,11 @@ X-Gitlab-Event: Note Hook { "object_kind": "note", "user": { + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" }, "project_id": 5, "project":{ @@ -646,9 +636,11 @@ X-Gitlab-Event: Note Hook { "object_kind": "note", "user": { + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" }, "project_id": 5, "project":{ @@ -752,9 +744,11 @@ X-Gitlab-Event: Note Hook { "object_kind": "note", "user": { + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" }, "project_id": 5, "project":{ @@ -828,9 +822,11 @@ X-Gitlab-Event: Merge Request Hook { "object_kind": "merge_request", "user": { + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" }, "project": { "id": 1, @@ -989,9 +985,11 @@ X-Gitlab-Event: Wiki Page Hook { "object_kind": "wiki_page", "user": { + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "email": "admin@example.com" }, "project": { "id": 1, @@ -1080,6 +1078,7 @@ X-Gitlab-Event: Pipeline Hook "url": "http://192.168.64.1:3005/gitlab-org/gitlab-test/merge_requests/1" }, "user":{ + "id": 1, "name": "Administrator", "username": "root", "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", @@ -1121,9 +1120,11 @@ X-Gitlab-Event: Pipeline Hook "manual": true, "allow_failure": false, "user":{ + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" }, "runner": null, "artifacts_file":{ @@ -1143,9 +1144,11 @@ X-Gitlab-Event: Pipeline Hook "manual": false, "allow_failure": false, "user":{ + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" }, "runner": { "id":380987, @@ -1170,9 +1173,11 @@ X-Gitlab-Event: Pipeline Hook "manual": false, "allow_failure": false, "user":{ + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" }, "runner": { "id":380987, @@ -1197,9 +1202,11 @@ X-Gitlab-Event: Pipeline Hook "manual": false, "allow_failure": false, "user":{ + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" }, "runner": { "id":380987, @@ -1224,9 +1231,11 @@ X-Gitlab-Event: Pipeline Hook "manual": false, "allow_failure": false, "user":{ + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" }, "runner": null, "artifacts_file":{ @@ -1273,7 +1282,8 @@ X-Gitlab-Event: Job Hook "id": 3, "name": "User", "email": "user@gitlab.com", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" }, "commit": { "id": 2366, @@ -1349,6 +1359,7 @@ X-Gitlab-Event: Deployment Hook }, "short_sha": "279484c0", "user": { + "id": 1, "name": "Administrator", "username": "root", "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", @@ -1362,11 +1373,18 @@ X-Gitlab-Event: Deployment Hook Note that `deployable_id` is the ID of the CI job. -### Member events +### Group member events **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. -Triggered when a user is added as a group member. +Member events are triggered when: + +- A user is added as a group member +- The access level of a user has changed +- The expiration date for user access has been updated +- A user has been removed from the group + +#### Add member to group **Request Header**: @@ -1394,6 +1412,62 @@ X-Gitlab-Event: Member Hook } ``` +#### Update member access level or expiration date + +**Request Header**: + +```plaintext +X-Gitlab-Event: Member Hook +``` + +**Request Body**: + +```json +{ + "created_at": "2020-12-11T04:57:22Z", + "updated_at": "2020-12-12T08:48:19Z", + "group_name": "webhook-test", + "group_path": "webhook-test", + "group_id": 100, + "user_username": "test_user", + "user_name": "Test User", + "user_email": "testuser@webhooktest.com", + "user_id": 64, + "group_access": "Developer", + "group_plan": null, + "expires_at": "2020-12-20T00:00:00Z", + "event_name": "user_update_for_group" +} +``` + +#### Remove member from group + +**Request Header**: + +```plaintext +X-Gitlab-Event: Member Hook +``` + +**Request Body**: + +```json +{ + "created_at": "2020-12-11T04:57:22Z", + "updated_at": "2020-12-12T08:52:34Z", + "group_name": "webhook-test", + "group_path": "webhook-test", + "group_id": 100, + "user_username": "test_user", + "user_name": "Test User", + "user_email": "testuser@webhooktest.com", + "user_id": 64, + "group_access": "Guest", + "group_plan": null, + "expires_at": "2020-12-14T00:00:00Z", + "event_name": "user_remove_from_group" +} +``` + ### Feature Flag events Triggered when a feature flag is turned on or off. @@ -1428,6 +1502,7 @@ X-Gitlab-Event: Feature Flag Hook "http_url":"http://example.com/gitlabhq/gitlab-test.git" }, "user": { + "id": 1, "name": "Administrator", "username": "root", "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", @@ -1554,7 +1629,7 @@ Markdown features, like link labels. ## Testing webhooks You can trigger the webhook manually. Sample data from the project is used. -> For example: for triggering `Push Events` your project should have at least one commit. +For example, for triggering `Push Events` your project should have at least one commit.  diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index e0f66013454..7119970fca0 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issue Boards +# Issue Boards **(CORE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5554) in [GitLab 8.11](https://about.gitlab.com/releases/2016/08/22/gitlab-8-11-released/#issue-board). @@ -233,17 +233,18 @@ advanced functionality is present in [higher tiers only](https://about.gitlab.co ### Configurable issue boards **(STARTER)** -> [Introduced](https://about.gitlab.com/releases/2017/11/22/gitlab-10-2-released/#issue-boards-configuration) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. +> - [Introduced](https://about.gitlab.com/releases/2017/11/22/gitlab-10-2-released/#issue-boards-configuration) in GitLab 10.2. +> - Setting current iteration as scope [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196804) in GitLab 13.8. -An issue board can be associated with a GitLab [Milestone](milestones/index.md#milestones), -[Labels](labels.md), Assignee and Weight +An issue board can be associated with a [milestone](milestones/index.md#milestones), +[labels](labels.md), assignee, weight, and current [iteration](../group/iterations/index.md), which automatically filter the board issues accordingly. This allows you to create unique boards according to your team's need.  You can define the scope of your board when creating it or by clicking the **Edit board** button. -After a milestone, assignee or weight is assigned to an issue board, you can no longer +After a milestone, iteration, assignee, or weight is assigned to an issue board, you can no longer filter through these in the search bar. In order to do that, you need to remove the desired scope (for example, milestone, assignee, or weight) from the issue board. @@ -320,7 +321,8 @@ As in other list types, click the trash icon to remove a list. ### Group issues in swimlanes **(PREMIUM)** -> Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> - Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> - Editing issue titles in the issue sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232745) in GitLab 13.8. With swimlanes you can visualize issues grouped by epic. Your issue board keeps all the other features, but with a different visual organization of issues. @@ -336,6 +338,19 @@ To group issues by epic in an issue board:  +To edit an issue without leaving this view, select the issue card (not its title), and a sidebar +appears on the right. There you can see and edit the issue's: + +- Title +- Assignees +- Epic **PREMIUM** +- Milestone +- Time tracking value (view only) +- Due date +- Labels +- Weight +- Notifications setting + You can also [drag issues](#drag-issues-between-lists) to change their position and epic assignment: - To reorder an issue, drag it to the new position within a list. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 02cb0313a74..d4fbc4fb10b 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -29,8 +29,8 @@ confidential checkbox and hit **Save changes**. There are two ways to change an issue's confidentiality. -The first way is to edit the issue and mark/unmark the confidential checkbox. -Once you save the issue, it will change the confidentiality of the issue. +The first way is to edit the issue and toggle the confidentiality checkbox. +After you save the issue, the confidentiality of the issue is updated. The second way is to locate the Confidentiality section in the sidebar and click **Edit**. A popup should appear and give you the option to turn on or turn off confidentiality. @@ -46,20 +46,19 @@ system note in the issue's comments. ## Indications of a confidential issue -NOTE: -If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), -you won't be able to see the confidential issues at all. - There are a few things that visually separate a confidential issue from a regular one. In the issues index page view, you can see the eye-slash icon next to the issues that are marked as confidential.  +If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), +you cannot see confidential issues at all. + --- Likewise, while inside the issue, you can see the eye-slash icon right next to -the issue number, but there is also an indicator in the comment area that the +the issue number. There is also an indicator in the comment area that the issue you are commenting on is confidential.  @@ -83,7 +82,7 @@ project's search results respectively. | Maintainer access | Guest access | | :-----------: | :----------: | -|  |  | +|  |  | ## Merge Requests for Confidential Issues @@ -93,24 +92,24 @@ To help prevent confidential information being leaked from a public project in the process of resolving a confidential issue, confidential issues can be resolved by creating a merge request from a private fork. -The merge request created will target the default branch of the private fork, +The created merge request targets the default branch of the private fork, not the default branch of the public upstream project. This prevents the merge request, branch, and commits entering the public repository, and revealing -confidential information prematurely. When the confidential commits are ready -to be made public, this can be done by opening a merge request from the private -fork to the public upstream project. +confidential information prematurely. To make a confidential commit public, +open a merge request from the private fork to the public upstream project. -NOTE: -If you create a long-lived private fork in the same group or in a sub-group of -the original upstream, all the users with Developer membership to the public -project will also have the same permissions in the private project. This way, -all the Developers, who have access to view confidential issues, will have a -streamlined workflow for fixing them. +Permissions are inherited from parent groups. Developers have the same permissions +for private forks created in the same group or in a sub-group of the original +Permissions are inherited from parent groups. When private forks are created +in the same group or sub-group as the original upstream repository, users +receive the same permissions in both projects. This inheritance ensures +Developer users have the needed permissions to both view confidential issues and +resolve them. ### How it works On a confidential issue, a **Create confidential merge request** button is -available. Clicking on it will open a dropdown where you can choose to +available. Clicking on it opens a dropdown where you can choose to **Create confidential merge request and branch** or **Create branch**: | Create confidential merge request | Create branch | @@ -121,12 +120,12 @@ The **Project** dropdown includes the list of private forks the user is a member of as at least a Developer and merge requests are enabled. Whenever the **Branch name** and **Source (branch or tag)** fields change, the -availability of the target or source branch will be checked. Both branches should -be available in the private fork selected. +availability of the target and source branch are checked. Both branches should +be available in the selected private fork. -By clicking the **Create confidential merge request** button, GitLab will create +By clicking the **Create confidential merge request** button, GitLab creates the branch and merge request in the private fork. When you choose -**Create branch**, GitLab will only create the branch. +**Create branch**, GitLab creates only the branch. -Once the branch is created in the private fork, developers can now push code to +After the branch is created in the private fork, developers can push code to that branch to fix the confidential issue. diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index b5d3b71e679..250fa618dd8 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -31,10 +31,9 @@ git commit -m "this is my commit message. Related to https://gitlab.com/<usernam Of course, you can replace `gitlab.com` with the URL of your own GitLab instance. -NOTE: -Linking your first commit to your issue is going to be relevant +Linking your first commit to your issue is relevant for tracking your process with [GitLab Value Stream Analytics](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). -It will measure the time taken for planning the implementation of that issue, +It measures the time taken for planning the implementation of that issue, which is the time between creating an issue and making the first commit. ## From Related Issues @@ -45,7 +44,7 @@ issues regarding the same topic. You do that as explained above, when [mentioning an issue from a commit message](#from-commit-messages). -When mentioning issue `#111` in issue `#222`, issue `#111` will also display a notification +When mentioning issue `#111` in issue `#222`, issue `#111` also displays a notification in its tracker. That is, you only need to mention the relationship once for it to display in both issues. The same is valid when mentioning issues in [merge requests](#from-merge-requests). @@ -56,8 +55,8 @@ display in both issues. The same is valid when mentioning issues in [merge reque Mentioning issues in merge request comments works exactly the same way as they do for [related issues](#from-related-issues). -When you mention an issue in a merge request description, it will simply -[link the issue and merge request together](#from-related-issues). Additionally, +When you mention an issue in a merge request description, it +[links the issue and merge request together](#from-related-issues). Additionally, you can also [set an issue to close automatically](managing_issues.md#closing-issues-automatically) as soon as the merge request is merged. diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 023a8ee57bc..e7cd1377603 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -53,7 +53,7 @@ Exported issues are always sorted by `Issue ID`. > > **Weight** and **Locked** columns were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5300) in GitLab Starter 10.8. -Data wis encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: +Data is encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: | Column | Description | |---------|-------------| diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 63cd784333a..34e9340067c 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -11,14 +11,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. Due dates can be used in issues to keep track of deadlines and make sure features are -shipped on time. Users must have at least [Reporter permissions](../../permissions.md) -to be able to edit them, but they can be seen by everybody with permission to view -the issue. +shipped on time. Users need at least [Reporter permissions](../../permissions.md) +to be able to edit the due date. All users with permission to view +the issue can view the due date. ## Setting a due date -When creating or editing an issue, you can click in the **due date** field and a calendar -will appear to help you choose the date you want. To remove the date, select the date +When creating an issue, select the **Due date** field to make a calendar +appear for choosing the date. To remove the date, select the date text and delete it. The date is related to the server's timezone, not the timezone of the user setting the due date. @@ -37,18 +37,17 @@ The last way to set a due date is by using [quick actions](../quick_actions.md), ## Making use of due dates -Issues that have a due date can be easily seen in the issue tracker, -displaying a date next to them. Issues where the date is overdue will have -the icon and the date colored red. You can sort issues by those that are -`Due soon` or `Due later` from the dropdown menu on the right. - - +You can see issues with their due dates in the [issues list](index.md#issues-list). +Overdue issues have their icon and date colored red. +To sort issues by their due dates, select **Due date** from the dropdown menu on the right. +Issues are then sorted from the earliest due date to the latest. +To display isses with the latest due dates at the top, select **Sort direction** (**{sort-lowest}**). Due dates also appear in your [to-do list](../../todos.md).  -The day before an open issue is due, an email will be sent to all participants +The day before an open issue is due, an email is sent to all participants of the issue. Like the due date, the "day before the due date" is determined by the server's timezone. diff --git a/doc/user/project/issues/img/due_dates_issues_index_page.png b/doc/user/project/issues/img/due_dates_issues_index_page.png Binary files differdeleted file mode 100644 index 94679436b32..00000000000 --- a/doc/user/project/issues/img/due_dates_issues_index_page.png +++ /dev/null diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 05e7eb3021a..74311eefd83 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -22,8 +22,8 @@ their implementation between: They can also be used for a variety of other purposes, customized to your needs and workflow. -Issues are always associated with a specific project, but if you have multiple projects in a group, -you can also view all the issues collectively at the group level. +Issues are always associated with a specific project. If you have multiple projects in a group, +you can view all of the issues collectively at the group level. **Common use cases include:** @@ -91,9 +91,13 @@ must be set. ## Viewing and managing issues -While you can view and manage the full details of an issue on the [issue page](#issue-page), -you can also work with multiple issues at a time using the [Issues List](#issues-list), -[Issue Boards](#issue-boards), Issue references, and [Epics](#epics). **(PREMIUM)** +While you can view and manage details of an issue on the [issue page](#issue-page), +you can also work with multiple issues at a time using: + +- [Issues List](#issues-list). +- [Issue Boards](#issue-boards). +- Issue references. +- [Epics](#epics) **(PREMIUM)**. Key actions for issues include: @@ -117,14 +121,17 @@ and modify them if you have the necessary [permissions](../../permissions.md). Assignees in the sidebar are updated in real time. This feature is **disabled by default**. To enable, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). -### Issues list +### Issues List + + + +On the Issues List, you can: - +- View all issues in a project when opening the Issues List from a project context. +- View all issues in a groups's projects when opening the Issues List from a group context. -On the Issues List, you can view all issues in the current project, or from multiple -projects when opening the Issues List from the higher-level group context. Filter the -issue list with a [search query](../../search/index.md#filtering-issue-and-merge-request-lists), -including specific metadata, such as label(s), assignees(s), status, and more. From this +You can filter the Issues List with a [search query](../../search/index.md#filtering-issue-and-merge-request-lists), +including specific metadata, such as labels, assignees, status, and more. From this view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues. For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page @@ -140,21 +147,21 @@ You can sort a list of issues in several ways, for example by issue creation dat labels or their assignees**(PREMIUM)**. They offer the flexibility to manage issues using highly customizable workflows. -You can reorder issues within a column. If you drag an issue card to another column, its -associated label or assignee will change to match that of the new column. The entire +You can reorder issues in the column. If you drag an issue card to another column, its +associated label or assignee is changed to match that of the new column. The entire board can also be filtered to only include issues from a certain milestone or an overarching label. ### Design Management With [Design Management](design_management.md), you can upload design -assets to issues and view them all together to easily share and -collaborate with your team. +assets to issues and view them all together for sharing and +collaboration with your team. ### Epics **(PREMIUM)** [Epics](../../group/epics/index.md) let you manage your portfolio of projects more -efficiently and with less effort by tracking groups of issues that share a theme, across +efficiently and with less effort. Epics track groups of issues that share a theme, across projects and milestones. ### Related issues @@ -179,10 +186,10 @@ message in the Activity stream about the reference, with a link to the other iss To prevent duplication of issues for the same topic, GitLab searches for similar issues when new issues are being created. -When typing in the title in the **New Issue** page, GitLab searches titles and descriptions -across all issues the user has access to in the current project. Up to five similar issues, -sorted by most recently updated, are displayed below the title box. Note that this feature -requires [GraphQL](../../../api/graphql/index.md) to be enabled. +As you type in the title field of the **New Issue** page, GitLab searches titles and descriptions +across all issues to in the current project. Only issues you have access to are returned. +Up to five similar issues, sorted by most recently updated, are displayed below the title box. +[GraphQL](../../../api/graphql/index.md) must be enabled to use this feature.  @@ -193,8 +200,8 @@ requires [GraphQL](../../../api/graphql/index.md) to be enabled. > - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. -To help you track the status of your issues, you can assign a status to each issue to flag work -that's progressing as planned or needs attention to keep on schedule: +To help you track issue statuses, you can assign a status to each issue. +This marks issues as progressing as planned or needs attention to keep on schedule: - **On track** (green) - **Needs attention** (amber) diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 2520a562f1e..4c8630581f5 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -35,6 +35,7 @@ The numbers in the image correspond to the following features: - **12.** [Participants](#participants) - **13.** [Notifications](#notifications) - **14.** [Reference](#reference) +- [Issue email](#email) - **15.** [Edit](#edit) - **16.** [Description](#description) - **17.** [Mentions](#mentions) @@ -174,6 +175,13 @@ for the issue. Notifications are automatically enabled after you participate in `foo/bar#xxx`, where `foo` is the `username` or `groupname`, `bar` is the `project-name`, and `xxx` is the issue number. +### Email + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18816) in GitLab 13.8. + +Guest users can see a button in the right sidebar to copy the email address for the issue. +Sending an email to this address creates a comment containing the email body. + ### Edit Clicking this icon opens the issue for editing. All the fields which diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 03060ca720c..ef860df054e 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -19,16 +19,16 @@ Key actions for issues include: ## Create a new issue -When you create a new issue, you'll be prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), +When you create a new issue, you are prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), as illustrated below. If you know the values you want to assign to an issue, you can use the -[Quick actions](../quick_actions.md) feature to input values, instead of selecting them from lists. +[Quick actions](../quick_actions.md) feature to input values. While creating an issue, you can associate it to an existing epic from current group by selecting it using **Epic** dropdown. ### Accessing the New Issue form -There are many ways to get to the New Issue form from within a project: +There are many ways to get to the New Issue form from a project's page: - Navigate to your **Project's Dashboard** > **Issues** > **New Issue**: @@ -75,9 +75,8 @@ using the dropdown button at the top-right of the page.  -We'll keep track of the project you selected most recently, and use it as the default -for your next visit. This should save you a lot of time and clicks, if you mostly -create issues for the same project. +The project you selected most recently becomes the default for your next visit. +This should save you a lot of time and clicks, if you mostly create issues for the same project.  @@ -90,22 +89,22 @@ the appropriate project and followed up from there. ### New issue via email A link to **Email a new issue to this project** is displayed at the bottom of a project's -**Issues List** page, if your GitLab instance has [incoming email](../../../administration/incoming_email.md) -configured. +**Issues List** page. The link is shown only if your GitLab instance has [incoming email](../../../administration/incoming_email.md) +configured and there is at least one issue in the issue list.  When you click this link, an email address is generated and displayed, which should be used by **you only**, to create issues in this project. You can save this address as a -contact in your email client for easy access. +contact in your email client for quick access. WARNING: This is a private email address, generated just for you. **Keep it to yourself**, as anyone who knows it can create issues or merge requests as if they -were you. If the address is compromised, or you'd like it to be regenerated for -any reason, click **Email a new issue to this project** again and click the reset link. +were you. If the address is compromised, or you want to regenerate it, +click **Email a new issue to this project**, followed by **reset it**. -Sending an email to this address will create a new issue in your name for +Sending an email to this address creates a new issue associated with your account for this project, where: - The email subject becomes the issue title. @@ -118,15 +117,15 @@ older format is still supported, allowing existing aliases or contacts to contin ### New issue via URL with prefilled fields -You can link directly to the new issue page for a given project, with prefilled -field values using query string parameters in a URL. This is useful for embedding -a URL in an external HTML page, and also certain scenarios where you want the user to -create an issue with certain fields prefilled. +To link directly to the new issue page with prefilled fields, use query +string parameters in a URL. You can embed a URL in an external +HTML page, or create issues with certain +fields prefilled. The title, description, description template, and confidential fields can be prefilled using this method. You cannot pre-fill both the description and description template -fields in the same URL (since a description template also populates the description -field). +fields in the same URL because a description template also populates the description +field. | Field | URL Parameter Name | Notes | |----------------------|-----------------------|-------------------------------------------------------| @@ -147,9 +146,9 @@ Follow these examples to form your new issue URL with prefilled fields. ## Moving Issues -Moving an issue will copy it to a new location (project), and close it in the old project, -but it will not be deleted. There will also be a system note added to both issues -indicating where it came from and went to. +Moving an issue copies it to the target project, and closes it in the originating project. +The original issue is not deleted. A system note, which indicates +where it came from and went to, is added to both issues. The "Move issue" button is at the bottom of the right-sidebar when viewing the issue. @@ -157,7 +156,9 @@ The "Move issue" button is at the bottom of the right-sidebar when viewing the i ### Moving Issues in Bulk -If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**. +If you have advanced technical skills you can also bulk move all the issues from +one project to another in the rails console. The below script moves all issues +that are not in status **closed** from one project to another. To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below script. Please be sure to change `project`, `admin_user`, and `target_project` to your values. @@ -193,23 +194,18 @@ from its list and dropping it into the **Closed** list. ### Closing issues automatically -NOTE: -For performance reasons, automatic issue closing is disabled for the very first -push from an existing repository. - -When a commit or merge request resolves one or more issues, it is possible to have -these issues closed automatically when the commit or merge request reaches the project's -default branch. +When a commit or merge request resolves issues, the issues +can be closed automatically when the commit reaches the project's default branch. If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern), -all issues referenced in the matched text will be closed. This happens when the commit +all issues referenced in the matched text are closed. This happens when the commit is pushed to a project's [**default** branch](../repository/branches/index.md#default-branch), or when a commit or merge request is merged into it. For example, if `Closes #4, #6, Related to #5` is included in a Merge Request -description, issues `#4` and `#6` will close automatically when the MR is merged, but not `#5`. +description, issues `#4` and `#6` are closed automatically when the MR is merged, but not `#5`. Using `Related to` flags `#5` as a [related issue](related_issues.md), -but it will not close automatically. +but is not closed automatically.  @@ -219,9 +215,12 @@ If the issue is in a different repository than the MR, add the full URL for the Closes #4, #6, and https://gitlab.com/<username>/<projectname>/issues/<xxx> ``` +For performance reasons, automatic issue closing is disabled for the very first +push from an existing repository. + #### Default closing pattern -When not specified, the default issue closing pattern as shown below will be used: +When not specified, this default issue closing pattern is used: ```shell \b((?:[Cc]los(?:e[sd]?|ing)|\b[Ff]ix(?:e[sd]|ing)?|\b[Rr]esolv(?:e[sd]?|ing)|\b[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?: *,? +and +| *,? *)?)|([A-Z][A-Z0-9_]+-\d+))+) @@ -251,8 +250,8 @@ This commit is also related to #17 and fixes #18, #19 and https://gitlab.example.com/group/otherproject/issues/23. ``` -will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, -as well as `#22` and `#23` in `group/otherproject`. `#17` won't be closed as it does +closes `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, +as well as `#22` and `#23` in `group/otherproject`. `#17` is not closed as it does not match the pattern. It works with multi-line commit messages as well as one-liners when used from the command line with `git commit -m`. @@ -261,14 +260,14 @@ when used from the command line with `git commit -m`. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19754) in GitLab 12.7. The automatic issue closing feature can be disabled on a per-project basis -within the [project's repository settings](../settings/index.md). Referenced -issues will still be displayed as such but won't be closed automatically. +in the [project's repository settings](../settings/index.md). Referenced +issues are still displayed, but are not closed automatically.  This only applies to issues affected by new merge requests or commits. Already closed issues remain as-is. Disabling automatic issue closing only affects merge -requests *within* the project and won't prevent other projects from closing it +requests *in* the project and does not prevent other projects from closing it via cross-project issues. #### Customizing the issue closing pattern **(CORE ONLY)** diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 2f8603e1db0..22dfd3a8719 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -57,7 +57,7 @@ and edit labels. ### Project labels -> Showing all inherited labels [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in 13.5. +> Showing all inherited labels [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in GitLab 13.5. To view the project labels list, navigate to the project and click **Issues > Labels**. The list includes all labels that are defined at the project level, as well as all @@ -228,7 +228,7 @@ to label notifications for the project only, or the whole group. > - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this. Labels can have relative priorities, which are used in the **Label priority** and -**Priority** sort orders of the epic, issue, and merge request list pages. Prioritization +**Priority** sort orders of issues and merge request list pages. Prioritization for both group and project labels happens at the project level, and cannot be done from the group label list. @@ -241,7 +241,7 @@ means higher priority.  -On the epic, merge request, and issue list pages (for both groups and projects) you +On the merge request and issue list pages (for both groups and projects) you can sort by `Label priority` or `Priority`. If you sort by `Label priority`, GitLab uses this sort comparison order: diff --git a/doc/user/project/members/img/access_requests_management.png b/doc/user/project/members/img/access_requests_management.png Binary files differdeleted file mode 100644 index 9a1c9621e41..00000000000 --- a/doc/user/project/members/img/access_requests_management.png +++ /dev/null diff --git a/doc/user/project/members/img/access_requests_management_13_8.png b/doc/user/project/members/img/access_requests_management_13_8.png Binary files differnew file mode 100644 index 00000000000..950ef4dec01 --- /dev/null +++ b/doc/user/project/members/img/access_requests_management_13_8.png diff --git a/doc/user/project/members/img/add_user_email_accept.png b/doc/user/project/members/img/add_user_email_accept.png Binary files differdeleted file mode 100644 index cbee9e08c70..00000000000 --- a/doc/user/project/members/img/add_user_email_accept.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_email_accept_13_8.png b/doc/user/project/members/img/add_user_email_accept_13_8.png Binary files differnew file mode 100644 index 00000000000..ed980036af5 --- /dev/null +++ b/doc/user/project/members/img/add_user_email_accept_13_8.png diff --git a/doc/user/project/members/img/add_user_email_ready.png b/doc/user/project/members/img/add_user_email_ready.png Binary files differdeleted file mode 100644 index 0066eb3427b..00000000000 --- a/doc/user/project/members/img/add_user_email_ready.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_email_ready_13_8.png b/doc/user/project/members/img/add_user_email_ready_13_8.png Binary files differnew file mode 100644 index 00000000000..a610b46a176 --- /dev/null +++ b/doc/user/project/members/img/add_user_email_ready_13_8.png diff --git a/doc/user/project/members/img/add_user_email_search.png b/doc/user/project/members/img/add_user_email_search.png Binary files differdeleted file mode 100644 index 66bcd6aad80..00000000000 --- a/doc/user/project/members/img/add_user_email_search.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_email_search_13_8.png b/doc/user/project/members/img/add_user_email_search_13_8.png Binary files differnew file mode 100644 index 00000000000..934cf19bd3d --- /dev/null +++ b/doc/user/project/members/img/add_user_email_search_13_8.png diff --git a/doc/user/project/members/img/add_user_give_permissions.png b/doc/user/project/members/img/add_user_give_permissions.png Binary files differdeleted file mode 100644 index 376a3eefccc..00000000000 --- a/doc/user/project/members/img/add_user_give_permissions.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_give_permissions_13_8.png b/doc/user/project/members/img/add_user_give_permissions_13_8.png Binary files differnew file mode 100644 index 00000000000..1916d056a52 --- /dev/null +++ b/doc/user/project/members/img/add_user_give_permissions_13_8.png diff --git a/doc/user/project/members/img/add_user_import_members_from_another_project.png b/doc/user/project/members/img/add_user_import_members_from_another_project.png Binary files differdeleted file mode 100644 index cb3b70bd4b5..00000000000 --- a/doc/user/project/members/img/add_user_import_members_from_another_project.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_import_members_from_another_project_13_8.png b/doc/user/project/members/img/add_user_import_members_from_another_project_13_8.png Binary files differnew file mode 100644 index 00000000000..a6dddec3fb7 --- /dev/null +++ b/doc/user/project/members/img/add_user_import_members_from_another_project_13_8.png diff --git a/doc/user/project/members/img/add_user_imported_members.png b/doc/user/project/members/img/add_user_imported_members.png Binary files differdeleted file mode 100644 index 51fd7688890..00000000000 --- a/doc/user/project/members/img/add_user_imported_members.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_imported_members_13_8.png b/doc/user/project/members/img/add_user_imported_members_13_8.png Binary files differnew file mode 100644 index 00000000000..725e447604f --- /dev/null +++ b/doc/user/project/members/img/add_user_imported_members_13_8.png diff --git a/doc/user/project/members/img/add_user_list_members.png b/doc/user/project/members/img/add_user_list_members.png Binary files differdeleted file mode 100644 index e0fa404288d..00000000000 --- a/doc/user/project/members/img/add_user_list_members.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_list_members_13_8.png b/doc/user/project/members/img/add_user_list_members_13_8.png Binary files differnew file mode 100644 index 00000000000..b8c0160c6d8 --- /dev/null +++ b/doc/user/project/members/img/add_user_list_members_13_8.png diff --git a/doc/user/project/members/img/add_user_search_people.png b/doc/user/project/members/img/add_user_search_people.png Binary files differdeleted file mode 100644 index 41767a9167c..00000000000 --- a/doc/user/project/members/img/add_user_search_people.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_search_people_13_8.png b/doc/user/project/members/img/add_user_search_people_13_8.png Binary files differnew file mode 100644 index 00000000000..e9aa58512ab --- /dev/null +++ b/doc/user/project/members/img/add_user_search_people_13_8.png diff --git a/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png b/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png Binary files differdeleted file mode 100644 index e6e3f8f043b..00000000000 --- a/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png +++ /dev/null diff --git a/doc/user/project/members/img/other_group_sees_shared_project_v13_8.png b/doc/user/project/members/img/other_group_sees_shared_project_v13_8.png Binary files differnew file mode 100644 index 00000000000..aa2aaf071e1 --- /dev/null +++ b/doc/user/project/members/img/other_group_sees_shared_project_v13_8.png diff --git a/doc/user/project/members/img/project_groups_tab_13_8.png b/doc/user/project/members/img/project_groups_tab_13_8.png Binary files differnew file mode 100644 index 00000000000..5d7948f0761 --- /dev/null +++ b/doc/user/project/members/img/project_groups_tab_13_8.png diff --git a/doc/user/project/members/img/project_members.png b/doc/user/project/members/img/project_members.png Binary files differdeleted file mode 100644 index 218f5a24d2e..00000000000 --- a/doc/user/project/members/img/project_members.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_13_8.png b/doc/user/project/members/img/project_members_13_8.png Binary files differnew file mode 100644 index 00000000000..9120d471b3b --- /dev/null +++ b/doc/user/project/members/img/project_members_13_8.png diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png Binary files differdeleted file mode 100644 index 7d83659ef7a..00000000000 --- a/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png +++ /dev/null diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_8.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_8.png Binary files differnew file mode 100644 index 00000000000..6cbbb386396 --- /dev/null +++ b/doc/user/project/members/img/share_project_with_groups_tab_v13_8.png diff --git a/doc/user/project/members/img/share_project_with_groups_v13_6.png b/doc/user/project/members/img/share_project_with_groups_v13_6.png Binary files differdeleted file mode 100644 index 121e77671a3..00000000000 --- a/doc/user/project/members/img/share_project_with_groups_v13_6.png +++ /dev/null diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 85cb139c45b..cccb998fc31 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -21,7 +21,7 @@ project's **Members**. When your project belongs to the group, group members inherit the membership and permission level for the project from the group. - + From the image above, we can deduce the following things: @@ -46,17 +46,17 @@ using the dropdown on the right side: Right next to **People**, start typing the name or username of the user you want to add. - + Select the user and the [permission level](../../permissions.md) that you'd like to give the user. Note that you can select more than one user. - + Once done, select **Add users to project** and they are immediately added to your project with the permissions you gave them above. - + From there on, you can either remove an existing user or change their access level to the project. @@ -68,14 +68,14 @@ You can import another project's users in your own project by hitting the In the dropdown menu, you can see only the projects you are Maintainer on. - + Select the one you want and hit **Import project members**. A flash message displays, notifying you that the import was successful, and the new members are now in the project's members list. Notice that the permissions that they had on the project you imported from are retained. - + ## Invite people using their e-mail address @@ -83,18 +83,18 @@ If a user you want to give access to doesn't have an account on your GitLab instance, you can invite them just by typing their e-mail address in the user search field. - + As you can imagine, you can mix inviting multiple people and adding existing GitLab users to the project. - + Once done, hit **Add users to project** and watch that there is a new member with the e-mail address we used above. From there on, you can resend the invitation, change their access level, or even delete them. - + While unaccepted, the system automatically sends reminder emails on the second, fifth, and tenth day after the invitation was initially sent. @@ -130,7 +130,7 @@ NOTE: If a project does not have any maintainers, the notification is sent to the most recently active owners of the project's group. - + If you change your mind before your request is approved, just click the **Withdraw Access Request** button. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index edfe8ae3b5b..d17717fb29c 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -26,19 +26,20 @@ To share 'Project Acme' with the 'Engineering' group: 1. For 'Project Acme' use the left navigation menu to go to **Members**. -  +  1. Select the **Invite group** tab. 1. Add the 'Engineering' group with the maximum access level of your choice. 1. Optionally, select an expiring date. 1. Click **Invite**. +1. After sharing 'Project Acme' with 'Engineering': + - The group is listed in the **Groups** tab. -  +  -1. After sharing 'Project Acme' with 'Engineering', the project is listed - on the group dashboard + - The project is listed on the group dashboard. -  +  Note that you can only share a project with: diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 8eabef982c8..8adaae3b2ef 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -23,10 +23,10 @@ of the merge request. ## Enabling commit edits from upstream members -The feature can only be enabled by users who already have push access to the -source project and only lasts while the merge request is open. Once enabled, -upstream members will also be able to retry the pipelines and jobs of the -merge request: +From [GitLab 13.7 onwards](https://gitlab.com/gitlab-org/gitlab/-/issues/23308), +this setting is enabled by default. It can be changed by users with Developer +permissions to the source project. Once enabled, upstream members will also be +able to retry the pipelines and jobs of the merge request: 1. While creating or editing a merge request, select the checkbox **Allow commits from members who can merge to the target branch**. diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 04114968c80..6fa2340c7a4 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -60,7 +60,7 @@ on your code by using GitLab CI/CD and [sitespeed.io](https://www.sitespeed.io) using Docker-in-Docker. 1. First, set up GitLab Runner with a - [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). + [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). 1. Configure the default Browser Performance Testing CI job as follows in your `.gitlab-ci.yml` file: ```yaml diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 5a98338a81b..ca15ec154fc 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -72,10 +72,10 @@ It requires GitLab 11.11 or later, and GitLab Runner 11.5 or later. If you are u GitLab 11.4 or earlier, you can view the deprecated job definitions in the [documentation archive](https://docs.gitlab.com/12.10/ee/user/project/merge_requests/code_quality.html#previous-job-definitions). -First, you need GitLab Runner configured: +- Using shared runners, the job should be configured For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). +- Using private runners, there is an [alternative configuration](#set-up-a-private-runner-for-code-quality-without-docker-in-docker) recommended for running CodeQuality analysis more efficiently. -- For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). -- With enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. +In either configuration, the runner mmust have enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. Once you set up GitLab Runner, include the Code Quality template in your CI configuration: @@ -140,6 +140,99 @@ definition they could execute privileged Docker commands on the runner host. Having proper access control policies mitigates this attack vector by allowing access only to trusted actors. +### Set up a private runner for code quality without Docker-in-Docker + +It's possible to configure your own runners and avoid Docker-in-Docker. You can use a +configuration that may greatly speed up job execution without requiring your runners +to operate in privileged mode. + +This alternative configuration uses socket binding to share the Runner's Docker daemon +with the job environment. Be aware that this configuration [has significant considerations](../../../ci/docker/using_docker_build.md#use-docker-socket-binding) +to be consider, but may be preferable depending on your use case. + +1. Register a new runner: + + ```shell + $ gitlab-runner register --executor "docker" \ + --docker-image="docker:stable" \ + --url "https://gitlab.com/" \ + --description "cq-sans-dind" \ + --tag-list "cq-sans-dind" \ + --locked="false" \ + --access-level="not_protected" \ + --docker-volumes "/cache"\ + --docker-volumes "/var/run/docker.sock:/var/run/docker.sock" \ + --registration-token="<project_token>" \ + --non-interactive + ``` + +1. **Optional, but recommended:** Set the builds directory to `/tmp/builds`, + so job artifacts are periodically purged from the runner host. If you skip + this step, you must clean up the default builds directory (`/builds`) yourself. + You can do this by adding the following two flags to `gitlab-runner register` + in the previous step. + + ```shell + --builds-dir /tmp/builds + --docker-volumes /tmp/builds:/tmp/builds + ``` + + The resulting configuration: + + ```toml + [[runners]] + name = "cq-sans-dind" + url = "https://gitlab.com/" + token = "<project_token>" + executor = "docker" + builds_dir = "/tmp/builds" + [runners.docker] + tls_verify = false + image = "docker:stable" + privileged = false + disable_entrypoint_overwrite = false + oom_kill_disable = false + disable_cache = false + volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock", "/tmp/builds:/tmp/builds"] + shm_size = 0 + [runners.cache] + [runners.cache.s3] + [runners.cache.gcs] + ``` + +1. Apply two overrides to the `code_quality` job created by the template: + + ```yaml + include: + - template: Code-Quality.gitlab-ci.yml + + code_quality: + services: # Shut off Docker-in-Docker + tags: + - cq-sans-dind # Set this job to only run on our new specialized runner + ``` + +The end result is that: + +- Privileged mode is not used. +- Docker-in-Docker is not used. +- Docker images, including all CodeClimate images, are cached, and not re-fetched for subsequent jobs. + +With this configuration, the run time for a second pipeline is much shorter. For example +this [small change](https://gitlab.com/drewcimino/test-code-quality-template/-/merge_requests/4/diffs?commit_id=1e705607aef7236c1b20bb6f637965f3f3e53a46) +to an [open merge request](https://gitlab.com/drewcimino/test-code-quality-template/-/merge_requests/4/pipelines) +running Code Quality analysis ran significantly faster the second time: + + + +This configuration is not possible on `gitlab.com` shared runners. Shared runners +are configured with `privileged=true`, and they do not expose `docker.sock` into +the job container. As a result, socket binding cannot be used to make `docker` available +in the context of the job script. + +[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) +was chosen as an operational decision by the runner team, instead of exposing `docker.sock`. + ### Disabling the code quality job The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` environment diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index cb95daa2cab..bc718ae867f 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -62,7 +62,7 @@ request's page at the top-right side: - Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. - Set the merge request as a [**Draft**](work_in_progress_merge_requests.md) to avoid accidental merges before it is ready. -Once you have created the merge request, you can also: +After you have created the merge request, you can also: - [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. - [Perform inline code reviews](reviewing_and_managing_merge_requests.md#perform-inline-code-reviews). @@ -70,7 +70,7 @@ Once you have created the merge request, you can also: - Preview continuous integration [pipelines on the merge request widget](reviewing_and_managing_merge_requests.md#pipeline-status-in-merge-requests-widgets). - Preview how your changes look directly on your deployed application with [Review Apps](reviewing_and_managing_merge_requests.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). -- Perform a [Review](../../discussions/index.md#merge-request-reviews) in order to create multiple comments on a diff and publish them once you're ready. +- Perform a [Review](../../discussions/index.md#merge-request-reviews) to create multiple comments on a diff and publish them when you're ready. - Add [code suggestions](../../discussions/index.md#suggest-changes) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. - Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking). @@ -115,9 +115,10 @@ It is also possible to manage multiple assignees: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. > - It was [deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49787) on GitLab 13.7.1. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49787) on GitLab 13.7. > - It's enabled on GitLab.com. > - It's recommended for production use. +> - It can be enabled or disabled for a single project. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-merge-request-reviewers). **(CORE ONLY)** WARNING: @@ -160,6 +161,53 @@ Feature.disable(:merge_request_reviewers) Feature.disable(:merge_request_reviewers, Project.find(<project id>)) ``` +#### Reviewer approval rules + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. +> - It was [deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51183) in GitLab 13.8. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - It can be enabled or disabled for a single project. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-reviewer-approval-rules). **(CORE ONLY)** + +When editing the **Reviewers** field in a new or existing merge request, this feature +displays the name of the matching [approval rule](merge_request_approvals.md#approval-rules) +below the name of each suggested reviewer. [Code Owners](../code_owners.md) are displayed as `Codeowner` without group detail. We intend to iterate on this feature in future releases. + +This example shows reviewers and approval rules when creating a new merge request: + + + +This example shows reviewers and approval rules in a merge request sidebar: + + + +##### Enable or disable Reviewer Approval Rules **(CORE ONLY)** + +Merge Request Reviewers is under development and ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +# For the instance +Feature.enable(:reviewer_approval_rules) +# For a single project +Feature.enable(:reviewer_approval_rules, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:reviewer_approval_rules) +# For a single project +Feature.disable(:reviewer_approval_rules, Project.find(<project id>)) +``` + ### Merge requests to close issues If the merge request is being created to resolve an issue, you can @@ -199,5 +247,5 @@ is set for deletion, the merge request widget displays the at once. By doing so, you save pipeline minutes. - Delete feature branches on merge or after merging them to keep your repository clean. - Take one thing at a time and ship the smallest changes possible. By doing so, - you'll have faster reviews and your changes will be less prone to errors. + reviews are faster and your changes are less prone to errors. - Do not use capital letters nor special chars in branch names. diff --git a/doc/user/project/merge_requests/img/code_quality_host_bound_sequential.png b/doc/user/project/merge_requests/img/code_quality_host_bound_sequential.png Binary files differnew file mode 100644 index 00000000000..2b31f3b42ee --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality_host_bound_sequential.png diff --git a/doc/user/project/merge_requests/img/reviewer_approval_rules_form_v13_8.png b/doc/user/project/merge_requests/img/reviewer_approval_rules_form_v13_8.png Binary files differnew file mode 100644 index 00000000000..c2aa0689d65 --- /dev/null +++ b/doc/user/project/merge_requests/img/reviewer_approval_rules_form_v13_8.png diff --git a/doc/user/project/merge_requests/img/reviewer_approval_rules_sidebar_v13_8.png b/doc/user/project/merge_requests/img/reviewer_approval_rules_sidebar_v13_8.png Binary files differnew file mode 100644 index 00000000000..3828868965b --- /dev/null +++ b/doc/user/project/merge_requests/img/reviewer_approval_rules_sidebar_v13_8.png diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 82b5d67ba2b..9154897d42d 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -103,7 +103,7 @@ job. An example configuration workflow: 1. Set up GitLab Runner to run Docker containers, like the - [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). + [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). 1. Configure the default Load Performance Testing CI job in your `.gitlab-ci.yml` file. You need to include the template and configure it with variables: diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 5c466654b31..93b85ce8669 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -8,7 +8,7 @@ type: reference, concepts # Squash and merge > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1024) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.17. -> - [Ported](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) to GitLab Core 11.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from [GitLab Starter](https://about.gitlab.com/pricing/)to GitLab Core in 11.0. With squash and merge you can combine all your merge request's commits into one and retain a clean history. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index c38b28f7718..3960f916f9b 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -33,7 +33,7 @@ This format was originally developed for Java, but most coverage analysis framew for other languages have plugins to add support for it, like: - [simplecov-cobertura](https://rubygems.org/gems/simplecov-cobertura) (Ruby) -- [gocover-cobertura](https://github.com/t-yuki/gocover-cobertura) (Golang) +- [gocover-cobertura](https://github.com/boumenot/gocover-cobertura) (Golang) Other coverage analysis frameworks support the format out of the box, for example: diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index fd7c58f12b9..4910751ece1 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -72,10 +72,26 @@ Let's consider the following scenario: ## Job token -A unique job token is generated for each job and provides the user read -access all projects that would be normally accessible to the user creating that -job. The unique job token does not have any write permissions, but there -is a [proposal to add support](https://gitlab.com/groups/gitlab-org/-/epics/3559). +When a pipeline job is about to run, GitLab generates a unique token and injects it as the +[`CI_JOB_TOKEN` predefined variable](../../ci/variables/predefined_variables.md). +This token can authenticate [API requests](../../api/README.md) +from the job script (Runner) that needs to access the project's resources (for example, when +fetching a job artifact). + +Once the token is authenticated, GitLab identifies the user who triggered the job and uses this user +to authorize access to the resource. Therefore, this user must be assigned to +[a role that has the required privileges](../permissions.md). + +The job token has these limitations: + +- Not all APIs allow job tokens for authentication. See [this list](../../api/README.md#gitlab-ci-job-token) + for available endpoints. +- The token is valid only while the pipeline job runs. Once the job finishes, the token can't be + used for authentication. + +Although a job token is handy to quickly access a project's resources without any configuration, it +sometimes gives extra permissions that aren't necessary. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) +to redesign the feature for more strategic control of the access permissions. If you need your CI pipeline to push to the Package Registry, consider using [deploy tokens](deploy_tokens/index.md). 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 4aa89ec6f8d..f02697a3cd5 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 @@ -24,7 +24,7 @@ GitLab Pages site. Note that **how to** add DNS records depends on which server your domain is hosted on. Every control panel has its own place to do it. If you are not an administrator of your domain, and don't have access to your registrar, -you'll need to ask for the technical support of your hosting service +you must ask the technical support of your hosting service to do it for you. To help you out, we've gathered some instructions on how to do that @@ -67,7 +67,7 @@ Example: - `www` => `CNAME` => `example.com` -This way, visitors visiting `www.example.com` will be redirected to +This way, visitors visiting `www.example.com` are redirected to `example.com`. ## MX record diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index f8173b4c004..8ed0ef82893 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -47,7 +47,8 @@ Click **Create New Domain**. #### 2. Get the verification code -Once you have added a new domain to Pages, the verification code will be prompted to you. Copy the values from GitLab and paste them in your domain's control panel as a TXT record on the next step. +After you add a new domain to Pages, the verification code prompts you. Copy the values from GitLab +and paste them in your domain's control panel as a TXT record on the next step.  @@ -91,7 +92,7 @@ add a DNS apex `CNAME` record instead of an `A` record. The main advantage of doing so is that when GitLab Pages IP on GitLab.com changes for whatever reason, you don't need to update your `A` record. There may be a few exceptions, but **this method is not recommended** -as it most likely won't work if you set an [`MX` record](dns_concepts.md#mx-record) for your root domain. +as it most likely doesn't work if you set an [`MX` record](dns_concepts.md#mx-record) for your root domain. ##### For subdomains @@ -154,12 +155,11 @@ Once you have added all the DNS records:  -As soon as your domain becomes active, your website will be available -through your domain name. +As soon as your domain becomes active, your website is available through your domain name. WARNING: Considering GitLab instances with domain verification enabled, -if the domain cannot be verified for 7 days, it will be removed +if the domain can't be verified for 7 days, it's removed from the GitLab project. > **Notes:** @@ -169,9 +169,9 @@ from the GitLab project. to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification). > - [DNS propagation may take some time (up to 24h)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), although it's usually a matter of minutes to complete. Until it does, verification - will fail and attempts to visit your domain will respond with a 404. + fails, and attempts to visit your domain result in a 404. > - Once your domain has been verified, leave the verification record - in place: your domain will be periodically reverified, and may be + in place. Your domain is periodically reverified, and may be disabled if the record is removed. ##### Troubleshooting Pages domain verification @@ -211,7 +211,7 @@ For a subdomain: You can add more than one alias (custom domains and subdomains) to the same project. An alias can be understood as having many doors leading to the same room. -All the aliases you've set to your site will be listed on **Setting > Pages**. +All the aliases you've set to your site are listed on **Setting > Pages**. From that page, you can view, add, and remove them. ### Redirecting `www.domain.com` to `domain.com` with Cloudflare @@ -294,7 +294,7 @@ Sublime Text, Atom, Dreamweaver, Brackets, etc). To make your website's visitors even more secure, you can choose to force HTTPS for GitLab Pages. By doing so, all attempts to visit your -website via HTTP will be automatically redirected to HTTPS via 301. +website through HTTP are automatically redirected to HTTPS through 301. It works with both the GitLab default domain and with your custom domain (as long as you've set a valid certificate for it). 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 3dea35153e4..aa06a15a8c0 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 @@ -50,15 +50,15 @@ Once you've met the requirements, enable Let's Encrypt integration: 1. Click **Save changes**. -Once enabled, GitLab will obtain a LE certificate and add it to the -associated Pages domain. It also will be renewed automatically by GitLab. +Once enabled, GitLab obtains a LE certificate and add it to the +associated Pages domain. GitLab also renews it automatically. > **Notes:** > > - Issuing the certificate and updating Pages configuration > **can take up to an hour**. -> - If you already have SSL certificate in domain settings it -> will continue to work until it will be replaced by Let's Encrypt's certificate. +> - If you already have an SSL certificate in domain settings it +> continues to work until replaced by the Let's Encrypt's certificate. ## Troubleshooting diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index dc73a664324..e8c6305dbab 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -10,10 +10,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w _Read this document for a brief overview of SSL/TLS certificates in the scope of GitLab Pages, for beginners in web development._ -Every GitLab Pages project on GitLab.com will be available under +Every GitLab Pages project on GitLab.com is available under HTTPS for the default Pages domain (`*.gitlab.io`). Once you set up your Pages project with your custom (sub)domain, if you want -it secured by HTTPS, you will have to issue a certificate for that +it secured by HTTPS, you must issue a certificate for that (sub)domain and install it on your project. NOTE: @@ -41,9 +41,6 @@ the connection between the **client** (you, me, your visitors) and the **server** (where you site lives), through a keychain of authentications and validations. -How about taking Josh's advice and protecting our sites too? We will be -well supported, and we'll contribute to a safer internet. - ## Organizations supporting HTTPS There is a huge movement in favor of securing all the web. W3C fully @@ -62,8 +59,8 @@ GitLab Pages accepts certificates provided in the [PEM](https://knowledge.digice for public websites for security reasons and to ensure that browsers trust your site's certificate. There are various kinds of certificates, each one -with a certain security level. A static personal website will -not require the same security level as an online banking web app, +with a certain security level. A static personal website doesn't +require the same security level as an online banking web app, for instance. There are some certificate authorities that diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 6dd431e02b0..e0d5e8be535 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -41,7 +41,7 @@ configuration for the Pages site to generate properly. If everything is configured correctly, the site can take approximately 30 minutes to deploy. -You can watch the pipeline run by going to **CI / CD > Pipelines**. +You can watch the pipeline run by navigating to **CI / CD > Pipelines**. When the pipeline is finished, go to **Settings > Pages** to find the link to your Pages website. diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index 525bbde4671..c7916b7c01e 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -17,7 +17,7 @@ configured to generate a Pages site. To fork a sample project and create a Pages website: -1. View the sample projects by going to the [GitLab Pages examples](https://gitlab.com/pages) group. +1. View the sample projects by navigating to the [GitLab Pages examples](https://gitlab.com/pages) group. 1. Click the name of the project you want to [fork](../../../../gitlab-basics/fork-project.md). 1. In the top right, click the **Fork** button, and then choose a namespace to fork to. 1. Go to your project's **CI/CD > Pipelines** and click **Run pipeline**. @@ -50,7 +50,7 @@ You can take some **optional** further steps: If you set the repository path to `gitlab-tests.gitlab.io`, the resulting URL for your Pages website is `https://gitlab-tests.gitlab.io`. -  +  - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-baseurls) from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the configuration file. 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 230e88f35f5..3f2df634e3a 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Create a GitLab Pages website from scratch -This tutorial shows you how to create a Pages site from scratch. You will start with +This tutorial shows you how to create a Pages site from scratch. You start with a blank project and create your own CI file, which gives instruction to a [runner](https://docs.gitlab.com/runner/). When your CI/CD [pipeline](../../../../ci/pipelines/index.md) runs, the Pages site is created. @@ -218,7 +218,7 @@ There are three default stages for GitLab CI/CD: build, test, and deploy. If you want to test your script and check the built site before deploying -to production, you can run the test exactly as it will run when you +to production, you can run the test exactly as it runs when you push to `master`. To specify a stage for your job to run in, @@ -376,7 +376,7 @@ test: In this case, you need to exclude the `/vendor` directory from the list of folders Jekyll builds. Otherwise, Jekyll -will try to build the directory contents along with the site. +tries to build the directory contents along with the site. In the root directory, create a file called `_config.yml` and add this content: diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index f549c4e6e7d..801fe0c7ef0 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -16,7 +16,7 @@ wildcard domain with your sysadmin. This guide is valid for any GitLab instance, replace the Pages wildcard domain on GitLab.com (`*.gitlab.io`) with your own. If you set up a GitLab Pages project on GitLab, -it will automatically be accessible under a +it's automatically accessible under a subdomain of `namespace.example.io`. The [`namespace`](../../group/index.md#namespaces) is defined by your username on GitLab.com, @@ -45,35 +45,35 @@ To understand Pages domains clearly, read the examples below. - You created a project called `blog` under your username `john`, therefore your project URL is `https://gitlab.com/john/blog/`. Once you enable GitLab Pages for this project, and build your site, - it will be available under `https://john.gitlab.io/blog/`. + you can access it at `https://john.gitlab.io/blog/`. - You created a group for all your websites called `websites`, and a project within this group is called `blog`. Your project URL is `https://gitlab.com/websites/blog/`. Once you enable - GitLab Pages for this project, the site will live under + GitLab Pages for this project, the site is available at `https://websites.gitlab.io/blog/`. - You created a group for your engineering department called `engineering`, a subgroup for all your documentation websites called `docs`, and a project within this subgroup is called `workflows`. Your project URL is `https://gitlab.com/engineering/docs/workflows/`. Once you enable - GitLab Pages for this project, the site will live under + GitLab Pages for this project, the site is available at `https://engineering.gitlab.io/docs/workflows`. ### User and Group website examples - Under your username, `john`, you created a project called - `john.gitlab.io`. Your project URL will be `https://gitlab.com/john/john.gitlab.io`. + `john.gitlab.io`. Your project URL is `https://gitlab.com/john/john.gitlab.io`. Once you enable GitLab Pages for your project, your website - will be published under `https://john.gitlab.io`. + is published under `https://john.gitlab.io`. - Under your group `websites`, you created a project called - `websites.gitlab.io`. your project's URL will be `https://gitlab.com/websites/websites.gitlab.io`. + `websites.gitlab.io`. Your project's URL is `https://gitlab.com/websites/websites.gitlab.io`. Once you enable GitLab Pages for your project, - your website will be published under `https://websites.gitlab.io`. + your website is published under `https://websites.gitlab.io`. **General example:** -- On GitLab.com, a project site will always be available under +- On GitLab.com, a project site is always available under `https://namespace.gitlab.io/project-name` -- On GitLab.com, a user or group website will be available under +- On GitLab.com, a user or group website is available under `https://namespace.gitlab.io/` - On your GitLab instance, replace `gitlab.io` above with your Pages server domain. Ask your sysadmin for this information. @@ -87,7 +87,7 @@ Every Static Site Generator (SSG) default configuration expects to find your website under a (sub)domain (`example.com`), not in a subdirectory of that domain (`example.com/subdir`). Therefore, whenever you publish a project website (`namespace.gitlab.io/project-name`), -you'll have to look for this configuration (base URL) on your SSG's +you must look for this configuration (base URL) on your SSG's documentation and set it up to reflect this pattern. For example, for a Jekyll site, the `baseurl` is defined in the Jekyll @@ -99,11 +99,11 @@ baseurl: "/blog" ``` On the contrary, if you deploy your website after forking one of -our [default examples](https://gitlab.com/pages), the `baseurl` will -already be configured this way, as all examples there are project -websites. If you decide to make yours a user or group website, you'll -have to remove this configuration from your project. For the Jekyll -example we've just mentioned, you'd have to change Jekyll's `_config.yml` to: +our [default examples](https://gitlab.com/pages), the `baseurl` is +already configured this way, as all examples there are project +websites. If you decide to make yours a user or group website, you +must remove this configuration from your project. For the Jekyll +example we just mentioned, you must change Jekyll's `_config.yml` to: ```yaml baseurl: "" diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 846d30e898c..c9e28bf15c2 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -81,10 +81,12 @@ becomes available automatically. To deploy your site, GitLab uses its built-in tool called [GitLab CI/CD](../../../ci/README.md) to build your site and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to accomplish this task is created from a file named -`.gitlab-ci.yml`, which you can [create and modify](getting_started/pages_from_scratch.md) at will. A specific `job` called `pages` in the configuration file will make GitLab aware that you are deploying a GitLab Pages website. +`.gitlab-ci.yml`, which you can [create and modify](getting_started/pages_from_scratch.md). +A specific `job` called `pages` in the configuration file makes GitLab aware that you're deploying a +GitLab Pages website. You can either use the GitLab [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names), -`*.gitlab.io`, or your own domain (`example.com`). In that case, you'll +`*.gitlab.io`, or your own domain (`example.com`). In that case, you need administrator access to your domain's registrar (or control panel) to set it up with Pages. The following diagrams show the workflows you might follow to get started with Pages. @@ -94,15 +96,15 @@ The following diagrams show the workflows you might follow to get started with P ## Access to your Pages site If you're using GitLab Pages default domain (`.gitlab.io`), -your website will be automatically secure and available under +your website is automatically secure and available under HTTPS. If you're using your own custom domain, you can optionally secure it with SSL/TLS certificates. -If you're using GitLab.com, your website will be publicly available to the internet. +If you're using GitLab.com, your website is publicly available to the internet. To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). If you're using a self-managed instance (Core, Starter, Premium, or Ultimate), -your websites will be published on your own server, according to the +your websites are published on your own server, according to the [Pages settings](../../../administration/pages/index.md) chosen by your sysadmin, who can make them public or internal. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 5a284bf57c3..8380f367212 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -44,19 +44,19 @@ Visit the [GitLab Pages group](https://gitlab.com/groups/pages) for a complete l You can provide your own 403 and 404 error pages by creating the `403.html` and `404.html` files respectively in the root directory of the `public/` directory -that will be included in the artifacts. Usually this is the root directory of +that are included in the artifacts. Usually this is the root directory of your project, but that may differ depending on your static generator configuration. If the case of `404.html`, there are different scenarios. For example: - If you use project Pages (served under `/projectname/`) and try to access - `/projectname/non/existing_file`, GitLab Pages will try to serve first + `/projectname/non/existing_file`, GitLab Pages tries to serve first `/projectname/404.html`, and then `/404.html`. - If you use user/group Pages (served under `/`) and try to access - `/non/existing_file` GitLab Pages will try to serve `/404.html`. + `/non/existing_file` GitLab Pages tries to serve `/404.html`. - If you use a custom domain and try to access `/non/existing_file`, GitLab - Pages will try to serve only `/404.html`. + Pages tries to serve only `/404.html`. ## Redirects in GitLab Pages @@ -71,8 +71,8 @@ To restrict access to your website, enable [GitLab Pages Access Control](pages_a If you ever feel the need to purge your Pages content, you can do so by going to your project's settings through the gear icon in the top right, and then -navigating to **Pages**. Hit the **Remove pages** button and your Pages website -will be deleted. +navigating to **Pages**. Click the **Remove pages** button to delete your Pages +website.  @@ -81,9 +81,9 @@ will be deleted. When using Pages under the general domain of a GitLab instance (`*.example.io`), you _cannot_ use HTTPS with sub-subdomains. That means that if your username or group name contains a dot, for example `foo.bar`, the domain -`https://foo.bar.example.io` will _not_ work. This is a limitation of the -[HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). HTTP pages will continue to work provided you -don't redirect HTTP to HTTPS. +`https://foo.bar.example.io` does _not_ work. This is a limitation of the +[HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). +HTTP pages continue to work provided you don't redirect HTTP to HTTPS. GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations). You can only create the highest-level group website. @@ -130,11 +130,11 @@ See this document for a [step-by-step guide](getting_started/pages_from_scratch. Remember that GitLab Pages are by default branch/tag agnostic and their deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit the `pages` job with the [`only` parameter](../../../ci/yaml/README.md#onlyexcept-basic), -whenever a new commit is pushed to a branch that will be used specifically for -your pages. +whenever a new commit is pushed to a branch used specifically for your +pages. That way, you can have your project's code in the `master` branch and use an -orphan branch (let's name it `pages`) that will host your static generator site. +orphan branch (let's name it `pages`) to host your static generator site. You can create a new empty branch like this: @@ -142,9 +142,9 @@ You can create a new empty branch like this: git checkout --orphan pages ``` -The first commit made on this new branch will have no parents and it will be -the root of a new history totally disconnected from all the other branches and -commits. Push the source files of your static generator in the `pages` branch. +The first commit made on this new branch has no parents and is the root of a +new history totally disconnected from all the other branches and commits. +Push the source files of your static generator in the `pages` branch. Below is a copy of `.gitlab-ci.yml` where the most significant line is the last one, specifying to execute everything in the `pages` branch: @@ -172,9 +172,9 @@ also includes `.gitlab-ci.yml`. Most modern browsers support downloading files in a compressed format. This speeds up downloads by reducing the size of files. -Before serving an uncompressed file, Pages will check whether the same file -exists with a `.br` or `.gz` extension. If it does, and the browser supports receiving -compressed files, it will serve that version instead of the uncompressed one. +Before serving an uncompressed file, Pages checks if the same file exists with +a `.br` or `.gz` extension. If it does, and the browser supports receiving +compressed files, it serves that version instead of the uncompressed one. To take advantage of this feature, the artifact you upload to the Pages should have this structure: @@ -236,10 +236,10 @@ public/ ``` Pages supports reaching each of these files through several different URLs. In -particular, it will always look for an `index.html` file if the URL only +particular, it always looks for an `index.html` file if the URL only specifies the directory. If the URL references a file that doesn't exist, but -adding `.html` to the URL leads to a file that *does* exist, it will be served -instead. Here are some examples of what will happen given the above Pages site: +adding `.html` to the URL leads to a file that *does* exist, it's served +instead. Here are some examples of what happens given the above Pages site: | URL path | HTTP response | File served | | -------------------- | ------------- | ----------- | @@ -275,7 +275,7 @@ to private, internal or public. ### Do I need to create a user/group website before creating a project website? -No, you don't. You can create your project first and it will be accessed under +No, you don't. You can create your project first and access it under `http(s)://namespace.example.io/projectname`. ## Known issues diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index f2b75354bf8..b5932fc8766 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -61,7 +61,7 @@ might be slightly different. Follow the ``` Alternatively, you can register without adding an e-mail account, - but you won't be notified about the certificate expiration's date: + but you aren't notified about the certificate expiration's date: ```shell sudo certbot certonly -a manual -d example.com --register-unsafely-without-email @@ -71,10 +71,10 @@ might be slightly different. Follow the Read through CertBot's documentation on their [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options). -1. You'll be prompted with a message to agree with their terms. +1. You're prompted with a message to agree with their terms. Press `A` to agree and `Y` to let they log your IP. - CertBot will then prompt you with the following message: + CertBot then prompts you with the following message: ```shell Create a file containing just this data: @@ -88,7 +88,7 @@ might be slightly different. Follow the Press Enter to Continue ``` -1. **Do not press Enter yet.** Let's Encrypt will need to verify your +1. **Do not press Enter yet.** Let's Encrypt needs to verify your domain ownership before issuing the certificate. To do so, create 3 consecutive directories under your website's root: `/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/` @@ -103,11 +103,11 @@ might be slightly different. Follow the `http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP` to allow Let's Encrypt to verify the ownership of your domain, therefore, it needs to be part of the website content under the - repo's [`public`](index.md#how-it-works) folder. + repository's [`public`](index.md#how-it-works) folder. 1. Add, commit, and push the file into your repository in GitLab. Once the pipeline passes, press **Enter** on your terminal to continue issuing your - certificate. CertBot will then prompt you with the following message: + certificate. CertBot then prompts you with the following message: ```shell Waiting for verification... @@ -157,7 +157,7 @@ valid certificates)**. ## Renewal -Let's Encrypt certificates expire every 90 days and you'll have to +Let's Encrypt certificates expire every 90 days and you must renew them periodically. To renew all your certificates at once, run: ```shell diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 9d17277fe9e..a2a17a4f2ca 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -28,20 +28,20 @@ For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v with GitLab Pages, depending on your project's visibility: - If your project is private: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - **Only project members**: Only project members are able to browse the website. + - **Everyone**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. - If your project is internal: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership. - - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - **Only project members**: Only project members are able to browse the website. + - **Everyone with access**: Everyone logged into GitLab is able to browse the website, no matter their project membership. + - **Everyone**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. - If your project is public: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - **Only project members**: Only project members are able to browse the website. + - **Everyone with access**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. 1. Click **Save changes**. The next time someone tries to access your website and the access control is -enabled, they will be presented with a page to sign into GitLab and verify they +enabled, they're presented with a page to sign into GitLab and verify they can access the website. ## Terminating a Pages session diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 9f849051f40..64be3182dab 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -9,8 +9,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Introduced in [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672): > once an action is executed, an alert appears when a quick action is successfully applied. -> - In [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/16877) and later, you can use +> - Introduced in [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/16877): you can use > quick actions when updating the description of issues, epics, and merge requests. +> - Introduced in [GitLab 13.8](https://gitlab.com/gitlab-org/gitlab/-/issues/292393): when you enter +> `/` into a description or comment field, all available quick actions are displayed in a scrollable list. +> - The rebase quick action was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49800) in GitLab 13.8. Quick actions are textual shortcuts for common actions on issues, epics, merge requests, and commits that are usually done by clicking buttons or dropdowns in the GitLab UI. @@ -31,6 +34,9 @@ The following quick actions are applicable to descriptions, discussions and thre | `/assign @user` | ✓ | ✓ | | Assign one user. | | `/assign @user1 @user2` | ✓ | ✓ | | Assign multiple users. **(STARTER)** | | `/assign me` | ✓ | ✓ | | Assign yourself. | +| `/assign_reviewer @user` | | ✓ | | Assign one user as a reviewer. | +| `/assign_reviewer @user1 @user2` | | ✓ | | Assign multiple users as reviewers. **(STARTER)** | +| `/assign_reviewer me` | | ✓ | | Assign yourself as a reviewer. | | `/award :emoji:` | ✓ | ✓ | ✓ | Toggle emoji award. | | `/child_epic <epic>` | | | ✓ | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | | `/clear_weight` | ✓ | | | Clear weight. **(STARTER)** | @@ -56,6 +62,8 @@ The following quick actions are applicable to descriptions, discussions and thre | `/promote` | ✓ | | | Promote issue to epic. **(PREMIUM)** | | `/publish` | ✓ | | | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) **(ULTIMATE)** | | `/reassign @user1 @user2` | ✓ | ✓ | | Replace current assignees with those specified. **(STARTER)** | +| `/rebase` | | ✓ | | Rebase source branch. This will schedule a background task that attempt to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` will be ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab will display a message that a rebase cannot be scheduled. Rebase failures will be displayed with the merge request status. | +| `/reassign_reviewer @user1 @user2` | | ✓ | | Replace current reviewers with those specified. **(STARTER)** | | `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace current labels with those specified. | | `/relate #issue1 #issue2` | ✓ | | | Mark issues as related. **(STARTER)** | | `/remove_child_epic <epic>` | | | ✓ | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | @@ -78,7 +86,9 @@ The following quick actions are applicable to descriptions, discussions and thre | `/title <new title>` | ✓ | ✓ | ✓ | Change title. | | `/todo` | ✓ | ✓ | ✓ | Add a to-do item. | | `/unassign @user1 @user2` | ✓ | ✓ | | Remove specific assignees. **(STARTER)** | -| `/unassign` | ✓ | ✓ | | Remove all assignees. | +| `/unassign` | | ✓ | | Remove all assignees. | +| `/unassign_reviewer @user1 @user2` | | ✓ | | Remove specific reviewers. **(STARTER)** | +| `/unassign_reviewer` | | ✓ | | Remove all reviewers. | | `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove specified labels. | | `/unlabel` or `/remove_label` | ✓ | ✓ | ✓ | Remove all labels. | | `/unlock` | ✓ | ✓ | | Unlock the discussions. | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 7b412270938..90d7ac0a3c2 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -200,7 +200,7 @@ If the job that's executing is within a freeze period, GitLab CI/CD creates an e variable named `$CI_DEPLOY_FREEZE`. To prevent the deployment job from executing, create a `rules` entry in your -`gitlab-ci.yaml`, for example: +`gitlab-ci.yml`, for example: ```yaml deploy_to_production: @@ -274,14 +274,11 @@ Release note descriptions are unrelated. Description supports [Markdown](../../m ### Release assets -You can currently add the following types of assets to each release: +You can add the following types of assets to each release: - [Source code](#source-code) - [Links](#links) -GitLab will support more asset types in the future, including objects such -as pre-built packages, compliance/security evidence, or container images. - #### Permanent links to release assets > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27300) in GitLab 12.9. @@ -336,8 +333,8 @@ The four types of links are "Runbook," "Package," "Image," and "Other." > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. Each time a release is created, GitLab takes a snapshot of data that's related to it. -This data is saved in a JSON file and called *release evidence*. The feature currently -includes test artifacts and linked milestones (and will include issues) to facilitate +This data is saved in a JSON file and called *release evidence*. The feature +includes test artifacts and linked milestones to facilitate internal processes, like external audits. To access the release evidence, on the Releases page, click the link to the JSON file that's listed diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 75e1aea632f..f7da3629c23 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -34,10 +34,6 @@ Forking a project is, in most cases, a two-step process. The fork is created. The permissions you have in the namespace are the permissions you will have in the fork. WARNING: -In GitLab 12.6 and later, when project owners [reduce a project's visibility](../../../public_access/public_access.md#reducing-visibility), -it **removes the relationship** between a project and all its forks. - -WARNING: When a public project with the repository feature set to "Members only" is forked, the repository will be public in the fork. The owner of the fork will need to manually change the visibility. This is being diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index e1d84baec4d..c4f5d330f63 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -31,7 +31,7 @@ that you [connect with GitLab via SSH](../../../ssh/README.md). ## Files Use a repository to store your files in GitLab. In [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33806), -you'll see on the repository's file tree an icon next to the file name +you'll see on the repository's file tree an icon next to the filename according to its extension:  @@ -236,18 +236,24 @@ lock your files to prevent any conflicting changes. You can access your repositories via [repository API](../../../api/repositories.md). -## Clone in Apple Xcode +## Clone a repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0 +Learn how to [clone a repository through the command line](../../../gitlab-basics/start-using-git.md#clone-a-repository). + +Alternatively, clone directly into a code editor as documented below. + +### Clone to Apple Xcode + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0. Projects that contain a `.xcodeproj` or `.xcworkspace` directory can now be cloned -in Xcode using the new **Open in Xcode** button, located next to the Git URL +into Xcode using the new **Open in Xcode** button, located next to the Git URL used for cloning your project. The button is only shown on macOS. ## Download Source Code -> Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. -> Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. +> - Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. +> - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. The source code stored in a repository can be downloaded from the UI. By clicking the download icon, a dropdown will open with links to download the following: diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 96694a9e954..4a7f75ba1ac 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -8,19 +8,16 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.htm # Repository mirroring Repository mirroring allows for mirroring of repositories to and from external sources. It can be -used to mirror branches, tags, and commits between repositories. +used to mirror branches, tags, and commits between repositories. It is useful when you want to use +a repository outside of GitLab. A repository mirror at GitLab will be updated automatically. You can also manually trigger an update at most once every 5 minutes on GitLab.com with [the limit set by the administrator on self-managed instances](../../../administration/instance_limits.md#pull-mirroring-interval). -## Overview - -Repository mirroring is useful when you want to use a repository outside of GitLab. - There are two kinds of repository mirroring supported by GitLab: -- Push: for mirroring a GitLab repository to another location. -- Pull: for mirroring a repository from another location to GitLab. **(STARTER)** +- [Push](#pushing-to-a-remote-repository): for mirroring a GitLab repository to another location. **(CORE)** +- [Pull](#pulling-from-a-remote-repository): for mirroring a repository from another location to GitLab. **(STARTER)** When the mirror repository is updated, all new branches, tags, and commits will be visible in the project's activity feed. @@ -31,8 +28,7 @@ immediate update, unless: - The mirror is already being updated. - The [limit for pull mirroring interval seconds](../../../administration/instance_limits.md#pull-mirroring-interval) has not elapsed since its last update. -For security reasons, in [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/27166), -the URL to the original repository is only displayed to users with +For security reasons, the URL to the original repository is only displayed to users with Maintainer or Owner permissions to the mirrored project. ## Use cases @@ -62,7 +58,8 @@ For an existing project, you can set up push mirroring as follows: 1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. 1. Enter a repository URL. 1. Select **Push** from the **Mirror direction** dropdown. -1. Select an authentication method from the **Authentication method** dropdown, if necessary. +1. Select an authentication method from the **Authentication method** dropdown. + You can authenticate with either a password or an [SSH key](#ssh-authentication). 1. Check the **Only mirror protected branches** box, if necessary. 1. Check the **Keep divergent refs** box, if desired. 1. Click the **Mirror repository** button to save the configuration. @@ -88,17 +85,7 @@ section. You can also create and modify project push mirrors through the [remote mirrors API](../../../api/remote_mirrors.md). -### Push only protected branches **(CORE)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3350) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. -> - [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18715) in 10.8. - -You can choose to only push your protected branches from GitLab to your remote repository. - -To use this option, check the **Only mirror protected branches** box when creating a repository -mirror. - -### Keep divergent refs **(CORE)** +### Keep divergent refs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0. @@ -119,7 +106,7 @@ update. NOTE: After the mirror is created, this option can currently only be modified via the [API](../../../api/remote_mirrors.md). -## Setting up a push mirror from GitLab to GitHub **(CORE)** +### Setting up a push mirror from GitLab to GitHub To set up a mirror from GitLab to GitHub, you need to follow these steps: @@ -132,7 +119,7 @@ The mirrored repository will be listed. For example, `https://*****:*****@github The repository will push soon. To force a push, click the **Update now** (**{retry}**) button. -## Setting up a push mirror from GitLab to AWS CodeCommit +### Setting up a push mirror from GitLab to AWS CodeCommit AWS CodeCommit push mirroring is currently the best way to connect GitLab repositories to AWS CodePipeline, as GitLab is not yet supported as one of their Source Code Management (SCM) providers. @@ -210,7 +197,7 @@ To test mirroring by forcing a push, click the half-circle arrows button (hover If **Last successful update** shows a date, you have configured mirroring correctly. If it is not working correctly a red `error` tag appears and shows the error message as hover text. -## Setting up a push mirror to another GitLab instance with 2FA activated +### Setting up a push mirror to another GitLab instance with 2FA activated 1. On the destination GitLab instance, create a [personal access token](../../profile/personal_access_tokens.md) with `write_repository` scope. 1. On the source GitLab instance: @@ -249,8 +236,8 @@ To configure mirror pulling for an existing project:  Because GitLab is now set to pull changes from the upstream repository, you should not push commits -directly to the repository on GitLab. Instead, any commits should be pushed to the upstream repository. -Changes pushed to the upstream repository will be pulled into the GitLab repository, either: +directly to the repository on GitLab. Instead, any commits should be pushed to the remote repository. +Changes pushed to the remote repository will be pulled into the GitLab repository, either: - Automatically within a certain period of time. - When a [forced update](#forcing-an-update) is initiated. @@ -275,10 +262,62 @@ Repository mirrors are updated as Sidekiq becomes available to process them. If - Fails (for example, a branch diverged from upstream), it will be attempted again later. Mirrors can fail up to 14 times before they will not be enqueued for update again. -### SSH authentication +### Overwrite diverged branches **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4559) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. + +You can choose to always update your local branches with remote versions, even if they have +diverged from the remote. + +WARNING: +For mirrored branches, enabling this option results in the loss of local changes. + +To use this option, check the **Overwrite diverged branches** box when creating a repository mirror. + +### Trigger pipelines for mirror updates **(STARTER)** + +If this option is enabled, pipelines will be triggered when branches or tags are +updated from the remote repository. Depending on the activity of the remote +repository, this may greatly increase the load on your CI runners. Only enable +this if you know they can handle the load. CI will run using the credentials +assigned when you set up pull mirroring. + +### Hard failure **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3117) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. + +Once the mirroring process is unsuccessfully retried 14 times in a row, it will get marked as hard +failed. This will become visible in either the: + +- Project's main dashboard. +- Pull mirror settings page. + +When a project is hard failed, it will no longer get picked up for mirroring. +You can resume the project mirroring again by [forcing an update](#forcing-an-update). + +### Trigger an update using the API **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. + +Pull mirroring uses polling to detect new branches and commits added upstream, often minutes +afterwards. If you notify GitLab by [API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project), +updates will be pulled immediately. + +For more information, see [Start the pull mirroring process for a Project](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project). + +## Mirror only protected branches **(STARTER)** + +Based on the mirror direction that you choose, you can opt to mirror only the +[protected branches](../protected_branches.md) from/to your remote repository. +For pull mirroring, non-protected branches are not mirrored and can diverge. + +To use this option, check the **Only mirror protected branches** box when +creating a repository mirror. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2551) for Pull mirroring in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) for Push mirroring in [GitLab Core](https://about.gitlab.com/pricing/) 11.6 +## SSH authentication + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2551) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5 for Pull mirroring. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in [GitLab Core](https://about.gitlab.com/pricing/) 11.6 for Push mirroring. SSH authentication is mutual: @@ -367,50 +406,6 @@ NOTE: The generated keys are stored in the GitLab database, not in the filesystem. Therefore, SSH public key authentication for mirrors cannot be used in a pre-receive hook. -### Overwrite diverged branches **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4559) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. - -You can choose to always update your local branches with remote versions, even if they have -diverged from the remote. - -WARNING: -For mirrored branches, enabling this option results in the loss of local changes. - -To use this option, check the **Overwrite diverged branches** box when creating a repository mirror. - -### Only mirror protected branches **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3326) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. - -You can choose to pull mirror only the protected branches from your remote repository to GitLab. -Non-protected branches are not mirrored and can diverge. - -To use this option, check the **Only mirror protected branches** box when creating a repository mirror. - -### Hard failure **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3117) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. - -Once the mirroring process is unsuccessfully retried 14 times in a row, it will get marked as hard -failed. This will become visible in either the: - -- Project's main dashboard. -- Pull mirror settings page. - -When a project is hard failed, it will no longer get picked up for mirroring. A user can resume the -project mirroring again by [Forcing an update](#forcing-an-update). - -### Trigger update using API **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. - -Pull mirroring uses polling to detect new branches and commits added upstream, often minutes -afterwards. If you notify GitLab by [API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project), -updates will be pulled immediately. - -For more information, see [Start the pull mirroring process for a Project](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project). - ## Forcing an update **(CORE)** While mirrors are scheduled to update automatically, you can always force an update by using the @@ -429,10 +424,7 @@ bidirectional mirroring, you should prepare for the likely conflicts by deciding them and how they will be resolved. Rewriting any mirrored commit on either remote will cause conflicts and mirroring to fail. This can -be prevented by: - -- [Pulling only protected branches](#only-mirror-protected-branches). -- [Pushing only protected branches](#push-only-protected-branches). +be prevented by [mirroring only protected branches](#mirror-only-protected-branches). You should [protect the branches](../protected_branches.md) you wish to mirror on both remotes to prevent conflicts caused by rewriting history. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 24bfeee5e7f..b9477da3937 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -19,7 +19,7 @@ From a project's files page, click the '+' button to the right of the branch sel Choose **New file** from the dropdown.  -Enter a file name in the **Filename** box. Then, add file content in the editor +Enter a filename in the **Filename** box. Then, add file content in the editor area. Add a descriptive commit message and choose a branch. The branch field will default to the branch you were viewing in the file browser. If you enter a new branch name, a checkbox will appear, allowing you to start a new merge diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 9d75c4ab071..c99b0d91523 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -34,7 +34,7 @@ Users with Reporter or higher [permissions](../../permissions.md) can create req To create a requirement: -1. From your project page, go to **Requirements**. +1. In a project, go to **Requirements**. 1. Select **New requirement**. 1. Enter a title and description and select **Create requirement**. @@ -200,10 +200,10 @@ requirements_confirmation: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/246857) in GitLab 13.7. -You can import requirements to a project by uploading a CSV file with the columns -`title` and `description`. +You can import requirements to a project by uploading a [CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) +with the columns `title` and `description`. -The user uploading the CSV file will be set as the author of the imported requirements. +After the import, the user uploading the CSV file is set as the author of the imported requirements. Users with Reporter or higher [permissions](../../permissions.md) can import requirements. @@ -213,20 +213,20 @@ Before you import your file: - Consider importing a test file containing only a few requirements. There is no way to undo a large import without using the GitLab API. -- Ensure your CSV file meets the [file format](#csv-file-format) requirements. +- Ensure your CSV file meets the [file format](#imported-csv-file-format) requirements. To import requirements: -1. Navigate to a project's Requirements page. - - If the project already has existing requirements, click the import icon (**{import}**) at the +1. In a project, go to **Requirements**. + - If the project already has existing requirements, select the import icon (**{import}**) in the top right. - - For a project without any requirements, click **Import CSV** in the middle of the page. -1. Select the file and click **Import requirements**. + - For a project without any requirements, select **Import CSV** in the middle of the page. +1. Select the file and select **Import requirements**. The file is processed in the background and a notification email is sent to you after the import is complete. -### CSV file format +### Imported CSV file format When importing requirements from a CSV file, it must be formatted in a certain way: @@ -257,3 +257,37 @@ Another Title,"A description, with a comma" The limit depends on the configuration value of Max Attachment Size for the GitLab instance. For GitLab.com, it is set to 10 MB. + +## Export requirements to a CSV file + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290813) in GitLab 13.8. + +You can export GitLab requirements to a +[CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) sent to your default notification +email as an attachment. + +By exporting requirements, you and your team can import them into another tool or share them with +your customers. Exporting requirements can aid collaboration with higher-level systems, as well as +audit and regulatory compliance tasks. + +Users with Reporter or higher [permissions](../../permissions.md) can export requirements. + +To export requirements: + +1. In a project, go to **Requirements**. +1. Select the **Export as CSV** icon (**{export}**) in the top right. A confirmation modal appears. +1. Select **Export requirements**. The exported CSV file is sent to the email address associated with your user. + +### Exported CSV file format + +You can preview the exported CSV file in a spreadsheet editor, such as Microsoft Excel, +OpenOffice Calc, or Google Sheets. + +The exported CSV file contains the following columns: + +- Requirement ID +- Title +- Description +- Author Username +- Latest Test Report State +- Latest Test Report Created At (UTC) diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 4f3ca12c582..76156690fe7 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -10,32 +10,38 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/214839) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215364) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2. -Service Desk is a module that allows your team to connect directly -with any external party through email right inside of GitLab; no external tools required. -An ongoing conversation right where your software is built ensures that user feedback ends -up directly where it's needed, helping you build the right features to solve your users' -real problems. +Service Desk is a module that allows your team to connect +with any external party through email, without any external tools. +An ongoing conversation in the same place as where your software +is built ensures user feedback ends up where it's needed. -With Service Desk, you can provide efficient email support to your customers, who can now -email you bug reports, feature requests, or general feedback that will all end up in your -GitLab project as new issues. In turn, your team can respond straight from the project. +With Service Desk, you can provide efficient email support to your customers. They can +email you bug reports, feature requests, or general feedback. They all end up in your +GitLab project as new issues. In turn, your team can respond directly from the project. As Service Desk is built right into GitLab itself, the complexity and inefficiencies -of multiple tools and external integrations are eliminated, significantly shortening +of multiple tools and external integrations are eliminated. This significantly shortens the cycle time from feedback to software update. For an overview, check the video demonstration on [GitLab Service Desk](https://about.gitlab.com/blog/2017/05/09/demo-service-desk/). -## Use cases +## How it works + +GitLab Service Desk enables people to create issues in your +GitLab instance without needing their own user account. + +It provides a unique email address for end users to create issues in a project. +Follow-up notes can be sent either through the GitLab interface or by email. End +users only see the thread through email. For instance, let's assume you develop a game for iOS or Android. The codebase is hosted in your GitLab instance, built and deployed with GitLab CI/CD. -Here's how Service Desk will work for you: +Here's how Service Desk works for you: 1. You provide a project-specific email address to your paying customers, who can email you directly - from within the app. + from the application. 1. Each email they send creates an issue in the appropriate project. 1. Your team members navigate to the Service Desk issue tracker, where they can see new support requests and respond inside associated issues. @@ -43,61 +49,54 @@ Here's how Service Desk will work for you: 1. Your team starts working on implementing code to solve your customer's problem. 1. When your team finishes the implementation, whereupon the merge request is merged and the issue is closed automatically. -1. The customer will have been attended successfully via email, without having real access to your +1. The customer's requests are handled through email, without ever having access to your GitLab instance. 1. Your team saved time by not having to leave GitLab (or setup any integrations) to follow up with your customer. -## How it works - -GitLab Service Desk is a simple way to allow people to create issues in your -GitLab instance without needing their own user account. - -It provides a unique email address for end users to create issues in a project, -and replies can be sent either through the GitLab interface or by email. End -users will only see the thread through email. - ## Configuring Service Desk NOTE: Service Desk is enabled on GitLab.com. You can skip step 1 below; you only need to enable it per project. -If you have project maintainer access you have the option to set up Service Desk. -Follow these steps to do so: +If you have project maintainer access you have the option to set up Service Desk. Follow these steps: 1. [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. - - We recommend using [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), - but in GitLab 11.7 and later you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). + We recommend using [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), + but in GitLab 11.7 and later you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). 1. Navigate to your project's **Settings > General** and locate the **Service Desk** section. 1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues - to the project. These issues will be [confidential](issues/confidential_issues.md), so they will - only be visible to project members. Note that in GitLab 11.7, we updated the generated email + to the project. These issues are [confidential](issues/confidential_issues.md), so they are + only visible to project members. Note that in GitLab 11.7, we updated the generated email address's format. The older format is still supported, however, allowing existing aliases or contacts to continue working. WARNING: - This email address can be used by anyone to create an issue on this project, whether or not they - have access to your GitLab instance. We recommend **putting this behind an alias** so it can be - changed if needed, and **[enabling Akismet](../../integration/akismet.md)** on your GitLab + This email address can be used by anyone to create an issue on this project, regardless + of their access level to your GitLab instance. We recommend **putting this behind an alias** so it can be + changed if needed. We also recommend **[enabling Akismet](../../integration/akismet.md)** on your GitLab instance to add spam checking to this service. Unblocked email spam would result in many spam issues being created. If you have [templates](description_templates.md) in your repository, you can optionally select one from the selector menu to append it to all Service Desk issues. -  - -Service Desk is now enabled for this project! You should be able to access it from your project -navigation's **Issues** menu. +Service Desk is now enabled for this project! You should be able to access it from your project's +**Issues** menu.  ### Using customized email templates - > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/214839) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215364) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2. + +An email is sent to the author when: -When a user submits a new issue using Service Desk, or when a new note is created on a Service Desk issue, an email is sent to the author. +- A user submits a new issue using Service Desk. +- A new note is created on a Service Desk issue. The body of these email messages can be customized by using templates. To create a new customized template, create a new Markdown (`.md`) file inside the `.gitlab/service_desk_templates/` @@ -106,39 +105,46 @@ directory in your repository. Commit and push to your default branch. #### Thank you email The **Thank you email** is the email sent to a user after they submit an issue. -The file name of the template has to be `thank_you.md`. -You can use `%{ISSUE_ID}` placeholder which will be replaced by an issue IID in the email and -`%{ISSUE_PATH}` placeholder which will be replaced by project path and the issue IID. +The filename of the template has to be `thank_you.md`. +There are a few placeholders you can use which are automatically replaced in the email: + +- `%{ISSUE_ID}`: issue IID +- `%{ISSUE_PATH}`: project path appended with the issue IID + As the Service Desk issues are created as confidential (only project members can see them) the response email does not provide the issue link. #### New note email -The **New note email** is the email sent to a user when the issue they submitted has a new comment. -The file name of the template has to be `new_note.md`. -You can use `%{ISSUE_ID}` placeholder which will be replaced by an issue IID -in the email, `%{ISSUE_PATH}` placeholder which will be replaced by - project path and the issue IID and `%{NOTE_TEXT}` placeholder which will be replaced by the note text. +When a user-submitted issue receives a new comment, GitLab sends a **New note email** +to the user. The filename of this template must be `new_note.md`, and you can +use these placeholders in the email: + +- `%{ISSUE_ID}`: issue IID +- `%{ISSUE_PATH}`: project path appended with the issue IID +- `%{NOTE_TEXT}`: note text ### Using custom email display name > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7529) in GitLab 12.8. -You can customize the email display name. Emails sent from Service Desk will have +You can customize the email display name. Emails sent from Service Desk have this name in the `From` header. The default display name is `GitLab Support Bot`. -### Using custom email address **(CORE ONLY)** +To edit the custom email display name: + +1. In a project, go to **Settings > General > Service Desk**. +1. Enter a new name in **Email display name**. +1. Select **Save Changes**. + +### Using custom email address > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. -> - It was [deployed behind a feature flag](../feature_flags.md), disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) on GitLab 13.7. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-custom-email-address). **(CORE ONLY)** - -If the `service_desk_email` feature flag is enabled in your configuration, -then it's possible to create Service Desk issues by sending emails to the -custom Service Desk email address, which should have the following format: +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. + +If the `service_desk_email` is configured, then you can create Service Desk +issues by sending emails to the Service Desk email address. The default +address has the following format: `project_contact+%{key}@example.com`. The `%{key}` part is used to find the project where the issue should be created. The @@ -148,53 +154,57 @@ The `%{key}` part is used to find the project where the issue should be created. You can set the project name suffix in your project's Service Desk settings. It can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). - +NOTE: +The `service_desk_email` and `incoming_email` configurations should +always use separate mailboxes. This is important, because emails picked from +`service_desk_email` mailbox are processed by a different worker and it would +not recognize `incoming_email` emails. -You can add the following snippets to your configuration. +To configure a custom email address for Service Desk, add the following snippets to your configuration file: -Example for installations from source: +- Example for installations from source: -```yaml -service_desk_email: - enabled: true - address: "project_contact+%{key}@example.com" - user: "project_support@example.com" - password: "[REDACTED]" - host: "imap.gmail.com" - port: 993 - ssl: true - start_tls: false - log_path: "log/mailroom.log" - mailbox: "inbox" - idle_timeout: 60 - expunge_deleted: true -``` + ```yaml + service_desk_email: + enabled: true + address: "project_contact+%{key}@example.com" + user: "project_support@example.com" + password: "[REDACTED]" + host: "imap.gmail.com" + port: 993 + ssl: true + start_tls: false + log_path: "log/mailroom.log" + mailbox: "inbox" + idle_timeout: 60 + expunge_deleted: true + ``` -Example for Omnibus GitLab installations: +- Example for Omnibus GitLab installations: -```ruby -gitlab_rails['service_desk_email_enabled'] = true + ```ruby + gitlab_rails['service_desk_email_enabled'] = true -gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" -gitlab_rails['service_desk_email_email'] = "project_support@gmail.com" + gitlab_rails['service_desk_email_email'] = "project_support@gmail.com" -gitlab_rails['service_desk_email_password'] = "[REDACTED]" + gitlab_rails['service_desk_email_password'] = "[REDACTED]" -gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" -gitlab_rails['service_desk_email_idle_timeout'] = 60 + gitlab_rails['service_desk_email_idle_timeout'] = 60 -gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" -gitlab_rails['service_desk_email_host'] = "imap.gmail.com" + gitlab_rails['service_desk_email_host'] = "imap.gmail.com" -gitlab_rails['service_desk_email_port'] = 993 + gitlab_rails['service_desk_email_port'] = 993 -gitlab_rails['service_desk_email_ssl'] = true + gitlab_rails['service_desk_email_ssl'] = true -gitlab_rails['service_desk_email_start_tls'] = false -``` + gitlab_rails['service_desk_email_start_tls'] = false + ``` In this case, suppose the `mygroup/myproject` project Service Desk settings has the project name suffix set to `support`, and a user sends an email to `project_contact+mygroup-myproject-support@example.com`. @@ -203,27 +213,10 @@ As a result, a new Service Desk issue is created from this email in the `mygroup The configuration options are the same as for configuring [incoming email](../../administration/incoming_email.md#set-it-up). -#### Disable custom email address **(CORE ONLY)** - -Service Desk custom email is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:service_desk_custom_address) -``` - -To disable it: - -```ruby -Feature.disable(:service_desk_custom_address) -``` - ## Using Service Desk +There are a few ways Service Desk can be used. + ### As an end user (issue creator) To create a Service Desk issue, an end user does not need to know anything about @@ -235,29 +228,30 @@ receive an email back confirming receipt: This also gives the end user an option to unsubscribe. If they don't choose to unsubscribe, then any new comments added to the issue -will be sent as emails: +are sent as emails:  -And any responses they send will be displayed in the issue itself. +Any responses they send via email are displayed in the issue itself. ### As a responder to the issue -For responders to the issue, everything works as usual. They will see a familiar looking -issue tracker, where they can see issues created via customer support requests and -filter and interact with them just like other GitLab issues. +For responders to the issue, everything works just like other GitLab issues. +GitLab displays a familiar-looking issue tracker where responders can see +issues created through customer support requests, and filter or interact with them.  -Messages from the end user will show as coming from the special Support Bot user, but apart from that, -you can read and write comments as you normally do: +Messages from the end user are shown as coming from the special +[Support Bot user](../../subscriptions/self_managed/index.md#billable-users). +You can read and write comments as you normally do in GitLab:  Note that: - The project's visibility (private, internal, public) does not affect Service Desk. -- The path to the project, including its group or namespace, will be shown on emails. +- The path to the project, including its group or namespace, are shown in emails. ### Support Bot user diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 53233cc347e..27727890383 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -179,7 +179,7 @@ If use of the `Internal` visibility level all imported projects are given the visibility of `Private`. NOTE: -The maximum import file size can be set by the Administrator, default is 50MB. +The maximum import file size can be set by the Administrator, default is `0` (unlimited). As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). ### Project import status diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 41f404de4f2..26ef5e2260a 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -52,10 +52,6 @@ If you set **Project Visibility** to public, you can limit access to some featur to **Only Project Members**. In addition, you can select the option to [Allow users to request access](../members/index.md#project-membership-and-requesting-access). -WARNING: -If you [reduce a project's visibility level](../../../public_access/public_access.md#reducing-visibility), -that action unlinks all forks of that project. - Use the switches to enable or disable the following features: | Option | More access limit options | Description | diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 494f0b725e3..39de9ab9ca2 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -38,8 +38,10 @@ For examples of how you can use a project access token to authenticate with the ## Project bot users -For each project access token created, a bot user will also be created and added to the project with -["Maintainer" level permissions](../../permissions.md#project-members-permissions). +Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users) and do not count as licensed seats. + +For each project access token created, a bot user is created and added to the project with +[Maintainer level permissions](../../permissions.md#project-members-permissions). For the bot: @@ -49,15 +51,15 @@ For the bot: API calls made with a project access token are associated with the corresponding bot user. -These users will appear in **Members** but can not be modified. -Furthermore, the bot user can not be added to any other project. +These bot users are included in a project's **Members** list but cannot be modified. Also, a bot +user cannot be added to any other project. - The username is set to `project_{project_id}_bot` for the first access token, such as `project_123_bot`. - The username is set to `project_{project_id}_bot{bot_count}` for further access tokens, such as `project_123_bot1`. -When the project access token is [revoked](#revoking-a-project-access-token) the bot user is then deleted and all records are moved to a system-wide user with the username "Ghost User". For more information, see [Associated Records](../../profile/account/delete_account.md#associated-records). - -Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users) and do not count as licensed seats. +When the project access token is [revoked](#revoking-a-project-access-token) the bot user is deleted +and all records are moved to a system-wide user with the username "Ghost User". For more +information, see [Associated Records](../../profile/account/delete_account.md#associated-records). ## Revoking a project access token @@ -72,7 +74,7 @@ the following table. | Scope | Description | | ------------------ | ----------- | -| `api` | Grants complete read/write access to the scoped project API, including the Package Registry](../../packages/package_registry/index.md). | +| `api` | Grants complete read/write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | | `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | | `read_registry` | Allows read-access (pull) to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | | `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 29b24028e48..af8e78afb28 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -33,8 +33,8 @@ start seeing results. ## Command palette You can see all available commands for manipulating editor content by pressing -the <kbd>F1</kbd> key when the editor is in focus. After that, -you'll see a complete list of available commands for +the <kbd>F1</kbd> key when the editor is in focus. After that, the editor displays +a complete list of available commands for manipulating editor content. The editor supports commands for multi-cursor editing, code block folding, commenting, searching and replacing, navigating editor warnings and suggestions, and more. @@ -47,7 +47,7 @@ the command without having to select it in the command palette. ## Syntax highlighting -As expected from an IDE, syntax highlighting for many languages within +As expected from an IDE, syntax highlighting for many languages in the Web IDE makes your direct editing even easier. The Web IDE currently provides: @@ -78,7 +78,7 @@ All the themes GitLab supports for syntax highlighting are added to the Web IDE' You can pick a theme from your [profile preferences](../../profile/preferences.md). The themes are available only in the Web IDE file editor, except for the [dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/209808) and -the [solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228), +the [Solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228), which apply to the entire Web IDE screen. | Solarized Light Theme | Solarized Dark Theme | Dark Theme | @@ -144,12 +144,13 @@ schemas: Each schema entry supports two properties: -- `uri`: please provide an absolute URL for the schema definition file here. The schema from this URL -is loaded when a matching file is open. -- `match`: a list of matching paths or glob expressions. If a schema matches a particular path pattern, -it will be applied to that file. Please enclose the pattern in quotes if it begins with an asterisk (`*`), -it's be applied to that file. If a pattern begins with an asterisk (`*`), enclose it in quotation -marks. Otherwise, the configuration file is not valid YAML. +- `uri`: please provide an absolute URL for the schema definition file here. + The schema from this URL is loaded when a matching file is open. +- `match`: a list of matching paths or glob expressions. If a schema matches a + particular path pattern, it is applied to that file. Please enclose the pattern + in quotes if it begins with an asterisk (`*`), it's be applied to that file. + If a pattern begins with an asterisk (`*`), enclose it in quotation marks. + Otherwise, the configuration file is not valid YAML. ## Configure the Web IDE @@ -180,7 +181,7 @@ The Web IDE currently supports the following `.editorconfig` settings: After making your changes, click the **Commit** button on the bottom-left to review the list of changed files. -Once you have finalized your changes, you can add a commit message, commit the +After you have finalized your changes, you can add a commit message, commit the changes and directly create a merge request. In case you don't have write access to the selected branch, you see a warning, but can still create a new branch and start a merge request. @@ -268,7 +269,7 @@ GitLab.com  -Once you have done that, you can preview projects with a `package.json` file and +After you have done that, you can preview projects with a `package.json` file and a `main` entry point inside the Web IDE. An example `package.json` is shown below. @@ -325,7 +326,7 @@ In order to enable the Web IDE terminals you need to create the file file is fairly similar to the [CI configuration file](../../../ci/yaml/README.md) syntax but with some restrictions: -- No global blocks can be defined (i.e., `before_script` or `after_script`) +- No global blocks (such as `before_script` or `after_script`) can be defined. - Only one job named `terminal` can be added to this file. - Only the keywords `image`, `services`, `tags`, `before_script`, `script`, and `variables` are allowed to be used to configure the job. @@ -350,7 +351,7 @@ terminal: NODE_ENV: "test" ``` -Once the terminal has started, the console is displayed and we could access +After the terminal has started, the console is displayed and we could access the project repository files. **Important**. The terminal job is branch dependent. This means that the @@ -364,7 +365,7 @@ If there is no configuration file in a branch, an error message is shown. If Interactive Terminals are available for the current user, the **Terminal** button is visible in the right sidebar of the Web IDE. Click this button to open or close the terminal tab. -Once open, the tab shows the **Start Web Terminal** button. This button may +After opening, the tab shows the **Start Web Terminal** button. This button may be disabled if the environment is not configured correctly. If so, a status message describes the issue. Here are some reasons why **Start Web Terminal** may be disabled: @@ -378,7 +379,7 @@ can be closed and reopened and the state of the terminal is not affected. When the terminal is started and is successfully connected to the runner, then the runner's shell prompt appears in the terminal. From here, you can enter -commands executed within the runner's environment. This is similar +commands executed in the runner's environment. This is similar to running commands in a local terminal or through SSH. While the terminal is running, it can be stopped by clicking **Stop Terminal**. @@ -426,7 +427,7 @@ terminal: [predefined environment variable](../../../ci/variables/predefined_variables.md) for GitLab Runners. This is where your project's repository resides. -Once you have configured the web terminal for file syncing, then when the web +After you have configured the web terminal for file syncing, then when the web terminal is started, a **Terminal** status is visible in the status bar.  @@ -434,7 +435,7 @@ terminal is started, a **Terminal** status is visible in the status bar. Changes made to your files via the Web IDE sync to the running terminal when: -- <kbd>Ctrl</kbd> + <kbd>S</kbd> (or <kbd>Cmd</kbd> + <kbd>S</kbd> on Mac) +- <kbd>Control</kbd> + <kbd>S</kbd> (or <kbd>Command</kbd> + <kbd>S</kbd> on Mac) is pressed while editing a file. - Anything outside the file editor is clicked after editing a file. - A file or folder is created, deleted, or renamed. @@ -446,7 +447,7 @@ The Web IDE has a few limitations: - Interactive Terminals is in a beta phase and continues to be improved in upcoming releases. In the meantime, please note that the user is limited to having only one active terminal at a time. -- LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository will be overwritten with the modified LFS file content. +- LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository is overwritten with the modified LFS file content. ### Troubleshooting diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 7802f2ba95e..779179a6665 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -204,13 +204,11 @@ otherwise they will not display when pushed to GitLab: ## Customizing sidebar -On the project's Wiki page, there is a right side navigation that renders the full Wiki pages list by default, with hierarchy. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by clicking the **Edit sidebar** button. -To customize the sidebar, you can create a file named `_sidebar` to fully replace the default navigation. +To customize the Wiki's navigation sidebar, you need Developer permissions to the project. -WARNING: -Unless you link the `_sidebar` file from your custom nav, to edit it you'll have to access it directly -from the browser's address bar by typing: `https://gitlab.com/<namespace>/<project_name>/-/wikis/_sidebar` (for self-managed GitLab instances, replace `gitlab.com` with your instance's URL). +On the top-right, click **Edit sidebar** and make your changes. This creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation. Example for `_sidebar` (using Markdown format): diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index fe2371947b4..e3501be8e8e 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -52,14 +52,17 @@ The Advanced Search Syntax also supports the use of filters. The available filte - blob: Filters by Git `object ID`. Exact match only. To use them, add them to your keyword in the format `<filter_name>:<value>` without -any spaces between the colon (`:`) and the value. A keyword or an asterisk (`*`) is required for filter searches and has to be added in front of the filter separated by a space. +any spaces between the colon (`:`) and the value. When no keyword is provided, an asterisk (`*`) will be used as the keyword. Examples: - Finding a file with any content named `search_results.rb`: [`* filename:search_results.rb`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=*+filename%3Asearch_results.rb&group_id=9970&project_id=278964) -- Finding a file named `found_blob_spec.rb` with the text `CHANGELOG` inside of it: [`CHANGELOG filename:found_blob_spec.rb](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=CHANGELOG+filename%3Afound_blob_spec.rb&group_id=9970&project_id=278964) +- The leading asterisk (`*`) can be ignored in the case above: [`filename:search_results.rb`](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=filename%3Asearch_results.rb) +- Finding a file named `found_blob_spec.rb` with the text `CHANGELOG` inside of it: [`CHANGELOG filename:found_blob_spec.rb`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=CHANGELOG+filename%3Afound_blob_spec.rb&group_id=9970&project_id=278964) - Finding the text `EpicLinks` inside files with the `.rb` extension: [`EpicLinks extension:rb`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=EpicLinks+extension%3Arb&group_id=9970&project_id=278964) +- Finding any file with the `.yaml` extension: [`extension:yaml`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=extension%3Ayaml&group_id=9970&project_id=278964) - Finding the text `Sidekiq` in a file, when that file is in a path that includes `elastic`: [`Sidekiq path:elastic`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=Sidekiq+path%3Aelastic&group_id=9970&project_id=278964) +- Finding any file in a path that includes `elasticsearch`: [`path:elasticsearch`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=path%3Aelasticsearch&group_id=9970&project_id=278964) - Finding the files represented by the Git object ID `998707b421c89bd9a3063333f9f728ef3e43d101`: [`* blob:998707b421c89bd9a3063333f9f728ef3e43d101`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=false&scope=blobs&repository_ref=&search=*+blob%3A998707b421c89bd9a3063333f9f728ef3e43d101&group_id=9970) - Syntax filters can be combined for complex filtering. Finding any file starting with `search` containing `eventHub` and with the `.js` extension: [`eventHub filename:search* extension:js`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=eventHub+filename%3Asearch*+extension%3Ajs&group_id=9970&project_id=278964) diff --git a/doc/user/search/img/project_search_general_settings_v13_8.png b/doc/user/search/img/project_search_general_settings_v13_8.png Binary files differnew file mode 100644 index 00000000000..08395e0d4f9 --- /dev/null +++ b/doc/user/search/img/project_search_general_settings_v13_8.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 8c3d941192c..d229c27b608 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -18,7 +18,7 @@ The number displayed on their right represents the number of issues and merge re  -When you click **Issues**, you'll see the opened issues assigned to you straight away: +When you click **Issues**, the opened issues assigned to you are shown straight away:  @@ -29,14 +29,18 @@ You can also filter the results using the search and filter field, as described ### Issues and MRs assigned to you or created by you -You'll also find shortcuts to issues and merge requests created by you or assigned to you +GitLab shows shortcuts to issues and merge requests created by you or assigned to you on the search field on the top-right of your screen:  ### Filtering issue and merge request lists -Follow these steps to filter the **Issues** and **Merge Requests** list pages within projects and +> - Filtering by Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +> - Filtering by child Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. +> - Filtering by Iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. + +Follow these steps to filter the **Issues** and **Merge Requests** list pages in projects and groups: 1. Click in the field **Search or filter results...**. @@ -44,15 +48,12 @@ groups: - Author - Assignee - [Milestone](../project/milestones/index.md) - - [Iteration](../group/iterations/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6) + - [Iteration](../group/iterations/index.md) - Release - [Label](../project/labels.md) - My-reaction - Confidential - - Epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in GitLab 12.9), - including [child epic](../group/epics/index.md#multi-level-child-epics) - ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in - [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0) + - [Epic and child Epic](../group/epics/index.md) (available only for the group the Epic was created, not for [higher group levels](https://gitlab.com/gitlab-org/gitlab/-/issues/233729)). - Search for this text 1. Select or type the operator to use for filtering the attribute. The following operators are available: @@ -73,7 +74,7 @@ Some filter fields like milestone and assignee, allow you to filter by **None**  -Selecting **None** returns results that have an empty value for that field. E.g.: no milestone, no assignee. +Selecting **None** returns results that have an empty value for that field. For example: no milestone, no assignee. Selecting **Any** does the opposite. It returns results that have a non-empty value for that field. @@ -82,11 +83,11 @@ Selecting **Any** does the opposite. It returns results that have a non-empty va You can filter issues and merge requests by specific terms included in titles or descriptions. - Syntax - - Searches look for all the words in a query, in any order. E.g.: searching - issues for `display bug` will return all issues matching both those words, in any order. + - Searches look for all the words in a query, in any order. For example: searching + issues for `display bug` returns all issues matching both those words, in any order. - To find the exact term, use double quotes: `"display bug"` - Limitation - - For performance reasons, terms shorter than 3 chars are ignored. E.g.: searching + - For performance reasons, terms shorter than 3 chars are ignored. For example: searching issues for `included in titles` is same as `included titles` - Search is limited to 4096 characters and 64 terms per query. @@ -118,6 +119,13 @@ the dropdown) **Approved-By** and select the user.  +### Filtering merge requests by reviewer **(CORE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47605) in GitLab 13.7. + +To filter review requested merge requests for a specific individual, you can type (or select from +the dropdown) **Reviewer** and select the user. + ### Filtering merge requests by environment or deployment date **(CORE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44041) in GitLab 13.6. @@ -149,7 +157,7 @@ relevant users or other attributes. For performance optimization, there is a requirement of a minimum of three characters to begin your search. For example, if you want to search for -issues that have the assignee "Simone Presley", you'll need to type at +issues that have the assignee "Simone Presley", you must type at least "Sim" before autocomplete gives any relevant results. ## Search history @@ -162,11 +170,11 @@ You can view recent searches by clicking on the little arrow-clock icon, which i Individual filters can be removed by clicking on the filter's (x) button or backspacing. The entire search filter can be cleared by clicking on the search box's (x) button or via <kbd>⌘</kbd> (Mac) + <kbd>⌫</kbd>. -To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>⌫</kbd> keyboard combination can be used. +To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Control</kbd> + <kbd>⌫</kbd> keyboard combination can be used. ## Filtering with multiple filters of the same type -Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the AND logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results will only include entries whereby the assignees are assigned to both Sam and Sarah are returned. +Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the AND logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results include only entries whereby the assignees are assigned to both Sam and Sarah are returned.  @@ -182,7 +190,7 @@ author, type, and action. Also, you can sort them by You can search through your projects from the left menu, by clicking the menu bar, then **Projects**. On the field **Filter by name**, type the project or group name you want to find, and GitLab -will filter them for you as you type. +filters them for you as you type. You can also look for the projects you [starred](../project/index.md#star-a-project) (**Starred projects**), and **Explore** all public and internal projects available in GitLab.com, from which you can filter by visibility, @@ -199,7 +207,7 @@ Similarly to [projects search](#projects), you can search through your groups fr the left menu, by clicking the menu bar, then **Groups**. On the field **Filter by name**, type the group name you want to find, and GitLab -will filter them for you as you type. +filters them for you as you type. You can also **Explore** all public and internal groups available in GitLab.com, and sort them by **Last created**, **Oldest created**, **Last updated**, or **Oldest updated**. @@ -211,15 +219,15 @@ You can also filter them by name (issue title), from the field **Filter by name* When you want to search for issues to add to lists present in your Issue Board, click the button **Add issues** on the top-right of your screen, opening a modal window from which -you'll be able to, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**, +you can, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**, and **Labels**, select multiple issues to add to a list of your choice:  ## Shortcut -You'll find a shortcut on the search field on the top-right of the project's dashboard to -quickly access issues and merge requests created or assigned to you within that project: +GitLab shows a shortcut on the search field on the top-right of the project's dashboard to +quickly access issues and merge requests created or assigned to you in that project:  @@ -234,12 +242,12 @@ You can also type in this search bar to see autocomplete suggestions for: - Recently viewed issues (try and type some word from the title of a recently viewed issue) - Recently viewed merge requests (try and type some word from the title of a recently viewed merge request) - Recently viewed epics (try and type some word from the title of a recently viewed epic) -- [GitLab Flavored Markdown](../markdown.md#special-gitlab-references) (GFM) for issues within a project (try and type a GFM reference for an issue) +- [GitLab Flavored Markdown](../markdown.md#special-gitlab-references) (GFM) for issues in a project (try and type a GFM reference for an issue) ## Basic search The Basic search in GitLab is a global search service that allows you to search -across the entire GitLab instance, within a group, or a single project. Basic search is +across the entire GitLab instance, in a group, or in a single project. Basic search is backed by the database and allows searching in: - Projects @@ -254,12 +262,12 @@ backed by the database and allows searching in: - Wiki (Project only) To start a search, type into the search bar on the top-right of the screen. You can always search -in all GitLab and may also see the options to search within a group or project if you are in the +in all GitLab and may also see the options to search in a group or project if you are in the group or project dashboard.  -Once the results are returned, you can modify the search, select a different type of data to +After the results are returned, you can modify the search, select a different type of data to search, or choose a specific group or project.  @@ -274,11 +282,11 @@ the search field on the top-right of your screen while the project page is open. ### SHA search -You can quickly access a commit from within the project dashboard by entering the SHA -into the search field on the top right of the screen. If a single result is found, you will be +You can quickly access a commit from the project dashboard by entering the SHA +into the search field on the top right of the screen. If a single result is found, you are redirected to the commit result and given the option to return to the search results page. - + ## Advanced Search **(STARTER)** @@ -292,3 +300,39 @@ GitLab instance. Use advanced queries for more targeted search results. [Learn how to use the Advanced Search Syntax.](advanced_search_syntax.md) + +## Search project settings + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292941) in GitLab 13.8. +> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-search-project-settings). **(CORE ONLY)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can search inside the project’s settings sections by entering a search +term in the search box located at the top of the page. The search results +appear highlighted in the sections that match the search term. + + + +### Enable or disable Search project settings **(CORE ONLY)** + +Search project settings is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:search_settings_in_page) +``` + +To disable it: + +```ruby +Feature.disable(:search_settings_in_page) +``` diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 33aa0bd253b..af499221da6 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -53,7 +53,7 @@ From there, add the **Title**, **Description**, and a **File** name with the appropriate extension (for example, `example.rb`, `index.html`). WARNING: -Make sure to add the file name to get code highlighting and to avoid this +Make sure to add the filename to get code highlighting and to avoid this [copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870). ## Versioned Snippets @@ -69,10 +69,10 @@ new commit to the master branch is recorded. Commit messages are automatically generated. The snippet's repository has only one branch (master) by default, deleting it or creating other branches is not supported. -Existing snippets will be automatically migrated in 13.0. Their current -content will be saved as the initial commit to the snippets' repository. +Existing snippets are automatically migrated in 13.0. Their current +content is saved as the initial commit to the snippets' repository. -### File names +### Filenames Snippets support syntax highlighting based on the filename and extension provided for them. While it is possible to submit a snippet @@ -86,10 +86,10 @@ number increases incrementally when more snippets without an attributed filename are added. When upgrading from an earlier version of GitLab to 13.0, existing snippets -without a supported filename will be renamed to a compatible format. For -example, if the snippet's filename is `http://a-weird-filename.me` it will -be changed to `http-a-weird-filename-me` to be included in the snippet's -repository. As snippets are stored by ID, changing their filenames will not break +without a supported filename are renamed to a compatible format. For +example, if the snippet's filename is `http://a-weird-filename.me` it is +changed to `http-a-weird-filename-me` to be included in the snippet's +repository. As snippets are stored by ID, changing their filenames breaks direct or embedded links to the snippet. ### Multiple files by Snippet @@ -105,8 +105,8 @@ to a certain context. For example: - A snippet with a `docker-compose.yml` file and its associated `.env` file. - A `gulpfile.js` file coupled with a `package.json` file, which together can be used to bootstrap a project and manage its dependencies. -Snippets support between 1 and 10 files. They can be managed via Git (since they're [versioned](#versioned-snippets) -by a Git repository), through the [Snippets API](../api/snippets.md), or within the GitLab UI. +Snippets support between 1 and 10 files. They can be managed via Git (because they're [versioned](#versioned-snippets) +by a Git repository), through the [Snippets API](../api/snippets.md), or in the GitLab UI.  @@ -122,7 +122,7 @@ To delete a file from your snippet through the GitLab UI: 1. Go to your snippet in the GitLab UI. 1. Click **Edit** in the top right. -1. Select **Delete file** alongside the file name of each file +1. Select **Delete file** alongside the filename of each file you wish to delete. 1. Click **Save changes**. @@ -139,7 +139,7 @@ master branch. ### Reduce snippets repository size -Since versioned Snippets are considered as part of the [namespace storage size](../user/admin_area/settings/account_and_limit_settings.md), +Because versioned Snippets are considered as part of the [namespace storage size](../user/admin_area/settings/account_and_limit_settings.md), it's recommended to keep snippets' repositories as compact as possible. For more information about tools to compact repositories, @@ -151,7 +151,7 @@ see the documentation on [reducing repository size](../user/project/repository/r - Creating or deleting branches is not supported. Only a default *master* branch is used. - Git tags are not supported in snippet repositories. - Snippets' repositories are limited to 10 files. Attempting to push more -than 10 files will result in an error. +than 10 files results in an error. - Revisions are not *yet* visible to the user on the GitLab UI, but it's planned to be added in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) for updates. @@ -187,9 +187,9 @@ facilitating the collaboration among users. You can download the raw content of a snippet. -By default snippets will be downloaded with Linux-style line endings (`LF`). If +By default snippets are downloaded with Linux-style line endings (`LF`). If you want to preserve the original line endings you need to add a parameter `line_ending=raw` -(e.g., `https://gitlab.com/snippets/SNIPPET_ID/raw?line_ending=raw`). In case a +(For example: `https://gitlab.com/snippets/SNIPPET_ID/raw?line_ending=raw`). In case a snippet was created using the GitLab web interface the original line ending is Windows-like (`CRLF`). ## Embedded snippets @@ -207,7 +207,7 @@ To embed a snippet, first make sure that: - In **Project > Settings > Permissions**, the snippets permissions are set to **Everyone with access** -Once the above conditions are met, the "Embed" section will appear in your +After the above conditions are met, the "Embed" section appears in your snippet where you can simply click on the "Copy" button. This copies a one-line script that you can add to any website or blog post. @@ -221,6 +221,6 @@ Here's how an embedded snippet looks like: <script src="https://gitlab.com/gitlab-org/gitlab-foss/snippets/1717978.js"></script> -Embedded snippets are displayed with a header that shows the file name if it's defined, +Embedded snippets are displayed with a header that shows the filename if it's defined, the snippet size, a link to GitLab, and the actual snippet content. Actions in the header allow users to see the snippet in raw format and download it. diff --git a/doc/user/todos.md b/doc/user/todos.md index 7d5a66a1632..27a849719c5 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -72,7 +72,7 @@ prevent data loss, in the case where a user's access is accidentally revoked. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7926) in GitLab 9.0. -If you're mentioned at the start of a line, the to-do item you receive is +If you're mentioned at the start of a line, the to-do item you receive is listed as *directly addressed*. For example, in the following comment: ```markdown diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 5f637c8d5cb..8662efc03a7 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -22,7 +22,6 @@ To help manage storage, a namespace's owner can view: - Total storage used in the namespace - Total storage used per project -- Breakdown of storage use per project, by storage type. To view storage usage, from the namespace's page go to **Settings > Usage Quotas** and select the **Storage** tab. The Usage Quotas statistics are updated every 90 minutes. |
