Add latest changes from gitlab-org/gitlab@master

6 files changed, 168 insertions, 21 deletions

diff --git a/doc/administration/settings/scim_setup.md b/doc/administration/settings/scim_setup.md
index 52061150fa7..2e1b40d58b8 100644
--- a/doc/administration/settings/scim_setup.md
+++ b/doc/administration/settings/scim_setup.md
@@ -33,6 +33,51 @@ To configure GitLab SCIM:
     - Token from the **Your SCIM token** field.
     - URL from the **SCIM API endpoint URL** field.
 
+## Configure an identity provider
+
+You can configure the following as an identity provider:
+
+- [Okta](#configure-okta).
+
+NOTE:
+Other identity providers can work with GitLab but they have not been tested and are not supported. You should contact the provider for support. GitLab support can assist by reviewing related log entries.
+
+### Configure Okta
+
+The SAML application created during [single sign-on](index.md) set up for Okta must be set up for SCIM.
+
+Prerequisites:
+
+- You must use the [Okta Lifecycle Management](https://www.okta.com/products/lifecycle-management/) product. This
+  product tier is required to use SCIM on Okta.
+- [GitLab is configured](#configure-gitlab) for SCIM.
+- The SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/) set up as
+  described in the [Okta setup notes](../../integration/saml.md#set-up-okta).
+- Your Okta SAML setup matches the [configuration steps](index.md), especially the NameID configuration.
+
+To configure Okta for SCIM:
+
+1. Sign in to Okta.
+1. In the upper-right corner, select **Admin**. The button is not visible from the Admin Area.
+1. In the **Application** tab, select **Browse App Catalog**.
+1. Find and select the **GitLab** application.
+1. On the GitLab application overview page, select **Add Integration**.
+1. Under **Application Visibility**, select both checkboxes. The GitLab application does not support SAML
+   authentication so the icon should not be shown to users.
+1. Select **Done** to finish adding the application.
+1. In the **Provisioning** tab, select **Configure API integration**.
+1. Select **Enable API integration**.
+   - For **Base URL**, paste the URL you copied from **SCIM API endpoint URL** on the GitLab SCIM configuration page.
+   - For **API Token**, paste the SCIM token you copied from **Your SCIM token** on the GitLab SCIM
+     configuration page.
+1. To verify the configuration, select **Test API Credentials**.
+1. Select **Save**.
+1. After saving the API integration details, new settings tabs appear on the left. Select **To App**.
+1. Select **Edit**.
+1. Select the **Enable** checkbox for both **Create Users** and **Deactivate Users**.
+1. Select **Save**.
+1. Assign users in the **Assignments** tab. Assigned users are created and managed in your GitLab group.
+
 ## Remove access
 
 Removing or deactivating a user on the identity provider blocks the user on
diff --git a/doc/api/integrations.md b/doc/api/integrations.md
index 0abf155133e..92cbaaab0b5 100644
--- a/doc/api/integrations.md
+++ b/doc/api/integrations.md
@@ -232,9 +232,9 @@ Parameters:
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `new_issue_url` | string | true |  New issue URL. |
-| `issues_url` | string | true | Issue URL. |
-| `project_url` | string | true | Project URL. |
+| `new_issue_url` | string | true |  URL of the new issue. |
+| `issues_url` | string | true | URL of the issue. |
+| `project_url` | string | true | URL of the project. |
 
 ### Disable Bugzilla
 
@@ -339,8 +339,8 @@ Parameters:
 
 | Parameter     | Type   | Required | Description    |
 | ------------- | ------ | -------- | -------------- |
-| `issues_url`  | string | true     | Issue URL.     |
-| `project_url` | string | true     | Project URL.   |
+| `issues_url`  | string | true     | URL of the issue.     |
+| `project_url` | string | true     | URL of the project.   |
 
 ### Disable ClickUp
 
@@ -404,9 +404,9 @@ Parameters:
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `new_issue_url` | string | true |  New issue URL. |
-| `issues_url` | string | true | Issue URL. |
-| `project_url` | string | true | Project URL. |
+| `new_issue_url` | string | true |  URL of the new issue. |
+| `issues_url` | string | true | URL of the issue. |
+| `project_url` | string | true | URL of the project. |
 
 ### Disable a custom issue tracker
 
@@ -610,9 +610,9 @@ Parameters:
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `new_issue_url` | string | true | The URL to create an issue in EWM. |
-| `project_url`   | string | true | The URL to the project in EWM. |
-| `issues_url`    | string | true | The URL to view an issue in EWM. Must contain `:id`. |
+| `new_issue_url` | string | true | URL of the new issue. |
+| `project_url`   | string | true | URL of the project. |
+| `issues_url`    | string | true | URL of the issue. |
 
 ### Disable EWM
 
@@ -1364,9 +1364,9 @@ Parameters:
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `new_issue_url` | string | true | New issue URL. |
-| `project_url` | string | true | Project URL. |
-| `issues_url` | string | true | Issue URL. |
+| `new_issue_url` | string | true | URL of the new issue. |
+| `project_url` | string | true | URL of the project. |
+| `issues_url` | string | true | URL of the issue. |
 
 ### Disable Redmine
 
@@ -1620,8 +1620,8 @@ Parameters:
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `issues_url` | string | true | Issue URL. |
-| `project_url` | string | true | Project URL. |
+| `issues_url` | string | true | URL of the issue. |
+| `project_url` | string | true | URL of the project. |
 
 ### Disable YouTrack
 
diff --git a/doc/api/users.md b/doc/api/users.md
index 31fe6234ad2..83947f63384 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -25,8 +25,6 @@ GET /users
 | Attribute          | Type    | Required | Description                                                                                                            |
 | ------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
 | `username`         | string  | no       | Get a single user with a specific username.                                                                            |
-| `extern_uid`       | string  | no       | Get a single user with a specific external authentication provider UID.                                                |
-| `provider`         | string  | no       | The external provider.                                                                                                 |
 | `search`           | string  | no       | Search for a username.                                                                                                |
 | `active`           | boolean | no       | Filters only active users. Default is `false`.                                                                         |
 | `external`         | boolean | no       | Filters only external users. Default is `false`.                                                                       |
@@ -146,6 +144,8 @@ You can use all [parameters available for everyone](#for-non-administrator-users
 
 | Attribute          | Type    | Required | Description                                                                                                           |
 | ------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `extern_uid`       | string  | no       | Get a single user with a specific external authentication provider UID.                                                |
+| `provider`         | string  | no       | The external provider.                                                                                                 |
 | `order_by`         | string  | no       | Return users ordered by `id`, `name`, `username`, `created_at`, or `updated_at` fields. Default is `id`               |
 | `sort`             | string  | no       | Return users sorted in `asc` or `desc` order. Default is `desc`                                                       |
 | `two_factor`       | string  | no       | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users |
diff --git a/doc/development/cicd/configuration.md b/doc/development/cicd/configuration.md
new file mode 100644
index 00000000000..903a3d63e8c
--- /dev/null
+++ b/doc/development/cicd/configuration.md
@@ -0,0 +1,100 @@
+---
+stage: Verify
+group: Pipeline Authoring
+info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
+---
+
+# Contribute to the CI/CD configuration
+
+## Glossary
+
+- **CI/CD configuration**: The YAML file that defines the CI/CD configuration for a project.
+- **keyword**: Each keyword in the CI/CD configuration.
+- **entry**: An `Entry` class that represents a keyword in the CI/CD configuration.
+
+Not every keyword in the CI/CD configuration is represented by an `Entry` class.
+We create `Entry` classes for keywords that have a complex structure or reusable parts.
+
+For example;
+
+- The `image` keyword is represented by the [`Entry::Image`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/config/entry/image.rb) class.
+- The `name` subkeyword of the `image` keyword is not represented by an `Entry` class.
+- The `pull_policy` subkeyword of the `image` keyword is represented by the [`Entry::PullPolicy`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/config/entry/pull_policy.rb) class.
+
+## Adding New Keywords
+
+CI config keywords are added in the [`lib/gitlab/ci/config/entry`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/config/entry) directory.
+For EE-specific changes, use the [`ee/lib/gitlab/ci/config/entry`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/lib/gitlab/ci/config/entry)
+or [`ee/lib/ee/gitlab/ci/config/entry`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/lib/ee/gitlab/ci/config/entry) directory.
+
+### Inheritance
+
+An entry is represented by a class that inherits from;
+
+- `Entry::Node`: for simple keywords.
+(e.g. [`Entry::Stage`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/config/entry/stage.rb))
+- `Entry::Simplifiable`: for keywords that have multiple structures.
+For example, [`Entry::Retry`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/config/entry/retry.rb) can be a simple number or a hash configuration.
+- `Entry::ComposableArray`: for keywords that have a list of single-type sub-elements.
+For example, [`Entry::Includes`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/config/entry/includes.rb) has a list of `Entry::Include` elements.
+- `Entry::ComposableHash`: for keywords that have single-type sub-elements with user-defined keys.
+For example, [`Entry::Variables`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/config/entry/variables.rb) has a list of `Entry::Variable` elements with user-defined keys.
+
+### Helper Classes
+
+The following helper classes are available for use in entries:
+
+- `Entry::Validatable`: Enables the `validations` block in an entry class and provides validations.
+- `Entry::Attributable`: Enables the `attributes` method in an entry class. It creates these methods for each attribute; `xxx`, `has_xxx?`, `has_xxx_value?`.
+- `Entry::Configurable`: Enables the `entry` method in an entry class. It creates these methods for each entry; `xxx_defined?`, `xxx_entry`, `xxx_value`.
+
+### The `value` Method
+
+The `value` method is the main method of an entry class. It returns the actual value of the entry.
+By default, from the `Entry::Node` class, the `value` method returns the hash configuration of the entry unless it has nested entries.
+It can be useful for simple entries. For example, `Entry::Paths` has an array of strings as its value. So, it can return the array of strings directly.
+
+In some keywords, we override the `value` method. In this method, we return what and how we want to return from the entry.
+The usage of `Entry::Attributable` and `Entry::Configurable` may have a significant role here. For example,
+in `Entry::Secret`, we have this;
+
+```ruby
+attributes %i[vault file token].freeze
+
+entry :vault, Entry::Vault::Secret
+entry :file, ::Gitlab::Config::Entry::Boolean
+
+def value
+  {
+    vault: vault_value,
+    file: file_value,
+    token: token
+  }.compact
+end
+```
+
+- `vault_value` is the value of the nested `vault` entry.
+- `file_value` is the value of the nested `file` entry.
+- `token` is the value of the basic `token` attribute.
+
+**It is important** that we should always use the `xxx_value` method to get the value of a nested entry.
+
+## Feature Flag Usage
+
+When adding new CI/CD configuration keywords, it is important to use feature flags to control the rollout of the change.
+This allows us to test the change in production without affecting all users. For more information, see the [feature flags documentation](../feature_flags/index.md).
+
+### Feature Flag Actor
+
+In entry classes, we have no access to the current project or user. However, it's discouraged to use feature flags without [an actor](../feature_flags/index.md#feature-actors).
+To solve this problem, we have three options;
+
+1. Use `Feature.enabled?(:feature_flag, Feature.current_request)`.
+1. Use `YamlProcessor::FeatureFlags.enabled?(:feature_flag)`
+1. Do not use feature flags in entry classes and use them in other parts of the code.
+
+## Testing and Validation
+
+When adding or modifying an entry, the corresponding spec file must be either added or updated.
+Besides, to have a fully integrated test, it's also important to add/modify tests in the `spec/lib/gitlab/ci/yaml_processor_spec.rb` file or
+the files in `spec/lib/gitlab/ci/yaml_processor/test_cases/*` directory.
diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md
index 18781f9315a..693ef6817ee 100644
--- a/doc/development/cicd/index.md
+++ b/doc/development/cicd/index.md
@@ -9,7 +9,9 @@ info: Any user with at least the Maintainer role can merge updates to this conte
 Development guides that are specific to CI/CD are listed here:
 
 - If you are creating new CI/CD templates, read [the development guide for GitLab CI/CD templates](templates.md).
-- If you are adding a new keyword or changing the CI schema, check the [CI schema guide](schema.md)
+- If you are adding a new keyword or changing the CI schema, refer to the following guides:
+  - [The CI configuration guide](configuration.md)
+  - [The CI schema guide](schema.md)
 
 See the [CI/CD YAML reference documentation guide](cicd_reference_documentation_guide.md)
 to learn how to update the [reference page](../../ci/yaml/index.md).
diff --git a/doc/user/project/repository/code_suggestions/self_managed.md b/doc/user/project/repository/code_suggestions/self_managed.md
index d0218c87ab0..f16b1b05abb 100644
--- a/doc/user/project/repository/code_suggestions/self_managed.md
+++ b/doc/user/project/repository/code_suggestions/self_managed.md
@@ -109,6 +109,8 @@ This setting is visible only in self-managed GitLab instances.
 WARNING:
 If you clear the **Turn on Code Suggestions for this instance** checkbox, the users in your instance can still use Code Suggestions for up to one hour, until the issued JSON web token (JWT) expires.
 
+::EndTabs
+
 ### Request access to Code Suggestions
 
 GitLab provisions access on a customer-by-customer basis for Code Suggestions
@@ -150,8 +152,6 @@ You must [manually synchronize your subscription](../../../../subscriptions/self
 
 Without the manual synchronization, it might take up to 24 hours to active Code Suggestions on your instance.
 
-::EndTabs
-
 ## Use Code Suggestions
 
 Prerequisites: