Add latest changes from gitlab-org/gitlab@master

7 files changed, 82 insertions, 38 deletions

diff --git a/doc/administration/docs_self_host.md b/doc/administration/docs_self_host.md
index 932ffb87288..a659508e37a 100644
--- a/doc/administration/docs_self_host.md
+++ b/doc/administration/docs_self_host.md
@@ -265,8 +265,5 @@ To upgrade to a later version [using your own web-server](#self-host-the-product
 
 If you self-host the product documentation:
 
-- The version dropdown list displays additional versions that don't exist. Selecting
-  these versions displays a `404 Not Found` page.
-- The search displays results from `docs.gitlab.com` and not the local site.
 - By default, the landing page redirects to the
   respective version (for example, `/14.5/`). This causes the landing page <https://docs.gitlab.com> to not be displayed.
diff --git a/doc/development/sec/security_report_ingestion_overview.md b/doc/development/sec/security_report_ingestion_overview.md
index f2b4f100c8b..a9afe26411b 100644
--- a/doc/development/sec/security_report_ingestion_overview.md
+++ b/doc/development/sec/security_report_ingestion_overview.md
@@ -7,15 +7,56 @@ type: concepts
 
 # Security report ingestion overview
 
-## Definitions
+WARNING:
+The `Vulnerability::Feedback` model is currently undergoing deprecation and should be actively avoided in all further development. It is currently maintained with feature parity to enable revert should any issues arise, but is intended to be removed in 16.0. Any interactions relating to the Feedback model are superseded by the `StateTransition`, `IssueLink`, and `MergeRequestLink` models. You can find out more on [in this epic](https://gitlab.com/groups/gitlab-org/-/epics/5629).
 
-- **Vulnerability Finding** – an instance of `Vulnerabilities::Finding` class. This class was previously called `Vulnerabilities::Occurrence`; after renaming the class, we kept the associated table name `vulnerability_occurrences` due to the effort involved in renaming large tables.
-- **Vulnerability** – an instance of `Vulnerability` class. They are created based on information available in `Vulnerabilities::Finding` class. Every `Vulnerability` **must have** a corresponding `Vulnerabilities::Finding` object to be valid, however this is not enforced at the database level.
-- **Security Finding** – an instance of `Security::Finding` class. They store **partial** finding data to improve performance of the pipeline security report. We are working on extending this class to store almost all required information so we can stop relying on job artifacts.
-- **Feedback** – an instance of `Vulnerabilities::Feedback` class. They are created to keep track of users' interactions with Vulnerability Findings before they are promoted to a Vulnerability. We are in the process of removing this model via [Deprecate and remove Vulnerabilities::Feedback epic](https://gitlab.com/groups/gitlab-org/-/epics/5629).
-- **Issue Link** – an instance of `Vulnerabilities::IssueLink` class. They are used to link `Vulnerability` objects to `Issue` objects.
+## Commonly used terms
 
-## Vulnerability creation from security reports
+### Feedback 
+
+An instance of `Vulnerabilities::Feedback` class. They are created to keep track of users' interactions with Vulnerability Findings before they are promoted to a Vulnerability. This model is deprecated and due to be removed by GitLab 16.0 as part of the [Deprecate and remove Vulnerabilities::Feedback epic](https://gitlab.com/groups/gitlab-org/-/epics/5629).
+
+### Issue Link
+
+An instance of `Vulnerabilities::IssueLink` class. They are used to link `Vulnerability` records to `Issue` records.
+
+### Merge Request Link
+
+An instance of `Vulnerabilities::MergeRequestLink` class. They are used to link `Vulnerability` records to `MergeRequest` records.
+
+### Security Finding
+
+An instance of `Security::Finding` class. These serve as a meta-data store of a specific vulnerability detected in a specific `Security::Scan`. They currently store **partial** finding data to improve performance of the pipeline security report. This class has been extended to store almost all required scan information so we can stop relying on job artifacts and is [due to be used in favor of `Vulnerability::Findings` soon.](https://gitlab.com/gitlab-org/gitlab/-/issues/393394)
+
+### Security Scan
+
+An instance of the `Security::Scan` class. Security scans are representative of a `Ci::Build` which output a `Job Artifact` which has been output as a security scan result, which GitLab acknowledges and ingests the findings of as `Security::Finding` records.
+
+### State Transition
+
+An instance of the `Vulnerabilities::StateTransition` class. This model represents a state change of a respecitve Vulnerability record, for example the dismissal of a vulnerability which has been determined to be safe.
+
+### Vulnerability
+
+An instance of `Vulnerability` class. A `Vulnerability` is representative of a `Vulnerability::Finding` which has been detected in the default branch of the project, or if the `present_on_default_branch` flag is false, is representative of a finding which has been interacted with in some way outside of the default branch, such as if it is dismissed (`State Transition`), or linked to an `Issue` or `Merge Request`. They are created based on information available in `Vulnerabilities::Finding` class. Every `Vulnerability` **must have** a corresponding `Vulnerabilities::Finding` object to be valid, however this is not enforced at the database level. 
+
+### Finding
+
+An instance of `Vulnerabilities::Finding` class. A `Vulnerability::Finding` is a database only representation of a security finding which has been merged into the default branch of a project, as the same `Vulnerability` may be present in multiple places within a project. This class was previously called `Vulnerabilities::Occurrence`; after renaming the class, we kept the associated table name `vulnerability_occurrences` due to the effort involved in renaming large tables.
+
+### Identifier
+
+An instance of the `Vulnerabilities::Identifier` class. Each vulnerability is given a unique identifier that can be derived from it's finding, enabling multiple Findings of the same `Vulnerability` to be correlated accordingly.
+
+### Vulnerability Read
+
+An instance of the `Vulnerabilities::Read` class. This is a denormalised record of `Vulnerability` and `Vulnerability::Finding` data to improve performance of filtered querying of vulnerability data to the front end.
+
+### Remediation
+
+An instance of the `Vulnerabilities::Remediation` class. A remediation is representative of a known solution to a detected `Vulnerability`. These enable GitLab to recommend a change to resolve a specific `Vulnerability`.
+
+## Vulnerability creation from Security Reports
 
 Assumptions:
 
@@ -24,23 +65,23 @@ Assumptions:
 - No Vulnerabilities are present in the database
 - All pipelines perform security scans
 
-1. Code is pushed to a branch that's **not** the default branch.
+### Scan runs in a pipeline for a non-default branch
+
+1. Code is pushed to the branch.
 1. GitLab CI runs a new pipeline for that branch.
 1. Pipeline status transitions to any of [`::Ci::Pipeline.completed_statuses`](https://gitlab.com/gitlab-org/gitlab/-/blob/354261b2fe4fc5b86d1408467beadd90e466ce0a/app/models/concerns/ci/has_status.rb#L12).
 1. `Security::StoreScansWorker` is called and it schedules `Security::StoreScansService`.
 1. `Security::StoreScansService` calls `Security::StoreGroupedScansService` and schedules `ScanSecurityReportSecretsWorker`.
 1. `Security::StoreGroupedScansService` calls `Security::StoreScanService`.
 1. `Security::StoreScanService` calls `Security::StoreFindingsService`.
-1. `ScanSecurityReportSecretsWorker` calls `Security::TokenRevocationService` to revoke any leaked keys.
-1. At this point we have `Security::Finding` objects **only**.
+1. `ScanSecurityReportSecretsWorker` calls `Security::TokenRevocationService` to automatically revoke any leaked keys that were detected.
+1. At this point we **only** have `Security::Finding` records as these findings are not present in the default branch of the project.
 
-At this point, the following things can happen to the `Security::Finding`:
+At this point, the following things can happen to the `Security::Finding` which would result in its promotion to a `Vulnerability::Finding` with a respective `Vulnerability` record:
 
-- Dismissal
-- Issue creation
-- Promotion to a Vulnerability
+### Scan runs in a pipeline for the default branch
 
-If the pipeline ran on the default branch then the following, additional steps are done:
+If the pipeline ran on the default branch then the following, then in addition to the steps in [#Scan-is-executed-again-a-non-default-branch], these additional steps are executed:
 
 1. `Security::StoreScansService` gets called and schedules `StoreSecurityReportsWorker`.
 1. `StoreSecurityReportsWorker` executes `Security::Ingestion::IngestReportsService`.
@@ -49,27 +90,28 @@ If the pipeline ran on the default branch then the following, additional steps a
 
 ### Dismissal
 
-If you select `Dismiss vulnerability`, a Feedback is created. You can also dismiss it with a comment.
+If you change the state of a vulnerability, such as selecting `Dismiss vulnerability` the following things currently happen:
 
-#### After Feedback removal
+- A `Feedback` record of `dismissal` type is created to record the current state. 
+- If they do not already exist, a `Vulnerability Finding` and a `Vulnerability` with `present_on_default_branch: false` attribute get created, to which a `State Transition` reflecting the state change is related. 
 
-If there is only a Security Finding, a Vulnerability Finding and a Vulnerability get created. At the same time we create a `Vulnerabilities::StateTransition` record to indicate the Vulnerability was dismissed.
+You can optionally add a comment to the state change which is recorded on both the `Feedback` and the `State Transition`.
 
-### Issue creation
+### Issue or Merge Request creation
 
-If you select `Create issue`, a Vulnerabilities::Feedback record is created as well. The Feedback has a different `feedback_type` and an `issue_id` that's not `NULL`.
+If you select `Create issue` or `Create merge request` the following things currently happen:
 
-NOTE:
-Vulnerabilities::Feedback are in the process of being [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/5629). This will later create a `Vulnerabilities::IssueLink` record.
+- A `Vulnerabilities::Feedback` record is created. The Feedback will have a `feedback_type` of `issue` or `merge request` and an `issue_id` or `merge_request_id` that's not `NULL` respective to the attachment.
+- If they do not already exist, a `Vulnerability Finding` and a `Vulnerability` with `present_on_default_branch: false` attribute get created, to which a `Issue Link` or `Merge Request Link` will be related respective to the action taken.
 
-#### After Feedback removal
+## Vulnerabilities in the Default Branch
 
-If there's only a Security Finding, a Vulnerability Finding and a Vulnerability gets created. At the same time, we create an Issue and a Issue Link.
+Security Findings detected in scan run on the default branch are saved as `Vulnerabilities` with the `present_on_default_branch: true` attribute and respective `Vulnerability Finding` records. `Vulnerability` records that already exist from interactions outside of the default branch will be updated to `present_on_default_branch: true`
 
-## Promotion to a Vulnerability
+`Vulnerabilities` which have already been interacted with will retain all existing `State Transitions`, `Merge Request Links` and `Issue Links`, as well as a corresponding `Vulnerability Feedback`.
 
-If the branch with a Security Finding gets merged into the default branch, all Security Findings get promoted into Vulnerabilities. Promotion is the process of creating Vulnerability Findings and Vulnerability records from those Security Findings.
+## Vulnerability Read Creation
 
-If there's a dismissal Feedback present for that Security Finding, the created Vulnerability is marked as dismissed.
+`Vulnerability::Read` records are created via postgres database trigger upon the creation of a `Vulnerability::Finding` record and as such are part of our ingestion process, though they have no impact on it bar it's denormalization performance benefits on the report pages.
 
-If there's an issue Feedback present for that Security Finding, we also create an Issue Link for that Vulnerability.
+This style of creation was intended to be fast and seamless, but has proven difficult to debug and maintain and may be [migrated to the application layer later](https://gitlab.com/gitlab-org/gitlab/-/issues/393912).
diff --git a/doc/security/email_verification.md b/doc/security/email_verification.md
index 7a2ad6d2f30..1072475680c 100644
--- a/doc/security/email_verification.md
+++ b/doc/security/email_verification.md
@@ -4,14 +4,14 @@ group: Anti-Abuse
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Email verification **(FREE)**
+# Account email verification **(FREE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86352) in GitLab 15.2 [with a flag](../administration/feature_flags.md) named `require_email_verification`. Disabled by default.
 
 FLAG:
 On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `require_email_verification`. On GitLab.com, this feature is not available.
 
-Email verification provides an additional layer of GitLab account security.
+Account email verification provides an additional layer of GitLab account security.
 When certain conditions are met, an account is locked. If your account is locked,
 you must verify your identity or reset your password to sign in to GitLab.
 
diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md
index c3f19c92f91..962f6f0fd61 100644
--- a/doc/security/user_email_confirmation.md
+++ b/doc/security/user_email_confirmation.md
@@ -5,7 +5,7 @@ group: Authentication and Authorization
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# User email confirmation at sign-up **(FREE SELF)**
+# Make new users confirm email **(FREE SELF)**
 
 GitLab can be configured to require confirmation of a user's email address when
 the user signs up. When this setting is enabled, the user is unable to sign in until
diff --git a/doc/user/analytics/dora_metrics.md b/doc/user/analytics/dora_metrics.md
index e7c5fba3a44..70ce005dfb9 100644
--- a/doc/user/analytics/dora_metrics.md
+++ b/doc/user/analytics/dora_metrics.md
@@ -154,6 +154,11 @@ These deployment records are not created for pull-based deployments, for example
 
 To track DORA metrics in these cases, you can [create a deployment record](../../api/deployments.md#create-a-deployment) using the Deployments API. See also the documentation page for [Track deployments of an external deployment tool](../../ci/environments/external_deployment_tools.md).
 
+### Measure DORA metrics with Jira
+
+- Deployment frequency and Lead time for changes are calculated based on GitLab CI/CD and Merge Requests (MRs), and do not require Jira data.
+- Time to restore service and Change failure rate require GitLab incidents for the calculation. For more information, see [Measure DORA Time to restore service and Change failure rate with external incidents](#measure-dora-time-to-restore-service-and-change-failure-rate-with-external-incidents).
+
 ### Measure DORA Time to restore service and Change failure rate with external incidents
 
 [Time to restore service](#time-to-restore-service) and [Change failure rate](#change-failure-rate)
diff --git a/doc/user/group/moderate_users.md b/doc/user/group/moderate_users.md
index 9f2e87473ff..4ec86893524 100644
--- a/doc/user/group/moderate_users.md
+++ b/doc/user/group/moderate_users.md
@@ -4,7 +4,7 @@ group: Anti-Abuse
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Moderate users  **(FREE SELF)**
+# Moderate users  **(FREE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/155) in GitLab 15.8.
 
diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md
index f66ff0e599d..f90b81b06cb 100644
--- a/doc/user/project/code_owners.md
+++ b/doc/user/project/code_owners.md
@@ -44,14 +44,14 @@ For example:
 
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
 
-## View a file's Code Owner
+## View Code Owners of a file or directory
 
-To view the Code Owners for a file:
+To view the Code Owners of a file or directory:
 
 1. On the top bar, select **Main menu > Projects** and find your project.
 1. On the left sidebar, select **Repository > Files**.
 1. Go to the file or directory you want to see the Code Owners for.
-1. Optional. Select your desired branch.
+1. Optional. Select a branch or tag.
 
 GitLab shows the Code Owners at the top of the page.